25 Using Gauge Components

This chapter describes how to use the ADF Data Visualization dial, LED, rating, and status meter gauge components using simple UI-first development. The chapter defines the data requirements, tag structure, and options for customizing the look and behavior of the components.

If your application uses the Fusion technology stack, you can use data controls to create gauges. For more information, see "Creating Databound Gauges" in Developing Fusion Web Applications with Oracle Application Development Framework.

This chapter includes the following sections:

25.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 charts.

Using thresholds, 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.

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, LED, rating, and status meter.

25.1.1 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: Displays a metric value plotted on a circular axis. The gauge's background attribute determines whether the gauge's background is displayed as a rectangle, circle, or semicircle. An indicator points to the dial gauge's metric value on the axis.

    Figure 25-1 shows three dial gauges with backgrounds set to full circle, partial circle, and rectangle. In all three examples, the gauge's metric value is 63.

    Figure 25-1 Dial Gauge Examples

    This image is described in the surrounding text

  • LED: Graphically depicts a measurement, such as a key performance indicator (KPI). Several styles of shapes are available for LED gauges, including round or rectangular shapes that use color to indicate status, and triangles or arrows that point up, left, right, or down indicate good (up), fair (left- or right-pointing), or poor (down) states in addition to the color indicator. A human shape is also available.

    Figure 25-2 shows LED gauges configured with a variety of shapes, sizes, and thresholds.

    Figure 25-2 LED Gauge Examples

    This image is described in the surrounding text

  • Rating: Displays and optionally accepts input for a metric value. This gauge is typically used to show ratings for products or services, such as the star rating for a movie.

    Figure 25-3 shows six rating gauges configured with star, circle, diamond, rectangle, triangle, and human shapes. Rating gauges may be changed to have either a horizontal or vertical orientation.

    Figure 25-3 Rating Gauge Examples

    This image is described in the surrounding text

  • Status Meter: Displays the metric value on a horizontal, circular or vertical axis. An inner rectangle shows the current level of a measurement against the ranges marked on an outer rectangle. Optionally, status meters can display colors to indicate where the metric value falls within predefined thresholds.

    Figure 25-4 shows examples of status meter gauges configured as horizontal, circular and vertical status meters. The gauges are configured to use thresholds that display color to indicate whether the gauge's value falls within an acceptable range.

    Figure 25-4 Status Meter Gauge Examples

    This image is described in the surrounding text.

    The figure shows an example of a circular status meter gauge configured to display a portion of the plot area. This is useful to depict key performance indicators (KPI) in a functional and visually intriguing manner.

    This image is described in the surrounding text.

25.1.2 End User and Presentation Features of Gauge Components

ADF Data Visualization gauge components provide a range of presentation features, such as shape variations, threshold display, visual effects, animation, and customizable color and label styles.

The gauge components also support interactivity features such as popup and context menus. All gauges also include value change support, which allows the user to change the gauge's metric value.

25.1.2.1 Gauge Shape Variations

Gauge shapes are configurable and vary by gauge type.

  • Dial gauges: The background attribute sets shape and shading. Figure 25-5 shows the backgrounds available for dial gauges, which include the circle, dome, and rectangular shapes with alta, antique, dark, or light shading.

    Figure 25-5 Dial Gauge Backgrounds

    This image is described in the surrounding text

  • LED gauge: The type attribute sets the LED gauge's shape. Figure 25-6 shows the types available for the LED gauge, which include circle, rectangle, arrow, triangle, diamond, and star.

    Figure 25-6 LED Gauge Types

    This image is described in the surrounding text

  • Status meter gauge: The orientation attribute determines whether the status meter is displayed along a horizontal, a circular, or a vertical axis. Figure 25-4 shows status meter gauges configured as horizontal bars, circles and vertical bars.

  • Rating gauge: The rating gauge's shape attribute determines the rating gauge's shape. Figure 25-3 shows the shapes available for the rating gauge, which include the star, diamond, circle, rectangle, and triangle shapes.

25.1.2.2 Gauge Thresholds

Gauge thresholds contain values that represent the upper bound of a range on the status meter or LED gauge. Typically, thresholds are defined to indicate whether a gauge's metric value falls within an acceptable range.

Figure 25-7 shows three each of horizontal, circular and vertical status meter gauges, each configured to show a red indicator when the gauge's metric value is at or below 30, a yellow indicator when the metric value is at or below 60, and a green indicator when the metric value is greater than 60.

Figure 25-7 Status Meter Gauge Thresholds

This image is described in the surrounding text

Figure 25-8 shows three LED gauges, each configured to display its shape in red when the gauge's metric value is at or below 30, in yellow when the metric value is at or below 60, and in green when the metric value is greater than 60.

Figure 25-8 LED Gauge Thresholds

This image is described in the surrounding text

25.1.2.3 Gauge Visual Effects

By default, gauges apply gradients and overlays to color display. You can disable visual effects to achieve a flatter design.

