The wizard control is a component for guiding a user through a series of steps in order to complete a long, multi-step process. A common use for the wizard is gathering and storing user input, and presenting information. The developer implementing this control can customize the contents of the steps, apply validation logic where necessary, and react to certain inputs by skipping over a step(s).
The wizard control is made up of 4 key parts:
WizardBuilder
.
WizardBuilder
.
The developer has control over what to render as the contents of each step. The most common use case is for the
developer to create a distinct component (and template) for each step.
There are a number of example components in the dev-guide/src/app/modules/controls/wizard/components
. An
example of such a component is simple-text-input
which also demonstrates the use of a data model, and
input validation.
Note: When creating these components to be dynamically rendered steps, note that:
WizardStepComponent<T>
class, where T
is the
developer-created
Model (described below).
entryComponents
array in the module definition that imports the
wizard.
The WizardBuilder class allows you the instantiate your wizard by exposing methods for you to:
i) Create stages and steps – using the addStepInStage
method, which takes 3 arguments:
a) The name of the step – which will appear in the steps list.
b) The componentType of the step – these are the custom components created by the developer which handle step
contents.
c) The name of the stage within which the step should be appear.
Note: When considering the order by the steps will appear in the steps list for a given stage, the order
of the addStepsInStage
calls is the determining factor.
ii) Initialize various optional parameters if required. Setters have been provided for these
attributes.
Table of Parameters:
Name | Description | Type | Required |
---|---|---|---|
heading |
The title to be displayed above the stages list. | string | No |
showExitConfirmationDialog |
The boolean which determines whether a confirmation dialog will be shown when 'Exit' is clicked. The default is true. |
boolean | No |
canNavigateToPreviousStep |
The boolean which determines whether the back button will be removed and navigation to a previous step is not possible. |
boolean | No |
finishView |
The view which will be displayed when ‘Finish’ button is clicked on the last step of the last stage. |
Type<Any> | No |
hideStepsListSidePane |
The boolean which determines whether or not the steps list will be shown. The default is true. (‘False’ may be useful if there is one step per stage, for all stages). |
boolean | No |
exitButtonTitle |
The string which implements custom text to the 'Exit' button. For example 'Cancel'. |
string | No |
finishButtonTitle |
The string which implements custom text to the 'Finish' button. For example 'Confirm'. |
string | No |
Note: The wizardBuilder is a required input binding when implementing the wizard via the
<sme-wizard>
markdown tag.
The model is the second required input binding when using the wizard via the <sme-wizard>
tag.
This model should be defined by the developer, and it determines what data can be stored throughout the wizard
experience.
This interface must extend the WizardModel
class. (In the example, refer to the data.ts
file as an
example).
Note: This model will be accessible throughout your custom defined WizardStepComponents. The developer has
sole responsibility for updating the Model throughout the wizard experience.
As mentioned above, to use the wizard in a template, it should be implemented as:
<sme-wizard [wizardBuilder]="yourBuilder" [model]="yourModel"><sme-wizard>
The two required input bindings should be instantiated and supplied as described.
There are two key parts to validation inside the wizard:
runValidation
is exposed via the WizardStepComponent
class (which all
steps should
inherit).Observable<WizardStepValidation>
.
WizardStepComponent
inherited class, all step components get access to a
public attribute valid
. The navigation buttons use this as the primary disabled state indicator.
Update this class member whenever the validation state changes.
Note: Validation on inputs is triggered when the user clicks the Next button (and when they click the Finish button, if validation is implemented on the final step).
To allow for further flexibility, a number of EventEmitters have been provided, so that the developer can react to certain triggers, if necessary.
Event Name | Trigger | When is it useful? |
---|---|---|
stepInvalidated |
The event fired when a step validation fails. (Validation must be implemented on the step). |
In this scenario: the user inputs something, clicks Next, validation is triggered, there input is invalid, the developer may want to do something at this point. |
stepSubmitted |
The event fired when the step is submitted. | If the developer needs to be informed of progress through the wizard. |
exit |
The event fired when the wizard is exited (before reaching the final step). |
If the developer wants to handle Exit logic themselves. This trigger notifies the developer about the Exit event |
finished |
The event fired when the final step is submitted. | If the developer doesn’t supply a ‘finishView’ via the WizardBuilder, clicking ‘Finish’ will not do anything from a user’s perspective. This is where the developer can provide logic. |
As described, the Back
and Next
buttons are the primary controllers of navigation
throughout the wizard
(although users can also click on completed steps and stages to view them again).
To provider greater flexibility, there is a way to dynamically ‘skip’ steps in response the user inputs as they
move through the wizard. Via the WizardStepComponent
inherited class, all step components get access
to a public
attribute skipped
. The developer can utilize this attribute to mark the step is ‘skippable’ dependent
on some
criteria – the most common scenario being in response to input on a previous step (whose data must be stored in
the Model, so it is accessible to this ‘skippable’ component).
Note:
skipped
attribute is
set to true
as a user progresses through the wizard, the whole stage will be skipped over.
Back
and edits the step which has determined another step will be skipped, the
updates will propagate, and the step will no longer be skipped.