35 Creating Databound Graph and Gauge Components

This chapter describes how to create graphs or gauges from data modeled with ADF Business Components, using ADF data controls and ADF Faces components in a Fusion web application. Specifically, it describes how you can use ADF Data Visualization areaGraph, barGraph, horizontalBarGraph, bubbleGraph, comboGraph, funnelGraph, lineGraph, paretoGraph, pieGraph, radarGraph, scatterGraph, sparkChart, stockGraph, and gauge components to create graphs and gauges that visually represent business data. It describes how to use ADF data controls to create these components with data-first development.

If you are designing your page using simple UI-first development, then you can add the graph or gauge to your page and configure the data bindings later. For information about the data requirements, tag structure, and options for customizing the look and behavior of the graph and gauge components, see the "Using Graph Components" and "Using Gauge Components" chapters in Developing Web User Interfaces with Oracle ADF Faces.

This chapter includes the following sections:

35.1 About ADF Data Visualization Graph and Gauge Components

ADF Data Visualization components provide extensive graphical and tabular capabilities for visually displaying and analyzing business data. Each component needs to be bound to data before it can be rendered since the appearance of the components is dictated by the data that is displayed.

Both graph and gauge components render graphical representations of data. However, graphs, which support more than 50 types of charts, allow you to evaluate multiple data points on multiple axes in a variety of ways. Many graph types assist in the comparison of results from one group with the results from another group. In contrast, gauges focus on a single data point and examine that point relative to minimum, maximum, and threshold indicators to identify problems.

The prefix dvt: occurs at the beginning of each data visualization component name indicating that the component belongs to the ADF Data Visualization Tools (DVT) tag library.

35.1.1 End User and Presentation Features

Visually compelling data visualization components enable end users to understand and analyze complex business data. The components are rich in features that provide out-of-the-box interactivity support. For detailed descriptions of the end user and presentation features for each component, see the following:

35.1.2 Data Visualization Components Use Cases and Examples

For detailed descriptions of data visualization use cases and examples, see the following:

35.1.3 Additional Functionality for Data Visualization Components

You may find it helpful to understand other Oracle ADF features before you data bind your data visualization components. Additionally, once you have added a data visualization component to your page, you may find that you need to add functionality such as validation and accessibility. Following are links to other functionality that data visualization components use:

  • Partial page rendering: You may want a data visualization component to refresh to show new data based on an action taken on another component on the page. For more information, see the "Rerendering Partial Page Content" chapter in Developing Web User Interfaces with Oracle ADF Faces.

  • Personalization: Users can change the way the data visualization components display at runtime, those values will not be retained once the user leaves the page unless you configure your application to allow user customization. For more information, see the "Allowing User Customization on JSF Pages" chapter in Developing Web User Interfaces with Oracle ADF Faces.

  • Accessibility: You can make your data visualization components accessible. For more information, see the "Developing Accessible ADF Faces Pages" chapter in Developing Web User Interfaces with Oracle ADF Faces.

  • Skins and styles: You can customize the appearance of data visualization components using an ADF skin that you apply to the application or by applying CSS style properties directly using a style-related property (styleClass or inlineStyle). For more information, see the "Customizing the Appearance Using Styles and Skins" chapter in Developing Web User Interfaces with Oracle ADF Faces.

  • Placeholder data controls: If you know the data visualization components on your page will eventually use ADF data binding, but you need to develop the pages before the data controls are ready, then you should consider using placeholder data controls, rather than manually binding the components. Using placeholder data controls will provide the same declarative development experience as using developed data controls. For more information, see Chapter 19, "Designing a Page Using Placeholder Data Controls."

35.2 Creating Databound Graphs

When you create a graph using a data collection inserted from the Data Controls panel, a Component Gallery allows you to choose from a wide number of graph categories, graph types, and layout options. Graph categories group together one or more types of graph. For example, the Bar category includes the following types of graphs:

  • Bar

  • Dual-Y Bar

  • Split Dual-Y Bar

  • Percent

  • Stacked Bar

  • Dual-Y Stacked Bar

  • Split Dual-Y Stack Bar

  • Floating Stacked Bar

Explore the Component Gallery that appears when you create a graph to view available graph categories, types, and descriptions for each one. Figure 35-1 shows the Component Gallery that appears for ADF graphs when you use the Data Controls panel.

Figure 35-1 ADF Graphs Component Gallery from Data Controls Panel

ADF Graphs Component Gallery

Note:

Some graph types require very specific kinds of data. If you bind a graph to a data collection that does not contain sufficient data to display the graph type requested, then the graph is not displayed and a message about insufficient data appears.

You can also create a graph by dragging a graph component from the Components window. This approach allows you the option of designing the graph's user interface before binding the component to data. A Create Graph dialog appears to view graph types, descriptions, and quick layout options. For more information about creating graphs using UI-first development, see the "Using Graph Components" chapter in Developing Web User Interfaces with Oracle ADF Faces.

Table 35-1 lists the categories that appear in the Component Gallery for graphs. Each category has one or more graph types associated with it.

Table 35-1 ADF Graph Categories in the Component Gallery

Category Description

Area

Creates a graph in which data is represented as a filled-in area. Use area graphs to show trends over time, such as sales for the last 12 months. Area graphs require at least two groups of data along an axis. The axis is often labeled with time periods such as months.

Bar

Creates a graph in which data is represented as a series of vertical bars. Use to examine trends over time or to compare items at the same time, such as sales for different product divisions in several regions.

Bar (Horizontal)

Creates a graph that displays bars horizontally along the y-axis. Use to provide an orientation that allows you to show trends or compare values.

Bubble

Creates a graph in which data is represented by the location and size of round data markers (bubbles). Use to show correlations among three types of values, especially when you have a number of data items and you want to see the general relationships. For example, use a bubble graph to plot salaries (x-axis), years of experience (y-axis), and productivity (size of bubble) for your work force. Such a graph allows you to examine productivity relative to salary and experience.

Combination

Creates a graph that uses different types of data markers (bars, lines, or areas) to display different kinds of data items. Use to compare bars and lines, bars and areas, lines and areas, or all three.

Funnel

Creates a graph that is 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 graph requires actual values and target values against a stage value, which might be time. For example, use this component to watch a process (such as a sales pipe line) move towards a target across the stage of the quarters of a fiscal year.

Line

Creates a graph in which data is represented as a line, as a series of data points, or as data points that are connected by a line. Line graphs require data for at least two points for each member in a group. For example, a line graph over months requires at least two months. Typically a line of a specific color is associated with each group of data such as the Americas, Europe, or Asia. Use to compare items over the same time.

Pareto

Creates a graph in which data is represented by bars and a percentage line that indicates the cumulative percentage of bars. Each set of bars identifies different sources of defects, such as the cause of a traffic fatality. The bars are arranged by value, from the largest number to the lowest number of incidents. A pareto graph is always a dual-y graph in which the first y-axis corresponds to values that the bars represent and the second y-axis runs from 0 to 100% and corresponds to the cumulative percentage values. Use the pareto graph to identify and compare the sources of defects.

Pie

Creates a graph in which one group of data is represented as sections of a circle causing the circle to look like a sliced pie. Use to show relationship of parts to a whole such as how much revenue comes from each product line.

Radar

Creates a graph that appears as a circular line graph. Use to show patterns that occur in cycles, such as monthly sales for the last three years.

Scatter/Polar

Creates a graph in which data is represented by the location of data markers. Use to show correlation between two different kinds of data values such as sales and costs for top products. Scatter graphs are especially useful when you want to see general relationships among a number of items.

Sparkchart

Creates a simple, condensed graph that displays trends or variations, often in the column of a table, or inline with text.

Stock

Creates a graph in which data shows the high, low, and closing prices of a stock and, optionally, the opening price and trading volume of the stock.

