VStepper
Vaadin addon for displaying a series of components one at a time.
VStepper
This addon displays a series components as steps one at a time. Each step consists of the content component itself as well a header component. The header component is always shown and usually used to display which steps are already completed, active or inactive at any given moment. You can navigation between these steps by hitting the back or next button at the bottom of the component.
Basic Usage
You can add steps to your stepper in a variety of different ways the easiest of which is to add only the content components directly. In this case the step is created by the stepper using a default header:
VStepper simpleUse = new VStepper();
simpleUse.addStep(new Label("Step 1"));
simpleUse.addStep(new Label("Step 2"));
simpleUse.addStep(new Label("Step 3"));
You can also provide a caption for the default header when adding a component:
VStepper customHeaderCaptions = new VStepper();
customHeaderCaptions.addStep("Step 1", new Label("Step 1"));
customHeaderCaptions.addStep("Step 2", new Label("Step 2"));
customHeaderCaptions.addStep("Step 3", new Label("Step 3"));
The third option is to add a step by providing you own header component in addition to the content. The VStepper creates the steps using the provider header and content components:
VStepper headerComponents = new VStepper();
headerComponents.addStep(new Label("Step 1"), new Label("Step 1"));
headerComponents.addStep(new TexField(), new Label("Step 2"));
headerComponents.addStep(new Span("Step 3"), new Label("Step 3"));
Advanced Usage
Step Events
There are four step events invoked by the VStepper. They are called enter, abort, complete and validationChanged. Content and header components can react to the enter, abort and complete events by implementing the EnterStepListener, AbortStepListener and CompleteStepListener interfaces respectively. You can also add listeners for all events directly via the Step API.
Content components which require validation in order to move on to the next step should implement the ValidationContent interface. The VStepper will register itself as a listener to these contents and only allow moving on when the step content is validated.
The last option to add a step is to create the step yourself by overwriting the Step class and adding that step to the VStepper:
private VStepper createStepper() {
VStepper customSteps = new VStepper();
customSteps.addStep(createStep(new Label("Step 1"), new Label("Step 1")));
customSteps.addStep(createStep(new Label("Step 2"), new Label("Step 2")));
customSteps.addStep(createStep(new Label("Step 3"), new Label("Step 3")));
return customSteps;
}
private Step createStep(Component header, Component content) {
return new Step(header, content) {
@Override
protected void onEnter() {
}
@Override
protected void onAbort() {
}
@Override
protected void onComplete() {
}
@Override
public boolean isValid() {
return true;
}
};
}
More examples can be found in the source code and the online demo.
Helper classes
There are three helper classes to make the usage of this component easier.
StepHeader
StepHeader is a helper class for creating your own step header. It attaches the CSS classes "active" or "completed" to the step header depending on the current state of the step. This allows you to visually highlight different step states in the step header.
StepContent
StepContent is an abstract helper class for implementing step contents. It implements all step event listeners and provides an implementation for adding and updating validation listeners.
BinderContent
BinderContent provides some basic data binding functionality. It initialises the step based on the underlying bean on enter. Resets the step back to the bean content on abort and writes the step content values to the bean on complete. In addition it updates all validation listeners on every binder value change.
Styling
Since your own content and header implementations are placed within the shadow dom of the VStepper you need to import your CSS classes like this:
@CssImport(value = "./styles/vstepper-styles.css", themeFor = "v-stepper")
Known issues
- Highlighting of the active step header for the default header component does not work correctly in safari browser. You should either provide your own header component or adjusting the CSS of the default header.
Roadmap
- Navigating to steps by clicking the header
- Theme variant for a vertical stepper
Links
Compatibility
Was this helpful? Need more help?
Leave a comment or a question below. You can also join
the chat on Discord or
ask questions on StackOverflow.
Version
Added different validation modes: On change and on next
- Released
- 2020-05-25
- Maturity
- STABLE
- License
- Apache License 2.0
Compatibility
- Framework
- Vaadin 14+
- Browser
- Firefox
- Safari
- Google Chrome
- Microsoft Edge
VStepper - Vaadin Add-on Directory
Vaadin addon for displaying a series of components one at a time.View on GitHub
VStepper version 1.0.6
* Minor bugfixes
* Added ThemeableMixin support
* Added BinderContent class for data binding support
VStepper version 1.0.7
* Setters for button texts
* Improved binderContent
VStepper version 1.0.8
* Maven dependency clean up
* Exposed stepper buttons in API
VStepper version 1.0.9
Added different validation modes: On change and on next