24-50 Web User Interface Developers Guide for Oracle Application Development Framework
– all default: Show all data change indicators.
■
animationUpColor: Use to specify the RGB hexadecimal color used to indicate that a data value has increased.
■
animationDownColor: Use to specify the RGB hexadecimal color used to indicate that a data value has decreased.
25
Using ADF Gauge Components 25-1
25
Using ADF Gauge Components
This chapter describes how to use a databound ADF gauge component to display data, and provides the options for gauge customization.
This chapter includes the following sections:
■
Section 25.1, Introduction to the Gauge Component
■
Section 25.2, Understanding Data Requirements for Gauges
■
Section 25.3, Creating a Gauge
■
Section 25.4, Customizing Gauge Type, Layout, and Appearance
■
Section 25.5, Adding Gauge Special Effects and Animation
■
Section 25.6, Using Custom Shapes in Gauges For information about the data binding of gauges, see the Creating Databound ADF
Gauges section in the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development Framework.
25.1 Introduction to the Gauge Component
Gauges identify problems in data. A gauge usually plots one data point with an indication of whether that point falls in an acceptable or an unacceptable range.
Frequently, you display multiple gauges in a single gauge set. The gauges in a set usually appear in a grid-like format with a configurable layout.
A Component Gallery displays available gauge categories, types, and descriptions to provide visual assistance when creating gauges and using a quick-start layout.
Figure 25–1 shows the Component Gallery for gauges.
25-2 Web User Interface Developers Guide for Oracle Application Development Framework
Figure 25–1 Component Gallery for Gauges
When a gauge component is inserted into a JSF page using the Component Gallery, a set of child tags that support customization of the gauge is automatically inserted.
Example 25–1 shows the code inserted in the JSF page for a dial gauge with the
quick-start layout selected in the Component Gallery in Figure 25–1
.
Example 25–1 Gauge Sample Code
dvt:gauge id=gauge2 value={bindings.Gaugedemo1View1.gaugeModel} gaugeType=DIAL imageFormat=FLASH
dvt:gaugeBackground dvt:specialEffects fillType=FT_GRADIENT
dvt:gradientStopStyle dvt:specialEffects
dvt:gaugeBackground dvt:gaugeFrame
dvt:indicator dvt:indicatorBase
dvt:gaugePlotArea dvt:tickLabel
dvt:tickMark dvt:topLabel
dvt:bottomLabel dvt:metricLabel position=LP_WITH_BOTTOM_LABEL
dvt:thresholdSet dvt:threshold fillColor=d62800
dvt:threshold fillColor=00ff00 dvt:thresholdSet
dvt:gauge
Using ADF Gauge Components 25-3
Gauges are displayed in a default size of 200 X 200 pixels. You can customize the size of a gauge or specify dynamic resizing to fit an area across different browser window
sizes. When gauges are displayed in a horizontally or vertically restricted area, for example in a web page sidebar, the gauge is displayed in a small image size. Although
fully featured, the smaller image is a simplified display.
By default, gauges are displayed using a Flash player as specified in the gauge component imageFormat attribute. Alternatively, gauges can be displayed using a
Portable Network Graphics PNG output format, as in the case when plug-ins are not allowed on client machines, or in bidirectional locales. Although static rendering is
fully supported when using a PNG output format, certain interactive features are not available including:
■
Animation
■
Context menus
■
Drag and drop gestures
■
Interactive pie slice behavior
■
Reference object hover behavior
■
Popup support
■
Selection
■
Series rollover behavior
■
Time selector
■
Zoom and scroll live client-side scrolling
25.1.1 Types of Gauges
The following types of gauges are supported by the gauge component:
■
Dial: Indicates its metric along a 220 degree arc. This is the default gauge type. Figure 25–2
shows a dial gauge indicating a Plasma HD TV stock level within an acceptable range.
Figure 25–2 Dial Gauge with Thresholds
■
Status Meter: Indicates the progress of a task or the level of some measurement along a rectangular bar. An inner rectangle shows the current level of a
measurement against the ranges marked on an outer rectangle. Figure 25–3
shows the Plasma HD TV stock level using a status meter gauge.
25-4 Web User Interface Developers Guide for Oracle Application Development Framework
Figure 25–3 Status Meter Gauge with Thresholds
■
Status Meter vertical: Indicates the progress of a task or the level of some measurement along a vertical rectangular bar.
Figure 25–4 shows the Plasma HD
TV stock level using a vertical status meter gauge.
Figure 25–4 Vertical Status Meter Gauge with Thresholds
■
LED light-emitting diode: Graphically depicts 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, or poor down arrow.
Figure 25–5 shows the Plasma HD TV stock level
using a LED bulb indicator.
Figure 25–5 LED Bulb Gauge
Figure 25–6 shows the same stock level using a LED arrow.
Using ADF Gauge Components 25-5
Figure 25–6 LED Arrow Gauge
For dial and status meter gauges, a tooltip of contextual information automatically displays when a users moves a mouse over the plot area, indicator, or threshold
region. Figure 25–7
shows the indicator tooltip for a dial gauge.
Figure 25–7 Indicator Tooltip for Dial Gauge
25.1.2 Gauge Terminology
Gauge terms identify the many aspects of a gauge and gauge set that you can customize. The gauge component includes approximately 20 child tags that provide
options for this customization.
The parts of a gauge that can be customized are:
■
Overall gauge customization: Each item in this group is represented by a gauge child tag:
– Gauge Background: Controls border color and fill color for the background of
a gauge.
– Gauge Set Background: Controls border color and fill color for the background
of a gauge set.
– Gauge Frame: Refers to the frame behind the dial gauge.
– Plot Area: Represents the area inside the gauge itself.
– Indicator: Points to the value that is plotted in a dial gauge. It is typically in
the form of a line or an arrow.
– Indicator Bar: The inner rectangle in a status meter gauge.
– Indicator Base: The circular base of a line or needle style indicator in a dial
gauge.
– Threshold Set: Specifies the threshold sections for the metrics of a gauge. You
can create an infinite number of thresholds for a gauge.
■
Data values: These include the metric which is the actual value that the gauge is plotting, minimum value, maximum value, and threshold values.
Section 25.2, Understanding Data Requirements for Gauges
describes these values.
25-6 Web User Interface Developers Guide for Oracle Application Development Framework
■
Labels: The gauge supports the following elements with a separate child tag for each item:
– Bottom Label: Refers to an optional label that appears below or inside the
gauge. By default displays the label for the data row.
– Lower Label Frame: Controls the colors for the background and border of the
frame that contains the bottom label. The metric label can also appear inside the lower label frame, to the right of the bottom label.
– Metric Label: Shows the value of the metric that the gauge is plotting in text.
– Tick Marks: Refers to the markings along the value axis of the gauge. These
can identify regular intervals, from minimum value to maximum value, and can also indicate threshold values. Tick marks can specify major increments
that may include labels or minor increments.
– Tick Labels: Displays text that is displayed to identify major tick marks on a
gauge.
– Top Label: Refers to the label that appears at the top or inside of a gauge. By
default, a title separator is used with a label above the gauge. By default, displays the label for the data column.
– Upper Label Frame: Refers to the background and border of the frame that
encloses the top label. You can specify border color and fill color for this frame. Turn off the default title separator when using this frame.
■
Legend: The gauge supports the gauge legend area, text, and title elements with a separate child tag for each item.
■
Shape Attributes Set: The gauge supports interactivity properties for its child elements. For example, the alt text of a gauge plot area can be displayed as a
tooltip when the user moves the mouse over that area at runtime. For more information, see
Section 25.5.3, How to Add Interactivity to Gauges.
25.2 Understanding Data Requirements for Gauges
You can provide the following kinds of data values for a gauge:
■
Metric: The value that the gauge is to plot. This value can be specified as static data in the Gauge Data attributes category in the Property Inspector. It can also be
specified through data controls or through the tabularData attribute of the dvt:gauge tag. This is the only required data for a gauge. The number of metric
values supplied affects whether a single gauge is displayed or a series of gauges are displayed in a gauge set.
■
Minimum and maximum: Optional values that identify the lowest and highest points on the gauge value axis. These values can be provided as dynamic data
from a data collection. They can also be specified as static data in the Gauge Data attributes category in the Property Inspector for the dvt:gauge tag. For more
information, see
Section 25.4.4, How to Add Thresholds to Gauges.
■
Threshold: Optional values that can be provided as dynamic data from a data collection to identify ranges of acceptability on the value axis of the gauge. You
can also specify these values as static data using gauge threshold tags in the Property Inspector. For more information, see
Section 25.4.4, How to Add Thresholds to Gauges.
The only required data element is the metric value. All other data values are optional.
Using ADF Gauge Components 25-7
25.3 Creating a Gauge
You can use any of the following ways to supply data to a gauge component:
■
ADF Data Controls: You declaratively create a databound gauge by dragging and dropping a data collection from the ADF Data Controls panel.
Figure 25–8 shows
the Create Gauge dialog where you configure the metric value, and optionally the minimum and maximum and threshold values for a gauge you are creating.
Figure 25–8 Create Gauge Dialog
For more information, see the “Creating Databound ADF Gauges section in the Oracle Fusion Middleware Fusion Developers Guide for Oracle Application Development
Framework.
■
Tabular data: You can provide CSV comma-separated value data to a gauge through the tabularData attribute of the dvt:gauge tag.
25.3.1 Creating a Gauge Using Tabular Data
The process of creating a gauge from tabular data includes the following steps:
■
Storing the data in a method in the gauge’s managed bean.
■
Creating a gauge that uses the data stored in the managed bean.
25.3.1.1 Storing Tabular Data for a Gauge in a Managed Bean
The tabularData attribute of a gauge component lets you specify a list of metric values that the gauge uses to create a grid and to populate itself. You can provide only
the metric value through the tabularData attribute. Therefore, you must specify any desired thresholds and minimum or maximum values through the Property Inspector.
A gauge component displays rows and columns of gauges. The text that you specify as column labels appears in the top label of the gauges. The text that you specify as row
labels appears in the bottom label of the gauges.
25-8 Web User Interface Developers Guide for Oracle Application Development Framework
25.3.1.2 Structure of the List of Tabular Data
The list that contains the tabular data consists of a three-member Object array for each data value to be passed to the gauge. The members of each array must be
organized as follows:
■
The first member index 0 is the column label, in the grid, of the data value. This is generally a String.
■
The second member index 1 is the row label, in the grid, of the data value. This is generally a String.
■
The third member index 2 is the data value, which is usually Double. Figure 25–9
has five columns: Quota, Sales, Margin, Costs, and Units. The example has three rows: London, Paris, and New York. This data produces a gauge set with five
gauges in each row and lets you compare values such as sales across the three cities.
Figure 25–9 Comparison of Annual Results
Example 25–2 shows code that creates the list of tabular data required for the gauge
that compares annual results for three cities.
Example 25–2 Code to Create a List of Tabular Data for a Gauge
public List getGaugeData {
ArrayList list = new ArrayList; String[] rowLabels = new String[] {London, Paris, New York};
String[] colLabels = new String[] {Quota, Sales, Margin, Costs, Units};
double [] [] values = new double[][]{ {60, 90, 135},
{50, -100, -150}, {130, 140, 150},
{70, 80, -130}, {110, 120, 130}
}; for int c = 0; c colLabels.length; c++
{ for int r = 0; r rowLabels.length; r++
{ list.add new Object [] {colLabels[c], rowLabels[r],
new Double values [c][r]}; }
} return list;
}
25.3.2 How to Create a Gauge Using Tabular Data
Use the tabularData attribute of the gauge tag to reference the tabular data that is stored in a managed bean.
Using ADF Gauge Components 25-9
To create a gauge that uses tabular data from a managed bean: 1.
In the ADF Data Visualizations page of the Component Palette, Gauge panel, drag and drop a Gauge onto the page.
2.
In the Component Gallery, select the category, type, and quick-start layout style for the gauge that you are creating.
3. In the Gauge Data category of the Property Inspector, from the tabularData
attribute dropdown menu, choose Expression Builder. 4.
In the Expression Builder dialog, use the search box to locate the managed bean.
5.
Expand the managed bean node and select the method that creates the list of tabular data.
6. Click OK.
The Expression is created. For example, if the name of the managed bean is sampleGauge and the name of
the method that creates the list of tabular data is getGaugeData, the Expression Builder generates the code {sampleGauge.gaugeData} as the value for the
tabularData attribute of the dvt:gauge tag.
25.3.3 What Happens When You Create a Gauge Using Tabular Data
When you create a gauge tag that is powered by data obtained from a list referenced in the tabularData attribute, the following results occur:
■
A gauge is generated with a setting in its tabularData attribute. The settings for all other attributes for this gauge are provided by default.
■
You have the option of changing the setting of the gaugeType attribute in the Property Inspector to DIAL, LED, STATUSMETER, or VERTICALSTATUSMETER.
25.4 Customizing Gauge Type, Layout, and Appearance
Gauge components can be customized in the following ways:
■
Change the gauge type
■
Specify the layout of gauges in a gauge set
■
Change a gauge size and style
■
Add thresholds
■
Format numbers and text
■
Specify an N-degree dial gauge
■
Customize gauge labels
■
Customize indicators and tick marks
■
Specifying transparency in gauges
25.4.1 How to Change the Type of the Gauge
You can change the type of a gauge using the gaugeType attribute of the dvt:gauge tag. The gauge type is reflected in the visual editor default gauge.
25-10 Web User Interface Developers Guide for Oracle Application Development Framework
To change the type of a gauge: 1.
In the Structure window, right-click the dvt:gauge node and choose Go to Properties
.
2. In the Property Inspector, choose a gauge type from the GaugeType attribute
dropdown list. Valid values are DIAL, LED, STATUSMETER, or VERTICALSTATUSMETER.
25.4.2 How to Determine the Layout of Gauges in a Gauge Set
A single gauge can display one row of data bound to a gauge component. A gauge set displays a gauge for each row in multiple rows of data in a data collection.
You can specify the location of gauges within a gauge set by specifying values for attributes in the dvt:gauge tag.
To specify the layout of gauges in a gauge set: 1.
In the Structure window, right-click the dvt:gauge node and choose Go to Properties
.
2. In the Property Inspector, select the Common attributes category.
3.
To determine the number of columns of gauges that will appear in a gauge set, specify a value for the gaugeSetColumnCount attribute.
A setting of zero causes all gauges to appear in a single row. Any positive integer determines the exact number of columns in which the gauges are displayed. A
setting of -1 causes the number of columns to be determined automatically from the data source.
4.
To determine the placement of gauges in columns, specify a value for the gaugeSetDirection attribute.
If you select GSD_ACROSS, then the default layout of the gauges is used and the gauges appear from left to right, then top to bottom. If you select GSD_DOWN,
the layout of the gauges is from top to bottom, then left to right.
5.
To control the alignment of gauges within a gauge set, specify a value for the gaugeSetAlignment attribute.
This attribute defaults to the setting GSA_NONE, which divides the available space equally among the gauges in the gauge set. Other options use the available
space and optimal gauge size to allow for alignment towards the left or right and the top or bottom within the gauge set. You can also select GSA_CENTER to
center the gauges within the gauge set.
25.4.3 Changing Gauge Size and Style
You can customize the width and height of a gauge, and you can allow for dynamic resizing of a gauge based on changes to the size of its container. You can also control
the style sheet used by a gauge. These two aspects of a gauge are interrelated in that they share the use of the gauge inlineStyle attribute.
25.4.3.1 Specifying the Size of a Gauge at Initial Display
You can specify the initial size of a gauge by setting values for attributes of the dvt:gauge tag. If you do not also provide for dynamic resizing of the gauge, then the
initial size becomes the only display size for the gauge.
Using ADF Gauge Components 25-11
To specify the size of a gauge at its initial display: 1.
In the Structure window, right-click the dvt:gauge node and choose Go to Properties
.
2. In the Style attributes category of the Property Inspector, enter a value for the
InlineStyle attribute of the dvt:gauge tag. For example: inlineStyle=width:200px;height:200px
25.4.3.2 Providing Dynamic Resizing of a Gauge
You must enter values in each of two attributes of the dvt:gauge tag to allow for a gauge to resize when its container in a JSF page changes in size. The values that you
specify for this capability also are useful for creating a gauge component that fills an area across different browser window sizes.
To allow dynamic resizing of a gauge: 1.
In the Structure window, right-click the dvt:gauge node and choose Go to Properties
.
2. In the Behavior attributes category of the Property Inspector for the
DynamicResize attribute, select the value DYNAMIC_SIZE. 3.
In the Style attributes category of the Property Inspector, for the InlineStyle attribute, enter a fixed number of pixels or a relative percent for both width and
height.
For example, to create a gauge that fills its container’s width and has a height of 200 pixels, use the following setting for the inlineStyle attribute:
width:100;height:200px;
25.4.3.3 Using a Custom Style Class for a Gauge
You have the option of specifying a custom style class for use with a gauge. However, you must specify width and height in the inlineStyle attribute.
To specify a custom style class for a gauge: 1.
In the Structure window, right-click the dvt:gauge node and choose Go to Properties
.
2. In the Style attributes category of the Property Inspector, for the StyleClass
attribute, select Edit from the Property menu choices, and select the CSS style class to use for this gauge.
3.
In the InlineStyle attribute, enter a fixed number of pixels or a relative percent for both width and height.
For example, to create a gauge that fills its container’s width and has a height of 200 pixels, use the following setting for the inlineStyle attribute:
width:100;height:200px;.
25.4.4 How to Add Thresholds to Gauges
Thresholds are data values in a gauge that highlight a particular range of values. Thresholds must be values between the minimum and the maximum value for a
gauge. The range identified by a threshold is filled with a color that is different from the color of other ranges.
The data collection for a gauge can provide dynamic values for thresholds when the gauge is databound. After the gauge is created, you can also insert a
