6 Creating the MAF AMX User Interface

6.2.1 How to Use a View Component

A View (view element in a MAF AMX file) is a core page structure component that is automatically inserted into a MAF AMX file when the file is created. This component provides a hierarchical representation of the page and its structure and represents a single MAF AMX page.

For more information, see Tag Reference for Oracle Mobile Application Framework.

6.2.2 How to Use a Panel Page Component

A Panel Page (panelPage element in a MAF AMX file) is a component that allows you to define a scrollable area of the screen for laying out other components.

By default, when you create a MAF AMX page, Oracle Enterprise Pack for Eclipse automatically creates and inserts a Panel Page component into the page. When you add components to the page, they will be inserted inside the Panel Page component.

To prevent scrolling of certain areas (such as a header and footer of the page) and enable stretching when orientation changes, you can specify a Facet component for your Panel Page. The Panel Page's header Facet includes the title placed in the Navigation Bar of each page. For information about other types of Facet components that the Panel Page can contain, see Section 6.2.7, "How to Use a Facet Component."

Example 6-2 shows the panelPage element defined in a MAF AMX file. This Panel Page contains a header Facet.

<amx:panelPage id="pp1">
   <amx:facet name="header">
      <amx:outputText id="ot1" value="Welcome"/>
   </amx:facet>
</amx:panelPage>

For more information, see Tag Reference for Oracle Mobile Application Framework.

6.2.3 How to Use a Panel Group Layout Component

The Panel Group Layout component is a basic layout component that lays out its children horizontally or vertically. In addition, there is a wrapping layout option that enables child components to flow across and down the page.

To create the Panel Group Layout component, use the Palette.

To add the Panel Group Layout component:

1. In the Palette, open the MAF AMX pane and drag and drop a Panel Group Layout to the MAF AMX page.

2. Insert the desired child components into the Panel Group Layout component.

3. To add spacing between adjacent child components, insert the Spacer (spacer) component, also available from the MAF AMX pane of the Palette.

4. Use the Properties window to set the component attributes. For more information, see Tag Reference for Oracle Mobile Application Framework.

Example 6-3 shows the panelGroupLayout element defined in a MAF AMX file.

<amx:panelGroupLayout styleClass="prod" id="pgl1">
   <amx:outputText styleClass="prod-label" value="Screen Size:" id="ot1"/>
</amx:panelGroupLayout>

6.2.4 How to Use a Panel Form Layout Component

The Panel Form Layout (panelFormLayout) component positions components so that their labels and fields align horizontally. In general, the main content of the Panel Form Layout component is comprised of input components (such as Input Text) and selection components (such as Choice). If a child component with a label attribute defined is placed inside the Panel Form Layout component, the child component's label and field are aligned and sized based on the Panel Form Layout definitions. Within the Panel Form Layout, the label area can either be displayed on the start side of the field area or on a separate line above the field area. Separate lines are used if the labelPosition attribute of the Panel Form Layout is set to topStart, topCenter, or topEnd. Otherwise the label area appears on the start side of the field area. Within the label area, the labelPosition attribute controls where the label text can be aligned:

• to the start side (labelPosition="start" or labelPosition="topStart")

• to the center (labelPosition="center" or labelPosition="topCenter")

• to the end side (labelPosition="end" or labelPosition="topEnd")

Within the field area, the fieldHalign attribute controls where the field content can be aligned:

• to the start side (fieldHalign="start")

• to the center (fieldHalign="center")

• to the end side (fieldHalign="end")

Within the Panel Form Layout, the child components can be placed in one or more columns using maxColumns and rows attributes. These attributes should be used in conjunction with labelWidth, fieldWidth, labelPosition, and showHorizontalDividers attributes to obtain the optimal multi-column layout.

To add the Panel Form Layout component:

1. In the Palette, drag and drop a Panel Form Layout component to the MAF AMX page.

2. In the New Panel Form Layout dialog, set the component's attributes. For more information, see Tag Reference for Oracle Mobile Application Framework.

Example 6-4 shows the panelFormLayout element defined in a MAF AMX file.

<amx:panelFormLayout styleClass="prod" id="pfl1">
   <amx:panelLabelAndMessage label="Type" id="plm1">
      <amx:commandLink text="Personal" action="edittype" id="cl1"/>
   </amx:panelLabelAndMessage>
</amx:panelFormLayout>

6.2.5 How to Use a Panel Stretch Layout Component

The Panel Stretch Layout (panelStretchLayout) component manages three child Facet components: top, bottom, and center (see Example 6-5). You can use any number and combination of these facets.

<amx:panelStretchLayout id="psl1">
   <amx:facet name="top">
   </amx:facet>
   <amx:facet name="center">
   </amx:facet>
   <amx:facet name="bottom">
   </amx:facet>
</amx:panelStretchLayout>

If an attempt is made to represent the Panel Stretch Layout component as a set of three rectangles stacked one on top of another, the following would apply:

• The height of the top rectangle is defined by the natural height of the top facet.

• The height of the bottom rectangle is defined by the natural height of the bottom facet.

• The rest of the vertical space is distributed to the rectangle in the middle. If the height of this rectangle is smaller than the value defined for Center.height and the scrollPolicy attribute of the panelStretchLayout is set to either scroll or auto, then scroll bars are added.

To add the Panel Stretch Layout component:

1. In the Palette, drag and drop a Panel Stretch Layout onto the MAF AMX page.

2. Review the created child Facet components and, if necessary, remove some of them.

3. Use the Properties window to set the component attributes. For more information, see Tag Reference for Oracle Mobile Application Framework.

6.2.6 How to Use a Panel Label And Message Component

Use the Panel Label And Message (panelLabelAndMessage) component to place a component which does not have a label attribute. These components usually include an Output Text, Button, or Link.

To add the Panel Label And Message component:

1. In the MAF AMX pane of the Palette, drag and drop a Panel Label And Message component into a Panel Group Layout component.

2. In the New Panel Label and Message dialog, set the component's attributes. For more information, see Tag Reference for Oracle Mobile Application Framework.

Example 6-4 shows the panelLabelAndMessage element defined in a MAF AMX file. The label attribute is used for the child component.

<amx:panelLabelAndMessage label="Phone" id="plm1">
   <amx:outputText value="212-555-0123" id="ot1"/>
</amx:panelLabelAndMessage>

6.2.7 How to Use a Facet Component

You use the Facet (facet) component to define an arbitrarily named facet, such as a header or footer, on the parent layout component. The position and rendering of the Facet are determined by the parent component.

The MAF AMX page header is typically represented by the Panel Page component (see Section 6.2.2, "How to Use a Panel Page Component") in combination with the Header, Primary, and Secondary facets:

• Header facet: contains the page title.

• Primary Action facet: represents an area that appears in the left corner of the header bar and typically hosts Button or Link components, but can contain any component type.

• Secondary Action facet: represents an area that appears in the right corner of the header bar and typically hosts Button or Link components, but can contain any component type.

The MAF AMX page footer is represented by the Panel Page component (see Section 6.2.2, "How to Use a Panel Page Component") in combination with the footer facet:

• Footer facet: represents an area that appears below the content area and typically hosts Button or Link components, but can contain any component type.

Example 6-7 shows the facet element declared inside the Panel Page container. The type of the facet is always defined by its name attribute (see Table 6-2).

<amx:panelPage id="pp1">
   <amx:facet name="footer">
      <amx:commandButton id="cb2" icon="folder.png"
                         text="Move (#{myBean.mailcount})"
                         action"move"/>
   </amx:facet>
</amx:panelPage>

Table 6-2 lists predefined Facet types that you can use with specific parent components.

To add the Facet component:

You can use the context menu displayed on the Outline pane to add a Facet component as a child of another component. The context menu displays options that are valid for your selected parent component.

To add a Facet, first select the parent component in the Outline or Source editor, and complete one of the following steps:

• Right-clicking the amx:PanelPage entry in the Outline lets you enter a Facet, as Figure 6-2 shows.

  Figure 6-2 Using Context Menu to Add Facet to Panel Page

  
  

Alternatively:

1. In the Palette, drag and drop a Facet component into another component listed in Table 6-2.

2. In the Properties window, set the component's attributes. For more information, see Tag Reference for Oracle Mobile Application Framework.

6.2.8 How to Use a Popup Component

Use the Popup (popup) component to display a popup window. You can declare this component as a child of the View component.

You can use the following operations in conjunction with the Popup component:

• Close Popup Behavior (closePopupBehavior) operation represents a declarative way to close the Popup in response to a client-triggered event.

• Show Popup Behavior (showPopupBehavior) operation represents a declarative way to show the Popup in response to a client-triggered event specified using the type attribute of the Show Popup Behavior.

  The popupId attribute of the Show Popup Behavior specifies the unique identifier of the Popup component relative to its parent component. The alignId attribute of the Show Popup Behavior specifies the unique identifier of the UI component relative to which the Popup is to be aligned. Since setting identifiers manually is tedious and can lead to invalid references, you set values for these two attributes using an editor that is integrated with the standard Properties window. There is an Audit rule that is specifically defined to validate these identifiers (see Section 5.3.2.4, "What You May Need to Know About Element Identifiers and Their Audit").

  The decoration attribute of the Show Popup Behavior allows you to configure the Popup to have an anchor pointing to the component that matches the specified alignId. You do so by setting the decoration attribute to anchor (the default value is simple).

  Note:

  There is no need to define decoration="anchor" to use the alignId attribute. When using decoration="anchor", if the alignId attribute is not specified or a match is not found for the alignId, the decoration defaults to simple resulting in minimal ornamentation of the Popup component.

  Values you set for the align attribute of the Show Popup Behavior indicate where the alignment of the Popup component is to be positioned if there is enough space to satisfy that positioning. When there is not enough space, alternate positioning is chosen by MAF.

  Tip:

  To center a Popup on the screen, you should set the alignId attribute of the Panel Page component, and then use the align="center".

  For more information on the Show Popup Behavior component's attributes and their values, see Tag Reference for Oracle Mobile Application Framework.

Example 6-8 shows popup and showPopupBehavior elements defined in a MAF AMX file.

<amx:view>
   <amx:panelPage id="panelPage1">
      <amx:commandButton id="commandButton1" text="Show Popup">
         <amx:showPopupBehavior popupId="popup1" type="action"
                                align="topStart" alignId="panelPage1" 
                                decoration="anchor"/>
      </amx:commandButton>
   </amx:panelPage>
   <amx:popup id="popup1" 
              animation="slideUp" 
              autoDismiss="true"
              backgroundDimming="off"/>
</amx:view>

Popup components can display validation messages when the user input errors occur. For more information, see Section 6.9, "Validating Input."

To set a Popup child:

1. Select the popup element in the Outline pane and click the right mouse button.

2. Select Add Child from a list of Popup components (see Figure 6-3).

   Figure 6-3 Selecting Popup Child attribute from List

   
   

3. Select the Popup component to be displayed when this Show Popup Behavior is invoked.

A MAF sample application called UIDemo demonstrates how to use the Popup component and how to apply styles to adjust the page layout to a specific pattern. The UIDemo application is available from File > New > MAF Examples.

6.2.9 How to Use a Panel Splitter Component

Use the Panel Splitter (panelSplitter) component to display multiple content areas that may be controlled by a left-side navigation pane. Panel Splitter components are commonly used on tablet devices that have larger display size. These components are typically used with a list on the left and the content on the right side of the display area.

A Panel Splitter can contain a navigator Facet (see Section 6.2.7, "How to Use a Facet Component") which is generated automatically when you drag and drop the Panel Splitter onto a MAF AMX page, and a Panel Item component. The Panel Item (panelItem) component represents the content area of a Panel Splitter. Since each Panel Splitter component must have a least one Panel Item, the Panel Item is automatically added to the Panel Splitter when the Panel Splitter is created. Each Panel Item component can contain any component that a Panel Group Layout can contain (see Section 6.2.3, "How to Use a Panel Group Layout Component").

The left side of the Panel Splitter is represented by a navigator facet (navigator), which is optional in cases where only multiple content with animations is desired (for example, drawing a multicontent area with a Select Button that requires animation when selecting different buttons to switch content). When in landscape mode, this facet is rendered; in portrait mode, a button is placed above the content area and when clicked, the content of the facet is launched in a popup.

When developing for iOS platform, you can configure the Panel Splitter and Panel Item to accommodate the right-to-left language environment by setting their animation attribute to either slideStart, slideEnd, flipStart, or flipEnd. The animation attribute of the Panel Item components overrides the Panel Splitter's animation attribute. For more information, see Tag Reference for Oracle Mobile Application Framework.

Example 6-9 shows the panelSplitter element defined in a MAF AMX file, with the navigator facet used as a child component.

<amx:panelSplitter id="ps1"
               selectedItem="#{bindings.display.inputValue}"
               animation="flipEnd">
   <amx:facet name="navigator">
      <amx:listView id="lv1"
                    value="#{bindings.data.collectionModel}" 
                    var="row"
                    showMoreStrategy="autoScroll"
                    bufferStrategy="viewport>
         ...
      </listView>
   </facet>
   <amx:panelItem id="x">
      <amx:panelGroupLayout>
         ...
      </panelGroupLayout>
   </panelItem>
   <amx:panelItem id="y">
      <amx:panelGroupLayout>
         ...
      </panelGroupLayout>
   </panelItem>
</panelSplitter>

For more examples, see the UIDemo application, available from File > New > MAF Examples.

For more information, see Tag Reference for Oracle Mobile Application Framework.

6.2.10 How to Use a Spacer Component

Use the Spacer (spacer) component to create an area of blank space with a purpose to separate components on a MAF AMX page. You can include vertical and horizontal spaces in a page using the height (for vertical spacing) and width (for horizontal spacing) attributes of the spacer:

To add the Spacer component:

1. In the Components window, drag and drop a Spacer onto the MAF AMX page.

2. Use the Properties window to set the attributes of the component. For more information, see Tag Reference for Oracle Mobile Application Framework.

Example 6-10 shows the spacer element defined in a MAF AMX file.

<amx:outputText id="ot1" value="This is a long piece of text for this page..."/>
<amx:spacer id="s1" height="10"/>
<amx:outputText id="ot2" value="This is some more lengthy text..."/>

6.2.11 How to Use a Table Layout Component

Use the Table Layout (tableLayout) component to display data in a typical table format that consists of rows containing cells.

The Row Layout (rowLayout) component represents a single row in the Table Layout. The Table Layout component must contain either one or more Row Layout components or Iterator components that can produce Row Layout components.

The CellFormat (cellFormat) component represents a cell in the Row Layout. The Row Layout component must contain either one or more CellFormat components, Iterator components, Attribute List Iterator components, or Facet Definition components that can produce CellFormat components.

The Table Layout structure does not allow cell contents to use percentage heights nor can a height be assigned to the overall table structure as a whole. For details, see the description of the following attributes in the Tag Reference for Oracle Mobile Application Framework:

• layout and width attributes of the Table Layout component

• width and height attributes of the Row Layout component

To add the Table Layout component:

1. In the Components window, drag and drop a Table Layout onto the MAF AMX page.

2. Insert the desired number of Row Layout, Iterator, Attribute List Iterator, or Facet Definition child components into the Table Layout component.

3. Insert Cell Format, Iterator, Attribute List Iterator, or Facet Definition child components into each Row Layout component.

4. Use the Properties window to set the attributes of all added components. For more information, see Tag Reference for Oracle Mobile Application Framework.

Example 6-11 shows the tableLayout element and its children defined in a MAF AMX file.

<amx:tableLayout id="tableLayout1"
                 rendered="#{pageFlowScope.pRendered}"
                 styleClass="#{pageFlowScope.pStyleClass}"
                 inlineStyle="#{pageFlowScope.pInlineStyle}"
                 borderWidth="#{pageFlowScope.pBorderWidth}"
                 cellPadding="#{pageFlowScope.pCellPadding}"
                 cellSpacing="#{pageFlowScope.pCellSpacing}"
                 halign="#{pageFlowScope.pHalign}"
                 layout="#{pageFlowScope.pLayoutTL}"
                 shortDesc="#{pageFlowScope.pShortDesc}"
                 summary="#{pageFlowScope.pSummary}"
                 width="#{pageFlowScope.pWidth}">
   <amx:rowLayout id="rowLayout1">
      <amx:cellFormat id="cellFormatA" rowSpan="2" halign="center">
         <amx:outputText id="otA" value="Cell A"/>
      </amx:cellFormat>
      <amx:cellFormat id="cellFormatB" rowSpan="2" halign="center">
         <amx:outputText id="otB" value="Cell B (wide content)"/>
      </amx:cellFormat>
      <amx:cellFormat id="cellFormatC" rowSpan="2" halign="center">
         <amx:outputText id="otC" value="Cell C"/>
      </amx:cellFormat>
   </amx:rowLayout>
   <amx:rowLayout id="rowLayout2">
      <amx:cellFormat id="cellFormatD" halign="end">
         <amx:outputText id="otD" value="Cell D"/>
      </amx:cellFormat>
      <amx:cellFormat id="cellFormatE">
         <amx:outputText id="otE" value="Cell E"/>
      </amx:cellFormat>
   </amx:rowLayout>
</amx:tableLayout>

6.2.12 How to Use a Deck Component

The Deck (deck) component represents a container that shows one of its child components at a time. The transition from one displayed child component (defined by the displayedChild attribute) to another is enabled by the Transition (transition) operation. The transition can take a form of animation. For more information about the transition, see Section 5.2.11, "How to Specify the Page Transition Style."

The Deck can be navigated forward and backwards.

To add the Deck component:

1. In the Components window, drag and drop a Deck onto the MAF AMX page.

2. Insert the desired number of Transition operations and child UI components into the Deck component.

3. Use the Properties window to set the attributes of all added components. For more information, see Tag Reference for Oracle Mobile Application Framework.

Example 6-12 shows the deck element and its children defined in a MAF AMX file. The Deck component's displayedChild attribute to define which child component ID should be displayed. Typically, this is controlled by a component such as a Select One Button or other selection component.

<amx:deck id="deck1"
             rendered="#{pageFlowScope.pRendered}"
             styleClass="#{pageFlowScope.pStyleClass}"
             inlineStyle="width:95px;height:137px;overflow:hidden;
                                    #{pageFlowScope.pInlineStyle}"
             landmark="#{pageFlowScope.pLandmark}"
             shortDesc="#{pageFlowScope.pShortDesc}"
             displayedChild="#{pageFlowScope.pDisplayedChild}">

   <amx:transition triggerType="#{pageFlowScope.pTriggerType}" 
                   transition="#{pageFlowScope.pTransition}"/>
   <amx:transition triggerType="#{pageFlowScope.pTriggerType2}"
                   transition="#{pageFlowScope.pTransition2}"/>
   <amx:commandLink id="linkCardBack1" text="Card Back">>
     <amx:setPropertyListener from="linkCardA"
                              to="#{pageFlowScope.pDisplayedChild}"/>
   </amx:commandLink>
   <amx:commandLink id="linkCardA1" text="Card Front A">
   <amx:setPropertyListener id="setPL1"
                            from="linkCardB"
                            to="#{pageFlowScope.pDisplayedChild}"/>
   </amx:commandLink>
   <amx:commandLink id="linkCardB1" text="Card Front B">
      <amx:setPropertyListener id="setPL2"
                               from="linkCardC"
                               to="#{pageFlowScope.pDisplayedChild}"/>
   </amx:commandLink>
   <amx:commandLink id="linkCardC1" text="Card Front C">
      <amx:setPropertyListener id="setPL3"
                               from="linkCardD"
                               to="#{pageFlowScope.pDisplayedChild}"/>
   </amx:commandLink>
   <amx:commandLink id="linkCardD1" text="Card Front D">
      <amx:setPropertyListener id="setPL4"
                               from="linkCardE"
                               to="#{pageFlowScope.pDisplayedChild}"/>
   </amx:commandLink>
   <amx:commandLink id="linkCardE1" text="Card Front E">
      <amx:setPropertyListener id="setPL5"
                               from="linkCardBack"
                               to="#{pageFlowScope.pDisplayedChild}"/>
   </amx:commandLink>
</amx:deck>

For more information, see Tag Reference for Oracle Mobile Application Framework.

6.2.13 How to Use the Fragment Component

The Fragment (fragment) component enables sharing of MAF AMX page contents. This component is used in conjunction with a MAF AMX fragment file. For more information, see Section 5.3.1.6, "Sharing the Page Contents."

To add the Fragment component:

1. In the Components window, drag and drop a Fragment to the MAF AMX page.

2. Use the Insert Fragment dialog to set the Src attribute of the Fragment to a fragment file (.amxf).

3. Optionally, use the Structure view to add child components, such as an Attribute, Attribute List, or Facet.

4. Use the Properties window to set the attributes of all added components. For more information, see Tag Reference for Oracle Mobile Application Framework.

Example 5-12, "Fragment in MAF AMX Page" shows a fragment element added to a MAF AMX page. Example 5-11, "Fragment Definition" shows the corresponding MAF AMX fragment file.

A MAF sample application called FragmentDemo demonstrates how to create and use the Fragment. This sample application is available from File > New > MAF Examples.

6.3.1 How to Use the Input Text Component

The Input Text (inputText) component represents an editable text field. The following types of Input Text components are available:

• Standard single-line Input Text, which is declared as an inputText element in a MAF AMX file:

  <amx:inputText id="text1" 
                    label="Text Input:" 
                    value="#{myBean.text}" />
  

• Password Input Text:

  <amx:inputText id="text1" 
                 label="Password Input:"
                 value="#{myBean.text}"  
                 secret="true" />
  

• Multiline Input Text (also known as text area):

  <amx:inputText id="text1" 
                 label="Textarea:"
                 value="#{myBean.text}"
                 simple="true"
                 rows="4" />
  

Figure 6-4 shows the Input Text component displayed in the Preview pane. This component has its parameters set as follows:

<amx:inputText id="inputText1"
               label="Input Text"
               value="text"/>

Figure 6-4 Input Text at Design Time

The inputType attribute lets you define how the component interprets the user input: as a text (default), email address, number, telephone number, or URL. These input types are based on the values allowed by HTML5.

