Skip Headers
JD Edwards EnterpriseOne Tools Development Tools: Form Design Aid Guide
Release 8.98 Update 4

Part Number E14706-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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:

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:

  1. Create a working table for each page.

  2. On the Wizard:Save For Reentry event of each wizard page, save the data into the working tables.

  3. 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:

  1. 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.

  2. On the Wizard is Finished event, have the wizard control save the data using table I/O or business functions.

  3. Create one working table to hold reentry data.

  4. 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.

  5. 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.

  6. 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:

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:

Figure 36-1 Wizard form initialization

Description of Figure 36-1 follows
Description of "Figure 36-1 Wizard form initialization"

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 follows
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 follows
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 follows
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 follows
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 follows
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 follows
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 follows
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 follows
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 follows
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:

  1. Runtime initiates the transaction.

  2. Runtime saves each page into the business view.

  3. Runtime fires the Post Button Clicked event if it encounters a Save button on a page (the event fires for each button encountered).

  4. Runtime fires the Post Button Async event for each Save button instance in a separate thread.

  5. Runtime fires the wizard control event: Wizard is Finished-After.

  6. 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.)

Parameters

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

Returns

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.

Parameters

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.

Returns

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."

Parameters

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.

Additional Notes

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.

Parameter

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.

Parameters

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.

Parameters

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.

Additional Notes

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.

Parameters

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).