23 Using Gauge Components

This chapter describes how to display data in gauges using the ADF Data Visualization gauge component. If your application uses the Fusion technology stack, then you can use data controls to create gauges. For more information, see the "Creating Databound Gauges" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

This chapter includes the following sections:

23.1 About the Gauge Component

Gauges are measuring instruments for indicating a quantity such as sales, stock levels, temperature, or speed. Gauges typically display a single data value, often more effectively than a graph. Gauges can show state information such as acceptable or unacceptable ranges using color. For example, a gauge value axis might show ranges colored red, yellow, and green to represent low, medium, and high states. When you need to compare many data values at a glance, multiple gauges can be shown inside table cells, or in a vertical, horizontal, or grid layout as a gauge set.

Best Practice Tip:

When multiple data values, such as the text values of thresholds and the current value are required, a list or table component may be a better choice than a gauge.

The gauge component supports four categories of gauge types: dial, status meter, vertical status meter, and LED. All gauge types can display a title, bottom label, data label, and legend.

23.1.1 End User and Presentation Features of Gauge Components

To understand how gauges are used and can be customized, it may be helpful to review these elements and features:

  • Display elements including:

    • Gauge and gauge set backgrounds

    • Gauge frames

    • Dial gauge plot area

    • Indicators and indicator bars

    • Gauge top, bottom, and metric labels

    • Thresholds and labels

    • Legends

    • Tick marks and labels

  • Tooltips: A tooltip of contextual information automatically displays when a user moves a cursor over the plot area, indicator, or threshold region. Figure 23-1 shows the indicator tooltip for a dial gauge.

    Figure 23-1 Indicator Tooltip for Dial Gauge

    Indicator tooltip for dial gauge.

23.1.2 Gauge Component Use Cases and Examples

Gauges are typically used to display a single data point. The following types of gauges are supported by the gauge component:

  • Dial: Indicates its metric along a configurable arc value axis. This is the default gauge type. Dial gauges can display as a simple gauge, a gauge with thresholds, or as a set of dial gauges.

    Figure 23-2 shows a dial gauge with thresholds indicating a Plasma HD TV stock level within an acceptable range.

    Figure 23-2 Dial Gauge with Thresholds

    Gauge dial with thresdholds.

  • Status Meter: Indicates the progress of a task or the level of some measurement along a horizontal rectangular bar. An inner rectangle shows the current level of a measurement against the ranges marked on an outer rectangle. Status meter gauges can display as a simple gauge, a gauge with thresholds, or as a set of status meter gauges.

    Figure 23-3 shows the Plasma HD TV stock level using a status meter gauge.

    Figure 23-3 Status Meter Gauge with Thresholds

    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. Vertical status meter gauges can display as a simple gauge, a gauge with thresholds, or as a set of vertical status meter gauges.

    Figure 23-4 shows the Plasma HD TV stock level using a vertical status meter gauge.

    Figure 23-4 Vertical Status Meter Gauge with Thresholds

    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 round or rectangular shapes that use color to indicate status and triangles or arrows that indicate good (up), fair (left- or right-pointing), or poor (down) states in addition to a color indicator. LED gauges can also display as a gauge set.

    Figure 23-5 shows the Plasma HD TV stock level using a LED bulb indicator using color to indicate status.

    Figure 23-5 LED Bulb Gauge

    LED bulb gauge.

    Figure 23-6 shows the same stock level using a LED arrow.

    Figure 23-6 LED Arrow Gauge

    LED arrow gauge

All gauge types can be displayed as a set of gauges in a built-in grid layout. Gauge sets are useful when displaying individual values for a group of related items. Figure 23-7 shows a gauge set comparing performance measures across three cities.

Figure 23-7 Gauge Set Comparing Performance Across Cities

Gauge Set Comparing Performance Across Cities

Horizontal status meter and LED gauges are well-suited for display in table cells where users can see and compare them alongside related information such as labels, links, and icons. Figure 23-8 shows a table comparing the population density in countries with the highest population in 2010.

Figure 23-8 Horizontal Status Meter Gauges Displayed in Table

Horizontal status meter gauges displayed in table.

23.1.3 Additional Functionality of Gauge Components

You may find it helpful to understand other ADF Faces features before you implement your gauge component. Additionally, once you have added a gauge 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 gauge components can use:

  • Partial page rendering: You may want a gauge to refresh to show new data based on an action taken on another component on the page. For more information, see Chapter 8, "Rerendering Partial Page Content."

  • Personalization: When enabled for users to change the way the gauge displays at runtime, those values will not be retained once the user leaves the page unless you configure your application to allow user customization. For information, see Chapter 32, "Allowing User Customization on JSF Pages."

  • Accessibility: You can make your gauge components accessible. For more information, see Chapter 30, "Developing Accessible ADF Faces Pages."

  • Skins and styles: You can customize the appearance of gauge 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 Chapter 28, "Customizing the Appearance Using Styles and Skins."

  • Automatic data binding: If your application uses the Fusion technology stack, then you can create automatically bound gauges based on how your ADF Business components are configured. For more information, see the "Creating Databound Gauges" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

    Note:

    If you know the UI 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 the "Designing a Page Using Placeholder Data Controls" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Additionally, data visualization components share much of the same functionality, such as how data is delivered, automatic partial page rendering (PPR), and how data can be displayed and edited. For more information, see Section 21.2, "Common Functionality in Data Visualization Components."

23.2 Using the Gauge Component

Gauges display the following kinds of data values:

  • 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 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 gauge tag. For more information, see Section 23.3.1, "How to Configure Gauge Thresholds."

  • 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 23.3.1, "How to Configure Gauge Thresholds."

23.2.1 Configuring Gauges

The properties for the gauge component are sufficient to produce a gauge, but you can also add and configure child components or supported facets to further customize the display and behavior of the gauge or gauge set. The prefix dvt:occurs at the beginning of each gauge component name indicating that the component belongs to the ADF Data Visualization Tools (DVT) tag library. You can configure gauge child components and supported facets in the following areas:

  • Gauge display elements:

    • Gauge background (gaugeBackground) and gauge set background (gaugeSetBackground): Bounded area behind the gauge or gauge set.

    • Gauge frame (gaugeFrame): Refers to the decorative frame that encloses the plot area on dial gauges.

    • Plot area (gaugePlotArea): Indicates the graphical representation of the metric value of the gauge.

    • Indicator (indicator): Points to the value that is plotted in a dial gauge, typically in the form of a line or an arrow.

    • Indicator bar (indicatorBar): The inner rectangle in a status meter gauge.

    • Indicator base (indicatorBase): The circular base of a line or needle style indicator in a dial gauge.

    • Gauge labels:

      • Top label (topLabel): Shows the gauge title appearing at the top or inside of a gauge. You can configure an upper label frame (upperLabelFrame) for this label to specify border color and fill color. Turn off the default title separator when using this frame.

      • Bottom label (bottomLabel): Refers to an optional label that appears below or inside the gauge. By default, displays the label for the data row. You can configure a lower label frame (lowerLabelFrame) for this label to specify border color and fill color.

      • Metric label (metricLabel): Shows the value of the metric that the gauge is plotting in text.

    • Thresholds and legend: Use a threshold set (thresholdSet) to specify the threshold sections (threshold) for the metrics of a gauge. You can create an unlimited number of thresholds for a gauge.

      A legend displays a description of the threshold set with the color and the name or range of each threshold. Legend elements include legend area (gaugeLegendArea), text (gaugeLegendText), and title (gaugeLegendTitle).

    • Tick marks (tickMark): 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 tick mark labels (tickLabel) or minor increments.

    • Context menus (bodyContextMenu facet): Use this facet to support a single af:popup component containing the context menu that will be shown on right click on any non-selectable object within the component. The af:popup must contain an af:menu to display the context menu.

  • Data values: Format categorical and numeric data values with standard ADF converters. For more information, see Section 23.5, "Formatting Numeric Data Values in Gauges."

  • Interactivity: Use a shape attributes set (shapeAttributesSet) to configure behavior properties for gauge 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 23.6.3, "How to Add Interactivity to Gauges."

  • Custom shapes: You can use a set of pre-built custom styles for gauges, or specify a vector graphics file that is used for output by setting the customShapesPath attribute. For more information, see Section 23.7, "Using Custom Shapes for Gauges."

  • Image formats: Gauges support the following image formats: HTML5, Flash, and PNG. By default, gauges display in Flash, but you can change the default image format. You can also disable Flash across your application or customize its behavior on client platforms. For more information, see Section 23.2.5, "What You May Need to Know About Gauge Image Formats."