The second row in Figure 25-9 shows the result of disabling visual effects on the three LED gauges in Figure 25-8.

Figure 25-9 LED Gauges Showing Enabled and Disabled Visual Effects

This image is described in the surrounding text

25.1.2.4 Active Data Support (ADS)

Gauges support ADS by sending a Partial Page Refresh (PPR) request when an active data event is received. The PPR response updates the components, animating the changes as needed. Supported ADS events include updates to the value, minimum, and maximum gauge attributes.

Note:

EL Operators are not supported within the EL Expressions for active attributes.

For additional information about using the Active Data Service, see Using the Active Data Service with an Asynchronous Backend.

25.1.2.5 Gauge Animation

Gauges support animation on initial display or data change using the af:transition child tag.

25.1.2.6 Gauge Tooltips

You can configure a tooltip of contextual information to display when a user moves a cursor over the gauge. This is done using the shortDesc attribute.

Figure 25-10 shows the tooltip for a dial gauge.

Figure 25-10 Circular Status Meter Gauge Displaying a Tooltip

This image is described in the surrounding text.

25.1.2.7 Gauge Popups and Context Menus

You can configure gauges to display popups or context menus using the af:showPopupBehavior tag.

Figure 25-11 shows a circular status meter gauge configured to show a popup when the user clicks the gauge. The popup displays an output message in a note window.

Figure 25-11 Status Meter Gauge Displaying a Popup

This image is described in the surrounding text

Figure 25-12 shows a circular status meter gauge configured to show a context menu when the user right-clicks the gauge. The context menu displays an output message in a note window.

Figure 25-12 Status Meter Gauge Displaying a Context Menu

This image is described in the surrounding text

25.1.2.8 Gauge Value Change Support

You can configure gauges to accept input from the user to change the metric value. For example, you could configure a rating gauge that allows the user to assign the number of stars to a movie rating.

Figure 25-13 shows an example of a rating gauge configured to accept user input. The gauge's initial metric value is 1. As the user glides the mouse over the stars, the color changes to indicate the number of selected stars. To effect the change, the user clicks the highlighted star with the largest desired value.

Figure 25-13 Rating Gauge Illustrating Value Change Support

This image is described in the surrounding text

25.1.2.9 Gauge Reference Lines (Status Meter Gauges)

You can configure status meter gauges to display a reference line. Reference lines can be used in conjunction with thresholds to display trend information, such as the previous value, and target information at the same time.

Figure 25-14 shows a horizontal, a circular, and a vertical status meter gauge configured to show reference lines. Each gauge is configured to show one black reference line with its value set to 65.

Figure 25-14 Status Meter Gauges Displaying Reference Lines

This image is described in the surrounding text

25.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 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 Allowing User Customization on JSF Pages.

  • Accessibility: You can make your gauge components accessible. For more information, see 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 Customizing the Appearance Using Styles and Skins.

  • Touch devices: When you know that your ADF Faces application will be run on touch devices, the best practice is to create pages specific for that device. For additional information, see Creating Web Applications for Touch Devices Using ADF Faces.

  • 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 "Creating Databound Gauges" in Developing Fusion Web Applications with 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 "Designing a Page Using Placeholder Data Controls" in Developing Fusion Web Applications with 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 Common Functionality in Data Visualization Components.

25.2 Using the Gauge Component

To use the Gauge component, add the gauge to a page using the Component Palette window. Then define the data for the gauge and complete the additional configuration in JDeveloper using the tag attributes in the Properties window.

25.2.1 Gauge Component Data Requirements

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 Value attribute in the Properties window. It can also be specified through data controls. This is the only required data for a gauge.

  • 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 Minimum and Maximum fields in the Properties window for the gauge.

    The default minimum value for all gauges is 0. The default maximum value for dial, LED, and status meters gauges is 100, and the default maximum value for rating gauges is 5. You must change this value if your gauge's metric exceeds the maximum value for your gauge to display properly.

  • Thresholds: 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 Properties window. For more information, see How to Configure Gauge Thresholds.

25.2.2 How to Add a Gauge to a Page

When you are designing your page using simple UI-first development, you use the Components window to add a gauge to a JSF page. When you drag and drop a gauge component onto the page, a Create Gauge dialog displays available categories of gauge types, with descriptions, to provide visual assistance when creating gauges. Figure 25-15 shows the Create Horizontal Status Meter Gauge dialog.

Figure 25-15 Create Gauge Dialog for Horizontal Status Meter

This image is described in the surrounding text

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

In the Properties window you can click the icon that appears when you hover over the property field to display a property description or edit options. Figure 25-16 shows the Property menu for a gauge component value attribute.

Figure 25-16 Gauge Value Attribute in Properties Window

This image is described in the surrounding text

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 "Creating Databound Gauges" in Developing Fusion Web Applications with 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 Configuring Gauges.

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

