Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number B31973-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

15 Presenting Data Using Output Components

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:

15.1 Introduction to Output Text, Image, Icon, and Media Components

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.

Tip:

The graphic used for each icon is determined by the skin used in the application. If you would like to change the icon's graphic, you must create a new skin. For more information, see Chapter 19, "Customizing the Appearance Using Styles and Skins".

To display an image on a page, you use the image component. Images can also be used as links (including image maps). The media component can play back an audio clip or a video clip. Both components have attributes so that you can define how the item is to be presented in the page.

15.2 Displaying Output Text and Formatted Output Text

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 15-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 15-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 property to specify whether or not special HTML and XML characters are escaped for the current markup language. By default, characters are escaped.

Example 15-2 illustrates two outputText components, the first of which uses the default value of true for the escape property, and the second has the attribute set to false.

Example 15-2 Output Text With and Without the escape Property Set

<af:outputText value="&lt;h3>output &amp; heading&lt;/h3>"/>
<af:outputText value="&lt;h3>output &amp; heading&lt;/h3>"
               escape="false"/>

Figure 15-1 shows the different effects seen in a browser of the two different settings of the escape property.

Figure 15-1 Using the escape Property for Output Text

Effects in a browser of different escape property values

You should avoid setting the escape property 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 19, "Customizing the Appearance Using Styles and Skins".

Example 15-3 shows an outputFormatted component displaying only a few words of its value in bold.

Example 15-3 Using outputFormatted to Bold Some Text

<af:outputFormatted value="&lt;b>This is in bold.&lt;/b> This is not bold"/>

Figure 15-2 shows how the component displays the text.

Figure 15-2 Text Formatted Using the outputFormatted Component

Text Formatted Using the outputFormatted Component

Table 15-1 lists the formatting codes allowed for formatting values.

Table 15-1 Formatting Codes for Use in af:outputFormatted Values

Formatting Code Effect

<br>

Line break

<hr>

Horizontal rule

<ol>...</ol><ul>...</ul><li>...</li>

Lists: ordered list, unordered list, and list item

<p>...</p>

Paragraph

<b>...</b>

Bold

<i>...</i>

Italic

<tt>...</tt>

Teletype or monospaced

<big>...</big>

Larger font

<small>...</small>

Smaller font

<pre>...</pre>

Preformatted: layout defined by whitespace and line break characters preserved

<span>...</span>

Span the enclosed text

<a>...</a>

Anchor


Table 15-2 lists the character codes for displaying special characters in the values.

Table 15-2 Character Codes for Use in af:outputFormatted Values

Character Code Character

&lt;

Less than

&gt;

Greater than

&amp;

Ampersand

&reg;

Registered

&copy;

Copyright

&nbsp;

Nonbreaking space

&quot;

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.

Note:

For security reasons, JavaScript is not supported in output values.

15.2.1 How to Display Output 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:

  1. 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.
  2. 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 15-1 and Table 15-2.

    The outputFormatted component also supports the styleUsage attribute whose values are the following predefined styles for the text:

    • inContextBranding

    • instruction

    • pageStamp

    Figure 15-3 shows how the styleUsage values apply styles to the component.

    Figure 15-3 styleUsage Attribute Values

    styleAttribute values

    Note:

    If styleUsage and styleClass attributes are both set, the styleClass attribute takes precedence.

15.3 Displaying Icons

ADF Faces provides a set of icons used with message components, as shown in Figure 15-4.

Figure 15-4 ADF Faces Icons

There are six default icons

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 graphics used for the icons are determined by the skin the application uses. If you want to change the graphic, create a custom skin. For more information, see Chapter 19, "Customizing the Appearance Using Styles and Skins".

15.3.1 How to Display a Standard Icon

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:

  1. From the Component Palette, drag and drop an Icon onto your page.

  2. Expand the Common section and set the name attribute to the name of the icon function.

  3. Expand the Appearance section, and set the shortDesc attribute to the text you want to be displayed as the alternate text for the icon.

15.4 Displaying Images

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 15.5, "Using Images as Links".

To display an image:

  1. To create an image component, drag and drop an Image component from the Component Palette onto your page.

  2. 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.

  3. If you want to include a longer description for the image, in the Property Inspector, set the longDescURL attribute to the URI for the information.

15.5 Using Images as Links

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 17.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.

15.5.1 How to Use an Image as One or More Go Links

You can use an image as a Go link 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 go links:

  1. Drag and drop a Go Link component from the Component Palette onto the page.

  2. Drag and drop an Image component as a child to the goLink component.

  3. 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.

  4. 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.

  5. 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.

15.6 Downloading Files

You can create a way for users to download files by creating an action component such as a command button and associating it with a fileDownloadActionListener tag. When the user selects or clicks the action component, a popup dialog is displayed that allows the user to select different download options, as shown in Figure 15-5.

Figure 15-5 File Download Dialog

File download dialog

The fileDownloadActionListener tag is used declaratively to allow an action component such as command button, command link, or menu item to programmatically send the contents of a file to the user. You can also declare a specific content type or file name. Because file download must be processed with an ordinary request instead of the XMLHttp AJAX requests, the parent component's partialSubmit attribute, if supported, must be set to false. Using the fileDownloadActionListener tag is the only supported way to perform file download within a region.

Tip:

For information about uploading a file to the server, see Section 9.9, "Using File Upload".

After the content has been sent to the browser, how that content is displayed or saved depends on the option selected in the dialog. If the Open with option was selected, the application associated with that file type will be invoked to display the content. For example, a text file may result in Notepad being started. If the Save to Disk option was selected, depending on the browser, a popup dialog may appear to select a file name and a location in which to store the content.

Example 15-4 shows the tags of a command button with the fileDownloadActionListener tag to download the file content Hi there! to the user.

Example 15-4 File Download Using Command Button and fileDownloadActionListener Tag

<af:commandButton value="Say Hello">
  <af:fileDownloadActionListener filename="hello.txt"
      contentType="text/plain; charset=utf-8"
      method="#{bean.sayHello}"/>
</af:commandButton>

Example 15-5 shows the managed bean method used to process the file download.

Example 15-5 Managed Bean Method Used to Process File Download

public void sayHello(FacesContext context, OutputStream out) throws IOException{
  OutputStreamWriter w = new OutputStreamWriter(out, "UTF-8");
  w.write("Hi there!");
   . . .
}

15.6.1 How to Create a File Download

To allow users to download a file, create an action component, and then add a fileDownloadActionListener tag as a child component of the action component.

To create a file download mechanism:

  1. From the Component Palette, drag and drop any action component to your page (for more information about action components, see Section 17.2, "Using Buttons and Links for Navigation").

  2. Expand the Operations section of Component Palette, and drag and drop the File Download Action Listener tag as a child to the action component.

  3. In the Property Inspector set the following attributes:

    • contentType: Specify the MIME type of the file, for example text/plain, text/csv, application/pdf, and so on.

    • filename: Specify the proposed file name for the object. When the file name is specified, a Save File dialog will typically be displayed, though this is ultimately up to the browser. If the name is not specified, the content will typically be displayed inline in the browser if possible.

    • method: Specify the method that will be used to download the file contents. The method takes two arguments, a FacesContext and an OutputStream. The OutputStream object will be automatically closed, so the sole responsibility of this method is to write all bytes to the OutputStream object.

    For example, the code for a command button would be similar to the following:

    <af:commandButton text="Load File">
      <af:fileDownloadActionListener contentType="text/plain"
          filename="MyFile.txt"
          method="#(mybean.LoadMyFile"/>
    </af:commandButton>
    

15.7 Playing Video and Audio Clips

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.

15.7.1 Media Players

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 link player is used.

15.7.2 Display Size

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.

15.7.3 Controls

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 15-6 uses the all setting for a media component.

Example 15-6 Controls for a Media Player

<af:media source="/images/myvideo.wmv" controls="all"/>

Figure 15-6 shows how the player is displayed to the user.

Figure 15-6 Media Player with All Controls

Media player with all controls

15.7.4 Automatic Start and Repeated Play

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.

15.7.5 How to Play Audio and Video Clips

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:

  1. Drag and drop a Media component from the Component Palette onto the page.

  2. 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.

  3. 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 link player 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.

  4. 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 15.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 15.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 15.7.2, "Display Size".

  5. 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 15-7 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.

Example 15-7 Media Component to Play a Video Clip Continuously

<af:media source="/components/images/seattle.wmv" playCount="0"
          autostart="true" controls="all"
          innerHeight="112" innerWidth="260"
          shortDesc="My Video Clip" 
          standbyText="My video clip is loading"/>