Figure 35-2 shows the vertical bar graph that appears on the Orders Dashboard page in the Summit ADF sample application. This graph displays the number of days it took to ship each order for a given customer so that you can easily identify any trends in ship times.

Figure 35-2 Order Ship Time Bar Graph

Order ship times graph

For information about customizing graphs after the data binding is completed, see the "Configuring Graphs" chapter in Developing Web User Interfaces with Oracle ADF Faces.

35.2.1 How to Create an Area, Bar, or Line Graph Using Data Controls

Graphs are based on data collections. Using data controls in Oracle ADF, JDeveloper makes this a declarative task. You drag and drop a collection from the Data Controls panel onto the JSF page and use a dialog to bind the data collection attributes in the graph.

The graph requires a simple grid of numeric data points to plot a graph. The grid's row and column labels are used to identify components within the graph. By default, the rows appear as the series and the columns appear as the groups.

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 graph. Categories of data values are members represented as axis labels, or appear as additional properties in a tooltip. The role that an attribute plays in the bindings (either data values or identifiers) is determined by both its data type (Graph requires numeric data values) and where it gets mapped (e.g., Bars vs. X Axis).

Before you begin:

It may be helpful to have an understanding of databound data visualization graphs. For more information, see Section 35.2, "Creating Databound Graphs."

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Section 35.1.3, "Additional Functionality for Data Visualization Components."

You will need to complete these tasks:

To create a databound area, bar, or line graph:

  1. From the Data Controls panel, select a collection.

    For example, to create the bar graph that displays the shipping times for each order on the Orders Dashboard page of the Summit ADF sample application, select the OrdersForCustomer collection. Figure 35-3 shows the OrdersForCustomer collection in the Data Controls panel.

    Figure 35-3 Data Collection for Order Ship Times

    Data collection for order ship times

  2. Drag the collection onto a JSF page and, from the context menu, choose Graphs.

  3. In the Component Gallery, select a graph category and a graph type and click OK.

    For information about the graph categories and graph types that appear in the Component Gallery, see Table 35-1.

    The name of the dialog and the input field labels that appear depend on the category, type of graph, and data collection that you select. For example, if you select Bar as the graph category and Bar as the graph type, then the name of the dialog that appears is Create Bar Graph and the input fields are labeled Bars and X Axis.

  4. Do the following in the dialog to configure the graph to display data:

    • Drag attributes from the Available list to the Bars or X Axis input fields, depending on where you want the values for the attributes to appear at runtime.

      For example, to configure the bar graph in the Summit ADF sample application to display the order dates along the X Axis, drag the DateOrdered attribute from the Available list to the X Axis field in the Create Bar Graph dialog. To configure the graph to display the time to ship as bars, drag the TimeToShip attribute from the Available list to the Bar field in the Create Bar Graph dialog.

    • In the Attribute Labels table, accept the default value or select a value from the dropdown list in the Label field to specify the label that appears at runtime.

      The underlying data type determines the choices available in the Label field. The choice you make determines how that attribute's label is rendered in the graph. For more information, see Section 35.2.3, "What You May Need to Know About Using Attribute Labels."

    • If you want to change the display of the data represented in the bars to the Y-Axis, click the Swap Bars with Y-Axis button. This action switches the hidden data layer between the graph series and groups, not a simple manual swap of the bars and y-axis attributes.

    • If you want to change from the default selection of Typed Attributes to Name-Value Pairs to configure how data points are stored in a collection, then click the Change Data Shape button. A dialog appears that presents you with the following options:

      • Typed Attributes

        Each kind of data point in the collection is represented by a different attribute. This option is also valid when there is only a single kind of data point in the graph.

        For example, if you have data points for Estimated Value and Actual Value, then select Typed Attributes only if you have one attribute for the estimated value and a second attribute for the actual value.

      • Name-Value Pairs

        Indicates that there are two or more kinds of data points represented by exactly two attributes; a Name attribute that specifies the kind of data point, and a Value attribute that specifies the data value.

        For example, the Name attribute might have the value EST for a Value attribute that represents an estimated value, or the Name attribute might have a value ACT for a Value attribute that represents an actual value.

        For more information about using name-value pairs, see Section 35.2.5, "What You May Need to Know About Using Name-Value Pairs."

    • Select Set the current row for master-detail to use the graph's row selection listener to enable clicks on a bar, slice, or other graph data element to update the data in another ADF component.

      For more information, see Section 35.2.4, "What You May Need to Know About Using a Graph's Row Selection Listener for Master-Detail Processing."

      Note:

      If the data collection is the child collection in a master-detail relationship, the dialog includes the option to Include Child Accessors (Hierarchical Graph). This option is included for backwards compatibility with older data models that mapped Tree collections onto the graph's cube model, and you normally would not check this box.

    Figure 35-4 shows the Create Bar Graph dialog that generates the Summit ADF sample application ship times bar graph using data from the DateOrdered and TimeToShip attributes in the OrdersForCustomer data collection.

    Figure 35-4 Create Bar Graph Dialog for Time to Ship Graph

    Create bar graph for TimeToShip graph

  5. Optionally, click the Preview tab to display a live preview of the bar graph and its data. If necessary, go back to the Configuration tab so that you can adjust the bar graph specifications.

  6. Click OK.

After completing the data binding dialog, you can use the Properties window to specify settings for the graph attributes and you can also use the child tags associated with the graph tag to customize the graph further. For more information, see "Configuring Graphs" in Developing Web User Interfaces with Oracle ADF Faces.

Note:

Use the emptyText attribute to specify the text to display when there is no data to return in the graph. The default message is No data to display. The attribute accepts HTML for formatting the message and an EL expression that evaluates to the viewable property of the data. If the graph is not viewable (for example, if there are authorization restrictions set against the graph), it displays Access Denied.

35.2.2 What Happens When You Use the Data Controls Panel to Create a Graph

Dropping a graph from the Data Controls panel has the following effect:

  • Creates the bindings for the graph and adds the bindings to the page definition file

  • Adds the necessary code for the UI components to the JSF page

The data binding XML that JDeveloper generates varies depending on the type of graph you select. The XML represents the physical model of the specific graph type you create. Example 35-1 shows the bindings that JDeveloper generated in the page definition file where a vertical bar graph was created using data from the DateOrdered and TimeToShip attributes in the OrdersForCustomer data collection.

Example 35-1 Binding XML for an ADF Bar Graph

<graph IterBinding="OrdersForCustomerIterator" id="OrdersForCustomer"
       xmlns="http://xmlns.oracle.com/adfm/dvt" type="BAR_VERT_CLUST">
  <graphDataMap convert="false" leafOnly="true">
    <series>
      <data>
        <item value="TimeToShip"/>
      </data>
    </series>
    <groups>
      <item value="DateShipped"/>
    </groups>
  </graphDataMap>
</graph>

Example 35-2 shows the code generated for a vertical bar graph when you drag the OrdersForCustomer data collection onto a JSF page.

Example 35-2 JSF Code for an ADF Bar Graph

<dvt:barGraph id="graph2" value="#{bindings.OrdersForCustomer.graphModel}"
                          subType="BAR_VERT_CLUST">
  <dvt:background>
    <dvt:specialEffects/>
  </dvt:background>
  <dvt:graphPlotArea/>
    <dvt:seriesSet>
       <dvt:series/>
    </dvt:seriesSet>
  <dvt:o1Axis/>
  <dvt:y1Axis/>
  <dvt:legendArea automaticPlacement="AP_NEVER"/>
  <dvt:attributeFormat name="TimeToShip" id="af3">
    <af:convertNumber pattern="#{bindings.OrdersForCustomer1.hints.TimeToShip.format}"
                      groupingUsed="false"/>
  </dvt:attributeFormat>
  <dvt:attributeFormat name="DateOrdered" id="af4">
    <af:convertDateTime pattern="#{bindings.OrdersForCustomer1.hints.DateOrdered.format}"/>
  </dvt:attributeFormat>
