Usage examples for IBM® Gauge widgets

The gauge widgets that are provided represent a way to display numerical data graphically. Two gauge widgets are provided: AnalogGauge and BarGraph. The example code in this topic is also available for the analog guage and the bar graph.

AnalogGauge widget

The analog gauge widget provides a way to display data on a circular gauge, such as a speedometer or a pressure gauge. To create an analog gauge, first determine the shape that you want the gauge to take, what indicators you want to display on the gauge, what ranges you want to create on the range, and other factors.

<div	dojoType="ibm_gauge.widget.AnalogGauge"
	id="testGauge"
	cx=150
	cy=175
	radius=125></div>

The previous code creates a new analog gauge widget, located within the div with an ID of testGauge. The gauge currently has no ranges, indicators, or tick marks. The data area for the gauge is indicated, however, by the parameters that were passed in.

var g = dijit.byId("testGauge");
g.addRange({low:0, high:10, hover:'0 - 10'});
g.addRange({low:10, high:20, hover:'10 - 20'});
g.addRange({low:20, high:30, hover:'20 - 30'});
g.addRange({low:30, high:40, hover:'30 - 40'});
g.addRange({low:40, high:50, hover:'40 - 50'});

This code adds five ranges to the gauge, with appropriate low, high, and hover values. The hover value is displayed when the mouse points to that particular range.

for(var i=0; i<=50; i+=5){
	g.addIndicator({ value:i, 
			 type:'line', 
			 length:5, 
			 offset:125,
			 label:''+i});
}

The gauge now has tick marks at every five units, with a small line and the value indicated in text. The for loop in the previous method is a more efficient process than writing out the values for each individual tick mark.

Next, add an arrow indicator to the gauge, making it functionally complete.

var valueIndicator = {
	value:17, 
	type:'arrow',
	color: 'yellow',
	length: 135, 
	width: 3,
	hover:'Value: 17', 
	title: 'Value'
};
g.addIndicator(valueIndicator);

The parameters passed in are described in the Gauges Reference topic. However, the value parameter specifies the current numerical value on the gauge where the indicator is positioned initially. The type indicates the type of indicator. For an analog gauge, the available values are arrow and line. The length and width indicate the size of the arrow, and the hover and title parameters specify the text attributed with the indicator.

var targetIndicator = {
	value:6, 
	type:'line', 
	color:'red', 
	width: 3,
	hover:'Target: 6', 
	title: 'Target'
};
g.addIndicator(targetIndicator);

Now that you have created a target indicator, you might also indicate the goal or a warning threshold. Multiple possibilities exist, as you can add any number of indicators to the gauge.

If you ran your code or used the complete version at the end of this topic, then you notice that the indicators with titles have boxes beneath the gauge that indicate numerical values. These boxes are displayed by default to ensure that this widget is accessible to those using screen readers, for example, to view the page. The boxes can be disabled by setting the hideValues parameter to true on the gauge, itself. However, disabling the boxes does make the widget inaccessible. The parameter is the same on the bar graph widget as well.

Bar graph widget

The bar graph widget is used to display numerical information graphically in a bar graph. Multiple possibilities exist, as with the analog gauge widget. You can add any number of bars, indicators, tick marks, text, and so on to the widget. See the following markup example:

<div	dojoType="ibm_gauge.widget.BarGraph"
	id="testBarGraph"
	widgetId="testBarGraph"
	executeScripts="true"
	gaugeHeight="55"
	dataY="25"
	dataHeight="25"
	dataWidth="225"/>

In this example, you add a gradient background to the bar graph. The following steps are applicable to the analog gauge widget as well, as they are handled by the _Gauge super class.

var bg = dijit.byId("testBarGraph");
var fill = {
	type: "linear",
	x1: bg.gaugeWidth/2,
	x2: bg.gaugeWidth/2,
	y2: 0,
	y1: bg.gaugeHeight,
	colors: [{offset: 0, color: "#ECECEC"}, {offset: 1, color: "white"}]
};
bg.gaugeBackground = fill;

This code adds a vertical, linear gradient, going from a white color at the beginning to a light gray at the end, for the background of the bar graph. Three types of gradients are available. More information is available in the Gauges Reference topic.

