Oracle ADF Data Visualizations Gauge

An Oracle JDeveloper How To Document
Written by Katarina Obradovic-Sarkic, Oracle Corporation
December, 2007

Introduction to ADF Data Visualization Components

ADF Data Visualization components (ADF DVT) are a set of rich interactive ADF Faces components that provide significant graphical and tabular capabilities for visualizating and analyzing data. Data Visualization components provide the following common features:

  • Design time creation using data control palette, JSF visual editor, property inspector and component palette
  • Support for data binding to standard rowset as well hierarchical data controls

Getting Started

This document is intended for users who want to learn more advanced topics related to the DVT components. The following steps are recommended to get started with creating and using Data Visualization components:

ADF Data Visualizations Gauge

Gauge is a DVT component that plots one data point with indication of whether the data point falls in an acceptable or unacceptable range. One databound ADF 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.

Supported Gauge types are:

  • Dial: Standard and Threshold
  • Status Meter: Standard and Threshold
  • Vertical Status Meter: Standard and Threshold ( New in Technology Preview 3)
  • LED
Dial Gauge

Status Meter Gauge

Vertical Status Meter Gauge LED Gauge
Dial Gauge
Status Meter
Vertical Status Meter Gauge
LED Gauge

This document provides guidance and examples for using ADF DVT Gauge in common application scenarios. The following sections explain how to:

  • Use a Gauge to display data in an ADF Table column
  • Create thresholds for a Gauge
  • Format Gauge metric label and tick label

1. Using a Gauge to Display Data in an ADF Table Column

In this scenario we will create a Gauge that is displayed in a column of an ADF Table and displays the appropriate value for each cell in that column.

Preparation Steps

1. Create a new Application using a "Fusion Web Application" template.

2. In the Model project, create a connection to the Fusion Order Demo schema. For details on downloading and installing the Fusion Order Demo schema, follow the Data Visualization Components tutorial on OTN.

3. Create an ADF Business Components read-only View object named "WarehouseStockLevels". This View object will give us the name, address and stock quantity information for the different warehouses that store a selected product. Use the following SQL query:

   Warehouses, Addresses,
   Warehouse_Stock_Levels WarehouseStockLevels
   Warehouses.warehouse_id = WarehouseStockLevels.warehouse_id and 
   Addresses.address_id = Warehouses.address_id and 
   WarehouseStockLevels.Product_Id = :product
   order by WarehouseStockLevels.Quantity_On_Hand asc

4. Create a bind variable named "product" of type Number and default value "1". This View object will give us the name, address and stock quantity information for the different warehouses that store a selected product.

5. When creating the View object, make sure to add it to the Application Module so that the corresponding Data Control will appear in the Data Control palette.

6. In the ViewController project, create a new JSF jspx page.

7. From the Data Control palette drag the data control "WarehouseStockLevels1" into the page and choose to render it as an ADF Table.

Create ADF table

8. In the "Edit Table Columns" dialog, move the column "QuantityOnHand" to be last and delete fields ProductId, WarehouseId, and CountryId, which are not needed.

9. Change the names of the columns to be more readable, as shown in the image below.

Edit table Columns

Displaying Table Column Data with a Gauge

1. To display a gauge in the cells of a table column, simply drag a Gauge tag from the Component Palette ADF Data Visualization page, into the "Quantity" column of the ADF Table, as shown in the image below.

Gauge stamping in visual editor

By default,a Dial gauge is created as a child of the af:column tag.

2. In the visual editor, select and delete the af:inputText field "QuantityOnHand" so that the entire space of a cell is devoted to the Gauge.

3. Select the af:column tag that contains the gauge and in the Property Inspector, under "Appearance", set its width property to 200.

4. Select the dvt:gauge tag and in the Property Inspector, under "Common", change the gauge type to STATUSMETER.

5. By default, the Gauge size is 200 by 200. To reduce its size, on the "Appearance" tab under "Image", set the imageHeight property to 50 and the imageWidth property to 200.

