# 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](https://github.com/mLottmann/VStepper/blob/master/src/test/java/com/mlottmann/View.java) and the [online demo](https://matthias.app.fi/vstepper-demo-1.0/main/). ## 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