To enable conversion of numbers, as well as date and time values that are entered in the Input Text component, you use the Convert Number (see Section 6.3.25, "How to Convert Numerical Values") and Convert Date Time (see Section 6.3.24, "How to Convert Date and Time Values") components.

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples.

On some mobile devices, when the end user taps an Input Text field, the keyboard is displayed (slides up). If an Input Text is the only component on a MAF AMX page, the input focus is on this field and the keyboard is displayed by default when the page loads.

A multiline Input Text may be displayed on a secondary page where it is the only component, in which case the multiline Input Text receives focus when the page loads and the keyboard becomes visible.

Input Text components render and behave differently on iOS and Android-powered devices: on iPhone and iPad, Input Text components may be displayed with or without a border.

When creating an Input Text component, consider the following:

• To input or edit content, the end user has to tap in the field, which triggers a blinking insertion cursor to be displayed at the point of the tap, allowing the end user to edit the content. If the field does not contain content, the insertion cursor is positioned at the start of the field.

• Fields represented by Input Text components may contain default text, typically used as a prompt. When the end user taps a key on the keyboard in such a field, the default text clears when Edit mode is entered. This behavior is enabled and configured through the Input Text's hintText attribute.

• Fields represented by Input Text components do not have a selected appearance. Selection is indicated by the blinking insertion cursor within the field.

• If the end user enters more text than fits in the field, the text content shifts left one character at a time as the typing continues.

• A multiline Input Text component is rendered as a rectangle of any height. This component supports scrolling when the content is too large to fit within the boundaries of the field: rows of text scroll up as the text area fills and new rows of text are added. The end user may flick up or down to scroll rows of text if there are more rows than can be displayed in the given display space. A scroll bar is displayed within the component to indicate the area is being scrolled.

• Password field briefly echoes each typed character, and then reverts the character to a dot to protect the password.

• The appearance and behavior of the Input Text component on iOS can be customized (see Section 6.3.1.1, "Customizing the Input Text Component").

6.3.1.1 Customizing the Input Text Component

MAF AMX provides support for the input capitalization and correction on iOS-powered devices, as well as the ability to override the return button located at the bottom right of the mobile devices's soft keypad (see Figure 6-5) such that this button would appear and act as the Go or Search button (see Figure 6-6) and trigger a DataChangeEvent for a single-line Input Text component.

Figure 6-5 Return Button on iOS-Powered Device at Runtime

Figure 6-6 Go and Search Buttons on iOS at Runtime

Table 6-3 lists attributes of the Input Text component that allow you to customize the appearance and behavior of that component and the soft keypad that is used to enter values into fields represented by the Input Text.

Table 6-3 Input-Customizing Attributes of the Input Text Component

Attribute	Values	Description
keyboardDismiss	normal: use the operating system's default. go: request the field to act like a trigger for behavior. search: request the field to act like a search field that triggers a lookup.	Indicates how the text field is to be used. If go or search is specified, dismissing the keypad causes the input to blur on both iOS and Android platforms. Even though support for Go and Search buttons on iOS is subject to change and might be terminated at any time, on some iOS-powered devices keypads are provided with the enhanced functionality. For example, instead of displaying a return button on a single-line text field, it might already replace it with a Go or Search button.
autoCapitalize	auto: use the operating system's default. sentences: request that sentences comprising the input start with a capital letter. none: request that no capitalization be applied automatically to the input. words: request that words comprising the input start with capital letters. characters: request that each character typed as an input become capitalized.	Requests special treatment by iOS for capitalization of values while the field represented by the Input Text is being edited. Note that setting this property has no impact on Android.
autoCorrect	auto: use the operating system's default. on: request auto-correct support for the input. off: request auto-correct of the input be disabled.	Requests special treatment by iOS for correcting values while the field represented by the Input Text is being edited. Note that setting this property has no impact on Android.

Since iOS provides limited support for auto-capitalization and auto-correction on its device simulator, you must test this functionality on an iOS device.

6.3.2 How to Use the Input Number Slider Component

The Input Number Slider (inputNumberSlider) component enables selection of numeric values from a range of values by using a slider instead of entering the value by using keys. The filled portion of the trough or track of the slider visually represents the current value.

The Input Number Slider may be used in conjunction with the Output or Input Text component to numerically show the value of the slider. The Input Text component also allows direct entry of a slider value: when the end user taps the Input Text field, the keyboard in numeric mode slides up; the keyboard can be dismissed by either using the slide-down button or by tapping away from the slider component.

The Input Number Slider component always shows the minimum and maximum values within the defined range of the component.

Example 6-13 demonstrates the inputNumberSlider element defined in a MAF AMX file.

<amx:inputNumberSlider id="slider1" value="#{myBean.count}"/>

Figure 6-7 shows the Input Number Slider component displayed in the Preview pane. This component has its parameters set as follows:

<amx:inputNumberSlider id="inputNumberSlider1"
                       label="Input Number"
                       minimum="0"
                       maximum="20"
                       stepSize="1"
                       value="10"/>

Figure 6-7 Input Number Slider at Design Time

To enable conversion of numbers that are entered in the Input Number Slider component, you use the Convert Number component (see Section 6.3.25, "How to Convert Numerical Values").

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples.

Similar to other MAF AMX UI components, the Input Number Slider component has a normal and selected state. The component is in its selected state at any time it is touched. To change the slider value, the end user touches, and then interacts with the slider button.

The Input Number Slider component has optional imageLeft and imageRight attributes which point to images that can be displayed on either side of the slider to provide the end user with additional information.

6.3.3 How to Use the Input Date Component

The Input Date (inputDate) component presents a popup input field for entering dates. The default date format is the short date format appropriate for the current locale. For example, the default format in American English (ENU) is mm/dd/yy. The inputType attribute defines if the component accepts date, time, or date and time as an input. The time zone depends on the time zone configured for the mobile device, and, therefore, it is relative to the device. At runtime, the Input Date component has the device's native look and feel.

Example 6-14 demonstrates the inputDate element defined in a MAF AMX file. The inputType attribute of this component is set to the default value of date. If the value attribute is read-only, it can be set to either an EL expression or any other type of value; if value is not a read-only attribute, it can be specified only as an EL expression.

<amx:inputDate id="inputDate1" label="Input Date" value="#{myBean.date}"/>

For more information, see the following:

• Tag Reference for Oracle Mobile Application Framework

• HTML5 global dates and times defined by W3C

• CompGallery, available from File > New > MAF Examples.

6.3.4 How to Use the Output Text Component

MAF AMX provides the Output Text (outputText) component for you to use as a label to display text.

Example 6-15 demonstrates the outputText element defined in a MAF AMX file.

<amx:outputText id="ot1"
                value="output" 
                styleClass="#{pageFlowScope.pStyleClass}"/>

Figure 6-8 shows the Output Text component displayed in the Preview pane.

Figure 6-8 Output Text at Design Time

You use the Convert Number (see Section 6.3.25, "How to Convert Numerical Values") and Convert Date Time (see Section 6.3.24, "How to Convert Date and Time Values") converters to facilitate the conversion of numerical and date-and-time-related data for the Output Text components.

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery and UIDemo, MAF sample applications available from File > New > MAF Examples.

6.3.5 How to Use Buttons

The Button (commandButton) component is used to trigger actions (for example, Save, Cancel, Send) and to enable navigation to other pages within the application (for example, Back: see Section 6.3.5.7, "Enabling the Back Button Navigation" for more information).

You may use the Button in one of the following ways:

• Button with a text label.

• Button with a text label and an image icon.

  Note:

  You may define the icon image and placement as left or right of the text label.

• Button with an image icon only (for example, the " + " and " - " buttons for adding or deleting records).

MAF supports one default Button type for the following three display areas:

1. Buttons that appear in the top header bar: in MAF AMX pages, the header is represented by the Panel Page component (see Section 6.2.2, "How to Use a Panel Page Component") in combination with the header, primary, and secondary facets, which is typical on iPhones:

   • Header Facet contains the page title.

   • Primary Action Facet represents an area that appears in the left corner of the header bar and typically hosts Button or Link components, but can contain any component type.

   • Secondary Action Facet represents an area that appears in the right corner of the header bar and typically hosts Button or Link components, but can contain any component type.

2. Buttons that appear in the content area of a page.

3. Buttons that appear in the footer bar of a page. In MAF AMX pages, the footer is represented by the Panel Page component (see Section 6.2.2, "How to Use a Panel Page Component") in combination with the footer facet:

   • Footer Facet represents an area that appears below the content area and typically hosts Button or Link components, but can contain any component type.

All Button components of any type have three states:

1. Normal.

2. Activated: represents appearance when the Button is tapped or touched by the end user. When a button is tapped (touch and release), the button action is performed. Upon touch, the activated appearance is displayed; upon release, the action is performed. If the end user touches the button and then drags their finger away from the button, the action is not performed. However, for the period of time the button is touched, the activated appearance is displayed.

3. Disabled.

The appearance of a Button component is defined by its styleClass attribute that you set to an adfmf-commandButton-<style>. You can apply any of the styles detailed in Table 6-4 to a Button placed in any valid location within the MAF AMX page.

There is a Rounded style (adfmf-commandButton-rounded) that you can apply to a Button to decorate it with a thick rounded border (see Figure 6-9). You can define this style in combination with any other style.

Figure 6-9 Rounded Button at Design Time

MAF AMX provides a number of additional decorative styles (see Section 6.3.5.5, "Using Additional Button Styles").

There is a particular order in which MAF AMX processes the Button component's child operations and attributes. For more information, see Section 6.3.5.8, "What You May Need to Know About the Order of Processing Operations and Attributes."

<amx:panelPage id="pp1">
   <amx:facet name="primary">
      <amx:commandButton id="cb1" 
                         text="Cancel"
                         action="cancel" 
                         actionListener="#{myBean.rollback}"/>
   </amx:facet>
</amx:panelPage>

<amx:panelPage id="pp1">
   <amx:facet name="primary">
      <amx:commandButton id="cb1" 
                         icon="plus.png"
                         action="add" 
                         actionListener="#{myBean.AddItem}"/>
   </amx:facet>
</amx:panelPage>

<amx:panelPage id="pp1">
   <amx:facet name="footer">
      <amx:commandButton id="cb2" 
                         icon="folder.png"
                         text="Move (#{myBean.mailcount})" 
                         action="move"/>
   </amx:facet>
</amx:panelPage>

<amx:panelPage id="pp1">
   <amx:commandButton id="cb1" 
                      text="Reply"
                      actionListener="#{myBean.share}"/>
</amx:panelPage>

6.3.5.2 Displaying Back Style Buttons

The following are various types of back style buttons that are placed within Panel Page facets or content area:

• Normal, activated, or disabled Button with a text label only.

• Normal, activated, or disabled Button with an image icon only:

Example 6-20 demonstrates the commandButton element declared in a MAF AMX file.

Example 6-20 Definition of Back Button with Text Label

<amx:panelPage id="pp1">
   <amx:facet name="header">
      <amx:outputText value="Details" id="ot1"/>
   </amx:facet>
   <amx:facet name="primary">
      <amx:commandButton id="cb1" 
                         text="Back"
                         action="__back"/>
   </amx:facet>
   ...
</amx:panelPage>

Every time you place a Button component within the primary facet and set its action attribute to __back, MAF AMX automatically applies the back arrow styling to it, as Figure 6-10

Figure 6-10 Back Button at Design Time

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples

6.3.5.3 Displaying Highlight Style Buttons

Similar to other types of Buttons, highlight style buttons that are placed within Panel Page facets or content area can have their state as normal, activated, or disabled.

Example 6-21 demonstrates the commandButton element declared in a MAF AMX file.

Example 6-21 Definition of Highlight Button with Text Label

<amx:panelPage id="pp1">
   <amx:facet name="secondary">
      <amx:commandButton id="cb2" 
                         text="Save"
                         action="save" 
                         styleClass="adfmf-commandButton-highlight"/>
   </amx:facet>
</amx:panelPage>

Figure 6-11 Highlight Button at Design Time

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples.

6.3.5.4 Displaying Alert Style Buttons

Alert style buttons placed within the Panel Page can have normal, activated, or disabled state.

Example 6-22 demonstrates the commandButton element declared in a MAF AMX file.

Example 6-22 Definition of Alert Button with Text Label

<amx:commandButton id="cb1" 
                   text="Delete"
                   actionListener="#{myBean.delete}" 
                   styleClass="adfmf-commandButton-alert" />

Figure 6-12 Alert Button at Design Time

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples.

6.3.5.5 Using Additional Button Styles

MAF AMX provides the following additional Button styles:

• Dark style

• Bright style

• Small style

• Large style

• Highlight style

• Confirm style

• Two varieties of the Alternate style

Figure 6-13 Additional Button Styles

6.3.6 How to Use Links

You use the Link (commandLink) component to trigger actions and enable navigation to other views.

The Link component can have any type of component defined as its child. By using such components as Set Property Listener (see Section 6.3.23, "How to Use the Set Property Listener"), Action Listener (see Section 6.3.22, "How to Use the Action Listener"), Show Popup Behavior, Close Popup Behavior see Section 6.2.8, "How to Use a Popup Component"), and Validation Behavior (see Section 6.9, "Validating Input") as children of the Link component, you can create an actionable area within which clicks and gestures can be performed.

By placing an Image component (see Section 6.3.7, "How to Display Images") inside a Link you can create a clickable image.

Example 6-23 demonstrates the commandLink element declared in a MAF AMX file.

<amx:commandLink id="cl1" 
                 text="linked"
                 action="gotolink" 
                 actionListener="#{myBean.doSomething}"/>

Figure 6-14 shows the basic Link component displayed in the Preview pane.

Figure 6-14 Link at Design Time

Example 6-24 demonstrates the commandLink element declared in a MAF AMX file. This component is placed within the panelFormLayout and panelLabelAndMessage components.

<amx:panelPage id="pp1">
   <amx:panelFormLayout id="form">
      <amx:panelLabelAndMessage id="panelLabelAndMessage1" label="Label">
         <amx:commandLink id="cl1"
                          text="linked"
                          action="gotolink" 
                          actionListener="#{myBean.doSomething}"/>
      </amx:panelLabelAndMessage>
   </amx:panelFormLayout>
</amx:panelPage>

Figure 6-15 shows the Link component placed within a form and displayed in the Preview pane.

Figure 6-15 Link Within Form at Design Time

There is a particular order in which MAF AMX processes the Link component's child operations and attributes. For more information, see Section 6.3.5.8, "What You May Need to Know About the Order of Processing Operations and Attributes."

MAF AMX provides another component which is similar to the Link, but which does not allow for navigation between pages: Link Go (goLink) component. You use this component to enable linking to external pages. Figure 6-16 shows the Link Go component displayed in the Preview pane. This component has its parameters set as follows:

<amx:goLink id="goLink1"
            text="Go Link"
            url="http://example.com"/>

Figure 6-16 Link Go at Design Time

Image is the only component that you can specify as a child of the Link Go component.

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application This sample application is available from File > New > MAF Examples

6.3.7 How to Display Images

MAF AMX enables the display of images on iOS and Android-powered devices using the Image (image) component represented by a bitmap.

In addition to placing an Image in a Button and List View, you can place it inside a Link component (see Section 6.3.6, "How to Use Links") to create a clickable image.

Example 6-25 demonstrates the image element definition in a MAF AMX file.

<amx:image id="i1"
           styleClass="prod-thumb"
           source="images/img-big-#{pageFlowScope.product.uid}.png" />

The following are supported formats on Android platform:

• GIF

• JPEG

• PNG

• BMP

The following are supported formats on iOS platform:

• PNG

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery and UIDemo, MAF sample applications available from File > New > MAF Examples.

6.3.8 How to Use the Checkbox Component

The Checkbox (selectBooleanCheckbox) component represents a check box that you create to enable single selection of true or false values, which allows toggling between selected and deselected states.

You can use the label attribute of the Checkbox component to place text to the left of the checkbox, and the text attribute places text on the right.

Example 6-26 demonstrates the selectBooleanCheckbox element declared in a MAF AMX file.

<amx:selectBooleanCheckbox id="check1"
                           label="Agree to the terms:" 
                           value="#{myBean.bool1}"
                           valueChangeListener=
                              "#{PropertyBean.ValueChangeHandler}"/>

Figure 6-17 shows the unchecked Checkbox component displayed in the Preview pane. This component has its parameters set as follows:

<amx:selectBooleanCheckbox id="selectBooleanCheckbox1"
                           label="Checkbox"
                           value="false"
                           valueChangeListener=
                                "#{PropertyBean.ValueChangeHandler}"/>

Figure 6-17 Unchecked Checkbox at Design Time

<amx:selectBooleanCheckbox id="selectBooleanCheckbox1"
                           label="Checkbox"
                           value="true"
                           valueChangeListener=
                                "#{PropertyBean.ValueChangeHandler}"/>

Figure 6-18 shows the checked Checkbox component displayed in the Preview pane. This component has its parameters set as follows:

Figure 6-18 Checked Checkbox Definition

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application This sample application is available from File > New > MAF Examples

6.3.9 How to Use the Boolean Switch Component

The Boolean Switch (selectBooleanSwitch) component allows editing of boolean values as a switch metaphor instead of a checkbox.

Similar to other MAF AMX UI components, this component has a normal and selected state. To toggle the value, the end user taps (touches and releases) the switch once. Each tap toggles the switch.

Example 6-28 demonstrates the selectBooleanSwitch element defined in a MAF AMX file.

<amx:selectBooleanSwitch id="switch1" 
                         label="Flip switch:"
                         onLabel="On" 
                         offLabel="Off" 
                         value="#{myBean.bool1}"
                         valueChangeListener=
                                "#{PropertyBean.ValueChangeHandler}"/>

Figure 6-19 shows the Boolean Switch component displayed in the Preview pane. This component has its parameters set as follows:

<amx:selectBooleanSwitch id="selectBooleanSwitch1"
                         label="Switch"
                         value="value1"
                         valueChangeListener=
                                "#{PropertyBean.ValueChangeHandler}"/>

Figure 6-19 Boolean Switch at Design Time

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples

6.3.10 How to Use the Select Many Checkbox Component

The Select Many Checkbox (selectManyCheckbox) component represents a group of check boxes that you use to enable multiple selection of true or false values, which allows toggling between selected and deselected states of each check box in the group. The selection mechanism is provided by the Select Items or Select Item component (see Section 6.3.14.3, "What You May Need to Know About Differences Between Select Items and Select Item Components") contained by the Select Many Checkbox component.

Example 6-29 demonstrates the selectManyCheckbox element declared in a MAF AMX file.

<amx:selectManyCheckbox id="selectManyCheckbox1"
                        label="Select shipping options"
                        value="#{myBean.shipping}"
                        valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItem id="selectItem1" 
                   label="Air" 
                   value="#{myBean.shipping.air}"/>
   <amx:selectItem id="selectItem2" 
                   label="Rail" 
                   value="#{myBean.shipping.rail}"/>
   <amx:selectItem id="selectItem3" 
                   label="Water"
                   value="#{myBean.shipping.water}"/>
</amx:selectManyCheckbox>

Figure 6-20 shows the Select Many Checkbox component displayed in the Preview pane. This component has its parameters set as follows:

<amx:selectManyCheckbox id="selectManyCheckbox1"
                        label="Select Many Checkbox"
                        value="value2"
                        valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItem id="selectItem1" label="Selection 1" value="value1"/>
   <amx:selectItem id="selectItem2" label="Selection 2" value="value2"/>
   <amx:selectItem id="selectItem3" label="Selection 3" value="value3"/>
</amx:selectManyCheckbox>

Figure 6-20 Select Many Checkbox at Design Time

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples.

6.3.11 How to Use the Select Many Choice Component

The Select Many Choice (selectManyChoice) component allows selection of multiple values from a list. The selection mechanism is provided by the Select Items or Select Item component (see Section 6.3.14.3, "What You May Need to Know About Differences Between Select Items and Select Item Components") contained by the Select Many Checkbox component.

Example 6-30 demonstrates the selectManyChoice element declared in a MAF AMX file.

<amx:selectManyChoice id="check1" 
                      label="Select Option:"
                      value="#{myBean.shipping}"
                      valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItem id="selectItem1"
                   label="Signature Required"
                   value="signature" />
   <amx:selectItem id="selectItem2" 
                   label="Insurance" 
                   value="insurance" />
   <amx:selectItem id="selectItem3"
                   label="Delivery Confirmation" 
                   value="deliveryconfirm"/>
</amx:selectManyChoice>

Figure 6-21 Select Many Choice at Design Time

<amx:selectManyChoice id="check1" 
                      label="Select Shipping Options:"
                      value="#{myBean.shipping}">
   <amx:selectItems id="selectItems1" value="#{myBean.shippingOptions}"/>
</amx:selectManyChoice>

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples

The look and behavior of the Select Many Choice component on all supported devices is almost identical to the Select Many Checkbox component (see Section 6.3.10, "How to Use the Select Many Checkbox Component" for more information).

6.3.12 How to Use the Select Button Component

The Select Button (selectOneButton) component represents a button group that lists actions, with a single button active at any given time. The selection mechanism is provided by the Select Items or Select Item component (see Section 6.3.14.3, "What You May Need to Know About Differences Between Select Items and Select Item Components") contained by the Select Button component.

Example 6-32 demonstrates the selectOneButton element defined in a MAF AMX file.

<amx:selectOneButton id="bg1" 
                     value="#{myBean.myState}"
                     valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItem id="selectItem1" label="Yes" value="yes"/>
   <amx:selectItem id="selectItem2" label="No" value="no"/>
   <amx:selectItem id="selectItem3" label="Maybe" value="maybe"/>
</amx:selectOneButton>

Figure 6-22 shows the Select Button component displayed in the Preview pane. This component has its parameters set as follows:

<amx:selectOneButton id="selectOneButton1"
                     label="Select Button"
                     value="value1"
                     valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItem id="selectItem1" label="Value 1" value="value1"/>
   <amx:selectItem id="selectItem2" label="Value 2" value="value2"/>
   <amx:selectItem id="selectItem3" label="Value 3" value="value3"/>
</amx:selectOneButton>

Figure 6-22 Select Button at Design Time

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples

6.3.13 How to Use the Radio Button Component

