Setting up help text in APEX is not hard but I often see it not done at all or implemented using regions with static content and then toggled on or off. That is unfortunate when there is declarative support for providing help texts.

In the last post I show 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 inline with a page the user is on.

For this blog I used version 5.1.4.00.08 of APEX on apex.oracle.com. The following has been the same since at least release 3.2 of Apex while where and how you enter the needed properties may not be identical in previous and future releases. I don’t think it has changed much over the years.

Show help in-line

It is often preferable to be able to see the help on the page you want to know how it works. If you have it on another page like I showed in the last post, you often end up going there reading a bit and then go back to look only to repeat that a number of times.

What if you could see the help on the page you’re on? Sometimes that is much better.

Setting up the global page

The basis for this is using the global page to have a help region be available on every page in the application (unless you restrict it).

Create a global page if you do not have one in your application. Then add a “help text region” to the Content body of the global page. Name it “Info” and a sequence of 0 to make sure it is the very first region in the content body.

If you run the application now, every page shows the help text for its page. So it is already working, but we want the user to select when it is to be displayed.

We will use a page item to define when the help is shown and when it is not.

Creating the page item

Lets create a page item “AI_SHOW_HELP” to let us control when help is shown.

Go to the shared objects:

• Click on “Shared Components”.
• Click on “Application Items”.
• Click Create
• Name = AI_SHOW_HELP
• Session State Protection = Checksum Required – Session Level
• Click Create Applöication Item

Set default value for AI_SHOW_HELP

To make sure the application shows with help not being displayed, we’ll set up an application computation to default the application item to N.

• Click on “Shared Components”.
• Click on “Application Computations”.
• Click Create
• Computation Item = AI_SHOW_HELP
• Computation Point = On New Instance (New Session)
• Computation Type = Static Assignment
• Computation = N
• Click Create Computation

Set a condition for when to show the help text region

With the Application Item in place and defaulting it to not show help, we just need to set the condition on the help text region on the global page to only show when AI_SHOW_HELP has a value different from N. To make sure it is only shown when we have requested it, we check for it being Y rather than just not being N.

• Open the global page in the page designer (editing the page)
• Click on the help text region (named Info above)
• Scroll down to  Server Side Condition group among the regions properties
• Type = “Item = Value”
• Item = AI_SHOW_HELP
• Value = Y
• Click Save

If you now run the application, the help will no longer show on any of your pages. The reason is of course that we default AI_SHOW_HELP to “N” while only showing the help text when it is set to “Y” without any means to set it to “Y”.

What we need now is a way for the user to toggle AI_SHOW_HELP between “Y” and “N”

Navigation bar entry to toggle help on or off

The way to create a toggle in the navigation bar is to have two entries and only show the one the reverses the current selection, i.e. if AI_SHOW_HELP is “Y” then let it be “N” and vice versa.

Head back to shared components and click on “Navigation Bar List”, and click on “Navigation Bar List” in the report to go to editing the entries in the navigation bar.

• Click “Create Entry”
• Sequence = 30
• List Entry Label = Show Help
• Target Type = Page in this Application
• Target = &APP_PAGE_ID.
• Set these items = AI_SHOW_HELP
• With these values = Y
• Conditions = Value of Item/Column in Expression 1 is != Expression 2
• Expression 1 = AI_SHOW_HELP
• Expression 2 = Y
• Click Create List Entry

Now we have a navigation bar entry (high up right where the logout link is) that toggles help on and that is only shown when help is not shown.

Run the application and click “Show Help” in the navigation bar to see the inline help being visible again. There is then – yet – no means to turn off the help.

Now that it works we need to create one more entry that does the reverse. It is shown when help is visible to allow the user to hide the help again.

Return to the edit window and let’s set up a reverse navigation bar entry of the one we just created.

The easy way to do it is to click the copy icon on the right side on the row for “Show Help”. Do that and enter the following values.

• Sequence = 40
• New List Entry Label = Hide Help
• Click Copy List Entry

Now lets edit the few things we need.

• Click “Hide Help” in the report over navigation bar entries.
• In Target section, set “With these values” = N
• In Conditions, set “Expression 2” = N
• Click Apply Changes

That is it, the application now has a toggle between Show Help and Hide Help to toggle showing help about pages inline in the application. Note that it is an application wide setting, so once on it remains active until the user turns it off. Thus, if you turn it on and move around in the application, the help will show on every page until you decide to turn it off and not show help anymore.

Watch it live

As I said in the last post I have set up a demo-app I’ll use to show the effects when I blog about things APEX where it makes sense to have a an app to show the feature. For the above, take a look at it. Log in with demo/demo.