23.2.2 How to Add a Gauge to a Page

When you are designing your page using simple UI-first development, you use the Component Palette to add a gauge to a JSF page. When you drag and drop a gauge component onto the page, the Component Gallery displays available categories of gauge types, with descriptions, to provide visual assistance when creating gauges. You can also specify a quick-start layout of the gauge's title and legend. Figure 23-9 shows the Component Gallery for gauges with the dial gauge type selected.

Figure 23-9 Component Gallery for Gauges

Gauge Component Gallery.

Once you complete the dialog, and the gauge is added to your page, you can use the Property Inspector to specify data values and configure additional display attributes for the gauge.

In the Property Inspector you can use the dropdown menu for each attribute field to display a property description and options such as displaying an EL Expression Builder or other specialized dialogs. Figure 23-10 shows the dropdown menu for a gauge component value attribute.

Figure 23-10 Gauge Component Value Attribute Dropdown Menu

gauge component attribute field dropdown list

Note:

If your application uses the Fusion technology stack, then you can use data controls to create a gauge and the binding will be done for you. For more information, see the "Creating Databound Gauges" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child components can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You may also find it helpful to understand functionality that can be added using other ADF Faces features. For more information, see Section 23.1.3, "Additional Functionality of Gauge Components."

To add a gauge to a page:

  1. In the Component Palette, from the ADF Data Visualizations page, in the Gauge panel, drag and drop a Gauge onto the page to open the Create Gauge dialog in the Component Gallery.

    Use the dialog to select the gauge category and type, and the quick start layout for display of gauge title, legend, and labels. If you need help, press F1 or click Help.

  2. In the Property Inspector, view the attributes for the gauge or gauge set. Use the help button to display the complete tag documentation for the gauge component.

  3. Expand the Common section. Use this section to set the following attributes:

    • GaugeType: If you wish to change the category of gauge types selected in the Component Gallery, use the dropdown list to select any of the following valid values: DIAL, LED, STATUSMETER, or VERTICALSTATUSMETER.

    • GaugeSetColumnCount, GaugeSetAlignment, and GaugeSetDirection: Use one or more of these attributes to determine the layout of gauges in a gauge set. For more information see, Section 23.3.4, "How to Specify the Layout of Gauges in a Gauge Set."

  4. Expand the Gauge Data section. Specify data values for the gauge by setting the value in these fields:

    • Value: For a single gauge, specify the data model, which must be an instance of DataModel, using an EL Expression. Alternatively, set a metric value as either a Java.lang.Number object or a String.

    • TabularData: For a gauge set, specify a tabular data set as a Java.util.List object. For more information, see Section 23.2.4, "How to Create a Gauge Using Tabular Data."

    • MinValue and MaxValue: Optionally, set the lowest and greatest values on the gauge axis. These values are set automatically if not specified.

  5. Expand the Appearance section. Specify display attributes by setting the value in these fields:

    • LedStyle: If you wish to change the shape of the LED gauge selected in the Component Gallery, use the dropdown list to select any of the following valid values: LS_DOT, LS_ARROW, LS_RECTANGLE, or LS_TRIANGLE. You can also use the LS_CUSTOM value if you wish to specify a custom image.

    • ThresholdDialStyle: If you wish to change the default style (TDS_SEGMENTS) of thresholds in dial gauges, use the dropdown list to select any of the following valid values: TDS_PIE_FILL, TDS_RING_FILL.

    • AngleExtent: Use to specify the range of degrees that sweeps through angles other than the standard 220-degree arc in a dial gauge.

    • CustomShapesPath: Use to specify the path to the custom shape definition file. For more information, see Section 23.7, "Using Custom Shapes for Gauges."

    • ShortDesc: Enter a description of the gauge. This description is accessed by screen reader users.

    • AnimationOnDisplay, AnimationOnDataChange, AnimationDuration (Animation sub-section): Use one or more of these attributes to set animation effects for the gauge. For more information, see Section 23.6.4, "Animating Gauges."

By default, your gauge will display in the Flash image format. If you want to change the default image format or restrict the usage of Flash content, see Section 23.2.5, "What You May Need to Know About Gauge Image Formats."

23.2.3 What Happens When You Add a Gauge to a Page

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 23-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 23-9.

Example 23-1 Gauge Sample Code

<dvt:gauge id="gauge1" gaugeType="DIAL">
  <dvt:gaugeBackground>
    <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:gauge>

23.2.4 How to Create a Gauge Using Tabular Data

A gauge set is created when a grid of data is used for the gauge component. The tabularData attribute of a gauge component lets you specify a list of values that the gauge uses to create a grid and to populate itself. To create a gauge using tabular data you must store the data in a method in the gauge's managed bean, and then use the gauge component's tabularData attribute to reference the data.

When you provide only the metric value through the tabularData attribute, each value in the grid is represented by a separate gauge. In this case you must specify any desired thresholds and minimum or maximum values through the Property Inspector.

For example, the table in Figure 23-11 has five columns: Quota, Sales, Margin, Costs, and Units, and 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 23-11 Comparison of Annual Results

Comparison of annual results for 3 cities.

In a managed bean, the structure of the list of 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 of the data value in the grid. This is generally a String.

  • The second member (index 1) is the row label of the data value in the grid. This is generally a String.

  • The third member (index 2) is the data value, which is usually Double.

Example 23-2 shows code in a managed bean that creates the list of tabular data required for the gauge that compares annual results for three cities displayed in Figure 23-11.

Example 23-2 Managed Bean to Create a List of Tabular Data for Annual Results

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;
}

To provide the metric value and optionally threshold. minimum, and maximum values, use data specification to set the columns or rows of data through the tabularData attribute.

For example, the data in Figure 23-12 provides the metric values and minimum, maximum, and threshold values for two cities. The data produces a gauge set of two gauges comparing sales results by desired specifications.

Figure 23-12 Comparison of Sales Results by Specification

Comparison of desired specifications.

Example 23-3 shows code in a managed bean that creates the list of tabular data required for the gauge that compares sales results by specification for two cities displayed in Figure 23-12.

Example 23-3 Managed Bean to Create a List of Tabular Data for Sales Results

