-
Notifications
You must be signed in to change notification settings - Fork 396
Gauge HTML API
ATTENTION This wiki is for canvas gauges v1. Documentation for version 2+ is available here.
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.min.js"></script>
</head>
<body>
<canvas data-type="canv-gauge"></canvas>
</body>
</html>
For more detailed example, please, see example-html-gauge.html file.
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-value Sets the value gauge should be rendered with.
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-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-update-value-on-animation Specifies if value should be constantly updated during needle animation. By default is 'false'.
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-colors-needle-start Sets a color for the needle start. Instad of the "data-colors-needle" we can use also this attribute to specify the color for the needle start. By default is: "rgba(240, 128, 128, 1)"
data-colors-needle-end Sets a color for the needle end. Instad of the "data-colors-needle" we can use also this attribute to specify the color for the needle end. By default is: "rgba(255, 160, 122, .9)"
data-colors-needle-shadowup Sets a color for the needle shadow up. By default is: "rgba(2, 255, 255, 0.2)"
data-colors-needle-shadowdown Sets a color for the needle shadow down. By default is: "rgba(188, 143, 143, 0.45)"
data-colors-needle-circle-outerstart Sets a color for the start of the needle outer circle. By default is: "#f0f0f0"
data-colors-needle-circle-outerend Sets a color for the end of the needle outer circle. By default is: "#ccc"
data-colors-needle-circle-innerstart Sets a color for the start of the needle inner circle. By default is: "#e8e8e8"
data-colors-needle-circle-innerend Sets a color for the end of the needle inner circle. By default is: "#f5f5f5"
data-colors-valuebox-rectstart Sets a color for the start of the gauge's value box rect. By default is: "#888"
data-colors-valuebox-rectend Sets a color for the end of the gauge's value box rect. By default is: "#666"
data-colors-valuebox-background Sets a color for the background of the gauge's value box rect. By default is: "#babab2"
data-colors-valuebox-shadow Sets a color for the shadow of the gauge's value box rect. By default is: "rgba(0, 0, 0, 1)"
data-colors-valuetext-foreground Sets a color for the foreground of the gauge's value text. By default is: "#444"
*data-colors-valuetext-shadow Sets a color for the shadow of the gauge's value text. By default is: "rgba(0, 0, 0, 0.3)"
data-colors-circle-shadow Sets a color for the gauge's outer circle shadow. By default is: "#ddd"
data-colors-circle-outerstart Sets a color for the start of the gauge's outer circle. By default is: "#ddd"
data-colors-circle-outerend Sets a color for the end of the gauge's outer circle. By default is: "#aaa"
data-colors-circle-middlestart Sets a color for the start of the gauge's middle circle. By default is: "#eee"
data-colors-circle-middleend Sets a color for the end of the gauge's middle circle. By default is: "#eee"
data-colors-circle-innerstart Sets a color for the start of the gauge's inner circle. By default is: "#fafafa"
*data-colors-circle-innerend Sets a color for the end of the gauge's inner circle. By default is: "#ccc"
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-circles-outervisible Determine if the gauge's outer circle is visible or not. By default is: "true"
data-circles-middlevisible Determine if the gauge's middle circle is visible or not. By default is: "true"
data-circles-innervisible Determine if the gauge's inner circle is visible or not. By default is: "true"
data-valuebox-visible Determine if the gauge's value box is visible or not. By default is: "true"
data-valuetext-visible Determine if the gauge's value text is visible or not. Note if this attribute is "false" then the value box is also hide, in other words, the "data-valuebox-visible" value is ignored. By default is: "true"
data-ticksangle Defines max angle used for the ticks drawing (270 by default, if to pass 360 ticks will be drawn on entire circle).
data-startangle Defines which angle should be treated as zero-value angle (default is 45)
data-needle-type Defines how the needle should look like. Allowed: "arrow", "line". Default is "arrow"
data-needle-circle-inner Defines if it is required to draw inner circle for the needle (values are "true" or "false")
data-needle-circle-outer Defines if it is required to draw outer circle for the needle (values are "true" or "false")
data-needle-circle-size Defines max outer circle size for the needle in percents (default is "10")
data-needle-start Defines where the needle should start (only for needle-type="line"). This is value in percent of the entire gauge radius. Default is "0"
data-needle-end Defines where the needle should end (works for both needle types). This is value in percent of the entire gauge radius. Default is "77"
data-needle-width - Max width of the needle. Default is "4"
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
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 accessed 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);