About gauge-meter.js

gauge-meter.js is a light weight, easy to use, customizable Gauge Meter rendered in a canvas tag.
It supports all mayor browsers, including IE7 & 8 (with use of excanvas.js, but u'll want to disable the animations).

Quick start

I find that in most cases, a few lines of code explains more than a bulk of documentation:

8
<!-- The Gauge Meter HTML element
(you can assign an initial value by passing it as text in the div) -->
<div id="gauge1">8</div>

<!-- the input field & button -->
<input id="gm1_val" type="text" placeholder="0-10">
<button onclick="setGM1()" type="button">Set</button>

<script>
    //creating the Gauge Meter
    var gm1 = new GaugeMeter(
    {
        ElementId   : "gauge1",
        MinValue    : 0,
        MaxValue    : 10,
        //you can also provide an initial value in the settings object
        /*Value       : 8,*/,
		NoDataText  : "Enter value",
        Text        : "Grade"
    });
    
    //the function for setting a new value
    function setGM1()
    {
        gm1.SetValue(document.getElementById('gm1_val').value);
    }
</script>

Size

The Gauge Meter will always have the width of the containing div. If you wish to have a bigger or smaller Gauge Meter, just modify the width of the div and everything will size along accordingly.

The height of the Gauge Meter will always be 60% of the Gauge Meters width.

Constructor

When creating the Gauge Meter object, an object with settings should be passed as parameter.
Most of the keys of the settings parameter are optional. gauge-meter.js will have default values ready.

In the following table you will find a list keys that can be passed to the settings parameter:

Key Description Value Required Default
ElementId The id of a HTML element where the canvas tag for the Gauge Meter will be created string n/a
MinValue The lowest value of the Gauge Meter number 0
MaxValue The highest value of the Gauge Meter number 100
Value The (current) value to where the needle of the Gauge Meter will point. This key has no default. When no value is given, the Gauge Meter will have a disabled look number n/a
Text The text in the middle of the Gaute Meter string
MinLabel The text left of the Gauge Meter representing the lowest value. If not provided, the default will be a the lowest value returned as a string. string n/a
MaxLabel The text right of the Gauge Meter representing the highest value. If not provided, the default will be a the highest value returned as a string. string n/a
NoDataText If the Value key is not provided, the Gauge Meter will appear disabled showing the text of this key string
Animate Defines if the Gauge Meter should animate or not boolean true
AnimTime Defines the duration of the animation in miliseconds. Note: this is based on a no easing animation. When easing is used, the animation time will take longer. number 500
Refreshrate Defines how fast the moving needle needs to be refreshed (lower value = smoother). This option is only used when the browser does not support requestAnimationFrame() number 12
StartEazingAt A number between 0 and 1 defining at what at what time eazing should take place. Having 0 to eaze right away and 1 to not eaze at all. number 0.5
EazeForce Eaze reduced by nth of step (higher = faster stop) number 1.02
FontColor The font color color rgb(78,101,112)
Font The font font 10px Arial
GaugeColors An array of colors defining the appearance of the Gauge Meter from left to right. The default is red, orange, green, green, green. array of colors [
"rgb(255,0,0)",
"rgb(255,165,0)",
"rgb(34,139,34)",
"rgb(0,128,0)",
"rgb(0,100,0)"
]
GaugeSegments An object with style settings for the Gauge Segments. If may contain the following two keys:
  • BorderColor: color
  • BorderWidth: number
 object {
BorderColor: 'rgb(64,62,68)',
BorderWidth: 2
}
OuterBorder An object with style settings for the outer border. If may contain the following keys:
  • BorderColor: color
  • BorderWidth: number
  • BackgroundColor: color
  • Radius: number
 object {
BorderWidth : 2,
BorderColor : "rgb(145,190,211)",
BackgroundColor : "rgba(145,190,211,0.3)",
Radius : 10
}
Panel An object with style settings for the inner panel. If may contain the following keys:
  • BorderColor: color
  • BackgroundColor: color
  • BorderWidth: number
  • Margin: number
  • Radius: number
 object {
BackgroundColor : 'rgba(145,190,211,0.15)',
BorderColor : 'rgb(145,190,211)',
BorderWidth : 1,
Margin : 7,
Radius : 5
}
Needle An object with style settings for the Gauge needle. If may contain the following keys:
  • BorderColor: color
  • BorderWidth: number
  • BackgroundColor: color
 object {
BorderWidth: 1,
BorderColor: "rgb(0,0,0)",
BackgroundColor: "rgb(255,74,74)"
}
NeedlePivot An object with style settings for the Gauge needle's pivot. If may contain the following keys:
  • BorderColor: color
  • BorderWidth: number
  • BackgroundColor: color
 object {
BorderWidth: 2,
BorderColor: 'rgb(78,101,112)',
BackgroundColor: 'rgb(205,224,226)'
}
GaugeAngle The number of degrees in which the angle of the gauge meter is rendered. number 140

Functions

The following function can be run on an instantiated Gauge Meter:

.SetValue(value)

Sets the new value for the Gauge Meter.
Depending on how the Meter is initialised, this function will animate.
If the provided value is undefined or a positive isNan(), the NoData flag will be set, disabling the gauge meter. 
//instantiating a new GaugeMeter
var gauge_meter = new GaugeMeter({/* settings */});

//setting the new value
gauge_meter.SetValue(50);

.Setup(settings)

Sets up new settings to be used by the Gauge Meter.
The provided settings will overrule the existing settings. 
//instantiating a new GaugeMeter
var gauge_meter = new GaugeMeter(
{
	ElementId   : "gauge1",
	MinValue    : 0,
	MaxValue    : 10,
	Value		: 5
});

//setup new settings
gauge_meter.Setup(
{
	MaxValue    : 20
});

Properties

.Settings

The Settings property contains all the used settings.
Settings can be modified, but will only be visible after a call to either the .SetValue of .Setup function. 
//instantiating a new GaugeMeter
var gauge_meter = new GaugeMeter(
{
	ElementId   : "gauge1",
	MinValue    : 0,
	MaxValue    : 10,
	Value		: 5
});

//reading properties
console.log(gauge_meter.Settings.MaxValue);

//settings properties
gauge_meter.Settings.MaxValue = 50;
gauge_meter.Setup(); //call .Setup to use set properties

Examples

<div id="gauge2"></div>

<script>
    //note that you don't need to assign the Gauge Meter to a var 
    //if your not planning on setting a different value later on
    GaugeMeter(
    {
        ElementId     : "gauge2",
        Value         : 33,
        Animate       : false,
        MinLabel      : "0 %",
        MaxLabel      : "100 %",
        Text          : "completed",
        GaugeColors   :
        [
            '#D0D0FF', '#C0C0FF',
            '#B0B0FF', '#A0A0FF',
            '#9090FF', '#8080FF',
            '#7070FF', '#6060FF',
            '#5050FF', '#4040FF'
        ],
        GaugeSegments : { BorderColor : '#0000FF', BorderWidth : 1},
        NeedlePivot   : { BorderColor : '#0000FF', BackgroundColor : '#D0D0FF' },
        Font          : '14px Helvetica'

    });
</script>
                                    
<div id="gauge3"></div>
<button onclick="reloadGM3()">reload to see animation</button>

<script>
    gm3_settings = 
    {
        ElementId	: "gauge3",
        MinValue	: -100,
        MaxValue	: 100,
        Value           : 38,
        MinLabel	: "-100 c",
        MaxLabel	: "+100 c",
        Text            : "Temp. Celsius",
        GaugeColors     : ['#FF0000','#00FF00'],
        GaugeSegments   : { BorderColor: '#383838', BorderWidth: 2 },
        Panel           : { BorderWidth:1, BorderColor: '#000000',
                            BackgroundColor: '#FFFFFF',Margin: 3 },
        OuterBorder     : { BorderWidth:1, BorderColor: '#0F0F0F',
                            BackgroundColor: '#AEAEAE' },
        NeedlePivot     : { BorderWidth:1, BorderColor: '#0F0F0F',
                            BackgroundColor: '#AEAEAE' }
    }
    GaugeMeter(gm3_settings);

    function reloadGM3()
    {
        GaugeMeter(gm3_settings);
    }
</script>
                                    
<div id="gauge4"></div>

<script>
    GaugeMeter(
    {
        ElementId  : "gauge4",
        NoData     : true,
        NoDataText : "no data",
        MinLabel   : "+50 %",
        MaxLabel   : "-50 %"
    });
</script>