CommonGauge gauge = new CommonGauge();
    Object[] specs = { DataSpecification.METRIC, DataSpecification.MINIMUM, DataSpecification.MAXIMUM, DataSpecification.THRESHOLD, DataSpecification.THRESHOLD }; 
    String[] colLabels = new String[] { "Sales", "Min", "Max", "Quota", "Target" };
    String[] rowLabels = new String[] { "Boston", "Chicago" };
    double[][] values = new double[][] { {40, 60}, {0,0}, {100,80}, {30,35}, {50,70} };
    List gaugeData = new ArrayList();
    for (int c = 0; c < colLabels.length; c++) {
       for (int r = 0; r < rowLabels.length; r++) {
          gaugeData.add(new Object[] { colLabels[c], rowLabels[r], new Double(values[c][r]) });
       }
    }
    gauge.setTabularData(specs, gaugeData);

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a managed bean that creates a list of tabular data. If you do not, follow the instructions in Section 3.6, "Creating and Using Managed Beans."

You should already have a gauge set on your page. If you do not, follow the instructions in this chapter to create a gauge set. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

To create a gauge set using tabular data from a managed bean:

  1. In the Structure window, select the dvt:gauge component.

  2. In the Property Inspector expand the Gauge Data section.

  3. From the TabularData attribute menu, choose Expression Builder.

  4. In the Expression Builder dialog, use the search box to locate the gauge's 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 gauge component.

23.2.5 What You May Need to Know About Gauge Image Formats

Gauges support the following image formats: HTML5, Flash, and PNG. The image format used depends upon the application's settings and the client's environment. By default, gauges display in Flash, but you can configure your application to use a specific image format by setting the following parameters:

If the specified image format is not available on the client, the application will default to an available format. For example, if the client does not support HTML5, the application will use:

  • Flash, if the Flash Player is available.

  • Portable Network Graphics (PNG) output format. A PNG output format is also used when printing gauges. Although static rendering is fully supported when using a PNG output format, certain interactive features are not available including:

    • Animation

    • Context menus

    • Popup support

    • Interactivity

To improve performance, inline PNG images using data URIs are used when there is browser support for URIs and the images are sufficiently small. However, if the application specifies a path to a stored image using the imageSource attribute on the gauge component, it will be respected and inline images will not be sent.

23.2.6 Using Gauges in Tables

You can display gauges in table cells where users can see and compare them alongside related information. The immediate children of an ADF table component must be column components. Each visible column component is displayed as a separate column in the table. Column components contain components used to display content, images, or provide further functionality.

The child components of each column display the data for each row in that column. The column does not create child components per row; instead, the table uses stamping to render each row. Each child is stamped once per row, repeatedly for all the rows. As each row is stamped, the data for the current row is copied into a property that can be addressed using an EL expression. You specify the name to use for this property using the var property on the table. Once the table has completed rendering, this property is removed or reverted back to its previous value.

Example 23-4 shows sample code for displaying gauges in an ADF table component.

Example 23-4 Gauge Component Stamped in Table Column

<af:table summary="table" value="#{gaugeData.gaugeTableData}" var="testvar"
     rowBandingInterval="0" id="t1" columnStretching="last"
     inlineStyle="height:400px" styleClass="AFStretchWidth">
  <af:column rowHeader="true" sortable="false" headerText="Country"
             align="center" id="c1" width="120"
             inlineStyle="font-weight:bold; font-size: 12px;">
    <af:outputText value="#{testvar.name}" id="ot1"/>
  </af:column>
  <af:column sortable="true" headerText="Density (1/km^2)"
             align="center" id="c2" width="300"
             sortProperty="density">
    <dvt:gauge shortDesc="Gauge" id="gauge77" gaugeType="STATUSMETER"
               binding="#{editor.component}" dynamicResize="DYNAMIC_SIZE"
               value="#{testvar.density}"
               inlineStyle="height:22px" styleClass="AFStretchWidth"
               minValue="0.0" maxValue="1200.0">
      <dvt:indicatorBar/>
      <dvt:thresholdSet>
        <dvt:threshold fillColor="#00aa00" thresholdMaxValue="300"/>
        <dvt:threshold fillColor="#ffcc00" thresholdMaxValue="700"/>
        <dvt:threshold fillColor="#cc2255"/>
      </dvt:thresholdSet>
      <dvt:topLabel position="LP_NONE"/>
      <dvt:bottomLabel position="LP_NONE"/>
      <dvt:metricLabel position="LP_NONE"/>
    </dvt:gauge>
  </af:column>
</af:table>

When configuring gauges in table cells, use these guidelines to improve usability:

  • Vertical status meter gauges are not recommended for use in table cells as the table rows would have to be very tall.

  • Make gauges as small as possible while maintaining legibility.

  • To maximize use of space, use table column and row headers to describe gauges, rather than using gauge titles or bottom labels.

  • Use only one type of gauge per column or row, and use the same axis values and thresholds.

  • Display horizontal status meters in columns, and dial and LED gauges in rows or columns.

  • Avoid displaying so many gauges that users must scroll to see them all.

23.3 Configuring Gauge Display Elements

You can customize gauge display elements including thresholds, labels, indicators, tick marks, and the layout of gauge sets.

23.3.1 How to Configure Gauge Thresholds

Thresholds are numerical 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. For information about using dynamic values for thresholds, see

After the gauge is created, you can also specify static threshold values by configuring a thresholdSet child component that wraps an unlimited number of threshold child components in a gauge. If threshold values are supplied in both the data collection and in threshold components, the gauge honors the values in the threshold components.

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

Note:

If you create a gauge using a gauge type with thresholds in the Component Gallery, a dvt:thresholdSet component and dvt:threshold component children are automatically added to the dvt:gauge component in the Structure window.

To add static thresholds to a gauge:

  1. In the Structure window, right-click the dvt:gauge component and choose Insert inside dvt:gauge > ADF Data Visualization > Threshold Set.

  2. Right-click the dvt:thresholdSet component and choose Insert inside dvt:thresholdSet > Threshold.

  3. In the Property Inspector, set the following attributes:

    • ThresholdMaxValue: Specify the maximum value for the threshold section you are configuring. Values can be an integer or

      Note:

      For the final threshold, the maximum value of the gauge is used as the threshold maximum value regardless of any entry you make in the ThresholdMaxValue attribute for the final threshold.

    • FillColor and BorderColor: Optionally, specify a RGB value for the fill color and border color respectively for the threshold section you are configuring. You can also change the color from opaque to transparent. For more information, see Section 23.4.2, "Specifying Transparency for Gauge Elements."

    • Text: Optionally, specify the text to be displayed in the legend to identify this threshold. You can also bind the text to a text resource. For more information, see Section 23.4.3, "How to Format Gauge Text and Use Text Resources."

  4. Repeat Step 2 and Step 3 to create each threshold in the gauge from the lowest minimum value to the highest maximum value.

Note:

You have the option of adding any number of thresholds to gauges. However, arrow and triangle LED gauges support thresholds only for the three directions to which they point

23.3.2 How to Customize Gauge Labels

By default gauges display a metric label, and optional top and bottom labels using the child components metricLabel, topLabel, and bottomLabel. You can customize the display and positioning of each label, as well as control the fill and border colors of the optional top and bottom gauge label frames.

The categorical data value represented by the top or bottom label can also be customized using an attributeFormat tag and ADF Faces converter tags to format percents, scale numbers, control the number of decimal places, placement of signs, and so on. For more information, see Section 23.5.1, "How to Format Numeric Data Values in Gauges."

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

Note:

When you add a gauge to your page, gauge child label components are automatically added to the gauge component. The default location, if any, of each gauge label is specified in the position attribute of the component, based on the choice you make for a quick-layout option in the Component Gallery.