</dvt:barGraph>

Note:

When you create a graph using data-first development, JDeveloper adds a dvt:attributeFormat tag to the page for every non-string categorical attribute. In this example, the TimeToShip attribute represents a numerical value, and the DateOrdered attribute represents a date. Therefore, JDeveloper added the dvt:attributeFormat tags for both attributes.

You can update the dvt:attributeFormat tag after the graph is created. For additional information, see "Formatting Data Values in Graphs" in Developing Web User Interfaces with Oracle ADF Faces.

35.2.3 What You May Need to Know About Using Attribute Labels

When you configure attribute labels in the Create Graph dialog, the underlying data type determines the choices available in the Label field. The choice you make determines how that attribute's label is rendered in the graph.

If an attribute represents data values, then the choices in the Label field are:

  • Use Attribute Name: Select to render the value as a string using the label from the UIHints for that attribute in the underlying ViewObject. This is the default selection.

  • No Label: Select to render no label. This choice is useful if there is a single metric and you want to provide your own descriptive text on the page to describe the resulting graph.

  • Select Text Resource: Select to open a Select Text Resource dialog to select or add a text resource to use for the label. The text resource is a translatable string from an application resource bundle. If you need help, press F1 or click Help.

  • Expression Builder: Select to open the Expression Builder dialog to create an expression to be executed at runtime for the label. If you need help, press F1 or click Help.

If the attribute represents a category of data values, then the choices are:

  • Use Attribute Value: Select to render the attribute values as category labels. This is the default selection.

  • From the dropdown list, choose an alternate attribute for the label. For example, use Employee Names for labels instead of Employee IDs.

35.2.4 What You May Need to Know About Using a Graph's Row Selection Listener for Master-Detail Processing

You can use the row selection listener of a graph (which serves as a master view) to enable clicks on a bar, slice, or other graph data element to update the data in another ADF component (which serves as a detail view). For example, clicking on a bar that represents sales for a given product in a graph might cause the display of the detailed sales data for that product in a pivot table.

The following requirements must be met to achieve this master-detail processing declaratively:

  1. You must use the same data control to provide data for both views as follows:

    1. Bind the graph as a row set to the parent collection in the data control, for example, DepartmentsView.

    2. Bind the other ADF view (such as a table or pivot table) to the dependent detail collection in the data control, for example EmployeesView.

  2. Select Set the current row for master-detail in the Create Graph dialog to set a value automatically for the clickListener attribute of the graph tag and use the processClick method that is already part of the graph binding.

    For example, if the value attribute of the graph tag is value="#{bindings.myGraph.graphModel}", then the clickListener attribute is set to clickListener="#{bindings.myGraph.graphModel.processClick}".

You do not have to write Java code for handling clicks on data elements in the graph. The processClick event on the graph binding recognizes click events on data component in a graph and performs the necessary processing.

35.2.5 What You May Need to Know About Using Name-Value Pairs

When you configure a graph using data controls, by default the data binding dialog supports typed attributes, where each kind of data point in the collection is represented by a different attribute. For example, if you have data points for the sales and costs of multiple products, use typed attributes only if you have one attribute for the sales data of each product, and a second attribute for the cost of each product in the data collection.

Typed attributes data shape is also valid when there is only a single kind of data point in the graph. Figure 35-5 shows a typed attribute data shape.

Figure 35-5 Typed Attribute Data Shape

typed attributes data shape

You can select Change Data Shape in the data binding dialog to change the dialog to support name-value pairs, where there are two or more kinds of data points represented by exactly two attributes: a Name attribute that specifies the name of the data point and a Value attribute that specifies the data value. In this case, each dedicated attribute has values that identify each kind of data point. For example, the metrics attribute might have values for dales and costs for each product in a data collection. Figure 35-6 shows a data collection in a name-value pairs data shape.

Figure 35-6 Name-Value Pairs Data Shape

name-value pairs data shape

When using a name-value pairs data shape, specify these values in the graph data binding dialog:

  • Name Attribute: the attribute in the data collection representing the Name attribute, when its unique values categorize data points into different metrics.

  • Value Attribute: the attribute in the data collection representing the numeric data points plotted on the graph. Each data point is categorized as belonging to a particular metric by the corresponding Name attribute value.

  • Specify the values for the Value attribute in the relevant fields for the graph type as defined in the dialog, for example, Bubble Colors and Bubble Tooptips for a bubble graph. Values can be attributes in the data collection, or data values, representing a unique value of the Name attribute to be used at runtime to categorize data points into specific metrics.

    You must add one or more data values by selecting Data Value from the field Add dropdown list. Each data value represents a unique value of the Name Attribute to be used at runtime to categorize data points into specific metrics. You are not required to select all the metrics available in the Name Attribute.

    After specifying attributes or data values for the input field, you can right-click any attribute to display a context menu for actions such as Move Right, Move Left, Delete, or Edit Data Value.

For example, you can create a stock graph that displays open, high, low, and close stock values bound to a data collection with a single numeric column of data in a name-value pairs shape as displayed in Figure 35-7.

Figure 35-7 Stock Graph Created With Name-Value Pairs

Stock Graph Created With Name-Value Pairs

35.2.6 How to Create a Stock Graph Using Name-Value Pairs

You can create a graph where the data collection is arranged in a series of name-value pairs instead of typed attributes. For example, stock values may be arranged in a single numeric column of data with multiple data points and multiple attributes to designate these points

Figure 35-8 shows an example of a data collection arranged in name-value pairs. For each MarketDate, the Measure attribute contains the names for the values stored in the Data attribute: OPEN, HIGH, LOW, CLOSE, and VOLUME.

Figure 35-8 Stock Values in Name-Value Pairs Data Shape

stock values in name-value pairs data shape

Before you begin:

It may be helpful to have an understanding of databound data visualization graphs. For more information, see Section 35.2, "Creating Databound Graphs."

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Section 35.1.3, "Additional Functionality for Data Visualization Components."

It may also be helpful to understand name-value pairs data shapes. For information, see Section 35.2.5, "What You May Need to Know About Using Name-Value Pairs."

You will need to complete these tasks:

To create a graph using a name-value pairs data shape:

  1. From the Data Controls panel, select a collection.

    In the example to create a graph that displays the open, high, low, and close stock values over a week's time, select the collection SStockPriceView1. Figure 35-9 shows the SStockPriceView1 collection in the Data Controls panel.

    Figure 35-9 Data Collection for Stock Values in Single Column

    Data collection for stock values in single column

  2. Drag the collection onto a JSF page and, from the context menu, choose Graphs.

  3. In the Component Gallery, select the Stock graph category, then the Open-Hi-Lo-Close Candle with Volume graph type, and click OK.

  4. Do the following to change the dialog to support a name-value pairs data shape:

    • Click Change Data Shape.

    • In the Change Chart Data Shape dialog, select Name-Value Pairs, and click OK.

    • If prompted, confirm your selection.

  5. Do the following in the modified dialog to configure the graph to display data:

    • For Name Attribute, select the attribute containing the names of the name-value pairs.

      For example, choose Measure from the dropdown list to create a stock graph using the data collection in Figure 35-8.

    • For Value Attribute, specify the attribute containing the data for the name-value pairs.

      For example, choose Data from the dropdown list to create a stock graph using the data collection in Figure 35-8.

    • In the Chart Values table, accept the default value or select a value from the dropdown list in the Label field to specify the label that appears at runtime.

      The underlying data type determines the choices available in the Label field. The choice you make determines how that attribute's label is rendered in the graph. For more information, see Section 35.2.3, "What You May Need to Know About Using Attribute Labels."

    • Set the current row for master-detail: Select to use the graph's row selection listener to enable clicks on a bar, slice, or other graph data element to update the data in another ADF component. For more information see Section 35.2.4, "What You May Need to Know About Using a Graph's Row Selection Listener for Master-Detail Processing."

      Note:

      If the data collection is the child collection in a master-detail relationship, the dialog includes the option to Include Child Accessors (Hierarchical Graph). This option is included for backwards compatibility with older data models that mapped Tree collections onto the graph's cube model, and you normally would not check this box.

    Figure 35-10 shows the Create Stock Graph dialog that generates a graph using the Measure attribute in the SStockPriceView1 collection.

    Figure 35-10 Create Stock Graph for StockSingleFactColView1

    Create stock graph for StockSingleFactColView1

  6. Optionally, click the Preview tab to display a live preview of the stock graph and its data. If necessary, go back to the Configuration tab so that you can adjust the stock graph specifications.

  7. Click OK.