You must complete the following tasks:

  1. Create an application workspace as described in Creating an Application Workspace.

  2. Create a view page as described in Creating a View Page.

To add a gauge to a page:

  1. In the ADF Data Visualizations page of the Components window, from the Gauge panel, drag and drop the desired gauge onto the page to open the Create Gauge dialog.
  2. In the Create Gauge dialog, click OK to add the gauge to the page.
  3. In the Properties window, view the attributes for the gauge. Use the Component Help button to display the complete tag documentation for the gauge component.

25.2.3 What Happens When You Add a Gauge to a Page

JDeveloper generates only a minimal set of tags when you drag and drop a gauge from the Components window onto a JSF page.

For all gauges but the rating gauge, JDeveloper adds the dvt:gaugeMetricLabel tag to the page. For the status meter and LED gauges which support thresholds, JDeveloper adds one dvt:gaugeThreshold tag representing the maximum bound of the gauge.

The example below shows the default code that JDeveloper adds to the page for a dial, LED, status meter, and rating gauge. In this example, each gauge is contained in a grid cell of the af:panelGridLayout component. The gauge-related tags are highlighted in bold.

<af:panelGridLayout id="pgl1">
  <af:gridRow marginTop="5px" height="auto" id="gr1">
    <af:gridCell marginStart="5px" width="50%" id="gc1">
      <dvt:dialGauge id="dialGauge1">
        <dvt:gaugeMetricLabel rendered="true" id="gml1"/>
      </dvt:dialGauge>
    </af:gridCell>
    <af:gridCell marginStart="5px" width="50%" id="gc2">
      <dvt:ledGauge id="ledGauge1">
        <dvt:gaugeThreshold id="thr1" color="#d62800"/>
        <dvt:gaugeMetricLabel rendered="true" id="gml2"/>
      </dvt:ledGauge>
    </af:gridCell>
  </af:gridRow>
  <af:gridRow marginTop="5px" height="auto" marginBottom="5px" id="gr2">
    <af:gridCell marginStart="5px" width="50%" id="gc4">
      <dvt:statusMeterGauge id="statusMeterGauge1">
        <dvt:gaugeThreshold id="thr3" color="#d62800"/>
          <dvt:gaugeMetricLabel rendered="true" id="gml3"/>
        </dvt:statusMeterGauge>
    </af:gridCell>
    <af:gridCell marginStart="5px" width="50%" marginEnd="5px" id="gc6">
      <dvt:ratingGauge id="ratingGauge1"/>
    </af:gridCell>
  </af:gridRow>
</af:panelGridLayout>

For information about the panel grid layout component, see How to Use the panelGridLayout, gridRow, and gridCell Components to Create a Grid-Based Layout.

25.2.4 How to Add Data to Gauges

A gauge's metric value is the only required value for a gauge, and you specify this value in the gauge's value attribute. You can specify the value for the value attribute as a static numeric value in the Properties window, in a managed bean that returns the gauge's numeric value, or by binding a data control to a gauge.

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

To add data to a gauge:

  1. Optionally, create the managed bean that will return the gauge's metric value.

    If you need help creating classes, see "Working with Java Code" in Developing Applications with Oracle JDeveloper. For help with managed beans, see Creating and Using Managed Beans.

  2. In the Structure window, right-click the dvt:typeGauge node and choose Go To Properties.
  3. In the Properties window, do one of the following:

    • To add data to the gauge statically or to reference a managed bean that returns the gauge's metric value, expand the Common section and specify the metric value in the Value field.

      You can enter a static numeric value or specify an EL expression that references the managed bean and metric value.

      For example, to specify an EL expression for a managed bean named gauge that returns the gauge's metric value in a method named getGaugeMetric(), enter the following in the Value field: #{gauge.gaugeMetric}.

      For help with creating EL expressions, see How to Create an EL Expression.

    • To bind the gauge to a data control, click Bind to ADF Control to select a data collection.

      For more information about using data controls to supply data to your gauge, see "Creating Databound Gauges" in Developing Fusion Web Applications with Oracle Application Development Framework.

  4. If needed, in the Properties window, expand the Appearance section and enter values for the Minimum and Maximum fields.

    You can enter a static numeric value or specify an EL expression that references a managed bean and minimum or maximum value.

    Note:

    If your gauge's metric value exceeds the default maximum value for the gauge, you must change the maximum value or your gauge will not display properly.

If you want your LED or status meter gauge to display thresholds for predefined ranges, add a dvt:gaugeThreshold tag for each threshold. For additional information, see How to Configure Gauge Thresholds.

25.2.5 Configuring Gauges

The properties for the gauge component are sufficient to produce a gauge, but you can modify the gauge properties to customize the display and behavior of the gauge. You can also add and configure child components or supported facets to customize the display and behavior of the gauge. The prefix dvt: occurs at the beginning of each gauge component name indicating that the component belongs to the Tag Reference for Oracle ADF Faces Data Visualization Tools tag library.

