Creating a wizard

You can create a new wizard for the application by using the components explained in this topic.

Wizard is a screen which has set of pages and navigation between the pages is pre-defined. A wizard screen is a stack container for wizard pages.

Table 1. Components of a wizard
Component	Description
`<wizard_name>-wizard.tpl.html`	The main HTML file for the wizard.
`<wizard_name>-wizard.config.js`	Configuration file for routing and other configuration required by the wizard.
`<wizard_name_init>.tpl.html`	The main HTML file for the wizard initialization
`<wizard_name_init>.controller.js`	The controller JS file for wizard initialization logic
`<wizard_name_finish>.tpl.html`	The main HTML file for the wizard completion screen.
`<wizard_name_finish>.controller.js`	The controller JS for wizard completion logic.
`<wizard_page_name>.scss`	Styling for the wizard page using SCSS format.
`<wizard_page_name>_mashups.xml`	Mashup definitions for the mashups used in the wizard pages.
`<wizard_page_name>.tpl.html`	The main HTML file for a wizard page.
`<wizard_page_partial>.tpl.html`	The partial HTML files for a wizard page, if necessary
`<wizard_page_name>.controller.js`	The controller JS file that has the behavior logic for a wizard page.

Wizard HTMLs

The <wizard_name>-wizard.tpl.html is the main HTML file that references wizard's init , finish and wizard pages as shown in the following code snippet:

<isc-wizard custom-transition="true" wizard-init-controller="myWizardInitController"
      wizard-init-template-url="myWizardInitTpl.html" 
      wizard-finish-controller="myWizardFinishController"
      wizard-finish-template-url="myWizardFinishTpl.html">

      <isc-wizard-page page-id="myPage1" page-enter-action="myPage1ActionBundleKey" 
        template-url="mypage1.html" controller="mypage1controller"></isc-wizard-page>
      <isc-wizard-page page-id="myPage2" page-enter-action="myPage2ActionBundleKey" 
        template-url="mypage2.html" controller="mypage2controller"></isc-wizard-page>
    </isc-wizard>

Wizard init page

Any validation or logic that needs to be executed as part of wizard initialization should be done in the wizard init page.
Implementation for wizard init page is same as wizard pages.

Wizard finish page

Any validation or logic that needs to be executed as part of wizard completion should be done in wizard finish page.
Implementation for wizard finish page is same as wizard pages.

Wizard page HTML

The UI part of a wizard page is implemented using a single HTML file (<wizard_page_name>.tpl.html) or multiple HTML files. You can divide the screen UI into multiple sections and have partial HTMLs (<wizard_page_partial>.tpl.html) for each section. This makes it easier to manage all the HTML code needed for the UI.

Wizard configuration

Wizard configuration is same as screen configuration. The routing configuration is registered in the <wizard_name>-wizard.config.js file as shown in the following code snippet:

angular.module('store').config(['iscStateProvider',
				function(iscStateProvider) {
				iscStateProvider.state('<state_name/wizard_name>',{
				templateUrl : '<path to <wizard_name>-wizard.tpl.html>',						
		  	     addToHistory :false|true, // when true adds to state history. Default is true
				resourceId : '<resource_permission_id>'//If user has permission to the resource, then only the wizard can be accessed by the user.  be accessed by the user.					
					})
				}
			]);

Wizard page controller ( `init` and `finish` controller)

The logic for wizard behavior is implemented using a controller. Instead of implementing the behavior logic as a normal javascript function, it is implemented as a prototype object, which helps in better code organization. The logic is split into multiple javascript code parts as described in the following table:

Table 2. Components of a controller
Component	Description
`model`	A JSON object which consists of models that can be used to store backend data such as API output. For example, `"orderList":{}` could be used to store the output of the `getOrderList` API.
`mashupRefs`	An array of mashupref objects.
`ui`	JSON object that holds UI properties. It is added to `$scope` and is referenced as `$scope.ui`
`ui<method>`	Methods that can be invoked from HTML events. `ui<methods>` are event handlers. Any method with prefix as `ui` is added to `$scope` and can be referenced as `$scope.ui<method_name>`
`Helper methods`	Methods without `ui` as prefix are treated as helper methods and are not accessed using the `$scope` object.
`Private methods`	Methods with `_` as prefix are treated as private methods and are not accessed using the `$scope` object.
`initialize`	This method is the entry point for the execution logic. Any mashup or API call that needs the `init` logic should be coded in this method.

Since the behavior logic is implemented as a prototype object, this object is termed as the control object. Therefore, you can use 'this' to access the control object attributes.

While writing the controller logic, ensure that you follow these steps:

Invoke mashups to fetch and persist data.
Define models to hold the data fetched by mashups.
Bind UI controls to the models.

Use

iscWizard.initializeWizardPage($scope,{<implementation
logic>});

to initialize wizard page behavior logic to the $scope object. Refer to wizard controller code samples in <wscdev.war>/ngstore/store/views/samples.

Mashups for the wizard

All the mashups referred in a screen should be defined as <wizard_name>_mashups.xml.
Common mashups defined at the application level can be used across screens.
Mashups defined for a screen, for a particular scenario, must not be used in other screens.

Refer the Mashups topic for more information.

Navigating between wizard pages

To start the wizard from wizard init page, use iscWizard.startWizard() when custom-transition="false" and iscWizard.startCustomWizard(pageId,pageInput,pageOptions) when custom-transition="true".
When custom-transition="true" is set for the wizard in the <wizard_name>-wizard.tpl.html file, then the wizard works in custom transition mode, where in the current page needs to open the next page. For example, iscWizard.gotoCustomPage(pageId,pageInput,pageOptions);

When custom-transition="false" is set for the wizard in the tpl.html file, then the wizard works in standard mode, where in the current page needs to call iscWizard.gotoNextPage();
To navigate back, use iscWizardPage.gotoPreviousPage();
To finish the wizard from wizard pages, use iscWizard.finishWizard();
To close the wizard between the flow, use iscWizard.closeWizard();
To store any data at the wizard level, use iscWizard.setWizardContext(key,value); and to retrieve any data at the wizard level, use iscWizard.getWizardContext(key);.
To get the wizard page inputs, use iscWizard.getWizardPageInput();

Wizard styling

Wizard styling is implemented in an SCSS file. Each page should have its own SCSS file.

Sample implementation

You can refer the sample files in <wscdev.war>/ngstore/store/views/samples/wizard folder for better understanding.