Wijmo v2 is here! Yay! For today’s Wijmo Wednesday, let’s take a look at a new Wijmo v2 feature: Linear Gauges.
Getting Started
To get started, we need to create a new DIV for the gauge to live in.
<div id="gauge"></div>
There you go! Of course, that doesn’t do anything, so let’s write a little bit of JavaScript to turn that DIV into a Linear Gauge.
$("#gauge").wijlineargauge();
If you render this as is, the gauge will look similar to this picture:
A couple of things to point out on this gauge. First is the tick marks. These are called Major Ticks. By default, these are set to automatically show for an interval of 10. There are also Minor Ticks that can be shown in between each major tick. By default, these are not displayed. We’ll show you how to change the value in a moment.
Changing Minimum and Maximum Values
There are two properties for setting minimum and maximum values of the linear gauge. These are called min and max. Let’s play with the values:
$("#gauge").wijlineargauge({ min: 0, max: 1000 });
Doing this will product an image like so:
Whoa! What’s wrong!? Well, the tick major is still set to 10, so the gauge is trying to render a tick for every interval from 0 to 1000. Let’s change the ticks to a more reasonable value.
Setting Tick Intervals
I’m going to play with two new values: tickMajor and tickMinor.
$("#gauge").wijlineargauge({
min: 0,
max: 1000,
tickMajor: {
interval: 200
},
tickMinor: {
interval: 50,
visible: true
}
});
Refresh the page. Note the bolded visible: true. This is important since the tickMajor.visible property is defaulted to false. Here’s what the updated picture looks like:
Doesn’t that look much better! Next, let’s play around with that pointer and set the gauge to a value other than zero.
Setting Pointer Value
$("#gauge").wijlineargauge({
min: 0,
max: 1000,
tickMajor: {
interval: 200
},
tickMinor: {
interval: 50,
visible: true
},
value: 475
});
The code change is highlighted above. Set the value property to update where the pointer goes. Pictures don’t do this justice, because the transition is animated.
If you’d like to update the value dynamically, all you need to do is use jQueryUI property updating syntax:
$("#gauge").wijlineargauge("option", "value", 755);
Ranges
$("#gauge").wijlineargauge({
min: 0,
max: 1000,
tickMajor: {
interval: 200
},
tickMinor: {
interval: 50,
visible: true
},
value: 475,
ranges: [
{
startValue: 800,
endValue: 1000,
startDistance: 0.95,
endDistance: 0.75,
startWidth: 0.5,
endWidth: 0.5,
style: {
fill: "90-#3DA1D8-#3A6CAC",
opacity: "1",
stroke: "none"
}
}
]
});
The ranges property is an array. Inside the array is a list of range values that are to be applied to the gauge. In this example, I’m only creating a single range, but you can add more. StartValue and endValue are obvious. This is where the range begins and ends. StartWidth and endWidth determine the width (or depending on the orientation it could considered height). Let’s assume I change the value of startWidth to 0.1.
Pretty cool, huh? Last option is for startDistance and endDistance. This changes where on gauge the fill starts to render. For example, I’ll change startDistance to .095 and endDistance to .75 (width is also set back to .5). The rendered result will “tilt” the range.
Why would this be useful? Here’s a great example over in the Wijmo control explorer. It shows how ranges can provide a cool visual effect for showing scale.
And there you have it. All the basics you need to know in order to get started with Wijmo’s linear gauges. I hope you enjoy working with them! If you have any questions, feel free to shoot me an email or ask in the comments.
Kevin Griffin
keving@componentone.com
MESCIUS inc.