Configurable elements vary by gauge type. Some elements are available to all or more than one gauge type and include:

  • minimum and maximum: Attributes that specify the minimum and maximum values for the gauge.

  • inlineStyle: Attribute that specifies the style of the outer element (enclosing div) of the component.

  • shortDesc: Attribute that specifies the short description of this component. This is used to customize the tooltip text that appears when the user hovers the mouse over the gauge.

  • visualEffects: Attribute that specifies whether gradients and overlays are displayed. By default, this is set to auto, but you can also set this to none to turn off visual effects.

  • styleClass: Attribute that sets a CSS style class to use for this component.

  • gaugeMetricLabel: Child component that determines the metric label's style, visibility, scaling, and text type. This attribute is not available on the rating gauge which uses the number of shapes as its metric value.

  • readOnly: Attribute on dial, rating, and status meter gauges that determines whether the user can change the gauge's metric value.

  • gaugeThreshold: Child component that specifies a threshold for LED or status meter gauges.

  • borderColor: Attribute that specifies the border color of the LED or status meter gauge's indicator.

  • color: Attribute that specifies the fill color of the LED or status meter gauge's indicator.

  • orientation: Attribute that determines the shape direction of rating or status meter gauges. This specifies whether rating gauges are rendered vertically or horizontally, and whether status meter gauges are rendered vertically, horizontally, or in a circular manner.

  • title: Attribute that accepts a string value and defines the title for LED and status meter gauges.

  • titleStyle: Attribute that determines the styling options on the string value set in the title attribute.

You can view a complete list of gauge tags and supported child components by clicking Component Help in the Properties window for the gauge.

25.2.5.1 Configuring Dial Gauges

Configurable elements specific to dial gauges include:

  • background: Attribute that determines the shape and background style of the dial gauge.

  • indicator: Attribute that specifies the indicator style for the dial gauge.

  • gaugeTickLabel: Child component that determines the tick label's style, visibility, scaling, and text type.

25.2.5.2 Configuring LED Gauges

Configurable elements specific to LED gauges include:

  • type: Attribute that specifies the shape of the LED gauge.

  • size: Attribute that determines the relative size of the LED gauge.

  • rotation: Attribute that specifies the rotation of LED gauges configured to use arrow or triangle shapes.

25.2.5.3 Configuring Rating Gauges

Configurable elements specific to rating gauges include:

  • shape: Attribute that determines the shape of the rating gauge increments.

  • inputIncrement: Attribute that specifies the change increment when users edit the metric value.

  • unselectedShape: Attribute that determines the shape of gauge increments that are not selected.

  • changedStyle: Attribute that determines the color and border color of selected gauge increments after a change in value has been made.

  • selectedStyle: Attribute that determines the color and border color of gauge increments that have been selected.

  • unselectedStyle: Attribute that determines the color and border color of gauge increments that are not selected.

  • hoverStyle: Attribute that controls the color and border color of gauge increments that are hovered on but not yet selected.

25.2.5.4 Configuring Status Meter Gauges

Configurable elements specific to status meter gauges include:

  • indicatorSize: Attribute that determines the size of the indicator, relative to the plot area. Accepts a positive numeric value.

  • borderRadius: Attribute that determines the degree of curvature of the corners of the indicator. Accepts a positive pixel value.

  • plotArea: Attribute that determines whether or not the plot area is displayed.

  • plotAreaBorderRadius: Attribute that determines the degree of curvature of the corners of the plot area. Accepts a positive pixel value. If this value isn’t specified, the borderRadius attribute applies to both the indicator and the plot area.

  • plotAreaColor: Attribute that determines the color of the plot area. Accepts a color value or hex code.

  • plotAreaBorderColor: Attribute that determines the color of the plot area border. Accepts a color value or hex code.

  • thresholdDisplay: Attribute that determines how thresholds are displayed.

  • titlePosition: Attribute that controls the placement of the string value defined in the title attribute. Accepts the values auto, center, and start.

There are configurable elements specific to circular status meter gauges which are ignored by other status meter gauges. These include:

  • innerRadius: Attribute that determines the radius of an inner circle in the gauge. Accepts a value between 0 and 1.

  • startAngle: Attribute that determines the angle at which the indicator starts being drawn in a clockwise manner (and counterclockwise for BiDi locales). Accepts a value between 0 and 360.

  • angleExtent: Attribute that determines the extent to which the plot area is drawn. The plot area is drawn starting at the startAngle and ending after the full angle extent is drawn. Accepts a value between 0 and 360.

25.3 Customizing Gauge Display Elements

Gauges provide a number of useful customizations for display elements, including thresholds, styles, numeric data values, visual effects, animation, and reference lines.

25.3.1 How to Configure Gauge Thresholds

Thresholds are numerical data values in status meter or LED gauges that highlight a particular range of values. Thresholds must be values between the minimum and the maximum value for a gauge.

