More Wizards

This section describes some additional features of wizards.

More Complex Navigation

Normally, a wizard displays each wizardpage in the order that you place them in the XUL file. In some cases however, you may want to have different pages of the wizard appear depending on what the user selects in earlier pages.

In this case, place a pageid attribute on each of the pages. This should be set to an indentifer for each page. Then, to navigate to a page, use one of two methods:

1. Set the next attribute on each page to the page ID of the next page to go to. You can change these attributes as needed to navigate to different pages.
2. Call the wizard's goTo method. It takes one argument, the page ID of a page to go to. You might call this method in the onpageadvanced or onwizardnext handlers. Remember to return false in this case, because you have already changed the page yourself. Note that the goTo method, because it causes a page change, will fire the events again, so you'll have to make sure you handle this case.

For example, here are a set of wizard pages (the inner content has been omitted):

<wizardpage pageid="type" next="font">
<wizardpage pageid="font" next="done">
<wizardpage pageid="color" next="done">
<wizardpage pageid="done">

The wizard always starts at the first page, which in this case has the page ID type. The next page is the one with the page ID font, so the wizard will navigate to that page next. On the page with the page ID font, we can see that the next page is done, so that page will be displayed afterwards. The page with the page ID done has no next attribute, so this will be the last page. A script will adjust the next attributes as necessary to go to the page with the page ID color when needed.

Wizard Functions

The wizard works much like a tabbed panel, except that the tabs are not displayed and the user navigates between pages by using the buttons along the bottom. Because all of the pages are part of the same file, all of the values of the fields on all pages will be remembered. Thus, you do not have to load and save information between pages.

However, you may want to do some validation of each field on each page. For this, use the handlers described in the previous section. If a field is invalid, you might display an alert. In some cases, it would be more convenient to disable the Next button until valid input has been entered.

The wizard has a property canAdvance, which can be set to true to indicate that the Next button should be enabled. If set to false, the Next button is disabled. You can change the property when invalid or valid data has been entered.

In the following example, the user must enter a secret code into a textbox on the first page of the wizard. The function checkCode is called whenever the first page is shown as indicated by the onpageshow attribute. It is also called whenever a key is pressed in the textbox, to determine whether the Next button should be enabled again.

<?xml version="1.0"?>

<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

<wizard id="theWizard" title="Secret Code Wizard"
  xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

     <script>
     function checkCode()
     {
       document.getElementById('theWizard').canAdvance=
         (document.getElementById('secretCode').value == "cabbage");
     } 
     </script>

     <wizardpage onpageshow="checkCode();">
       <label value="Enter the secret code:"/>
       <textbox id="secretCode" onkeyup="checkCode();"/>
     </wizardpage>

     <wizardpage>
       <label value="That is the correct secret code."/>
     </wizardpage>

</wizard>

There is also a corresponding canRewind property that you can use to enable or disable the Back button. Both properties are adjusted automatically as you switch pages. Thus, the Back button will be disabled on the first page so you don't have to set it yourself.

Another useful property of the wizard is currentPage, which holds a reference to the currently displayed wizardpage. You can also modify the current page by changing this property. If you do change it, the various page change events will still be fired.

(Next) Next, we'll see how to use overlays to handle common content.

Examples: 12.5.1