To customize a gauge label:

  1. In the Structure window, select the gauge child label component (dvt:metricLabel, dvt:topLabel, or dvt:bottomLabel) you wish to configure.

  2. In the Property Inspector, set the following attributes:

    • Position: Use to specify the location, if any, of the gauge label. Valid values include:

      • LP_NONE: No label is displayed.

      • LP_INSIDE_GAUGE: Label is displayed inside the plot area of the gauge. Labels are horizontally centered across a gauge. When set to this value, top and bottom labels are also vertically centered inside the plot area. Good choice for the LED gauge.

      • LP_INSIDE_GAUGE_RIGHT and LP_INSIDE_GAUGE_LEFT: Metric label is displayed either to the right or lefts of the plot area.

      • LP_ABOVE_GAUGE: The default value for the top label. Displays the label above the gauge.

      • LP_BELOW_GAUGE: The default value for the bottom label. Displays the label below the gauge. If the position of both the bottom and metric labels are set to this value, then both labels are displayed below the gauge. However, the bottom label is displayed above the metric label.

      • LP_WITH_BOTTOM_GAUGE: The default value for the metric label. Displays the label beside the bottom label.

    • Text: The text displayed in the top or bottom label. In the attribute menu, choose Select Text Resources for a dialog to associate the text with application text resources. For more information, see Section 23.4.3, "How to Format Gauge Text and Use Text Resources."

    • NumberType, Scaling, and AutoPrecision: Available only for metric labels. Use these attributes to configure the display of numeric data values in the gauge. For more information, see Section 23.5.2, "What You May Need to Know About Automatic Scaling and Precision."

  3. If you wish to configure the text font used in the gauge label, do the following:

    1. In the Structure window, right-click the gauge child label component (dvt:metricLabel, dvt:topLabel, or dvt:bottomLabel) you wish to configure and select Insert inside label component > Font.

    2. In the Property Inspector, set the attributes for the font. For more information, see Section 23.4.3, "How to Format Gauge Text and Use Text Resources."

  4. If you wish to configure a frame around the top or bottom gauge label, do the following:

    1. In the Structure window, right-click the dvt:gauge component and select Insert inside dvt:gauge > Upper Label Frame or Lower Label Frame.

    2. In the Property Inspector, specify a RGB value for the FillColor and BorderColor attributes for the label frame you are configuring. You can also change the color from opaque to transparent. For more information, see Section 23.4.2, "Specifying Transparency for Gauge Elements."

23.3.3 How to Customize Gauge Indicators and Tick Marks

Gauges use a graphic to indicate the precise gauge value. By default gauges display a line for dial gauges using the child component indicator, and a bar inside status meter or vertical status meter gauges using the child component indicatorBar. The child component indicatorBase is used to set the fill properties of the circular base of all indicators of a dial gauge. You can customize the appearance of gauge indicators.

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

Note:

When you add a gauge to your page, gauge child indicator components are automatically added to the gauge component based on the gauge type you chose in the Component Gallery. LED gauges do not have indicators.

To customize the appearance of gauge indicators:

  • For dial gauge indicators, do the following:

    1. In the Structure window, select the dvt:indicator component.

    2. In the Property Inspector, set the following attributes:

      • Type: Identifies the kind of indicator: a line indicator (default), a fill indicator, or a needle indicator.

      • BorderColor: Specifies the color of the border of the indicator.

      • FillColor: Specifies the color of the fill for the indicator.

      • UseThresholdFillColor: Determines whether the color of the threshold area in which the indicator falls should override the specified color of the indicator.

    3. In the Structure window, select the dvt:indicatorBase component.

    4. In the Property Inspector, set the following attributes:

      • Rendered: Identifies the kind of indicator: a line indicator (default), a fill indicator, or a needle indicator.

      • BorderColor: Specifies the color of the border of the indicator.

      • FillColor: Specifies the color of the fill for the indicator.

  • For status meter and vertical status meter gauges, do the following:

    1. In the Structure window, select the dvt:indicatorBar component.

    2. In the Property Inspector, set the following attributes:

      • BorderColor: Specifies the color of the border of the indicator.

      • FillColor: Specifies the color of the fill for the indicator.

      Note:

      If you want to specify that the color of the threshold area in which the indicator bar falls should override the specified color of the indicator, add an indicator component to the gauge, and set its UseThresholdFillColor attribute to true.

Tick marks are incremental marks along the gauge value axis for dial, status meter, and vertical status meter gauges. LED gauges do not have tick marks. By default, gauges display tick marks using the gauge child tickMark component to specify the display, spacing, and color or major and minor tick marks.

The gauge child tickLabel component identifies major tick labels to specify the location of the labels (interior or exterior of the gauge), and the format for numbers displayed in the tick labels. Minor tick marks do not support labels.

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

Note:

When you add a gauge to your page, gauge child tick mark and tick mark label components are automatically added to the gauge component based on the choices you make in the Component Gallery. LED gauges do not have tick marks.

To customize the tick marks and tick labels for a gauge:

  1. In the Structure window, select the dvt:tickMark component.

  2. In the Property Inspector, set values for the following attributes:

    • MajorIncrement and MinorIncrement: Sets the distance between two major tick marks and two minor tick marks, respectively. If the value is less than zero for either attribute, the tick marks are not displayed.

    • MajorTickColor and MinorTickColor: Sets the hexidecimal color of major tick marks and minor tick marks, respectively.

    • Content: Specifies where tick marks occur within a gauge set. Valid values are any combination separated by spaces or commas including:

      • TC_INCREMENTS: Display tick marks in increments.

      • TC_MAJOR_TICK: Display tick marks for minimum, maximum, and incremental values.

      • TC_MIN_MAX: Display tick marks for minimum and maximum values.

      • TC_METRIC: Display tick marks for actual metric values.

      • TC_NONE: Display no tick marks.

      • TC_THRESHOLD: Display tick marks for threshold values.

  3. In the Structure window, select the dvt:tickLabel component.

  4. In the Property Inspector, set values for the following attributes:

    • Position: By default, the dial gauge displays interior tick labels to provide a cleaner look when the gauge is contained entirely within the gauge frame. Because the tick labels lie within the plot area, the length of the tick labels must be limited to fit in this space. You can customize your gauge to use exterior labels by setting the value for this attribute to TLP_EXTERIOR from the default TLP_INTERIOR.

    • Content: Specifies where tick labels occur within a gauge set. Valid values are any combination separated by spaces or commas including:

      • TC_INCREMENTS: Display tick labels in increments.

      • TC_MAJOR_TICK: Display tick labels for minimum, maximum, and incremental values.

      • TC_MIN_MAX: Display tick labels for minimum and maximum values.

      • TC_METRIC: Display tick labels for actual metric values.

      • TC_NONE: Display no tick labels.

      • TC_THRESHOLD: Display tick labels for threshold values.

    • NumberType, Scaling, and AutoPrecision: Available only for metric labels. Use these attributes to configure the display of numeric data values in the gauge. For more information, see Section 23.5.1, "How to Format Numeric Data Values in Gauges."

23.3.4 How to Specify 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 gauge component.

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child components can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge set on your page. If you do not, follow the instructions in this chapter to create a gauge set. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

