Configure Gauges

This guide contains detailed instructions on how to configure the CircularGauge and LinearGauge widgets. You will learn how to provide data to be visualized on a gauge, select an appropriate preset and customize it to the task's requirements. As a result, you will get the gauges that show the local temperature and the temperature in the selected town, in Celsius.

Create a Circular Gauge

Begin by creating an HTML file. Then, add references to the required libraries (see the Add Libraries tutorial).

HTML
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <script type="text/javascript" src="jquery-1.9.1.min.js"></script>
        <script type="text/javascript" src="knockout-2.2.1.js"></script>
        <script type="text/javascript" src="globalize.min.js"></script>
        <script type="text/javascript" src="dx.chartjs.js"></script>
    </head>
    <body></body>
</html>

There are several approaches to creating a ChartJS widget. This page will utilize the jQuery approach. Refer to the Add a Widget tutorial to go over the remaining approaches.

Add a div element. It will be a container for the dxCircularGauge widget.

HTML
<body>
    <div id="gaugeContainer" style="height:320px"></div>
</body>

Create the dxCircularGauge widget within the added container.

HTML
<head>
    <!-- ... -->
    <script type="text/javascript">
        $(function () {
            $("#gaugeContainer").dxCircularGauge({});
        })
    </script>
</head>

Run this code and you will see that a default gauge preset ("preset1") is applied, although we did not specify an option. You can choose another default preset. To set a preset, use the preset property of the configuration object.

JavaScript
$(function () {
    $("#gaugeContainer").dxCircularGauge({
        preset: 'preset2'
    });
});

In contrast to "preset2", the default preset is more appropriate for our task with a thermometer. However, we will have to customize this preset so that it looks more like a thermometer. To begin, we will provide data for the created gauge.

Provide Data

According to the declared task, the needle must show the temperature in the selected town and the marker must show the temperature in the current town. But to start learning dxCircularGauge basics, we will simply assign random values. To define data for a CircularGuage, define the scale, needles, markers and rangeContainer objects within the configuration object.

JavaScript
$("#gaugeContainer").dxCircularGauge({
    scale: {
        startValue: -50,
        endValue: 50
    },
    needles: [{ value: 24 }],
    markers: [{ value: 19 }],
    rangeContainer: {
        ranges: [{
                startValue: -50,
                endValue: 0,
                color: 'blue'
            }, {
                startValue: 0,
                endValue: 50,
                color: 'red'
            }
        ]
    }  
});

As you can see in this code, the scale bounds are set using the startValue and endValue properties. The needles and markers arrays contain only one object, per our task. The rangeContainer object defines two ranges - their start/end values and color.

Scale Adjustment

A scale is displayed by major and minor ticks, as well as labels. As you can see in the previous step's result, we can leave the labels as they are. But we need to change the way major ticks are displayed and visualize minor ticks (as they are not shown in the chosen preset).

JavaScript
$("#gaugeContainer").dxCircularGauge({
    //...
    scale: {
        //...
        majorTick: {
            color: 'black',
            tickInterval : 10
        },
        minorTick: {
            visible: true,
            color: 'black',
            tickInterval : 1
        }
    }
});

In the code above, we have changed the visibility of minor ticks, set the color to black, as well as a tick interval for major and minor ticks.

We need to reduce the range container's radius, so that it does not overlap the scale. Refer to the next step to learn how to do this.

Ranges Adjustment

Let's offset the ranges so that they do not overlap the scale. In the CircularGauge widget, the position of any element is specified by an offset from an invisible scale line. The offset of ranges is set to 0, by default. To set the required offset for the ranges, use the offset property of the rangeContainer object. The rangeContainer object holds the properties that specify display parameters for all ranges.

JavaScript
$("#gaugeContainer").dxCircularGauge({
    //...
    rangeContainer: {
        //...
        offset: 5,
    },
});

In the code above, 5 is the offset of the range container relative to its previous position.

Needle Adjustment

To set a color for a needle, we will use its color property. To set a color for the needle's spindle, we will use the spindle configuration object.

JavaScript
$("#gaugeContainer").dxCircularGauge({
    //...
    needles: [{ 
        //...
        color : 'red',
    }],
    spindle: {color : 'red'},
});