On status meter gauges, the range identified by a threshold is filled with a color that is different than the color of other ranges. The threshold can be displayed on the indicator or the plot area.

Figure 25-17 shows horizontal, circular, and vertical status meters configured for thresholds. The gauges in the first row are configured to show the threshold on the indicator. In the second row, the gauges are configured to display the current threshold on the plot area. In the third row, the gauges are configured to display all thresholds on the plot area.

Figure 25-17 Status Meter Gauge Threshold Display Options

This image is described in the surrounding text

On LED gauges, the background is filled with the color defined for the threshold range containing the metric value. Figure 25-18 shows three LED gauges configured with thresholds using the same maximum bound and color values as the status meters shown in Figure 25-17.

Figure 25-18 LED Gauges Configured with Three Thresholds

This image is described in the surrounding text

When you create a status meter or LED gauge by dragging the gauge to the page from the Components window, JDeveloper adds one dvt:gaugeThreshold tag as a child of the gauge. You can add additional thresholds by inserting additional dvt:gaugeThreshold tags and defining the threshold's value and color attributes.

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 "Creating Databound Gauges" in Developing Fusion Web Applications with Oracle Application Development Framework.

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

To configure status meter or LED gauge thresholds:

  1. In the Structure window, right-click the dvt:statusMeterGauge or dvt:LEDGauge component and choose Insert Inside (Status Meter or LED) Gauge > Threshold.

    Depending upon how you created the gauge, you may already have one dvt:gaugeThreshold component defined and can proceed to the next step for that threshold.

  2. Right-click the dvt:gaugeThreshold node and choose Go to Properties.

  3. In the Properties window, set values for the following:

    • Maximum: Specify the maximum bound for the threshold. You can enter an integer value or use the dropdown menu to choose Expression Builder to enter an EL Expression that represents the maximum bound.

      You do not need to enter a value for the threshold representing the maximum bound for the gauge. This value is automatically derived from the value in the gauge's maximum attribute.

    • Color: Specify the RGB value in hexadecimal notation or choose Expression Builder from the attribute's dropdown menu to enter an expression that evaluates to the RGB value.

      For example, enter #0000FF to render the threshold in blue.

    • BorderColor: Specify the RGB value in hexadecimal notation or choose Expression Builder from the attribute's dropdown menu to enter an expression that evaluates to the RGB value.

      For example, enter #000000 to render the threshold's border color in black.

    • ShortDesc: Specify the custom hover text for the threshold in plain text or choose Expression Builder from the attribute's dropdown menu to enter an EL expression that contains the text value.

  4. Repeat Step 1 through Step 3 for each threshold that you want to configure.

  5. For status meter gauges, set the following attributes to customize the threshold display.

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

    2. In the Properties window, in the ThresholdDisplay field, use the dropdown menu to customize the placement and appearance of the threshold.

      By default, the threshold is displayed on the indicator. If you want the current threshold displayed on the plot area, choose currentOnly. To display all thresholds on the plot area, choose all.

    3. In the PlotArea field, use the dropdown menu to turn the plot area display on or off.

      By default, PlotArea is set to auto which will show the plot area when thresholds are configure and ThresholdDisplay is set to currentOnly or all. You can also set this to on or off.

    4. In the Indicator field, enter any positive value to change the relative size of the indicator.

      For example, to set the indicator to consume 50% of the plot area, enter 0.5, or to make the indicator twice as large as the plot area, enter 2.Figure 25-19 shows the effect of changing the indicator size to 0.5.

      Figure 25-19 Status Meter Gauge Indicator Size Set to 0.5

      This image is described in the surrounding text

25.3.2 Formatting Gauge Style Elements

You can customize the styling of gauges to change the initial size of a gauge and apply style elements to labels and other presentation features.

25.3.2.1 How to Change Gauge Size and Apply CSS Styles

You can customize the width and height of a gauge by applying a CSS style or specifying a value in the gauge's inlineStyle attribute.

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

To specify the size of or apply CSS styles to a gauge:

  1. In the Structure window, right-click the gauge component and choose Go to Properties.
  2. To specify size: In the Properties window, expand the Style section. Specify the initial size of the gauge in the InlineStyle attribute. You can specify a fixed size or specify 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. To apply CSS styles: In the Properties window, expand the Style section and enter the name of the style class in the StyleClass field.

    For example, to set the width of the gauge to fill 100% of its container's width, use the following setting for the StyleClass attribute:

    AFStretchWidth

    For information about applying CSS styles, see Customizing the Appearance Using Styles and Skins.

25.3.2.2 How to Format Gauge Text

You can format the text in the following gauge child components:

  • gaugeMetricLabel

  • gaugeTickLabel

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