To specify the layout of gauges in a gauge set:

  1. In the Structure window, right-click the dvt:gauge component and choose Go to Properties.

  2. In the Property Inspector, expand the Common section and set the following attributes:

    • GaugeSetColumnCount: Specify the number of columns of gauges that will appear in the gauge set.

      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.

    • GaugeSetDirection: Use the dropdown list to select a value for the placement of gauges in columns.

      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.

    • GaugeSetAlignment: Use the dropdown list to select a value for the alignment of gauges within a gauge set.

      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.

23.3.5 What You May Need to Know About Configuring Gauge Set Display

When configuring gauge set display, use these guidelines to improve usability:

  • When the individual gauges in a gauge set do not have titles or axes, specify a label above the gauge set that displays the name of the data set and its units of measure, for example, "2010 Population (Millions)."

  • When thresholds are defined, include a legend. For more information, see Section 23.3.1, "How to Configure Gauge Thresholds."

  • Avoid displaying so many gauges that users must scroll to view all of the gauges.

23.4 Formatting Gauge Style Elements

You can customize the styling of gauges to change the initial size or a gauge, specify dynamic resizing to fit the presentation area of a gauge, and apply style elements. You can also use text formatting and text resource, and transparency in gauges.

23.4.1 How to Change Gauge Size and Apply CSS Styles

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.

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. These two aspects of a gauge are interrelated in that they share the use of the gauge inlineStyle attribute.

You can also apply CSS styles such as active, focus, hover, link, and visited to use for a gauge.

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

To specify the size of a gauge:

  1. In the Structure window, select the dvt:gauge component.

  2. In Property Inspector, expand the Style section. Specify the initial size of the gauge in the InlineStyle attribute. If you do not also provide for dynamic resizing of the gauge, then the initial size becomes the only display size for the gauge. For example,

    width:200px;height:200px

    If you are specifying dynamic resizing for the gauge, you can enter a fixed number of pixels or a relative percent for both width and height. For example, to create a gauge that fills 50% of its container's width and has a height of 200 pixels, use the following setting for the InlineStyle attribute:

    width:50%;height:200px

    Best Practice Tip:

    Instead of specifying width at 100% in the inlineStyle attribute, set the styleClass attribute to AFStretchWidth.

  3. If you want to specify dynamic resizing for the gauge, expand the Behavior section. From the DynamicResize attribute dropdown list, select DYNAMIC_SIZE.

To apply CSS styles to a gauge:

  1. In the Structure window, select the dvt:gauge component.

  2. In the Property Inspector, expand the Style section. From the StyleClass attribute menu, choose Edit and use the property editor dialog to select the CSS styles to apply to the gauge.

23.4.2 Specifying Transparency for Gauge Elements

You can specify that various elements of a gauge display a transparent color instead of the default opaque color by setting the borderColor and fillColor attributes on the gauge child components related to those elements. These color properties accept a 6 or 8 RGB hexidecimal value. When an 8-digit value is used, the first two digits represent transparency. For example, you can set transparency by using a value of 00FFFFFF.

Any gauge child component that supports borderColor or fillColor attributes can be set to transparency. The following are examples of gauge child components that support transparency:

  • gaugeBackground

  • gaugeFrame

  • gaugePlotArea

  • gaugeLegendArea

23.4.3 How to Format Gauge Text and Use Text Resources

You can format the text in gauges using a gaugeFont component as a child for any of the these gauge child components that represent titles and labels in a gauge:

  • bottomLabel

  • metricLabel

  • gaugeLegendText

  • gaugeLegendTitle

  • tickLabel

  • topLabel

The attributes of the gaugeFont component allows you to specify these font attributes for the gauge child element:

  • name: Specifies the name of the font, for example San Serif.

  • size: Specifies the font size in pixels, for example 11.

  • color: Specifies the color of the font. This color property accepts a 6 or 8 RGB hexidecimal value. When an 8-digit value is used, the first two digits represent transparency. For example, you can set transparency by using a value of 00FFFFFF

  • bold: Specifies whether or not the font is bold. The default value is FALSE.

  • italic: Specifies whether or not the text is in italics. The default value is FALSE.

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

Note:

When you add a gauge to your page, gauge child components for titles or labels are automatically added to the gauge component, based on the choices you make in the Component Gallery.

To specify a text font for a gauge title or label component:

  1. In the Structure window, right-click the gauge child component for a title or label, for example, dvt:metricLabel, and choose Insert inside dvt:metricLabel > Font.

    If the component is not available, right-click the dvt:gauge component, and choose Insert inside dvt:gauge > ADF Data Visualization > gauge child title or label component.

  2. In the Property Inspector, set values for one or more of the dvt:gaugeFont component attributes. Use the help button to display the complete tag documentation for the dvt:gaugeFont component.

You can also set the font attributes of gauge components globally across all pages in your application by using a cascading style sheet (CSS) to build a skin, and configuring your application to use the skin. By applying a skin to define the fonts used in gauge components, the pages in an application will be smaller and more organized, with a consistent style easily modified by changing the CSS file. For more information, see Chapter 28, "Customizing the Appearance Using Styles and Skins."

JDeveloper supports easy localization of DVT components using the abstract class java.util.ResourceBundle to provide locale-specific resources. For those gauge child components that represent titles and labels in a gauge you can associate a text resource referenced in an application resource bundle. For more information, see Chapter 29, "Internationalizing and Localizing Pages."

To specify a text resource for a gauge title or label component:

  1. In the Structure window, select the gauge child component for a title or label, for example, dvt:metricLabel.

  2. In the Property Inspector, in the text attribute menu, choose Select Text Resources to open the Select Text Resource dialog.

    Use the dialog to associate the component text with a text resource. If you need help, press F1 or click Help

23.5 Formatting Numeric Data Values in Gauges

Gauge child components including metricLabel, tickLabel, and gaugeLgendText display numeric data values in gauges. Each component has a numberType attribute that lets you specify whether you want to display the value itself, or a percentage that the value represents. In some cases, this might be sufficient numeric formatting.

If you wish to further format the gauge metric or tick label value, you can use an ADF Faces standard converter, af:convertNumber. For example, you may wish to display the value as currency or display specific decimal settings.

23.5.1 How to Format Numeric Data Values in Gauges

The metrics represented in gauges are numeric data values. You can apply specific formatting rules to these values.

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

Note:

When you add a gauge to your page, gauge child components that display configurable data values are automatically added to the gauge component, based on the choices you make in the Component Gallery.

To format numeric data values in a gauge:

  1. In the Structure window, select the gauge child component displaying data values (metricLabel, tickLabel, or gaugeLegendText) that you wish to configure.

    If the component is not available, right-click the dvt:gauge component, and choose Insert inside dvt:gauge > ADF Data Visualization > (metricLabel, tickLabel, or gaugeLegendText).

  2. In the Property Inspector, if you want to display the data value as a percentage rather than as a value, set the NumberType attribute of the component to NT_PERCENT.

  3. If you want to specify additional formatting for the data values displayed in the gauge metric or tick label, do the following:

    1. In the Structure window, right-click the dvt:metricLabel or dvt:tickLabel, and choose Insert inside (dvt:metricLabel or dvt:tickLabel) > Convert Number.

    2. In the Property Inspector, specify values for the attributes of the af:convertNumber component to produce additional formatting. Use the help button to display the complete tag documentation for the af:convertNumber component.

Note:

When the numberType attribute of metric or tick labels is set to percent (NT_PERCENT), a child af:convertNumber tag, if used, will be automatically set to percent for its type attribute. When af:convertNumber is forced to percent, gauge clears the pattern attribute. This means that patterns are ignored when a gauge forces percent formatting.

