Wizard control - mkArtak/LittleBlazors GitHub Wiki

The Wizard control enables users to define ordered component sequences, which will be shown only one at a time. These are usually useful when collecting complex data from the user, which is not easy to do in a single page. The wizard supports two modes - simple navigation through the pages (back and forth) as well as a final completion stage, where user can define an action after the user goes through all the pages.

The Wizard control also supports state transition between pages, making data entered in one page available to the rest of the pages.

To simplest way to create a wizard, is to use the WizardPage control for each page as follows:

<Wizard>
  <WizardPage>
    This is the first page of the wizard
  </WizardPage>
  <WizardPage>
    This is the second page of the wizard
  </WizardPage>
</Wizard>

The WizardPage control can be used for simple pages, where the component which hosts the wizard will be responsible for all the actions happening on each page. This is fine in situations, when there are very little content on each page. In some situations, however, there is a need to have more complex pages, where it's desirable to turn the page into a separate control. To use a separate component as a page, it should inherit the WizardPage component and follow the below rendering pattern:

@using LittleBlazors.Components.Wizards
@inherits WizardPage

@if (this.IsPageActive)
{
  // all page content should go here
}

@code {
  
}

Assuming the above component is named CustomPage, it can be used in a wizard as follows:

<Wizard>
  <WizardPage>
    <div>This form is going to introduce you to the custom page.</div>
  </WizardPage>
  <CustomPage />
</Wizard>

Transitions from one Wizard Page to another are referred to as navigation. Custom WizardPages can handle navigation events by overriding OnNavigatedTo and/or OnNavigatingAway methods.

In some situations, developers may need to initiate navigation from within a wizard page. For these situations, they can use the NavigateBack and NavigateForward methods on the Wizard property each pages has access to. This will result in the same experience as clicking the Back and Next buttons respectively.

Each WizardPage has access to a StateManager property, which is used to pass and retrieve state to/from other pages. The StateManager is of IWizardStateManager type which defines two simple methods:

While access to the StateManager is available, there is even more simpler way to store and retrieve state. If the data to be stored is in a property of the custom page, then the simply applying [State] attribute to the property will make sure the state is stored when navigating away from the page. In the following example the CustomPage defines a Text property so the Wizard can use it on the next page:

@using LittleBlazors.Components.Wizard
@inherits WizardPage

@if (this.PageIsActive)
{
  // all page content should go here
  <input @bind="Text" />
}

@code {
  [State]
  private string Text { get; set; }
}

This will result in the text entered in the CustomPage to be stored in the state container with the Text key, so that other pages can retrieve it with the same key. If, however, you would like to store the value with a custom key, the Staate attribute accepts an optional key parameter, which can be used as follows: [State("customKey")].

By default, the Wizard control supports simple navigation between pages. If the user wants to run some action after the user goes through all the pages they can do so by setting the SupportCompletion flag. By doing so two things happen:

• the Wizard shows a Finish button when the user gets to the last page of it
• the Wizard fires OnComplete even when the Finish button is clicked

The below example demonstrates how to register an OnComplete handler:

<Wizard SupportCompletion="true" OnComplete="OnWizardCompleted">
  // pages go here
</Wizard>

@code {
  private Task OnWizardCompleted(IWizardStateManager stateManager)
  {
    // code to handle final action
  }
}

The OnComplete event handler gives the developer access to the stateManager of the wizard, where pages have stored any information, so that the developer can act according to the user input.

While out-of the box the wizard has no defined styles, it is fully customizable. The internal layout of the Wizard control is as follows:

<div class="@WizardPageContainerClassName">
  // pages render here
</div>
<div class="@FooterContainerClassName">
  <button style="BackButtonStyle">Back</button>
  <button style="NextButtonStyle">Next</button>
  <button style="FinishButtonStyle">Finish</button>
</div>

As shown above, each button has a style property fully controlling its appearance and visibility. The following table details the settings controllable through a ButtonStyle type.