wizard-for-vaadin
Simple way to define multistep wizards with Vaadin
Wizard for Vaadin
Simple way to define multistep wizards with Vaadin
Usage
1. Define your context
Create a class, which will hold all the necessary entities for you through your steps. If you create multiple wizards, this class may be wizard specific. It can contain your most important entities or data which should be available on different steps or on the final screen.
2. Define your steps
You need to implement WizardStep
. Normally each step in your wizard should be
a separate class. Each step should get the same context instance in the
constructor.
The "hard" way
In WizardStep
there is a Div
, named layout
. You can use this layout
as a holder of the UI
of your step. As the status of the content depends on how users reaches the step (what the user)
selected in the previous step, or maybe the user is going backward, it's preferred toprotected void onAttach(AttachEvent attachEvent)
To make your wizard work, you need to implement the following method in your steps:
Div getLayout()
: to return the layout which should be displayedboolean isValid()
: if the user clicks on the next button, this method will validate your stepboolean commit()
: if the validation passed, you can commit your change: save to database, add to the context, etc.
If any of isValid()
or commit()
methods are failing, the wizard won't go to the next step.
The simple way
If you want to create a simple form based step, with a details message (like on the preview image),
you only need to extend AbstractFormWizardStep
(just like in TestFormStep
).
You only need to define your information message, your form layout and what to do after validation successes
and the context has been updated with the fields. The validation uses Vaadin's Binder, so you also need to bind your
fields to your context.
To make your form based wizard work, you need to implement the following method in your step:
boolean commitAfterContextUpdate()
: the method is part is called by thecommit()
method inWizardStep
after the validation happened. You can save your entity to the database here, or do anything with the context after the binder updated the fields in the context.Html getInformationMessage()
: the content of the information details. If you don't need information message, it can be disabled from configuration.FormLayout createForm()
: the place where you need to implement your form (and bind your fields with the binder for validation)
3. Instantiate your steps
After you've created all your step implementation, create a new instance from them and collect them into a list.
4. Define your wizard
If the default configurations are fine for you, you simply can create a new Wizard
instance. You
only need to define the context
(same you set for your steps) and your list of steps.
Add your Wizard
instance to your layout.
5. Set your custom start layout (optional)
There is a configurable built-in default start layout. But you also can define your own start view. The wizard will only start if the user clicks to the start button. This view is useful is you want to display some extra information before start.
After you designed your start view, you only need to set it for your Wizard
by calling setStartLayout()
on it
or if you base your view on AbstractWizardEndpoint
you can inherit configuration from the Wizard
by calling
createStartLayout
method. If you choose this option, you also can
implement Optional<Component> getExtraBottomContent()
method which makes it possible to add extra content to the bottom part, after the message.
If you simply want to configure the built-in start view, you can configure the following:
- icon and icon size, if you want to display an icon
- picture (name, path, width, height, padding) if you want to display a picture instead of the icon
- title (and title padding if necessary)
- color, which will be the background color of the top part and the border color of the bottom part
- contrast color, which will be used as text color where we applied background color
- border radius
- the width of the message box
- message, an HTML text which should be displayed at the bottom part
6. Set your custom finish layout (optional)
There is a configurable built-in default finish layout. But you also can define your own finish view.
You only need to extend the AbstractWizardEndpoint
class with the same context you used for your steps and wizard.
After you designed your finish view, you only need to set it for your Wizard
by calling setFinishLayout()
on it
or if you base your view on AbstractWizardEndpoint
you can inherit configuration from the Wizard
by calling
createFinishLayout
method. If you choose this option, you also can
implement Optional<Component> getExtraBottomContent()
method which makes it possible to add extra content to the bottom part, after the message.
If you simply want to configure the built-in start view, you can configure the following:
- icon and icon size, if you want to display an icon
- picture (name, path, width, height, padding) if you want to display a picture instead of the icon
- title (and title padding if necessary)
- color, which will be the background color of the top part and the border color of the bottom part
- contrast color, which will be used as text color where we applied background color
- border radius
- the width of the message box
- message, an HTML text which should be displayed at the bottom part
Configuration
Wizard for Vaadin contains some configuration, so you can change the look of your wizard, mostly the header and the footer.
Wizard configuration
Under WizardConfigurationProperties
you can configure the following:
- the header & footer configurations
- start view should be displayed or not
Header configuration
Under WizardHeaderConfigurationProperties
you can configure the following:
- background color of header
- order of columns (completed, active and inactive)
- the title of columns
- display titles or not
- display title when there is no related task
- color of task avatars
- too many tasks in a column should be grouped or not
- if yes, after how many items should we group them
For more details, please check the WizardHeaderConfigurationProperties
class.
Content configuration
Under WizardContentConfigurationProperties
you can configure the following:
- is the information details enabled or not
- the icon for the summary
- the color of the icon in the summary
- the text of the summary
- should the details be opened automatically or not
- the background, border color and border radius of the details
Besides the start and end views, content can be configured as described above.
Footer configuration
Under WizardFooterConfigurationProperties
you can configure the following:
- background color of footer
- is padding enabled or not
- backward step is enabled or not
- icon should be displayed on buttons or not
- how to handle unavailable button: disable them or hide them (e.g.: finish button when there is multiple incomplete steps)
- how should different buttons look (text, icon, vaadin theme variants and icon before text or after text)
For more details, please check the WizardFooterConfigurationProperties
class.
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
- Released
- 2024-02-14
- Maturity
- STABLE
- License
- Apache License 2.0
Compatibility
- Framework
- Vaadin 23
- Browser
- N/A