Oracle Apex - Adding Tabular Form Help

Introduction

If you use Oracle APEX I'm sure you like the pop-up help text that you can assign each of your region items. It's part an items configuration, just ensure the UI template "Option with Help" is selected, scroll down to Help Text box and type it in. (Simple)

That's all great, but when I recently found I needed to use a Tabular Form (which is a like an editable report) I went to the column definitions, scrolled to the bottom of the config page, but found it didn't have anywhere to enter help.

Tabular Form Column Help

In the past it's not been a big deal, nobody really asked for it, and you could always add extra stuff to the Page Help,.. but it's not ideal. For this tabular form I needed to be able to explain what the columns were used for because the heading title doesn't do a good job of describing it.

I remembered the method I came up with for Region Help, and figured I'd have a go at adapting this for the column titles. I particular liked this idea because it kept things simple. It uses dummy items to hold the help text which means the help also gets added to the page help without any extra work.

Here's my tabular form:-

My APEX Tabular Form

So lets get right into it using our example above which was on page number 30...

1. Create four Display Only items and ensure you have the 'Optional with Help' UI template selected:

• P30_MEASURE_HELP with label "Measure Column",
• P30_WEIGHTING_HELP with label "Weighting Column",
• P30_CAP_HELP with label "Cap Column",
• P30_UPLIFT_HELP with label "Uplift Column".

    (NB. the label defines how it will look in the page help)
 
2. For each set the help text (as you would for a normal region item).

3. Run the page and you will see these extra item labels showing on your screen, don't panic, this is only temporary. If you have Firebug installed, right click the label and select Inspect Element.

(Which ever browser you use find a way to see to the link html.)

4. Copy the html to your clipboard and paste it into a text editor. It will look similar to this..

<a class="optional-w-help" tabindex="999" href="javascript:popupFieldHelp('2859011741903715','641282443145')">Uplift Column</a>

5. There are two numbers here that are passed to the popupFieldHelp() function, the first one is the help unique id. The second number is your session id which we need to replace so it always shows the current session number. Delete the second number and enter '&APP_SESSION', then remove the word 'Column' from the link text.

The line should now read...

<a class="optional-w-help" tabindex="999" href="javascript:popupFieldHelp('2859011741903715','&APP_SESSION.')">Uplift</a>

6. Now edit the page, right click the report and select 'Edit Report Attributes'.

The completed changes to the report headings

7. Paste your html into the correct heading, and then repeat for the other three items.

8. Finally re-edit your help items and set them to 'Hidden'.

That's it, you're done. Now when you hover your mouse over the titles the '?' appear. All that remains is to click them all to make sure it works.

Oracle Apex - Adding Region Help

Oracle APEX Help Text

Occasionally at work I build systems using Oracle's Application Express and I find I have to stop the web developer within me from going overboard and solving problems in a non APEX way. We had just completed a new system for managing customer discounts and had asked the system owner to come up with field and page help for the application. After a few days we received a spreadsheet full of descriptions and help for most of the pages, but to my surprise they'd included region help. The latter being something that isn't currently implemented in vanilla APEX.

Just to explain a little for those not conversant in APEX, systems are built from a number of pages, and each page can be essentially a report or form. You can have a mix of these by using regions, but as everything must be in a region anyway it's really a case of adding extra regions. Additionally it can be beneficial to split forms across multiple regions to aid clarity or group by function. The following example shows percentage fields used to capture discount percentages for a customer.

Standard Form Region in APEX.

Item help has already been added to this region and this can be seen by clicking one of the labels. This runs a JQuery function called 'popupFieldHelp' and generates a fancy popup like this example.

Item Help Example.

So far all perfectly normal, there's nothing new here!

Additionally these items appear on the Page Help, grouped together under a section title that matches their region title.

What About Region Help?

So everything was great until we were asked for a region help, but as the requirement was valid I couldn't just discard the idea. But I didn't want to write custom JQuery code because my non-developer colleague may need to update it, and I also wanted it to appear in the page help. Here's what I came up with...

1. Add a 'Display Only' page item to your region and choose a sensible name.

(In our example this will be 'P19_ADDITIONAL_DISCOUNTS_HELP').

2. Set the Label text to reference the region name, to be shown in the page help.

(I used 'Additional Discounts Region' for my label.)

3. Add the help text to the item in the normal way entering your region help text.

4. Move the item so that it is first in the region and run the page.

5. Test your new help text by clicking on the item label, then right click it and copy the link code.

(nb. In Firefox this is 'Copy Link Location' and in Internet Explorer it is 'Copy Shortcut'.)

6. Paste the link code into Notepad (or similar) and you should have something like this..

javascript:popupFieldHelp('3439324541165905','112943106205802')

(nb. The first number is your item number, the second is the session number)

7. Edit the region and alter the title to..

<a class="uHelpLink" href="javascript:popupFieldHelp ('xxxxxxxxx','&APP_SESSION.')">Additional Discounts</a>

Where xxxxxxxxx is your item number that we found in the previous stage.

8. Save and run the page and your title will now show as a link (see image below).

Region Help Linked To Region Title.

9. Click the title link and check it works.

10. Finally edit the page again and set the item to 'Hidden' so that it's label no longer shows in the region.

(nb. The item help box will now be hidden when editing the item, but it's still there and available to page and item popup help functions.)

---

Update, 20/01/2015 Method adapted for tabular form columns.