Just as with the analog gauge widget, you can add the following ranges and tick marks:

bg.addRange({low:0, high:10, hover:'0 - 10'});
bg.addRange({low:10, high:20, hover:'10 - 20'});
bg.addRange({low:20, high:30, hover:'20 - 30'});
bg.addRange({low:30, high:40, hover:'30 - 40'});
bg.addRange({low:40, high:50, hover:'40 - 50'});
	
for(var i=0; i<=50; i+=5){
	bg.addIndicator({
		value:i, 
		type:'line', 
		length:5, 
		offset:-5,
		width: 1,
		label:''+i
	});
}

Finally, you can add a target and value indicators. For the bar graph widget, the target indicator is still the line type ; however, the value indicator is the bar type .

var valueIndicator = {
	value:17, 
	type:"bar", 
	width: 7,
	hover:'Value: 17',
	title: 'Value'
}
bg.addIndicator(valueIndicator);

var targetIndicator = {
	value:22, 
	type:"line", 
	color:'#D00000', 
	hover:'Target: 22',
	title: 'Target'
}
bg.addIndicator(targetIndicator);

The bar graph is now complete. The target and value indicators can be moved with a drag action from the graph to new values. In addition, you can change the values in the value boxes beneath the bar graph. As with the analog gauge, those boxes that indicate the value can be disabled.


AnalogGauge example code:

<div	dojoType="ibm_gauge.widget.AnalogGauge"
	id="testGauge"
	cx=150
	cy=175
	radius=125></div>
<script>
dojo.addOnLoad(function(){
	var g = dijit.byId("testGauge");

	g.addRange({low:0, high:10, hover:'0 - 10'});
	g.addRange({low:10, high:20, hover:'10 - 20'});
	g.addRange({low:20, high:30, hover:'20 - 30'});
	g.addRange({low:30, high:40, hover:'30 - 40'});
	g.addRange({low:40, high:50, hover:'40 - 50'});
	
	for(var i=0; i<=50; i+=5){
		g.addIndicator({ value:i,
	 			 type:'line',
				 length:5,
				 offset:125,
				 label:''+i});
	}

	var valueIndicator = {
		value:17, 
		type:'arrow', 
		color:'yellow',
		length: 135, 
		width: 3,
		hover:'Value: 17', 
		title: 'Value'
	};
	g.addIndicator(valueIndicator);

	var targetIndicator = {
		value:6, 
		type:'line', 
		color:'red', 
		width: 3,
		hover:'Target: 6', 
		title: 'Target'
	};
	g.addIndicator(targetIndicator);
});
</script>

BarGraph example code:

<div	dojoType="ibm_gauge.widget.BarGraph"
	id="testBarGraph"
	widgetId="testBarGraph"
	gaugeHeight="55"
	dataY="25"
	dataHeight="25"
	dataWidth="225"/>		
<script>
dojo.addOnLoad(function(){
	var bg = dijit.byId("testBarGraph");
	var fill = {
		type: "linear",
		x1: bg.gaugeWidth/2,
		x2: bg.gaugeWidth/2,
		y2: 0,
		y1: bg.gaugeHeight,
		colors: [{offset: 0, color: "#ECECEC"}, {offset: 1, color: "white"}]
	};
	bg.gaugeBackground = fill;

	bg.addRange({low:0, high:10, hover:'0 - 10'});
	bg.addRange({low:10, high:20, hover:'10 - 20'});
	bg.addRange({low:20, high:30, hover:'20 - 30'});
	bg.addRange({low:30, high:40, hover:'30 - 40'});
	bg.addRange({low:40, high:50, hover:'40 - 50'});
	
	for(var i=0; i<=50; i+=5){
		bg.addIndicator({
			value:i, 
			type:'line', 
			length:5, 
			offset:-5,
			width: 1,
			label:''+i
		});
	}
	
	var valueIndicator = {
		value:17, 
		type:"bar", 
		width: 7,
		hover:'Value: 17',
		title: 'Value'
	}
	bg.addIndicator(valueIndicator);
	
	var targetIndicator = {
		value:22, 
		type:"line", 
		color:'#D00000', 
		hover:'Target: 22',
		title: 'Target'
	}
	bg.addIndicator(targetIndicator);
});
</script>