18 Customizing Help

This chapter describes how you can customize or extend user assistance help in your Oracle Fusion application to match your runtime and design time customizations.

This chapter contains the following sections:

Section 18.1, "About Customizing Help"
Section 18.2, "Customizing or Extending Oracle Fusion Applications Help"
Section 18.3, "Customizing or Adding Bubble Embedded Help"
Section 18.4, "Customizing or Adding Static Instructions, In-Field Notes, and Terminology Definitions"

18.1 About Customizing Help

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

This type of help includes help topics, FAQs, examples, demonstrations and PDF guides, and is delivered with the Oracle Fusion Applications Help as shown in Figure 18-1.

Figure 18-1 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 typically contain forms or tables. This instruction guides the user in filling out the form or using the table, as shown in Figure 18-2.
  
  Figure 18-2 Static Help Text in Oracle Fusion Applications
- 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.
  
  Figure 18-3 In-Field Note in Oracle Fusion Applications
- Terminology definition: displayed by input components and defines terms used on the page, as shown in Figure 18-4.
  
  Figure 18-4 Terminology Definition in Oracle Fusion Applications
- Bubble help: displayed when the end user mouses over a button or link component, as shown in Figure 18-5.
  
  Figure 18-5 Bubble Help in Oracle Fusion Applications
- 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.
  
  Figure 18-6 Help Window in Oracle Fusion Applications

18.1.1 What You Can Do with 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.

18.1.2 Before You Begin Customizing Help

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, then you will need specific privileges. Contact your security administrator for details.
Install Oracle JDeveloper and set up your development environment. For more information, see the "Setting Up Your Development Environment" chapter in the Oracle Fusion Applications Developer's Guide.
Create a customization application workspace. For more information, see Chapter 10, "Using Oracle JDeveloper for Customizations."
Start JDeveloper in the Oracle Fusion Applications Administrator Customization role.
Select a layer value. When customizing application artifacts in JDeveloper, you first must 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."

18.2 Customizing or Extending Oracle Fusion Applications Help

You can customize existing help files in Oracle Fusion Applications Help, or you can extend Oracle Fusion Applications Help by adding custom topics.

After they are 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 necessary 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.

18.3 Customizing or Adding Bubble Embedded Help

For bubble help, you can use CRM Application Composer or Page Composer to customize or create the help text.

The following components use bubble help.

Butcon
Button
Link
Tab

Task: Customize or Add Bubble Help

The text displayed in bubble help is the value of the component's shortDesc attribute. Usually, the value resolves to a key in a resource bundle. If you are customizing a CRM application, then 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 Page Composer to customize the attribute. For more information, see Section 3.3, "Editing Component Properties in Page Composer."

18.4 Customizing or Adding Static Instructions, In-Field Notes, and Terminology Definitions

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 is displayed 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 (Oracle Fusion Applications Edition).

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 Applications Help Type	ADF Faces Help Type	Component
Static instruction	instruction	Page header Subheader Sub-subheader
In-field note	instruction	Multiselect checkbox group Single-select choice list Multiselect choice list Single-select list box Multiselect list box Text box Single-select radio groups Items in true/false radio groups Items in true/false checkbox groups Color picker Date/time picker Flexfield LOV Spin box Slider File upload Shuttle Rich Text Editor
Terminology definition	definition	Checkbox prompt Checkbox group prompt Single-select choice list Multiselect choice list Single-select list box Multiselect list box Text box Radio group prompt Color picker Date/time picker Flexfield LOV Column headers Spin box Slider File upload Shuttle Rich Text Editor

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 must 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.12, "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.

For example:
```
MYCUSTHELP_NEWHELPTOPIC_DEFINITION
```
In this example, MYCUSTHELP is 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 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 for the id attribute. 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 (Oracle Fusion Applications Edition).