6. On the "Gauge Data" tab, set the MinValue to 0 and MaxValue to 2000.

7. Click on a little arrow next to the "Value" field and choose "Expression Builder".

Bind Gauge Value

8. In the Expression Builder dialog, in the Variables section expand the JSP Objects node, and then expand the row node. Select "QuantityOnHand" and click on the button "Insert Into Expression". This binds the gauge value to the QuantityOnHand attribute for each row of the table.

Gauge Stamp Binding


2. Specifying Thresholds for a Gauge

By default, the gauge does not display any thresholds. To create gauge thresholds, perform the following steps, which are the same regardless of the gauge type:

1. On the Component Palette under ADF Data Visualization -> Gauge, find the tag ThresholdSet. Drag the tag onto the dvt:gauge tag in the visual editor or the Structure Pane.

Component Palette Thresholds

2. Drag three Threshold tags inside the ThresholdSet tag.

3. Select the first dvt:threshold tag, and using the Property Inspector set the following properties:

  • Advanced tab: id ="t0"
  • Common tab: ThresholdMaxValue="300"

4. Select the second dvt:threshold tag, and using the Property Inspector set the following properties:

  • Advanced tab: id ="t1"
  • Common tab: ThresholdMaxValue="700"

5. Select the third dvt:threshold tag, and using the Property Inspector set the following properties:

  • Advanced tab: id ="t2"
  • The last threshold does not need to have a max value because it will simply use the max value for the entire gauge.

Run the page. The gauge appears as a set of status meters in the Quantity column of the table, displaying the specified thresholds and the Quantity values for each warehouse.

3. Formatting Metric and Tick Labels for a Gauge

Note that the metric and tick labels are by default displaying their values as "0.2K". Also, the metric label is displayed below the gauge which takes unnecessary vertical space.

To format the metric and tick labels, perform the following steps:

1. On the Component Palette under ADF Data Visualization -> Gauge select MetricLabel and TickLabels tags and drag them onto the dvt:gauge tag using the JSF Visual Editor or the Structure Pane.

2. Select the tag dvt:metricLabel and using the Property Inspector set the attribute position="LP_INSIDE_GAUGE_RIGHT". This will position to metric label (Quantity for each row) on the inside right side of the gauge.

3. On the Component Palette under ADF Data Visualization -> Shared Child Tags select the NumberFormat tag and drag it onto the dvt:metricLabel tag. Drag another dvt:numberFormat tag onto the dvt:tickLabel tag. The number Format tag is used to format the numbers displayed by the DVT components.

4. Select each of the dvt:numberFormat tags, and using the PropertyInspector in the Scale selection set the following attribute scaleFactor="SCALEFACTOR_NONE". This will ensure that the numbers are displayed as e.g."200" instead of "0.2K".

The final gauge code should look like this inside the af:column tag:

 <af:column sortProperty="QuantityOnHand" sortable="false"
                                headerText="Quantity on Hand" width="200">
        <dvt:gauge gaugeType="STATUSMETER"
                imageWidth="200" imageHeight="50" maxValue="2000.0"
                        <dvt:threshold id="t0" thresholdMaxValue="300.0"/>
                        <dvt:threshold id="t1" thresholdMaxValue="700.0"/>
                        <dvt:threshold id="t2"/>
                        <dvt:numberFormat scaleFactor="SCALEFACTOR_NONE"/>
                <dvt:metricLabel position="LP_INSIDE_GAUGE_RIGHT">
                        <dvt:numberFormat scaleFactor="SCALEFACTOR_NONE"/>

Run the completed page. The table and the gauges should look as follows:

Gauge Stamping Completed

Where to Get More Information

For more information on using the Data Visualization components consult the chapter "Creating Databound Graphs, Gauges, Pivot Tables, Maps, and Gantt Charts" in the Fusion Developer's Guide for Oracle ADF and the chapter "Using Data Visualization Components" in the ADF Faces Component Guide, as well as other resources listed in the "Getting Started" section of this document.


false ,,,,,,,,,,,,,,,