Implementing Modal Transfers

This section provides an overview of modal transfers and discusses how to implement modal transfers.

When you use modal transfers to transfer from one component (the originating component) to another component (the modal component), the user must click the OK or Cancel buttons on the modal component before returning to the originating component.

Modal transfers provide some control over the order in which the user fills in pages, which is useful where data in the originating component can be derived from data entered by the user into the modal component.

Limit use of this feature, as it forces users to complete interaction with the modal page before returning to the main component.

Note: Modal transfers cannot be initiated from SearchInit PeopleCode.

A modal component resembles a Microsoft Windows modal dialog box. It displays three buttons: OK, Cancel, and Apply. No toolbars or windows are available while the modal component has the focus. The OK button saves changes to the modal component and returns the user to the originating component. The Apply button saves changes to the modal component without returning to the originating component. The Cancel button returns the user to the originating component without saving changes to the modal component.

Modal components are generally smaller than the page from which they are invoked. Remember that OK and Cancel buttons are added at runtime, thus increasing the size of the pages.

The originating component and the modal component share record fields in a derived/work record called a shared work record. The derived/work fields of this record provide the two components with an area in memory where they can share data. Edit boxes in both components are associated with the same derived/work field, so that changes made to this field in the originating component are reflected in the modal component, and vice versa. The following diagram illustrates this shared memory:

Image: Edit boxes on the originating and modal components share the same data

The following diagram explains that the Edit boxes on the originating and modal components share the same data.

Edit boxes on the originating and modal components share the same data

Edit boxes associated with the same derived/work fields must be placed at level zero in both the originating component and the modal component.

You can use the shared fields to:

  • Pass values assigned to the search keys in the modal component search record.

    If these fields are missing or invalid, the search page appears, enabling the user to enter search keys.

  • Pass other values from the originating component to the modal component.

  • Pass values back from the modal component to the originating component.

Modeless Windows

In addition to modal secondary windows, you can create a modeless window. A modeless window is different from a modal window launched by any of the DoModal* functions in that its state is separate from that of the parent, launching component. When a modeless window is launched from a classic component using the TransferModeless function, the modeless window does not mask the parent window, which allows the user to update the modeless and parent window from the same browser session at the same time. However, when a modeless window is launched from a fluid component using either the ViewContentURLModeless or ViewURLModeless functions, the parent window is masked and cannot be accessed until the modeless window is dismissed. In this respect and from the user’s perspective, a modeless window launched from a fluid component operates similar to a modal window; but programmatically, its state is separate from that of the parent, launching component.

Similar to modal, secondary windows opened by any of the DoModal* functions, the modeless window does not include the browser title bar, browser menus, and the browser tool bars, status bar, and tool icons associated with most browser windows.

Note: While the title bar of a modeless window includes an X (or cancel) button, it cannot include any custom buttons.

Important! Only one active child modeless window can be open at one time. Therefore, after opening a modeless child window from the parent, you cannot open a second modeless child window from that modeless window. However, you can open a modal window from that modeless window.

Any component accessible through an application menu system can be accessed using a modal transfer. However, to implement a modal transfer, you must modify pages in both the originating component and the modal component. After these modifications are complete, you can implement the modal transfer using the DoModalComponent function from a page in the originating component.

Before beginning this process, you should answer the following questions:

  • Should the originating component provide search key values for the modal component?

    If so, what are the search keys? (Check the modal component's search record.)

  • Does the originating component need to pass any data to the modal component?

    If so, what record fields are needed to store this data?

  • Does the modal component need to pass any data back to the originating component?

    If so, what record fields are needed to store this data?

To implement a modal transfer:

  1. Create derived/work record fields for sharing data between the originating and modal components.

    Create a new derived/work record or open an existing derived/work record. If suitable record fields exist, you can use them; otherwise create new record fields for any data that needs to be shared between the components. These can be search keys for the modal component, data to pass to the modal component, or data to pass back to the originating component.

  2. Add derived work fields to the level-zero area of the originating component.

    Add one edit box for each of the derived/work fields that you need to share between the originating and modal components to the level-zero area of the page from which the transfer will take place. You probably want to make the edit boxes invisible.

  3. Add the same derived work fields to the level-zero area of the modal component.

    Add one edit box for each of the edit boxes that you added in the previous step to the level-zero area of the page to which you are transferring. You probably want to make the edit boxes invisible.

  4. Add PeopleCode to pass values into the derived/work fields in the originating component.

    To provide search key values or pass data to the modal page, write PeopleCode that assigns appropriate values to the derived/work fields before DoModalComponent is called.

    For example, if the modal component search key is PERSONAL_DATA.EMPLID, you could place the following assignment statement in the derived/work field's RowInit event:

    EMPLID = PERSONAL_DATA.EMPLID

    You also might assign these values in the same program where DoModalComponent is called.

  5. Add PeopleCode to access and change the derived/work fields in the modal component.

    No PeopleCode is required to pass search key values during the search. However, if other data has been passed to the modal component, you may need PeopleCode to access and use the data. You may also need to assign new values to the shared fields so that they can be used by the originating component.

    It is possible that the component was accessed through the menu system and not through a modal transfer. To write PeopleCode that runs only in the component when it is running modally, use the IsModalComponent function:

    If IsModalComponent() Then 
       /* PeopleCode for modal execution only.  */ 
    End-If
  6. Add PeopleCode to access changed derived/work fields in the originating component.

    If the modal component has altered the data in the shared work fields, you can write PeopleCode to access and use the data after DoModalComponent has executed.

    Note: You can use the EndModalComponent function as a programmatic implementation of the OK and Cancel buttons.