Monday, 19 January 2015

Oracle Apex - Adding Tabular Form Help


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.