35.2.7 Creating a Databound Spark Chart Using Data Controls

Spark charts are simple, condensed graphs that display trends or variations, often in the column of a table, or inline with text. Line, bar, and area spark charts require a single series of data values. Figure 35-11 shows an example of a line spark chart in a table column.

Figure 35-11 Line Spark Chart in Table of Stock Prices

line spark chart in table

Floating bar spark charts require two series of data values, one for the float offset, and one for the bar value. Figure 35-12 shows an example of a floating bar sparkchart.

Figure 35-12 Floating Bar Spark Chart

floating bar spark chart

You can create a sparkchart by inserting a data control from the Data Controls Panel. Figure 35-13 shows the Component Gallery that displays when you drag a sparkchart component onto your page from the Data Controls panel.

Figure 35-13 Create Sparkchart Component Gallery

Create sparkchart component gallery.

A binding dialog prompts you to specify the value you wish to display for the selected sparkchart type. Line, bar, and area spark charts require a single series of data values, for example the changing value of a stock. Floating bar sparkcharts require two series of data values, one for the float offset, and one for the bar value. For example, in the Create Floating Stacked Bar Sparkchart dialog you specify:

  • Bar Height: Use to select the data value to use for the bar value.

  • Bar Float: Use to select the data value to use for the float offset, the distance between the axis and the floating bar.

Figure 35-14 shows a completed Create Floating Stacked Bar Sparkchart dialog.

Figure 35-14 Sparkchart Binding Dialog

Sparkchart Binding Dialog

In a simple UI-first development scenario you can insert a sparkchart using the Components window and bind it to data afterwards.

You can provide data to sparkcharts in any of the following ways:

  • Specify data statically in child dvt:sparkItem tags. Example 35-3 shows an example of providing static data to a sparkchart.

    Example 35-3 Static Data in Sparkchart

    <dvt:sparkChart>
  <dvt:sparkItem value="20"/>
  <dvt:sparkItem value="15"/>
  <dvt:sparkItem value="30"/>
</dvt:sparkChart>

  • Specify data using EL Expression in child dvt:sparkItem tags. Example 35-4 shows an example of providing data using EL Expressions.

    Example 35-4 EL Expression Data in Sparkchart

    <af:table value="#{sample.tableModel}" var="row">
  <af:column>
    <dvt:sparkChart>
      <dvt:sparkItem value="#{row.col1}"/>
      <dvt:sparkItem value="#{row.col2}"/>
      <dvt:sparkItem value="#{row.col3}"/>
    </dvt:sparkChart>
  </af:column>
</af:table>

  • Specify data using a child accessor in a table. Example 35-5 shows an example of using af:iterator to provide sparkchart data from the data collection model, row.stockValues.

    Example 35-5 Sparkchart Data in Table Child Accessor

    <af:table value="#{sample.tableModel}" var="row">
  <af:column>
    <dvt:sparkChart>
      <af:iterator value="#{row.stockValues}" var="data">
        <dvt:sparkItem value="#{data.closeValue}"/>
      </af:iterator>
    </dvt:sparkChart>
  </af:column>
</af:table>

35.2.8 How to Create Databound Pie Graphs

A pie graph displays one group of data, each slice representing a different series. This graph type requires one column, with multiple rows, one for each slice. Multiple pie graphs show one pie for each group, or column, of data. Pie graphs can be drawn with just one data point, though such graphs may not be useful. In the case of pie bar graphs, each slice represents a series total. The data for one such slice is represented in further detail by a percentage stacked bar.

Figure 35-15 shows a pie graph in the Summit ADF sample application that displays the inventory available for the ordered item at each stock location as a percentage of the total available inventory for the item. As the user moves the mouse over each slice, a tooltip shows the actual quantity at the location. The column of data in this example represents the total inventory for the ordered item, and the slices represent the inventory levels at each stocking location.

Figure 35-15 Pie Graph Showing Inventory Levels at Stock Locations

Pie graph showing inventory at stock locations

Before you begin:

It may be helpful to have an understanding of databound data visualization graphs. For more information, see Section 35.2, "Creating Databound Graphs."

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Section 35.1.3, "Additional Functionality for Data Visualization Components."

You will need to complete these tasks:

To create a databound pie graph:

  1. From the Data Controls panel, select a collection.

    For example, to create the pie graph that displays the inventory levels at each stock location in the Summit Customer Management page of the Summit ADF sample application, select the BackOfficeAppModuleDataControl > Customers > OrdersForCustomer > ItemsForOrder > InventoryForOrderItem collection. Figure 35-16 shows the InventoryForOrderItem collection in the Data Controls panel.

    Figure 35-16 Data Collection for InventoryForOrderItem Collection

    Data Control for Example Pie Graph

  2. Drag the collection onto a JSF page and, from the context menu, choose Graphs.

  3. In the Component Gallery, select the Pie graph category and a graph type and click OK.

    For example, select the Pie graph category and the Pie graph type to create the pie graph in Figure 35-15.

  4. Do the following in the Create Pie Graph dialog to configure the pie graph to display data:

    • From the Pie field's dropdown menu, select an attribute to represent the column of data.

      For example, to configure the pie graph in the Summit ADF sample application to display inventory levels, select the AmountInStock attribute from the Pie field's dropdown menu.

    • Drag attributes from the Available list to the Slices field, depending on where you want the values for the attributes to appear at runtime.

      For example, to configure the pie graph in the Summit ADF sample application to display the ordered item's inventory levels at each stock location, drag the City attribute from the Available list to the Slices field in the Create Pie Graph dialog.

    • In the Attribute Labels table, accept the default value or select a value from the dropdown list in the Label field to specify the label that appears at runtime.

      The underlying data type determines the choices available in the Label field. The choice you make determines how that attribute's label is rendered in the graph. For more information, see Section 35.2.3, "What You May Need to Know About Using Attribute Labels."

    • Select Set the current row for master-detail to use the graph's row selection listener to enable clicks on a bar, slice, or other graph data element to update the data in another ADF component.

      For more information, see Section 35.2.4, "What You May Need to Know About Using a Graph's Row Selection Listener for Master-Detail Processing."

      Note:

      If the data collection is the child collection in a master-detail relationship, the dialog includes the option to Include Child Accessors (Hierarchical Graph). This option is included for backwards compatibility with older data models that mapped Tree collections onto the graph's cube model, and you normally would not check this box.

    • If you want to change from the default selection of Typed Attributes to Name-Value Pairs to configure how data points are stored in a collection, then click the Change Data Shape button.

      For more information about using name-value pairs, see Section 35.2.5, "What You May Need to Know About Using Name-Value Pairs."

    Figure 35-17 shows the Create Pie Graph dialog that generates a pie graph using the AmountInStock and City attributes in the InventoryForOrderItem collection.

    Figure 35-17 Create Pie Graph for InventoryForOrderItem

    Create Pie Graph for InventoryForOrderItem

  5. Optionally, click the Preview tab to display a live preview of the pie graph and its data. If necessary, go back to the Configuration tab so that you can adjust the stock graph specifications.

  6. Click OK.

