6.4 Creating Dialog Pages

Oracle APEX includes support for modal and non-modal dialog pages. Modal and non-modal dialog pages are only supported if the current application theme contains at least one page template of template type Dialog Page.

• About Supported Dialogs
  When you create a new page, the wizard prompts you to select a Page Mode. The Page Mode determines if the page is a normal application page or a dialog page.
• Creating a Dialog Page Template
  Create a dialog template if your theme does not include one and how to edit dialog template attributes to change the display.
• Editing a Dialog Page in Page Designer
  Change how a dialog page displays by editing attributes in Page Designer.
• Generating a Cancel Dialog Dynamic Action on the Dialog Page
  For dialog pages that contain a Cancel button, create a dynamic action that controls what happens when the button is clicked.
• Generating a Close Dialog Page Process on the Dialog Page
  Close a dialog page by creating a Close Dialog page process.
• About Branching with Dialog Pages
  Open dialog pages using buttons or links.
• Handling Refresh Actions on Parent Page
  Learn about handling refresh actions on parent pages.

6.4.1 About Supported Dialogs

When you create a new page, the wizard prompts you to select a Page Mode. The Page Mode determines if the page is a normal application page or a dialog page.

Oracle APEX supports two types of dialog pages:

• Modal Dialog - A modal dialog is an overlay window positioned within the same browser window. A modal dialog remains active and focused until the user has finished with it and closes it. While a modal dialog is active, the user is unable to interact with the rest of the page until the dialog is closed.
• Non-modal Dialog - A non-modal dialog displays a separate popup browser window. A user can interact with a non-modal dialog and content on the page. Use a non-modal dialog when the requested information is not essential to continue. This type of window can be left open while work continues elsewhere.

Oracle APEX includes dialog page templates in the Universal Theme - 42. When you set the Page Mode to either Modal or Non-Modal, APEX automatically uses the default dialog page template.

You can further define the appearance and layout of a dialog by specifying the Dialog Template.

6.4.2 Creating a Dialog Page Template

Create a dialog template if your theme does not include one and how to edit dialog template attributes to change the display.

The dialog page template contains JavaScript function calls that handle the initialization, closure, and cancellation of a dialog page. When you create a dialog page template, you must define these and other Dialog Page Templates attributes.

See Also:

Required Dialog Page Template Attributes

If you are using an existing application and the theme does not contain a dialog page template, then you must create one. While you can create one from scratch, the easiest option is to copy an existing dialog template.

To create a dialog page template:

1. Navigate to the Shared Components, Templates page:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Click Shared Components.
   4. Under User Interface, select Templates.
2. Click Create.
3. In the Create Template Wizard:.
   1. Template Type - Select Page and click Next.
   2. Creation Method - Select As a Copy of an Existing Template and click Next.
   3. Copy From - Select the application to copy from and click Next.
   4. Identify Theme - Select the theme you are copying from and the theme you are copying to and click Next.
   5. New Templates - Locate the Modal Dialog templates to copy (for example, Drawer, Modal Dialog, or Wizard Modal Dialog) and select Yes.
   6. Select Copy Page Templates.
4. Verify the dialog page template is active in the current theme

See Also:

Selecting a Default Page Template

6.4.3 Editing a Dialog Page in Page Designer

Change how a dialog page displays by editing attributes in Page Designer.

To edit a dialog page in Page Designer:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears. Attributes are organized in groups.
2. In Page Designer locate the Appearance group.
3. Appearance, Page Mode - Select one of the following:
   • Modal Dialog - The page is presented as a modal dialog. A modal dialog is an overlay window positioned within the viewport, which remains active and focused until the end user dismisses (or closes) it. The underlying page is grayed out and the end user is prevented from interacting with the rest of the page until the dialog is closed.
   • Non-Modal Dialog - The page is presented as a non-modal dialog. A non-modal dialog is an overlay window positioned within the viewport, where the end user can interact with the dialog, and content on the page that launched the dialog. A non-modal dialog can be used when the requested information is not essential to continue; work can continue elsewhere while the window is still open.

   Note that options Modal and Non-Modal Dialog will only be available for selection when the current application theme contains a default Dialog Page Template.

4. Appearance, Dialog Template - Select a dialog template to define the appearance and layout of this page. Making a selection here overrides the default dialog template.

   Options include:

   • Theme Default
   • Drawer
   • Modal Dialog
   • Wizard Modal Dialog

   Dialog templates are defined in the application theme. When a dialog page is created, the template is automatically set to Theme Default which renders the page using the default page template defined in the current theme.