23.5.2 What You May Need to Know About Automatic Scaling and Precision

In order to achieve a compact and clean display, gauges automatically determine the scale and precision of the values being displayed in metric labels and tick labels. For example, a value of 40,000 will be formatted as 40K, and 0.230546 will be displayed with 2 decimal points as 0.23.

Automatic formatting still occurs when af:convertNumber is specified. Gauge tags that support af:convertNumber child tags have scaling and autoPrecision attributes that can be used to control the gauge's automatic number formatting. By default, these attribute values are set to scaling="auto" and autoPrecision="on". Fraction digit settings specified in af:convertNumber, such as minFractionDigits, maxFractionDigits, or pattern, are ignored unless autoPrecision is set to off.

23.6 Adding Gauge Special Effects and Animation

You can add special features to a gauge such as applying gradient effects to parts of a gauge, adding interactivity to gauges, animating gauges, and taking advantage of gauge support for active data.

23.6.1 How to Add Gradient Special Effects to a Gauge

A gradient is a special effect in which an object changes color gradually. Each color in a gradient is represented by a stop. The first stop is stop 0, the second is stop 1, and so on. You must specify the number of stops in the special effects for a child component of a gauge that supports special effects.

You can define gradient special effects for the following child components of a gauge:

  • gaugeBackground

  • gaugeSetBackground

  • gaugePlotArea

  • gaugeFrame

  • gaugeLegendArea

  • lowerLabelFrame

  • upperLabelFrame

  • indicator

  • indicatorBar

  • indicatorBase

  • threshold

For each child component of a gauge to which you want to add special effects, you must insert a child specialEffects component. For example, if you want to add a gradient to the background of a gauge, then you would add a child specialEffects component to the background component. You must also set the specialEffects component fillType attribute to FT_GRADIENT.

Then, optionally if you want to control the rate of change for the fill color of the child component, you add as many gradientStopStyle components as you need to control the color and rate of change for the fill color of the component. The gradientStopStyle components are added as child components to the specialEffects component.

The approach that you use to define gradient special effects is identical for each child component of the gauge that supports these effects. The procedure defines how to add gradient special effects to the background of a gauge.

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

Note:

When you add a gauge to your page, gauge child components are automatically added to the gauge component based on the gauge type you chose in the Component Gallery.

To add a gradient special effect to the background of a gauge:

  1. In the Structure window, right-click the gauge child component that supports gradient special effects, for example dvt:gaugeBackground, and choose Insert inside dvt:gaugeBackground > Special Effects.

  2. In the Property Inspector, set the following attributes:

    • FillType: From the dropdown list select FT_GRADIENT.

    • GradientDirection: From the dropdown list select the direction of change that you want to use for the gradient fill. The default value is GD_RIGHT.

    • NumStops: Enter the number of stops to use for the gradient.

  3. Optionally, in the Property Inspector, click Configure Gradient Stops to control the color and rate of change for the first gradient stop.

  4. In the Property Inspector, set the following attributes:

    • StopIndex: Enter a zero-based integer as an index for the component.

    • GradientStopColor: Specify a RGB value for the color that you want to use at this specific point along the gradient. You can also change the color from opaque to transparent. For more information, see Section 23.4.2, "Specifying Transparency for Gauge Elements."

    • GradientStopPosition: Enter the proportional distance along a gradient for the identified stop color. The gradient is scaled from 0 to 100. If 0 or 100 is not specified, default positions are used for those points.

  5. If you wish to configure additional gradient stops, in the Structure window, right-click the dvt:specialEffects component and choose Insert inside dvt:specialEffects > dvt:gradientStopStyle.

  6. Repeat Step 4 for each gradient stop you want to configure.

23.6.2 What Happens When You Add a Gradient Special Effect to a Gauge

When you add a gradient fill to the background of a gauge, specify two stops, and configure the color and rate of change for each stop, XML code is generated. Example 23-5 shows the XML code that is generated.

Example 23-5 XML Code Generated for Adding a Gradient to the Background of a Gauge

<dvt:gauge>
  <dvt:gaugeBackground borderColor="#848284">
    <dvt:specialEffects fillType="FT_GRADIENT" gradientDirection="GD_RADIAL">
      <dvt:gradientStopStyle stopIndex="0" gradientStopPosition="60"
           gradientStopColor="FFFFCC"/>
      <dvt:gradientStopStyle stopIndex="1" gradientStopPosition="90"
           gradientStopColor="FFFF99"/>
    </dvt:specialEffects> 
  </dvt:gaugeBackground>
</dvt:gauge>

23.6.3 How to Add Interactivity to Gauges

Interactivity in gauges involves associating a specified part of a gauge with an HTML attribute such as a hyperlink, or a JavaScript event such as a user moving the cursor over that part of the gauge. For example, a gauge indicator could be associated with a hyperlink, or a tooltip of a gauge indicator could change from "Indicator" to "Indicator is Clicked" when the user clicks the indicator.

You specify interactivity properties on one or more shapeAttributes components wrapped in a gauge child shapeAttributesSet component. The interactivity provides a connection between the gauge subcomponent, as specified in the component attribute of a shapeAttributes component, and an HTML attribute or a JavaScript event. Each shapeAttributes component must contain a subcomponent and at least one attribute in order to be functional.

The valid values for gauge subcomponents, as specified in the component attribute of the shapeAttributes component, are:

  • GAUGE_BOTTOMLABEL: the label below the gauge

  • GAUGE_INDICATOR: the indicator in the gauge

  • GAUGE_LEGENDAREA: the legend area of the gauge

  • GAUGE_LEGENDTEXT: the text label of the legend area

  • GAUGE_METRICLABEL: the label showing the metric value

  • GAUGE_TOPLABEL: the label above the gauge

  • GAUGE_PLOTAREA: the area inside the gauge

  • GAUGE_THRESHOLD: the threshold area of the gauge

Interactivity attributes associated with the gauge subcomponent can be any of the following:

  • Behavior attributes: An attribute such as onClick, onMouseMove, onKeyDown, or any attribute with a prefix of on that takes a string containing JavaScript code or a reference to a managed bean method that returns JavaScript code as its value. If the value is a managed bean method, the method takes the subcomponent handle as its input parameter.

  • Common attributes: An HTML attribute such as alt, href, nohref, target, title, and tabindix that takes a string or a managed bean method that returns a string as its value. The value can be a string, or a boolean depending on the attribute. Other attributes control the basic settings of the interactivity, such as clickable, clickAction, and clickListener to control the click events, and id to reference the subcomponent.

For example, Example 23-6 shows the code for a dial gauge where the tooltip of the indicator changes from "Indicator" to "Indicator is Clicked" when the user clicks the indicator, and the tooltip for the gauge metric label displays "Metric Label" when the user mouses over that label at runtime.

Example 23-6 Sample Code for Gauge shapeAttributes Component

<dvt:gauge>
      <dvt:shapeAttributesSet>
         <dvt:shapeAttributes component="GAUGE_INDICATOR" alt="Indicator"
            onClick="document.title="onClick";"/>
         <dvt:shapeAttributes component="GAUGE_METRICLABEL" alt="Metric Label"
            onMouseMove="document.title="onMouseMove";"/>
      </dvt:shapeAttributesSet>
</dvt:gauge>

You can also use a managed bean method to return the value of the interactivity attribute. Example 23-7 shows a managed bean sample code.

Example 23-7 Sample Managed Bean Code