After completing the data binding dialog, you can use the Properties window to specify settings for the graph attributes and you can also use the child tags associated with the graph tag to customize the graph further. For more information, see "Configuring Graphs" in Developing Web User Interfaces with Oracle ADF Faces.

35.2.9 Configuring Databound Graphs for Drilling

You can configure a databound graph to display a detailed view of data displayed by an area, line, or marker.

Figure 35-18 shows a simple example of a bar graph that displays the total salaries of all employees in each department within the Summit organization. When the user moves the mouse over the department's ID, a tooltip appears to indicate that the ID is drillable. If the user clicks the department ID, the page changes to display the name and salary of each employee in the department.

Figure 35-18 Bar Graph Configured for Drilling

Bar Graph Configured for Drilling

35.2.9.1 How to Configure Databound Graphs for Drilling

To make a databound graph drillable, set the drillingEnabled attribute for the graph to true. The default value is false.

You must also update the graph's page definition file to define the drilling hierarchy and specify how you want the aggregated data displayed.

The graph in Figure 35-18 is bound to a data control in the Summit sample application for ADF DVT components that contains the department ID, last name, and salary for each employee. To make the graph drillable, the page definition file for the graph was modified to add the hierarchy details and to specify total salary for the aggregated value on the initial page.

Example 35-6 shows the binding in the page definition file before drilling configuration.

Example 35-6 Code Sample Showing Page Definition Before Drilling

<graph IterBinding="SEmpView1Iterator" id="SEmpView1"
       xmlns="http://xmlns.oracle.com/adfm/dvt"
       type="BAR_VERT_CLUST">
  <graphDataMap convert="false" leafOnly="true">
    <series>
      <data>
        <item value="Salary"/>
      </data>
    </series>
    <groups>
      <item value="DeptId"/>
    </groups>
  </graphDataMap>
</graph>

Example 35-7 shows the same page definition file configured for drilling support, with the additional entries to enable drilling support highlighted.

Example 35-7 Code Sample Showing Page Definition Configured for Drilling

<graph IterBinding="SEmpView1Iterator" id="SEmpView1"
           xmlns="http://xmlns.oracle.com/adfm/dvt"
           type="BAR_VERT_CLUST">
  <graphDataMap convert="false" leafOnly="true">
    <hierarchies>
      <item value="DeptId">
        <child value="LastName"/>
      </item>
    </hierarchies>
    <drills type="REPLACE"/>
    <series>
      <data aggregateDuplicates="true" defaultAggregateType="SUM">
        <item value="Salary"/>
      </data>
    </series>
    <groups>
      <item value="DeptId"/>
    </groups>
  </graphDataMap>
</graph>

Before you begin:

It may be helpful to have an understanding of databound graphs. For more information, see Section 35.2, "Creating Databound Graphs."

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Section 35.1.3, "Additional Functionality for Data Visualization Components."

You will need to complete these tasks:

  1. Create an application module that contains instances of the view objects that you want in your data model, as described in Section 13.2, "Creating and Modifying an Application Module."

  2. Create a JSF page as described in the "How to Create JSF Pages" section of Developing Web User Interfaces with Oracle ADF Faces.

  3. Create a databound graph as described in Section 35.2, "Creating Databound Graphs."

    The sample bar graph in Figure 35-18 uses a data control from the Summit ADF DVT sample application that contains information about each employee in an organization. Figure 35-19 shows the sample data control.

    Figure 35-19 Data Control for Drilled Bar Graph Example

    Data Control for Drilled Graph Example

To configure drilling support for a databound graph:

  1. In the Structure window, right-click the dvt:typeGraph node and choose Go to Page Definition.

  2. In the page definition's source view, add a hierarchies element to the graphDataMap and define the parent-child relationship for the drilling hierarchy.

    In Example 35-7, the DeptId item is the top level of the hierarchy and will be displayed when the graph is initially rendered. The child is defined as LastName and will be displayed when the user drills a department ID on the graph.

    To add an additional drill level, add another item to hierarchies. Use the value of the child from the first item as the new value for the second item, and add the additional value for the drill level as a child to the second item. Example 35-8 shows the hierarchies entry for a graph configured for two levels of drilling. In this example, the user can drill from yearly data to quarterly data and from quarterly data to monthly data.

    Example 35-8 Hierarchies in Page Definition File Showing Two Drill Levels

    <hierarchies>
  <item value="year">
    <child value="quarter"/>
  </item>
  <item value="quarter">
    <child value="month"/>
  </item>
</hierarchies>

  3. Add a drills element to the graphDataMap and set the type to REPLACE:

    <drills type="REPLACE"/>

    This type of drilling filters the rowset on the drilled target and replaces the target and its siblings with the target's children. This is the only drilling type supported for graph.

  4. Add the defaultAggregateType to data in graphDataMap.

    The defaultAggregateType determines how the data is aggregated when the graph is initially displayed. In Example 35-7, the defaultAggregateType is set to SUM, and the graph will display the total salary for all employees within the department.

    You can also set the defaultAggregateType to AVERAGE, COUNT, MAX, MEDIAN, MIN, NONE, STDDEV, or VARIANCE.

  5. If you want all duplicates to be aggregated, add aggregateDuplicates to data and set it to true as shown in Example 35-7.

  6. Save the modified page definition file.

  7. In the Structure window, right-click the dvt:<type>Graph component and choose Go to Properties.

  8. Expand the Behavior section, and select true from the DrillingEnabled attribute's dropdown menu.

35.3 Creating Databound Gauges

A gauge plots one data point with indication of whether the data point falls in an acceptable or unacceptable range. One databound gauge component can create a single gauge or an entire set of gauges, depending on the number of rows in the data collection used. In a collection, each row contains the values for a single gauge.

The Component Gallery for gauges allows you to choose from the following categories of gauges:

  • Dial: Indicates the metric value of a task along a configurable arc.

  • Status Meter: Indicates the progress of a task or the level of some measurement along a rectangular bar.

  • Status Meter (Vertical): Indicates the progress of a task or the level of some measurement along a rectangular bar.

  • LED: Depicts graphically a measurement such as a key performance indicator (KPI). Several styles of graphics are available for LED gauges such as arrows that indicate good (up arrow), fair (left- or right-pointing arrow), and poor (down arrow).

Each of these categories contains a number of different types of gauge. Explore the Component Gallery that appears when you create a single gauge to view all available gauge and category types, and descriptions for each one. Figure 35-20 shows the Component Gallery that appears for ADF gauges.

Figure 35-20 ADF Gauges Component Gallery

ADF Faces Gauges component gallery

The data binding process is essentially the same regardless of which type of gauge you create. Only the metric value (that is, the measurement that the gauge is to indicate) is required. However, if a row in a data collection contains range information such as maximum, minimum, and thresholds, then these values can be bound to the gauge to provide dynamic settings. If information that you want to use in a gauge's upper or lower labels is available in the data collection, then you can bind these values to the gauge also.

For information about customizing a gauge after the data binding is completed, see the "Using Gauge Components" chapter in Developing Web User Interfaces with Oracle ADF Faces.

35.3.1 How to Create a Databound Dial Gauge

You can use the ADF gauge component to create a dial gauge against a background that specifies ranges of values (also called thresholds) that vary from poor to excellent. The gauge indicator specifies the current value of the metric while the graphic allows you to evaluate the status of that value easily.

Figure 35-21 shows a single dial gauge that appears if you create a gauge from the AmountInStock data for inventory items in the Summit ADF DVT sample application. The value of the AmountInStock metric (which is 650) appears in a label below the gauge. The range of values in the gauge is displayed as 0 to 1500. Threshold ranges are defined at the values stored for the item's ReorderPoint (625) and MaxInStock (1100) attributes and are filled with the colors red for poor (below the reorder point), green for adequate (between the reorder point and maximum inventory level), and yellow for values above the item's maximum inventory level.

