Creating a wizard-like experience for HTML client (Andy Kung)

Creating a wizard-like experience for HTML client (Andy Kung)

Rate This
  • Comments 6

If you have been playing with the new HTML client, you will know that LightSwitch provides a built-in screen template for creating data. It allows user to input data via a modal dialog. In some scenarios, however, we’d much prefer to guide the user via a step-by-step wizard-like dialog.

In this article, I will show you how to create such experience by customizing the built-in screen template. We will create a simple survey app that that allows users to enter data via a 3-step “wizard.” Something like this:

clip_image002

Let’s Begin!

Set up the database

Create a LightSwitch HTML Application (VB or C#). Name it MySurvey. On the start screen, click Create new table.

clip_image004

Name the table Survey and add 3 String fields: Name, Quest, and Color.

clip_image006

Create a survey list

In Solution Explorer, right click on HTMLClient node to add a screen.

clip_image008

We’d like to create a screen with a list of surveys. In Add New Screen dialog, select Browse Data Screen template, name the screen SurveyList, and pick Surveys as Screen Data. Click OK.

clip_image010

Create a “New Survey” dialog

We’d like to create an add button for the survey list. In Survey List screen, right click on Command Bar node to add a button.

clip_image012

In the Add Button dialog, pick Surveys.addAndEditNew and leave Navigate To as New Screen. This tells the system that this button will add a new item to the survey list via a new screen we’re about to create. Click OK.

clip_image014

LightSwitch will guide us to create an Add/Edit Details Screen. Name the new screen NewSurvey. Click OK.

clip_image016

Define steps for the wizard

In the New Survey screen, you will notice we have one tab group under the Tabs node.

clip_image018

We want to simulate a 3-step wizard by using 3 tabs, showing one tab (step) at a time.

Add 2 new tab groups by right clicking on Tabs node.

clip_image020

Select the first tab group. In Properties, change Name to Step1.

clip_image022

Name the same property to Step2 and Step3 for the other 2 tab groups.

Since we only want to show one question for each step, move Name directly under the first tab group.

clip_image024

Move Quest and Color to Step2 and Step3 tab groups respectively.

clip_image026

Since we have no use of the columns node under the first tab group, delete it.

clip_image028

Hit F5 key to run the application. Click the Add Survey button. You will see we have an add dialog to add a new survey. There are 3 tab groups, each containing a survey question.

clip_image030

Customize the dialog into a “wizard”

To make this more like a step-by-step wizard, we need to do a couple of tweaks. First, we only want to show the Save button in the last step. Second, we want to hide the tab titles to prevent the user from jumping directly to a step.

Close the browser and go back to Visual Studio. Let’s make these changes.

In New Survey screen, select the screen root node. Go to Properties window and check Hide Tab Titles. This will hide the title of each tab group. Also select Browse for Screen Type. This will display a Close button instead of a Save button in the modal dialog.

clip_image032

If you run the application now, you will only see the first tab showing.

clip_image034

All we need to do now is to place a Next button to go to the next step.

Create navigation buttons

Right click on Command Bar node under the first tab to add a button.

clip_image036

In Add Button dialog, select Write my own method and name it ShowStep2. Click OK.

clip_image038

Double click on the new button will take you to the code editor. We will use the showTab API to display the next tab group (step). We will also update the dialog title programmatically as we move from step to step.

myapp.NewSurvey.ShowStep2_execute = function (screen) {

    // Write code here.

    screen.showTab("Step2");

    screen.details.displayName = "Step 2";

};

Go back to the New Survey screen. Follow the same steps to create a ShowStep3 button for the 2nd tab (step).

myapp.NewSurvey.ShowStep3_execute = function (screen) {

    // Write code here.

    screen.showTab("Step3");

    screen.details.displayName = "Step 3";

};

On the last tab (step), we want a Save button. Add a button to the 3rd tab (step) and name the method Finish.

clip_image040

Write the following code. The commitChanges API will save the screen and close the dialog.

myapp.NewSurvey.Finish_execute = function (screen) {

    // Write code here.

    myapp.commitChanges();

};

Run the application and add a survey by following the “wizard. “

Handle validation errors

One problem you might notice is that we don’t prevent you from going into the next step even if there are validation errors. We want to surface these error messages before letting the user continue.

Update the 3 code methods as the following:

myapp.NewSurvey.ShowStep2_execute = function (screen) {

    // If no value is entered, manually set the field to null to trigger 'required' validation

    if (screen.Survey.Name == null) {

        screen.Survey.Name = null;

    }

    // Go to next step only if there are no validation errors associated with the field.

    var contentItem = screen.findContentItem("Name");

    if (contentItem.validationResults.length === 0) {

        screen.showTab("Step2");

        screen.details.displayName = "Step 2";

    }  

};

 

myapp.NewSurvey.ShowStep3_execute = function (screen) {

    // If no value is entered, manually set the field to null to trigger 'required' validation

    if (screen.Survey.Quest == null) {

        screen.Survey.Quest = null;

    }

    // Go to next step only if there are no validation errors associated with the field.

    var contentItem = screen.findContentItem("Quest");

    if (contentItem.validationResults.length === 0) {

        screen.showTab("Step3");

        screen.details.displayName = "Step 3";

    }

};

 

myapp.NewSurvey.Finish_execute = function (screen) {

    // If no value is entered, manually set the field to null to trigger 'required' validation

    if (screen.Survey.Color == null) {

        screen.Survey.Color = null;

    }

    // Save changes only if there are no validation errors associated with the field.

    var contentItem = screen.findContentItem("Color");

    if (contentItem.validationResults.length === 0) {

        myapp.commitChanges();

    }

};

There are 2 new things we’re doing here:

  1. In HTML client, we don’t show the required field error message until the value is change by the user. Because of this reason, we are programmatically setting the value back to null. This will trigger the error message to show if the user just click Next button without entering anything.
  2. We only allow you to move to the next step if there are no errors at the current step.

Run the application and click Next without any value. We now prevent you from going into the next step prematurely.

clip_image042

Polish the experience

There are a couple of enhancements we can do:

  • Change the Display Name of the questions to make it more descriptive (ex. What… is your name?). You can do so via Properties.
  • Change the Display Name and Icon of the buttons via Properties.

clip_image044

Bonus: Add some Back buttons

You can add some Back buttons to the flow by utilizing the same showTab API. For example, in Step 2, you can include a Back button with the following method:

myapp.NewSurvey.BackStep1_execute = function (screen) {

    // Go back to step 1

    screen.showTab("Step1");

};

clip_image046

Bonus: Add an optional step

Sometimes the next set of questions is based on a question user answers at the current step. In case you did not get the joke in my example, the 3 questions are taken from the movie Monty Python and the Holy Grail. Let’s add an additional step to ask if people get the joke.

Add a Boolean field GetTheJoke in the Survey table. Uncheck the Required box to make it an optional field.

clip_image048

In New Survey screen, add another tab group (step) and name it OptionalStep.

clip_image050

Drag GetTheJoke field from the data members list under the tab group. Change the Display Name of the field.

clip_image052

Add a Next button in the group by creating a new method. It simply goes to Step 2.

clip_image054

myapp.NewSurvey.OptionalStep_execute = function (screen) {

    // Write code here.

    screen.showTab("Step2");

    screen.details.displayName = "Step 2";

};

In the original ShowStep2 method, let’s add an IF statement before showing Step 2. If the user’s name does not contain “Sir”, let’s ask if they get the joke.

myapp.NewSurvey.ShowStep2_execute = function (screen) {

    // If no value is entered, manually set the field to null to trigger 'required' validation

    if (screen.Survey.Name == null) {

        screen.Survey.Name = null;

    }

    // Go to next step only if there are no validation errors associated with the field.

    var contentItem = screen.findContentItem("Name");

    if (contentItem.validationResults.length === 0) {

        if (screen.Survey.Name.indexOf("Sir") < 0) {

            screen.showTab("OptionalStep");

        } else {

            screen.showTab("Step2");

            screen.details.displayName = "Step 2";

        }

    }

};

Run the application and try out the optional step.

clip_image056

Conclusion

We have successfully created a step-by-step wizard-like experience by customizing the built-in screen template! We learned how to:

  • Create multiple steps by adding multiple screen tabs
  • Make the dialog looks like a wizard by hiding screen titles and the save button
  • Navigate to the next step and update title
  • Save and close the wizard programmatically
  • Handle validation errors at each step

As King Arthur would say, “You have to know these things when you’re a king, you know.”

-andy

Leave a Comment
  • Please add 1 and 2 and type the answer here:
  • Post
  • Perfect example and well done. I will look into using Wizards more. Should be a better user experience than putting everything on the screen and throwing a bunch of validation errors at them.

  • Thank you for the great tutorial.

  • I used this with a Microsoft Agent JavaScript library. The tutorial and code are posted here: lightswitchhelpwebsite.com/.../Using-The-Clippy-Agent-in-the-Visual-Studio-LightSwitch-HTML-Client.aspx

  • This is very cool and inspiring. Have you tried a parent-child wizard that collects, say, family info and then allows an addition of family members? I am interested in creating such an experience for a family profile data collection online form.

  • One thing puzzles me when I read this is that no one raised the issue that these steps are hard coded. If you have more survey questions, you need add more steps. This might be a realistic example in real world

  • Is there any reference on msdn for html screen object api ; I have to search through  tuturiasl every time I need it

Page 1 of 1 (6 items)