17 Displaying
Tips, Messages, and Help
This chapter describes how to define and display tips
and messages for ADF Faces components, and how to provide different levels
of help information for users.
This chapter
includes the following sections:
- Section 17.1, "Introduction to Displaying Tips
and Messages"
- Section 17.2, "Displaying Tips for
Components"
- Section 17.3, "Displaying Hints and Error
Messages for Validation and Conversion"
- Section 17.4, "Grouping Components with a
Single Label and Message"
- Section 17.5, "Displaying Help for Components"
ADF Faces
provides many different ways for displaying informational text in an
application. You can create simple tip text, validation and conversion tip
text, validation and conversion failure messages, as well as elaborate help
systems.
Many ADF
Faces components support the shortDesc attribute, which for most
components, displays tip information when a user hovers the cursor over the
component. Figure 17-1shows a tip configured for a
toolbar button. For more information about creating tips, see Section 17.2, "Displaying Tips for Components."
Along with
tips, EditableValueHolder components (such as the inputText component, or the selection
components) can display hints used for validation and conversion. When you
configure validation or conversion, a default hint automatically displays in a
note window (for more information, see Chapter 6, "Validating and Converting Input").
For example, when users click Help > Give Feedback in the
File Explorer application, a dialog displays where they can enter a time and
date for a customer service representative to call. Because theinputDate component contains a
converter, when the user clicks in the field, a note window displays a hint
that shows the expected pattern, as shown in Figure 17-2. If theinputDate component was also configured
with a minimum or maximum value, the hint would display that information as
well. These hints are provided by the converters and validators automatically.
ADF Faces
uses the standard JSF messaging API. JSF supports a built-in framework for
messaging by allowing FacesMessage instances to be added to the FacesContext object using the addMessage(java.lang.String
clientId, FacesMessage message) method. In general there are two types of messages that can be
created: component-level messages, which are associated with a specific
component based on any client ID that was passed to the addMessage method, and global-level
messages, which are not associated with a component because no the client ID
was passed to the addMessage method.When conversion or validation fails on
an EditableValueHolder ADF Faces component,FacesMessages objects are automatically
added to the message queue on the FacesContext instance, passing in that
component's ID. These messages are then displayed in the note window for the
component. ADF Faces components are able to display their own messages. You do
not need to add any tags.
For example,
if a user enters a date incorrectly in the field shown in Figure 17-2, an error message is displayed, as
shown in Figure 17-3. Note that the error message appears
in the note window along with the hint.
If you want
to display a message for a non-ADF Faces component, or if you want the message
to be displayed inline instead of the note window, use the ADF Faces messagecomponent.
Similarly,
the document tag
handles and displays all global FacesMessages objects (those that do not
contain an associated component ID), as well as component FacesMessages. Like component messages, you do
not need to add any tags for messages to be displayed. Whenever a global
message is created (or more than two component messages), all messages in the
queue will be displayed in a popup window, as shown in Figure 17-4.
However, you
can use the ADF Faces messages component if you want messages to display on the
page rather than in a popup window. For more information about displaying hints
and messages for components, see Section 17.3, "Displaying Hints and Error Messages
for Validation and Conversion."
Tip:
While ADF Faces provides messages for validation and
conversion, you can add your own FacesMessages objects to the queue using the
standard JSF messaging API. When you do so, ADF Faces will display icons with
the message based on the message level, as follows: 
Instead of
having each component display its own messages, you can use the panelLabelAndMessage component to group components
and display a message in one area. This can be very useful when you have to
group components together. For example, the File Explorer application uses
a panelLabelAndMessage component where users enter a telephone number. The telephone
number input field is actually three separate inputText components. The panelLabelAndMessage component wraps three inputText components. Instead of each
having its own label and message, the three have just one label and one
message, as shown in Figure 17-3. For more information, see Section 17.4, "Grouping Components with a Single
Label and Message."
Instead of
configuring messages for individual component instances, you can create a
separate help system that provides information that can be reused throughout
the application.You create help information using different types of providers,
and then reference the help text from the UI components. The following are the
three types of help supported by ADF Faces:
- Definition: Provides a help icon
(question mark in a blue circle) with the help text appearing when the
user mouses over the icon, as shown in Figure 17-5.
- Instruction: Depending on the component,
this type of help either provides instruction text within the component
(as with panelHeader components), or displays text in the note
window that is opened when the user clicks in the component, as shown
in Figure 17-6. The text can be any length.
- External URL: You can have a
help topic that resides in an external application, which will open in displaying
a separate browser window. For example, instead of instruction help, Figure 17-7 shows the Select
Skin selectOneChoice component configured to open a help topic
about skins. When a user clicks the help icon, the help topic opens.
For more information about creating help systems, see Section 17.5, "Displaying Help for Components."
ADF Faces
components use the shortDesc attribute to display a tip when the user hovers
the mouse over the component. Input components display the tips in their note
window. Other component types display the tip in a standard tip box. This text
should be kept short. If you have to display more detailed information, or if
the text can be reused among many component instances, consider using help
text, as described in Section 17.5, "Displaying Help for Components."
- In the Structure window, select
the component for which you want to display the tip.
- In the Property Inspector,
expand the Appearance section and enter a value for
the shortDesc attribute.
Tip:
The value should be less than 80 characters, as some
browsers will truncate the
tip if it exceeds that length.
If the text to be used is stored in a resource bundle, use the dropdown
list to select Select Text Resource. Use the Select Text Resource
dialog to either search for appropriate text in an existing bundle, or to
create a new entry in an existing bundle. For more information about using
resource bundles, see Chapter 21, "Internationalizing and Localizing
Pages."
Validators
and converters have a default hint that is displayed to users when they click
in the associated field. For converters, the hint usually tells the user the
correct format to use. For validators, the hint is used to convey what values
are valid.
For example,
in the File Explorer application, when a user clicks in the input date field on
the Speak with Customer Service page, a tip is displayed showing the correct
format to use, as shown in Figure 17-10.
When the
value of an ADF Faces component fails validation, or cannot be converted by a
converter, the component displays the resulting FacesMessage instance.
For example,
entering a date that does not match the dateStyle attribute of the converter
results in an error message, as shown in Figure 17-11.
You can
override the default validator and converter hint and error messages. Each
ADF Faces validator and converter component has attributes you can use to
define the detail messages to be displayed for the user. The actual attributes
vary according to the validator or converter. Figure 17-12 shows the attributes that
you can populate to override the messages for the convertDateTime converter, as displayed in the
Property Inspector.
If you do
not want messages to be displayed in the note window, you can use the message component, and messages will
be displayed inline with the component. Figure 17-13 shows how messages are
displayed using the message component.
JSF pages in
an ADF Faces application use the document tag, which among other things,
handles displaying all global messages (those not associated with a component)
in a popup window. However, if you want to display global messages on the page
instead, use the messages component.
To override
the default validator and converter messages, set values for the different
message attributes.
- In the Structure window, select
the converter or validator for which you want to create the error message.
Note:
You can override messages only for ADF Faces
components. If you want to create a message for a non-ADF Faces component (for
example for the f:validator component), then use the message component. For more
information, see Section 17.3.3, "How to Display Component Messages Inline."
- In the Property Inspector,
expand the Messages section and enter a value for the
attribute for which you want to provide a message.
The values can include dynamic content by using parameter placeholders
such as {0}, {1}, {2}, and so on. For example, the messageDetailConvertDate attribute on theconvertDateTime converter uses the following
parameters:
- {0} the label that identifies
the component
- {1} the value entered by the
user
- {2}an example of the format
expected by the component.
Using these parameters, you could create this message:
{1} is not using the correct date format. Please enter
the date as follows: {2}.
The error message would then be displayed as shown in Figure 17-14.
Tip:
Use the dropdown menu to view the property help, which
includes the parameters accepted by the message.
If the text to be used is stored in a resource bundle, use the dropdown
list to select Select Text Resource. Use the Select Text Resource
dialog to either search for appropriate text in an existing bundle, or to
create a new entry in an existing bundle. For more information about using
resource bundles, see Chapter 21, "Internationalizing and Localizing
Pages."
Note:
The message text is for the detail message of
the FacesMessage object.
If you want to override the summary (the text shown at the top of the message),
you can only do this globally. For more information, see Section 17.3.2, "What You May Need to Know About
Overriding Default Messages Globally."
Instead of
changing the message string per component instance with the messageDetail[XYZ] attributes, override the
string globally so that the string will be displayed for all instances. To
override globally, create a message bundle whose contents contain the key for
the message and the message text you wish to use.
You create
and use a message bundle in the same way you create and use resource bundles
for translation, using either Java classes or properties files. For procedures
and information, see Chapter 21, "Internationalizing and Localizing
Pages."
For message
key information, see Appendix B, "Message Keys for Converter and
Validator Messages."
Instead of
having a component display its messages in the note window, use the message component to display the
messages inline on the page. In order for the message component to display the
correct messages, associate it with a specific component.
- In the Structure window, select
the component that will display its messages using the message component. If not already
set, enter an ID for the component.
- In the Component Palette, from
the Common Components panel, drag a Message and drop it
where you want the message to be displayed on the page.
- Use the dropdown menu for
the for attribute to select Edit.
- In the Edit Property dialog,
locate the component for which the message component will display
messages. Only components that have their ID set are valid selections.
Note:
The message icon and message content that will be
displayed are based on what was given when the FacesMessage object was created. Setting
the messageType or message attributes on the message component causes the messageType or message attribute values to be
displayed at runtime, regardless of whether or not an error has occurred. Only
populate these attributes if you want the content to always be displayed when
the page is rendered.
Instead of
displaying global messages in a popup window for the page, display them inline
using the messages component.
- In the Component Palette, from
the Common Components panel, drag a Messages and drop it
onto the page where you want the messages to be displayed.
- In the Property Inspector set
the following attributes:
- globalOnly: By default, ADF Faces
displays global messages (messages that are not associated with
components) followed by individual component messages. If you want to
display only global messages in the box, set this attribute to true. Component messages will
continue to be displayed with the associated component.
- inline: Set to true to show messages at the
top of the page. Otherwise, messages will be displayed in a dialog.
By default,
ADF Faces input and select components have built-in support for label and
message display. If you want to group components and use a single label, wrap
the components using the panelLabelAndMessage component.
For example,
the File Explorer application collects telephone numbers using four
separate inputText components;
one for the area code, one for the exchange, one for the last four digits, and
one for the extension. Because a single label is needed, the four inputText components are wrapped in
a panelLabelAndMessage component, and the label value is set on that component. However,
the input component for the extension requires an additional label, so an outputText component is used. Example 17-1 shows the JSF code for thepanelLabelAndMessage component.
<af:panelLabelAndMessage
labelAndAccessKey="#{explorerBundle['help.telephone']}"
helpTopicId="HELP_TELEPHONE_NUMBER"
labelStyle="vertical-align: top;
padding-top:
0.2em;">
<af:inputText autoTab="true" simple="true"
maximumLength="3"
columns="3">
<af:convertNumber type="number"
integerOnly="true"/>
</af:inputText>
<af:inputText autoTab="true" simple="true"
maximumLength="3"
columns="3">
<af:convertNumber type="number"
integerOnly="true"/>
</af:inputText>
<af:inputText autoTab="true" simple="true"
maximumLength="4"
columns="4">
<af:convertNumber type="number"
integerOnly="true"/>
</af:inputText>
<af:outputText
value="#{explorerBundle['help.extension']}"/>
<af:inputText
simple="true" columns="4">
<af:convertNumber type="number"
integerOnly="true"/>
</af:inputText>
</af:panelLabelAndMessage>
The panelLabelAndMessage component also includes
an End facet
that can be used to display additional components at the end of the
group. Figure 17-16 shows how the telephone
number fields would be displayed if the End facet was populated with an outputText component.
Use a panelGroupLayout component within a panelLabelAndMessage component to group the
components for the required layout. For information about using thepanelGrouplayout component, see Section 8.12, "Grouping Related Items."
You set
the simple attribute
to true on
each of the input components so that their individual labels are not displayed.
However, you may want to set a value for the label attribute on each of the
components for messaging purposes and for accessibility.
Tip:
If you have to use multiple panelLabelAndMessage components one after another,
wrap them inside an af:panelFormLayout component, so that the labels line up properly.
For information about using the panelFormLayout component, see Section 8.6, "Arranging Content in Forms."
Group and
wrap components using the panelLabelAndMessage component. The panelLabelAndMessage component can be used to wrap
any components, not just those that typically display messages and labels.
For each input and select component:
- Set the simple attribute to true.
- For accessibility reasons, set
the label attribute to a label for the component.
- In the Structure window, select
the input and/or select components created in Step 1. Right-click the selection and
choose Surround With > Panel Label And Message.
- With the panelLabelAndMessage component selected, in
the Property Inspector, set the following:
- label: Enter the label text to be
displayed for the group of components.
- for: Use the dropdown menu to
choose Edit. In the Edit Property dialog, select the ID of the child
input component. If there is more than one input component, select the
first component.
Set the for attribute to the first inputComponent to meet accessibility
requirements.
- If one or more of the nested
input components is a required component and you want a marker to be
displayed indicating this, set the showRequired attribute to true.
- To place content in the End facet, drag and drop the
desired component into the facet.
Because facets accept one child component only, if you want to add more
than one child component, you must wrap the child components inside a
container, such as apanelGroupLayout or group component.
Tip:
If the facet is not visible in the visual editor:
a. Right-click the panelLabelAndMessage component in the Structure
window.
b. From the context menu, choose Facets
- Panel Label And Message >facet name. Facets in use on the page
are indicated by a checkmark in front of the facet name.
ADF Faces
provides a framework that allows you to create and display three different
types of help whose content comes from an external source, rather than as text
configured on the component. Because it is not configured directly on the
component, the content can be used by more than one component, saving time in
creating pages and also allowing you to change the content in one place rather
than everywhere the content appears.
The first
type of external help provided by ADF Faces is Definition help. Like a standard
tip, the content appears in a message box. However, instead of appearing when
the user mouses over the component, Definition help provides a help icon (a
blue circle with a question mark). When the user mouses over the icon, the
content is displayed, as shown inFigure 17-17.
Table 17-1 shows the components that
support Definition help.
|
Supported
Components
|
Help Icon
Placement
|
Example
|
|
All input
components, Select components, Choose Color, Choose Date, Query components
|
Before the
label, or if no label exists, at the start of the field
|
 |