Figure 35-21 The Amount in Stock Dial Gauge

Amount in stock dial gauge

To create a dial gauge using a data control, you bind the gauge component to an attribute in a data collection. JDeveloper allows you to do this declaratively by dragging and dropping an attribute from the Data Controls panel. After you drag and drop the attribute, use the Create Dial Gauge dialog to configure the gauge.

Figure 35-22 shows the Create Dial Gauge dialog configured for the Amount in Stock dial gauge shown in Figure 35-21 and using the gauge type and quick start layout shown in Figure 35-20.

Figure 35-22 Create Gauge Dialog for Amount In Stock Dial Gauge

Create Gauge Binding Dialog

Before You Begin:

It may be helpful to have an understanding of databound data visualization gauges. For more information, see Section 35.3, "Creating Databound Gauges."

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Section 35.1.3, "Additional Functionality for Data Visualization Components."

You will need to complete these tasks:

To create a databound dial gauge:

  1. From the Data Controls panel, select an attribute from a collection.

    For example, to create a dial gauge in the Summit ADF DVT sample application to display the stock levels for an inventory item, you would select the AmountInStock attribute in the ProductInventoryView1 collection. Figure 35-23 shows the ProductInventoryView1 collection in the Data Controls panel with the AmountInStock attribute selected.

    Figure 35-23 Data Collection with Amount in Stock for an Inventory Item

    Data collection with warranty period for a product

  2. Drag the attribute onto a JSF page and, from the context menu, choose Gauges.

  3. In the Component Gallery, choose the category, type of gauge, and quick start layout, and then click OK.

  4. In the Create Dial Gauge dialog, click the Configuration tab and do the following:

    • In the Metric box, confirm the column in your data collection that contains the actual value that the gauge is to plot. This is the only required value in the dialog.

    • In the Minimum box, if your data collection stores a minimum value for the gauge range, select the column that contains this value. Alternatively, specify a minimum number for the range. If you do not specify a value, the minimum value is calculated automatically and defaults to 0.

    • In the Maximum box, if your data collection stores a maximum value for the gauge range, select the column that contains this value. Alternatively, specify a maximum number for the range. If you do not specify a value, the maximum value is calculated automatically and defaults to 100.

    • In the Show Top Label section, if your data collection stores a value that you want to display in the top label of the gauge, select the Show Top Label check box.

      Choose the label to display from the Label dropdown menu. Optionally, from the Position dropdown menu, choose Inside Gauge to position the label inside the gauge.

    • In the Show Bottom Label section, if your data collection stores a value that you want to display in the bottom label of the gauge, select the Show Bottom Label check box.

      Choose the label to display from the Label dropdown menu. Optionally, from the Position dropdown menu, choose Inside Gauge to position the label inside the gauge.

    • In the Show Metric Label box, if your data collection stores a metric value that you want to display in the metric label of the gauge, select the Show Metric Label check box.

      From the Show Metric Label dropdown list, choose Inside Gauge to position the label inside the gauge or Below Gauge to position the label below the gauge. To display the metric label with the bottom label, choose With Bottom Label and select Show Bottom Label in the Show Bottom Label section.

    • If you selected a quick start layout that includes thresholds, in the Threshold Attributes list, specify the value for threshold1 and threshold2. You can enter either a static value or choose an available attribute from the threshold's dropdown menu.

    Note:

    Gauge top, bottom, and threshold labels can also be configured to specify a text resource from a resource bundle using the Select Text Resource dialog, or use the EL Expression builder to evaluate the label text at runtime. Use the dropdown menu for the label field to open both dialogs.

  5. Optionally, click the Preview tab to display a live preview of the gauge and its data. If necessary, go back to the Configuration tab so that you can adjust the gauge specifications.

  6. Click OK.

In the Properties window, after you complete the binding of the gauge, you can set values for additional attributes in the gauge tag and its child tags to customize the component. For example, to configure the Amount In Stock gauge to show inventory amounts without scaling, set the scaling attribute of the metric and tick labels to none.

You can also examine and adjust the existing gauge bindings by clicking the Edit icon in the Properties window for the gauge component.

For additional information about customizing a gauge after the data binding is completed, see the "Using Gauge Components" chapter in Developing Web User Interfaces with Oracle ADF Faces.

35.3.2 What Happens When You Create a Dial Gauge from a Data Control

Dropping a gauge from the Data Controls panel has the following effect:

  • Creates the bindings for the gauge and adds the bindings to the page definition file

  • Adds the necessary code for the UI components to the JSF page

Example 35-9 shows the bindings that JDeveloper generated for the dial gauge that displays the inventory levels for a product in a warehouse. This code example shows that the gauge metric receives its value dynamically from the AmountInStock attribute in the ProductInventoryView1 data collection and its threshold values dynamically from the ReorderPoint and MaxInStock attributes in the same collection.

Example 35-9 Bindings for a Dial Gauge

<parameters/>
<executables>
  <variableIterator id="variables"/>
  <iterator Binds="ProductInventoryView1" RangeSize="1"
            DataControl="AppModuleDataControl"
            id="ProductInventoryView1Iterator"/>
</executables>
<bindings>
  <attributeValues IterBinding="ProductInventoryView1Iterator" id="AmountInStock">
    <AttrNames>
      <Item Value="AmountInStock"/>
    </AttrNames>
  </attributeValues>
  <attributeValues id="ReorderPoint" IterBinding="ProductInventoryView1Iterator">
    <AttrNames>
      <Item Value="ReorderPoint"/>
    </AttrNames>
  </attributeValues>
  <attributeValues id="MaxInStock" IterBinding="ProductInventoryView1Iterator">
    <AttrNames>
      <Item Value="MaxInStock"/>
    </AttrNames>
  </attributeValues>
  <attributeValues id="Name" IterBinding="ProductInventoryView1Iterator">
    <AttrNames>
      <Item Value="Name"/>
    </AttrNames>
  </attributeValues>
</bindings>

Example 35-10 shows the code that ­JDeveloper generated in the JSF page for a dial gauge. The <dvt:thresholdSet> element specifies one <dvt:threshold> element for each threshold.

Example 35-10 Code on the JSF Page for a Dial Gauge

<dvt:gauge id="gauge1" value="#{bindings.AmountInStock.inputValue}"
                       gaugeType="DIAL" minValue="0"
                       maxValue="1500" shortDesc="Amount In Stock Gauge">
  <dvt:gaugeBackground>
    <dvt:specialEffects/>
  </dvt:gaugeBackground>
  <dvt:thresholdSet>
    <dvt:threshold fillColor="#d62800"
         thresholdMaxValue="#{bindings.ReorderPoint.inputValue}"/>
    <dvt:threshold fillColor="#63a500"
         thresholdMaxValue="#{bindings.MaxInStock.inputValue}"/>
    <dvt:threshold fillColor="#e7e700"/>
  </dvt:thresholdSet>
  <dvt:gaugeFrame/>
  <dvt:indicator/>
  <dvt:indicatorBase/>
  <dvt:gaugePlotArea/>
  <dvt:tickLabel scaling="none"/>
  <dvt:tickMark/>
  <dvt:topLabel position="LP_ABOVE_GAUGE" text="#{bindings.Name.inputValue}"/>
  <dvt:bottomLabel position="LP_BELOW_GAUGE"
                   text="#{bindings.AmountInStock.hints.label}"/>
  <dvt:metricLabel position="LP_WITH_BOTTOM_LABEL" scaling="none">
    <af:convertNumber pattern="#{bindings.AmountInStock.format}"/>
  </dvt:metricLabel>
</dvt:gauge>

Note:

You can also bind a gauge to a collection instead of an attribute in the data collection. For example, you could drag the ProductInventoryView1 collection to create the dial gauge instead of dragging the AmountInStock attribute. This feature is still available for backwards compatibility and for configuring gauge sets, but its use is discouraged in favor of the simpler standard attribute binding.

