|Oracle® Fusion Applications Extensibility Guide
11g Release 1 (220.127.116.11)
Part Number E16691-02
This chapter describes how you can customize or extend user assistance help in your Oracle Fusion application to match any customizations.
This chapter contains the following sections:
When you customize an Oracle Fusion application, you may find you also need to customize or extend the existing help to match your changes. Oracle Fusion applications provide two different types of help.
Oracle Fusion Applications Help
Embedded static page-level help
This type of help is displayed directly on a page, using attributes of a component. The help text is included in the application.
Tip:Help text is stored in resource bundles, and so can be translated. For more information, see Chapter 16, "Translating Custom Text."
Embedded help includes the following:
Static instruction text: displayed by panel components that normally contain forms or tables. This instruction guides the user in filling out the form or using the table, as shown in Figure 18-2.
In-field help note: displayed by input components and guides the user in entering data into the component. Figure 18-3 shows an in-field note.
Terminology definition: displayed by input components and defines terms used on the page, as shown in Figure 18-4.
Bubble help: displayed when the end user mouses over a button or link component, as shown in Figure 18-5.
Help window: displayed when a user clicks the help icon, as shown in Figure 18-6. This type of help is generally brief context-sensitive help, and can also provide links to help files in Oracle Fusion Applications Help.
In Oracle Fusion Applications Help, you can change the content in existing help windows or you can create new help windows. Within a page of an application, you can customize or create bubble help, static instructions, in-field notes, terminology definitions, and help windows. This help text is stored either as a value for an attribute, or in translatable resource bundles.
Before you customize help, you should be familiar with the Oracle Fusion application architecture that enables customization, as described in Chapter 1, "Customizing and Extending Oracle Fusion Applications." You should also understand the typical workflows for working with customizations, as described in Chapter 2, "Understanding the Customization Development Lifecycle."
You will also need to do the following before you can begin customizing help:
If you will be adding or customizing Oracle Fusion Applications Help, you will need the correct privileges. Please contact your security administrator for details.
Install JDeveloper and set up your development environment. For more information, see "Chapter 2 Setting Up Your Development Environment" of the Oracle Fusion Applications Developer's Guide.
Create a customization application workspace. For more information, see Chapter 10, "Using JDeveloper for Customizations."
Launch JDeveloper in the Oracle Fusion Applications Administrator Customization role.
Select a layer value. When customizing application artifacts in JDeveloper, you first need to select the layer and layer value to work in. You use the Customization Context window to make this selection. For more information about customization layers, see Section 1.2, "Understanding Customization Layers.""
You can customize existing help files in Oracle Fusion Applications Help, or you can extend Oracle Fusion Applications Help by adding custom topics.
Once created, custom help files are distinguished by an icon in search results, and they are displayed at the top of help listings when you navigate.
Task: Customize Oracle Fusion Applications Help Windows
When you have the correct privileges, help windows in Oracle Fusion Applications Help display a Manage Custom Help link, which allows you to change the content and specify in which help windows in the application your custom help will appear, and where it will appear in the help site navigators. For more information, see the "Define Help Configuration" section in the Oracle Fusion Applications Common Implementation Guide.
Task: Add Custom Help Files to Oracle Fusion Applications Help
You can add new custom help files to Oracle Fusion Applications Help. Custom help files will appear like standard help files and can be searched and included in help windows and navigators. For more information, see the "Define Help Configuration" section in the Oracle Fusion Applications Common Implementation Guide.
For bubble help, you can use CRM Application Composer or Oracle Composer to customize or create the help text.
The following components use bubble help.
Task: Customize or Add Bubble Help
The text displayed in bubble help is the value of the component's
shortDesc attribute. Normally, the value resolves to a key in a resource bundle. If your are customizing a CRM application, you can use CRM Application Composer to customize the value of the attribute. For more information, see Section 4.2, "Editing Objects." For other applications, you use Oracle Composer to customize the attribute. For more information, see Section 3.3, "Editing Component Properties in Oracle Composer."
Oracle Fusion Applications embedded help (aside from bubble help) uses two types of ADF Faces help: instruction and definition. Instruction-type help displays static text, either in a specified area on a component (like static instruction help, shown in Figure 18-2), or in a note window, as in-field notes do, shown in Figure 18-3. Definition-type help displays a help icon, and is what terminology definition embedded help uses, as shown in Figure 18-4. When the user mouses over the help icon, the help text displays in a message box. UI components display the instruction and definition help text using the
helpTopicId attribute. For more information about the ADF Faces help framework, see the "Displaying Help for Components" section of the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
It is important that for the type of help you want to add or customize, you understand which component actually displays the help, and which type of ADF Faces help is being used. Table 18-1 shows the different types of Oracle Fusion Applications embedded help, the corresponding ADF Faces help, and the components that display that type of help.
Table 18-1 Oracle Fusion Applications Help and Corresponding ADF Faces Help and UI Components
|Oracle Fusion Application Help Type||ADF Faces Help Type||Component|
You perform the following tasks in JDeveloper in the Oracle Fusion Applications Administrator Customization role.
Note:You cannot directly customize the existing help text strings. If you want to change text that currently appears, you need to create a new text string and associate the component with that new text.
Task: Add Help Strings to Resource Bundle
Add custom help text strings to an existing custom resource bundle or create a new resource bundle to hold your customized help text (Oracle Fusion applications use XLIFF files for resource bundles). If you create a new resource file, you must register that file with the project. For information about creating and using resource bundles for an Oracle Fusion application, see Section 11.10, "Customizing or Adding Resource Bundles."
The help text must use the following syntax:
<trans-unit>: Enter the topic ID. This must contain a unique prefix, the topic name, and the help type, either INSTRUCTION or DEFINITION.
Note:You prefix must unique. You must use this prefix for all your custom help strings.
In this example, MYCUSTHELPis the prefix used to access the XLIFF file. NEWHELPTOPIC is the topic name, and DEFINITION is the type of ADF Faces help.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 (instruction and definition), then both types of help will be displayed by the UI component.
<source>: Create as a direct child of the
<trans-unit> element and enter the help text.
<target>: Create as a direct child of the
<trans-unit> element and leave it blank. This will hold translated text populated by translation tools.
<note>: Create as a direct child of the
<trans-unit> element and enter a description for the help text.
Example 18-1 shows an example of a resource file that contains two topics.
Example 18-1 XLIFF Resource Bundle
<?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="MYCUSTHELP_NEWHELPTOPIC_DEFINITION"> <source>Credit Card Definition</source> <target/> <note>This is the credit card definition text.</note> </trans-unit> <trans-unit id="MYCUSTHELP_NEWTOPIC2_INSTRUCTIONS"> <source>Credit Card Instructions</source> <target/> <note>This is the credit card instruction text.</note> </trans-unit> </body> </file> </xliff>
Task: Associate the Component with the Help Strings
In JDeveloper, select the component to display the help. Associate that component with the
<trans-unit> element in the resource bundle, using the component's
helpTopicID attribute. Ensure that the component supports the type of help (that is, definition or instruction) defined in the trans-unit id. For instructions, see the "How to Access Help Content from a UI Component" section of the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.