Wizard navigation behavior

Wizards present users with multiple navigation options. Each panel in a wizard can have buttons for next, previous, finish, or cancel. The names here are the default values but represent generic functions. These options are presented as buttons in the navigation frame at the bottom of the content window. If included, each navigation button has a specific behavior that runs when it is selected by a user.

Next
A user clicks Next in the navigation panel:
  1. If a panel is still loading, do nothing while it finishes loading. Otherwise, continue to the next step.
  2. The savePanelData() function runs on the current panel to save its data into the object model.
  3. The validatePanelData() function runs on the current panel to ensure that the user entered valid data. If there is a problem with this validation, this function returns false and remains on the current panel. You should help the user enter correct data with a meaningful error message.
  4. Display the new panel. When the panel finishes loading, it must indicate this by calling the parent.setContentFrameLoaded(true); function. This stops the progress indicator icon in the tools UI center, and enables the Finish or Next buttons, thus allowing other panels to be selected.
Previous
A user clicks Previous in the navigation panel:
  1. If a panel is still loading, do nothing while it finishes loading. Otherwise, continue to the previous step.
  2. The savePanelData() function runs on the current panel to save its data into the object model.
  3. Display the new panel. When the panel finishes loading, it must indicate this by calling the parent.setContentFrameLoaded(true); function. This stops the progress indicator icon in the tools UI center, and enables the Finish or Next buttons, thus allowing other panels to be selected.
Finish
A user clicks Finish to finalize the interaction with the wizard:
  1. If a panel is still loading, do nothing while it finishes loading. Otherwise, continue to the next step.
  2. Check to see if Finish has already been clicked. If so, return and do nothing. If not, set a flag to indicate that Finish has been clicked.
  3. The savePanelData() function runs on the current panel to save its data into the object model. The data is saved so that if the page re-displays, for example, if some data on the page is not valid, the original data can be pre-populated onto the page. This allows the user to re-enter only the corrected data instead of all of it.
  4. The validatePanelData() function runs on the current panel to ensure that the user has entered valid data. If there is a problem with this validation, this function returns false and remains on the current panel. You should help the user enter correct data with a meaningful error message.
  5. The preSubmitHandler() runs to invoke any optional JavaScript functions that must run before the finish URL.
  6. If a finish command is specified by the finishURL attribute in the wizard XML file, convert the object model to XML and send it as a parameter to the finish command.
  7. Set a flag to indicate that the finish command has completed.
  8. If an error occurs in the finish server command (performing an update or otherwise), the command redirects back to the navigation frame passing back these two parameters:
    SubmitErrorMessage
    The error message to display to the user.
    If National language-enabled, the translated message displays.
    SubmitErrorStatus
    The corresponding error status or error code.

    If the SubmitErrorStatus variable is passed in, then the submitErrorHandler() function runs with the preceding two variables as parameters. You are responsible for implementing this function in the JavaScript file so that it displays the error message to the user, and redirects to the problematic input field based on the error code. If this function is not defined, a default alert window displays the error message.

    If the SubmitErrorStatus is not passed in, then it is assumed that the finish command succeeded.

  9. Call the submitFinishHandler() function with the submitFinishMessage as a parameter, which was set in the controller command.
Cancel
Displays a cancel confirmation dialog. If the user clicks OK, submitCancelHandler() then the parent frame's cancel method is run.