As your users move through your Blazor Wizard, you’ll need to catch any errors and prevent users from moving ahead until they’ve fixed them.
In a previous post, I showed how easy it is to add a wizard to your Blazor application to guide your user through a difficult task using the Progress Telerik UI for Blazor Wizard component. In that post, I concentrated on dressing the wizard’s user interface. In this post, I’m going to focus on implementing wizard-related business logic.
Regardless of what UI you create for each step, you’ll want to do two things:
The key to controlling the user’s progress through the steps is each step’s OnChange
event, which is raised when the user clicks on a Next or Previous button. To control the user’s progress in the OnChange
event,
you just need to check for any bad data on the page and, if you find problem data then cancel the OnChange
event (and, if you want the user to automatically go to the next or previous step, do nothing).
To simplify this process, you can leverage the Telerik Form for Blazor component’s features to validate your data and display error messages. If you
use the TelerikForm, “checking for problems” is just a matter of testing the TelerikForm component’s IsValid
property.
To implement that design, you first need to tie a method to the WizardStep’s OnChange
property. Then, inside the step’s Content
element, add your TelerikForm and populate it with whatever you need for the step’s
UI. You’ll also need to set the TelerikForm’s @ref
attribute to point to a field or property in your code area.
Putting it all together, the Razor markup for a typical WizardStep
would look like this:
<WizardStep OnChange="@OverviewStep" … >
<Content>
<TelerikForm @ref="OverviewForm" … >
…form content…
</TelerikForm>
</Content>
</WizardStep>
In your code area, you need to declare a field or property of type TelerikForm to tie to your form’s @ref
attribute (in the following code I’ve used a field). You’ll also need to define a method for each step’s OnChange
event. These methods must accept a parameter of type WizardStepChangeEventArgs
.
The typical skeleton for a WizardStep
’s OnChange
method will look like this:
private TelerikForm OverviewForm;
private void OverviewStep(WizardStepChangeEventArgs wsc)
{
}
Inside the method, you just need to check the form field’s IsValid
property to see if the form found bad data. If IsValid
is false, you can stop the user from moving off the step by setting to true the IsCancelled
property on the parameter passed to your method. After that, you should probably exit the method to avoid doing anything else with the bad data on the page in your method (remember: if you do nothing, the user will automatically advance to the next
step).
As a result, a typical step’s OnChange
method will look like this:
private void OverviewStep(WizardStepChangeEventArgs wsc)
{
if (!OverviewForm.IsValid())
{
wsc.IsCancelled = true;
return;
}
…any processing required before moving to the next step…
}
Side Note: For more on the Telerik UI for Blazor Form component, see the documentation. However, you’ll probably want to suppress
the default Submit button on the form so that any step-related processing happens in your wizard’s OnChange
event. To do that, just add an empty <FormButtons>
element to the end of the form:
<FormButtons></FormButtons>
</TelerikForm>
As part of handling errors in the last step, you can mark any step with errors as invalid in the list of steps at the top of your wizard. This feature can be especially useful when validating data on the last step of the wizard—if you find a problem, you can mark the step where the problem can be fixed so that the user knows where to go to solve the problem.
The first step in flagging a step with a problem is, in your Razor file, to tie the step’s Valid
attribute to a field or property. This example ties the attribute to a field called SelectOccurrencesValid
:
<WizardStep Valid="@SelectOccurrencesValid"
OnChange="@OverviewStep" …>
Then, in your code file, you need to declare that field or property and initialize it to true (might as well assume that the step is valid, after all). Finally, when you find that a step has a problem, you need to set the field to false (and set it to true when the field is valid). That’s what this code does:
private bool SelectOccurrencesValid = true;
private void SelectOccurrencesStep(WizardStepChangeEventArgs wsc)
{
if (!SelectOccurrences.IsValid())
{
wsc.IsCancelled = true;
SelectOccurrencesValid = false;
return;
}
OverviewValid = true;
}
The display of the steps across the top of the Telerik wizard for Blazor is automatically updated to show invalid steps by putting an “x” icon in any invalid steps and highlighting their labels in red (this graphic shows two invalid steps: the current step has a blue “x” icon and its label is in the standard font; the other, invalid step has a white “x” icon and its label is in boldface):
To implement the wizard’s business logic, just tie an event to the wizard’s OnFinished
event which is run when the user clicks the Done button. This example ties the wizard’s OnFinished
event to a method called
DoneButton:
<TelerikWizard OnFinish="@DoneButton"…
The corresponding method doesn’t accept any parameters and would look like this:
private void DoneButton()
{
…take action….
}
If you are validating data in the last step then, when you find errors, in addition to flagging the problem step as invalid, you can move the user to the offending step. The first step in that process is to use the TelerikWizard’s @bind-value
attribute with an integer field or property—this field or property can be used to make any step the “current step.” This example uses a field called currentStep
:
<TelerikWizard @bind-value="currentStep">
In your code, you need (of course) to declare that field:
int currentStep = 0;
After that, it’s just a matter of setting the field or property to the step you want to move the user to when a problem is found. This code would move the user to the third step in the wizard (while we count wizard steps from “Step 1,” the TelerikWizard counts from “Step 0”):
if (DateList.Count() == 0)
{
DateStepValid = false;
currentStep = 2;
return;
}
And, with these changes, you’ve gone from the basic wizard in your Blazor application to a more sophisticated implementation that will let manage your user’s progress, flag errors (especially simple if you leverage the TelerikForm component) and return the user to the problem step.
The Telerik Wizard UI component for Blazor will still take care of the process of navigating through your steps. You can take more control of that navigation process also, if you need to, as I’ll cover in my next post.
Peter Vogel is a system architect and principal in PH&V Information Services. PH&V provides full-stack consulting from UX design through object modeling to database design. Peter also writes courses and teaches for Learning Tree International.