5. Edit the remaining attributes in Appearance group as needed.

   To learn more about an attribute, see field-level Help.

6. Under Dialog, edit the appropriate attributes:
   1. Width - Enter the width of the dialog, in pixels or a percentage.
      The substitution string #DIALOG_WIDTH# in the dialog initialization code of the page template is replaced with the value entered in this item. For a page using a Desktop user interface, the value is set in pixels, such as 500.
   2. Height - Enter the height of the dialog, in pixels, for example, 500.
      The substitution string #DIALOG_HEIGHT# in the dialog initialization code of the page template is replaced with the value entered.
   3. Maximum Width - Enter the maximum width of the dialog in pixels.
      The substitution string #DIALOG_MAX_WIDTH# in the dialog initialization code of the page template is replaced with the value entered in this item.
   4. Attributes - Dialog support varies depending on the user interface of the page. A subset of dialog attributes are declaratively supported: height, width, and maximum width.
      To define any additional attributes for the dialog, enter the name/value pairings in a comma separated list. The substitution string #DIALOG_ATTRIBUTES# in the dialog initialization code defined at page template level, is replaced by any value(s) entered in this item.
   5. CSS Classes - Enter classes to add to this component. You may add multiple classes by separating them with spaces.
   6. Chained - Select On if this dialog is opened by another dialog, and should reuse the same dialog window.
      For example, if this dialog is part of a multiple page dialog wizard, and you wish to reuse the dialog window for each step of the wizard. Select Off if this dialog is opened by another dialog and should be opened in a new dialog window. For example, when this dialog is modal, and you wish to open it within a parent modal dialog window.
7. To save your changes, click Save.

6.4.4 Generating a Cancel Dialog Dynamic Action on the Dialog Page

For dialog pages that contain a Cancel button, create a dynamic action that controls what happens when the button is clicked.

The dynamic action must have True Action event which is set to Cancel Dialog. This dynamic action will use the cancellation JavaScript call contained in the page template (apex.navigation.dialog.cancel) to handle the canceling the dialog.

See Also:

Managing Dynamic Actions

6.4.5 Generating a Close Dialog Page Process on the Dialog Page

Close a dialog page by creating a Close Dialog page process.

In previous releases, this Close Dialog page processes were referred to as a Close Popup Window. This dialog will use the closure JavaScript call contained in the page template (apex.navigation.dialog.close), to handle the closing of the dialog. The page process also supports the return of dialog page items, which you may wish to reference on the parent page.

Tip:

You can also close a dialog page with the Close Dialog dynamic action. Both the dynamic action and the process support returning dialog page items. Use the page process when the page needs to be submitted and use the dynamic action when the page does not need to be submitted. Both end up calling the closure JavaScript call. Alternatively, you can create a page branch, which will close a dialog page and redirect to the page specified in the branch.

See Also:

• Understanding Page Processes
• Controlling Navigation Using Branches

6.4.6 About Branching with Dialog Pages

Open dialog pages using buttons or links.

Dialog pages support the following branching options:

• Dialog page to dialog page.

  You can branch from one dialog page to another dialog page if:

  • Both pages have the same Page Mode. For example, a Modal Dialog page and a page where the dialog Chained attribute is set to On. Setting the Chained attribute to On enables support for chained or nested dialogs such as the dialogs that appear in many internal APEX wizards. Chained or nested dialogs enable you to re-use a dialog window to display each page.
• Dialog page to Normal page.
  • When branching from a dialog page to a normal page, the dialog page is closed and the user navigates to a new page in the browser. The new page can be a parent (or launching) page or another Normal page in an application.

6.4.7 Handling Refresh Actions on Parent Page

Learn about handling refresh actions on parent pages.

If you have generated a Close Dialog page process on the dialog page, you must implement refresh actions on the parent page using the new Dialog Closed dynamic action event type. You can use the set type Dialog Return Item when creating a Set Value True Action, to set a single value, based on the return item of a dialog.

Tip:

For a partial page refresh of a parent page, implement the close dialog with dynamic action (for example, for report and form pages where you want to edit data in a modal dialog form and only want the report refreshed on close). In contrast, branching is the best approach if you have a multi-step modal wizard or if you have several possible target pages when closing the dialog.

See Also:

Managing Dynamic Actions