The Radio Button (selectOneRadio) component represents a group of radio buttons that lists available choices. The selection mechanism is provided by the Select Items or Select Item component (see Section 6.3.14.3, "What You May Need to Know About Differences Between Select Items and Select Item Components") contained by the Radio Button component.

Example 6-33 and Example 6-34 demonstrate the selectOneRadio element definition in a MAF AMX file.

<amx:selectOneRadio id="radio1"
                    label="Choose a pet:"
                    value="#{myBean.myPet}"
                     valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItem id="selectItem1" label="Cat" value="cat"/>
   <amx:selectItem id="selectItem2" label="Dog" value="dog"/>
   <amx:selectItem id="selectItem3" label="Hamster" value="hamster"/>
   <amx:selectItem id="selectItem4" label="Lizard" value="lizard"/>
</amx:selectOneRadio>

<amx:selectOneRadio id="radio1"
                    label="Choose a pet:"
                    value="#{myBean.myPet}"
                     valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItems id="selectItems1" value="myBean.allPets"/>
</amx:selectOneRadio>

Figure 6-23 shows the Boolean Switch component displayed in the Preview pane. This component has its parameters set as follows:

<amx:selectOneRadio id="selectOneRadio1"
                     label="Radio Button"
                     value="value1"
                     valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItem id="selectItem1" label="Value 1" value="value1"/>
   <amx:selectItem id="selectItem2" label="Value 2" value="value2"/>
   <amx:selectItem id="selectItem3" label="Value 3" value="value3"/>
</amx:selectOneRadio>

Figure 6-23 Radio Button at Design Time

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples

6.3.14 How to Use the Choice Component

The Choice (selectOneChoice) component represents a combo box that is used to enable selection of a single value from a list. The selection mechanism is provided by the Select Items or Select Item component (see Section 6.3.14.3, "What You May Need to Know About Differences Between Select Items and Select Item Components") contained by the Choice component.

Example 6-35 demonstrates the selectOneChoice element definition with the selectItem subelement in a MAF AMX file.

<amx:selectOneChoice id="choice1"
                     label="Your state:"
                     value="#{myBean.myState}"
                     valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItem id="selectItem1" label="Alaska" value="AK"/>
   <amx:selectItem id="selectItem2" label="Alabama" value="AL"/>
   <amx:selectItem id="selectItem3" label="California" value="CA"/>
   <amx:selectItem id="selectItem4" label="Connecticut" value="CT"/>
</amx:selectOneChoice>

Example 6-36 demonstrates the selectOneChoice element definition with the selectItems subelement in a MAF AMX file.

<amx:selectOneChoice id="choice1"
                     label="Your state:"
                     value="#{myBean.myState}"
                     valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItems id="selectItems1" value="myBean.allStates"/>
</amx:selectOneChoice>

Figure 6-24 shows the Choice component displayed in the Preview pane. This component has its parameters set as follows:

<amx:selectOneChoice id="selectOneChoice1"
                     label="Choice"
                     value="value1"
                     valueChangeListener="#{PropertyBean.ValueChangeHandler}">
   <amx:selectItem id="selectItem1" label="Value 1" value="value1"/>
   <amx:selectItem id="selectItem2" label="Value 2" value="value2"/>
   <amx:selectItem id="selectItem3" label="Value 3" value="value3"/>
</amx:selectOneChoice>

Figure 6-24 Choice at Design Time

For more information, illustrations, and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples.

6.3.15 How to Use List View and List Item Components

Use the List View (listView) component to display data as a list of choices where the end user can select one or more options.

The List Item (listItem) component represents a single row in the List View. Typically, you place a List Item component inside the List View to lay out and style a list of data items. At runtime, List Item components respond to swipe gestures (see Section 6.4, "Enabling Gestures").

The List View allows you to define one of the following:

• A row that is replicated based on the number of items in the list (collection).

• A static row that is produced by adding a child List Item component without specifying the List View's var and value attributes. You can add as many of these static items as necessary, which is useful when you know the contents of the list at design time. In this case, the list is not editable and behaves like a set of menu items.

You can create the following types of List View components:

• Basic List

  Example 6-37 shows the listView element defined in a MAF AMX file. This definition corresponds to the basic component.

  Example 6-37 Basic List View Definition

  <amx:listView id="listView1" 
                showMoreStrategy="autoScroll" 
                bufferStrategy="viewport">
     <amx:listItem id="listItem1">
        <amx:outputText id="outputText1" value="ListItem Text"/>
     </amx:listItem>
     <amx:listItem id="listItem2">
        <amx:outputText id="outputText3" value="ListItem Text"/>
     </amx:listItem>
     <amx:listItem id="listItem3">
        <amx:outputText id="outputText5" value="ListItem Text"/>
     </amx:listItem>
     <amx:listItem id="listItem4">
        <amx:outputText id="outputText7"
                        value="This is really long text to test how it is handled"/>
     </amx:listItem>
  </amx:listView>
  

  Figure 6-25 demonstrates a basic List View component at design time.

  Figure 6-25 Basic List View at Design Time

  
  

  Example 6-38 shows another definition of the listView element in a MAF AMX file. This definition also corresponds to the basic component; however, the value of this List View is provided by a collection.

  Example 6-38 Basic List View Definition

  <amx:listView id="list1" 
                value="#{myBean.listCollection}" 
                var="row"
                showMoreStrategy="autoScroll" 
                bufferStrategy="viewport">
     <amx:listItem actionListener="#{myBean.selectRow}"
                   showLinkIcon="false"
                   id="listItem1">
        <amx:outputText value="#{row.name}" id="outputText1"/>
     </amx:listItem>
  </amx:listView>
  

  Note:

  Currently, when a text string in an Output Text inside a List Item is too long to fit on one line, the text does not wrap at the end of the line. You can prevent this by adding "white-space: normal;" to the inlineStyle attribute of the subject Output Text child component.

• List with icons

  Example 6-39 shows the listView element defined in a MAF AMX file. This definition corresponds to the component with icons.

  Example 6-39 List View with Icons Definition

  <amx:listView id="list1" 
                value="#{myBean.listCollection}" 
                var="row"
                showMoreStrategy="autoScroll" 
                bufferStrategy="viewport">
     <amx:listItem id="listItem1">
        <amx:tableLayout id="tl1" width="100%">
           <amx:rowLayout id="rl1">
              <amx:cellFormat id="cf11" width="40px" halign="center">
                 <amx:image id="image1" source="#{row.image}"/>
              </amx:cellFormat>
              <amx:cellFormat id="cf12" width="100%" height="43px">
                 <amx:outputText id="outputText1" value="#{row.desc}"/>
              </amx:cellFormat>
           </amx:rowLayout>
        </amx:tableLayout>
     </amx:listItem>
  </amx:listView>
  

  Figure 6-26 demonstrates a List View component with icons and text at design time.

  Figure 6-26 List View with Icons at Design Time

  
  

• List with search