public String alt(oracle.dss.dataView.ComponentHandle handle) { 
     return handle.getName(); } 
     public String onClick(oracle.dss.dataView.ComponentHandle handle) { 
     return ("document.title=\"onClick\";"); } 
     public String onMouseMove(oracle.dss.dataView.ComponentHandle handle) {
     return ("document.title=\"onMouseMove\";"); }

Example 23-8 shows sample code for referencing the managed bean in a shapeAttributes component.

Example 23-8 Gauge shapeAttributes Component Referencing a Managed Bean

<dvt:gauge>
  <dvt:shapeAttributesSet>
    <dvt:shapeAttributes component="GAUGE_INDICATOR" alt="#{sampleGauge.alt}"
                         onClick="#{sampleGauge.onClick}"/>
    <dvt:shapeAttributes component="GAUGE_METRICLABEL"
                         alt="#{sampleGauge.alt}"
                         onMouseMove="#{sampleGauge.onMouseMove}"/>
    </dvt:shapeAttributesSet>
</dvt:gauge>

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You may find it helpful to understand how managed beans are used in JDeveloper. For more information, see Section 3.6, "Creating and Using Managed Beans."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

To add interactivity to a gauge subcomponent:

  1. In the Structure window, right-click the dvt:gauge component, and choose Insert inside dvt:gauge > ADF Data Visualizations > Shape Attributes Set.

  2. Right-click the dvt:shapeAttributesSet component, and choose Insert inside dvt:shapeAttributesSet > Shape Attributes.

  3. In the Property Inspector, expand the Common Section. For the Component attribute, use the dropdown list to select the gauge subcomponent to which you are adding interactivity, for example GAUGE_INDICATOR

  4. Set one or more of the other attributes in this section to specify the interactivity properties for the subcomponent.

    Note:

    You can use the attribute dropdown menu on the attributes in this section to choose a Method Expression Builder dialog when creating a reference to a managed bean. For some attributes you can also choose Edit > Edit Property to select an available managed bean from a dropdown list, or choose New to create a managed bean using the Create Managed Bean dialog.

  5. Expand the Behavior section. Use this section to set one or more of these attributes with a prefix of on that takes a string containing JavasScript code or a reference to a managed bean method that returns JavaScript code as its value.

  6. If you wish to configure additional interactivity effects for a gauge subcomponent, repeat step 2 through step 5 for each subcomponent.

23.6.4 Animating Gauges

You can animate gauges (not gauge sets) upon initial display, or to show changes in data. Animation effects are specified in the gauge's animationOnDisplay and animationOnDataChange properties. For example, a dial gauge indicator can change color at initial display or when a data value increases or decreases. Figure 23-13 shows a dial gauge with the dial indicator animated to display the data change at each threshold level.

Figure 23-13 Animated Dial Gauge

Animated dial gauge.

Animation effects can also be performed using active data. The Active Data Service (ADS) allows you to bind ADF Faces components to an active data source using the ADF model layer. To allow this, you must configure the components and the bindings so that the components can display the data as it is updated in the source.

Alternatively, you can configure the application to poll the data source for changes at prescribed intervals.

23.6.5 How to Specify Animation Effects for Gauges

You can set animation effects for gauges upon initial display, or upon data change associated with partial page rerendering (PPR), or Active Data Service (ADS). For more information about PPR, see Chapter 8, "Rerendering Partial Page Content." For more information about ADS, see Chapter 35, "Using the Active Data Service with an Asynchronous Backend."

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

To specify animation effects for a gauge:

  1. In the Structure window, select the dvt:gauge component.

  2. In the Property Inspector, expand the Appearance section. Use the Animation subsection to set these attributes:

    • AnimationOnDisplay: Use to specify the type of initial rendering effect to apply. Valid values are:

      • NONE (default): Do not show any initial rendering effect.

      • AUTO: Apply an initial rendering effect automatically chosen based on graph or gauge type.

    • AnimationOnDataChange: Use to specify the type of data change animation to apply. Valid values are:

      • NONE: Apply no data change animation effects.

      • AUTO (default): Apply Active Data Service (ADS) data change animation events. For more information about ADS, see Section 23.6.6, "How to Configure Gauges to Display Active Data."

      • ON: Apply partial page refresh (PPR) data change animation events. Use this setting to configure the application to poll the data source for changes at prescribed intervals.

23.6.6 How to Configure Gauges to Display Active Data

Animation effects using Active Data Service (ADS) can be added to dial and status meter gauge types. ADS allows you to bind ADF Faces components to an active data source using the ADF model layer. To allow this, you must configure the components and the bindings so that the components can display the data as it is updated in the data source. For more information about ADS and configuring your application, see Chapter 35, "Using the Active Data Service with an Asynchronous Backend."

You configure a databound gauge to display active data by setting a value on the binding element in the corresponding page definition file.

Before you begin:

You should have a data source that publishes events when data is changed and you should have created business services that react to those events and the associated data controls to represent those services.

To configure a gauge to display active data:

  1. In the Structure window, select the dvt:gauge component.

  2. In the Property Inspector, expand the Common section and enter a unique value for the ID attribute.

    If you do not select an identifier, one will be entered for you.

  3. In the Structure window, right-click the dvt:gauge component, and select Go to Page Definition.

  4. In the Structure window, expand the Bindings folder, and select the node that represents the attribute binding for the component.

  5. In the Property Inspector, expand the Advanced section, and from the ChangeEventPolicy attribute dropdown list, select Push.

23.7 Using Custom Shapes for Gauges

A set of prebuilt custom shapes styles are provided for the gauge component. You can also create and use a graphics file to create a custom shape for a gauge. Set the customShapesPath attribute for the gauge component to use an available custom shapes style, or to point to the vector graphics file that is processed into the graphics used for output.

23.7.1 How to Use Prebuilt Custom Shapes Styles

You can choose from a set of prebuilt custom shapes styles to specify a custom shape for a gauge. The custom shapes styles are:

  • Rounded rectangle

  • Full circle

  • Beveled circle

Figure 23-14 shows a dial gauge displayed with each of the custom shapes styles applied.

Figure 23-14 Dial Gauges with Custom Shapes Styles

Dial gauges with custom shapes

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

To apply a custom shapes style to a gauge:

  1. In the Structure window, right-click the dvt:gauge component and choose Go to Properties.

  2. In the Property Inspector, expand the Appearance section, and select the custom shapes style from the CustomShapesPath attribute dropdown list. Valid values include: Rounded Rectangle, Full Circle, and Beveled Circle.

23.7.2 How to Use a Custom Shapes Graphic File

Due to the requirements for rotating and resizing a gauge's components, such as the plot area or tick marks, a vector graphics file is required when creating a custom shapes graphic file. Scalable Vector Graphics (SVG) is the supported file format for creating custom shapes for gauges.

After designing the gauge and exporting it to an SVG file, a designer can add information to identify, scale, and position the gauge shapes and components, and to specify other metadata used in processing.

In the SVG file, gauge components are identified using an ID. For example, an SVG file with <polygon id="indicator"/> would be interpreted as using a polygon shape for the indicator component. To specify multiple shapes to create the desired visual for a component, the ID can be modified as in id="indicator_0", id="indicator_1", and id="indicator_2".

Table 23-1 shows the gauge component IDs and their descriptions.

Table 23-1 Gauge Component IDs for Custom Shapes

ID Description

indicator

Points to the value represented by the gauge. If not specified, the gauge will use the indicator specified in the application.

