APEX Inline Popups and Dialogs

Note this contains information about a future release of APEX and the final release may differ from what I describe.

I previously described how to create inline popup regions but with the upcoming APEX 19.1 release that should no longer be necessary because the Universal Theme should have a built-in Inline Popup Region. You can try it out already on the APEX Early Adopter site. Here I will provide up to date information on inline popups and dialogs.

APEX has had inline dialog regions since release 5.0 but they were overshadowed by the modal dialog page. I have always felt that inline dialog regions are not used as often as they could or should be. Now with the upcoming 19.1 release I think most of the pieces are in place to make it practical and easy enough to use inline dialogs and the new inline popups.

First a brief description of inline regions and modal dialog pages and the distinctions between them and also what a popup is.

The inline dialog and inline popup regions are like any other region. You create them by choosing the appropriate region template “Inline Dialog” or “Inline Popup”. They are rendered by the server and included as part of the HTML page that is sent to the browser. What makes them special is that they are not initially visible; they are turned into a dialog or popup widget when the page loads. Most normal page templates include a layout position called “Inline Dialogs”. Typically these inline regions are put in that position because it helps to hide them while the page is loading. You need to provide a way for users to open and close these regions with dynamic actions or JavaScript code. Once the region is open the user can interact with the region and form items or sub regions. Changes to page items in the region are not saved until the page is submitted. If needed you can load and save data using dynamic actions or JavaScript code.

The modal dialog page is a complete APEX page that loads in an iframe that is inside a dialog widget. The rendering and processing of the dialog page can leverage the full power of the APEX engine. The dialog is opened with a URL. The URL is actually JavaScript code but you create links to the modal dialog page with the Page Designer link builder or using the APEX_UTIL.PREPARE_URL API just like any other APEX page. The dialog is closed with either a dynamic action (Cancel Dialog or Close Dialog action) or the Close Dialog process.

I previously defined a popup as:

A popup is different from a dialog in these ways: It is always modal, does not have a title bar and cannot be resized or moved. It may have buttons that close it but it also closes when you click or touch outside of it or press the Escape key. It may be positioned near the artifact that caused it to open. Popups are commonly used in mobile apps.

Comparison between inline regions and modal dialog pages.

• Inline Dialog and Inline Popup are APEX page regions.
• Modal Dialog pages are full APEX pages.
• Both modal dialog pages and inline dialog regions are implemented with the jQuery UI dialog widget.
• Inline popup regions are implemented with the APEX popup widget which is derived from jQuery UI dialog.
• An inline dialog region can be modal or non-modal but a dialog page is always modal. A non-modal dialog page is actually a separate browser window. There is no APEX page that is a popup (it makes no sense because popups should be lightweight).
• A submit button in a modal dialog page submits the page (the one in the iframe in the dialog). The parent page remains unchanged.
• A submit button in an inline region submits the page (the dialog content and the parent page are the same page).
• Inline regions open very quickly. This is because they are already rendered on the client; there is no round trip to the server.
• Modal dialog pages are slower to open because they must request the APEX page from the server.
• Modal dialog pages are always opened in the top level APEX window (browsing context) so when they are stacked (Dialog: Chained = No) they can be moved anywhere on the page.
• Inline dialogs and popups are always opened in the window they are in so if you add an inline dialog or popup to a modal dialog page they cannot be moved outside the modal dialog page iframe. This is why the modal dialog page templates don’t include the “Inline Dialogs” page position; inline dialogs are not that useful/user friendly inside modal dialog pages (but it is possible if you really want to do it). There may be added confusion for an inline popup region because clicking outside the popup to close it (regardless of noOverlay setting) only works for clicks in the same iframe. Clicking anywhere outside the iframe does nothing.
• The chained concept does not apply to inline dialogs or popups (because it has to do with how navigating to a new dialog page is handled). However it is possible to implement wizard like behavior in an inline region simply by showing and hiding content as the user “moves” through the wizard.

I wrote about modal dialog pages before and also how to persist size and position and how to pass data in and out.

Here is whats new and planned for 19.1:

• Universal Theme has a new region called Inline Popup as described above.
• Both Inline Dialog and Inline Popup regions have a new template option “Remove Body Padding” that does just that. When the popup or dialog contains a large region such as a chart or interactive grid you probably don’t want the body padding. This removes the need for custom CSS that I had used to remove padding in the IG Cookbook when putting an interactive grid in a dialog.
• The popup widget has a new option (noOverlay) that handles click outside to close without using an overlay. This is exposed as the inline popup region template option Remove Page Overlay. An overlay is what makes the dialog or popup modal and it makes the page “behind” the dialog look dim. It handles any clicks outside the dialog. For a popup the difference between using the overlay or not can be subtle. One thing is that the page is not dim with no overlay. The other is that with no overlay click outside the popup closes it and the click will also activate what it clicks on rather than being eaten by the overlay. Making noOverlay work in the presence of iframes was tricky. This option is motivated by the enhanced Popup LOV that is planned for a future release past 19.1.
• Finally, built-in dynamic actions Open Region and Close Region that will open and close Inline Dialog and Popup regions. People have been asking for this for a long time.
• Bonus: Open Region and Close Region work on collapsible regions as well to expand and collapse them.
• The apex.theme openRegion and closeRegion APIs that I mentioned here are planned to be documented. These APIs implement the Open Region and Close Region dynamic actions.

Before APEX 5.0 some themes included some kind of primitive dialog support and these themes tended to have global functions called openModal and closeModal. These functions were never official parts of the APEX core library and were not officially documented. Universal Theme includes functions with the same name for backward compatibility but they should be considered deprecated. Ever since 5.0 when all our our dialogs switched to use jQuery UI dialog I have recommended to use the dialog open and close methods. For example $("#dialogid").dialog("open"). This is a bit long winded so starting in 18.2 the apex.theme namespace has openRegion and closeRegion functions. These should be documented in 19.1. In addition there are new Dynamic Action actions Open Region and Close Region that are based on these functions.

A nice thing about these new functions (or dynamic actions) is that they work with more than just dialogs (that is why the are not called open/closeDialog). As already mentioned they work with inline dialog, inline popup, and collapsible regions. In fact they should work with any region that is implemented with a jQuery UI widget that supports either the open and close methods or the expand and collapse methods. So if you implement a region plugin or region template that has similar functionality and appropriately named methods it should automatically work with these new dynamic actions and apex.theme functions.

The steps for incorporating an inline dialog or popup are now very simple:

• Add a Static Content (or other type) region to the Inline Dialog page position. You can put
  whatever you like in the region.
• Change the template to Inline Popup or Inline Dialog. Set template options as you like.
• Create a button somewhere on the page to open the dialog or popup.
• Create a dynamic action on the button and use action Open Region, selecting the inline region.
• If you like you can add a button to the inline region to close the dialog or popup. Use the
  Close Region dynamic action for this button.

For this simple case there is no JavaScript required. More advanced topics will have to wait for another time.

We have converted most places in our sample apps to use the new functions to open and close dialogs. Hopefully we will get more examples of using popups and the new dynamic actions to open and close regions. The IG Cookbook has examples of inline dialogs or popups on pages 9, 11, 24, 25, 26, and 29. In addition the Custom Popup item plug-in included in that app works with either inline dialogs or popups. I hope to have an update to the IG Cookbook for 19.1 that uses the new DAs and the built-in inline popup region.

I hope to see more APEX apps using inline dialogs and popups going forward.