• List with dividers. This type of list allows you to group data and show order. Attributes of the List View component define characteristics of each divider. For information about attributes, see Tag Reference for Oracle Mobile Application Framework.

  MAF AMX provides a list divider that can do the following:

  • Collapse its contents independently.

  • Show a count of items in each divider.

  • Collapse at the same time.

  Example 6-40 shows the listView element defined in a MAF AMX file. This definition corresponds to the component with collapsible dividers and item counts.

  Example 6-40 List View with Dividers Definition

  <amx:listView id="list1" 
            value="#{bindings.data.collectionModel}"
            var="row"
            collapsibleDividers="true"
            collapsedDividers="#{pageFlowScope.mylistDisclosedDividers}" 
            dividerMode="all"
            dividerAttribute="type"
            showDividerCount="true"
            showMoreStrategy="autoScroll" 
            bufferStrategy="viewport"
            fetchSize="10">
     <amx:listItem>
        <amx:outputText id="ot1" value="#{row.name}">
     </amx:listItem>
  </amx:listView>
  

  Note:

  Data in the list with dividers must be sorted by the dividerAttribute because this type of list does not sort the data; instead, it expects the data it receives to be already sorted.

  Note:

  Dividers are not displayed when a List View component is in edit mode (that is, its editMode attribute is specified).

  When dividers are visible, the end user can quickly navigate to a specific divider using the List View's localized alphabetical index utility, which is available for List View components whose dividerMode attribute is set to firstLetter. You can disable this utility by setting the sectionIndex attribute to off.

  The index utility (indexer) consists of an index bar and index item and has the following characteristics:

  • If the list contains unsorted data or duplicate dividers, the index item points to the first occurrence in the list.

  • Only available letters are highlighted in the index, and only those highlighted become active. This is triggered by the change in the data model (for example, when the end user taps on More row item).

  • The index is not case-sensitive.

  • Unknown characters are hidden under the hash ( # ) sign.

  The indexer letters can only be activated (tapped) on rows that have been loaded into the list. For example, if the List View, using its fetchSize attribute, has loaded rows up to the letter C, the indexer enables letters from A to C. Other letters appear on the indexer when more rows are loaded into it.

  Table 6-5 describes styles that you can define for the index utility.

  Table 6-5 The List View Index Styles

  styleClass name	Description
  adfmf-listView-index	Defines style of the index bar.
  adfmf-listView-indexItem	Defines style of one item in the index bar.
  adfmf-listView-indexItem-active	Defines style of the item in the index bar which has link to a related divider.
  adfmf-listView-indexCharacter	Defines style of a character in the index bar.
  adfmf-listView-indexBullet	Defines style of a bullet between two characters in index bar.
  adfmf-listView-indexOther	Defines style of a character that represents all unknown characters in the index bar.

  
  

  When the List View component with visible dividers functions as a container that provides scrolling and it becomes a subject to scrolling, the dividers are pinned at the top of the view. If this is the case, you have to explicitly set the height of the List View component. In all other cases, when the List View does not perform any scrolling itself but instead uses the scrolling of its parent container (such as the Panel Page), the List View does not have any height constraint set and its height is determined by its child components. This absence of the defined height constraint effectively disables the animated transition and pinning of dividers.

• Inset List

  Example 6-41 shows the listView element defined in a MAF AMX file. This definition corresponds to the inset component.

  Example 6-41 Inset List View Definition

  <amx:listView id="listView1" 
                styleClass="adfmf-listView-insetList"
                showMoreStrategy="autoScroll" 
                bufferStrategy="viewport">
     <amx:listItem id="listItem1">
        <amx:outputText id="outputText1" value="ListItem Text"/>
     </amx:listItem>
     <amx:listItem id="listItem2">
        <amx:outputText id="outputText3" value="ListItem Text"/>
     </amx:listItem>
     <amx:listItem id="listItem3">
        <amx:outputText id="outputText5" value="ListItem Text"/>
     </amx:listItem>
     <amx:listItem id="listItem4">
        <amx:outputText id="outputText7"
                        value="This is really long text to test how it is handled"/>
     </amx:listItem>
  </amx:listView>
  

  Figure 6-27 demonstrates an inset List View component at design time.

  Figure 6-27 Inset List View at Design Time

  
  

  Example 6-42 shows another definition of the listView element in a MAF AMX file. This definition also corresponds to the inset component, however, the value of this List View is provided by a collection.

  Example 6-42 Inset List Definition

  <amx:listView id="list1" 
                value="#{CarBean.carCollection}"
                var="row" 
                styleClass="adfmf-listView-insetList"
                showMoreStrategy="autoScroll" 
                bufferStrategy="viewport"
                fetchSize="10">
     <amx:listItem id="li1" action="go">
        <amx:outputText id="ot1" value="#{row.name}"/>
     </amx:listItem>
  </amx:listView>
  

There is a particular order in which MAF AMX processes the List Item component's child operations and attributes. For more information, see Section 6.3.5.8, "What You May Need to Know About the Order of Processing Operations and Attributes."

Unlike other MAF AMX components, when you drag and drop a List View onto a MAF AMX page and generate the listView with content from a data control, a dialog called the Component Gallery appears. This dialog allows you to choose a specific layout for the List View. Figure 6-28shows the List View Component Gallery.

Figure 6-28 Component Gallery for List View formats

Table 6-6 lists the supported List Formats that are displayed in the ListView Component Gallery.

The Variations presented in the ListView Gallery for a selected list format consist of options to add either dividers, a leading image, or both:

• Selecting a variation with a leading image adds an Image row to the List Item Content table.

• Selecting a variation with a divider defaults the Divider Attribute field to the first attribute in its list rather than the default No Divider value, and populates the Divider Mode field with its default value of All.

The Styles options presented in the ListView Gallery allow you to suppress chevrons, use an inset style list, or both:

• The selections do not modify any state in the Edit List View dialog. They only affect the generated MAF AMX markup.

• Selecting a style with the inset list sets the adfmf-listView-insetList style class on the listView element in the generated MAF AMX markup.

The following is an example of the Simple format with the inset list:

<amx:listView var="row"
              value="#{bindings.employees.collectionModel}"
              fetchSize="#{bindings.employees.rangeSize}"
              styleClass="adfmf-listView-insetList"
              id="listView2"
              showMoreStrategy="autoScroll" 
              bufferStrategy="viewport">
   <amx:listItem id="li2">
      <amx:outputText value="#{row.employeename}" id="ot3"/>
   </amx:listItem>
</amx:listView>

The ListView Gallery's Description pane is updated based on the currently selected Variation. The format includes a brief description of the main style, followed by the details of the selected variation. Four main styles with four variations on each provide sixteen unique descriptions detailed in Table 6-7.

After you have chosen a data binding from the Palette > Data> Data Controls pane and dropped it into the editor, OEPE displays the ListView Gallery (see Figure 6-29).

When completing the dialog, consider the following:

• The image on the left reflects the main content elements from the selected List View format

• The editable cells of the Value column are populated with static text strings (see Table 6-8).

• If the List Item Content cell contains an Image, the Value cell is defaulted to the <add path to your image> string. If this is the case, you have to replace it with the path to the image.

• The List Item Selection indicates the selection mode.

• Since you cannot set the divider attribute when the List View contains List Item child components, rather than being data bound, both the Divider Attribute and the Divider Mode fields are disabled.

Figure 6-29 shows the List View Configuration dialog on which you can specify the layout of your list elements.

Figure 6-29 The List View Configuration dialog

The following are special cases to consider when creating a bound List View:

• If a Java bean method returns a list without generics, you should use the Element Type field to create the List Item content, as Figure 6-29 shows.

• If the list data collection value provided is not collection-based, a Value column replaces the Value Bindings column with blank values.

For more information, see the following:

• Tag Reference for Oracle Mobile Application Framework

• Section 6.3.15.3, "Configuring Layout Using Styles"

• Section 5.3.2.3.3, "Dragging and Dropping Collections"

• UIDemo, a MAF sample application available from File > New > MAF Examples. This sample demonstrates how to use various types of the List View component and how to apply styles to adjust the page layout to a specific pattern.

• Appendix D, "Limitations to the Application Usage"

<amx:listView var="row" 
              value="#{bindings.testResults.collectionModel}" 
              fetchSize="#{bindings.testResults.rangeSize}">

<accessorIterator MasterBinding="Class1Iterator"
                  Binds="testResults"
                  RangeSize="25" 
                  DataControl="Class1"
                  BeanClass="mobile.Test"
                  id="testResultsIterator"/>

<amx:listView id="listView1" rangeChangeListener="#{pageFlowScope.HRBean.goGet}" >

public void goGet(RangeChangeEvent rangeChangeEvent) {
   // Add event code here...
}

<amx:panelPage id="pp1">
   <amx:commandButton id="edit" 
                      text="Edit"
                      rendered="#{!bindings.inEditMode.inputValue}">
      <amx:setPropertyListener id="spl1"
                               from="true"
                               to="#{bindings.inEditMode.inputValue}"
                               type="action"/>
   </amx:commandButton>
   <amx:commandButton id="stop"
                      text="Stop Editing"
                      rendered="#{bindings.inEditMode.inputValue}">
      <amx:setPropertyListener id="spl2"
                               from="false"
                               to="#{bindings.inEditMode.inputValue}" 
                               type="action"/>
   </amx:commandButton>
   <amx:listView id="lv1"
                 value="#{bindings.data.collectionModel}"
                 var="row"
                 editMode="#{bindings.inEditMode.inputValue}"
                 moveListener="#{MyBean.Reorder}">
      <amx:listItem id="li1">
         <amx:outputText id= "ot1" value="#{row.description}">
      </amx:listItem>
   </amx:listView>
</amx:panelPage>

6.3.15.3 Configuring Layout Using Styles

To adjust the MAF AMX page layout to a specific pattern, you can combine the use of the various types of List View components and styles that are defined through the styleClass attribute (see Section 6.6, "Styling UI Components") that uses a set of predefined styles.

A MAF sample application called UIDemo demonstrates all the optional styles for each component and their associated rendering. The UIDemo application is available from File > New > MAF Examples.

Example 6-47 shows the listView element and its child elements defined in a MAF AMX file. The way each outputText child element is laid out in the list is specified by the tableLayout child element of the listItem. Alternatively, you may use the styleClass attribute to lay out and style outputText elements: setting this attribute to adfmf-listItem-startText places the Output Text component to the start (left side) of the row and applies a black font to its text; setting this attribute to adfmf-listItem-endText places the Output Text component to the end (right side) of the row and applies a blue font to its text. Whether or not the arrow pointing to the right is visible is configured by the showLinkIcon attribute of the listItem element. Since the default value of this attribute is true, the example does not contain this setting.

Example 6-47 Definition of List View with Start and End Text

<amx:listView id="listView1" value="#{myBean.listCollection}" var="row">
   <amx:listItem id="listItem1">
      <amx:tableLayout id="tl1" width="100%">
         <amx:rowLayout id="rl1">
            <amx:cellFormat id="cf1s1" width="10px"/>
            <amx:cellFormat id="cf11" width="60%" height="43px">
               <amx:outputText id="outputText11" value="#{row.name}"/>
            </amx:cellFormat>
            <amx:cellFormat id="cf1s2" width="10px"/>
            <amx:cellFormat id="cf12" halign="end" width="40%">
               <amx:outputText id="outputText12" value="#{row.status}"
                               styleClass="adfmf-listItem-highlightText"/>
            </amx:cellFormat>
         </amx:rowLayout>
      </amx:tableLayout>
   </amx:listItem>
</amx:listView>

Figure 6-30 shows a List View component with differently styled text added to the start (left side) and end (right side) of each row. Besides the text, rows are equipped with a right-pointing arrow representing a link that expands each list item.

Figure 6-30 List View with Start and End Text at Design Time

Example 6-48 shows the listView element and its child elements defined in a MAF AMX file. The way each outputText child element is laid out in the list is specified by the tableLayout child element of the listItem. Alternatively, you may use the styleClass attribute to lay out and style outputText elements: setting this attribute to adfmf-listItem-startText places the Output Text component to the start of the row and applies a black font to its text; setting this attribute to adfmf-listItem-endText places the Output Text component to the end of the row and applies a blue font to its text. Whether or not the arrow pointing to the right is visible on each particular row is configured by the showLinkIcon attribute of the listItem element. Since in this example this attribute is set to false for every listItem element, arrows pointing to the right are not displayed.

Example 6-48 Definition of List View with Start and End Text Without Expansion Links

<amx:listView id="listView1" value="#{myBean.listCollection}" var="row">
   <amx:listItem id="listItem1" showLinkIcon="false">
      <amx:tableLayout id="tl1" width="100%">
         <amx:rowLayout id="rl1">
            <amx:cellFormat id="cf1s1" width="10px"/>
            <amx:cellFormat id="cf11" width="60%" height="43px">
               <amx:outputText id="outputText11" value="#{row.name}"/>
            </amx:cellFormat>
            <amx:cellFormat id="cf1s2" width="10px"/>
            <amx:cellFormat id="cf12" halign="end" width="40%">
               <amx:outputText id="outputText12" value="#{row.status}"
                               styleClass="adfmf-listItem-highlightText"/>
            </amx:cellFormat>
         </amx:rowLayout>
      </amx:tableLayout>
   </amx:listItem>
</amx:listView>

Figure 6-31 shows a List View component with differently styled text added to the start and end of each row. The rows do not contain right-pointing arrows representing links.

Figure 6-31 List View with Start and End Text Without Expansion Links at Design Time

Example 6-49 shows the listView element and its child elements defined in a MAF AMX file. In addition to the text displayed at the start and end of each row, this List View contains subtext placed under the end text. The way each outputText child element is laid out in the list is specified by the tableLayout child element of the listItem. Alternatively, you may use the styleClass attribute to lay out and style outputText elements: setting this attribute to adfmf-listItem-upperStartText places the Output Text component to the left side of the row and applies a black font to its text; setting this attribute to adfmf-listItem-upperEndText places the Output Text component to the right side of the row and applies a smaller grey font to its text; setting this attribute to adfmf-listItem-captionText places the Output Text component under the Output Text component whose styleClass attribute is set to adfmf-listItem-upperStartText and applies a smaller grey font to its text.

Example 6-49 Defining List View with Start and End Text and Subtext

<amx:listView id="listView1" value="#{myBean.listCollection}" var="row">
   <amx:listItem id="listItem1">
      <amx:tableLayout id="tl1" width="100%">
         <amx:rowLayout id="rl11">
            <amx:cellFormat id="cf1s1" width="10px" rowSpan="2"/>
            <amx:cellFormat id="cf11" width="60%" height="28px">
               <amx:outputText id="outputTexta1" value="#{row.name}"/>
            </amx:cellFormat>
            <amx:cellFormat id="cf1s2" width="10px"/>
            <amx:cellFormat id="cf12" halign="end" width="40%">
               <amx:outputText id="outputTexta2" value="#{row.status}"
                               styleClass="adfmf-listItem-highlightText"/>
            </amx:cellFormat>
         </amx:rowLayout>
         <amx:rowLayout id="rl12">
            <amx:cellFormat id="cf13" columnSpan="3" width="100%" height="12px">
               <amx:outputText id="outputTexta3" 
                               value="#{row.desc}"
                               styleClass="adfmf-listItem-captionText"/>
            </amx:cellFormat>
         </amx:rowLayout>
      </amx:tableLayout>
   </amx:listItem>
</amx:listView>

Figure 6-32 shows a List View component with differently styled text added to the start and end of each row, and with a subtext added below the end text on the left.

Figure 6-32 List View with Start and End Text and Subtext at Design Time

Example 6-50 shows the listView element and its child elements defined in a MAF AMX file. This List View is populated with rows containing a main text and subtext. The way each outputText child element is laid out in the list is specified by the tableLayout child element of the listItem. Alternatively, you may use the styleClass attribute to lay out and style outputText elements: setting this attribute to adfmf-listItem-mainText places the Output Text component to the start of the row and applies a large black font to its text; setting this attribute to adfmf-listItem-captionText places the Output Text component under the Output Text component whose styleClass attribute is set to adfmf-listItem-mainText and applies a smaller grey font to its text.

Example 6-50 Defining List View with Main Text and Subtext

<amx:listView id="listView1" value="#{myBean.listCollection}" var="row">
   <amx:listItem id="listItem1">
      <amx:tableLayout id="tla1" width="100%">
         <amx:rowLayout id="rla1">
            <amx:cellFormat id="cf1s1" width="10px" rowSpan="2"/>
            <amx:cellFormat id="cfa1" width="100%" height="28px">
               <amx:outputText id="outputTexta1" value="#{row.name}"/>
            </amx:cellFormat>
         </amx:rowLayout>
         <amx:rowLayout id="rla2">
            <amx:cellFormat id="cfa2" width="100%" height="12px" >
               <amx:outputText id="outputTexta2" value="#{row.desc}"
                               styleClass="adfmf-listItem-captionText"/>
            </amx:cellFormat>
         </amx:rowLayout>
      </amx:tableLayout>
   </amx:listItem>
</amx:listView>

Figure 6-33 shows a List View component with differently styled text added as a main text and subtext to each row.

Figure 6-33 List View with Main Text and Subtext at Design Time

Example 6-51 shows the listView element and its child elements defined in a MAF AMX file. This List View is populated with cells containing an icon, main text, and subtext. The way each outputText child element is laid out in the list is specified by the tableLayout child element of the listItem. Alternatively, you may use the styleClass attribute to lay out and style outputText elements: setting this attribute to adfmf-listItem-mainText places the Output Text component to the left side of the row and applies a large black font to its text; setting this attribute to adfmf-listItem-captionText places the Output Text component under the Output Text component whose styleClass attribute is set to adfmf-listItem-mainText and applies a smaller grey font to its text. The position of the image element is defined by its enclosing cellFormat.

Example 6-51 Defining List View with Icons, Main Text and Subtext

<amx:listView id="lv1" value="#{myBean.listCollection}" var="row">
   <amx:listItem id="li1">
      <amx:tableLayout id="tl1" width="100%">
         <amx:rowLayout id="rl1">
            <amx:cellFormat id="cf1" rowSpan="2" width="40px" halign="center">
               <amx:image id="i1" source="#{row.image}"/>
            </amx:cellFormat>
            <amx:cellFormat id="cf2" width="100%" height="28px">
               <amx:outputText id="ot1" value="#{row.name}"/>
            </amx:cellFormat>
         </amx:rowLayout>
         <amx:rowLayout id="rl2">
            <amx:cellFormat id="cf3" width="100%" height="12px">
               <amx:outputText id="ot2" value="#{row.desc}"
                               styleClass="adfmf-listItem-captionText"/>
            </amx:cellFormat>
         </amx:rowLayout>
      </amx:tableLayout>
   </amx:listItem>
</amx:listView>

Figure 6-34 shows a List View component with icons and differently styled text added as a main text and subtext to each row.

Figure 6-34 List View with Icons, Main Text and Subtext at Design Time

Example 6-52 shows the listView element and its child elements defined in a MAF AMX file. In addition to the text displayed at the start and end of each row, this List View contains two different types of text placed on each side of each row. The way each outputText child element is laid out in the list is specified by the tableLayout child element of the listItem. Alternatively, you may use the styleClass attribute to lay out and style outputText elements: setting this attribute to adfmf-listItem-upperStartText places the Output Text component at the top left corner of the row and applies a large black font to its text; setting this attribute to adfmf-listItem-upperEndText places the Output Text component at the top right corner of the row and applies a large grey font to its text; setting this attribute to adfmf-listItem-lowerStartText places the Output Text component at the bottom left corner of the row and applies a smaller grey font to its text; setting this attribute to adfmf-listItem-lowerEndText places the Output Text component at the bottom right corner of the row and applies a smaller grey font to its text. Whether or not the arrow pointing to the right is visible is configured by the showLinkIcon attribute of the listItem element. Since the default value of this attribute is true, the example does not contain this setting.

Example 6-52 Defining List View with Four Types of Text

<amx:listView id="lv1" value="#{myBean.listCollection}" var="row">
   <amx:listItem id="li1">
      <amx:tableLayout id="tl1" width="100%">
         <amx:rowLayout id="rl1">
            <amx:cellFormat id="cf1" width="10px" rowSpan="2"/>
            <amx:cellFormat id="cf2" width="60%" height="28px">
               <amx:outputText id="ot1" value="#{row.name}"/>
            </amx:cellFormat>
            <amx:cellFormat id="cf3" width="10px" rowSpan="2"/>
            <amx:cellFormat id="cf4" width="40%" halign="end">
               <amx:outputText id="ot2" value="#{row.status}"
                               styleClass="adfmf-listItem-highlightText"/>
            </amx:cellFormat>
         </amx:rowLayout>
         <amx:rowLayout id="rla2">
            <amx:cellFormat id="cf5" width="60%" height="12px">
               <amx:outputText id="ot3" value="#{row.desc}"
                               styleClass="adfmf-listItem-captionText"/>
            </amx:cellFormat>
            <amx:cellFormat id="cf6" width="40%" halign="end">
               <amx:outputText id="ot4" value="#{row.priority}"
                               styleClass="adfmf-listItem-captionText"/>
            </amx:cellFormat>
         </amx:rowLayout>
      </amx:tableLayout>
   </amx:listItem>
</amx:listView>

Figure 6-35 shows a List View component with two types of differently styled text added to the start and end of each row. Besides the text, rows are equipped with a right-pointing arrow representing a link that expands each list item.

Figure 6-35 List View with Four Types of Text at Design Time

Example 6-53 shows the listView element and its child elements defined in a MAF AMX file. In addition to the text displayed at the start and end of each row, this List View contains two different types of text placed on each side of each row. The way each outputText child element is laid out in the list is specified by the tableLayout child element of the listItem. Alternatively, you may use the styleClass attribute to lay out and style outputText elements: setting this attribute to adfmf-listItem-upperStartText places the Output Text component at the top left corner of the row and applies a large black font to its text; setting this attribute to adfmf-listItem-upperEndText places the Output Text component at the top right corner of the row and applies a large grey font to its text; setting this attribute to adfmf-listItem-lowerStartTextNoChevron places the Output Text component at the bottom left corner of the row and applies a smaller grey font to its text; setting this attribute to adfmf-listItem-lowerEndTextNoChevron places the Output Text component at the bottom right corner of the row and applies a smaller grey font to its text. Whether or not the arrow pointing to the right is visible on each particular row is configured by the showLinkIcon attribute of the listItem element. Since in this example this attribute is set to false for every listItem element, arrows pointing to the right are not displayed.

Example 6-53 Defining List View with Four Types of Text and Without Expansion Links

<amx:listView id="lv1" value="#{myBean.listCollection}" var="row">
   <amx:listItem id="li1" showLinkIcon="false">
      <amx:tableLayout id="tl1" width="100%">
         <amx:rowLayout id="rl1">
            <amx:cellFormat id="cf1" width="10px" rowSpan="2"/>
            <amx:cellFormat id="cf2" width="60%" height="28px">
               <amx:outputText id="ot1" value="#{row.name}"/>
            </amx:cellFormat>
            <amx:cellFormat id="cf3" width="10px" rowSpan="2"/>
            <amx:cellFormat id="cf4" width="40%" halign="end">
               <amx:outputText id="ot2" value="#{row.status}"
                               styleClass="adfmf-listItem-highlightText"/>
            </amx:cellFormat>
         </amx:rowLayout>
         <amx:rowLayout id="rl2">
            <amx:cellFormat id="cf5" width="60%" height="12px">
               <amx:outputText id="ot3" value="#{row.desc}"
                               styleClass="adfmf-listItem-captionText"/>
            </amx:cellFormat>
            <amx:cellFormat id="cf6" width="40%" halign="end">
               <amx:outputText id="ot4" value="#{row.priority}"
                               styleClass="adfmf-listItem-captionText"/>
            </amx:cellFormat>
         </amx:rowLayout>
      </amx:tableLayout>
   </amx:listItem>
</amx:listView>

Figure 6-36 shows a List View component with two types of differently styled text added to the start and end of each row.

Figure 6-36 List View with Four Types of Text and Without Expansion Links at Design Time

6.3.16 How to Use the Carousel Component

You use the Carousel (carousel) component to display other components, such as images, in a revolving carousel. The end user can change the active item by using either the slider or by dragging another image to the front.

The Carousel component contains a Carousel Item (carouselItem) component, whose text represented by the text attribute is displayed when it is the active item of the Carousel. Although typically the Carousel Item contains an Image component, other components may be used. For example, you can use a Link as a child that surrounds an image. Instead of creating a Carousel Item component for each object to be displayed and then binding these components to the individual object, you bind the Carousel component to a complete collection. The component then repeatedly renders one Carousel Item component by stamping the value for each item. As each item is stamped, the data for the current item is copied into a property that can be addressed using an EL expression using the Carousel component's var attribute. Once the Carousel has completed rendering, this property is removed or reverted back to its previous value. Carousel components contain a Facet named nodeStamp, which is both a holder for the Carousel Item used to display the text and short description for each item, and also the parent component to the Image displayed for each item.

The Carousel Item stretches its sole child component. If you place a single Image component inside of the Carousel Item, the Image stretches to fit within the square allocated for the item (as the end user spins the carousel, these dimensions shrink or grow).

By default, the Carousel displays horizontally. The objects within the horizontal orientation of the Carousel are vertically-aligned to the middle and the Carousel itself is horizontally-aligned to the center of its container. You can configure the Carousel so that it can be displayed vertically, as you might want for a reference rolodex. By default, the objects within the vertical orientation of the Carousel are horizontally-aligned to the center and the Carousel itself is vertically aligned middle. You can change the alignments using the Carousel's orientation attribute.

Instead of partially displaying the previous and next images, you can configure your Carousel to display images in a filmstrip or circular design using the displayItems attribute.

By default, if the Carousel is configured to display in the circular mode, when the end user hovers over an auxiliary item (that is, an item that is not the current item at the center), the item is outlined to show that it can be selected. Using the auxiliaryPopOut attribute, you can configure the Carousel so that instead the item pops out and displays at full size.

In Oracle Enterprise Pack for Eclipse, the Carousel is located under MAF AMX in the Palette (see Figure 6-37).

Figure 6-37 Carousel in Palette

To create a Carousel component, you must first create the data model that contains images to display, then bind the Carousel to that model and insert a Carousel Item component into the nodeStamp facet of the Carousel. Lastly, you insert an Image component (or other components that contain an Image component) as a child to the Carousel Item component.

Example 6-54 demonstrates the carousel element definition in a MAF AMX file. When defining the carousel element, you must place the carouselItem element inside of a carousel elements's nodeStamp facet.

<amx:carousel id="carousel1"
              value="#{bindings.products.collectionModel}"
              var="item"
              auxiliaryOffset="0.9"
              auxiliaryPopOut="hover"
              auxiliaryScale="0.8"
              controlArea="full"
              displayItems="circular"
              halign="center"
              valign="middle"
              disabled="false"
              shortDesc="spin"
              orientation="horizontal"
              styleClass="AMXStretchWidth"
              inlineStyle="height:250px;background-color:#EFEFEF;">
   <amx:facet name="nodeStamp">
      <amx:carouselItem id="item1" text="#{item.name}"
                        shortDesc="Product: #{item.name}">
         <amx:commandLink id="link1" action="goto-productDetails" 
                          actionListener="#{someMethod()}">
            <amx:image id="image1" styleClass="prod-thumb"
                       source="images/img-big-#{item.uid}.png"/>
            <amx:setPropertyListener id="spl1"
                                     from="#{item}"
                                     to="#{pageFlowScope.product}"
                                     type="action"/>
         </amx:commandLink>
      </amx:carouselItem>
   </amx:facet>
</amx:carousel>

The Carousel component uses the CollectionModel class to access the data in the underlying collection. You may also use other model classes, such as java.util.List or array, in which case the Carousel automatically converts the instance into a CollectionModel class, but without any additional functionality.

A slider allows the end user to navigate through the Carousel collection. Typically, the thumb on the slider displays the current object number out of the total number of objects. When the total number of objects is too great to calculate, the thumb on the slider shows only the current object number.

For more information and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples.

6.3.17 How to Use the Film Strip Component

A Film Strip (filmStrip) is a container component that visualizes data distributed among a set of groups (pages) in a form of a vertical or horizontal strip. The UI components that represent display items (filmStripItem) included in a group must be of the same size and type, and only one group visible at a time. The end user can navigate pages of the Film Strip, select an item and generate actions by tapping it.

In Oracle Enterprise Pack for Eclipse, the Film Strip is located under MAF AMX in the Palette (see Figure 6-38).

Figure 6-38 Film Strip in Palette

Example 6-55 demonstrates the filmStrip element definition in a MAF AMX file.

<amx:filmStrip id="fs1"
               var="item"
               value="#{bindings.contacts.collectionModel}"
               rendered="#{pageFlowScope.pRendered}" 
               styleClass="#{pageFlowScope.pStyleClass}"
               inlineStyle="#{pageFlowScope.pInlineStyle}"
               shortDesc="#{pageFlowScope.pShortDesc}"
               halign="#{pageFlowScope.pFsHalign}"
               valign="#{pageFlowScope.pFsValign}"
               itemsPerPage="#{pageFlowScope.pMaxItems}" 
               orientation="#{pageFlowScope.pOrientation}">
   <amx:filmStripItem id="fsi1"
                      inlineStyle="text-align:center; width:200px;">
      <amx:commandLink id="ciLink" 
                       action="details" 
                       shortDesc="Navigate to details">
         <amx:image id="ciImage" source="images/people/#{item.first}.png"/>
         <amx:setPropertyListener id="spl1"
                                  from="#{item.rowKey}" 
                                  to="#{pageFlowScope.currentContact}" 
                                  type="action"/>
         <amx:setPropertyListener id="spl2"
                                  from="#{item.first}"
                                  to="#{pageFlowScope.currentContactFirst}"
                                  type="action"/>
         <amx:setPropertyListener id="spl3"
                                  from="#{item.last}"
                                  to="#{pageFlowScope.currentContactLast}"
                                  type="action"/>
      </amx:commandLink>
   </amx:filmStripItem>
</amx:filmStrip>

For more information and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples

6.3.18 How to Use Verbatim Component

You use the Verbatim (verbatim) operation to insert your own HTML into a page in cases where such a component does not exist or you prefer laying it out yourself using HTML.

In Oracle Enterprise Pack for Eclipse, Verbatim is located under MAF AMX in the Palette (see Figure 6-39).

Figure 6-39 Verbatim in Palette

For more information and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples

6.3.19 How to Use Output HTML Component

The Output HTML (outputHtml) component allows you to dynamically and securely obtain HTML content from an EL-bound property or method with the purpose of displaying it on a MAF AMX page. The Output HTML component behaves similarly to the Verbatim component (see Section 6.3.18, "How to Use Verbatim Component") and the same restrictions with regards to JavaScript and AJAX usage apply to it (see Section 6.3.18.1, "What You May Need to Know About Using JavaScript and AJAX with Verbatim Component").

In Oracle Enterprise Pack for Eclipse, Output HTML is located under MAF AMX in the Palette (see Figure 6-40).

Figure 6-40 Output HTML in Components Window

Example 6-56 demonstrates the outputHtml element definition in a MAF AMX file. The value attribute provides an EL binding to a String property that is used to obtain the HTML content to be displayed as the outputHTML in the final rendering of the MAF AMX page.

<amx:tableLayout id="t1" width="100%">
   <amx:rowLayout id="r1">
      <amx:cellFormat id="cf1" width="100%">
         <amx:outputHtml id="ReceiptView"
                         value="#{pageFlowScope.purchaseBean.htmlReceiptView}"/>
      </amx:cellFormat>
   </amx:rowLayout>
   <amx:rowLayout id="r2">
      <amx:cellFormat id="cf2" width="100%">
         <amx:outputHtml id="CheckView"
                         value="#{pageFlowScope.purchaseBean.htmlCheckView}"/>
      </amx:cellFormat>
   </amx:rowLayout>
</amx:tableLayout>

Example 6-57 shows the code from the Java bean called MyPurchaseBean that provides HTML for the Output HTML component shown in Example 6-56.

// The property accessor that gets the receipt view HTML
public String getHtmlReceiptView() {
   // Perform some URL remote call to get the HTML to be
   // inserted as a view of the Receipt and return that value
   return obtainReceiptHTMLFromServer();
}
// The property accessor that gets the check view HTML
public String getHtmlCheckView() {
   // Perform some URL remote call to get the HTML to be
   // inserted as a view of the Check and return that value
   return obtainCheckHTMLFromServer();
}

Since the Output HTML component obtains its HTML content from a Java bean property as opposed to downloading it directly from a remote source, consider using the existing MAF security features when coding the retrieval or generation of the dynamically provided HTML. For more information, see Chapter 21, "Securing Mobile Applications." In addition, ensure that the HTML being provided comes from a trusted source and is free of threats.

For more information and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples

6.3.20 How to Enable Iteration

You use the Iterator (iterator) operation to stamp an arbitrary number of items with the same kind of data, which allows you to iterate through the data and produce UI for each element.

In Oracle Enterprise Pack for Eclipse, the Iterator is located under MAF AMX in the Palette.

For more information, see Tag Reference for Oracle Mobile Application Framework.

6.3.21 How to Load a Resource Bundle

The Load Bundle (loadBundle) operation allows you to specify the resource bundle that provides localized text for the MAF AMX UI components on a page. For more information, see Section 6.7, "Localizing UI Components."

In Oracle Enterprise Pack for Eclipse, the Load Bundle is located under MAF AMX in the Palette (see Figure 6-41).

Figure 6-41 Load Bundle in Palette

In your MAF AMX file, you declare the loadBundle element as a child of the view element.

For more information, see Tag Reference for Oracle Mobile Application Framework.

6.3.22 How to Use the Action Listener

The Action Listener (actionListener) component allows you to declaratively invoke commands through EL based on the type of the parent component's usage.

The predominant reason for using the Action Listener component is to add gesture-supported actions to its parent components, as well as ability to perform multiple operations for a single gesture, including tap. For more information, see Section 6.3.22.1, "What You May Need to Know About Differences Between the Action Listener Component and Attribute."

In Oracle Enterprise Pack for Eclipse, the Action Listener component is located under MAF AMX in the Palette (see Figure 6-42).

Figure 6-42 Action Listener in Palette

You can add zero or more Action Listener components as children of any command component (Button, Link, List Item, Film Strip Item, and a subset of data visualization components). The type attribute of the Action Listener component defines which gesture, such as swipeLeft, swipeRight, tapHold, and so on, causes the ActionEvent to fire.

For more information, see the following:

• Section 6.10, "Using Event Listeners"

• Section 6.3.23, "How to Use the Set Property Listener"

• Section 6.4, "Enabling Gestures"

• Section 6.3.22.1, "What You May Need to Know About Differences Between the Action Listener Component and Attribute"

• Tag Reference for Oracle Mobile Application Framework

6.3.23 How to Use the Set Property Listener

The Set Property Listener (setPropertyListener) component allows you to declaratively copy values from one location (defined by the component's from attribute) to another (defined by the component's to attribute) as a result of an end-user action on a component, thus freeing you from the need to write Java code to achieve the same result.

In Oracle Enterprise Pack for Eclipse, the Set Property Listener component is located under MAF AMX in the Palette (see Figure 6-43).

Figure 6-43 Set Property Listener in Palette

Example 6-58 demonstrates the setPropertyListener element definition in a MAF AMX file.

<amx:listView value="#{bindings.products.collectionModel}" var="row" id="lv1">
   <amx:listItem id="li1" action="details">
      <amx:outputText value="#{row.name}" id="ot1" />
      <amx:setPropertyListener id="spl1"
                               from="#{row}"
                               to="#{pageFlowScope.product}"
                               type="action"/>
   </amx:listItem>
</amx:listView>

You can add zero or more Set Property Listener components as children of any command component (Button, Link, List Item, Film Strip Item, and a subset of data visualization components). The type attribute of the Set Property Listener component defines which gesture, such as swipeLeft, swipeRight, tapHold, and so on, causes the ActionEvent to fire.

For more information, see the following:

• Section 6.10, "Using Event Listeners"

• Section 6.3.22, "How to Use the Action Listener"

• Section 6.4, "Enabling Gestures"

• Tag Reference for Oracle Mobile Application Framework

6.3.24 How to Convert Date and Time Values

The Convert Date Time (convertDateTime) is not an independent UI component: it is a converter operation that you use in conjunction with an Output Text and Input Text component to display converted date, time, or a combination of date and time in a variety of formats following the specified pattern.

In Oracle Enterprise Pack for Eclipse, the Convert Date Time is located under MAF AMX in the Palette (see Figure 6-44).

Figure 6-44 Convert Date Time in Palette

Example 6-59 demonstrates the convertDateTime element declared in a MAF AMX file.

<amx:panelPage id="pp1">
   <amx:inputText styleClass="ui-text" value="Order Date" id="it1" >
      <amx:convertDateTime id="cdt1" type="both"/>
   </amx:inputText>
</amx:panelPage>

To convert date and time values:

1. From the Components window, drag a Convert Date Time component and insert it within an Output Text or Input Text component, making it a child element of that component.

2. Open the Property editor for the Convert Date Time component and define its attributes. For more information, see Tag Reference for Oracle Mobile Application Framework.

The Convert Date Time component allows a level of leniency while converting an input value string to date:

• A converter with associated pattern MMM for month, when attached to any value holder, accepts values with month specified in the form MM or M as valid.

• Allows use of such separators as dash ( - ) or period ( . ) or slash ( / ), irrespective of the separator specified in the associated pattern.

• Leniency in pattern definition set by the pattern attribute.

For example, when a pattern on the converter is set to "MMM/d/yyyy", the following inputs are accepted as valid by the converter:

Jan/4/2004
Jan-4-2004
Jan.4.2004
01/4/2004
01-4-2004
01.4.2004
1/4/2004
1-4-2004
1.4.2004

The converter supports the same parsing and formatting conventions as the java.text.SimpleDateFormat (specified using the dateStyle, timeStyle, and pattern attributes), except the case when the time zone is specified to have a long display, such as timeStyle=full or a pattern set with zzzz. Instead of a long descriptive string, such as "Pacific Standard Time", the time zone is displayed in the General Timezone format (GMT +/- offset) or RFC-822 time zones.

The exact result of the conversion depends on the locale, but typically the following rules apply:

• SHORT is completely numeric, such as 12.13.52 or 3:30pm

• MEDIUM is longer, such as Jan 12, 1952

• LONG is longer, such as January 12, 1952 or 3:30:32pm

• FULL is completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST

6.3.25 How to Convert Numerical Values

The Convert Number (convertNumber) is not an independent UI component: it is a converter operation that you use in conjunction with an Output Text, Input Text, and Input Number Slider components to display converted number or currency figures in a variety of formats following a specified pattern.

The Convert Number component provides the following types of conversion:

• From value to string, for display purposes.

• From formatted string to value, when formatted input value is parsed into its underlying value.

When the Convert Number is specified as a child of an Input Text component, the numeric keyboard is displayed on a mobile device by default.

In Oracle Enterprise Pack for Eclipse, the Convert Number is located under MAF AMX in the Palette (see Figure 6-45).

Figure 6-45 Convert Number in Components Window

Example 6-60 demonstrates the convertNumber element defined in a MAF AMX file.

<amx:panelPage id="pp1">
   <amx:inputText styleClass="ui-text" value="Product Price" id="it1" >
      <amx:convertNumber id="cn1"
                         type="percent" 
                         groupingUsed="false" 
                         integerOnly="true"/>
   </amx:inputText>
</amx:panelPage>

To convert numerical values:

1. From the Components window, drag a Convert Number component and insert it within an Output Text, Input Text, or Input Number Slider component, making it a child element of that component.

2. Open the Property editor for the Convert Number component and define its attributes. For more information, see Tag Reference for Oracle Mobile Application Framework.

6.3.26 How to Enable Drag Navigation

The Navigation Drag Behavior (navigationDragBehavior) operation allows you to invoke the action of navigating to the next or previous MAF AMX page by dragging a portion of the mobile device screen in a specified direction (left or right). As the drag in the specified direction occurs, an indicator is displayed on the appropriate side of the screen to hint that an action will be performed if the dragging continues and then stops as soon as the indicator is fully revealed. If the drag is released before the indicator is fully revealed, the indicator slides away and no action is invoked.

A MAF AMX page cannot contain more than two instances of the navigationDragBehavior element: one with its direction attribute set to back and one set to forward.

In Oracle Enterprise Pack for Eclipse, the Navigation Drag Behavior is located under MAF AMX in the Palette (see Figure 6-46).

Figure 6-46 Navigation Drag Behavior in Palette

Example 6-61 demonstrates the navigationDragBehavior element defined in a MAF AMX file. Note that this element can only be a child of the view element.

<amx:view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns:amx="http://xmlns.oracle.com/adf/mf/amx"
          xmlns:dvtm="http://xmlns.oracle.com/adf/mf/amx/dvt">
   <amx:navigationDragBehavior id="ndb1"
                               direction="forward"
                               action="gotoDetail"/> Foot 1 
   <amx:panelPage id="pp1">
      <amx:facet name="header">
      ...
   </amx:panelPage>
</amx:view>

Figure 6-47 shows the Navigation Drag Behavior at runtime (displayed using the mobileFusionFx skin).

Figure 6-47 Navigation Drag Behavior Operation at Runtime

For more information and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples

<amx:view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:amx="http://xmlns.oracle.com/adf/mf/amx"
          xmlns:dvtm="http://xmlns.oracle.com/adf/mf/amx/dvt">
   <amx:panelPage id="pp1">
      <amx:facet name="header">
         <amx:outputText value="Header1" id="ot1"/>
      </amx:facet>
      <amx:commandButton id="cb1"
                         text="commandButton1"
                         actionListener="#{pageFlowScope.myBean.doSomething}"/>
   </amx:panelPage>
   <amx:navigationDragBehavior id="ndb1" 
                               direction="forward" 
                               action="goView2"
                               disabled="#{pageFlowScope.myBean.navDisabled}"/>
</amx:view>

public class MyBean {
   boolean navDisabled = true;
   private PropertyChangeSupport propertyChangeSupport = 
                                    new PropertyChangeSupport(this);

   public void setNavDisabled(boolean navDisabled) {
      boolean oldNavDisabled = this.navDisabled;
      this.navDisabled = navDisabled;
      propertyChangeSupport.firePropertyChange("navDisabled", 
                                               oldNavDisabled, 
                                               navDisabled);
   }

   public boolean isNavDisabled() {
      return navDisabled;
   }

   public void doSomething(ActionEvent actionEvent) {
      setNavDisabled(!navDisabled);
   }

   public void addPropertyChangeListener(PropertyChangeListener l) {
      propertyChangeSupport.addPropertyChangeListener(l);
   }

   public void removePropertyChangeListener(PropertyChangeListener l) {
      propertyChangeSupport.removePropertyChangeListener(l);
   }
}

6.3.27 How to Use the Loading Indicator

The Loading Indicator Behavior (loadingIndicatorBehavior) operation allows you to define the behavior of the loading indicator by overriding the following:

• The duration of the fail-safe timer (in milliseconds).

• An optional JavaScript function name that can be invoked to decide on the course of action when the fail-safe threshold is reached.

For additional information, see the adf.mf.api.amx.showLoadingIndicator in Table 11-1, "Static APIs".

In Oracle Enterprise Pack for Eclipse, the Loading Indicator Behavior is located under MAF AMX in the Palette (see Figure 6-48).

Figure 6-48 Loading Indicator Behavior in the Palette

Example 6-64 demonstrates the loadingIndicatorBehavior element defined in a MAF AMX file. Note that this element can only be a child of the view element.

<amx:view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns:amx="http://xmlns.oracle.com/adf/mf/amx"
          xmlns:dvtm="http://xmlns.oracle.com/adf/mf/amx/dvt">
   <amx:loadingIndicatorBehavior id="lib1"
                        failSafeDuration="3000"
                        failSafeClientHandler="window.customFailSafeHandler"/>
   <amx:panelPage id="pp1">
      <amx:facet name="header">
      <!-- The loading indicator custom fail safe handler will appear 
           if the long running operation runs longer than 3 seconds -->
      <amx:commandButton id="cb1" 
                         text="longRunningOperation"
                         actionListener=
                               "#{pageFlowScope.myBean.longRunningOperation} />
   </amx:panelPage>
</amx:view>

In the preceding example, the commandButton is bound to a long-running method to illustrate that the loading indicator applies to long running operations once the page is loaded (not when the page itself takes a long time to load).

Example 6-65 demonstrates the custom.js file included with the application feature. It defines the client handler for the failSafeClientHandler in the loadingIndicatorBehavior page. As per the API requirement, this function returns a String of either hide, repeat, or freeze. For more information, see the adf.mf.api.amx.showLoadingIndicator in Table 11-1, "Static APIs".

window.customFailSafeHandler = function() { 
   var answer =
      prompt(
         "This is taking a long time.\n\n" +
         "Use \"a\" to hide the indicator.\n" +
         "Use \"z\" to wait for it.\n" +
         "Otherwise, give it more time.");

   if (answer == "a")
      return "hide"; // don't ask again; hide the indicator
   else if (answer == "z") 
      return "freeze" // don't ask again; wait for it to finish
   else 
      return "repeat"; // ask again after another duration
};

For more information and examples, see the following:

• Tag Reference for Oracle Mobile Application Framework

• CompGallery, a MAF sample application available from File > New > MAF Examples

6.5.1 How to Create an Area Chart

You use the Area Chart (areaChart) to visually represent data where sets of data items are related and categorized into groups and series. The series are visualized using graphical elements with some common style properties (such as, for example, an area color or pattern). Those properties have to be applied at the series level instead of per each individual data item. You have an option to use the default or custom series styles. For information about defining custom series styles, see Section 6.5.6, "How to Create a Line Chart."

The Area Chart can be zoomed and scrolled along its X Axis. This is enabled through the use of the zoomAndScroll attribute.

Example 6-68 shows the areaChart element defined in a MAF AMX file. To create a basic area chart with default series style, you pass it a collection and specify the dataStamp facet with a nested chartDataItem element.

<dvtm:areaChart id="areaChart1"
                value="#{bindings.lineData.collectionModel}"
                var="row" 
                inlineStyle="width: 400px; height: 300px;"
                animationOnDisplay="auto"
                animationDuration="1500" >
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="areaChartItem1"                          series="#{row.series}"
                          group="#{row.group}" 
                          value="#{row.value}" />
   </amx:facet>
   <dvtm:yAxis id="yAxis1"
               axisMaxValue="80.0" 
               majorIncrement="20.0" 
               title="yAxis Title" />
   <dvtm:legend id="l1" position="end" />
</dvtm:areaChart>

Figure 6-50 Area Chart at Design Time

Data items are initialized in the collection model and equipped with the stamping mechanism. At a minimum, each collection row must include the following properties:

• series: name of the series to which this data item belongs;

• group: name of the group to which this data item belongs;

• value: the data item value.

The collection row might also include other properties, such as color or shape, applicable to individual data items.

You can use Attribute Groups (attributeGroups element) to set style properties for a group of data items based on some grouping criteria, as Example 6-69 shows. In this case, the data item color and shape attributes are set based on the additional grouping expression. The attributeGroups can have the following child elements:

• attributeExceptionRule from the dvtm namespace: replaces an attribute value with another when a particular boolean condition is met.

• attributeMatchRule from the dvtm namespace: replaces an attribute when the data matches a certain value.

• attribute from the amx namespace.

<dvtm:areaChart id="areaChart1"
                value="#{bindings.lineData.collectionModel}"
                var="row" 
                inlineStyle="width: 400px; height: 300px;"
                title="Chart Title" 
                animationOnDisplay="auto"
                animationDuration="1500" >
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1"
                          series="#{row.series}"
                          group="#{row.group}" 
                          value="#{row.value}" />
         <dvtm:attributeGroups id="ag1" 
                               type="color" 
                               value="#{row.brand}" />
   </amx:facet>
   <dvtm:yAxis id="yAxis1"
               axisMaxValue="80.0" 
               majorIncrement="20.0" 
               title="yAxis Title" />
   <dvtm:legend id="l1" position="end" />
</dvtm:areaChart>

For information on attributes of the areaChart and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define a facet child element from the amx namespace. The facet can have a chartDataItem as its child (see Section 6.5.17.1, "Defining Chart Data Item").

You can style the Area Chart component's top-level element by overwriting the default CSS settings defined in the following class:

.dvtm-areaChart
   - supported properties: all

For more information on chart styling, see Section 6.5.11, "How to Style Chart Components."

For information on how to extend CSS files, see Section 6.6.4, "How to Style Data Visualization Components."

6.5.2 How to Create a Bar Chart

You use a Bar Chart (barChart) to visually display data as vertical bars, where sets of data items are related and categorized into groups and series. The series are visualized using graphical elements with some common style properties that you have to apply at the series level instead of per each individual data item.

The Bar Chart can be zoomed and scrolled along its X Axis. This is enabled through the use of the zoomAndScroll attribute.

Example 6-70 shows the barChart element defined in a MAF AMX file. The dataStamp facet is specified with a nested chartDataItem element.

<dvtm:barChart id="barChart1"
               value="#{bindings.barData.collectionModel}"
               var="row"
               inlineStyle="width: 400px; height: 300px;"
               animationOnDisplay="zoom"
               animationDuration="3000" >
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1"
                          series="#{row.series}"
                          group="#{row.group}"
                          value="#{row.value}" />
   </amx:facet>
   <dvtm:yAxis id="yAxis1"
               axisMaxValue="80.0" 
               majorIncrement="20.0" 
               title="yAxis Title" />
   <dvtm:legend id="l1" position="start" />
</dvtm:barChart>

Figure 6-51 Bar Chart at Design Time

The data model for a bar chart is represented by a collection of items (rows) that describe individual bars. Typically, properties of each bar include the following:

• series: name of the series to which this bar belongs;

• group: name of the group to which this bar belongs;

• value: the data item value (required).

Data must include the same number of groups per series. If any of the series or data pairs are missing, it is passed to the API as null.

For information on attributes of the barChart and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define a facet child element from the amx namespace. The facet can have a chartDataItem as its child (see Section 6.5.17.1, "Defining Chart Data Item").

You can style the Bar Chart component's top-level element by overwriting the default CSS settings defined in the following class:

.dvtm-barChart
   - supported properties: all

For more information on chart styling, see Section 6.5.11, "How to Style Chart Components."

For information on how to extend CSS files, see Section 6.6.4, "How to Style Data Visualization Components."

6.5.3 How to Create a Horizontal Bar Chart

You use a Horizontal Bar Chart (horizontalBarChart) to visually display data as horizontal bars, where sets of data items are related and categorized into groups and series. The series are visualized using graphical elements with some common style properties that you have to apply at the series level instead of per each individual data item.

The Bar Chart can be zoomed and scrolled along its X Axis. This is enabled through the use of the zoomAndScroll attribute.

Example 6-70 shows the horizontalBarChart element defined in a MAF AMX file. The dataStamp facet is specified with a nested chartDataItem element.

<dvtm:horizontalBarChart id="horizBarChart1"
                   value="#{bindings.barData.collectionModel}"
                   var="row"
                   inlineStyle="width: 400px; height: 300px;"
                   dataSelection="#{pageFlowScope.dataSelection}"
                   hideAndShowBehavior="#{pageFlowScope.hideAndShowBehavior}"
                   rolloverBehavior="#{pageFlowScope.rolloverBehavior}"
                   stack="#{pageFlowScope.stack}" >
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1"
                          series="#{row.series}"
                          group="#{row.group}"
                          value="#{row.value}" />
   </amx:facet>
   <dvtm:yAxis id="yAxis1"
               axisMaxValue="80.0" 
               majorIncrement="20.0" 
               title="yAxis Title" />
   <dvtm:legend id="l1" position="start" />
</dvtm:horizontalBarChart>

Figure 6-52 Horizontal Bar Chart at Design Time

The data model for a horizontal bar chart is represented by a collection of items (rows) that describe individual bars. Typically, properties of each bar include the following:

• series: name of the series to which this bar belongs;

• group: name of the group to which this bar belongs;

• value: the data item value (required).

Data must include the same number of groups per series. If any of the series or data pairs are missing, it is passed to the API as null.

For information on attributes of the horizontalBarChart and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define a facet child element from the amx namespace. The facet can have a chartDataItem as its child (see Section 6.5.17.1, "Defining Chart Data Item").

You can style the Horizontal Bar Chart component's top-level element by overwriting the default CSS settings defined in the following class:

.dvtm-horizontalBarChart
   - supported properties: all

For more information on chart styling, see Section 6.5.11, "How to Style Chart Components."

For information on how to extend CSS files, see Section 6.6.4, "How to Style Data Visualization Components."

6.5.4 How to Create a Bubble Chart

A Bubble Chart (bubbleChart) displays a set of data items where each data item has x, y coordinates and size (bubble). In addition, each data item can have various style attributes, such as color and markerShape. You can either set properties of each data item individually, or categorize the data items into groups based on various criteria. You may use multiple grouping criteria at the same time, and may also use different style attributes to visualize the relationships of the data items. However, unlike line charts (see Section 6.5.6, "How to Create a Line Chart") or area charts (see Section 6.5.1, "How to Create an Area Chart"), bubble charts do not have a strict notion of the series and groups.

The Bubble Chart can be zoomed and scrolled along its X and Y Axis. This is enabled through the use of the zoomAndScroll attribute.

Example 6-72 shows the bubbleChart element defined in a MAF AMX file. The dataStamp facet is specified with a nested chartDataItem element. The color and markerShape attributes of each data item are set individually based on the values supplied in the data model. In addition, the underlying data control must support the respective variable references of row.label, row.size, and row.shape.

<dvtm:bubbleChart id="bubbleChart1"
                  value="#{bindings.bubbleData.collectionModel}"
                  inlineStyle="width: 400px; height: 300px;"
                  dataSelection="multiple"
                  rolloverBehavior="dim"
                  animationOnDisplay="auto"
                  var="row">
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1"
                          group="#{row.group}" 
                          x="#{row.x}" 
                          y="#{row.y}"
                          markerSize="#{row.size}" 
                          color="#{row.color}"
                          markerShape="#{row.shape}" />
   </amx:facet>
</dvtm:bubbleChart>

Figure 6-53 Bubble Chart at Design Time

In Example 6-73, the attributeGroups element is used to set common style attributes for a related group of data items.

<dvtm:bubbleChart id="bubbleChart1"
                  value="#{bindings.bubbleData.collectionModel}"
                  dataSelection="multiple"
                  rolloverBehavior="dim"
                  animationOnDisplay="auto"
                  title="Bubble Chart"
                  var="row">
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1"
                          group="#{row.label}" 
                          x="#{row.x}" 
                          y="#{row.y}" >
         <dvtm:attributeGroups id="ag1" type="color" value="#{row.category}" />
         <dvtm:attributeGroups id="ag2" type="shape" value="#{row.brand}" />
      </dvtm:chartDataItem>
   </amx:facet>
</dvtm:bubbleChart>

The data model for a bubble chart is represented by a collection of items (rows) that describe individual data items. Typically, properties of each bar include the following:

• label: data item label (optional);

• x, y: value coordinates (required);

• z: the size of data item (required).

The data must include the same number of groups per series. If any of the series or data pairs are missing, it is passed to the API as null.

For information on attributes of the bubbleChart and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define a facet child element from the amx namespace. The facet can have a chartDataItem as its child (see Section 6.5.17.1, "Defining Chart Data Item").

You can style the Bubble Chart component's top-level element by overwriting the default CSS settings defined in the following class:

.dvtm-bubbleChart
   - supported properties: all

For more information on chart styling, see Section 6.5.11, "How to Style Chart Components."

For information on how to extend CSS files, see Section 6.6.4, "How to Style Data Visualization Components."

6.5.5 How to Create a Combo Chart

A Combo Chart (comboChart) represents an overlay of two or more different charts, such as a line and bar chart.

Example 6-74 shows the comboChart element defined in a MAF AMX file. The dataStamp facet is specified with a nested chartDataItem element. The seriesStamp facet overrides the default style properties for the series and sets custom series styles using the seriesStyle elements.

<dvtm:comboChart id="comboChart1"
                 value="#{bindings.barData.collectionModel}"
                 var="row"
                 inlineStyle="width: 400px; height: 300px;"
                 animationOnDisplay="auto"
                 animationDuration="1500" >
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1" 
                          series="#{row.series}"
                          group="#{row.group}"
                          value="#{row.value}" />
   </amx:facet>
   <amx:facet name="seriesStamp">
      <dvtm:seriesStyle id="seriesStyle1"
                        series="#{row.series}" 
                        type="bar"
                        rendered="#{(row.series eq 'Series 1') or
                                    (row.series eq 'Series 2') or
                                    (row.series eq 'Series 3')}" />
      <dvtm:seriesStyle id="seriesStyle2"
                        series="#{row.series}" 
                        type="line" 
                        lineWidth="5"
                        rendered="#{(row.series eq 'Series 4') or
                                    (row.series eq 'Series 5')}" />
   </amx:facet>
   <dvtm:yAxis id="yAxis1"
               axisMaxValue="80.0" 
               majorIncrement="20.0" 
               title="yAxis Title" />
   <dvtm:legend position="start" id="l1" />
