Home > Uncategorized > Working with APEX 5 Dialogs

Working with APEX 5 Dialogs

APEX 5 introduces native dialogs, both modal and non-modal. This article discusses:

  1. How to enable dialogs in your APEX 5 application if they are not already enabled.
  2. How to open a dialog.
  3. How to close a dialog, returning values from that dialog.
  4. How to respond to the closing of a dialog.

How to enable dialogs in your APEX 5+ application if they are not already enabled.

To check if Dialogs are already usable within your Application, start the Create New Page wizard and see if you can specify a Page Mode value of “Modal Dialog”. If you can then great, you don’t need to complete the steps in this section.

If you can’t, follow the steps below to enable the use of Dialogs.

NOTE: You won’t need to perform these steps if you’re using the Universal Theme. However, it is not necessary to be using the Universal Theme to use APEX’s native dialogs.

dialogs1

Above: If you can select Modal Dialog from the Page Mode select list then you do not need to complete the steps in this section.

Enabling APEX 5 native dialogs in your application

  1. Firstly, you need a Page Template which will be used as your Default Page Template for Dialogs. Within Application > Shared Components > Templates locate a suitable Page Template which already exists. You want to choose a Page Template which contains none of the components which would not be suitable for a dialog e.g. tabs, nav bar etc..
  2. Make a copy of this Page Template, calling the newly-created copy something like “Dialog Page”.
  3. Set the Template Type of this new Page Template to “Dialog Page”.dialogs2
  4. When you try to save the the new Page Template you may see errors such as the following:dialogs3To rectify these, locate the three fields mentioned and paste in the default values shown for each, as shown below.dialogs4
  5. Navigate to Shared Components > Themes. Open the the current theme for your application.
  6. Navigate to “Dialog Defaults” and select your newly-created Page Template from the Dialog Page select list. Click Apply Changes.dialogs5
  7. You should now be able to create new pages specifying their Page Mode as “Modal Dialog” or “Non-Modal Dialog”. You should also be able to modify the Page Mode of existing pages to turn them into dialog pages.

For more information about Dialog Templates in APEX 5:
http://docs.oracle.com/cd/E59726_01/doc.50/e39147/bldapp_pg.htm#HTMDB30099

How to open a Dialog

There are a couple of ways of opening a dialog page in APEX 5+.

THE SIMPLE WAY THAT YOU DON’T HAVE MUCH CONTROL OVER BUT WILL BE PERFECTLY SUFFICIENT AND QUICKER TO PUT IN PLACE IN MOST CASES

The simplest way is to use any of APEX’s built in methods of generating navigation.

For example, setting the action of a Region Button to “Redirect to Page in this Application” and choosing a Dialog Page.

THE MANUAL WAY THAT YOU HAVE MORE CONTROL OVER BUT TAKES A BIT LONGER

Alternatively, if you need to open a dialog using Javascript, you can use the following method:

a) Create a hidden page item which is going to hold the prepared URL of the dialog page you want to open. e.g. P35_DIALOG_URL

b) Populate this item with an on load pl/sql page process:

:P35_DIALOG_URL := APEX_UTIL.prepare_url(
p_url=>’f?p=400:38:&SESSION.::NO:RP::’
, p_triggering_element => ‘$(”#openDialogIcon”)’
);

The first argument passed to APEX_UTIL.prepare _url here is easy: it’s the URL of the dialog page.

The second argument, p_triggering_element, is a string representing a jQuery object which will be identified as the Triggering Element which opened the dialog.

Note that you must use $(‘#someitemid’) and NOT $(“#someitemid”) (i.e. single quotes instead of double quotes to surround the selector string).

The jQuery object you specify here is important as it’s the item against which the apexafterclosedialog Javascript Event will be registered. You can see an example of this later in this article.

This call to APEX_UTIL.prepare_url will return a string of the following form:

javascript:apex.navigation.dialog(‘f?p=400:38:995688545561::NO:RP::\u0026p_dialog_cs=BA6YtuVKy9_VwUU3hN7x1vcfehc’,{title:’Select desired Item from List’,height:’600′,width:’700′,maxWidth:’false’,modal:true,dialog:null},”,$(‘#openDialogIcon’));

c) Create an On Page Load Dynamic Action with a Javascript action to assign this Prepared URL with an tag’s HREF attribute. E.g.:

// Wrap an tag around the icon which opens the Select Item dialog.
// Set the href of this new tag to be the URL
// javascript:apex.navigation.dialog(…) style value required to open
// the dialog.
$(“#openDialogIcon”).wrap( ‘<a href=”‘ + $(“#P35_DIALOG_URL”).val() + ‘”></a>’ );

How to close a dialog, returning values from that dialog.

1) You can close a Modal Dialog in one of three ways:

a) A Close Dialog Page Process (submit the page to fire this as you would any other Page Process).

b) A Close Dialog Dynamic Action

c) Call Javascript of this form:

apex.navigation.dialog.close(true,[“P38_SELECTED_ITEM_ID”,”P38_SELECTED_ITEM_NAME”])

Where the first parameter (true) indicates whether the dialog is modal or not and the second parameter is an array of items in the dialog whose values should be available in the parent once the dialog has closed.

See https://docs.oracle.com/cd/E59726_01/doc.50/e39149/javascript_api.htm#AEAPI30096 for more details on this Javascript function (i.e. apex.navigation.dialog.close).

2) The important concept, regardless of which of the above 3 methods you choose to close your Dialog, is the Items to Return value. This is the correct way to pass back items to the calling/parent page.

As John Synders points out here (http://hardlikesoftware.com/weblog/2015/05/22/apex-5-0-dialogs/):

John Synders on the philosophy behind dialogs:
“The normal pattern for using dialogs is that it is OK for the calling or parent page to know about the dialog page, but not the other way around. The dialog should not know the context from which it is used. If a dialog page knows about the page it is called from then it limits how the dialog can be reused. This is not APEX specific; it is a common UI framework pattern but is often ignored in web apps. This means that if you are trying to take data entered in a dialog and insert or use it in the parent page, this should be done from event handlers or dynamic actions on the parent page not from code on the dialog page. You should not try to use JavaScript on the dialog page to try to manipulate the parent page.”

For example, using the Close Dialog Pager Process method (method “a”), you can set a comma separated list of items to return:

dialogs6

You may think “that’s all well and good in theory but I’m going to ignore this ideology and, in direct contravention of the above advice from John Synders, I’m going to use JavaScript on the dialog page to manipulate the parent page, just because it’s what I know and I’m not really bothered about reusing my dialog. I can just use something like parent.$(“#P100_SOME_ITEM”).val( ’some val from dialog’ ) to reference the parent and the job’s done.”

If you’re only using one level of dialogs (i.e. not a nested dialog) you can do this if you really want to and are happy to ignore the point about reusability of the dialog. However, If you are within a nested dialog (i.e. a dialog opened from another dialog) you’ll have problems with this since parent  will refer to the top level page and NOT the parent dialog. Search the John Synders article referenced above for the term “top level” to see why it’s built this way i.e. why all dialogs, nested or otherwise, are created in the parent page.

My advice would be NOT to do this in any case. Stick to the principle that the Dialog should not know about its caller.

How to respond to the closing of a dialog

So, great, now we have a means to close a dialog and specify which of the items in the dialog we wish to be available in the parent/calling window. The question then is: How do we get access to those values in the calling/parent window?

Again, we have a couple of options.

OPTION 1: Use Dynamic Actions

Create a Dynamic action with “Event Dialog Closed” as in the screenshot below. Note that the value for Selection Type is very important. If this is wrong, this will not work. This needs to be the item that triggered the opening of the dialog i.e. the Triggering Element.

dialogs7

Add one or more true actions to it of type “Set Value”, choosing a Set Type of Dialog Return Item. (In our example Page 35 is the parent page and page 38 is the dialog):

dialogs8

Option 2: Do it all manually with Javascript (who doesn’t like to have more control?)

For this option just create an On Page Load Dynamic Action with a Javascript Action as follows:

 

$(“#openDialogIcon”).on(“apexafterclosedialog”,function(e,data){

// the data parameter will be set to an object containing the values passed back from the closed dialog (“The Return Items”)

// e.g.:

// { P38_ITEM_ID: “1234”, P38_ITEM_NAME: “ACME WIDGET”, dialogPageId: 38 }

apex.item(“P35_ITEM_ID”).setValue( data.P38_SELECTED_ITEM_ID );

apex.item(“P35_ITEM_NAME”).setValue( data.P38_SELECTED_ITEM_NAME);

});

 

Again, note that the value of #openDialogIcon is very important. To repeat: This is the element that was indicated as the trigger for the opening of the dialog.

 

Related articles

Details of apex.navigation Javascript API

https://docs.oracle.com/cd/E59726_01/doc.50/e39149/javascript_api.htm#AEAPI30096

John Synders on Modal Dialogs in APEX 5

http://hardlikesoftware.com/weblog/2015/05/22/apex-5-0-dialogs/

Dialog Templates in APEX 5 (Oracle Documentation)

http://docs.oracle.com/cd/E59726_01/doc.50/e39147/bldapp_pg.htm#HTMDB30099

Advertisements
Categories: Uncategorized
  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: