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 this post I’ll show how to set up a specific page to be the landing page for showing help text for any page in the application. It is the precursor to the next post where I’ll take it a step further and 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 using another page
The following information is to a large extent a click stream version of Oracles official documentation.
The number in the parenthesis are example page numbers just to make sure there is no confusion of what page is referenced. It is the page numbers you’d end up with in a brand new application
Set up two pages
Create a blank page (2) and then add a help text region to the content body of the page. This is the page that will be used to display the help for any page in the application.
Create another blank page (3) and scroll down to the bottom and fill in help text about the page in the “Help Text” property.
Now we have everything needed in place, we just have to add any means of navigation to get the help page (2) to be loaded with the help text of this page (3). Typically this is done with a link in the navigation bar as we’ll see later, but it is often easier to just try out navigation with a plain button.
Add a button and label it “OtherPage”. Set the target to be the page number of the help page you just created (2). Set the request (in 5.1 under the advanced category) to “&APP_PAGE_ID.”.
Run the page (3) and click the button. You will be sent to your help page (2) where the help text you entered for the page (3).
If you add items on your page (3) the help text for those will also be shown on your help page. You will however not want to create a help button on every page in your application. It would both wast real estate on your page as well as time to set it up on every single page.
To make the help for every page in your application be displayed with no additional work per page other than writing the help text, let’s set up an entry on the navigation bar.
Go to shared components and clock on Navigation Bar List, and then on Desktop Navigation Bar. Click Create Entry and set:
- Sequence = 20
- List Entry Label = Help Page
- Target Type = Page in this Application
- Page = Your help page (2)
- Request = &APP_PAGE_ID.
If you run the application now you will see “Help Page” up in the navigation bar, and clicking it takes has the same exact result as the button. It navigates to he help page (3) and shows the help text for your page (2).
Now any new page you create for which you write help text will let the user clock on the navigation bar and get the help text with no extra effort from you.
Watch it live
I have just 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.