|
Panel
Header, PanelBox, Show Detail Header
|
End of header
text
|
 |
|
Panel
Window, Dialog
|
Next to
close icon in header
|
 |
|
Columns in
table and tree
|
Below
header text
|
 |
The second
type of help is Instruction help. Where Instruction help is displayed depends
on the component with which it is associated. The panelHeader and Search panel components
display Instruction help within the header. Figure 17-18 shows how the text that
typically is displayed as Definition help as shown in Figure 17-17 would be displayed as
Instruction help within the panelHeader component.
All other components
that support Instruction help display the text within a note window, as shown
in Figure 17-19. Note that no help icon is
displayed.
Table 17-2 shows the components that
support Instruction help.
|
Supported
Components
|
Help
Placement
|
Example
|
|
Input
components, Choose Color, Choose Date, Quick Query
|
Note
window, on focus only
|
|
|
Select
components
|
Note
window, on hover and focus
|
 |
|
Panel
Header, Panel Box, Query
|
Text below
header text
|
 |
The last
type of help is External URL help. You provide a URL to a web page in an
external application, and when the help icon is clicked, the web page opens in
a separate browser window, as shown in Figure 17-20. Instead of clicking a help icon,
you can use JavaScript to open a help window based on any client-based event.
ADF Faces
includes a variety of help providers. The ResourceBundleHelpProvider help provider allows you to
create resource bundles that hold the help content. TheELHelpProvider help provider allows you to
create XLIFF files that get converted into maps, or create a managed bean that
contains a map of help text strings. You can use a combination of the different
help providers. You can also create your own help provider class.
To create
help for your application, do the following:
- Determine the help provider(s)
to use and then implement the required artifacts.
- Register the help provider(s),
specifying the prefix that will be used to access the provider's help.
Each help provider has its own unique prefix, which is used as its
identifier. A particular provider will be called to produce help only for
help topic IDs that start with the prefix under which the provider is
registered.
- Have the UI components access
the help contained in the providers by using the component's helpTopicId attribute. A helpTopicId attribute contains the
following.
- The prefix that is used by the
provider of the help
- The topic name
For example, the value of the helpTopicId attribute on the inputText component shown in Figure 17-19 might be RBHELP_FILE_NAME, where RBHELP is the resource bundle help
providers prefix, and FILE_NAME is the help topic name.
You can
store help text within standard resource bundle property files and use
the ResourceBundleHelpProvider class to deliver the content.
- Create a properties file that
contains the topic ID and help text for each help topic. The topic ID must
contain the following:
- The prefix that will be used
by this provider, for example, RBHELP.
- The topic name, for
example, TELEPHONE_NUMBER.
- The help type, for
example, DEFINITION.
For example, a topic ID might be RBHELP_TELEPHONE_NUMBER_DEFINITION.
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-2), then both types of help will be
displayed by the UI component.
Example 17-2 shows an example resource
bundle with three topics.
RBHELP_CUST_SERVICE_EMAIL_DEFINITION=For security
reasons,
we strongly discourage the submission of credit card numbers.
RBHELP_TELEPHONE_NUMBER_DEFINITION=We only support
calling telephone numbers
in the United States at this time.
RBHELP_TELEPHONE_NUMBER_INSTRUCTIONS=Enter a telephone
number.
Note:
If you wish to use an external URL help type, create a
subclass of the ResourceBundleHelpProvider class. For more information,
see Step 3.
- Register the resource bundle 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, click the Source tab,
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
resource bundle.
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.
- <help-provider-class>: Create as a child element to
the <help-provider> element and enter oracle.adf.view.rich.help.ResourceBundleHelpProvider.
- <property>: Create as a child element to
the <help-provider> element. The property
defines the actual help source.
- <property-name>: Create as a child element to
the <property> element, and enter a
name for the source, for example, baseName.
- <value>: Create as a child element to
the <property> element and enter the
fully qualified class name of the resource bundle. For example, the
qualified class name of the resource bundle used in the ADF Faces demo
application is oracle.adfdemo.view.resource.DemoResources.
Example 17-3 shows how the resource
bundle in Example 17-2 would be registered in
the adf-settings.xml file.
<adf-settings
xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config
xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="RBHELP_">
<help-provider-class>
oracle.adf.view.rich.help.ResourceBundleHelpProvider
</help-provider-class>
<property>
<property-name>baseName</property-name>
<value>oracle.adfdemo.view.resource.DemoResources</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>
- If you
want to use External URL help, then you also must extend the ResourceBundleHelpProvider class and implement
the getExternalUrl method. Example 17-4 shows an example
method.
protected String getExternalUrl(FacesContext context,
UIComponent component,
String topicId)
{
if (topicId
== null)
return
null;
if
(topicId.contains("TOPICID_ALL") ||
topicId.contains("TOPICID_DEFN_URL") ||
topicId.contains("TOPICID_INSTR_URL") ||
topicId.contains("TOPICID_URL"))
return
http://www.myURL.com;
else
return
null;
}
In Example 17-4, all the topics in the method
return the same URL. You would have to create separate if statements to return different
URLs.
If you want the external window to be launched based on a component's
client event instead of from a help icon, use a JavaScript function. For more
information, see Section 17.5.4, "How to Use JavaScript to Launch an
External Help Window."
You can
store the help text in XLIFF XML files and use the ELHelpProvider class to deliver the content.
This class translates the XLIFF file to a map of strings that will be used as
the text in the help.
- Create an XLIFF file that
defines your help text, using the following elements within the <body> tag:
- <trans-unit>: Enter the topic ID. This
must contain the prefix, the topic name, and the help type, for
example, XLIFFHELP_CREDIT_CARD_DEFINITION. In this example,XLIFFHELP will become the prefix
used to access the XLIFF file. CREDIT_CARD is the topic name,
and DEFINITION is the type of help.
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-5), 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 is used to hold translated text.
- <note>: Create as a direct child of
the <trans-unit> element and enter a
description for the help text.
Example 17-5 shows an example of an XLIFF
file that contains two topics.
<?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">
<source>Credit Card Definition</source>
<target/>
<note>Credit Card definition text.</note>
</trans-unit>
<trans-unit id="XLIFF_CREDIT_CARD_INSTRUCTIONS">
<source>Credit Card Instructions</source>
<target/>
<note>Credit card instruction text.</note>
</trans-unit>
</body>
</file>
</xliff>
- 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.
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.
- <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.
<adf-settings
xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="XLIFF">
<help-provider-class>
oracle.adf.view.rich.help.ELHelpProvider
</help-provider-class>
<property>
<property-name>helpSource</property-name>
<value>#{adfBundle['project1xliff.view.Project1XliffBundle']}</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>
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 theELHelpProvider class to deliver the help.
- 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.
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
Map<String, String> getHelpMap()
{
return
_HELP_MAP;
}
static
private final Map<String, String> _HELP_MAP =
new HashMap<String, String>();
static
{
_HELP_MAP.put("MAPHELP_CREDIT_CARD_DEFINITION",
"Map value for credit card definition");
_HELP_MAP.put("MAPHELP_CREDIT_CARD_INSTRUCTIONS",
"Map value for credit card instructions");
_HELP_MAP.put("MAPHELP_SHOPPING_DEFINITION",
"Map value for shopping definition");
_HELP_MAP.put("MAPHELP_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.
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.
- 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.
<managed-bean>
<managed-bean-name>helpTranslationMap</managed-bean-name>
<managed-bean-class>
oracle.adfdemo.view.webapp.ELHelpProviderMapDemo
</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>
For more information about using and registering managed beans,
see Section 2.6, "Creating and Using Managed
Beans."
- 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.
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.
- <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.
- <property-name>: Create as a child element to
the <property> element and enter a
property name, for example helpSource.
- <value>: Create as a child element to
the <property> element and enter an EL
expression that resolves to the help map on the managed bean.
<adf-settings
xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config
xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="MAPHELP_">
<help-provider-class>
oracle.adf.view.rich.help.ELHelpProvider
</help-provider-class>
<property>
<property-name>helpSource</property-name>
<value>#{helpTranslationMap.helpMap}</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>
- If you
want to use External URL help with the managed bean provider, then extend
the ELHelpProvider class and implement the getExternalUrl method. Example 17-10shows an example method.
protected String getExternalUrl(FacesContext context,
UIComponent component,
String topicId)
{
if (topicId
== null)
return
null;
if
(topicId.contains("TOPICID_ALL") ||
topicId.contains("TOPICID_DEFN_URL") ||
topicId.contains("TOPICID_INSTR_URL") ||
topicId.contains("TOPICID_URL"))
return
http://www.myURL.com;
else
return
null;
}
In Example 17-10, all the topics in the method
return the same URL. You must create separate if statements to return different
URLs.
If you want the external window to be launched based on a component's
client event instead of from a help icon, use a JavaScript function. For more
information, see Section 17.5.4, "How to Use JavaScript to Launch an
External Help Window."
If you want
to use external URL help, by default, the user clicks a help icon to launch the
help window. Instead, you can use JavaScript and a client event listener for a
specific component's event to launch the help window.
<af:resource type="javascript">
function
launchHelp(event)
{
AdfPage.PAGE.launchHelpWindow("helpClient.jspx");
}
</af:resource>
- Drag
and drop a component whose client event will cause the function to be
called. You must set the clientId on this component
to true.
- In the Component Palette, from
the Operations panel, drag and drop a Client Listener as
a child to the component created in Step 2. Configure the clientListener to invoke the function
created in Step 1. For more information about using
the clientListener tag, see Section 3.2, "Listening for Client
Events."
Example 17-12 shows the code used to have
a click event on a commandToolbarButton component launch the helpClient.jspx page.
<af:toolbar id="tb1">
<af:commandToolbarButton text="Launch help window"
id="ctb1"
icon="/images/happy_computer.gif">
<af:clientListener method="launchHelp" type="click"/>
</af:commandToolbarButton>
</af:toolbar>
<af:resource type="javascript">
function
launchHelp(event)
{
AdfPage.PAGE.launchHelpWindow("helpClient.jspx");
}
</af:resource>
Instead of
using one of the ADF Faces help providers, create your own. Create the actual
text in some file that your help provider will be able to access and display.
To create a Java class help provider, extend the HelpProvider class. For more information
about this class, refer to the ADF Faces Javadoc.
- Create
a Java class that extends oracle.adf.view.rich.help.HelpProvider.
- Create a public constructor
with no parameters. You also must implement the logic to access and return
help topics.
- This
class will be able to access properties and values that are set in
the adf-settings.xml file when you register this provider. For
example, the ADF Faces providers all use a property to define the actual
source of the help strings. To access a property in the adf-settings.xml file, create a method
that sets a property that is a String. For example:
4. public void setMyCustomProperty(String arg)
- 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.
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. 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 andAC, 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.
- <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 and use it to
define the property that will be used as the argument for the method
created in Step 3.
- <property-name>: Create as a child element to
the <property> element and enter the
property name.
- <value>: Create as a child element to
the <property> element and enter the
value for the property.
<adf-settings
xmlns="http://xmlns.oracle.com/adf/settings">
<adf-faces-config
xmlns="http://xmlns.oracle.com/adf/faces/settings">
<help-provider prefix="MYAPP">
<help-provider-class>
oracle.adfdemo.view.webapp.MyHelpProvider
</help-provider-class>
<property>
<property-name>myCustomProperty</property-name>
<value>someValue</value>
</property>
</help-provider>
</adf-faces-config>
</adf-settings>
Use
the HelpTopicId attribute
on components to access and display the help.
- In the Structure window, select
the component to which you want to add help. For a list of components that
support help, see Table 17-1 and Table 17-2.
- In the Property Inspector,
expand the Appearance section, and enter a value for
the helpTopicId attribute. This should include the prefix
to access the correct help provider and the topic name. It should not
include the help type, as all help types registered with that name will be
returned and displayed, for example:
3. <af:inputText label="Credit Card"
helpTopicId="XLIFF_CREDIT_CARD"/>
This example will return both the definition and instruction help
defined in the XLIFF file in Example 17-5.
- If you want to provide help for
a component that does not support help, you can instead add an outputText component to display the
help text, and then bind that component to the help provider, for example:
5. <af:outputFormatted
6. value="#{adfFacesContext.helpProvider['XLIFF_CREDIT_CARD'].instructions}"/>
This will access the instruction help text.
When you add
help messages to input components that may already display messages for
validation and conversion, ADF Faces displays the messages in the following
order within the note window:
- Validation and conversion error
messages.
- Validation and conversion
hints.
- For input and select components
only, Instruction help. For panelHeader components, Instruction
help is always displayed below the header.
- Value for shortDesc attribute.
Figure 17-21 shows an inputDate component that contains a
converter, instruction help, and a tip message.
No comments:
Post a Comment