To format gauge text:

  1. In the Structure window, right-click dvt:gaugeMetricLabel or dvt:gaugeTickLabel and choose Go to Properties.
  2. In the Properties window, enter a value for LabelStyle.

    This property accepts font-related CSS attributes such as font-weight and font-size. For example, to set the label to bold, enter the following for LabelStyle:

    font-weight:bold;
  3. For status meter gauges, in the Properties window, select a value for Position.
    This property controls the position of the label on the gauge. Possible options are: auto, center, insideIndicatorEdge, outsideIndicatorEdge, outsidePlotArea, and withTitle. auto will default to outsidePlotArea for horizontal/vertical and center for circular status meter gauges.

You can also set the style 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 styles 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 What You May Need to Know About Skinning and Formatting Gauge Style Elements.

25.3.2.3 What You May Need to Know About Skinning and Formatting Gauge Style Elements

You can set the font and other style 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 styles 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.

You can use the ADF Data Visualization Tools Skin Selectors to define the styles for gauge components. Gauge component skin selectors that support styling include the following:

  • af|dvt-dialGauge

  • af|dvt-ledGauge

  • af|dvt-ratingGauge

  • af|dvt-ratingGauge::selected-shape

  • af|dvt-ratingGauge::unselected-shape

  • af|dvt-ratingGauge::hover-shape

  • af|dvt-ratingGauge::changed-shape

  • af|dvt-statusMeterGauge

  • af|dvt-gaugeMetricLabel

  • af|dvt-gaugeTickLabel

  • af|dvt-gaugeThreshold

  • af|dvt-gaugeThreshold::index$

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

To use a custom skin to set gauge styles:

  1. Add a custom skin to your application containing the defined skin style selectors for the gauge subcomponents.

    For example, specify the font family for all gauge metric labels in a mySkin.css file as follows:

    af|dvt-gaugeMetricLabel
{
  font-weight:bold;
}

    For help with creating a custom skin, see the "Creating an ADF Skin File" section in Developing ADF Skins.

  2. Configure the application to use the custom skin in the trinidad-config.xml file.

    For help with configuring the application, see the "Applying the Finished ADF Skin to Your Web Application" chapter of Developing ADF Skins.

For additional information about using styles and skins, see Customizing the Appearance Using Styles and Skins.

25.3.3 How to Format Numeric Data Values in Gauges

You can use the gauge's gaugeMetricLabel child component to format the appearance of the gauge's metric value in dial, LED, and status meter gauges. You can also format the appearance of dial gauge tick labels using the gaugeTickLabel child tag. Each component has a textType attribute that lets you specify whether you want to display the metric value itself or a percentage that the value represents.

In some cases, this might be sufficient numeric formatting, but you can use properties on the component to change scaling.

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.

You may also specify a custom label using the text attribute, in which case the textType attribute will be ignored.

Before you begin:

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

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

Add a dial, LED, or status meter gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

To format numeric values in a gauge:

  1. If you are formatting a dial gauge's tick label, in the Structure window, right-click the dvt:dialGauge component and choose Insert Inside Dial Gauge > Gauge Tick Label.

  2. In the Structure window, right-click the dvt:gaugeMetricLabel or dvt:gaugeTickLabel node and choose Go to Properties.

  3. In the Properties window, set values for the following:

    • Scaling: Use the attribute's dropdown list to change the default scaling from auto. You can select one of the available scaling options or none to turn off scaling.

    • TextType: Use the attribute's dropdown list to change the default text type from number to percent.

  4. 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:gaugeMetricLabel or dvt:gaugeTickLabel node and choose Insert Inside (Gauge Metric Label or Gauge Tick Label) > Convert Number.

    2. Right-click the af:convertNumber node and choose Go to Properties.

    3. In the Properties window, specify values for the attributes of the af:convertNumber component to produce additional formatting. Click Help or press F1 to display the complete tag documentation for the af:convertNumber component.

  5. Alternatively, you can specify a custom label. In the Properties window of the dvt:gaugeMetricLabel node, specify a value for the Text attribute. If the Text attribute is specified, the TextType attribute will be ignored.

25.3.4 How to Disable Gauge Visual Effects

By default, gauges are displayed with gradient coloring and overlays as shown in Figure 25-9. To disable these visual effects, set the gauge's visualEffects attribute to none.

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

To disable visual effects on a gauge:

  1. In the Structure window, right-click the dvt:typeGauge component and choose Go to Properties.
  2. In the Properties window, expand the Appearance section, and from the VisualEffects attribute's dropdown list, select none.

25.3.5 How to Configure Gauge Animation

To configure gauge animation, add the af:transition tag as a child of the gauge component and configure the trigger type and transition effect.

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

To configure gauge animation:

  1. In the Structure window, click the gauge component.
  2. In the Source editor, add the af:transition tag as a child of the highlighted gauge component as shown in the following example. 
    <af:transition triggerType="display" transition="auto"/>

25.3.6 How to Configure Status Meter Gauge Reference Lines

You can add reference lines to status meter gauges at specified values on the gauge's axis. To configure reference lines, add the dvt:referenceLine component to the status meter gauge and configure as needed.

