ADF help provider link per fragment

Requirement

In my current ADF project we need to offer a help page for every single fragment to the end user. Here he can check how the view is working and some kind of user documentation in Atlassian Confluence.

So we need an easy way to add URLs to a help page to every fragment and open it like a help window separate to the current application in a browser window.

Solution

ADF offers help providers to add help information to an UI component or add a help URL which fits exactly our requirement.

Both possibilities base on special resource bundle entries with a specific prefix. This prefix needs to be registered in a new ADF descriptor file for every workspace (hint: this one need to be created explicitly – it is not available in a new ADF Fusion Web Application).

This registration file is called adf-settings.xml and needs to be placed in “../workspace/.adf/META-INF/” (next to connections.xml)

<?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="V7HLP_">
      <help-provider-class>de.v7.libs.view.helpprovider.V7HelpProvider</help-provider-class>
      <property>
        <property-name>baseName</property-name>
        <value>de.v7.libs.view.helpprovider.V7HelpProviderResourceBundle</value>
      </property>
    </help-provider>
  </adf-faces-config>
</adf-settings>

Here we register a resource bundle with entries for the help provider. For our use case we only need one entry, which will be filled with different URL content from the java class.

# placeholder to override the URL via the provider class
V7HLP_TOPIC_URL=External URL Hilfe

The java class is called every time a help provider gets fired so we can handle this event in a custom way.

public class V7HelpProvider extends ResourceBundleHelpProvider {
    private ADFLogger log = ADFLogger.createADFLogger(V7HelpProvider.class);

    public V7HelpProvider() {
        super();
    }

    @Override
    protected String getExternalUrl(FacesContext facesContext, UIComponent uIComponent, String topicId) {

        if (topicId == null) {
            return null;
        } else if (uIComponent instanceof RichInputText && topicId.equals("V7HLP_TOPIC_URL")) {
            // on page template is a property "hilfeURL" which is placed in the shortDesc of an inputText
            String url = ((RichInputText) uIComponent).getShortDesc();

            log.info("HELP URL = " + url);

            return url;
        } else {
            return super.getExternalUrl(facesContext, uIComponent, topicId);
        }
    }
}

Integration in pages

To have a single point of edit for each URL I decided to add a page parameter to our base pageTempate which is used by every fragment.

In this template I added an inputText which has the helpTopicId pointing to our resource key in the resource bundle. The inputText holds no real value but only shows the nice help sign from adf as link to open the help “for the input text”. The inputText on the right hand side of the help link is no more part of the page – I moved it out of the end facet of the af:stretchlayout with ‘endWidth=”25px”‘.

In the java class of the help provider I take the shortDesc property of the inputText to read the URL and return this as content of the help provider itself.

...
<f:facet name="top">
  <af:panelStretchLayout id="pt_psl2" startWidth="0px" topHeight="0px" bottomHeight="0px" endWidth="25px" inlineStyle="#{attrs.hilfeColor}">
    <f:facet name="end">
      <af:inputText id="pt_it1" helpTopicId="V7HLP_TOPIC_URL" columns="0" readOnly="true" shortDesc="#{attrs.hilfeURL}"/>
    </f:facet>
    <f:facet name="center">
      <af:facetRef facetName="header"/>
    </f:facet>
  </af:panelStretchLayout>
</f:facet>
...

So we add a (confluence) link and the fragment shows the help icon as link. I also did some minor adjustments so the icon is only visible if hilfeURL not null…

With a single click a separate window opens as help browser window with the content of the URL in parallel.

CLICK –>

Google is always a help 😀