In an earlier post about two-way data binding with knockout, we introduced the ojStatusMeterGauge component and showed how it can be used to display and accept inputs for a metric value. In today's post, we'll show some of the popular customizations of this component, along with HTML samples so that you can quickly integrate them into your application.

gaugeAnim.gif

 

To get started, we'll create a basic status meter gauge similar to the ones below. The status meter is horizontal by default and a great choice for use within tables or grids, which provide a natural frame around the gauge that create a really clean look.

gaugeTable.png

<!-- HTML Snippet. Don't forget to require the 'ojs/ojgauge' component in your main.js. -->
<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100
}" style="width:120px;height:20px;">
</div>






 

Since it's optimized for display in table cells, the default horizontal status meter doesn't display the metric label or a plot area indicating the possible extents of the metric.  When displayed outside of table cells, it's a good idea to turn these on:

gauge1.png

<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100,
  metricLabel: {rendered: 'on'},
  plotArea: {rendered: 'on'}
}" style="width:200px;height:25px;">
</div>








 

By default, the gauge is displayed with slightly rounded edges. This can be customized or disabled using the borderRadius attribute. The rounded edges of the plot area can also be customized separately using plotArea.borderRadius.

gauge2.png

<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100,
  metricLabel: {rendered: 'on'},
  plotArea: {rendered: 'on'},
borderRadius: '0px'
}" style="width:200px;height:25px;">
</div>






 

In addition to being displayed outside of the plot area, the metric labels can be displayed in other positions. These work well both inside and outside table cells and look especially clean without the plot area.

gauge3.png


<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100,
  metricLabel: {rendered: 'on', position: 'insideIndicatorEdge'}
}" style="width:200px;height:25px;">
</div>

<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100,
  metricLabel: {rendered: 'on', position: 'outsideIndicatorEdge'}
}" style="width:200px;height:25px;">
</div>






 

The gauge indicator can be colored using either the color attribute or an array of threshold values. The color attribute takes an arbitrary color string and works particularly well in conjunction with the ColorAttributeGroupHandler that we introduced in the Colorful Bar Charts post, which makes it easy to keep colors consistent across components.

gauge4.png

<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100,
  metricLabel: {rendered: 'on'},
  plotArea: {rendered: 'on'},
  color: '#267db3'
}" style="width:200px;height:25px;">
</div>








 

Thresholds are specified as a set of objects with max values, where the indicator is colored based on which threshold the metric value belongs. No max value is needed for the final threshold, as it will be set to the max value of the gauge.

gauge5.png

<!-- Only the third gauge above is shown. Change the value to 25 and 50 to see the first and second -->
<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100,
  metricLabel: {rendered: 'on'},
  plotArea: {rendered: 'on'},
  thresholds: [{max: 33}, {max: 67}, {}]
}" style="width:200px;height:25px;">
</div>








 

There are two more visual options for displaying the thresholds. The first displays the current threshold color in the plot area, using the default color for the indicator. The second option displays all the thresholds in the plot area, giving the user more information on how close the metric value is to the threshold boundaries. This second option is not recommended for use within tables or lists, especially when the threshold values may vary between instances, as the amount of information and colors shown can be distracting to a user. It's ideally used in isolation when the user really needs that context about threshold boundaries. To create these gauges, set the indicatorSize and thresholdDisplay attributes.

gauge6.png

<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100,
  plotArea: {rendered: 'on'},
  thresholds: [{max: 33}, {max: 67}, {}],
  indicatorSize: 0.5, thresholdDisplay: 'currentOnly'
}" style="width:200px;height:25px;">
</div>

<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100,
  plotArea: {rendered: 'on'},
  thresholds: [{max: 33}, {max: 67}, {}],
  indicatorSize: 0.5, thresholdDisplay: 'all'
}" style="width:200px;height:25px;">
</div>







 

The indicatorSize can also be used to reduce the size of the plot area, giving a hint of the extents without the visual weight of the full plot area.

gauge7.png

<!-- Shown above with default thresholdDisplay and thresholdDisplay: 'all' -->
<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 25, min: 0, max: 100,
  plotArea: {rendered: 'on'},
  thresholds: [{max: 33}, {max: 67}, {}],
  indicatorSize: 5
}" style="width:200px;height:25px;">
</div>






 

The status meter gauge also supports reference lines, which are commonly used to display a previous or historical value. This can also be used in conjunction with thresholds to create bullet charts. Since bullet charts are commonly shown with square edges, I've also set the border radius to 0px.

gauge8.png

<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100,
  plotArea: {rendered: 'on'},
  thresholds: [{max: 33}, {max: 67}, {}],
  indicatorSize: 0.5,
  referenceLines: [{value: 85, color: 'black'}]
}" style="width:200px;height:25px;">
</div>

<div data-bind="ojComponent: {
  component: 'ojStatusMeterGauge',
  value: 75, min: 0, max: 100,
  plotArea: {rendered: 'on'},
  thresholds: [
    {max: 33, color: '#AAAAAA'},
    {max: 67, color: '#CCCCCC'},
    {color: '#EEEEEE'}],
  borderRadius: '0px',
  indicatorSize: 0.5, thresholdDisplay: 'all',
  referenceLines: [{value: 85, color: 'black'}]
}" style="width:200px;height:25px;">
</div>







 

Hopefully this post provides a good summary of the customization options on the gauges, as well as an idea of when to use them. Next week, I'll conclude this overview of the gauges by talking about the circular status meter, led, and rating gauges.