</dvtm:comboChart>

Figure 6-54 Combo Chart at Design Time

For information on attributes of the comboChart and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define a facet child element from the amx namespace. The facet can have a chartDataItem as its child (see Section 6.5.17.1, "Defining Chart Data Item").

You can style the Combo Chart component's top-level element by overwriting the default CSS settings defined in the following class:

.dvtm-comboChart
   - supported properties: all

For more information on chart styling, see Section 6.5.11, "How to Style Chart Components."

For information on how to extend CSS files, see Section 6.6.4, "How to Style Data Visualization Components."

6.5.6 How to Create a Line Chart

You use the Line Chart (lineChart) to visually represent data where sets of data items are related and categorized into groups and series. The series are visualized using graphical elements with some common style properties (such as, for example, a line color, width, or style). Those properties have to be applied at the series level instead of per each individual data item. You have an option to use the default or custom series styles.

The Line Chart can be zoomed and scrolled along its X Axis. This is enabled through the use of the zoomAndScroll attribute.

Example 6-75 shows the lineChart element defined in a MAF AMX file. To create a basic line chart with default series style, you pass it a collection and specify the dataStamp facet with a nested chartDataItem element.

<dvtm:lineChart id="lineChart1"
                inlineStyle="width: 400px; height: 300px;"
                rolloverBehavior="dim" 
                animationOnDisplay="auto"
                value="#{bindings.lineData1.collectionModel}"
                var="row" >
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1"
                          series="#{row.series}"
                          group="#{row.group}" 
                          value="#{row.value}"
                          color="#{row.color}" />
   </amx:facet>
</dvtm:lineChart>

Figure 6-55 Line Chart at Design Time

Data items are initialized in the collection model and equipped with the stamping mechanism. At a minimum, each collection row must include the following properties:

• series: name of the series to which this line belongs;

• group: name of the group to which this line belongs;

• value: the data item value.

The collection row might also include other properties, such as color or shape, applicable to individual data items.

You can use attribute groups (attributeGroups element) to set style properties for a group of data items based on some grouping criteria, as Example 6-76 shows. In this case, the data item color and shape attributes are set based on the additional grouping expression. The attributeGroups can have the following child elements:

