Add External Help to the Application

Call an external web-page as Help for pages in the application.

Elements

Ø  External web-pages from Help documents

Ø  Resource Bundle

Ø  adf-settings.xml file

Ø  Java Class

o   extends the ResourceBundleHelpProvider

Resource Bundle

Create a properties file that contains value-pairs, the topic ID and help text for each help topic. The topic ID must be made up of the following parts:

Ø  Prefix

o   Any prefix that will identify this application help

Ø  Name

o   Must be unique

Ø  Help Type

o   _DEFINITION

o   _INSTRUCTION

For example, a topic ID might be PASYS_HOMEPAGE_DEFINITION.

The Resource Bundle holds the value pairs

1.       Help Topic

a.       Help topic will have a suffix of _DEFINITION

2.       Help Text

a.       This appears when you mouse over the help icon

PASYS_HOMEPAGE_DEFINITION=  Apportionment Sub-System Home Page, Press for Help

Adf-settings.xml

Create the file ADF-Settings.xml under Application Resources \Descriptors\ADF-WEB-INF if it does not already exist

Register the resource bundle created in the previous step as a help provider in the adf-settings.xml file

<?xml version="1.0" encoding="windows-1252" ?>

<adf-settings xmlns="http://xmlns.oracle.com/adf/settings"

              xmlns:wap="http://xmlns.oracle.com/adf/settings/share/http/config">

<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">

  <help-provider prefix = "PASYS_HELP_">

    <help-provider-class>view.help.PasysHelpProvider</help-provider-class>

    <property>

      <property-name>baseName</property-name>

      <value>view.resources.ViewControllerBundle</value>

    </property>

  </help-provider>

</adf-faces-config>

</adf-settings>

The Above code assumes

Ø  PASYS_HELP_ as the Help-Provider prefix

Ø  view.resources.ViewControllerBundle is the Help “Resource Bundle”

Java Class

Create a Java Class

Ø  Name

o   PasysHelpProvider

Ø  Package

o   View.help

Ø  Extends

o   ResourceBundleHelpProvider

Add Help to Pages

Create a value pair in the properties file for each page to add Help

Ø  Help Topic

o   Include suffix _DEFINITION

Ø  Help Text

Add the Help Topic to the HelpTopicId of the component to contain the Help link

The HelpTopicId is the first value (Help Topic) in the pair minus the _DEFINITION e.g. PASYS_HELP_HOMEPAGE (from the example above)

The HelptopicId is found under the Appearance tab of the Properties. The topic on the Panel Header in this instance. A help icon will now appear beside the Panel Header Label when the page is invoked

At this point the Help Icon will display the help text only on mouse over when the page is invoked

External URL

To call an external web-page to display the help we must override the super class in our view.help method created above.

The getExternalUrl method currently returns Null all the time, so we override it and we hard-wire in the page we wish to display.

The external web-pages have been created in the help folder at ViewController\Web Content

The address is then /pasys/faces/help/ where pasys is the Java EE web-context root

package view.help;

import javax.faces.component.UIComponent;

import javax.faces.context.FacesContext;

import oracle.adf.view.rich.help.ResourceBundleHelpProvider;

public class PasysHelpProvider extends ResourceBundleHelpProvider {

  public PasysHelpProvider() {}

  private String PASYS_HOME_PAGE = "/pasys/faces/help/HomePage.htm";

       @Override

      protected String getExternalUrl(FacesContext context, UIComponent component, String topicId)

      {

      if (topicId == null)

       return null;

      if (topicId.contains ("PASYS_HELP_HOMEPAGE"))

         return PASYS_HOME_PAGE;

      return null;                                 

          }

      }

For every help-page we add a private string and an “if statement” as shown above for the Home Page.

We use the “contains” suffix to ensure we capture the help topic correctly.

To display the Help Page press the Help icon, the external page will be displayed in a separate window.