Using the Gauge Classes

The following is a list of terms pertaining to the gauge classes and their descriptions:

Use the gauge classes to create gauges that display metrics in several common formats, including status meters, LEDs, and ratings.

Three gauge classes are available: LEDGauge, RatingGaugeChart, and StatusMeterGauge. Each of these gauges must be implemented and instantiated as a different class.

Of these gauge types, the LEDGauge and StatusMeterGauge classes share many common characteristics, including the methods you can invoke and the properties you can set. While rating gauges share some characteristics with the other gauge types, the RatingGaugeChart class and supporting classes are described separately within this topic.

The following examples use the same value, 54.5, as the gauge metric. In addition, an instance of the Threshold class is used to specify the color shading on the dial gauge and the status meter gauge, as well as the color of the LED.

Example of an LED Gauge

Image: Example of an LED gauge

The following example displays an LED gauge:

Example of a Status Meter Gauge

Image: Example of a status meter gauge

The following example displays a status gauge:

You can specify a field in a rowset and have it depicted graphically as a gauge with minimal PeopleCode. The data in the field must be numeric. You can also choose to make the gauge interactive.

The high-level steps involved in creating any gauge are:

1. Identify a field on a record that has a numeric value that you want to show in a gauge.

2. Add a chart area to a page in Application Designer. Associate the record and field in Step 1 with that chart area.

3. In PeopleCode instantiate a gauge object using one of the built-in functions available for gauges:

   • GetLEDGauge

   • GetRatingGauge

   • GetStatusMeterGauge

4. Set property values for the gauge object as needed, keeping in mind the design guidelines below. Most properties have default values, so you can start by reviewing your gauge with no properties set and then set those that you need to in order to tailor the appearance and functionality of the gauge.

5. Depending on the gauge type:

   • For the LEDGauge and StatusMeterGauge classes, optionally, create an instance of the Threshold class and associate it with your instance of the gauge.

   • For the RatingGaugeChart class, create instances of the RatingGaugeState class and of the GaugeThreshold class and associate them with your instance of the gauge.

The following design guidelines apply to dial gauges, LED gauges, and status meter gauges only.

You can make your gauges interactive. You can either run FieldChange PeopleCode or redirect users to a URL. Interactivity will be initiated when a user clicks on (or touches) the gauge.

Image: Gauge interactivity flowchart

As illustrated in the following flowchart, in order to have your gauge be interactive, you must set the IsDrillable property to True. Then, if you have set the GaugeURL property to a valid URL, a click will redirect the user to that URL. If GaugeURL is not set, but there is FieldChange PeopleCode on the field that defines the gauge’s metric (that is, the field you passed into the GetStatusMeterGauge or GetLEDGauge function), then that PeopleCode will run. Otherwise, if neither GaugeURL is set nor FieldChange PeopleCode is present, then there is no interactivity even if IsDrillable is True.

The Threshold class is used in conjunction with the two gauge classes: LEDGauge and StatusMeterGauge. The Threshold class provides a way to add reference areas and color coding to your gauges.

Image: An LED gauge colored by a Threshold object

On the LED gauge, the Threshold class can be used to color the LED gauge according to the defined threshold values.

Using Thresholds with Gauges

Image: A LED gauge

The following example presents a LED gauge with color from the Threshold class:

To render the gauge in this way, you would create an instance of the Threshold class. Each property of the Threshold class is an array that you would populate as follows:

Values array	Colors array
Value of first threshold	Yellow
Value of the second threshold	Green
NA	Red

A user-defined PeopleCode function that instantiates this instance of the Threshold class looks like this:

Function bld_thrshld Returns Threshold;
   Local Threshold &thrshld;
   &thrshld = GetThreshold();
   &thrshld.Values = CreateArray(CJY_SLRY.CJY_SLRY_MIN, CJY_SLRY.CJY_SLRY_MAX);
   &thrshld.Colors = CreateArray(%ChartColor_Yellow, %ChartColor_Green, %ChartColor_Red);
   Return &thrshld;
End-Function;

However, you can add a Descriptions array to control what is displayed in data hints and in the legend:

Values array	Descriptions array	Colors array
Value of first threshold	Below Range	Yellow
Value of the second threshold	Within Range	Green
NA	Above Range	Red