The example below shows the code on the JSF page that creates the gauge and reference lines in Figure 25-14.

<af:panelGroupLayout id="pgl1" layout="horizontal">
  <af:spacer width="5" id="s1"/>
  <dvt:statusMeterGauge value="90" indicatorSize="0.5" plotArea="on" id="smg1">
    <dvt:referenceLine color="#FFFFFF" value="75" id="rl1"/>
    <dvt:referenceLine color="#000000" value="95" id="rl2"/>
    <dvt:gaugeThreshold maximum="33" id="gt1"/>
    <dvt:gaugeThreshold maximum="67" id="gt2"/>
    <dvt:gaugeThreshold id="gt3"/>
  </dvt:statusMeterGauge>
  <af:spacer width="25" id="s2"/>
  <dvt:statusMeterGauge inlineStyle="width:50px;height:50px;"
                        orientation="circular" value="90" id="smg2">
    <dvt:referenceLine color="#FFFFFF" value="75" id="rl3"/>
    <dvt:referenceLine color="#000000" value="95" id="rl4"/>
    <dvt:gaugeThreshold maximum="33" id="gt4"/>
    <dvt:gaugeThreshold maximum="67" id="gt5"/>
    <dvt:gaugeThreshold id="gt6"/>
  </dvt:statusMeterGauge>
</af:panelGroupLayout>

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

To add a reference line to a status meter gauge:

  1. In the Structure window, right-click the dvt:statusMeterGauge and choose Insert Inside Status Meter Gauge > Reference Line.
  2. Right-click the dvt:referenceLine node and choose Go to Properties.
  3. In the Properties window, enter values for the following:

    • Value: Specify the value for the reference line or choose Expression Builder from the attribute's dropdown menu to enter an expression that evaluates to the value.

    • Color: Specify the RGB value in hexadecimal notation or choose Expression Builder from the attribute's dropdown menu to enter an expression that evaluates to the RGB value.

      For example, to render the reference line in white, enter #000000.

    • LineStyle: Use the attribute's dropdown list to change the line from solid to dashed or dotted.

    • LineWidth: Specify the width of the line.

25.4 Adding Interactivity to Gauges

Gauges can be made more interactive and user-friendly by adding tooltips, popups, context menus, and value change support.

25.4.1 How to Configure Gauge Tooltips

You configure a gauge tooltip by setting a value for the gauge's shortDesc attribute. You may also configure a custom tooltip for a gauge threshold by setting a value for the threshold's shortDesc attribute. Note that the threshold tooltip will override the parent gauge's tooltip.

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

To add a tooltip to a gauge and gauge threshold:

  1. In the Structure window, right-click the dvt:typeGauge component and choose Go to Properties.
  2. In the Properties window, expand the Accessibility section.
  3. In the ShortDesc field, enter a description for the gauge. You can also use the attribute's dropdown menu to open the Select Text Resource or Expression Builder dialogs to select a text resource or EL expression that contains the gauge's description.
  4. In the Structure window, right-click the child dvt:gaugeThreshold component and choose Go to Properties.
  5. In the Properties window, expand the Other section.
  6. In the ShortDesc field, enter a description for the gauge threshold. You can also use the attribute's dropdown menu to open the Expression Builder dialog to select an EL expression that contains the gauge's description.

25.4.2 How to Add a Popup or Context Menu to a Gauge

The process to add a popup or context menu is essentially the same. Add the af:showPopupBehavior tag as a child of the gauge component, define the trigger type as click for popup menus or contextMenu for context menus, and add an af:popup containing the desired behavior to the page.

The example below shows the code on the page for the popup menu shown in Figure 25-11. In this example, the af:showPopupBehavior component uses the popupId to reference the af:popup component. The af:popup component is configured with the af:noteWindow component which is configured to display a simple message in the af:outputFormatted component. The triggerType of the af:showPopupBehavior tag is set to click, and the note window will launch when the user clicks anywhere in the gauge.

<af:group id="g1">
  <dvt:dialGauge id="dialGauge1" value="63" shortDesc="Dial Gauge with Popup">
    <af:showPopupBehavior popupId="::noteWindowPopup" triggerType="click"/>
    <dvt:gaugeMetricLabel rendered="true" id="gml1"/>
  </dvt:dialGauge>
  <af:popup childCreation="deferred" autoCancel="disabled"
            id="noteWindowPopup" launcherVar="source"
            clientComponent="true" eventContext="launcher">
    <af:noteWindow id="nw1">
      <af:outputFormatted value="This is an example of a gauge popup." id="of1"
                          shortDesc="Gauge Popup Example"/>
    </af:noteWindow>
  </af:popup>
</af:group>

You can change the popup to the context menu displayed in Figure 25-12 by simply changing the trigger type for the af:showPopupBehavior component to contextMenu as shown in the following code snippet:

<af:showPopupBehavior popupId="::noteWindowPopup" triggerType="contextMenu"/>

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

Add a popup component to your page. For help with configuring the af:popup component, see Using Popup Dialogs, Menus, and Windows.

To add a popup or context menu to a gauge:

  1. In the Structure window, right-click the gauge component and choose Insert Inside Type Gauge > Show Popup Behavior.
  2. Right-click af:showPopupBehavior and choose Go to Properties.
  3. In the Properties window, enter values for the following:

    • PopupId: Specify the ID of the af:popup component.

    • TriggerType: For popup menus, enter click. For context menus, enter contextMenu.

    Optionally, set values for Align, AlignId, and Disabled. Click Component Help for more information about the af:showPopupBehavior component.

25.4.3 How to Configure Value Change Support for a Gauge

You can allow users to change the metric value for a dial or rating gauge by setting the gauge's readOnly attribute to false.

To process the change on the server, specify a listener in the gauge's valueChangeListener attribute.

The code below shows an example of a value change listener for a rating gauge configured to process a value change on the server. In this example, the rating gauge and listener are contained in a managed bean named gaugeData. The listener is named ratingChangedListener and simply outputs the new value to the console.

import javax.faces.event.ValueChangeEvent;

public class GaugeData {
  private Double gaugeValue = 3.0;
  public void ratingChangedListener (ValueChangeEvent e){
    if (e != null){
      gaugeValue = (Double) e.getNewValue();
      System.out.println("You clicked on " + gaugeValue + " stars");
    }
  }
  public Double getGaugeValue(){
    return gaugeValue;
  }
}

The example below shows the code on the JSF page for a rating gauge configured to use the gaugeData managed bean.

dvt:ratingGauge id="ratingGauge1" readOnly="false" value="#{gaugeData.gaugeValue}"
                valueChangeListener="#{gaugeData.ratingChangedListener}">
</dvt:ratingGauge>

You can also process the change on the client using af:clientListener components configured for valueChange and input event types. To use this method, you must create JavaScript functions that perform change event handling.

The code below shows an example of a rating gauge configured with two af:clientListener components, one to handle the valueChange event and one to handle the input event. In this example, the valueChangeListener function sends an alert to the browser, and the inputListener function sends a message to the browser's console log.

<script type="text/javascript" xmlns="http://www.w3.org/1999/xhtml">
  function valueChangeListener(event) {
  alert("valueChange for " + event.getSource().getId() + ": " +
         event.getOldValue() + " --> " + event.getNewValue());
  }
  function inputListener(event) {
    console.log("input for " + event.getSource().getId() + ": " +
                 event.getValue());
  }
</script>
<dvt:ratingGauge id="ratingGauge1" readOnly="false" value="#{gauge.gaugeValue}">
  <af:clientListener method="valueChangeListener" type="valueChange"/>
  <af:clientListener method="inputListener" type="input"/>
</dvt:ratingGauge>

Note:

This example uses inline JavaScript for the purposes of illustration only. Inline JavaScript can increase response payload size, will never be cached in the browser, and can block browser rendering. Instead of using inline JavaScript, consider putting all scripts in JavaScript libraries. For additional information about adding JavaScript to a page, see Adding JavaScript to a Page. For additional information about client-side event handling, see Listening for Client Events.

Before you begin:

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

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

Add a gauge to your page. For help with adding a gauge to a page, see How to Add a Gauge to a Page.

If you are configuring server-side event handling, add the value change listener to the gauge's managed bean. If you need help with managed beans, see Creating and Using Managed Beans.

If you are configuring client-side event handling, create the JavaScript functions that will handle the valueChange and input events. For additional information about client-side event handling, see Listening for Client Events.

To configure value change support for a gauge:

  1. If you are configuring server-side change support, do the following:

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

    2. In the Properties window, expand the Common section if needed.

    3. From the ReadOnly attribute's dropdown list, select False.

    4. Expand the Behavior section.

    5. From the ValueChangeListener attribute's dropdown menu, choose Edit to select the gauge's managed bean and listener.

      For example, to reference the gaugeData sample bean, select gaugeData from the Managed Bean field's dropdown list, and select ratingChangedListener for the method. You can also choose Expression Builder from the ValueChangeListener attribute's dropdown menu to enter an EL expression that evaluates to the gauge's listener.

  2. If you are configuring client-side event support, do the following:

    1. In the Structure window, right-click the gauge component and choose Insert Inside Type Gauge > Client Listener.

    2. In the Insert Client Listener dialog, enter the name of the JavaScript function that will handle the event and the event type.

      For example, to use the example valueChangeListener() function as shown in the code sample above, enter valueChangeListener for the method and valueChange for the event type.

    3. Repeat Step 1 and Step 2 to insert additional client listeners as needed.

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

    5. In the Properties window, expand the Common section if needed.

    6. From the ReadOnly attribute's dropdown list, select False.