NOTE: If you have several needles in your CircularGauge, you can set their common options using the commonNeedleSettings configuration object. See the following code.

JavaScript
$("#gaugeContainer").dxCircularGauge({
    //...
    commonNeedleSettings: {
        color : 'red'
    }
});

Marker Adjustment

The last thing that we could change in our CircularGauge is the marker color. To set a color for a marker, we will use the color property of the marker's configuration object.

JavaScript
$("#gaugeContainer").dxCircularGauge({
    //...
    markers: [{
        //...
        color: 'green'
    }]
});

NOTE: If you have several markers in your CircularGauge, you can set their common options using the commonMarkerSettings configuration object, as demonstrated in the previous step for needles.

Runtime Data Update

To complete the implementation of the application, the CircularGauge should be updated when the user selects a town from the list.

First, add a combobox that will allow you to select a town, then paste the following code in the HTML file:

HTML
<select id="townSelector">
    <option value="44418">London</option>
    <option value="638242">Berlin</option>
    <option value="2459115">New York</option>
    <option value="24553382">Moscow</option>
    <option value="1225448">Bangkok</option>
</select>

As you can see in the code above, each town is identified by a unique WOEID. The next step is to update the needle's value when a town is changed. The temperature in the selected town will be requested from the Yahoo! Weather Web service using the Yahoo! Query Language (YQL). To perform a query, use the ajax() jQuery function.

Next, handle the combobox's change event. To update needle data, get the CircularGauge instance and set its needleValue property.

JavaScript
$('#townSelector').change(function () {
    var townCode = this.value,
        gauge = $('#gaugeContainer').dxCircularGauge('instance'),
        query = 'select item.condition.temp from weather.forecast where woeid="' + townCode + '" and u="c"',
        url = "http://query.yahooapis.com/v1/public/yql?format=json&q=" + escape(query);

    $.ajax(url, { dataType: 'jsonp' }).done(function (data) {
        var forecast = data.query.results;
        if (forecast) {
            gauge.needleValue(0, forecast.channel.item.condition.temp);
        }
    });
});

Run the complete code and check that the needle is set to the temperature that is specified for the currently selected town.

Add a LinearGauge

To display a value on a linear gauge, use the dxLinearGauge widget supplied with the ChartJS library. Use this page to learn how to configure this widget to your requirements, and thus get a linear gauge that displays the local temperature and the temperature of the selected town.

Like all the widgets from the ChartJS library, the dxLinearGauge widget can be created using either the JQuery or Knockout approach. Both of them are detailed in the Add a Widget tutorial.

To provide data for the dxLinearGauge, define the scale, needles, markers and rangeContainer objects, as we did for the dxCircularGague widget in previous steps.

HTML
<div id="linearGaugeContainer" style="height:30px"></div>
JavaScript
$("#linearGaugeContainer").dxLinearGauge({
    scale: {
        startValue: -50,
        endValue: 50,
    },
    needles: [{ value: 24}],
    markers: [{ value: 19}],
    rangeContainer: {
        ranges: [{
                startValue: -50,
                endValue: 0,
                color: 'blue'
            }, {
                startValue: 0,
                endValue: 50,
                color: 'red'
            }
        ]
    }
});

Now, let's add minor ticks, as we did for the CircularGauge.

JavaScript
$("#linearGaugeContainer").dxLinearGauge({
    scale: {
        //...
        minorTick: {
            visible: true,
            tickInterval: 1
        }
    },
    //...
});

Finally, customize the colors, change the gauge's orientation and shift the needle, marker and range container so that they do not overlap each other. The following code demonstrates this.

JavaScript
$("#linearGaugeContainer").dxLinearGauge({
    geometry: {
        orientation: 'vertical'
    },
    scale: {
        //...
        majorTick: {
            color: 'black',
        }
        minorTick: {
            //...
            color: 'black'
        }
    },
    needles: [{ value: 24, color: 'red', offset: 10}],
    markers: [{ value: 19, color: 'green', offset: -5}],
    rangeContainer: {
        //...
        offset: -5
    }
    //...
});

As you can see, the dxLinearGauge and dxCircularGauge widgets have much in common. The only difference is that the dxLinearGauge can be oriented vertically and horizontally.

Add a combobox and handle its change event just like you did for the dxCircularGauge widget above.