35.3.3 How to Create a Databound Status Meter Gauge Set

You can use the ADF gauge component to create a status meter gauge where the inner rectangle shows the current level of a measurement against the ranges marked in the outer rectangle. The graphic of the status meter gauge allows you to evaluate the condition or progress of a measurement easily.

Figure 35-24 shows a set of status meter gauges that represent the inventory levels at each warehouse that carries the product. As the user cycles through the list of products using the navigation controls on the left side of the page, the gauge set changes to reflect the warehouses that carry the selected product and the inventory levels for each of those warehouses.

Figure 35-24 The Warehouse Inventory Status Meter Gauge Set

Wharehouse inventory status meter gauge set

This set of gauges results from binding one gauge component to a data collection (SInventoryView2). This data collection contains a row of data for each warehouse that carries the product. Each row produces one gauge in the set. The form on the left side of the page is an ADF form that is bound to the SProductView1 data collection.

Figure 35-25 shows the data control for the ADF form and gauge set displayed in Figure 35-24. Note the hierarchical relationship between the SProductView1 and SInventoryView2 data collections. Because of this relationship, the gauge set data updates automatically as the user cycles through the form's navigation controls.

Figure 35-25 Data Collection for the Warehouse Inventory Status Meter Gauge Set

Warehouse Inventory Gauge Set Data Control

To create a status meter gauge set using a data control, you bind the gauge component to a data collection that contains multiple rows of data. JDeveloper allows you to do this declaratively by dragging and dropping a collection from the Data Controls panel.

Before you begin:

It may be helpful to have an understanding of databound data visualization gauges. For more information, see Section 35.3, "Creating Databound Gauges."

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Section 35.1.3, "Additional Functionality for Data Visualization Components."

You will need to complete these tasks:

To create a databound status meter gauge set:

  1. From the Data Controls panel, select a collection.

    For example, to create a status meter gauge set in the Summit ADF DVT sample application that displays the quantity of stock on hand in all warehouses that carry the given product, select the SInventoryView2 collection.

  2. Drag the collection onto a JSF page and, from the context menu, choose Gauges.

  3. In the Component Gallery, choose the following:

    • Status Meter or Status Meter (Vertical) in the Categories list

    • The type of gauge that you want to create

      To specify a gauge set, choose the gauge type that includes a gauge set. Figure 35-27 shows the Component Gallery with the horizontal status meter gauge set selected.

      Figure 35-27 Component Gallery for a Horizontal Status Meter Gauge Set

      Component Gallery For Horizontal Status Meter Gauge Set

    • The quick start layout for the gauge at runtime

  4. Click OK.

  5. In the Create Gauge dialog that appears, select values as described in the following list:

    • Select an attribute binding from the Metric dropdown list. This attribute binding contains the actual value that the gauge is to plot.

      For example, to duplicate the Summit ADF DVT gauge set example, select the AmountInStock attribute.

    • Input a minimum value in the Minimum field if your data collection stores a minimum value for the gauge range.

    • Input a maximum value in the Maximum field if your data collection stores a maximum value for the gauge range.

    • In the Show Top Label section, if your data collection stores a value that you want to display in the top label of the gauge, select the Show Top Label check box.

      Choose the label to display from the Label dropdown menu. Optionally, from the Position dropdown menu, choose Inside Gauge to position the label inside the gauge.

    • In the Show Bottom Label section, if your data collection stores a value that you want to display in the bottom label of the gauge, select the Show Bottom Label check box.

      Choose the label to display from the Label dropdown menu. Optionally, from the Position dropdown menu, choose Inside Gauge to position the label inside the gauge.

    • In the Show Metric Label box, if your data collection stores a value that you want to display in the metric label of the gauge, select the Show Metric Label check box.

      From the Show Metric Label dropdown list, choose Inside Gauge to position the label inside the gauge or Below Gauge to position the label below the gauge. To display the metric label with the bottom label, choose With Bottom Label and select Show Bottom Label in the Show Bottom Label section.

    • If you chose a quick-start layout that includes thresholds, enter values for threshold1 and threshold2. Do not enter a value for the threshold equal to the maximum value for the gauge because the gauge automatically treats the maximum value as a threshold setting.

    Note:

    Gauge Top, Bottom, and Threshold labels can be configured to specify a text resource from a resource bundle using the Select Text Resource dialog, or use the EL Expression builder to evaluate the label text at runtime. Use the dropdown menu for the label field to open both dialogs.

  6. Optionally, click the Preview tab to display a live preview of the gauge and its data. If necessary, click the Configuration tab so that you can adjust the gauge specifications.

    Figure 35-28 shows the settings for the set of status meter gauges that appears in Figure 35-24. In addition to setting values for the required metric value, this dialog sets values for thresholds based on the ReorderPoint and MaxInStock attributes of the data collection and specifies the placement, data source, and visibility of top, bottom, and metric labels.

    Figure 35-28 Create Gauge Dialog for Warehouse Inventory Gauge Set

    Create gauge dialog for wharehouse inventory gauge set

  7. Click OK.

In the Properties window, after you complete the binding of the gauge, you can set values for additional attributes in the gauge tag and its child tags to customize the component as needed.

For additional information about customizing a gauge after the data binding is completed, see "Using Gauge Components" in Developing Web User Interfaces with Oracle ADF Faces.

35.3.4 What Happens When You Create a Status Meter Gauge Set from a Data Control

Dropping a gauge set from the Data Controls panel has the following effect:

  • Creates the bindings for the gauge set and adds the bindings to the page definition file

  • Adds the necessary code for the UI components to the JSF page

Example 35-11 shows the row set bindings that were generated for the status meter gauge set that displays inventory levels for each warehouse as illustrated in Figure 35-24. This example shows the value binding created between the gauge metric attribute and the QuantityOnHand value in the data collection. It also shows the value binding between the Bottom Label attribute and the WarehouseName value in the data collection.

Example 35-11 Bindings Code for the ADF Status Meter Gauge Set

<gauge IterBinding="SInventoryView2Iterator" id="SInventoryView2"
       xmlns="http://xmlns.oracle.com/adfm/dvt"
       type="STATUSMETER">
  <gaugeDataMap convert="false">
    <item type="metric" value="AmountInStock"/>
    <item type="topLabel" value="WarehouseId"/>
    <item type="bottomLabel" value="Name"/>
    <thresholds>
      <item value="ReorderPoint"/>
      <item value="MaxInStock"/>
    </thresholds>
  </gaugeDataMap>
</gauge>

Example 35-12 shows the code generated on the JSF page for the status meter gauge set that shows inventory levels at warehouses for a given product. The gaugeSetColumnCount attribute specifies that gauges should be displayed in two columns.

Example 35-12 Code on the JSF Page for the ADF Status Meter Gauge Set

<dvt:gauge id="gauge1" value="#{bindings.SInventoryView2.gaugeModel}"
           gaugeType="STATUSMETER" gaugeSetDirection="GSD_ACROSS"
           gaugeSetColumnCount="2" shortDesc="Sample Gauge Set"
           inlineStyle="width:500px; height:500px;" gaugeSetAlignment="GSA_TOP">
  <dvt:gaugeBackground>
    <dvt:specialEffects/>
  </dvt:gaugeBackground>
  <dvt:thresholdSet>
    <dvt:threshold fillColor="#d62800" text="Reorder Time"/>
    <dvt:threshold fillColor="#63a500" text="Levels OK"/>
    <dvt:threshold fillColor="#e7e700" text="Over Stock"/>
  </dvt:thresholdSet>
  <dvt:indicatorBar/>
  <dvt:gaugePlotArea/>
  <dvt:tickLabel scaling="none"/>
  <dvt:tickMark/>
  <dvt:topLabel position="LP_ABOVE_GAUGE"/>
  <dvt:bottomLabel position="LP_BELOW_GAUGE"/>
  <dvt:gaugeLegendTitle text="Legend"/>
  <dvt:gaugeLegendArea position="LAP_RIGHT"/>
  <dvt:metricLabel position="LP_WITH_BOTTOM_LABEL" scaling="none"/>
