How to Create Resource Bundle-Based Help

Displaying Tips, Messages, and Help 17-17 Example 17–5 XLIFF Help ?xml version=1.0 encoding=UTF-8 ? xliff version=1.1 xmlns=urn:oasis:names:tc:xliff:document:1.1 file source-language=en original=this datatype=xml body trans-unit id=XLIFF_CREDIT_CARD_DEFINITION sourceCredit Card Definitionsource target noteCredit Card definition text.note trans-unit trans-unit id=XLIFF_CREDIT_CARD_INSTRUCTIONS sourceCredit Card Instructionssource target noteCredit card instruction text.note trans-unit body file xliff 2. Register XLIFF as a help provider in the adf-settings.xml file for information on creating the adf-settings.xml file if one does not exist, see Section A.5.1, How to Configure for ADF Faces in adf-settings.xml . To register the provider, open the adf-settings.xml file and add the following elements: ■ help-provider: Use the prefix attribute to define the prefix that UI components will use to access this help provider. This must be unique in the application, and must match the prefix used in the XLIFF file. ■ help-provider-class: Create as a child element to the help-provider element and enter oracle.adf.view.rich.help.ELHelpProvider. ■ property: Create as a child element to the help-provider element. The property values define the actual help source. ■ property-name: Create as a child element to the property element and enter a name for the help, for example, helpSource. ■ value: Create as a child element to the property element and enter an EL expression that resolves to the XLIFF file, wrapped in the adfBundle EL function, for example, {adfBundle[project1xliff.view.Project1XliffBundle]}. Example 17–6 shows how the XLIFF file in Example 17–5 would be registered in the adf-settings.xml file. Example 17–6 Registering an XLIFF File as a Help Provider adf-settings xmlns=http:xmlns.oracle.comadfsettings adf-faces-config xmlns=http:xmlns.oracle.comadffacessettings help-provider prefix=XLIFF help-provider-class Note: If the prefix attribute is missing, or is empty, then the help provider will be registered as a special default help provider. It will be used to produce help for help topic IDs that cannot be matched with any other help provider. Only one default help provider is permitted. 17-18 Web User Interface Developers Guide for Oracle Application Development Framework oracle.adf.view.rich.help.ELHelpProvider help-provider-class property property-namehelpSourceproperty-name value{adfBundle[project1xliff.view.Project1XliffBundle]}value property help-provider adf-faces-config adf-settings

17.5.3 How to Create Managed Bean Help

To implement managed bean help, create a managed bean that contains a map of strings that will be used as the text in the help. Managed bean help providers use the ELHelpProvider class to deliver the help. To create managed bean help: 1. Create a managed bean that returns a map of strings, each of which is the ID and content for a help topic, as shown in Example 17–7 . Example 17–7 Managed Bean that Returns a Map of Help Text Strings public class ELHelpProviderMapDemo { public ELHelpProviderMapDemo { } To use the ELHelpProvider, the EL expression must point to a Map, otherwise you will get a coerceToType error. public MapString, String getHelpMap { return _HELP_MAP; } static private final MapString, String _HELP_MAP = new HashMapString, String; static { _HELP_MAP.putMAPHELP_CREDIT_CARD_DEFINITION, Map value for credit card definition; _HELP_MAP.putMAPHELP_CREDIT_CARD_INSTRUCTIONS, Map value for credit card instructions; _HELP_MAP.putMAPHELP_SHOPPING_DEFINITION, Map value for shopping definition; _HELP_MAP.putMAPHELP_SHOPPING_INSTRUCTIONS, Map value for shopping instructions; } } The first string must contain the prefix, the topic name, and the help type, for example, MAPHELP_CREDIT_CARD_DEFINITION. In this example, MAPHELP will become the prefix used to access the bean. CREDIT_CARD is the topic name, and DEFINITION is the type of help. The second string is the help text. Displaying Tips, Messages, and Help 17-19 2. Register the managed bean in the faces-config.xml file. Example 17–8 shows the bean shown in Example 17–7 registered in the faces-config.xml file. Example 17–8 Managed Bean Registration in the faces-config.xml File. managed-bean managed-bean-namehelpTranslationMapmanaged-bean-name managed-bean-class oracle.adfdemo.view.webapp.ELHelpProviderMapDemo managed-bean-class managed-bean-scopesessionmanaged-bean-scope managed-bean For more information about using and registering managed beans, see Section 2.6, Creating and Using Managed Beans. 3. Register the managed bean as a help provider in the adf-settings.xml file for information on creating the adf-settings.xml file if one does not exist, see Section A.5.1, How to Configure for ADF Faces in adf-settings.xml . To register the provider, open the adf-settings.xml file and add the following elements: ■ help-provider: Create and use the prefix attribute to define the prefix that UI components will use to access this help provider. This must be unique in the application. ■ help-provider-class: Create as a child element to the help-provider element and enter the fully qualified class path to the class created in Step 1. ■ property: Create as a child element to the help-provider element. The property defines the map of help strings on the managed bean. Note: All prefixes under which help providers are registered must be unique. It is also not permissible for one prefix to begin with the same characters as another prefix. For example, if help providers have already been registered for the two prefixes AAB and AC, then the following prefixes are all invalid and will cause an exception to be thrown at registration time: AABC, A, AA, AC, ACB. However, the following are valid: AAD, AB, and so on. UI components access the help content based on the topic name. Therefore, if you use the same topic name for two different types of help as shown in Example 17–7 , then both types of help will be displayed by the UI component. Note: If you wish to use external URL help, create a subclass of the ELHelpProvider class. For more information, see Step 4. Note: If the prefix attribute is missing, or is empty, then the help provider will be registered as a special default help provider. It will be used to produce help for help topic IDs that cannot be matched with any other help provider. Only one default help provider is permitted.