• attributeExceptionRule from the dvtm namespace: replaces an attribute value with another when a particular boolean condition is met.

• attributeMatchRule from the dvtm namespace: replaces an attribute when the data matches a certain value.

• attribute from the amx namespace.

<dvtm:lineChart id="lineChart1"
                inlineStyle="width: 400px; height: 300px;"
                rolloverBehavior="dim" 
                animationOnDisplay="auto"
                title="Line Chart" 
                value="#{bindings.lineData1.collectionModel}"
                var="row" >
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1"
                          series="#{row.series}"
                          group="#{row.group}" 
                          value="#{row.value}" />
         <dvtm:attributeGroups id="ag1" 
                               type="color" 
                               value="#{row.brand}" />
      </dvtm:chartDataItem>
   </amx:facet>
</dvtm:lineChart>

To override the default style properties for the series, you can define an optional seriesStamp facet and set custom series styles using the seriesStyle elements, as Example 6-77 shows.

<dvtm:lineChart id="lineChart1"
                inlineStyle="width: 400px; height: 300px;"
                rolloverBehavior="dim" 
                animationOnDisplay="auto"
                title="Line Chart" 
                value="#{bindings.lineData1.collectionModel}"
                var="row" >
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1"
                          series="#{row.series}"
                          group="#{row.group}" 
                          value="#{row.value}" />
   </amx:facet>
   <amx:facet name="seriesStamp">
      <dvtm:seriesStyle series="#{row.series}"
                        lineStyle="#{row.lineStyle}"
                        lineWidth="#{row.lineWidth}" />
   </amx:facet>
</dvtm:lineChart>

In the preceding example, the seriesStyle elements are grouped based on the value of the series attribute. Series with the same name are supposed to share the same set of properties defined by other attributes of the seriesStyle, such as color, lineStyle, lineWidth, and so on. When MAF AMX encounters different attribute values for the same series name, it applies the value which was processed last.

Alternatively, you can control the series styles in a MAF AMX charts using the rendered attribute of the seriesStyle element, as Example 6-78 shows.

<dvtm:lineChart id="lineChart1"
                inlineStyle="width: 400px; height: 300px;"
                rolloverBehavior="dim"
                animationOnDisplay="auto"
                title="Line Chart"
                value="#{bindings.lineData1.collectionModel}"
                var="row" >
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1"
                          series="#{row.series}"
                          group="#{row.group}"
                          value="#{row.value}" 
                          color="#{row.color}" />
   </amx:facet>
   <amx:facet name="seriesStamp">
      <dvtm:seriesStyle series="#{row.series}"
                        color="red" 
                        lineWidth="3"
                        lineStyle="solid"
                        rendered="#{row.series == 'Coke'}" />
      <dvtm:seriesStyle series="#{row.series}"
                        color="blue"
                        lineWidth="2"
                        lineStyle="dotted"
                        rendered="#{row.series == 'Pepsi'}" />
   </amx:facet>
</dvtm:lineChart>

For information on attributes of the lineChart and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define a facet child element from the amx namespace. The facet can have a chartDataItem as its child (see Section 6.5.17.1, "Defining Chart Data Item").

You can style the Line Chart component's top-level element by overwriting the default CSS settings defined in the following class:

.dvtm-lineChart
   - supported properties: all

For more information on chart styling, see Section 6.5.11, "How to Style Chart Components."

For information on how to extend CSS files, see Section 6.6.4, "How to Style Data Visualization Components."

6.5.7 How to Create a Pie Chart

You use a Pie Chart (pieChart) to illustrate proportional division of data, with each data item represented by a pie segment (slice). Slices can be sorted by size (from largest to smallest), and small slices can be aggregated into a single ”other” slice.

Example 6-79 shows the pieChart element defined in a MAF AMX file. The dataStamp facet is specified with a nested pieDataItem element.

<dvtm:pieChart id="pieChart1"
               inlineStyle="width: 400px; height: 300px;"
               value="#{bindings.pieData.collectionModel}"
               var="row"
               animationOnDisplay="zoom"
               animationDuration="3000" >
   <amx:facet name="dataStamp">
      <dvtm:pieDataItem id="pieDataItem1"
                        label="#{row.name}" 
                        value="#{row.data}" />
   </amx:facet>
   <dvtm:legend position="bottom" id="l1" />
</dvtm:pieChart>

Figure 6-56 Pie Chart at Design Time

The data model for a pie chart is represented by a collection of items that define individual pie data items. Typically, properties of each data item include the following:

• label: slice label;

• value: slice value.

The model might also define other properties of the data item, such as the following:

• borderColor: slice border color;

• color: slice color;

• explode: slice explosion offset.

For information on attributes of the pieChart and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define a facet child element from the amx namespace. The facet can have a pieDataItem as its child (see Section 6.5.17.4, "Defining Pie Data Item").

You can style the Pie Chart component by overwriting the default CSS settings defined in dvtm-pieChart and dvtm-chartPieLabel, and dvtm-chartSliceLabel classes:

• The top-level element can be styled using

  .dvtm-pieChart
     - supported properties: all
  

• The pie labels cal be styled using

  .dvtm-chartPieLabel
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  

• The pie slice labels can be styled using

  .dvtm-chartSliceLabel
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  

For more information on chart styling, see Section 6.5.11, "How to Style Chart Components."

For more information on how to extend CSS files, see Section 6.6.4, "How to Style Data Visualization Components."

6.5.8 How to Create a Scatter Chart

A Scatter Chart (scatterChart) displays data as unconnected dots that represent data items, where each item has x, y coordinates and size. In addition, each data item can have various style attributes, such as color and markerShape. You can either set properties of each data item individually, or categorize the data items into groups based on various criteria. You may use multiple grouping criteria at the same time, and may also use different style attributes to visualize the data items relationships. However, unlike line charts (see Section 6.5.6, "How to Create a Line Chart") or area charts (see Section 6.5.1, "How to Create an Area Chart"), scatter charts do not have a strict notion of the series and groups.

The Scatter Chart can be zoomed and scrolled along its X and Y Axis. This is enabled through the use of the zoomAndScroll attribute.

Example 6-80 shows the scatterChart element defined in a MAF AMX file. The dataStamp facet is specified with a nested chartDataItem element. The color and markerShape attributes of each data item are set individually based on the values supplied in the data model.

<dvtm:scatterChart id="scatterChart1"
                   inlineStyle="width: 400px; height: 300px;"
                   animationOnDisplay="zoom"
                   animationDuration="3000"
                   value="#{bindings.scatterData.collectionModel}"
                   var="row" >
   <amx:facet name="dataStamp">
      <dvtm:chartDataItem id="chartDataItem1"
                          group="#{row.group}"
                          color="#{row.color}"
                          markerShape="auto"
                          x="#{row.data.x}"
                          y="#{row.data.y}">
         <dvtm:attributeGroups type="color"
                               value="#{row.series}" 
                               id="ag1" />
      </dvtm:chartDataItem>
   </amx:facet>
   <dvtm:xAxis id="xAxis1" title="X Axis Title" />
   <dvtm:yAxis id="xAxis2" title="Y Axis Title" />
   <dvtm:legend position="bottom" id="l1" />
</dvtm:scatterChart>

Figure 6-57 Scatter Chart at Design Time

The data model for a scatter chart is represented by a collection of items (rows) that describe individual data items. Attributes of each data item are defined by stamping (dataStamp) and usually include the following:

• x, y: value coordinates (required);

• markerSize: the size of the marker (optional).

The model might also define other properties of the data item, such as the following:

• borderColor: data item border color;

• color: data item color;

• tooltip: custom tooltip.

For information on attributes of the scatterChart and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define a facet child element from the amx namespace. The facet can have a chartDataItem as its child (see Section 6.5.17.1, "Defining Chart Data Item").

You can style the Scatter Chart component's top-level element by overwriting the default CSS settings defined in the following class:

.dvtm-scatterChart
   - supported properties: all

For more information on chart styling, see Section 6.5.11, "How to Style Chart Components."

For information on how to extend CSS files, see Section 6.6.4, "How to Style Data Visualization Components."

6.5.9 How to Create a Spark Chart

A Spark Chart (sparkChart) is a simple, condensed chart that displays trends or variations, often in the column of a table. The charts are often used in a dashboard to provide additional context to a data-dense display.

Example 6-81 shows the sparkChart element defined in a MAF AMX file. The dataStamp facet is specified with a nested sparkDataItem element.

<dvtm:sparkChart id="sparkChart1"
                 value="#{bindings.sparkData.collectionModel}"
                 var="row"
                 type="line"
                 inlineStyle="width:400px; height:300px; float:left;">
   <amx:facet name="dataStamp"> 
      <dvtm:sparkDataItem id="sparkDataItem1" value="#{row.value}" />
   </amx:facet>
</dvtm:sparkChart> 

Figure 6-58 Spark Chart at Design Time

The data model for a spark chart is represented by a collection of items (rows) that describe individual spark data items. Typically, properties of each data item include the following:

• value: spark value.

For information on attributes and dvtm child elements of the sparkChart, see Tag Reference for Oracle Mobile Application Framework.

You can define a facet child element from the amx namespace. The facet can have a sparkDataItem as its child (see Section 6.5.17.5, "Defining Spark Data Item").

You can style the Spark Chart component's top-level element by overwriting the default CSS settings defined in the following class:

.dvtm-sparkChart
   - supported properties: all

For more information on chart styling, see Section 6.5.11, "How to Style Chart Components."

For information on how to extend CSS files, see Section 6.6.4, "How to Style Data Visualization Components."

6.5.10 How to Create a Funnel Chart

A Funnel Chart (funnelChart) component provides a visual representation of data related to steps in a process. The steps appear as vertical slices across a horizontal cylinder. As the actual value for a given step or slice approaches the quota for that slice, the slice fills. Typically, a Funnel Chart requires actual values and target values against a stage value, which might be time.

Example 6-82 shows the funnelChart element defined in a MAF AMX file. The dataStamp facet is specified with a nested funnelDataItem element.

<dvtm:funnelChart id="funnelChart1"
                  var="row"
                  value="#{bindings.funnelData.collectionModel}"
                  styleClass="dvtm-gallery-component"
                  sliceGaps="on"
                  threeDEffect="#{pageFlowScope.threeD ? 'on' : 'off'}"
                  orientation="#{pageFlowScope.orientation}"
                  dataSelection="#{pageFlowScope.dataSelection}"
                  footnote="#{pageFlowScope.footnote}"
                  footnoteHalign="#{pageFlowScope.footnoteHalign}"
                  hideAndShowBehavior="#{pageFlowScope.hideAndShowBehavior}"
                  rolloverBehavior="#{pageFlowScope.rolloverBehavior}"
                  seriesEffect="#{pageFlowScope.seriesEffect}"
                  subtitle="#{pageFlowScope.titleDisplay ? 
                                            pageFlowScope.subtitle : ''}"
                  title="#{pageFlowScope.titleDisplay ? pageFlowScope.title : ''}"
                  titleHalign="#{pageFlowScope.titleHalign}"
                  animationOnDataChange="#{pageFlowScope.animationOnDataChange}"
                  animationDuration="#{pageFlowScope.animationDuration}"
                  animationOnDisplay="#{pageFlowScope.animationOnDisplay}"
                  shortDesc="#{pageFlowScope.shortDesc}">
   <amx:facet name="dataStamp">
      <dvtm:funnelDataItem id="funnelDataItem1"
                           label="#{row.label}" 
                           value="#{row.value}"
                           targetValue="#{row.targetValue}" 
                           color="#{row.color}"
                           shortDesc="This is a tooltip">
      </dvtm:funnelDataItem>
   </amx:facet>
   <dvtm:legend id="l1" 
                position="#{pageFlowScope.legendPosition}"
                rendered="#{pageFlowScope.legendDisplay}"/>
</dvtm:funnelChart> 

Figure 6-59 Funnel Chart at Design Time

The data model for a funnel chart is represented by a collection of items (rows) that describe individual funnel data items. Typically, properties of each data item include the following:

• value: funnel value

• label: funnel slice label

For information on attributes and dvtm child elements of the funnelChart, see Tag Reference for Oracle Mobile Application Framework.

You can define a facet child element from the amx namespace. The facet can have a funnelDataItem as its child (see Section 6.5.17.6, "Defining Funnel Data Item").

You can style the Funnel Chart component by overwriting the default CSS settings defined in dvtm-funnelChart and dvtm-funnelDataItem classes:

• The top-level element can be styled using

  .dvtm-funnelChart
     - supported properties: all
  

• The Funnel Chart data items cal be styled using

  .dvtm-funnelDataItem
     - supported properties: border-color, background-color
  

For more information on chart styling, see Section 6.5.11, "How to Style Chart Components."

For more information on how to extend CSS files, see Section 6.6.4, "How to Style Data Visualization Components."

6.5.11 How to Style Chart Components

With the exception of the Spark Chart, you can style chart components by overwriting the default CSS settings defined in the following classes:

• A chart component's legend can be styled using

  .dvtm-legend
     - supported properties used for text styling: 
                 font-family, font-size, font-weight, color, font-style
     - supported properties used for background styling: background-color
     - supported properties used for border styling: 
                 border-color (used when border width > 0)
  
  .dvtm-legendTitle
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  
  .dvtm-legendSectionTitle
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  

• A chart component's title, subtitle, and so on, can be styled using

  .dvtm-chartTitle
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  
  .dvtm-chartSubtitle
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  
  .dvtm-chartFootnote
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  
  .dvtm-chartTitleSeparator
     - supported properties: 
                 visibility (is title separator rendered),
                 border-top-color, border-bottom-color
  
  

• A chart component's axes can be styled using

  .dvtm-chartXAxisTitle
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  
  .dvtm-chartYAxisTitle
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  
  .dvtm-chartY2AxisTitle
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  
  .dvtm-chartXAxisTickLabel
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  
  .dvtm-chartYAxisTickLabel
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  
  .dvtm-chartY2AxisTickLabel
     - supported properties: 
                 font-family, font-size, font-weight, color, font-style
  

In addition to styling the chart component's top-level element, you can style specific child elements of some charts.

6.5.12 How to Use Events with Chart Components

You can use the ViewportChangeEvent to handle zooming and scrolling of chart components. When either zooming or scrolling occurs, the component fires an event loaded with information that defines the new viewport.

You can specify the viewportChangeListener as an attribute of Area Chart, Bar Chart, Horizontal Bar Chart, Combo Chart, and Line Chart components.

For more information, see the following:

• Section 6.10, "Using Event Listeners"

• Java API Reference for Oracle Mobile Application Framework

• Tag Reference for Oracle Mobile Application Framework

6.5.13 How to Create an LED Gauge

Unlike charts, gauges focus on a single data point and examine that point relative to minimum, maximum, and threshold indicators to identify problem areas. A LED (lighted electronic display) gauge (ledGauge) graphically depicts a measurement, such as key performance indicator (KPI). There are several styles of LED gauges. The ones with arrows are used to indicate good (up arrow), fair (left- or right-pointing arrow), or poor (down arrow). You can specify any number of thresholds for a gauge. However, some LED gauges (such as those with arrow or triangle indicators) support a limited number of thresholds because there is a limited number of meaningful directions for them to point. For arrow or triangle indicators, the threshold limit is three.

Example 6-83 shows the ledGauge element defined in a MAF AMX file.

<dvtm:ledGauge id="ledGauge1"
               value="65" 
               
               inlineStyle="width: 100px; height: 80px; float: left;
                            border-color: navy; background-color: lightyellow;">
   <dvtm:threshold id="threshold1" text="Low" maxValue="40" />
   <dvtm:threshold id="threshold2" text="Medium" maxValue="60" />
   <dvtm:threshold id="threshold3" text="High" maxValue="80" />
</dvtm:ledGauge>

Figure 6-60 LED Gauge at Design Time

The data model for a LED gauge is represented by a single metric value which is specified by the value attribute.

For information on attributes of the ledGauge and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define the following amx child elements:

• showPopupBehavior (see Section 6.2.8, "How to Use a Popup Component")

• closePopupBehavior (see Section 6.2.8, "How to Use a Popup Component")

• validationBehavior (see Section 6.9, "Validating Input")

6.5.14 How to Create a Status Meter Gauge

A Status Meter Gauge (statusMeterGauge) indicates the progress of a task or the level of some measurement along a horizontal rectangular bar or a circle. One part of the component shows the current level of a measurement against the ranges marked on another part. In addition, thresholds can be displayed behind the indicator whose size can be changed.

MAF AMX data visualization provides support for the reference line (referenceLine) on its status meter gauge component. You can use this line to produce a bullet graph.

Example 6-84 shows the statusMeterGauge element defined in a MAF AMX file.

<dvtm:statusMeterGauge id="meterGauge1"
                       value="65"
                       animationOnDisplay="auto"
                       animationDuration="1000"
                       inlineStyle="width: 300px;
                                    height: 30px;
                                    float: left;
                                    border-color: black;
                                    background-color: lightyellow;"
                       minValue="0"
                       maxValue="100">
   <dvtm:metricLabel/>
   <dvtm:threshold id="threshold1" text="Low" maxValue="40" />
   <dvtm:threshold id="threshold2" text="Medium" maxValue="60" />
   <dvtm:threshold id="threshold3" text="High" maxValue="80" />
</dvtm:statusMeterGauge>

Figure 6-61 Rectangular Status Meter Gauge at Design Time

To create a Status Meter Gauge represented by a circle (see Figure 6-62), you set its orientation attribute to circular. By default, this attribute is set to horizontal resulting in a horizontal rectangle.

Figure 6-62 Circular Status Meter Gauge at Design Time

The data model for a status meter gauge is a single metric value which is specified by the value attribute. In addition, the minimum and maximum values can also be specified by the minValue and maxValue attributes.

For information on attributes of the statusMeterGauge and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define the following amx child elements:

• showPopupBehavior (see Section 6.2.8, "How to Use a Popup Component")

• closePopupBehavior (see Section 6.2.8, "How to Use a Popup Component")

• validationBehavior (see Section 6.9, "Validating Input")

6.5.15 How to Create a Dial Gauge

A Dial Gauge (dialGauge) specifies ranges of values (thresholds) that vary from poor to excellent. The gauge indicator specifies the current value of the metric while the graphic allows for evaluation of the status of that value.

Example 6-84 shows the dialGauge element defined in a MAF AMX file.

<dvtm:dialGauge id="dialGauge1"
                background="#{pageFlowScope.background}"
                indicator="#{pageFlowScope.indicator}"
                value="#{pageFlowScope.value}"
                minValue="#{pageFlowScope.minValue}"
                maxValue="#{pageFlowScope.maxValue}"
                animationDuration="1000"
                animationOnDataChange="auto"
                animationOnDisplay="auto"
                shortDesc="#{pageFlowScope.shortDesc}"
                inlineStyle="#{pageFlowScope.inlineStyle}"
                styleClass="#{pageFlowScope.styleClass}"
                readOnly="true">
</dvtm:dialGauge>

Figure 6-63 Dial Gauge at Design Time

The data model for a dial gauge is a single metric value which is specified by the value attribute. In addition, the minimum and maximum values can be specified by the minValue and maxValue attributes.

For information on attributes of the dialGauge and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

Example 6-86 shows the definition of dialGauge element with the dark background theme and custom tick labels setting a range from -5000 to 5000.

<dvtm:dialGauge id="dialGauge1"
                background="circleDark"
                indicator="needleDark"
                value="#{pageFlowScope.value}"
                minValue="-5000"
                maxValue="5000"
                readOnly="false">
   <dvtm:metricLabel id="metricLabel1"
                     scaling="thousand" 
                     labelStyle="font-family: Arial, Helvetica; 
                                 font-size: 20; color: white;"/>
   <dvtm:tickLabel id="tickLabel1"
                   scaling="thousand"
                   labelStyle="font-family: Arial, Helvetica;
                               font-size: 18; color: white;"/>
</dvtm:dialGauge>

Figure 6-64 Dial Gauge with Metric and Tick Labels at Design Time

You can define the following amx child elements for the dialGauge:

• showPopupBehavior (see Section 6.2.8, "How to Use a Popup Component")

• closePopupBehavior (see Section 6.2.8, "How to Use a Popup Component")

• validationBehavior (see Section 6.9, "Validating Input")

6.5.16 How to Create a Rating Gauge

A Rating Gauge (ratingGauge) provides means to view and modify ratings on a predefined visual scale. By default, a rating unit is represented by a star. You can configure it as a circle, rectangle, star, or diamond by setting the shape attribute of the ratingGauge.

Example 6-87 shows the ratingGauge element defined in a MAF AMX file.

<dvtm:ratingGauge id="ratingGauge1"
                  value="#{pageFlowScope.value}"
                  minValue="0"
                  maxValue="5"
                  inputIncrement="full"
                  shortDesc="#{pageFlowScope.shortDesc}"
                  inlineStyle="#{pageFlowScope.inlineStyle}"
                  readOnly="true"
                  shape="circle"
                  unselectedShape="circle">
</dvtm:ratingGauge>

Figure 6-65 Rating Gauge at Design Time

The data model for a rating gauge is a single metric value which is specified by the value attribute. In addition, the minimum and maximum values can be specified by the minValue and maxValue attributes.

For information on attributes of the ratingGauge and dvtm child elements that you can define for this component, see Tag Reference for Oracle Mobile Application Framework.

You can define the following amx child elements for the ratingGauge:

• showPopupBehavior (see Section 6.2.8, "How to Use a Popup Component")

• closePopupBehavior (see Section 6.2.8, "How to Use a Popup Component")

• validationBehavior (see Section 6.9, "Validating Input")

.dvtm-ratingGauge {
}

.dvtm-ratingGauge .dvtm-ratingGaugeSelected {
   border-width: 1px;
   border-style: solid;
   border-color: #FFC61A;
   color: #FFBB00;
}

.dvtm-ratingGauge .dvtm-ratingGaugeUnselected {
   border-width: 1px;
   border-style: solid;
   border-color: #D3D3D3;
   color: #F4F4F4;
}

.dvtm-ratingGauge .dvtm-ratingGaugeHover {
   border-width: 1px;
   border-style: solid;
   border-color: #6F97CF;
   color: #7097CF;
}

.dvtm-ratingGauge .dvtm-ratingGaugeChanged {
   border-width: 1px;
   border-style: solid;
   border-color: #A8A8A8;
   color: #FFBB00;
}

6.5.17 How to Define Child Elements for Chart and Gauge Components

You can define a variety of child elements for charts and gauges. The following are some of these child elements:

• chartDataItem (see Section 6.5.17.1, "Defining Chart Data Item")

• xAxis, yAxis, and y2Axis (see Section 6.5.17.3, "Defining X Axis, YAxis, and Y2Axis")

• legend (see Section 6.5.17.2, "Defining Legend")

• pieDataItem (see Section 6.5.17.4, "Defining Pie Data Item")

• sparkDataItem (see Section 6.5.17.5, "Defining Spark Data Item")

• threshold (see Section 6.5.17.7, "Defining Threshold")

• funnelDataItem

For more information on these and other child elements, see Tag Reference for Oracle Mobile Application Framework.

In Oracle Enterprise Pack for Eclipse, child components of data visualization components are located under their respective visualization types (see Figure 6-66).

Figure 6-66 Creating Chart and Gauge Child Components

<dvtm:xAxis id="xAxis1" scrolling="on" axisMinValue="0.0" axisMaxValue="50.0" />

6.5.18 How to Create a Geographic Map Component

A Geographic Map (geographicMap) represents business data in one or more interactive layers of information superimposed on a single map. You can configure this component to use either Google or Oracle maps as the underlying map provider (see Section 6.5.18.1, "Configuring Geographic Map Components With the Map Provider Information").

Example 6-89 shows the geographicMap element defined in a MAF AMX file.

<dvtm:geographicMap id="g1" mapType="ROADMAP" 
                    centerX="-98.57" centerY="39.82" 
                    zoomLevel="2" initialZooming="auto">
   <dvtm:pointDataLayer id="pdl1"
                        var="row" 
                        value="#{bindings.locationData.collectionModel}"
                        dataSelection="multiple"
                        selectionListener="#{myBean.doSomeGood}">
      <dvtm:pointLocation id="pl1" type="address" address="#{row.address}">
         <dvtm:marker shortDesc="#{row.shortDesc}" id="m1" />
      </dvtm:pointLocation>
   </dvtm:pointDataLayer>
</dvtm:geographicMap>

Figure 6-67 Geographic Map at Design Time

You can define a pointDataLayer child element for the geographicMap. The pointDataLayer allows you to display data associated with a point on the map.The pointDataLayer can have a pointLocation as a child element. The pointLocation specifies the columns in the data layer's model that determine the location of the data points. These locations can be represented either by address or by X and Y coordinates.

The pointLocation can have a marker as a child element. The marker is used to stamp out predefined or custom shapes associated with data points on the map. The marker supports a set of properties for specifying a URI to an image that is to be rendered as a marker. The marker can have a convertNumber as its child element (see Section 6.3.25, "How to Convert Numerical Values").

For information on attributes of the geographicMap element and its child elements, see Tag Reference for Oracle Mobile Application Framework.

The Geographic Map component allows for insertion of a pin (creation of a point on the map) using a touch gesture. You can configure this functionality by using the mapInputListener. For more information, see Section 6.5.20, "How to Use Events with Map Components."

<adf-properties-child xmlns="http://xmlns.oracle.com/adf/config/properties">
   <adf-property name="mapProvider" value="googlemaps"/>
   <adf-property name="geoMapKey" value="your key"/>
</adf-properties-child>

<adf-properties-child xmlns="http://xmlns.oracle.com/adf/config/properties">
   <adf-property name="mapProvider" value="oraclemaps"/>
   <adf-property name="mapViewerUrl"
                 value="http://elocation.oracle.com/mapviewer"/>
   <adf-property name="baseMap" value="ELOCATION_MERCATOR.WORLD_MAP"/>
</adf-properties-child>

6.5.19 How to Create a Thematic Map Component

A Thematic Map (thematicMap) represents business data as patterns in stylized areas or associated markers. Thematic maps focus on data without the geographic details.

Example 6-92 shows the thematicMap element and its children defined in a MAF AMX file.

<dvtm:thematicMap id="tm1" 
                  animationOnDisplay="#{pageFlowScope.animationOnDisplay}"
                  animationOnMapChange="#{pageFlowScope.animationOnMapChange}"
                  animationDuration="#{pageFlowScope.animationDuration}"
                  basemap="#{pageFlowScope.basemap}"
                           tooltipDisplay="#{pageFlowScope.tooltipDisplay}"
                  inlineStyle="#{pageFlowScope.inlineStyle}"
                  zooming="#{pageFlowScope.zooming}"
                  panning="#{pageFlowScope.panning}"
                  initialZooming="#{pageFlowScope.initialZooming}">
   <dvtm:areaLayer id="areaLayer1"
                   layer="#{pageFlowScope.layer}"
                   animationOnLayerChange=
                      "#{pageFlowScope.animationOnLayerChange}"
                   areaLabelDisplay="#{pageFlowScope.areaLabelDisplay}"
                   labelType="#{pageFlowScope.labelType}"
                   areaStyle="background-color"
                   rendered="#{pageFlowScope.rendered}">
      <dvtm:areaDataLayer id="areaDataLayer1"
                          animationOnDataChange=
                             "#{pageFlowScope.dataAnimationOnDataChange}"
                          animationDuration=
                             "#{pageFlowScope.dataAnimationDuration}"
                          dataSelection="#{pageFlowScope.dataSelection}"
                          var="row" 
                          value="#{bindings.thematicMapData.collectionModel}">
         <dvtm:areaLocation id="areaLoc1" name="#{row.name}">
            <dvtm:area action="sales" id="area1" shortDesc="#{row.name}">
               <amx:setPropertyListener id="spl1" 
                                        to=
                   "#{DvtProperties.areaChartProperties.dataSelection}" 
                                        from="#{row.name}"
                                        type="action"/>
               <dvtm:attributeGroups id="ag1" type="color" value="#{row.cat1}" />
            </dvtm:area>
         </dvtm:areaLocation>
      </dvtm:areaDataLayer>
   </dvtm:areaLayer>
   <dvtm:legend id="l1" position="end">
      <dvtm:legendSection id="ls1" source="ag1"/>
   </dvtm:legend>
</dvtm:thematicMap>

Figure 6-68 Thematic Map at Design Time

Using the markerZoomBehavior attribute, you can enable scaling of the Thematic Map's markers when the map experiences zooming. You can enable the Marker rotation by setting its rotation attribute, whose value represents the angle at which the marker rotates in clockwise degrees around the center of the image.

MAF AMX Thematic Map supports the following advanced functionality:

• Custom markers (see Section 6.5.19.1, "Defining Custom Markers")

• Area isolation (see Section 6.5.19.3, "Defining Isolated Areas")

• Initial zooming (see Section 6.5.19.4, "Enabling Initial Zooming"

• Custom base maps (see Section 6.5.19.5, "Defining a Custom Base Map"

For information on attributes of the thematicMap element and its child elements, see Tag Reference for Oracle Mobile Application Framework.

<dvtm:areaLayer id="areaLayer1"
                ...
                areaStyle="background-color:transparent;border-color:transparent">

<basemap id="car" >
   <layer id="exterior" >
      <image source="/maps/car-800x800.png" 
             width="2560" 
             height="1920" />
      <image source="/maps/car-200x200.png"
             width="640"
             height="480" />
   </layer>
</basemap>

<dvtm:thematicMap id="tm1" basemap="car" source="customBasemaps/map1.xml" >
   <dvtm:areaLayer id="al1" layer="exterior" >
      <dvtm:pointDataLayer id="pdl1" 
                           var="row" 
                           value="{bindings.thematicMapData.collectionModel}" >
         <dvtm:pointLocation id="pl1" 
                             type="pointXY" 
                             pointX="#{row.x}"
                             pointY="#{row.y}" >
            <dvtm:marker id="m1" fillColor="#FFFFFF" shape="circle" />
         </dvtm:pointLocation>
      </dvtm:pointDataLayer>
   </dvtm:areaLayer>
</dvtm:thematicMap>

<dvtm:thematicMap id="demo1" basemap="car" source="customBasemaps/map1.xml" >
   <dvtm:areaLayer id="al1" layer="exterior" />
   <dvtm:pointDataLayer id="pdl1" 
                        var="row" 
                        value="{bindings.thematicMapData.collectionModel}" >
      <dvtm:pointLocation id="pl1" 
                          type="pointXY" 
                          pointX="#{row.x}"
                          pointY="#{row.y}" >
         <dvtm:marker id="m1" fillColor="#FFFFFF" shape="circle" />
      </dvtm:pointLocation>
   </dvtm:pointDataLayer>
</dvtm:thematicMap>

<basemap id="car" >
   <layer id="exterior" >
      <image source="/maps/car-800x800.png" 
             width="2560" 
             height="1920" />
      <image source="/maps/car-800x800-rtl.png" 
             width="2560" 
             height="1920" 
             dir="rtl" />
      <image source="/maps/car-200x200.png" 
             width="640" 
             height="480" />
      <image source="/maps/car-200x200-rtl.png"
             width="640"
             height="480"
             dir="rtl" />
   </layer>
   <points >
      <point name="hood" x="219.911" y="329.663" />
      <point name="frontLeftTire" x="32.975" y="32.456" />
      <point name="frontRightTire" x="10.334" y="97.982" />
   </points>
</basemap>

<dvtm:thematicMap id="demo1" basemap="car" source="customBasemaps/map1.xml" >
   <dvtm:areaLayer id="al1" layer="exterior" />
   <dvtm:pointDataLayer id="pdl1"
                        var="row"
                        value="#{bindings.thematicMapData.collectionModel}" >
      <dvtm:pointLocation id="pl1" type="pointName" pointName="#{row.name}" >
         <dvtm:marker id="m1" fillColor="#FFFFFF" shape="circle" />
      </dvtm:pointLocation>
   </dvtm:pointDataLayer>
</dvtm:thematicMap>

.dvtm-thematicMap {
   background-color: #FFFFFF;
   -webkit-user-select: none;
   -webkit-touch-callout: none;
   -webkit-tap-highlight-color: rgba(0,0,0,0);
}
   
.dvtm-areaLayer {
   background-color: #B8CDEC;
   border-color: #FFFFFF;
   border-width: 0.5px;
   /* border style and color must be set when setting border width */
   border-style: solid;
   color: #000000;
   font-family: tahoma, sans-serif;
   font-size: 13px;
   font-weight: bold;
   font-style: normal;
}
   
.dvtm-area {
   border-color: #FFFFFF;
   border-width: 0.5px;
   /* border style and color must be set when setting border width */
   border-style: solid;
}
   
.dvtm-marker {
   background-color: #61719F;
   opacity: 0.7;
   color: #FFFFFF;
   font-family: tahoma, sans-serif;
   font-size: 13px;
   font-weight: bold;
   font-style: normal;
   border-style: solid
   border-color: #FFCC33
   border-width: 12px
}

my-custom.js:

   CustomThematicMapStyle = {
      // selected area properties
      'areaSelected': {
         // selected area border color
         'borderColor': "#000000",
         // selected area border width
         'borderWidth': '1.5px'
      },

      // area properties on mouse hover
      'areaHover': {
         // area border color on hover
         'borderColor': "#FFFFFF",
         // area border width on hover
         'borderWidth': '2.0px'
      },
      
      // marker properties
      'marker': {
         // separator upper color
         'scaleX': 1.0,
         // separator lower color
         'scaleY': 1.0,
         // should display title separator
         'type': 'circle'
      },

      // thematic map legend properties
      'legend': {
         // legend position, such as none, auto, start, end, top, bottom
         'position': "auto"
      }
   };

})();

window['CustomThematicMapStyle'] =
{
   // custom style values 
   'styleDefaults': { 
      // custom color palette
      'colors': ["#000000", "#ffffff"],
      // custom marker shapes 
      'shapes' : ['circle', 'square'] 
   }
};

6.5.20 How to Use Events with Map Components

You can use the MapBoundsChangeEvent to handle the following map view property changes in the Geographic Map component:

• Changes to the zoom level.

• Changes to the map bounds.

• Changes to the map center.

When these changes occur, the component fires an event loaded with new map view property values.

You can define the mapBoundsChangeListener as an attribute of the Geographic Map.

You can use the MapInputEvent to handle the end user actions, such as taps and mouse clicks, in the Geographic and Thematic Map components. When these actions occur, the component fires an event loaded with the information on the latitude and longitude for the map, as well as the type of the action (for example, mouse down, mouse up, click, and so on).

You can define the mapInputListener as an attribute of the Geographic Map component.

For more information, see the following:

• Section 6.10, "Using Event Listeners"

• Java API Reference for Oracle Mobile Application Framework

• Tag Reference for Oracle Mobile Application Framework

6.5.21 How to Create a Treemap Component

A Treemap (treemap) displays hierarchical data across two dimensions represented by the size and color of its nodes (treemapNode).

In the Palette, the Treemap is located under MAF AMX Data Visualizations > Treemap (see Figure 6-69).

Figure 6-69 Treemap Location in the Palette

Example 6-101 shows the treemap element and its children defined in a MAF AMX file.

<dvtm:treemap id="treemap1"
              value="#{bindings.treemapData.collectionModel}"
              var="row"
              animationDuration="#{pageFlowScope.animationDuration}"
              animationOnDataChange="#{pageFlowScope.animationOnDataChange}"
              animationOnDisplay="#{pageFlowScope.animationOnDisplay}"
              layout="#{pageFlowScope.layout}"
              nodeSelection="#{pageFlowScope.nodeSelection}"
              rendered="#{pageFlowScope.rendered}"
              emptyText="#{pageFlowScope.emptyText}"
              inlineStyle="#{pageFlowScope.inlineStyle}" 
              sizeLabel="#{pageFlowScope.sizeLabel}"
              styleClass="dvtm-gallery-component"
              colorLabel="#{pageFlowScope.colorLabel}"
              sorting="#{pageFlowScope.sorting}"
              selectedRowKeys="#{pageFlowScope.selectedRowKeys}"
              isolatedRowKey="#{pageFlowScope.isolatedRowKey}"
              legendSource="ag1">
   <dvtm:treemapNode id="node1"
                     fillPattern="#{pageFlowScope.fillPattern}" 
                     label="#{row.label}"
                     labelDisplay="#{pageFlowScope.labelDisplay}" 
                     value="#{row.marketShare}" 
                     labelHalign="#{pageFlowScope.labelHalign}" 
                     labelValign="#{pageFlowScope.labelValign}">
      <dvtm:attributeGroups id="ag1" 
                            type="color" 
                            value="#{row.deltaInPosition}" 
                            attributeType="continuous"
                            minLabel="-1.5%"
                            maxLabel="+1.5%"
                            minValue="-1.5" 
                            maxValue="1.5" >
         <amx:attribute id="a1" name="color1" value="#ed6647" />
         <amx:attribute id="a2" name="color2" value="#f7f37b" />
         <amx:attribute id="a3" name="color3" value="#68c182" />
      </dvtm:attributeGroups>
   </dvtm:treemapNode>
</dvtm:treemap>

Figure 6-70 Treemap at Design Time

By setting the attributeType attribute of the attributeGroups element to continuous, you can enable visualization of a value associated with the Treemap item using a gradient color where the color intensity represents the relative value within a specified range.

For information on attributes of the treemap element and its child elements, see Tag Reference for Oracle Mobile Application Framework.

.dvtm-treemap {
   border-style: solid;
   border-color: #E2E8EE;
   border-radius: 3px;
   background-color: #EDF2F7;
   ...
}

.dvtm-treemapNodeSelected {
   // Selected node outer border color
   border-top-color: #E2E8EE;
   // Selected node inner border color
   border-bottom-color: #EDF2F7;
}

.dvtm-treemapNodeLabel {
   font-family: Helvetica, sans-serif;
   font-size: 14px;
   font-style: normal;
   font-weight: normal;
   color: #7097CF;
   ...
}

my-custom.js:

   window["CustomTreemapStyle"] = {
      
      // treemap properties
      "treemap" : {
         // Specifies the animation effect when the data changes - none, auto
         "animationOnDataChange": "auto",
         
         // Specifies the animation that is shown on initial display - none, auto
         "animationOnDisplay": "auto",
         
         // Specifies the animation duration in milliseconds
         "animationDuration": "500",
         
         // The text of the component when empty
         "emptyText": "No data to display",
         
         // Specifies the layout of the treemap - 
         // squarified, sliceAndDiceHorizontal, sliceAndDiceVertical
         "layout": "squarified",
         
         // Specifies the selection mode - none, single, multiple
         "nodeSelection": "multiple",
         
         // Specifies whether or not the nodes are sorted by size - on, off
         "sorting": "on"
      },

      // treemap node properties
      "node" : {
         // Specifies the label display behavior for nodes - node, off
         "labelDisplay": "off",
         
         // Specifies the horizontal alignment for labels displayed 
         // within the node - center, start, end
         "labelHalign": "end",
         
         // Specifies the vertical alignment for labels displayed 
         // within the node - center, top, bottom
         "labelValign": "center"
      },
   }

6.5.22 How to Create a Sunburst Component

A Sunburst (sunburst) displays hierarchical data across two dimensions represented by the size and color of its nodes (sunburstNode).

In the Palette, the Sunburst is located under MAF AMX Data Visualizations, as are its child nodes.

Example 6-106 shows the sunburst element and its children defined in a MAF AMX file.

<dvtm:sunburst id="sunburst1"
               value="#{bindings.sunburstData.collectionModel}"
               var="row"
               animationDuration="#{pageFlowScope.animationDuration}"
               animationOnDataChange="#{pageFlowScope.animationOnDataChange}"
               animationOnDisplay="#{pageFlowScope.animationOnDisplay}"
               colorLabel="#{pageFlowScope.colorLabel}"
               emptyText="#{pageFlowScope.emptyText}"
               inlineStyle="#{pageFlowScope.inlineStyle}"
               nodeSelection="#{pageFlowScope.nodeSelection}"
               rendered="#{pageFlowScope.rendered}"
               rotation="#{pageFlowScope.rotation}"
               shortDesc="#{pageFlowScope.shortDesc}"
               sizeLabel="#{pageFlowScope.sizeLabel}"
               sorting="#{pageFlowScope.sorting}"
               rotationAngle="#{pageFlowScope.startAngle}"
               styleClass="#{pageFlowScope.styleClass}"
               legendSource="ag1">
   <dvtm:sunburstNode id="node1" 
                      fillPattern="#{pageFlowScope.fillPattern}"
                      label="#{row.label}" 
                      labelDisplay="#{pageFlowScope.labelDisplay}"
                      value="#{pageFlowScope.showRadius ? 1 : row.marketShare}"
                      labelHalign="#{pageFlowScope.labelHalign}"
                      radius="#{pageFlowScope.showRadius ? row.booksCount : 1}">
      <dvtm:attributeGroups id="ag1" 
                            type="color" 
                            value="#{row.deltaInPosition}" 
                            attributeType="continuous"
                            minLabel="-1.5%"
                            maxLabel="+1.5%"
                            minValue="-1.5"
                            maxValue="1.5">
         <amx:attribute id="a1" name="color1" value="#ed6647" />
         <amx:attribute id="a2" name="color2" value="#f7f37b" />
         <amx:attribute id="a3" name="color3" value="#68c182" /> 
      </dvtm:attributeGroups>
   </dvtm:sunburstNode>
</dvtm:sunburst>

Figure 6-71 Sunburst at Design Time

By setting the attributeType attribute of the attributeGroups element to continuous, you can enable visualization of a value associated with the Sunburst item using a gradient color where the color intensity represents the relative value within a specified range.

For information on attributes of the sunburst element and its child elements, see Tag Reference for Oracle Mobile Application Framework.

.dvtm-sunburst {
   border-style: solid;
   border-color: #E2E8EE;
   border-radius: 3px;
   background-color: #EDF2F7;
   ...
}

.dvtm-sunburstNode {
   // Node border color
   border-color: "#000000";
}

.dvtm-sunburstNodeSelected {
   // Selected node border color
   border-color: "#000000";
}

.dvtm-sunburstNodeLabel {
   font-family: Helvetica, sans-serif;
   font-size: 14px;
   font-style: normal;
   font-style: normal;
   color: #7097CF;
   ...
}

my-custom.js:

window["CustomSunburstStyle"] = {
   // sunburst properties
   "sunburst" : {
      // Specifies whether or not the client side rotation is enabled - on, off
      "rotation": "off",
      
      // The text of the component when empty
      "emptyText": "No data to display",
      
      // Specifies the selection mode - none, single, multiple
      "nodeSelection": "multiple",
      
      // Animation effect when the data changes - none, auto
      "animationOnDataChange": "auto",
      
      // Specifies the animation that is shown on initial display - none, auto
      "animationOnDisplay": "auto",
      
      // Specifies the animation duration in milliseconds
      "animationDuration": "500",
      
      // Specifies the starting angle of the sunburst
      "startAngle": "90",
      
      // Specifies whether or not the nodes are sorted by size - on, off
      "sorting": "on"
   },
   
   // sunburst node properties
   "node" : {
      // Specifies whether or not the label is displayed - on, off
      "labelDisplay": "off"
   }
}

6.5.23 How to Create a Timeline Component

A Timeline (timeline) is an interactive component that allows viewing of events in chronological order, as well as navigating forward and backwards within a defined yet adjustable time range that can be used for zooming.

Events are represented by Timeline Item components (timelineItem) that include the title, description, and duration fill color. You can configure a dual timeline to display two series of events for a side-by-side comparison of related information.

In the Palette, the Timeline is located under MAF AMX Data Visualizations, as are its child components Timeline Item and Timeline Series.

Example 6-111 shows the timeline element and its children defined in a MAF AMX file.

