Wizard Control

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).

Overview

The wizard control is made up of 4 key parts:

  1. A list of stages along the top.
    The developer will initialize the desired stages list using the WizardBuilder.
  2. A list of steps on the left side panel.
    The developer will initialize the desired steps list using the WizardBuilder.
  3. Navigation buttons along the bottom.
    Users can navigate through the steps using the back/next buttons.
    They can also exit the wizard at any time (which will present a confirmation dialog), or finish if they are at the last step.
  4. The rendered step component in the right/center panel.
    The wizard dynamically renders the relevant step component, based on selection/progress through the steps list.

Implementing the Wizard Control


Wizard Step Components

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:


Wizard Builder

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.


Model

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.


Markdown & Input Binding

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.


Custom Wizard Functionality


Validation

There are two key parts to validation inside the wizard:

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).


Event Emitters

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.

Skipping Steps Dynamically

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: