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:

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.

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

Create a survey list

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

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.

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.

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.

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

Define steps for the wizard

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

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.

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

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.

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

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

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.

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.

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

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.

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

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 2^nd 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 3^rd tab (step) and name the method Finish.

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.

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.

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");

};

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.

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

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

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

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.

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