Skip to content

Gauge HTML API

Jump to bottom
Mikhus edited this page Feb 26, 2013 · 13 revisions

Gauge HTML API

Gauge can be simply configured by using an HTML definition only. All configuration could be done simply with data-* attributes.

Initially it is required to include gauge.js script in a head of the HTML document. Then each canvas element having data-type attribute set to "canv-gauge" will be automatically rendered to a gauge. Here is an example:

<!doctype html>
<html>
<head>
  <title>Simple HTML5 Canvas Gauge Example</title>
  <script src="https://raw.github.com/Mikhus/canv-gauge/master/gauge.js"></script>
</head>
<body>
  <canvas data-type="canv-gauge"></canvas>
</body>
</html>

For more detailed example, please, see example-html-gauge.html file.

Gauge configuration attributes:

Most of configuration attributes relies to their similar configuration properties in JS API.

data-type Should be set to "canv-gauge" to be rendered.

data-title Sets the gauge title value. Normally any string you like

data-min-value Minimal (low) value of the gauge

data-max-value Maximum (high) value of the gauge

data-major-ticks An array of major ticks should be written on a gauge. It simply should be defined as a numeric ticks values separated by space. Example: data-major-ticks="0 20 40 60 80 100"

data-minor-ticks Number of minor ticks should be drawn between each major ticks.

data-stroke-ticks Defines if ticks should be stroked or not. Possible values are "true" or "false".

data-units Units should be drawn on a gauge, for example "Km/h"

data-value-format Defines a format of the gauge value should be displayed on a gauge dial plate. It should be defined as number of integers dot number of decimals, like "3.2", means 3 integers and 2 decimals.

data-glow Turns on/off gauge glow effect. Possible values are "true" or "false".

data-animation-delay Sets a needle animation delay to a given number of milliseconds.

data-animation-duration Sets overall needle animation duration to a given number of milliseconds.

data-animation-fn Defines an animation function for the needle. Should be a string with function name or code with function definition. Available string functions are: 'linear', 'quad', 'quint', 'cycle', 'bounce', 'elastic'. If you want to define your own animation function set the value to, for example, "function( p) { return Math.pow( p, 3) }", which will make a cubic animation of the needle.

data-colors-plate Sets the color of the gauge plate. Color should be defined in hexadecimal or rgb format (#fff or #ffffff or rgb(255, 255, 255)).

data-colors-major-ticks Sets a color for major ticks drawing

data-colors-minor-ticks Sets a color for minor ticks drawing

data-colors-title Sets a color for title drawing

data-colors-units Sets a color for units drawing

data-colors-numbers Sets a color for numbers drawing

*data-colors-needle Sets a color for needle drawing. As far as needle allows start and end colors, them could be specified both separated by at least one space character. For example, "rgba(240, 128, 128, 1) rgba(255, 160, 122, .9)" or "#f00 #00f".

data-highlights Sets an array of ticks highlights should be used with the gauge. Each highlight element consists of "from value", "to value" and "color" separated by at least one space character. Highligh elements are separated by "," (comma). For example, "0 30 #eee, 30 60 #ccc, 60 90 #aaa" defines three highlight areas. First one from value 0 to value 30 with color #eee, second one from value 30 to value 60 with color #ccc and the last one from value 60 to value 90 with color #aaa

data-onready Defines an onready event for the gauge. it is should be a javascript code.

width Defines a gauge width

height Defines a gauge height

Gauge.Collection

All gauges created by a Gauge constructor are written to a Gauge.Collection array. Then you can access initialized gauges on a page via array collection. This collection defines special method get()

get( id) - returns a gauge object by its HTML identifier or by an index in the array collection. For example, imagine you have three gauges on a page defined as:

<canvas id="g1" data-type="canv-gauge"></canvas>
<canvas id="g2" data-type="canv-gauge"></canvas>
<canvas data-type="canv-gauge"></canvas>

You can easily access in your script the gauge objects by it's id, like:

Gauge.Collection.get('g1').setValue( 54.3);

As you see the third gauge does not have an id. By the way it could be accesses via index (you should be assured about the number of gauges on a page and their order to get an appropriate object):

Gauge.Collection.get(2).setValue( 58.9);

or

Gauge.Collection[2].setValue( 58.9);
Clone this wiki locally