The Descriptions array is added to the same user-defined PeopleCode function:

Function bld_thrshld Returns Threshold;
   Local Threshold &thrshld;
   &thrshld = GetThreshold();
   &thrshld.Values = CreateArray(CJY_SLRY.CJY_SLRY_MIN, CJY_SLRY.CJY_SLRY_MAX);
   &thrshld.Descriptions = CreateArray("Below Range", "Within Range", "Above Range");
   &thrshld.Colors = CreateArray(%ChartColor_Yellow, %ChartColor_Green, %ChartColor_Red);
   Return &thrshld;
End-Function;

Rating gauges are typically used to display or accept user feedback on a product or service. A rating gauge can be interactive or display only.

Display-only rating gauges (the ReadOnly property is True) set the gauge to the value of the field that was used when the rating gauge was created with the GetRatingGauge built-in function. The value of the rating gauge cannot be changed by the user.

Interactive rating gauges (the ReadOnly property is False) can update the underlying value in the RECORD.FIELD that was used when the rating gauge was created with the GetRatingGauge built-in function. If there is FieldChange PeopleCode on the field, the PeopleCode executes only for an interactive rating gauge.

The display of a rating gauge can be changed in two ways:

• Based on the state of the rating gauge.

• Based on threshold values against which the value of the rating gauge is compared.

A rating gauge can support four different states depending on the chart type:

• Unselected

• Selected

• Hover (interactive only)

• Changed (interactive only)

Here’s an example of a gauge transitioning through three states. Each state displays the gauge data differently:

Field or Control	Definition
	A rating gauge in the unselected state.
	A rating gauge in the hover state.
	A rating gauge in the selected state.

You can set the display characteristics for each state using the RatingGaugeState class. You create an instance of this class, set its properties, and assign the instance to the corresponding state property on the RatingGaugeChart instance that you created.’

In addition, a rating gauge supports up to three thresholds. Different thresholds can cause the rating gauge to change color and present different tooltip text based on the gauge value:

Field or Control	Definition
	A rating gauge with thresholds (Outstanding rating)
	A rating gauge with thresholds (Satisfactory rating)

You can set the characteristics for each threshold value using the GaugeThreshold class. You create an instance of this class and set its properties, including the threshold maximum. Create an array of GaugeThreshold instances and assign the array to the RatingGaugeChart object using its SetRatingGaugeThresholds method. If a gauge color or border color is set in a gauge threshold, those colors override the colors set by the rating gauge states.

Any gauge and threshold objects can be instantiated from PeopleCode only. You can use these objects only in PeopleCode programs that are associated with an online process, not in an Application Engine program, a message notification, a component interface, and so on.

Gauge objects are declared using the one of the three gauge classes data types. For example:

Component LedGauge &oLED;
Component RatingGaugeChart &oRating;
Component StatusMeterGauge &oSM;

In addition, optional threshold objects for use with dial gauges, LED gauges, and status meter gauges are declared using the Threshold class:

Component Threshold &oThrshld;

Gauge state objects and gauge threshold objects for use with rating gauges are declared using the RatingGaugeState class and the GaugeThreshold class respectively:

Local RatingGaugeState &oRatGaugeSelState, &oRatGaugeUnSelState, &oRatGaugeHovState, &oRatGaugeChangState;

Local GaugeThreshold &oGTresh1, &oGTresh2, &oGTresh3, &oGTresh4;

The PeopleCode program is terminated if a field or record is missing at runtime.

If a valid record is specified but no data is found, or for any other error, the chart is replaced by the message "Image creation failed."

If the Java Runtime Environment (JRE) is missing, an error appears and is logged.

The properties can be grouped as follows:

• Gauge type – You can select different visual representations for each gauge class

• Minimums and maximums – You can specify the range of values that you want the gauge to cover

• Labels – You can determine which, if any, labels, you want to accompany the gauge

• Gauge increments – Specify gauge increments if more numeric context is needed.

• Legends – A legend can be displayed to help users interpret the reference areas.

• Animation – You can choose the type and duration of animation for the gauge display.

• Interactivity – You can choose to have an event occur if the user clicks (or touches) the gauge.