</dvt:gauge>

35.3.5 Including Gauges in Databound ADF Tables

You can add databound dial, LED, or status meter gauges to a databound ADF table by choosing the gauge component when specifying column content during table editing or creation.

Figure 35-29 shows a portion of a table that displays all the products in a warehouse in the Summit ADF DVT sample application. In this example, the AmountInStock column includes a status meter gauge that shows the amount in stock for each product.

Figure 35-29 Gauge in Databound ADF Table

Gauge in Databound ADF Table

35.3.5.1 How to Include a Gauge in a Databound ADF Table

To add a gauge to a databound ADF table, drag a data collection that includes the gauge metric from the Data Controls panel to the JSF page and specify the type of gauge to create.

Before you begin:

It may be helpful to have an understanding of databound data visualization gauges. For more information, see Section 35.3, "Creating Databound Gauges."

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Section 35.1.3, "Additional Functionality for Data Visualization Components."

You will need to complete these tasks:

To include a gauge in a databound ADF table:

  1. From the Data Controls panel, select the collection to use for the ADF table.

    For example, to create the table that displays the inventory levels for each product in a warehouse in the Summit ADF DVT sample application, select the ProductInventoryView1 collection. Figure 35-30 shows the ProductInventoryView1 collection in the Data Controls panel.

    Figure 35-30 ProductInventoryView1 Data Collection

    ProductInventoryView1 Data Collection

  2. Drag the collection onto a JSF page and, from the context menu, choose Table -> ADF Table.

  3. In the Edit Table Columns dialog, select the column that represents the gauge metric.

    For example, select the AmountInStock column to use as the gauge metric.

  4. From the Component to Use dropdown menu, choose the type of gauge to create.

    For example, choose Gauge Status Meter to add a status meter to the table.

  5. Complete the table configuration.

    If you need help, press F1 or click Help.

    Figure 35-31 shows the completed dialog for the table displayed in Figure 35-29, with the Gauge Status Meter selected for the AmountInStock column.

    Figure 35-31 Edit Table Columns Dialog Showing Status Meter Gauge

    Gauge in Table Dialog

  6. Click OK to add the table to the JSF page.

In the Properties window, after you complete the binding of the table, you can set values for additional attributes in the gauge tag and its child tags to customize the component. For example, to configure the gauge to show inventory amounts without scaling, set the scaling attribute of the metric label to none.

You can also examine and adjust the existing table bindings by clicking the Edit icon in the Properties window for the table component.

For additional information about customizing a gauge after the data binding is completed, see the "Using Gauge Components" chapter in Developing Web User Interfaces with Oracle ADF Faces.

For additional information about creating and configuring databound ADF tables, see Chapter 29, "Creating ADF Databound Tables."

35.3.5.2 What Happens When You Include a Gauge in an ADF Table

When you include a gauge in a databound ADF table, the gauge's metric attribute is added to the page definition file, and the UI components are updated on the JSF page.

Example 35-13 shows the binding for the ADF table shown in Figure 35-29.

Example 35-13 Binding for Status Meter Gauge in ADF Table

<parameters/>
<executables>
  <variableIterator id="variables"/>
  <iterator Binds="ProductInventoryView2" RangeSize="25"
            DataControl="AppModuleDataControl"
            id="ProductInventoryView2Iterator"/>
  <searchRegion Binds="ProductInventoryView2Iterator" Criteria=""
                Customizer="oracle.jbo.uicli.binding.JUSearchBindingCustomizer"
                id="ProductInventoryView2Query"/>
</executables>
<bindings>
  <tree IterBinding="ProductInventoryView2Iterator" id="ProductInventoryView2">
    <nodeDefinition DefName="model.ProductInventoryView"
                    Name="ProductInventoryView20">
      <AttrNames>
        <Item Value="Name"/>
        <Item Value="AmountInStock"/>
        <Item Value="MaxInStock"/>
        <Item Value="OutOfStockExplanation"/>
        <Item Value="ProductId"/>
        <Item Value="ReorderPoint"/>
        <Item Value="RestockDate"/>
        <Item Value="WarehouseId"/>
        <Item Value="Id"/>
        <Item Value="ShortDesc"/>
      </AttrNames>
    </nodeDefinition>
  </tree>
</bindings>

Example 35-14 shows the code added to the JSF page for the ADF table. The gauge elements are highlighted in bold. For the sake of brevity, only the first three table columns are displayed.

Example 35-14 Sample Code on JSF Page Showing Gauge in Databound Table

<af:table value="#{bindings.ProductInventoryView2.collectionModel}" var="row"
          rows="#{bindings.ProductInventoryView2.rangeSize}"
          emptyText="#{bindings.ProductInventoryView2.viewable ? 
                    'No data to display.' : 'Access Denied.'}"
          fetchSize="#{bindings.ProductInventoryView2.rangeSize}"
          rowBandingInterval="0"
          filterModel="#{bindings.ProductInventoryView2Query.queryDescriptor}"
          queryListener="#{bindings.ProductInventoryView2Query.processQuery}"
          filterVisible="true" varStatus="vs"
          selectionListener="#{bindings.ProductInventoryView2.collectionModel.makeCurrent}"
          rowSelection="multiple" id="t1">
  <af:column sortProperty="#{bindings.ProductInventoryView2.hints.ProductId.name}"
             filterable="true" sortable="true"
             headerText="#{bindings.ProductInventoryView2.hints.ProductId.label}"
             id="c5" width="57">
    <af:outputText value="#{row.ProductId}"
             shortDesc="#{bindings.ProductInventoryView2.hints.ProductId.tooltip}"
             id="ot4">
      <af:convertNumber groupingUsed="false"
              pattern="#{bindings.ProductInventoryView2.hints.ProductId.format}"/>
    </af:outputText>
  </af:column>
  <af:column sortProperty="#{bindings.ProductInventoryView2.hints.Name.name}"
             filterable="true" sortable="true"
             headerText="#{bindings.ProductInventoryView2.hints.Name.label}"
             id="c1" width="143">
    <af:outputText value="#{row.Name}"
       shortDesc="#{bindings.ProductInventoryView2.hints.Name.tooltip}" id="ot1"/>
  </af:column>
  <af:column sortProperty="#{bindings.ProductInventoryView2.hints.ShortDesc.name}"
             filterable="true" sortable="true"
             headerText="#{bindings.ProductInventoryView2.hints.ShortDesc.label}"
             id="c10" width="100">
    <af:outputText value="#{row.ShortDesc}"
             shortDesc="#{bindings.ProductInventoryView2.hints.ShortDesc.tooltip}"
                   id="ot9"/>
  </af:column>
  <af:column sortProperty="#{bindings.ProductInventoryView2.hints.AmountInStock.name}"
             filterable="true" sortable="true"
             headerText="#{bindings.ProductInventoryView2.hints.AmountInStock.label}"
             id="c2" width="138">
    <dvt:gauge value="#{row.bindings.AmountInStock.inputValue}"
               gaugeType="STATUSMETER"
               inlineStyle="height:60px; width:80px;"
               shortDesc="#{bindings.ProductInventoryView2.hints.AmountInStock.tooltip}"
               id="g1" ledStyle="LS_RECTANGLE">
      <dvt:topLabel position="LP_NONE"/>
      <dvt:metricLabel position="LP_INSIDE_GAUGE" scaling="none">
        <af:convertNumber pattern="#{row.bindings.AmountInStock.format}"/>
      </dvt:metricLabel>
      <dvt:bottomLabel position="LP_NONE"/>
    </dvt:gauge>
  </af:column>
... remaining columns omitted
</af:table>