ADF Faces RC – displaying user help

ADF Faces RC under JDeveloper 11g supports different mechanisms for displaying runtime help to users linked with an on-screen component. I had a chance to play with this today and (once again) thought I'd document my findings here as I found the Oracle documentation somewhat confusing (or maybe it's just me).

The Oracle documentation that describes how to get this working can be found in section 16.5 Displaying Help for Components of the Oracle JDev 11g Fusion Web Developer's Guide. It's worth noting you should read the entire section 16 Displaying Tips, Messages, and Help as there are a few assumptions in section 16.5 that you've read the earlier parts.

Help types

A subset of the ADF Faces RC components include support for displaying help, through the inclusion of the helpTopicId attribute on the component's tag.

ADF Faces RC provides for 3 different help types for the components that support help:

· Definition – places a question mark icon near the component which when the user hovers the mouse over the component, help text is displayed. The exact location of the question mark icon relative to the component depends on the type of component. Section 16.5 of the Oracle documentation dictates this.


· Instructions – typically displays a note window (that looks like a speech bubble) over the component when the user clicks in the field, where the note window shows the help text. For panel headers and query object components the help text appears inline with the component rather than as a note window.


· External URL – displays a similar question mark icon to the "Definition" help type above, except when the user clicks on the icon (rather than hovers over the icon with the mouse pointer), launches a separate browser window opening an external URL.


Providing Definition or Instructions based help

The setup for providing either Definition or Instructions based help is as follows:

1. Within your ViewController project create a Java class that extends oracle.adf.view.rich.help.ResourceBundleHelpProvider. In the following example I've created the class MyHelpProvider under the package view.help


2. We next need to create the file adf-settings.xml to configure the custom ResoureBundleHelpProvider. This file is meant to go under the ADF META-INF node in the Application Resources options within the Application Navigator:


Unfortunately I can't find an easy way to create this file under this node. The easiest way seems to be to locate the <app_dir>\.adf\META-INF directory under Windows explorer or similar, and manually create the XML file in there. Once done return to JDeveloper and restart it. On JDeveloper reopening you should see the file added as per above.

(The Oracle documentation is incorrect in instructing you to create the adf-settings.xml file under the ViewController's META-INF directory. It should be the <app_dir>\.adf\META-INF directory as specified above).

The contents of the adf-settings.xml file are as follows:


Note the help-provider-class mapping that points to the package.name of our Java class, namely view.help.MyHelpProvider.

The <property>'s tags define the resource properties file that contain our help text to display for each help-enabled component. In this example I've created a file helpFile.properties (the extension is dropped in the adf-settings.xml file) in the view.resources package. We'll look at this next. The property-name as far as I can tell can be anything you want and has no effect elsewher. I'm not entirely sure why it's included; presumably it's possible to have multiple resource files?

3. The contents of helpFile.properties file are as follows:


As you can see in the properties file we have key-value pairs, specifically the help ID and the associated text. Of special note, see that each key is either completed with the word DEFINITION or INSTRUCTIONS. It is this that determines the help type for the component. (Somewhat confusingly INSTRUCTIONS is a plural, and DEFINTION is singular)

4. Finally we need to bind the help key from the properties file to the actual ADF Faces RC component on a web page:


Note for the 2 input text controls above the helpTopicId parameter. Note how these map back to what I had in the properties file minus the DEFINITION or INSTRUCTIONS suffix. Those suffixes are only included in the properties file. As such the properties file determines the behaviour of the help and components in this case.

Providing External URL based help

To configure the external URL help type we return to our custom MyHelpProvider class and override the super getExternalUrl method as follows:


In the 2nd if statement we've added the ability to capture the helpTopicId and return an alternative URL which will be used for the new browser window. As you add more components that require help, you simply add more if statements with associated URLs.

Further functionality

If you wish to configure multiple helper classes the adf-settings.xml file allows you to include a filter via the prefix attribute on the help-provider tag as follows:


In this case only helpTopicIds with the prefix MYHELP_ will be passed to the MyHelpProvider class.

In addition the Oracle documentation specifies how to use a managed bean help file, which is relatively simple, or XLIFF based help files. I don't have any experience with XLIFF files so I'll leave readers to read the Oracle documentation.

Credit

Thanks to user518058 and Frank Nimphius on the JDev OTN Forums for posting about a couple of the implementation issues with the user-help.