Telerik blogs
BlazorT4_1200x303

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 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:

  • Stop the user from going to another step if you find errors in the user’s entries
  • Perform the wizard’s updates when the user gets to the Done button on the final step

Handling Errors

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>

Marking Problem Steps

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

A screen shot of five circles joined by a line. The second and third icons have X icons inside the circles and the captions under the circle are displayed in red. The second step has a double circle, a blue background, and its text is not only in red but also in boldface.

Clicking the Done Button

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
About the Author

Peter Vogel

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.

Related Posts

Comments

Comments are disabled in preview mode.