Modal dialogs

A Modal Dialog is similar to a Pop-up Page, in that it opens a dialog box to display a page on top of the main application content. However, modal dialog is different in a number of ways.

  • When a modal dialog is open, its parent page cannot be accessed. The parent page is grayed-out and ignores any user action.
  • Changing the page in the Modal Dialog, either by submitting a form or by clicking a hyperlink, causes it to close, and the parent page to be changed to the changed page, with the following exceptions
    • If the page linked to has the same id as the current modal page (e.g. a 'save & new' button/link), then the page will be refreshed within the same modal window
    • If the link clicked has the attribute DISMISS_MODAL set to false, the page linked to will opened within the same modal window
    • If the link clicked has the attribute OPEN_MODAL set to true, it will open in a new modal window
  • The usage of Modal Dialogs is different to that of Pop-up pages. It is considerably less complex, consisting of using either one or two optional attributes on the LINK tag.

Using Modal Dialogs

A LINK tag is made to open in a Modal Dialog, rather than the default action of opening a new page in the same window, by setting the OPEN_MODAL attribute to true.

<LINK PAGE_ID="MultiSelectWidgetResult" OPEN_MODAL="true" />

Note in the example the use of the OPEN_MODAL attribute on the LINK tag.

Setting OPEN_MODAL on a LINK that is inside an ACTION_CONTROL of type SUBMIT has no effect. Setting OPEN_MODAL =true on a link implies also having DISMISS_MODAL =false on that link, and setting DISMISS_MODAL =true on it is ignored. Setting DISMISS_MODAL =false implies OPEN_MODAL =false, so there is no need to set it.

Configuring Modal Dialogs

Modal Dialogs can be individually configured by setting the WINDOW_OPTIONS attribute on a LINK tag which has the OPEN_MODAL attribute set to true. Multiple options can be set via this attribute, which is formatted as a comma separated list of name value pairs. The currently supported parameters are

  • width - sets the width of the Modal Dialog, measured in pixels. This parameter takes an integer value.
  • height - sets the height of the Modal Dialog, measured in pixels. This parameter takes an integer value.
<LINK PAGE_ID="MultiSelectWidgetResult" OPEN_MODAL="true"
          WINDOW_OPTIONS="width=600,height=500" />

Note in the example above the use of the WINDOW_OPTIONS attribute. The values specified for width and height are simple integers and do not have any alphabetic characters appended. A default width of 600 pixels is used if no width parameter is specified. If no height parameter is specified the height will be automatically calculated to accommodate the page contents. If an unsupported parameter is placed in the WINDOW_OPTIONS, a build time exception will be thrown.

If the WINDOW_OPTIONS attribute is also specified on the PAGE element of the page a LINK points to, it will take precedence over the value specified on the LINK itself.

The minimum required height for modal dialogs can be configured using the property modal.dialogs.minimum.height that is located in the ApplicationConfiguration.properties file.

Controlling Modal Dialogs from custom JavaScript

Modal Dialogs can be controlled by custom JavaScript using the provided curam.util.UimDialog API. For details see the full API documentation in HTML format, accessible by opening <cdej-dir>\doc\JavaScript\index.html in a Web browser.

Loading custom non-UIM pages in a Modal Dialog

Custom non-UIM pages must hook into a specific set of API functions in order to work correctly in a Modal Dialog. These functions are provided by the curam.util.Dialog API. The details are available in the full API documentation: <cdej-dir>\doc\JavaScript\index.html.