 |
| Wizard UI |
There are many scenarios in which the user needs to accomplish a very complex task. One strategy to simplify the task is to split it in a sequence of steps. For this purpose a wizard user interface is needed. K2BTools provides an easy, flexible and powerful way of creating Wizard User Interfaces.
 |
| Wizard Components |
A Wizard is composed of a series of steps, each step implements a part of the Wizard. When using WPD, each step is implemented by a WebComponent that is in charge of validating the data entered in the step. If the data is correct, the wizard goes to the next step. Each WebComponent can only belong to one Wizard.
There is a WebPanel that is in charge of the wizard navigation, which also implements the “Next” and “Previous” standard actions, and is in charge of showing the Wizard Progress Bar. This WebPanel will be called “Wizard Main Panel”.
In the Wizard, it is needed that all steps share some data, in order to read it and update it. The “Wizard Main Panel” is in charge of passing this data to all steps. The data is stored in an SDT, that will be defined by the developer. This SDT will be called “Wizard SDT”.
Each wizard, needs to have a “Wizard SDT”. A “Wizard SDT” is an SDT to temporary store data which will be shared among steps and will be used when the wizard is completed. For example, if the wizard persist data in the database, the information about the value of the records to be persisted should be stored in the Wizard SDT. For more information please read Defining a Wizard SDT.
Wizards can be implemented using the WebPanelDesigner. So, to define a Wizard, create a WebPanel, activate the Designer part and add a Wizard node. In the Wizard Node set the SDT property to the SDT defined in the previous step.
 |
| Adding a Wizard node |
Now it is time to add the steps that implement the wizard. Each step is implemented by a WebPanel. There are two options in order to create a step:
When saving the objects, the logic implementing the wizard's flow will be generated. Also, each step will include logic to load and save data between the wizard SDT and the variables shown in the panel These are some customizations which can be performed in the WebPanel:
- The initialization of the WPD variables with the “Wizard SDT”. The WPD will try to do a mapping between them, however, there are many cases in which the WPD cannot infer the mapping, so mapping initialization code must be added to the U_OpenPage subroutine. For more information about automatic mapping read Automatic Mapping between Wizard SDT and WPD variables
- When the Next or Finish (if it is the last step) action is executed, the event GlobalEvents.K2B_WizardConfirm is fired. This event will call the U_WizardConfirm subroutine. In this subroutine there are many things that can be customized.
- WebPanelDesigner will try to store the variables entered by the user in the “Wizard SDT”. However there are some cases in which this mapping cannot be inferred. For this purpose, code to store the variables in the Wizard SDT can be added. For more information read this.
- Code should be added in order to decide whether the step was successfully completed or not. If the step is not successful the &WizardStepCompleted variable must be set to false. In this case the wizard will not continue to the next step.
- Code could be added, to persist data in the database if needed. The purpose of this method is to give the developer flexibility to add the code needed when the step is completed.
There are many scenarios in which the initialization of the Wizard SDT is needed before starting the wizard. For example if the Wizard persist data in the data base and allows resuming, or if the Wizard Data depends on some values that are selected before the wizard starts.
The developer can add code in the U_InitializeWizardSDT subroutine to achieve this. This subroutine is executed before the first step is created.
In order to perform this initialization, after setting the SDT values, the SDT JSON must be stored in WizardData_WizardMain variable.
 |
| Example of setting the CustomerId in a Wizard that starts with the CustomerId instanciated |
When the user presses the finish button, some actions should be triggered in order to complete the wizard. The developer can add code to decide what will happen when the wizard is finished, and perform global validations on the data entered by the user. Depending on the implementation of the wizard, this code can be added in two places:
- In the U_WizardConfirm subroutine of the last step. The developer can use this subroutine in the last step to implement the finish action. It can be used to invalidate the step, or to add code to persist the result of the wizard in some data structure
- In the U_BeforeComplete subroutine in the “Wizard Main Panel”. Before the wizard is completed, the subroutine U_BeforeComplete is fired. This subroutine can be used to invalidate the wizard by setting the variable &IsValid_WizardMain to false if certain conditions are not met and also it can be used to add code to persist the result of the wizard in some data structure.
As mentioned in this page, the wizard implementation is flexible. The developer can choose to store data in the database, call a WebService, write data in a log, or whatever he wants when the wizard is finished.
The developer can configure what will happen after the Wizard is completed. One way to do that is to add code to the U_AfterComplete subroutine. This subroutine is fired when the wizard is completed. In this method the developer can choose, for example, to navigate to another panel, or to return to the caller.
Another alternative is to add an “After Complete Panel” in the “Wizard” node. When a WebPanel is set, after the wizard is finished, this web panel will be shown. The developer can configure if the AferCompletePanel should appear as an additional step in the Wizard Progress Bar. For more information read Using After Complete in Wizards.
There are certain scenarios in which a step should be skipped depending on a condition related to the data that already entered by the user. K2BTools supports adding conditional steps. To do that, the “HasCondition” property in the Step node must be set to true, in which case a subroutine named IsStepAvailable_{StepName} is created. In this subroutine the developer must add the code to decide whether the step is available or not. For more information read Using Conditional Steps in Wizards.
The “Wizard” node can be anywhere in the structure. Because of this, this user interface can be created easily.
 |
| WebPanel with a WizardNode and other components showing a summary of the data entered in the Wizard |
 |
| Instance specification of the WebPanel containing the Wizard and a summary of the data entered |
The Wizard node has a property called “Wizard Basic Layout”, that references a basic layout object.
The Wizard UX can be customized by modifying its basic layout. For more information read Using Wizard Basic Layout Object.
|