3 Component Support

This chapter describes the Apache MyFaces Trinidad components that are supported by ADF Mobile browser.

This chapter includes the following sections:

3.1 About Apache My Faces Trinidad Components

ADF Mobile browser supports more than 60 of the Apache MyFaces Trinidad components, enabling you to build applications with a rich component set that renders appropriately to the screens of mobile devices. For more information, refer to the Apache MyFaces Trinidad site (http://myfaces.apache.org/trinidad/).

3.1.1 Supported Features

ADF Mobile browser supports the following renderer-specific features:

3.1.2 Partial Page Rendering

The high-latency and low-bandwidth of networks in mobile environments decrease application responsiveness for mobile users. Screens refresh slowly, diminishing the mobile user experience. ADF Mobile browser's support of Partial Page Rendering (PPR) compensates for the negative impact that slow connections have on screen updates by minimizing the amount of data requested from the server; using PPR, mobile device screen updates do not require a full refresh. Browsers that do not support AJAX (Asynchronous JavaScript and XML) use full-page rendering instead of PPR. For example, a page submission on basic HTML browsers (which do not support JavaScript) results in the refresh of a full page.

Note:

Browsers for BlackBerry 4.5 (and earlier versions) do not support PPR. Specifying the autosubmit attribute on certain form-related components results in the submission of the page after the user exits the field. A full, not partial, refresh of the page then follows.

3.1.3 Dialogs

ADF Mobile browser supports dialogs, pages used by applications to obtain user input. Because mobile browsers cannot open a new window that contains a dialog (a pop-up window), they present dialogs as new pages within the main browser window after they automatically preserve the state of the current page.

3.1.4 Rendering Specific to the BlackBerry Browser 4.5 and Earlier Versions

On browsers for BlackBerry 4.5 and earlier versions, the bullets in a list sublevel (such as those in a tr:panelList component) appear large and are not indented. BlackBerry's table handling may affect complex layouts, as its browser does not allow horizontal scrolling. Instead, it wraps a table row onto multiple display lines which may disturb the layout. For more information, see Chapter 6, "Design Guidelines for BlackBerry 4.2 to 4.5."

3.2 Input Components

ADF Mobile browser supports input text fields and lists, core components that support user input.

3.2.1 Creating Input Text Fields

You can create input fields using the following components:

  • tr:inputColor

    Note:

    Mobile browsers do not support an inline chooseColor or a color dialog for the tr:inputColor component.

  • tr:inputDate

  • tr:inputHidden

  • tr:inputText

    Note:

    Basic HTML browsers do not support the autosubmit attribute of the tr:inputText component.

    Note:

    Trinidad optimizes the tr:inputText component for narrow-screen devices (that is, devices with screen width measuring less than 240 pixels). For more information see Chapter 7, "Narrow Screen Support and User Agent Details Support."

3.2.2 Creating Lists

You can create lists using the following components:

  • tr:panelChoice

  • tr:panelList

  • tr:selectBooleanCheckBox

  • tr:selectBooleanRadio

  • tr:selectItem

    Note:

    Mobile browsers do not support the disabled attribute for the tr:selectItem component.

  • tr:selectManyCheckBox

  • tr:selectManyListBox

  • tr:selectOneChoice

  • tr:selectOneListBox

  • tr:selectOneRadio

  • tr:resetButton

Note:

Basic HTML browsers do not support the autosubmit attribute for the tr:resetButton component.

3.3 Output Components

ADF Mobile browser uses the Apache MyFacesTrinidad core components that support output on mobile device applications. These components include those for displaying text and images and also components for displaying, or hiding, text.

3.3.1 Displaying Text

The following components enable you to display text:

  • tr:iterator

  • tr:message

  • tr:messages

    Note:

    Component-specific messages do not display on a mobile browser in the same manner as they do in a desktop browser. Instead, they display in the region where the message component (tr:message or tr:messages) is placed on the web page.

  • tr:outputDocument

  • tr:outputForwarded

  • tr:outputLabel

  • tr:outputText

3.3.2 Displaying Images

The following components enable you to display images:

  • tr:icon

  • tr:image

  • tr:panelTip

3.3.3 Showing (or Hiding) Components

The following components enable showing or hiding items:

  • tr:panelAccordion

    Note:

    Mobile browsers only support a full-page update; they do not support the partialTriggers attribute of the tr:panelAccordion component.

  • tr:panelTabbed

    Note:

    To conserve space within mobile browsers, the renderer intentionally prevents the display of tab bars on both the top and bottom of the tr:panelTabbed component. Valid values for the attribute positions are top and bottom. If both is specified, then the renderer displays the tabs on top.

  • tr:showDetail

    Note:

    For the tr:showDetail component, the disclosure arrow does not display; the [+] and [-] symbols display instead.

  • tr:showDetailHeader

    Note:

    For the tr:showDetailHeader component, the disclosure arrow does not appear on mobile browsers.

  • tr:showDetailItem

    Note:

    For the tr:showDetailItem component, the disclosure arrow does not appear on mobile browsers its flex attribute is not supported.

3.4 Layout Components

The layout components supported by ADF Mobile browser include those for managing the page itself (such as tr:document and tr:form) as well as components for laying out the sections of a page, such as tr:group, tr:panelFormLayout, and tr:panelGroupLayout.

3.4.1 Managing the Page

The following components enable you to manage the page:

  • tr:document

  • tr:form

    Note:

    ADF Mobile browser does not support the defaultCommand attribute of the tr:form component.

  • tr:page

Note:

ADF Mobile browser does not support the tr:page facet of the tr:page component.

3.4.2 Laying Out Sections of the Page

The following ADF Faces core tags support page layout for mobile device applications:

  • tr:group

  • tr:panelBorderLayout

    Note:

    Only the top and bottom facets are supported for the tr:panelBorderLayout component. ADF Mobile browser does not support the following facets:

    • left

    • right

    • start

    • end

    • innerLeft

    • innerRight

    • innerStart

    • innerEnd

    The tr:panelBorderLayout component does not render if you use any of these unsupported facets.

  • tr:panelBox

  • tr:panelFormLayout

  • tr:panelGroupLayout

  • tr:panelHeader

  • tr:panelHorizontalLayout

    Note:

    ADF Mobile browser does not support the halign=end attribute definition for the tr:panelHorizontalLayout component.

  • tr:panelLabelAndMessage

    Note:

    Trinidad optimizes the tr:panelLabelAndMessage component for narrow-screen devices (that is, devices witha screen width measuring less than 240 pixels). For more information see Section 7.1, "Determining Narrow Screen Support."

  • tr:panelPage

  • tr:panelPageHeader

    Note:

    ADF Mobile browser only supports the following facets of the tr:panelPageHeader component:

    • branding

    • brandingApp

    • navigation1

    • navigation2

  • tr:panelRadio

    Note:

    Trinidad optimizes the tr:panelRadio component for narrow-screen devices (that is, devices with a screen width measuring less than 240 pixels). For more information see Section 7.1, "Determining Narrow Screen Support."

  • tr:panelCaptionGroup

3.4.3 Inserting Spaces

The following components control the space allocation on pages:

  • tr:separator

  • tr:spacer

  • tr:subform

3.5 Navigation Components

ADF Mobile browser supports such components as buttons, links, and breadcrumbs that enable users to navigate to other pages of the application, or to external locations.

3.5.1 Creating Buttons

ADF Mobile browser supports the following button types:

  • tr:commandButton

    Note:

    Because the text attribute cannot display if the icon attribute has been set, you can define buttons as text or as an image, but not both. If you set the disabled attribute to true, then a tr:commandButton component with an icon attribute renders as a static image with no links.

  • tr:goButton

See Chapter 8, "Extending ADF Mobile Browser Applications" for information on how to use the tr:goButton component to integrate e-mail, telephony, and Google maps into an application.

3.5.2 Creating Links

ADF Mobile browser supports the following components for creating hyper-links:

See Chapter 8, "Extending ADF Mobile Browser Applications" for information on how to use the tr:goLink component to integrate e-mail, telephony, and Google maps into an application.

3.5.3 Navigation Components

ADF Mobile browser supports the following navigation components:

  • tr:breadcrumbs

    Note:

    Trinidad optimizes the tr:breadcrumbs component for narrow-screen devices (that is, devices with a screen width measuring less than 240 pixels). For more information see Chapter 7, "Determining Narrow Screen Support."

  • tr:commandNavigationItem

    Note:

    tr:commandNavigationItem does not render when you set the disabled attribute to true for the following:

    • tr:selectOneListBox

    • tr:selectOneChoice

    • tr:processChoiceBar

    • tr:navigationPane with hint, "choice"

    • tr:selectRangeChoiceBar

  • tr:navigationPane

    Note:

    tr:navigationPane hint = "choice" with a destination value is not supported for basic HTML browsers.

    Note:

    Trinidad optimizes the tr:navigationPane component for narrow-screen devices (that is, devices with a screen width measuring less than 240 pixels). For more information see Chapter 7, "Determining Narrow Screen Support."

  • tr:train

    Note:

    The tr:train component appears as x of y instead of listing each item. This is a display-only component for ADF Mobile browser; users cannot navigate through the application by clicking the x of y component. To enable navigation, you must add a separate link or button.

  • tr:processChoiceBar

    Note:

    Trinidad optimizes the tr:processChoiceBar component for narrow-screen devices (that is, devices with a screen width measuring less than 240 pixels). For more information see Section 7.1, "Determining Narrow Screen Support."

  • tr:selectRangeChoiceBar

    Note:

    Trinidad optimizes the tr:selectRangeChoiceBar component for narrow-screen devices (that is, devices with a screen width measuring less than 240 pixels). For more information see Chapter 7, "Determining Narrow Screen Support."

3.6 Data Visualization (Graphs and Gauges)

ADF Mobile browser supports data visualization tools (DVTs), described in the "Creating Databound ADF Data Visualization Components" section in Oracle Fusion Middleware Developing Fusion Web Applications with Oracle Application Development Framework.

ADF Mobile browser supports the following types of graphs:

  • area

  • bar

  • bar (horizontal)

  • bubble

  • combination (horizontal bar and line)

  • funnel

  • line

  • pareto

  • pie

  • radar

  • scattar/polar

  • spark

  • stock

ADF Mobile browser supports the following types of gauges:

  • dial

  • status meter

  • status meter (vertical)

  • LED

Because Oracle JDeveloper incorporates DVTs, you can quickly add graphs and gauges. To add these components to an application, first move a data control into the editor window using a drag-and-drop operation and then select Trinidad Gauges or Trinidad Graphs from the context menu. For example, Figure 3-1 illustrates the context menu that appears when you drag a collection into the editor.

Figure 3-1 Creating a DVT by Dragging and Dropping a Data Control

This image is described in the surrounding text

After you select either the Trinidad Graphs or Trinidad Gauges options, the DVT wizard appears and opens to the Component Gallery page, shown in Figure 3-2. You select the DVT type from this page.

Note:

ADF Mobile browser supports only static graphs and gauges, which are rendered as PNG images. Any mobile device that supports this image format can display graphs and gauges.

Figure 3-2 The Component Gallery for the DVT Wizard

This image is described in the surrounding text

3.7 Tables and Trees

ADF Mobile browser applications can display structured data in the rows and columns of a table or hierarchically in and trees.

3.7.1 Creating Tables

ADF Mobile browser supports tables comprised of the following components:

  • tr:table

    Note:

    ADF Mobile browser does not support the allDetailsEnabled attribute for the tr:table component; this attribute is always set to false.

  • tr:column

    Note:

    When you nest tr:column tags to create column groups, the header facets do not render for the column groups.

Creating a single-column table optimizes how tables display on mobile devices.

3.7.2 Creating Trees

ADF Mobile browser supports the tr:tree component.

Note:

tr:tree may not render on basic HTML browsers.

3.8 Generating HTML <meta> Tags

The <meta> tag designates how pages display within a browser. Example 3-1 illustrates examples of <meta> tag usage that include setting an application to display in full-screen mode and setting the viewport width for such devices as the Apple iPhone and iPad. This example also includes a <meta> tag used to designate how a page reloads after a given number of sections.

Example 3-1 Using the <meta> Tag to Set Page Behavior

<meta name="viewport" 
      content="width=device-width, user-scalable=no">
<meta name="apple-mobile-web-app-capable" 
      content="yes">
<meta http-equiv="refresh" 
      content="2;url=./test/index.jspx">

For more information on the use of the <meta> tag in applications running on Apple devices, see the descriptions of the Apple-specific meta tag keys in the "Supported Meta Tags" section of Safari HTML Reference, which is available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).

3.8.1 Using <trh:meta> to Generate HTML <meta> Tags

The <trh:meta> component tag generates an HTML <meta> tag. Example 3-2 shows using this component to:

  • Configure the viewport dimensions on mobile devices.

  • Disable user resizing of the viewport on mobile devices.

  • Enable the home screen bookmark of the web page to launch it in its own process rather than in Safari on iOS devices.

  • Configure the page to navigate to another page after two seconds.

Example 3-2 Using <trh:meta> to Generate Several HTML <meta> Tags

<af:document ...>
  <f:facet name="metaContainer">
    <af:group id="metaContainer">
      <trh:meta name="viewport" 
                content="width=device-width, user-scalable=no"/>
      <trh:meta name="apple-mobile-web-app-capable" 
                content="yes"/>
      <trh:meta type="httpEquiv" 
                name="refresh"
                content="2;url=./test/index.jspx"/>
    </af:group>
   </f:facet>
</af:document>

3.8.1.1 About Default Viewport Size on Mobile Devices

Web pages commonly have a hard-coded width that leaves white space on both sides of the page. While this does not interfere with pages displaying on desktop browsers, it can make the same pages appear too small on mobile devices. In addition, the display of the page controls can be too small for a user's finger tips as well, forcing the users to zoom in to interact with the page. Operating systems for Apple (iOS), Google (Android), and Micosoft (Windows Phone 7) assume a standard viewport width and render the page to fit the smaller screens, thereby causing this scaling to occur when web pages display on mobile devices .

To enable a page to display properly at the native resolution of a mobile device, you can specify the viewport dimension using the viewport meta key within the <trh:meta> tag, as illustrated in Example 3-3.

Example 3-3 Setting the Viewport Dimensions

<af:document ...>
   <f:facet name="metaContainer">
     <trh:meta name="viewport" 
               content="width=device-width"/>
   </f:facet>
   ...
 </af:document>

You can set a specific numeric value for pixels for the width property of the viewport meta key or you can use the device-width constant as shown in Example 3-3. On Apple (iOS) systems, the value set for the page's width in both the portrait and landscape orientations is the same (that is, for the landscape width, the Safari browser uses the value set for the portrait width).

Note:

The pixels on high-resolution displays, such as Retina on iPhone 4, do not have a one-to-one match to pixels on a lower-resolution devices such as iPhone 3GS. Despite this, the number of pixels defined for the width property for an iPhone 3GS equates to the same physical length on the iPhone 4, even though the iPhone 4 has more display pixels.

3.9 Unsupported Components and Attributes

ADF Mobile browser does not support some Apache MyFaces Trinidad components or certain component attributes.

3.9.1 Unsupported Components

ADF Mobile browser does not support the following components:

  • tr:chart

  • tr:chooseColor

  • tr:chooseDate

  • tr:inputFile

  • tr:inputListOFVariables

  • tr:inputNumberSpinbox

  • tr:legend

  • tr:media

  • tr:navigationTree

  • tr:panelButtonBar

  • tr:panelPopup

  • tr:panelSideBar

  • tr:poll

  • tr:progressIndicator

  • tr:selectManyShuttle

  • tr:selectOrderShuttle

  • tr:singleStepButtonBar

  • tr:statusIndicator

  • tr:switcher

  • tr:treeTable

3.9.2 Unsupported Attributes

ADF Mobile browser does not support the following attributes on any Apache MyFaces Trinidad component.

  • accessKey

  • shortDesc (tooltip)