Creating wizards on websites

Kentico allows you to create wizards — pages that guide users through a sequence of steps. A common example of a wizard is the checkout process of an on-line store. You can build wizards using the portal engine and a set of predefined web parts.

The wizard uses standard documents (pages) to define the steps. You have full control over the step content, and can leverage the features of Kentico documents for every step:

• Multilingual step content
• Unique step URLs
• Tracking of web analytics for individual steps
• On-line marketing features (such as optimization testingor content personalization)

Defining document wizards

To set up a document wizard on your website:

1. Open the Pages application and select your site.
2. Create a new page.
3. Switch to the Design tab.
4. Add the Document wizard manager web part.
5. Add the Page placeholder web part.

The page serves as the “parent” of the document wizard and provides a master page for the content of steps. The Document wizard manager ensures the overall logic of the wizard. The Page placeholder represents the area where the wizard displays the content of individual steps.

Adding steps

To create the wizard steps, add child pages (or other types of documents) under the page containing the Document wizard manager web part. Build the content of steps just like any other portal engine pages.

You also need to configure page nesting for all child documents that you wish to use as steps:

1. In the Pages application, select the document.
2. Open the Properties -> Template tab.
3. Enable nesting within the parent page (and any other required levels of the website).
4. Click Save.

You can choose which child documents to use as steps by configuring the document filtering properties of the Document wizard manager web part. The wizard only loads steps from the first level of direct child documents.

By default, the step order matches the order of the child documents in the content tree. You can use the OrderBy property of the Document wizard manager web part to load the steps in a different order determined by an SQL clause.

Building step navigation

Navigation allows users to move between the steps of the document wizard. Add navigation elements using the following web parts:

You can position the wizard navigation in two different ways:

• Shared navigation for the entire wizard - place the web parts onto the wizard’s parent page, around the page placeholder representing the step content
• Separate navigation for individual steps - add the web parts directly into the content of step documents

Restricting the step order

If you enable the Restrict step order property of the Document wizard manager web part, the wizard forces users to progress through the steps in the defined order. The system tracks which steps individual users have passed through, and stores the information in the HTTP session.

Restricting the step order causes the following behavior:

• Users can only move forward through the wizard’s steps using the Next button
• The Document wizard navigation web part renders unvisited steps as inactive items without links
• If a user attempts to access an unvisited step through the URL of the step document, the wizard opens the last visited step instead

If the Final step URL property is filled for the Document wizard manager web part, the wizard automatically clears the history of visited steps for users who click the Next button on the last step.

Setting up automatic step transitions

You can create wizards that automatically move users between steps under certain conditions:

1. In the Pages application, select the document representing the step where you want the transition to occur.

2. Open the Design tab and add the Document wizard step action web part (anywhere on the page).

3. Choose the type of step transition in the Action type property:

   • Skip - continues to the next step according to the direction the user is moving in the wizard
   • Next - always moves one step forward
   • Previous - always moves one step back

4. Enter the macro condition that triggers the step transition into the Action condition property. The condition must return a true or false value.

5. Click OK.

When a user arrives on the step containing the web part, the system evaluates the action condition. If true, the web part immediately performs the selected step transition.

For example, if you have a step that requires users to log in or register, you can make the wizard skip the step for already authenticated users:

CurrentUser.IsAuthenticated

Validating step data

Validation rules are a set of conditions that must be fulfilled to successfully complete wizard steps. Validation typically occurs on steps that require users to input data.

The wizard performs step validation:

• when users move to the next step by clicking the Document wizard button
• during automatic skip transitions done by the Document wizard step action web part (if the Validate step property is enabled)

The step validation requirements depend on the implementation of the web parts placed on the step. If the validation fails, the wizard cancels the step transition and the related web parts display a validation error message.

Document wizard macros

You can use macro expressions within the context of the document wizard to load the data of steps.

Getting steps:

• DocumentWizard.FirstStep
• DocumentWizard.CurrentStep
• DocumentWizard.PreviousStep
• DocumentWizard.NextStep
• DocumentWizard.LastStep
• DocumentWizard.Steps - accesses the collection of all steps in the wizard
• DocumentWizard.Steps.Count - returns the total number of steps in the wizard
• DocumentWizard.Steps[5] - gets the 6th step

Getting step data:

• Step.StepIndex - gets the step’s index in the document wizard step collection. The index of the first step is 0.
• Step.StepUrl - returns the relative URL of the step’s document, including the virtual directory and extension. For example: /Checkout/Shipping.aspx
• Step.StepData[“NodeName”] - gets the name of the step’s document. You can use the StepData property to get the values of any other document columns.

For example, you can add the following macro into the Text property of the Document wizard button web part that displays the next step button:

{%
DocumentWizard.CurrentStep == DocumentWizard.LastStep ? "Finish" : DocumentWizard.NextStep.StepData["NodeName"]
%}

The macro uses a ternary operator to dynamically set the caption of the Next button:

• The button text isFinish on the last step in the wizard (if the document wizard has a final step URL specified)
• The button displays the name of the next step document on all other steps