| Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1) Part Number B31973-03 |
|
|
View PDF |
| Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1) Part Number B31973-03 |
|
|
View PDF |
This chapter describes how to display output text, images, and icons using ADF Faces components, and how to use components that allow users to play video and audio clips.
This chapter includes the following sections:
Section 16.1, "Introduction to Output Text, Image, Icon, and Media Components"
Section 16.2, "Displaying Output Text and Formatted Output Text"
ADF Faces provides components for displaying text, icons, and images, and for playing audio and video clips on JSF pages.
Read-only text can be displayed using the outputText or outputFormatted components. The outputFormatted component allows you to add a limited set of HTML markup to the value of the component, allowing for some very simple formatting to the text.
Many ADF Faces components can have icons associated with them. For example, in a menu, each of the menu items can have an associated icon. You identify the image to use for each one as the value of an icon attribute for the menu item component itself. Information and instructions for adding icons to components that support them are covered in those components' chapters. In addition to using icons within components, ADF Faces also provides icons used when displaying messages. You can use these icons outside of messages as well.
To display an image on a page, you use the image component. Images can also be used as links (including image maps). You can also use images to depict the status of the server. The media component can play back an audio clip or a video clip. These components have attributes so that you can define how the item is to be presented on the page.
There are two ADF Faces components specifically for displaying output text on pages: outputText, which displays unformatted text, and outputFormatted, which displays text and can include a limited range of formatting options.
To display simple text either specified explicitly or from a resource bundle or bean, you use the outputText component. You define the text to be displayed as the value of the value property. For example:
<af:outputText value="The submitted value was: "/>
Example 16-1 shows two outputText components: the first specifies the text to be displayed explicitly and the second takes the text from a managed bean and converts the value to a text value ready to be displayed (for more information about conversion, see Section 6.3, "Adding Conversion").
Example 16-1 Output Text
<af:panelGroupLayout>
<af:outputText value="The submitted value was: "/>
<af:outputText value="#{demoInput.date}">
<af:convertDateTime dateStyle="long"/>
</af:outputText>
</af:panelGroupLayout>
You can use the escape attribute to specify whether or not special HTML and XML characters are escaped for the current markup language. By default, characters are escaped.
Example 16-2 illustrates two outputText components, the first of which uses the default value of true for the escape attribute, and the second has the attribute set to false.
Example 16-2 Output Text With and Without the escape Property Set
<af:outputText value="<h3>output & heading</h3>"/>
<af:outputText value="<h3>output & heading</h3>"
escape="false"/>
Figure 16-1 shows the different effects seen in a browser of the two different settings of the escape attribute.
You should avoid setting the escape attribute to false unless absolutely necessary. A better choice is to use the outputFormatted component, which allows a limited number of HTML tags.
As with the outputText component, the outputFormatted component also displays the text specified for the value property, but the value can contain HTML tags. Use the formatting features of the outputFormatted component specifically when you want to format only parts of the value in a certain way. If you want to use the same styling for the whole component value, instead of using HTML within the value, apply a style to the whole component. If you want all instances of a component to be formatted a certain way, then you should create a custom skin. For more information about using inline styles and creating skins, see Chapter 20, "Customizing the Appearance Using Styles and Skins".
Example 16-3 shows an outputFormatted component displaying only a few words of its value in bold.
Example 16-3 Using outputFormatted to Bold Some Text
<af:outputFormatted value="<b>This is in bold.</b> This is not bold"/>
Figure 16-2 shows how the component displays the text.
Before displaying any output text, decide whether or not any parts of the value must be formatted in a special way.
To display output text:
To create an outputText component, drag and drop Output Text from the Component Palette on the page. To create an outputFormatted component, drag and drop Output Formatted from the Component Palette.
Tip:
If parts of the value require special formatting, use an
outputFormatted component.Tip:
If you plan to support changing the text of the component through active data (for example, data being pushed from the data source will determine the text that is displayed), then you should use theactiveOutputText component instead of the outputText component. Create an activeOutputText component by dragging an Output Text (Active) from the Component Palette.Expand the Common section of the Property Inspector and set the value attribute to the value to be displayed. If you are using the outputFormatted component, use HTML formatting codes to format the text as needed, as described in Table 16-1 and Table 16-2.
The outputFormatted component also supports the styleUsage attribute whose values are the following predefined styles for the text:
inContextBranding
instruction
pageStamp
Figure 16-3 shows how the styleUsage values apply styles to the component.
Note:
If
styleUsage and styleClass attributes are both set, the styleClass attribute takes precedence.Table 16-1 lists the formatting codes allowed for formatting values in the outputFormatted component.
Table 16-1 Formatting Codes for Use in af:outputFormatted Values
| Formatting Code | Effect |
|---|---|
|
|
Line break |
|
|
Horizontal rule |
|
|
Lists: ordered list, unordered list, and list item |
|
|
Paragraph |
|
|
Bold |
|
|
Italic |
|
|
Teletype or monospaced |
|
|
Larger font |
|
|
Smaller font |
|
|
Preformatted: layout defined by whitespace and line break characters preserved |
|
|
Span the enclosed text |
|
|
Anchor |
Table 16-2 lists the character codes for displaying special characters in the values.
Table 16-2 Character Codes for Use in af:outputFormatted Values
| Character Code | Character |
|---|---|
|
|
Less than |
|
|
Greater than |
|
|
Ampersand |
|
|
Registered |
|
|
Copyright |
|
|
Nonbreaking space |
|
|
Double quotation marks |
The attributes class, style, and size can also be used in the value attribute of the outputFormatted component, as can href constructions. All other HTML tags are ignored.
ADF Faces provides a set of icons used with message components, as shown in Figure 16-4.
If you want to display icons outside of a message component, you use the icon component and provide the name of the icon type you want to display.
Note:
The images used for the icons are determined by the skin the application uses. If you want to change the image, create a custom skin. For more information, see Chapter 20, "Customizing the Appearance Using Styles and Skins".When you use messages in an ADF Faces application, the icons are automatically added for you. You do not have to add them to the message component. However, you can use the icons outside of a message component. To display one of the standard icons defined in the skin for your application, you use the icon component.
To display a standard icon:
From the Component Palette, drag and drop an Icon onto your page.
Expand the Common section and set the name attribute to the name of the icon function as shown in Figure 16-4. For example, if you want to display a red circle with a white X, you would set the name attribute to error.
Expand the Appearance section, and set the shortDesc attribute to the text you want to be displayed as the alternate text for the icon.
To display an image on a page, you use the image component and set the source attribute to the URI where the file is located. The image component also supports accessibility description text by providing a way to link to a long description of the image.
The image component can also be used as a link and can include an image map, however it must be placed inside a goLink component. For more information, see Section 16.5, "Using Images as Links".
To create an image component, drag and drop an Image component from the Component Palette onto your page.
Tip:
If you plan to support changing the
source attribute of the image through active data (for example, data being pushed from the data source will determine the image that is displayed), then you should use the activeImage component instead of the image component. Create an activeImage component by dragging an Image (Active) from the Component Palette.In the Insert Image dialog, set the following:
shortDesc: Set to the text to be used as the alternate text for the image.
source: Enter the URI to the image file.
If you want to include a longer description for the image, in the Property Inspector, set the longDescURL attribute to the URI where the information is located.
ADF Faces provides the commandImageLink component that renders an image as a link, along with optional text. You can set different icons for when the user hovers the mouse over the icon, and for when the icon is depressed or disabled. For more information about the commandImageLink component, see Section 18.2, "Using Buttons and Links for Navigation".
If you simply want an image to be used to navigate to a given URI, you can enclose the image in the goLink component and then if needed, link to an image map.
You can use an image as a goLink component to one or more destinations. If you want to use an image as a simple link to a single destination, use a goLink component to enclose your image, and set the destination attribute of the goLink component to the URI of the destination for the link.
If your image is being used as a graphical navigation menu, with different areas of the graphic navigating to different URIs, enclose the image component in a goLink component and create a server-side image map for the image.
To use an image as one or more goLink components:
Drag and drop a Go Link component from the Component Palette onto the page.
Drag and drop an Image component as a child to the goLink component.
In the Insert Image dialog, set the following:
shortDesc: Set to the text to be used as the alternate text for the image.
source: Enter the URI to the image file.
If different areas of the image are to link to different destinations:
Create an image map for the image and save it to the server.
Set the imageMapType attribute to server.
Select the goLink component and set the destination attribute to the URI of the image map on the server.
If the whole image is to link to a single destination, select the goLink component and enter the URI of the destination as the value of the destination attribute.
ADF Faces provides the statusIndicator component that you can use to indicate server activity. What displays depends both on the skin your application uses as well as how your server is configured. By default, the following are displayed:
When your application is configured to use the standard data transfer service, during data transfer the following animated spinning icon is displayed:
When the server is not busy, the following icon is displayed:
When your application is configured to use the Active Data Service (ADS), what the status indicator displays depends on how ADS is configured.
Note:
ADS allows you to bind your application to an active data source. You must use the Fusion technology stack in order to use ADS. For more information, see the "Using the Active Data Service" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.ADS can be configured to have data pushed to the model. Table 16-3 shows the icons that are used to display server states for push mode (note that the icons are actually animated).
After you drop a status indicator component onto the page, you can use skins to change the actual image files used in the component. For more information about using skins, see Chapter 20, "Customizing the Appearance Using Styles and Skins".
To use the status indicator icon:
Create a statusIndicator component by dragging and dropping a Status Indicator from the Component Palette.
Use the Property Inspector to set any needed attributes.
The ADF Faces media component allows you to include video and audio clips on your application pages.
The media control handles two complex aspects of cross-platform media display: determining the best player to display the media, and sizing the media player.
You can specify which media player is preferred for each clip, along with the size of the player to be displayed for the user. By default, ADF Faces uses the MIME type of the media resource to determine the best media player and the default inner player size to use, although you can specify the type of content yourself, using the contentType attribute.
You can specify which controls are to be available to the user, and other player features such as whether or not the clip should play automatically, and whether or not it should play continuously or a specified number of times.
You can specify which media player is to play your video or audio clip using the player attribute, choosing from Real Player, Windows Media Player, or Apple Quick Time Player.
Alternatively, you can create a link in the page that starts the playing of the media resource based on the user agent's built-in content type mapping. The media control attempts to pick the appropriate media player using the following steps:
If the primary MIME type of the content is image, the built-in user-agent support is used.
If a media player has been specified by the player attribute, and that player is available on the user agent and can display the media resource, that player is used.
If one player is especially good at playing the media resource and that player is available on the user agent, that player is used.
If one player is especially dominant on the user agent and that player can play the media resource, that player is used.
The player connected to the link provided on the page is used.
You can define the display size using two different schemes:
Define the size in pixels of the complete display, including the whole player area, which includes the media content area. For this scheme, use the width and height attributes.
This scheme is difficult to use, because it is difficult to define a suitable width and height to use across different players and different player control configurations.
Define the size in pixels of only the media content area. For this scheme, use the innerWidth and innerHeight attributes.
This is the preferred scheme, because you control the amount of space allocated to the player area for your clip.
If you do not specify a size for the media control using one of the schemes, a default inner size, determined by the content type of the media resource, is used. While this works well for audio content, for video content, it can cause content to be clipped or occupy too much space.
If you specify dimensions from both schemes, such as a height and an innerHeight, the overall size defined by the height attribute is used. Similarly, if you specify both a width and an innerWidth, the width attribute is used.
Using the controls attribute of the media component, you can define what player controls are displayed for controlling the media playback.
Because the set of controls available varies between players, you define what set of controls to display in a general way, rather than listing actual controls. For example, you can have the player display all controls available, the most commonly used controls, or no controls.
As an example, Example 16-4 uses the all setting for a media component.
Figure 16-5 shows how the player is displayed to the user.
By default, playback of a clip will not start until the user starts it using the displayed controls. You can specify that playback is to start as soon as the clip is loaded by setting the autostart attribute to true.
Once started, by default, the clip with play through once only. If the users have controls available, they can replay the clip. However, you can specify that the clip is to play back a fixed number of times, or loop continuously, by setting a value for the playCount attribute. Setting the playCount attribute to 0 replays the clip continuously. Setting the attribute to some other number plays the clip the specified number of times.
Once you add a media component to your page, you can configure the media player to use by default, the size of the player and screen, the controls, and whether or not the clip should replay.
To include an audio or video clip in your application page:
Drag and drop a Media component from the Component Palette onto the page.
In the Insert Media dialog, set the following attributes:
source: Enter the URI to the media to be played.
standbyText: Enter a message that will be displayed while the content is loading.
Expand the Common section of the Property Inspector and set the following attributes:
player: Select the media player that should be used by default to play the clip. You can choose from Real Player, Windows Media Player, or Apple Quick Time Player.
Alternatively, you can create a link in the page that starts the playing of the media resource based on the user agent's built-in content type mapping. The media control attempts to pick the appropriate media player using the following steps:
If the primary MIME type of the content is image, the built-in user-agent support is used.
If a media player has been specified by the player attribute, and that player is available on the user agent and can display the media resource, that player is used.
If one player is especially good at playing the media resource and that player is available on the user agent, that player is used.
If one player is especially dominant on the user agent and that player can play the media resource, that player is used.
The player connected to the link provided on the page is used.
autostart: Set to True if you want the clip to begin playing as soon as it loads.
contentType: Enter the MIME type of the media to play. This will be used to determine which player to use, the configuration of the controls, and the size of the display.
Expand the Appearance section of the Property Inspector and set the following attributes:
controls: Select the amount and types of controls you want the player to display, as follows:
all: Show all available controls for playing media on the media player.
Using this setting can cause a large amount of additional space to be required, depending on the media player used.
minimal: Show a minimal set of controls for playing media on the media player.
This value gives users control over the most important media playing controls, while occupying the least amount of additional space on the user agent.
none: Do not show any controls for the media player and do not allow control access through other means, such as context menus.
You would typically use this setting only for kiosk-type applications, where no user control over the playing of the media is allowed. This setting is typically used in conjunction with settings that automatically start the playback, and to play back continuously. For details of these settings, see Section 16.7.4, "Automatic Start and Repeated Play".
noneVisible: Do not show any controls for the media player, but allow control access through alternate means, such as context menus.
You would typically use this value only in applications where user control over the playing of the media is allowed, but not encouraged. As with the none setting, this setting is typically used in conjunction with settings that automatically start the playback, and to play back continuously. For details of these settings, see Section 16.7.4, "Automatic Start and Repeated Play".
typical: Show the typical set of controls for playing media on the media player.
This value, the default, gives users control over the most common media playing controls, without occupying an inordinate amount of extra space on the user agent.
For information about setting the height, width, innerHeight and innerWidth attributes, see Section 16.7.2, "Display Size".
Expand the Behavior section and set the playCount attribute to the number of times you want the media to play. Set it to 0 if you want the media to replay continuously.
Example 16-5 shows an af:media component in the source of a page. The component will play a video clip starting as soon as it is loaded and will play it continuously until stopped by the user. The player will display all the available controls.
|
 Copyright © 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
