I recently received a request to incorporate a gauge component in my Design Studio dashboards. The higher-ups had seen an Xcelsius dashboard utilizing gauges, and wanted the same functionality in the dashboards I was building. As we all know, a gauge component is not included out-of-the-box with Design Studio, and searching on SCN turned up nothing but requests from others for the same component. So, with my limited knowledge of HTML and absolutely zero experience with JavaScript, I decided to roll up my sleeves and build one myself. The following is a brief chronicle of the process. This is not meant to be a literal step-by-step tutorial, but to demonstrate the thought process behind the creation of the component and provide direction to those looking to create something similar.
I started with a copy of the clock component provided in the DS 1.3 SDK Samples pack, and followed the steps in section 3.2 of the Design Studio SDK Developer Guide to rename the proper components of the extension.
I removed the hour and minute hands by deleting the appropriate sections of the component.js file. I recolored the outer boarder with a gradient fill and added an inner boarder with the reverse gradient fill to give a 3 dimensional look to the exterior ring. To achieve the correct dimensions, I increased the UNIT variable to 145 (from 100) and moved the tick marks outwards by changing their respective start/end variables.
I wanted the number of tick marks to be dynamic, so I created user inputs in the contribution.xml for the number of major and minor tick marks to create. Using these variables, I changed the for-loops which draw the hour and minute tick marks to create the specified number of tick marks with equidistant spacing across the upper 2/3 of the gauge face.
I then changed the look of the gauge needle by editing the "draw second hand" section of the component.js file. To set where the needle is pointing, I replaced the variable "seconds" with one that the user can input either in the properties pane (in the contribution.xml) or with a setValue method (in the contribution.ztl). I created three triangles which together form the needle. The shading of the needle changes as the needle crosses the direction from which the light appears to come from (top left corner). I also embellished the "boss" by adding some transparency and a linear gradient.
To emulate the Xcelsius color ranges in the gauge component, I created arcs that rest above the ticks that are colored red, orange, yellow, and green. The positions of these ranges should be input by the user, so I created inputs in the contribution.xml for the ends of the red, orange, and yellow ranges (each range begins where the previous one ends -- red always begins at the minimum, green always ends at the maximum). I also created a setting that allows the user to select a continuous color distribution across the range instead of the discrete sections.
I wanted the option to have numbers on the dial, so I again created a user option to display numbers. The numbers are created when the tick marks are drawn by rotating the canvas inside of the "for" loop, placing the number text in the correct location, and rotating the canvas back before the next loop iteration. Correct placement of the numbers was moderately difficult to accomplish, mostly because by this point I had lost track of which direction the canvas was rotated and, subsequently, how to place the labels in the correct position relative to the center of the gauge. I created user inputs for the minimum and maximum of the dial, and allowed the gauge values to scale with the number of major tick marks the user selects (calculated based on the loop counter, the step size, and the min). One side effect of this approach: Since the labels are integers, we get some interesting results if the user selects a number of tick marks which does not evenly divide the range, as seen below.
The position of the needle is calculated based on the value (input by the user either in the properties pane or with the setValue method) relative to the max-min range (as seen above, if the value is 50, the needle points to 50 regardless of the min and max). As a finishing touch, I created a label in the bottom portion of the gauge to display the value the gauge is currently pointing to, as well as a user definable unit for the value (such as '%' or '$'). This label can also be turned on and off.
I decided to add a bit of a "reflection" to the dial to simulate it being covered in glass. Then, last but not least, I let the user choose a "theme": the default 'silver' or a slick 'black'
So ends my first adventure using the Design Studio SDK, the creation of my first custom component, and my first contribution to SCN. Your questions, comments, and suggestions are always welcome in the comments section below.
-- Nick Stein
- SAP Managed Tags:
44 Comments
