36 Understanding Wizard Controls
This chapter contains the following topics:
36.1 Wizard Controls
The wizard control is the primary component of the wizard. It can reside only on the wizard form type, and only one wizard control can exist on any given wizard form. Each wizard control contains multiple pages; each page is comprised of one subform or alias. Each page corresponds to a task that the user must complete to finish the wizard. During runtime, the wizard displays the first page and waits for the user to complete the task. Typically, you use the pages to prompt the user to provide input. After completing the task, the user clicks the Next button, and the wizard validates page one data and displays the second page in the list (index). In a standard scenario, the user continues in this fashion until the last page is reached, at which point the user clicks Finish and the wizard re-validates and commits the data before terminating.
You can opt to display the progress list itself (which also enables the user to jump between tasks by clicking a task in the progress list), and you can also display a progress indicator which shows how much of the wizard is complete without listing the individual tasks. The progress list indicates which pages have been completed, which ones have errors, and which ones have warnings by displaying icons next to affected tasks. You cannot alter these icons programmatically. Additionally, the control automatically provides certain buttons on each page of the wizard. It provides a Previous button on all but the first page, a Next button on all but the last page, a Finish button on the last page, and an Exit button on all pages. You can add additional buttons such as Save and Cancel, but you cannot remove these default buttons.
You can enable users to start a wizard and then save it to finish later. If a user saves, the control does not automate saving the data for you. Instead, you must react to the WIZARD:Save for Re-entry event and save the data programmatically. If you enable revisits on the wizard, the interface provides a Save For Later button as well.
The subforms included in the wizard have no form- or control-based limitations; that is, you can employ the full range of subform features and system functions. Therefore, to create an effective wizard application, you must be proficient with subforms.
Each subform is parented to the wizard form which means that subforms cannot communicate with each other directly; they must share data using the wizard form. Data can be passed in one of three ways: from page to wizard form (child to parent), from wizard form to page (parent to child), or in both directions. Only data in the child page data structure can be passed to the parent wizard form. Consequently, you must plan the data structures carefully. In general, objects in the data structure will fall into one of two categories: items which the page will want to share with other pages, and items which the page will require such as input from other pages or the wizard form itself.
You can embed subforms and use an alias to a reusable subform. You can programmatically reorder the pages (therefore reordering the tasks). You can also indicate a starting page other than the first one in the list. As the user progresses through the wizard, tasks that the user has completed are referred to as upstream tasks. Those which the user has yet to complete are referred to as downstream tasks.
You are not limited to forms inside the wizard. You can use form interconnections to link to forms outside of the wizard. If you use an interconnection, the forms that appear are called satellite pages. Like the wizard itself, satellite pages expand to fill the entire frame; the standard JD Edwards EnterpriseOne navigation menu is hidden. When the user clicks OK on the satellite page, the wizard reappears displaying the page containing the object that triggered the interconnection.
Forms have different statuses including indeterminate (no state), complete, and incomplete (but continue). No state is the initial, pristine state of a page and it indicates that the page has been initialized but not yet visited. Complete indicates that the page has been visited, finished successfully, and validated. Incomplete indicates that the page has been visited but not yet finished or validated. All pages in the wizard must be at a status of complete before runtime can commit data.
Runtime validates all wizard pages when the user clicks Finish, even hidden and disabled pages. To prevent a page from being validated and saved, enable the Form Design Aid (FDA) property, Suppress Validation and Save. During runtime, use the system function, Suppress Wizard Page Validation and Save. As a rule of thumb, call the Suppress Wizard Page Validation and Save system function for all hidden and disabled pages in the wizard to prevent Finish button processing on them.
When a wizard application is launched, runtime sets the status of all pages to no state as part of the initialization process. When the user enters a page of indeterminate status, runtime changes its status to incomplete to reflect the fact that the user has visited the page. These are the only times that runtime sets the page status. Application logic is expected to manage page status otherwise. However, runtime will not permit the application to assign a complete status to a page until all its errors have been resolved.
All pages must be at a status of complete for the Finish button process to succeed, even hidden and disabled pages, unless validation is suppressed for those pages. If any page is not set to complete, the Finish button process will fail and no data will be saved. To set page status, use the Set Wizard Page Status system function.
36.2 Wizard Control Design-Time Considerations
The wizard control permits the standard control property settings; likewise, the standard options are available for subforms and forms as well. It is recommended that you always enable transactions for all objects in the wizard, however. Since the runtime engine gathers and saves all data and then commits it in a single transaction if the wizard finishes with no errors, disabling transactions on any wizard object is counterproductive.
In addition to the standard control property values, the wizard control includes these wizard control-specific values as well:
-
Progress Indicator
If you want to show how much of the wizard has been completed, you can choose to do so as a percentage value or as the number of tasks completed out of the whole (X of Y).
-
Enable Re-entry Save
When enabled, this option displays the Save For Later button on every page. You can add logic to the button that enables users to stop using the wizard before completing it, save their work up to that point, and then return to the wizard later to finish. Because the wizard hides the JD Edwards EnterpriseOne navigation menu, you might consider enabling this option for lengthy wizards. Users cannot launch other JD Edwards EnterpriseOne applications if they cannot access the JD Edwards EnterpriseOne navigation menu.
Note:
Enabling this option only displays the Save For Later button. You must add application logic to save data and then load it and return to the correct page when the user returns. The wizard will not commit data to the database until the entire wizard is completed. -
Enable Progress List
When enabled, this option displays the list of tasks (each task corresponds to a wizard page) comprising the wizard. As the user completes the tasks, his or her advancement is indicated in the progress list.
Users can jump to up- or downstream tasks by choosing a task in the list. The user cannot jump to disabled, hidden, or unvisited pages using the progress list.
-
Suppress Validation and Save
This option is applied on individual subforms. Typically, you apply it to subforms which you have also disabled or hidden. You can use this option to prevent such pages from being processed at runtime, thereby making the wizard more efficient. Furthermore, the Finish button process requires that every validated page be at a status of complete. Depending on how you design the application, it might not be possible for disabled and hidden pages to achieve this status. Therefore, you must suppress validation and save on such pages or the wizard application will never commit data to the database.
The ability to suppress validation and save functions can be enabled and disabled during runtime with the Suppress Wizard Page Validation and Save system function.
36.2.1 Implementing Re-entry Save
When you select the Enable Re-entry Save option, the application must perform data saves and any other functions you want the application to provide if a user decides to save the wizard and return later.
This list describes a method for implementing re-entry save when each wizard page contains a separate business view:
-
Create a working table for each page.
-
On the Wizard:Save For Reentry event of each wizard page, save the data into the working tables.
-
When the user reenters, on the Wizard:Subform is Initialized event of each wizard page, load data from the working table and assign the values to form controls and variables.
This event occurs after the system applies next numbers and default values, so they will not override the user's earlier data.
This list describes a method for implementing re-entry save when each wizard page shares the same business view or has no business view:
-
Have the wizard control collect data from each page and store it in event rule (ER) variables.
The mapping links between the wizard pages and the wizard form must be bidirectional so that the wizard form can push data into each page.
-
On the Wizard is Finished event, have the wizard control save the data using table I/O or business functions.
-
Create one working table to hold reentry data.
-
On the Wizard:Save For Reentry event of each wizard page, pass the data from the child subform so the parent wizard form can save the data into the working table using table I/O or business functions.
-
When the user reenters, on the Post Wizard is Initialized event, have the wizard control load data from the working table and into ER variables.
Setting ER variables on this event enables you to override the next numbers applied by the system.
-
On the Wizard:Subform is Entered event, the system automatically populates subform interconnect (SI) variables from the parent wizard form. The page must assign the SI variables to form controls to display them.
36.3 Wizard Control Events
Wizard forms and their subforms have these wizard form-specific events (some occur on the wizard form and some on its subforms), and they typically occur roughly in this order:
-
Wizard is Initialized
This form-level event indicates that the form and control have been created, security has been applied, system variables have been initialized, and form data structures have been loaded. It is the only event on which you should use the Set Wizard Form Mode system function (to change the form mode to add, update, or copy), and the only one of two events on which you should use Set Selected Wizard Page (to start at a page other than the first visible, enabled page in the index).
Wizard is Initialized is also where you should hide, show, disable, or enable a page, or suppress page processing for a page, as appropriate. Finally, this is also when you should rearrange the page order if necessary (Set Wizard Page Index).
-
Post Wizard is Initialized
This form-level event fires immediately after Wizard is Initialized, indicating that the initialization process is complete and runtime is poised to enter the first page in the wizard. Any logic that should be applied to the Wizard is Initialized event can be applied here also. You can use the Set Selected Wizard Page system function on this event, but not after; runtime determines which page is the "first page" to enter based in part on whether you set a selected page.
-
WIZARD:Subform is Initialized
This subform-level event indicates that a subform has been initialized (including the standard processing for subforms in add mode). The event fires for each subform in the wizard control, in order. This event is called only once during the life cycle of a wizard form per session. If the user worked on the wizard previously and saved (that is, if this is a reentry), this event can be used to load previous session data and then assign the data to form controls and ER variables.
-
WIZARD:Subform is Entered
This subform-level event indicates that the page status is incomplete, that parent mapping links have been reestablished, and that the SI values have been updated. The event fires every time a user visits a page by accessing it from a previous page. The SI values should contain all current information. Assign SI values to form controls and grid rows if necessary. Set filter values and QBEs at this point if the Automatically Find On Entry option is enabled.
-
WIZARD:Post Subform is Entered
This subform-level event indicates that any processing required by the Automatically Find on Entry option is complete. This event is called every time a user visits this page from an earlier page. This is called after the Subform Entered event and after the automatic data fetch if Automatically Find On Entry is enabled.
-
WIZARD:Save for Re-entry
This subform-level event fires on every page, except those on which Suppress Validation and Save is enabled, when the user clicks the Save for Re-entry button. the application should save the data on the current page to a temporary working table on this event.
-
WIZARD:Validate Subform
This subform-level event occurs before runtime conducts customized validation of the form controls and grid rows. Runtime always performs the data dictionary validations unless the Suppress Validation and Save option is enabled for the page. At this point, the application code should set the page status to complete by calling he system function Set Wizard Page Status.
-
WIZARD:Subform is Exited
This subform-level event fires once for each subform in the control after the transactions have been processed and runtime is preparing to close the wizard form. It is the last subform-level event to fire for each subform before the wizard closes. On this event, the application should copy form controls or grid rows to SI variables, then call the Update Parent subform system function to update the wizard form. You can perform this call conditionally, such as when the user clicks Next or Finish.
-
Page is Exited - Before
This form-level event indicates that subform validation is complete. It is the last event to fire before runtime exits the current subform.
-
Page is Exited - After
This form-level event fires immediately after any logic on Page is Exited - Before finishes processing.
-
Wizard is Finished - Before
This form-level event indicates that page-level validation is complete and that runtime is about to begin passing data from the wizard to the business view.
-
Wizard is Finished - After
This form-level event fires after the business view is loaded with data from the wizard form but before the data is committed to the database. It is on this event that you should code any data operation that needs to be included in the transaction. Do not trigger a form interconnect on this event.
-
Wizard is Exited
This form-level event fires before form close; it is the last event to fire. This is the point at which you should add code to clean up caches and other resources used by the wizard. If you require a form interconnect (such as for a confirmation form), this event occurs outside the transaction boundary and is therefore safe to use to trigger the interconnection.
Note:
Even though wizard control may resemble a tab control, none of the tab page events are fired for wizard pages. Wizard pages are not tab pages.36.4 Wizard Control Runtime Processing
This section discusses the runtime processing of the wizard control.
36.4.1 Initialization
Form initialization is the only point at which you can change the form mode (add, edit, or update), and you should do so with Set Wizard Form Mode on the Wizard is Initialized event because runtime checks the form mode immediately after firing Wizard is Initialized.
This flowchart illustrates how runtime initializes the wizard form:
36.4.2 Page Entry
After the wizard form is initialized, runtime enters the first page in the wizard control. Runtime determines the first page to be the first enabled and visible page it encounters, starting from either the first page in the index or the selected page indicated by the Set Selected Wizard Page system function.
When the user enters a new page, the system automatically populates the SI variables from the parent form variables before Wizard:Subform is Entered fires. You can place logic to populate subform fields with this data on either event that fires during page entry.
This flowchart illustrates how runtime processes page entry:
Figure 36-2 Wizard control page entry processing
Description of "Figure 36-2 Wizard control page entry processing"
36.4.3 Next Button Processing
The Next button causes runtime to validate the current page. If no errors occur due to validation, then runtime displays the next downstream, visible, enabled page in the index. If errors occur, runtime does not display the next page; instead, it highlights the errors so that the user can fix them before moving forward.
When the user exits a page, the system does not automatically populate the SI variables to the parent form variables. Therefore, the application must assign appropriate SI variables and call the Update Parent subform system function in the WIZARD:Subform is Exited event, if necessary.
This flowchart illustrates the runtime processing that occurs on the current page when the user clicks the Next button:
Figure 36-3 Wizard control Next button processing
Description of "Figure 36-3 Wizard control Next button processing"
36.4.4 Previous Button Processing
When the user clicks the Previous button, runtime displays the previous upstream, visible, enabled page in the index, including the data entered by the user. To prevent the data from being cleared, runtime does not run the enter page process. If errors occur during validation, runtime marks the pages with errors in the progress list (if visible), but it always displays the previous page, nonetheless.
If the user wants to change previously entered data, he or she may do so, but must click Next to save the changes.
This flowchart illustrates the runtime processing that occurs when the user clicks the Previous button:
Figure 36-4 Wizard control Previous button processing
Description of "Figure 36-4 Wizard control Previous button processing"
36.4.5 Jumping Up- and Downstream
When the progress list is enabled, users can access previously-visited pages directly, effectively skipping one or more tasks if they select a page that is not immediately before or after the current page in the index.
When a user jumps downstream, runtime loops through each page between the start and target inclusively, applying Next button processing which includes error processing. If a page between the starting page and the target page throws an error in the course of Next button processing, runtime halts processing and displays the page on which the error occurred. If the user successfully jumps to the target page, runtime performs the page entry process.
This flowchart illustrates the runtime processing that occurs when the user tries to jump to a downstream page:
Figure 36-5 Wizard control downstream jump processing
Description of "Figure 36-5 Wizard control downstream jump processing"
When a user jumps upstream, runtime performs Previous button processing on the current page and then displays the target page as long as that page is visible and enabled. If the processing produces errors, runtime displays them, but it does not prevent the display of the target page. Runtime does not process the pages between the current page and the destination page because it is assumed that upstream pages should not be affected by downstream pages. Furthermore, runtime does not run the page entry process because nothing should change on the destination page.
If the user wants to change previously entered data, he or she may do so, but must click Next to save the changes.
This flowchart illustrates the runtime processing that occurs when the user tries to jump to an upstream page:
Figure 36-6 Wizard control upstream jump processing
Description of "Figure 36-6 Wizard control upstream jump processing"
36.4.6 Save for Re-entry Button Processing
If you enable it, the user can click the Save for Re-entry button to save the data to that point and close the form. You are responsible for creating logic to perform the data save (and to enable the user to return to the correct spot later).
This flowchart illustrates the runtime processing that occurs when the user clicks the Save for Re-entry button:
Figure 36-7 Wizard control Save for Re-Entry button processing
Description of "Figure 36-7 Wizard control Save for Re-Entry button processing"
36.4.7 Cancel Button Processing
When the user clicks Cancel, runtime confirms that the user actually wants to quit without saving any changes. If the cancel is confirmed, runtime sets SV Curr_Wizard_Action = CO WIZ_CANCEL, fires Wizard:Subform is Exited for every page in the wizard, followed by Wizard is Exited. Then runtime closes the wizard form.
36.4.8 Finish Button Processing
Finally, runtime is ready to perform transaction processing. Runtime processes each subform in order, writing the data to the business view, but not committing to the database. If a subform has a save button that was clicked, runtime performs standard save button processing. After all of the pages have been processed, runtime commits all database changes in one transaction and then proceeds to close each subform and then the wizard form.
This three-part flowchart illustrates the runtime processing that occurs after the successful validation of all pages in the wizard:
Figure 36-8 Wizard form Finish button processing, part 1 of 3
Description of "Figure 36-8 Wizard form Finish button processing, part 1 of 3"
Figure 36-9 Wizard control Finish button processing, part 2 of 3
Description of "Figure 36-9 Wizard control Finish button processing, part 2 of 3"
Figure 36-10 Wizard control Finish button processing, part 3 of 3
Description of "Figure 36-10 Wizard control Finish button processing, part 3 of 3"
36.5 Wizard Control Transaction Processing
All data is saved with a single transaction when the user clicks the Finish button. Contrast this behavior with clicking the Next button which validates data, but does not save it to the business view. Consequently, it is recommended that you limit the number of pages in a wizard for performance purposes.
The save transaction boundary is composed of and defined by this sequence of events:
-
Runtime initiates the transaction.
-
Runtime saves each page into the business view.
-
Runtime fires the Post Button Clicked event if it encounters a Save button on a page (the event fires for each button encountered).
-
Runtime fires the Post Button Async event for each Save button instance in a separate thread.
-
Runtime fires the wizard control event: Wizard is Finished-After.
-
Runtime performs the commit/rollback transaction.
Do not call form interconnects during any of the events inside the transaction boundary. Opening a new form will prolong the transaction and severely impact system performance.
For this reason, do not launch a separate "confirmation form" from any of these events. Instead, it is recommended that you use the last page of the wizard as the confirmation page. If it must be a separate form, then launch a confirmation form in the Wizard is Exited event. You can use the system variable SV Curr_Wizard_Action and launch only the confirmation form when the user clicks the Finish button.
36.6 Wizard Control System Functions
You can use the Disable Subform and Enable Subform system functions to hide and show pages. Because the wizard form is the parent of all subforms, only the wizard form can disable, enable, hide, or show a given page. This section lists the system functions that are specific to the wizard form and the wizard control.
Get Current Wizard Page ID
Use this system function to get the ID of the current page in the wizard. (The control ID of a subform can be found in the properties for the subform in FDA.)
- Wizard Control
-
The wizard form control (FC) to affect.
- Wizard Page ID
-
Input (integer), required. The object to which to assign the return value that indicates the ID of the current page. Set the parameter to an applicable object from the object list
The system function returns the ID of the current wizard page to the object indicated by Wizard Page ID.
Get Wizard Page Index
Use this system function to retrieve the index of a selected wizard page in relationship to the other wizard pages. The list of wizard pages starts with an index of one.
- Wizard Control
-
The wizard FC to affect.
- Subform
-
Input, required. The page for which you want the index value. Set the parameter to an applicable object from the object list.
- Index
-
Input (integer), required. The object to which to assign the return value that indicates the point in the list where the subform resides. This parameter is 1-based. Set the parameter to an applicable object from the object list.
The system function returns he index value of the subform to the object defined by Index.
Set Selected Wizard Page
Use this system function to make one of the wizard pages active; that is, "selected."
- Wizard Control
-
The wizard FC to affect.
- Subform
-
Input, required. The page you want to make active. Set the parameter to an applicable object from the object list.
This function is specifically designed to enable the user to change the initial page that will be displayed on a wizard control. If the Enable Re-entry Save option is selected, you can use this system function to display the page where the user left off when he or she restarts the wizard, for example.
Set Selected Wizard Page should not be called outside of the initialization of a wizard control (Wizard is Initialized or Wizard Post-Initialized events). Calling this function outside of the initialization of a wizard control might cause the wizard to malfunction and so is unsupported.
If a page is visible and enabled, this function enables you to skip it only if it has a status of complete or incomplete.
Set Wizard Form Mode
Use this system function to change the runtime mode of the wizard form to update, add, or copy. Use this function in the Wizard is Initialized event only.
- Mode
-
Input, required. The runtime mode to which to set the wizard form. Set the parameter to <Update Mode> (1), <Add Mode> (2), or <Copy Mode> (3).
Set Wizard Page Index
Use this system function to change the index of a selected wizard page, effectively "reordering" the pages. The list of wizard pages starts with an index of one.
- Wizard Control
-
The wizard FC to affect.
- Subform
-
Input, required. The page for which you want to change the index value. Set the parameter to an applicable object from the object list.
- Index
-
Input (integer), required. The index value to assign to the page. This parameter is 1-based. Set the parameter to an applicable object from the object list.
Set Wizard Page Status
Use this system function to set the status of a page in the wizard. The default status of a wizard page is to have no status.
- Subform
-
Input, required. The subform FC to affect.
- Status
-
Input (integer), required. The status to which to set the page. Set the parameter to <Complete> (1), <Incomplete> (2), or applicable object from the object list.
The default status of a wizard page is to have no status. An enabled and visible page with no status will not permit the user to move the next page. Changing the status to either complete or incomplete will permit the user to move to the next page.
All enabled and visible pages must be set to a complete status in order for completion processing to take place and permit the user to complete the wizard.
Suppress Wizard Page Validation and Save
Use this system function to prevent runtime validation and save functions for a specified wizard page. Typically, you suppress validation and save on invisible or disabled wizard pages.
- Subform
-
Input, required. The subform FC to affect.
- Suppress
-
Input (integer), required. A flag indicating whether to validate and save the page. Set the parameter to <Yes> (1) or <No> (2).