JustGage-ing where we’re at…

Welcome to this weeks’ #APIFriday! Today, we are taking a look at the Javascript plugin called JustGage. We are cheating a little bit on APIs this week, but using a plugin is similar to using an SDK API. I would say close enough counts here. The JustGage plugin allows you to create “gas gauge” style SVG (signed vector graphics) that you can use in your UI. This is a great way to add some new flavor to show status or progress. We used this plugin in our application for our kegerator. The gauges report on beer remaining, temperature of the keg, and whether the fridge door is opened or closed. It adds a little more color and pop to the UI, and users can get an understanding of the data without reading it. A lot of red on the screen probably means the door is open, the keg is low, or the temperature is too hot. Lots of green and the beer is ripe for the drinking.

This plugin creates a single SVG on your UI, so you can add this to an existing app, tweak a control your are already using, or start from scratch. Any way you like, just make sure you have an UI5 app prepped and ready to go in your WebIDE.

On the JustGage website, click the download button.  This will download a ZIP file that contains the plugins we need to add to the WebIDE. Unzip the folder in a convenient location.

In your WebIDE, create a new js folder under the webapp folder. This js folder will hold all our JavaScript plugins.

In this folder, import the 2 javascript files in the top level of the JustGage package. One is named justgage and the other is a version of raphael.

Once you import the files, you will need to tell your application where the new libraries are. In your index.html file, you will need to add 2 script tags, one for each js file. Identify the source as the relative location of the file, or js/filename.js.

		<script src="js/justgage.js"></script>
		<script src="js/raphael-2.1.4.min.js"></script>

JustGage objects work similarly to the Google Maps JS API where we had to set an area in the view to hold the object once it was created by the controller. You need to create a div to hold the gauge in the view. In your view file where you want the gauge to appear, add a new <html:div> tag and give it a unique ID, like “gauge1”. You need to make sure you have the html namespace defined in your view.

Namespace

xmlns:html="http://www.w3.org/1999/xhtml" 

Div tag – make sure this is inside the <content> tag

<html:div id="g1"></html:div>

Now we can add the JustGage object constructor to our controller. It will take in the ID for the div tag that we want to place the gauge in. Just like with Google Maps, the IDs in the XML views get prepended with the “__xmlviewX–” text, so for now, we need to include that in the constructor. I noticed someone commented on my Google Maps blog about this issues, so maybe we’ll have a fix to stop hard coding! I will update this blog if it works!

In the corresponding controller, you will need to add the onAfterRendering function to your controller if you do not already have it. The onAfterRendering function doesn’t fire until the view has been rendered. If we try to load our gauge before the view has finished rendering, it won’t be able to find the div as it hasn’t been created.

onAfterRendering: function() {

}

In your onAfterRendering function, you can add the constructor for the JustGage. Let’s start with the example from the JustGage documentation. On the documentation, click Setup and copy the code in between the last <script> tags.

  var g = new JustGage({
    id: "gauge",
    value: 67,
    min: 0,
    max: 100,
    title: "Visitors"
  });

The ID is from the sample code, so you will need to update it to match the ID for your div tag from your view. For example, in my application, my id value for the JustGage Constructor would be “__xmlview0–g1“.

Save and run your application. If you see a gauge, congrats! If you don’t, look in your developers console. Chances are you have your ID prepend text incorrect (I know I did at first). If that’s the case, use the inspect tool to find the div element (or any really) so you can see how it renders the ID name.

JustGage allows you configure the gauges in many different ways. You can set custom mins and maxs, as well as custom colors for the gauge. The gauge can be a half circle or a donut, full circle. But now you are probably wondering, “well this looks cool and all, but if I can only set the value of the gauge on instantiation, what good is it for me to show progress? Do I have to refresh my view every time I get new data?” The answer is NO! JustGage has a handy refresh function built it so you can just refresh the gauge value, not the whole SVG or even the whole view. Let’s add a button to our view.

In your view file, add a new Refresh Values button. We’ll use this to simulate receiving new data. The button will need an press function defined as well.

<Button text="Refresh Value" press="onRefresh" />

In the controller, we need to make some minor tweaks to our gauge. We want to make the gauge a globally available object so other functions can make modifications. Remove the var in the var g definition.

g = new JustGage({....

Instead of defining the variable g, our gauge, in the onAfterRendering function, we’ll define it as a global variable. Before your return statement for your controller, define the variable g.

var g;

Now our button press function will be able to find the gauge object. Let’s define our press function. Create a new function called onRefresh.

onRefresh: function() {

}

In the on refresh function, we’ll call the refresh method for JustGage. The refresh method takes in a new value that should be displayed. Let’s just have javascript generate a random int between 0 and 100.

g.refresh((Math.random() * 100) + 1);

Save and run your application. And that’s all we have to do! When you click the Refresh Value button, the gauge will update the value displayed. You’ll see that as the value goes up or down, the color of the gauge changes. This can also be customized using the “levelColors” attribute in JustGage constructor. The samples provided in the JustGage zip will give you a good set of configurations to try. If you have a specific question, let me know and I will help you!

As you probably noticed, the styling is a little off… I found that defining my own CSS class for the gauges gave me a lot more flexibility so they weren’t just floating all over the page.

In my application, I have the gauges value refreshed on an interval where we ping our DB for new values and refresh the gauge with those values. When setting an interval, be careful to only set it once. If you continue to call your set interval function, the number of timers you have running will increase exponentially.

That’s all for this week! Unfortunately I have to take the next week or 2 off as I am traveling. But #APIFriday will resume the last week of March! In the meantime, do you have an #APIFriday project you want to share? I would love to see it on the community, on Twitter, or on LinkedIn!