Using the Forms Wizard

Visual appearance

Unless you indicate otherwise, each field in the form associated with this widget is displayed individually with a caption. The caption is a user-friendly instruction telling users what to do in that step. In addition to the form fields to be completed, each step includes some link controls that are automatically generated by the wizard.

Cancel
Previous, except in the first step
Next, except in the last step
Complete on the last step, instead of Next

You can specify text or images for the links, or omit the information to use the language-neutral default values. On completion of each field, and each step, fields may be validated. Where this validation fails, you can display an error message.

User interactions

On each step of the wizard, the user can enter content into each of the form fields included in that step. When the user has completed all of the mandatory fields they may select the 'Next' link.

Selecting Next triggers validation for that step. The validation is provided by the Simple and Multiple Forms Validator widgets, as appropriate. If validation succeeds, the next step is displayed.

At any point, the user may go back to earlier steps of the wizard, in which case validation is not performed on the current step. Data entered in the current step is retained until the user returns.

Once the last step is complete, the user can complete the wizard by clicking Complete. This triggers validation on both the current (last) step, followed by an extra validation on the complete form. The validation of the fields in the final step is performed first, and if any validation errors occur they are dealt with in exactly the same way as those for any earlier step.

You can optionally include a Cancel action in each step. If the user has not entered any data, then the cancel operation occurs immediately, returning the user to the page containing the wizard. If the user has entered some data already, a confirmation dialog is displayed.

No special markup is required to connect validator widgets to the wizard. Markup for the validator widgets should be used. When the "next" action is clicked, each validator widget enclosed by a xforms:group element associated with the current step is processed. If at least one validate() returns false, it's assumed that validation failed and the next step is not shown.

XDIME 2 elements

You define the wizard with the widget:wizard element The optional cancel-dialog attribute provides a reference to a Popup widget that shows the cancel confirmation message. The widget:button element with the action attribute set to 'launch', represents the action link that launches the wizard

To complete the wizard the xforms:submit element must be specified, so that the users can submit the content.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:xforms="http://www.w3.org/2002/xforms"
  xmlns:si="http://www.volantis.com/xmlns/2006/01/xdime2/si"
  xmlns:widget="http://www.volantis.com/xmlns/2006/05/widget">
  <head>
    <title>widget:wizard</title>
    <xforms:model>
      <xforms:instance>
        <si:instance>
          <si:item name="login"/>
          <si:item name="password"/>
          <si:item name="repeat"/>
        </si:instance>
      </xforms:instance>
      <xforms:submission id="submit" action="."/>
    </xforms:model>
  </head>
  <body>
    <div>
      <widget:wizard class="widget" id="myWizard" cancel-dialog="myPopup">
        <xforms:group>
          <div>Please enter your login:</div>
          <p>
            <xforms:input ref="login">
              <xforms:label>Login</xforms:label>
            </xforms:input>
          </p>
        </xforms:group>
        <xforms:group>
          <div>Please enter your password:</div>
          <p>
            <xforms:input ref="password">
              <xforms:label>Password</xforms:label>
            </xforms:input>
            <xforms:input ref="repeat">
              <xforms:label>Repeat</xforms:label>
            </xforms:input>
          </p>
          <xforms:submit submission="myForm" id="submit-button">
            <xforms:label>Finish</xforms:label>
          </xforms:submit>
        </xforms:group>
      </widget:wizard>
    </div>
    <div>
      <widget:button id="start-button" action="myWizard#launch"> Start the wizard </widget:button>
    </div>
    <div>
      <widget:popup id="myPopup">
        <div> Do you really want to cancel?</div>
        <div>
          <widget:dismiss type="yes">yes</widget:dismiss>
          <widget:dismiss type="no">no</widget:dismiss>
        </div>
      </widget:popup>
    </div>
  </body>
</html>

The corresponding xforms:model and xforms:submission elements are defined within the head section of the page.

Supported style properties

The optional mcs-cancelable property allows the user to cancel entries on the form. A value of 'always' (default) means the wizard can be canceled; 'never' means the opposite.

The mcs-break-after property determines whether fragmentation occurs or not, and where it occurs.

Note:

Styling of the page navigation links is done exactly in the same way as in case of normal form fragmentation, using the ::mcs-next, ::mcs-previous, and ::mcs-reset pseudo-elements. Refer to Form fragments links in XDIME 2 for details.

Non-client fallback

In the case where the Forms Wizard widget is not supported, the form will behave like a normal form without the widget element. In particular xforms:group elements with mcs-break-after style property set to 'always' will cause the standard form fragmentation provided by MCS.

JavaScript

This widget supports JavaScript as well as the APE architecture. See JavaScript support and Actions, properties and events for details.