For the dial gauge, the indicator must be specified while pointing up (90 degrees), so that the shape can be properly rotated.

For the status meter gauge, the indicator should be specified with its full extent, and the gauge will be cropped to point to the metric value.

indicatorBase

For a dial gauge, refers to the object that appears at the base of the indicator component. If specified, and the indicatorCenter is not, then the center of the indicatorBase will be taken as the indicatorCenter.

gaugeFrame

Refers to the optional component that adds visual distinction to the plotArea. It can be turned on or off in the application by setting the rendered property. Used primarily when the user wants to use the default gauge plotArea. If no plotArea is specified, then the gauge will insert the default plotArea within the plotAreaBounds. This provides a quick way to change the look of the gauge without having to create a custom plotArea or tickMark.

lowerLabelFrame

Refers to the frame that contains the bottomLabel when its position is LP_BELOW_GAUGE; allows the user to customize the look of this frame. The gauge will position the lowerLabelFrame in the same relative position to other gauge components when it is found in the custom shapes file.

plotArea

For the dial gauge, refers to the circular area within which the indicator moves.

For the status meter gauge, refers to the area that contains the indicator.

For the LED gauge, refers to the area that contains any graphics that will not be filled with the LED fill color.

When a plotArea is not specified, the gauge will draw the default plotArea. For tick marks to be drawn, a specification of the plotArea also requires either tickMarkPath or a set of tick marks.

tickMark

Used to define increments on the gauge. When a set of tick marks is specified with no tickMarkPath, the gauge will use the tick marks exactly where they appear on the plotArea. In this case, it is up to the user to ensure that the tick marks appear at equal increments. If a tickMarkPath is specified, the gauge will accept a single tickMark, at 90 degrees for the dial, and it will rotate and position the tickMark along the tickMarkPath.

upperLabelFrame

Refers to the frame that contains the topLabel when its position is LP_ABOVE_GAUGE. Setting the upperLabelFrame allows the user to customize the look of this frame. The gauge will position the upperLabelFrame in the same relative position to other gauge components when it is found in the custom shapes file.

Table 23-2 shows the metadata IDs and the descriptions used for internal calculations, not rendered in the gauge.

Table 23-2 Metadata IDs for Custom Shapes

ID Description

indicatorBarBounds

Specifies the box containing the minimum and maximum extent of the indicator bar. If not specified, the bounding box is taken to be the entire indicator as specified in the input file.

indicatorCenter

Specifies the center of rotation for the indicator that rotates around in a dial gauge. The center of the shape with this ID is considered to be the indicator center. If not specified, it is assumed to be the center of the bottom edge of the plot area for an 180-degree dial gauge, and the center of the plot area for an N-degree dial gauge.

ledFillArea

Specifies the area of the LED gauge that should be filled with the appropriate threshold color. If not specified, then the entire plotArea shape specified in the graphics file will be filled with the threshold color.

lowerLabelFrameTextBox

For complex lowerLabelFrame shapes, specifies a rectangle that can be set as the lowerLabelFrameTextBox. This box determines the position of the bottom label within the lowerLabelFrame.

plotAreaBounds

Specified the bounding box for the plotArea. If no plotArea has been specified in this file, then a bounding box is needed for the gauge to draw the plot area of the gauge. If not specified, then the gaugeFrame will use its own bounding box for this purpose.

thresholdFillArea

Defines the area that will be filled with the threshold colors.

For a dial gauge, specifies the thresholdFillArea that will be filled by sweeping an arc from the indicatorCenter.

For a status meter gauge, specifies the thresholdFillArea that will be filled based on the orientation of the status meter gauge.

tickMarkPath

Defines the path in which to draw tick marks. This is necessary for the gauge to calculate where tick marks should be drawn on a custom plot area, and the gauge will be unable to change the majorTickCount if this is not specified.

upperLabelFrameTextBox

For complex upperLabelFrame shapes, specifies a rectangle that can be set as the upperLabelFrameTextBox. This box determines the position of the topLabel within the upperLabelFrame.

Example 23-9 shows a sample SVG file used to specify custom shapes for the components of a gauge.

Example 23-9 Sample SVG File Used for Gauge Custom Shapes

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns:svg="http://www.w3.org/2000/svg"
   xmlns="http://www.w3.org/2000/svg"
   version="1.0">
    <rect width="264.72726" height="179.18887" rx="8.2879562" 
       ry="10.368411" x="152.76225" y="202.13995" 
       style="fill:#c83737;fill-opacity:1;stroke:none"
       id="gaugeFrame"/>
    <rect width="263.09058" height="42.581127" rx="3.0565372"
       ry="3.414634" x="155.11697" y="392.35468"
       fill="#c83737"
       id="lowerLabelFrame" />
    <rect width="241.79999" height="120.13961"
       x="164.2415" y="215.94714"
       style="fill:#ffeeaa"
       id="plotAreaBounds"/>
    <rect width="74.516975" height="44.101883"
       rx="2.6630435" ry="3.5365853"
       x="247.883" y="325.4415"
       style="fill:#ffd5d5;fill-opacity:1;stroke:none"
       id="indicatorBase"/>
    <rect width="6.0830183" height="98.849045" rx="2.6630435"
       ry="2.2987804" x="282.86035" y="237.23772"
       style="fill:#00aa00;fill-opacity:1;stroke:none"
       id="indicator"/>
</svg>

Before you begin:

It may be helpful to have an understanding of how gauge attributes and gauge child tags can affect functionality. For more information, see Section 23.2.1, "Configuring Gauges."

You should already have a gauge on your page. If you do not, follow the instructions in this chapter to create a gauge set. For information, see Section 23.2.2, "How to Add a Gauge to a Page."

To use a custom shapes graphics file for a gauge:

  1. In the Structure window, right-click the dvt:gauge component and choose Go to Properties.

  2. In the Property Inspector, expand the Appearance section, and in the CustomShapesPath attribute field, enter the path to the SVG file to be used to specify the custom shapes for your gauge. For example:

    /path/customShapesFile.svg

23.7.3 What You May Need to Know About Supported SVG Features

The custom shapes available to you support the following SVG features:

  • Transformations

  • Paths

  • Basic shapes

  • Fill and stroke painting

  • Linear and radial gradients

SVG features that are not supported by custom shapes include:

  • Unit Identifiers: All coordinates and lengths should be specified without the unit identifiers, and are assumed to be in pixels. The parser does not support unit identifiers, because the size of certain units can vary based on the display used. For example, an inch may correspond to different numbers of pixels on different displays. The only exceptions to this are gradient coordinates, which can be specified as percentages.

  • Text: All text on the gauge is considered data, and should be specified through the tags or data binding.

  • Specifying Paint: The supported options are none, 6-digit hexadecimal, and a <uri> reference to a gradient.

  • Fill Properties: The fill-rule attribute is not supported.

  • Stroke Properties: The stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-disarray, and stroke-opacity attributes are not supported.

  • Linear Gradients and Radial Gradients: The gradientUnits, gradientTransform, spreadMethod, and xlink:href are not supported. Additionally, the r, fx, and fy attributes on the radial gradient are not supported.

  • Elliptical Arc Out-of-Range Parameters: If rx, ry, and x-axis-rot are too small such that there is no solution, the ellipse should be scaled uniformly until there is exactly one solution. The SVG parser will not support this.

  • General Error Conditions: The SVG input is expected to be well formed and without errors. The SVG parser will not perform any error checking or error recovery for incorrectly formed files, and it will stop parsing when it encounters an error in the file.