To continue on the theme of help text in APEX, let’s take a look at showing it in a modal popup dialog in this post and then finish off the subject in next post with customizing how help can be shown.

For completeness I’ll include a short section towards the end about how it works in non modal too.

In the last post I show how to show help text inline on a page and on the one before that how to set up a specific page to be the landing page for showing help text for any page in the application. In this post I’ll show how to get help text displayed in a modal dialog.

For this blog I used version 5.1.4.00.08 of APEX on apex.oracle.com.

As I’ve stated before, my preferred way to deal with help text in APEX applications is to do it with inline help as the last blog post discussed. But sometimes a dedicated page is preferable and sometimes a modal popup dialog is better. I think those cases might be preferred in cases where the help includes a lot of text and seeing the actual page at the same time is not needed. For example if the text more explains a concept than how to fill out the fields in the page.

We will set up another page with just a help region. We could make a copy of the page we created in the first post in this series, but to make this post more self contained we’ll create the page from scratch.

Creating the modal help page

Create a new blank page (I’ll use 4 in this example). Chose modal page type.

• Add a “Help Text” region to the content body.
• Name = Help
•  If you did not get the page created as modal, go to the page attributes.
  • Find The Appearence group.
  • Page type = Modal Dialog

This is identical to the page 2 created in the post about help on a dedicated page with just the page type changed to be modal.

Create a button to show the modal help

We’ll first create a button just to show the mechanics just because it is the easiest way to test it. After that we’ll finish off the access to help with a navigation bar entry, just as we did in the previous two posts.

Open the page from which you want to open the help. If you’ve followed along on the previous posts, it would be page 3. Any page for which you have some help text defined on the page attributes will do. That is needed just so we can see it work.

• Add a text button to any region you have on the page.
• Set the page to redirect to a page in this application
• Set the page to be page 4
• Open the advanced group in the popup
• Request = &APP_PAGE_ID.

Test the page and see that when you click the button you get a modal popup page with the helptext for the page you button is on.

With this working we know the mechanics of this works, now we just need a navigation bar set up for it so it becomes available across the whole application.

Create a navigation bar entry

As before, we’ll finish off this version too with a navigation bar entry. It is by far the most natural way to provide a natural way for a user to request help on a page and for it to be available everywhere in an application.

Since the difference against the navigation bar entry for the dedicated page is largely that the page that is linked is defined as a normal or modal page, this pretty much a repeat of that.

Go to shared components and click on Navigation Bar List, and then on Desktop Navigation Bar. Click Create Entry and set:

• Sequence = 50
• List Entry Label = Modal Help
• Target Type = Page in this Application
• Page = Your modal help page (4)
• Request = &APP_PAGE_ID.

If you run the application now you will see “Modal Help” up in the navigation bar, and clicking it takes has the same exact result as the button. It shows the help in a modal dialog by pulling up page 4 as a popup over the page your requested help from (3).

Now any new page you create for which you write help text will let the user click on the navigation bar and get the help text with no extra effort from you.

What about non modal?

Well, there is of course the option of a non modal page type too. The result of it is a stand alone window you can move around and keep referencing while navigating in the application.

To set it up we’ll just copy the page, button and navigationb bar entries.

Copy the page we created here (4) to a new one (5) and give it the name “Non Modal Help”, accept all other attributes and just click forward and create the page.

In page attributes:

• Change the page type to  “Non-Modal Dialog”.
• Set width to 700
• Set height to 600

Go to your page in the application (3 if you have followed along) and copy the button “Modal”.

• Name = “NonModal”.
• Sequence = 80.
• Target->Page = 5.

Test it to see your button creating a new window with the helptext.

Go to the shared components -> Navigation Bar List -> Desktop Navigation Bar

• Click copy icon on the right side for “Modal Help”
• Display Sequence = 60
• New List Entry Label = Non Modal Help
• Click “Copy List Entry”
• Click “Non Modal Help”
• Set Target->Page = 5

Now you’ve got a non modal help option in the navigation bar too. Try it out.

Watch it live

Take a minute and check out this live in my demo application to see for yourself the effect of it before you build it yourself. Log in with demo/demo.