<dvtm:timeline id="tl"
               itemSelection="#{pageFlowScope.itemSelection}"
               startTime="#{pageFlowScope.startTime}"
               endTime="#{pageFlowScope.endTime}">
   <dvtm:timelineSeries id="ts1"
                        label="#{pageFlowScope.s1Label}"
                        value="#{bindings.series1Data.collectionModel}"
                        var="row"
                        selectionListener=
                            "#{PropertyBean.timelineSeries1SelectionHandler}">
      <dvtm:timelineItem id="ti1"
                         startTime="#{row.startDate}"
                         endTime="#{row.endDate}"
                         title="#{row.title}"
                         description="#{row.description}" 
                         durationFillColor="#AAAAAA"/>
   </dvtm:timelineSeries>
   <dvtm:timeAxis id="ta1" scale="#{pageFlowScope.scale}"/>
</dvtm:timeline>

Figure 6-72 Timeline at Design Time

You can control the fill color of a specific Timeline Item's duration bar using its durationFillColor attribute.

To display two time scales at the same time on the Timeline, use the Time Axis' scale attribute that determines the scale of the second axis.

The Timeline can be scrolled horizontally as well as vertically. When the component is scrollable (that is, contains data outside of the visible display area), it is indicated by arrows pointing in the direction of the scroll.

For information on attributes of the timeline element and its child elements, see Tag Reference for Oracle Mobile Application Framework.

// Custom timeline style definition with listing
// of all properties that can be overriden
window["CustomTimelineStyle"] = {
   // Determines if items in the timeline are selectable
   "itemSelection": none

   // Timeline properties
   "timelineSeries" : {
      // Duration bars color palette
      "colors" : [comma separated list of hex colors]
   }
}

6.5.24 How to Create an NBox Component

An NBox (nBox) component presents data across two dimensions, with each dimension split into a number of ranges whose intersections form distinct cells into which each data item is placed.

In the Palette, the NBox is located under MAF AMX Data Visualizations.

Example 6-111 shows the nBox element and its children defined in a MAF AMX file.

<dvtm:nBox id="nBox1" 
           var="item" 
           value="#{bindings.NBoxNodesDataList.collectionModel}"
           columnsTitle="#{pageFlowScope.columnsTitle}"
           emptyText="#{pageFlowScope.emptyText}"
           groupBy="#{pageFlowScope.groupBy}"
           groupBehavior="#{pageFlowScope.groupBehavior}"
           highlightedRowKeys="#{pageFlowScope.showHighlightedNodes ? 
                                 pageFlowScope.highlightedRowKeys : ''}"
           inlineStyle="#{pageFlowScope.inlineStyle}"
           legendDisplay="#{pageFlowScope.legendDisplay}"
           maximizedColumn="#{pageFlowScope.maximizedColumn}"
           maximizedRow="#{pageFlowScope.maximizedRow}"
           nodeSelection="#{pageFlowScope.nodeSelection}" 
           rowsTitle="#{pageFlowScope.rowsTitle}"
           selectedRowKeys="#{pageFlowScope.selectedRowKeys}"
           shortDesc="#{pageFlowScope.shortDesc}">
   <amx:facet name="rows">
      <dvtm:nBoxRow value="low" label="Low" id="nbr1"/>
       <dvtm:nBoxRow value="medium" label="Med" id="nbr2"/>
       <dvtm:nBoxRow value="high" label="High" id="nbr3"/>
   </amx:facet>
   <amx:facet name="columns">
      <dvtm:nBoxColumn value="low" label="Low" id="nbc2"/>
      <dvtm:nBoxColumn value="medium" label="Med" id="nbc1"/>
      <dvtm:nBoxColumn value="high" label="High" id="nbc3"/>
   </amx:facet>
   <amx:facet name="cells">
      <dvtm:nBoxCell row="low"
                     column="low"
                     label=""
                     background="rgb(234,153,153)" 
                     id="nbc4"/>
      <dvtm:nBoxCell row="medium"
                     column="low"
                     label=""
                     background="rgb(234,153,153)" 
                     id="nbc5"/>
      <dvtm:nBoxCell row="high" 
                     column="low" 
                     label="" 
                     background="rgb(159,197,248)" 
                     id="nbc6"/>
      <dvtm:nBoxCell row="low"
                     column="medium"
                     label="" 
                     background="rgb(255,229,153)"
                     id="nbc7"/>
      <dvtm:nBoxCell row="medium" 
                     column="medium"
                     label=""
                     background="rgb(255,229,153)" 
                     id="nbc8"/>
      <dvtm:nBoxCell row="high" 
                     column="medium" 
                     label=""
                     background="rgb(147,196,125)" 
                     id="nbc9"/>
      <dvtm:nBoxCell row="low"
                     column="high"
                     label="" 
                     background="rgb(255,229,153)" 
                     id="nbc10"/>
      <dvtm:nBoxCell row="medium"
                     column="high" 
                     label=""
                     background="rgb(147,196,125)" 
                     id="nbc11"/>
      <dvtm:nBoxCell row="high" 
                     column="high"
                     label="" 
                     background="rgb(147,196,125)" 
                     id="nbc12"/>
   </amx:facet>
   <dvtm:nBoxNode id="nbn1"
                  row="#{item.row}"
                  column="#{item.column}" 
                  label="#{item.name}"
                  labelStyle="font-style:italic"
                  secondaryLabel="#{item.job}"
                  secondaryLabelStyle="font-style:italic" 
                  shortDesc="#{item.name + ': ' + item.job}">
      <dvtm:attributeGroups id="ag1"
                            type="indicatorShape" 
                            value="#{item.indicator1}"
                            rendered="#{pageFlowScope.showIndicator}"/>
      <dvtm:attributeGroups id="ag2"
                            type="indicatorColor" 
                            value="#{item.indicator2}"
                            rendered="#{pageFlowScope.showIndicator}"/>
      <dvtm:attributeGroups id="ag3"
                            type="color" 
                            value="#{item.group}"
                            rendered="#{pageFlowScope.showColors}"/>
   </dvtm:nBoxNode>
</dvtm:nBox>

Figure 6-73 NBox at Design Time

For information on attributes of the nBox element and its child elements, see Tag Reference for Oracle Mobile Application Framework.

6.5.25 How to Define Child Elements for Map Components, Sunburst, Treemap, Timeline, and NBox

You can define a variety of child elements for map components, Sunburst, Treemap, Timeline, and NBox. For information on available child elements and their attributes, see Tag Reference for Oracle Mobile Application Framework.

In Oracle Enterprise Pack for Eclipse, the Map, Sunburst, Treemap, Timeline, and NBox child components are located under MAF AMX Data Visualizations in the Palette (see Figure 6-74). In the figure, the Details option has been selected from Palette > Layout. This displays the tooltip content beside each icon in the MAF AMX Data Visualizations list.

Figure 6-74 Creating Map, Sunburst, Treemap, Timeline, and NBox Child Components

6.5.26 How to Create Databound Data Visualization Components

You can declaratively create a databound data visualization component using a data collection inserted from the Data Controls window (see Section 5.3.2.3, "Adding Data Controls to the View"). The palette selection that Figure 6-85 shows allows you to choose from a number of data visualization component categories, types, and layout options, all available under the heading MAF AMX Data Visualizations.

Figure 6-75 Palette Selection to Create Chart Components

To trigger the display of the Component Gallery, you drag and drop a collection from the Data Controls window onto a MAF AMX page, and then select either MAF Chart, MAF Gauge, or MAF Thematic Map from the context menu that appears (see Figure 6-76).

Figure 6-76 Creating Databound Data Visualization Components

After you select the category, type, and layout for your new databound component from the Component Gallery and click OK, you can start setting values the data collection attributes in the data visualization component. The name of the gallery, the dialog and the input field labels depend on the category and type of the data visualization component that you selected. For example, if you drag a data control of type chartData into your app, then select Chart > Horizontal Bar as the type, then the name of the dialog that appears is Bind Horizontal Bar Chart, giving you the ability to select the bound data elements (age, totalContribution, totalSavings, and shortDesc) and apply them either to the bars or to the Y axis, as Figure 6-77 shows.

Figure 6-77 Specifying Data Values for Databound Chart

The attributes in a data collection can be data values or categories of data values. Data values are numbers represented by markers, like bar height, or points in a scatter chart. Categories of data values are members represented as axis labels. The role that an attribute plays in the bindings (either data values or identifiers) is determined by both its data type (chart requires numeric data values) and where it is mapped (for example, Bars or X Axis).

If you use the Component Gallery to create a databound thematic map component, then the name of the dialog that appears is Bind 'thematicMap' and the Component Gallery lets you select the base map, with detail selections as the area layer. For example, if you select World as the base map and World continents as the area layer, the dialog shown in Figure 6-78 opens.

Figure 6-78 Bind 'thematicMap' Dialog

After completing one or more data binding dialogs, you can use the Properties window to specify settings for the component attributes. You can also use the child elements associated with the component to further customize it (see Section 6.5.17, "How to Define Child Elements for Chart and Gauge Components").

When you select MAF Geographic Map, MAF Sunburst, MAF NBox, MAF Timeline, or MAF Treemap from the context menu upon dropping a collection onto a MAF AMX page, one of the following dialogs appear:

Figure 6-79 Creating Geographic Map

Figure 6-80 Creating Sunburst

Figure 6-81 Creating Databound Timeline

Figure 6-82 Creating Databound Treemap

Figure 6-83 Creating Databound NBox

To complete the Create NBox dialog, you start by defining the number of rows and columns. Then you can select a cell on the box and specify values for the whole row or column in the bottom portion of the dialog, as Figure 6-84 shows.

Figure 6-84 Setting Row and Column Values for Databound NBox

The NBox component is created when you complete all pages of the series of dialogs by clicking Next.

For details on values for each field of each dialog, consult the online help by clicking Help or pressing F1.

6.6.1 How to Use Component Attributes to Define Style

You style your UI components by setting the following attributes:

• styleClass attribute defines a CSS style class to use for your layout component:

  <amx:panelPage styleClass="#{pageFlowScope.pStyleClass}">
  

  You can define the style class for layout, command, and input components in a MAF AMX page or in a skinning CSS file, in which case a certain style is applied to all components within the MAF AMX application feature (see Section 6.6.3, "What You May Need to Know About Skinning"). Alternatively, you can use the public style classes provided by MAF.

  Note:

  The CSS file is not accessible from Oracle Enterprise Pack for Eclipse. Instead, MAF injects this file into the package at build or deploy time, upon which the CSS file appears in the css directory under the Web Content root directory.

• inlineStyle attribute defines a CSS style to use for any UI component and represents a set of CSS styles that are applied to the root DOM element of the component:

  <amx:outputText inlineStyle="color:red;">
  

  You should use this attribute when basic style changes are required.

  Note:

  Some UI components are rendered with such subelements as HTML div elements and more complex markup. As a result, setting the inlineStyle attribute on the parent component may not produce the desired effect. In such cases, you should examine the generated markup and, instead of defining the inlineStyle attribute, apply a CSS class that would propagate the style to the subelement.

  For information on how to configure JavaScript debugging, see Section 22.3.5, "How to Enable Debugging of Java Code and JavaScript."

These attributes are displayed in the Property section in the Properties window, as Figure 6-85 shows. Use the Value column to specify the value of each property to define your style sheet.

Figure 6-85 Style Section of the Properties Window

For more information, see Tag Reference for Oracle Mobile Application Framework.

6.6.2 How to Work with Built-in and Inline Style Classes

Oracle Enterprise Pack for Eclipse includes tools for working with built-in style classes for each component. This is available from the Properties window when you click on a tag in an HTML file, or an XML file that contains an HTML representation (such as amx:tableLayout or a similar visual element).

OEPE gives you two options for modifying style classes:

• You can edit an element's inline style class, specifying the characteristics (font, size, weight, etc.) of the class.

• You can select from available built-in style classes already defined in CSS files for your application.

To edit an element's inline style class:

1. In the Source editor, click on a tag in the file that defines a visual display element, such as amx:tableLayout shown in Figure 6-86, with the tooltip displayed. In this example, Oracle Enterprise Pack for Eclipse displays the Table Layout page in the Properties pane:

   Figure 6-86 Editing the tableLayout display settings

   
   

2. From the Table Layout page, select the Style tab, as shown in Figure 6-87:

   Figure 6-87 Setting the table layout style

   
   

3. Double-click the icon next to the Inline style typein box. This opens the CSS Style Definition dialog, shown in Figure 6-88:

   Figure 6-88 CSS Style Definition dialog

   
   

4. At the left of the dialog, there is a list of style properties that you can edit. Selecting a different style property changes the main display, which reflects the characteristics of the selected style property. For example, the Text panel lets you specify font, size, style, and other characteristics of the text in the table; selecting the Border style property lets you set the width of top, left, right, and bottom borders individually, as well as selecting the thickness, color, and other characteristics.

5. When you have finished specifying the style characteristics, click OK. Oracle Enterprise Pack for Eclipse adds the table characteristics to the AMX file.

To select a built-in style class:

1. In the Source editor, click on a tag in the file that defines a visual display element, such as commandButton in Figure 6-89.

   Figure 6-89 Selecting a built-in style class

   
   

2. Click the icon at the right side of the Style Class field to display the Style Classes dialog, then expand the entries shown in Figure 6-90. Note that if your application has additional CSS files in its /css directory, they will be available for selection (this example only displays a single entry).

   Figure 6-90 The Style Classes dialog

   
   

3. Mouse over each of the style classes to learn more about it. When you have made your selection, click OK.

Selecting any AMX tag will cause the Properties pane to display a list of characteristics appropriate to that specific tag. For example, clicking the amf:outputText tag displays the Output Text dialog in the Properties pane, seen in Figure 6-91:

Figure 6-91 Output Text settings, All tab selected

As Figure 6-91 indicates, selecting the All tab displays a single dialog with all the properties available for editing. If you select the inlineStyle value, as shown here, and then click on the ellipsis icon highlighted at the right of the image, Oracle Enterprise Pack for Eclipse opens the CSS Style Definition dialog (seen in Figure 6-88), from which you can specify the desired characteristics for the text, background, block, box, border, list, positioning, and extension properties for amf:outputText.

6.6.3 What You May Need to Know About Skinning

Skinning allows you to define and apply a uniform style to all UI components within a MAF AMX application feature to create a theme for the entire feature.

The default skin family for MAF is called mobileAlta and the default version is the latest version of that skin. For more information, see Section 4.13, "Skinning Mobile Applications."

6.6.4 How to Style Data Visualization Components

Most of the style properties of MAF AMX data visualization components are defined in the dvtm.css file located in the css directory. You can override the default values by adding a custom CSS file with custom style definitions at the application feature level (see Section 4.13.9, "Overriding the Default Skin Styles").

Some of the style properties cannot be mapped to CSS and have to be defined in custom JavaScript files. These properties include the following:

• Background and needle images for the Dial Gauge component (see Section 6.5.15, "How to Create a Dial Gauge").

• Duration bars color palette for the Timeline component (see Section 6.5.23, "How to Create a Timeline Component").

• Base maps for the Thematic Map component (see Section 6.5.19.5, "Defining a Custom Base Map").

• Style properties of the Geographic Map component (see Section 6.5.18, "How to Create a Geographic Map Component").

• Style properties of the Thematic Map component (see Section 6.5.19.7, "Applying Custom Styling to the Thematic Map Component").

• Selected and unselected states of the Rating Gauge component (see Section 6.5.16.1, "Applying Custom Styling to the Rating Gauge Component").

You should specify these custom JavaScript files in the Includes section at the application feature level (see Section 4.11.1, "How to Define the Application Content"). By doing so, you override the default style values defined in the XML style template. Example 6-114 shows a JavaScript file similar to the one you would add to your MAF project that includes the MAF AMX application feature with data visualization components which require custom styling of properties that cannot be styled using CSS.

my-custom.js:

   CustomChartStyle = {

      // common chart properties
      'chart': {
         // text to be displayed, if no data is provided
         'emptyText': null,
         // animation effect when the data changes
         'animationOnDataChange': "none",
         // animation effect when the chart is displayed
         'animationOnDisplay': "none",
         // time axis type - disabled, enabled, mixedFrequency
         'timeAxisType': "disabled"
      },

      // chart title separator properties
      'titleSeparator': {
         // separator upper color
         'upperColor': "#74779A",
         // separator lower color
         'lowerColor': "#FFFFFF",
         // should display title separator
         'rendered': false
      },

      // chart legend properties
      'legend': {
         // legend position - none, auto, start, end, top, bottom
         'position': "auto"
      },

      // default style values
      'styleDefaults': {
         // default color palette
         'colors': ["#003366", "#CC3300", "#666699", "#006666", "#FF9900",
                    "#993366", "#99CC33", "#624390", "#669933", "#FFCC33",
                    "#006699", "#EBEA79"],
         // default shapes palette
         'shapes': ["circle", "square", "plus", "diamond",
                    "triangleUp", "triangleDown", "human"],
         // series effect
         'seriesEffect': "gradient",
         // animation duration in ms
         'animationDuration': 1000,
         // animation indicators - all, none
         'animationIndicators': "all",
         // animation up color
         'animationUpColor': "#0099FF",
         // animation down color
         'animationDownColor': "#FF3300",
         // default line width for line chart
         'lineWidth': 3,
         // default line style for line chart - solid, dotted, dashed
         'lineStyle': "solid",
         // should markers be displayed for line and area charts
         'markerDisplayed': false,
         // default marker color
         'markerColor': null,
         // default marker shape
         'markerShape': "auto",
         // default marker size
         'markerSize': 8,
         // pie feeler color for pie chart
         'pieFeelerColor': "#BAC5D6",
         // slice label position and text type for pie chart
         'sliceLabel': {
            'position': "outside",
            'textType': "percent" }
      }
   };

   CustomGaugeStyle = {
      // default animation duration in milliseconds
      'animationDuration': 1000,
      // default animation effect on data change
      'animationOnDataChange': "none",
      // default animation effect on gauge display
      'animationOnDisplay': "none",
      // default visual effect
      'visualEffects': "auto"
   };

   CustomTimelineStyle = {
      'timelineSeries' : {
      // duration bars color palette
      'colors' : ["#267db3", "#68c182", "#fad55c", "#ed6647"]
   };
...
}

After the JavaScript file has been defined, you can uncomment and modify any values. You add this file as an included feature in the maf-feature.xml file, as Example 6-115 shows.

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf:features xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xmlns:adfmf="http://xmlns.oracle.com/adf/mf">
   <adfmf:feature id="feature1" name="feature1">
      <adfmf:content id="feature1.1">
         <adfmf:amx file="feature1/untitled1.amx">
            <adfmf:includes>
               <adfmf:include type="StyleSheet" file="css/custom.css"/>
               <adfmf:include type="JavaScript" file="feature1/js/my-custom.js"/>
            </adfmf:includes>
         </adfmf:amx>
      </adfmf:content>
   </adfmf:feature>
</adfmf:features>

6.8.1 How to Configure UI and Data Visualization Components for Accessibility

MAF AMX UI and data visualization components have a built-in accessibility support, with most components being subject to the accessibility audit (see Figure 6-95).

Table 6-10 lists components and their attributes that you can set through the Accessibility section of the Properties window.

^Footnote 1 The landmark attribute has a default value (none) and is not subject to the accessibility audit.

You use the shortDesc attribute for different purposes for different components. For example, if you set the shortDesc attribute for the Image component, in the MAF AMX file it will appear as a value of the alt attribute of the image element.

The value of the shortDesc attribute can be localized.

For the Panel Group Layout and Deck components, you define the landmark role type (see Table 6-15, "Landmark Roles") that is applicable as per the context of the page. You can set one of the following values for the landmark attribute:

• default (none)

• application

• banner

• complementary

• contentinfo

• form

• main

• navigation

• search

Table 6-11 lists UI components whose accessible attributes defined by WAI-ARIA specification are automatically applied at run time and that you cannot modify.

^Footnote 1 The value attribute is not subject to the accessibility audit.

Figure 6-95 shows the accessibility audit warning displayed in Oracle Enterprise Pack for Eclipse.

Figure 6-95 Accessibility Audit Warning

For information on how to test your accessible MAF AMX application feature, see Section 22.2.1, "How to Perform Accessibility Testing on iOS-Powered Devices."

6.8.2 What You May Need to Know About the Basic WAI-ARIA Terms

As stated in the WAI-ARIA 1.0 specification, complex web applications become inaccessible when assistive technologies cannot determine the semantics behind portions of a document or when the user is unable to effectively navigate to all parts of it in a usable way. WAI-ARIA divides the semantics into roles (the type defining a user interface element), and states and properties supported by the roles. The following semantic associations form the base for the WAI-ARIA terms:

• Role

• Landmark

• Live region

For more information, see "Important Terms" at http://www.w3.org/TR/wai-aria/terms.

The following tables list role categories (as defined in the WAI-ARIA 1.0 specification) that are applicable to MAF.

Table 6-12 lists abstract roles that are used to support the WAI-ARIA role taxonomy for the purpose of defining general role concepts.

Table 6-13 lists widget roles that act as standalone user interface widgets or as part of larger, composite widgets.

Table 6-14 lists document structure roles that describe structures that organize content in a page. Typically, document structures are not interactive.

Table 6-15 lists landmark roles that represent regions of the page intended as navigational landmarks.

For the majority of MAF UI components, you cannot modify accessible WAI-ARIA attributes. For some components, you can set special accessible attributes at design time, and for the Panel Group Layout and Deck, you can use the WAI-ARIA landmark role type. For more information, see Section 6.8.1, "How to Configure UI and Data Visualization Components for Accessibility."

6.8.3 What You May Need to Know About the Oracle Global HTML Accessibility Guidelines

The Oracle Global HTML Accessibility Guidelines (OGHAG) is a set of scripting standards for HTML that Oracle follows. These standards represent a combination of Section 508 (see http://www.section508.gov) and Web Content Accessibility Guidelines (WCAG) 1.0 level AA (see http://www.w3.org/TR/WCAG10), with improved wording and checkpoint measurements.

For more information, see Oracle's Accessibility Philosophy and Policies at http://www.oracle.com/us/corporate/accessibility/policies/index.html.

6.10.1 What You May Need to Know About Constrained Type Attributes for Event Listeners

You can define event listeners as children of some MAF AMX UI components. The listeners' type attribute identifies which event they are to be registered to handle. Since each parent UI component supports only a subset of the events (suitable for that particular component), these supported events are presented in a constrained list of types that you can select for a listener.

Table 6-16 lists parent UI components, event listeners they can have as children, and event types they support.