Creating a wizard

You can create a wizard by specifying the wizard definition in the additionalwizards.xml file, and by creating the wizard UI widget.

1. Create a wizard definition in the additionalwizards.xml file. Ensure that the wizard ID is prefixed with extn.
   For example, <wizard id=extn.wizards.CustomWizard>.
2. Copy the additionalwizards.xml file to the <INSTALL_DIR>/extensions/wsc/webpages/wizardxmls/ folder.
3. Create a wizard widget for the corresponding wizard ID.
   For example, if the wizard ID is extn.wizards.CustomWizard, create CustomWizard.js widget with declared class as extn.wizards.CustomWizard. Copy the CustomWizard.js file to the <INSTALL_DIR>/extensions/wsc/webpages/wizards/ folder and the corresponding wizard widget templates to the <INSTALL_DIR>/extensions/wsc/wizards/templates/ folder.
4. Open the wizard by calling the WizardUtils.openWizardInEditor utility. To open the wizard, pass the following parameters in the WizardUtils.openWizardInEditor utility:
   • wizardId - identifier of the wizard.
   • wizardInput - initial input of the wizard.
   • editorId - identifier of the editor.
   • editorConfig - configuration for the editor. The attributes that are provided for this parameter are added to the editor.

   The wizard utility methods enable users to navigate in the wizard. The following table describes a few wizard utility methods of the WizardUtils.js (sc.plat.dojo.utils.WizardUtils) file. For more information about wizard utility methods, see the JavaScript documentation.

   Table 1. Wizard utility methods

   Wizard utility methods	Description
   getCurrentPage	Considers a wizard instance and returns the page that is displayed in the stack container of the wizard.
   isCurrentPageFirstEntity	If the page that is displayed or to be displayed is the first entity in the stack container of a wizard, this method returns the value true.
   isCurrentPageLastEntity	If the page that is displayed or to be displayed is the last entity in the stack container of a wizard, this method returns the value true.
   nextScreen	Retrieves the next screen of a wizard to be displayed.
   previousScreen	Displays the previous screen of a wizard flow.
   confirmWizard	Confirms a wizard instance.
   openWizardInEditor	Opens a wizard instance for a wizardId with wizardInput.
   closeWizard	Raises the beforeClose event and closes the wizard.
   getCurrentPageByUId	Retrieves the current page UID.
   isCurrentPageLeaf	If the page opened in a wizard is a leaf node, this method returns the value true.

   The wizard definition XML files are in the <INSTALL_DIR>/repository/eardata/wsc/war/wizardxmls directory. The UI files are in the <INSTALL_DIR>/repository/eardata/wsc/war/wsc/<module>/wizards directory. Here, <module> refers to shipment or others. For example, the wizard definition CustomerPickWizardFlow.xml file is in the <INSTALL_DIR>/repository/eardata/wsc/war/wizardxmls directory. Whereas, the CustomerPickWizard XML UI files are located in the <INSTALL_DIR>/repository/eardata/wsc/war/wsc/shipment/wizards directory.

   Ensure to create a wizard with navigation buttons such next, previous, confirm and cancel. On click of Next, the saveCurrentPage event is raised for the current wizard page to save data. After the data is saved, the onSaveSuccess event is raised and the next page is displayed in the wizard. Similarly, on click of Previous, a warning message is displayed prompting the user to save data on the current wizard page before going to the previous page. On clicking Yes, the saveCurrentPage event is raised. After the data is saved, the onSaveSuccess event is raised by the page to the wizard, and the previous wizard page is displayed. The event interaction between wizard and pages for Confirm and Cancel is similar to Next and Previous.

   For custom wizards, the following events are raised:

   • setScreenTitle - This event is raised to set the subtitle on the editor. For example, in the Create Order wizard, the title is Create Order and subtitle is Customer Search, which is the first screen in the wizard page.
   • handleTabClose - This event is raised when an editor is closed. Before closing the wizard, a warning message is displayed prompting the user to save any unsaved data on the page. Ensure to define the handleTabClose event subscriber for new wizards, so that the user is prompted to save data on closing the editor.
   • setWizardInput - This event is raised by an editor whenever the editor input is modified on some UI action. For example, when the editor input is changed on identifying a customer for the order, the editor input is updated and the setWizardInput event is raised to update the wizard input.