toorshia / justgage

JustGage is a handy JavaScript plugin for generating and animating nice & clean dashboard gauges. It is based on Raphaël library for vector drawing.

JustGage

JustGage is a handy JavaScript plugin for generating and animating nice & clean dashboard gauges. It is based on Raphaël library for vector drawing.

• JustGage
  • Getting Started
  • Basic usage
  • Options
    • Custom Sectors
    • Pointer options
  • Methods
    • Refresh
    • Update
      • Update Options
    • Destroy
  • Demo
  • Examples
  • Changelog
    • BREAKING CHANGES
  • License
  • Author

Getting Started

Installing Justgage is as easy as...

bower install justgage-official

or maybe you wish to use NPM...

npm install justgage --save

• Example NPM setup using Browserfy

or you can always download the CSS and JS files...

<!-- Raphael must be included before justgage -->
<script type="text/javascript" src="path/to/raphael.min.js"></script>
<script type="text/javascript" src="path/to/justgage.js"></script>

or if even don't want to download the files use cdnjs

<!-- Raphael must be included before justgage -->
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/raphael/2.1.4/raphael-min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/justgage/1.2.9/justgage.min.js"></script>

Basic usage

Html

<div id="gauge"></div>

JS

var gauge = new JustGage({
            id: "gauge", // the id of the html element
            value: 50,
            min: 0,
            max: 100,
            decimals: 2,
            gaugeWidthScale: 0.6
        });

// update the value randomly
setInterval(() => {
  gauge.refresh(Math.random() * 100);
}, 5000)

Options

Name	Default	Description
id	(required)	The HTML container element id
value	0	Value Gauge is showing
parentNode	null	The HTML container element object. Used if id is not present
defaults	false	Defaults parameters to use globally for gauge objects
width	null	The Gauge width in pixels (Integer)
height	null	The Gauge height in pixels
valueFontColor	#010101	Color of label showing current value
valueFontFamily	Arial	Font of label showing current value
symbol	''	Special symbol to show next to value
min	0	Min value
minTxt	false	Min value text, overrides min if specified
max	100	Max value
maxTxt	false	Max value text, overrides max if specified
reverse	false	Reverse min and max
humanFriendlyDecimal	0	Number of decimal places for our human friendly number to contain
textRenderer	null	Function applied before redering text (value) => value return false to format value based on config options
onAnimationEnd	null	Function applied after animation is done
gaugeWidthScale	1.0	Width of the gauge element
gaugeColor	#edebeb	Background color of gauge element
label	''	Text to show below value
labelFontColor	#b3b3b3	Color of label showing label under value
shadowOpacity	0.2	Shadow opacity 0 ~ 1
shadowSize	5	Inner shadow size
shadowVerticalOffset	3	How much shadow is offset from top
levelColors	["#a9d70b", "#f9c802", "#ff0000"]	Colors of indicator, from lower to upper, in RGB format
startAnimationTime	700	Length of initial animation in milliseconds
startAnimationType	>	Type of initial animation (linear, >, <, <>, bounce)
refreshAnimationTime	700	Length of refresh animation in milliseconds
refreshAnimationType	>	Type of refresh animation (linear, >, <, <>, bounce)
donutStartAngle	90	Angle to start from when in donut mode
valueMinFontSize	16	Absolute minimum font size for the value label
labelMinFontSize	10	Absolute minimum font size for the label
minLabelMinFontSize	10	Absolute minimum font size for the min label
maxLabelMinFontSize	10	Absolute minimum font size for the man label
hideValue	false	Hide value text
hideMinMax	false	Hide min/max text
showInnerShadow	false	Show inner shadow
humanFriendly	false	convert large numbers for min, max, value to human friendly (e.g. 1234567 -> 1.23M)
noGradient	false	Whether to use gradual color change for value, or sector-based
donut	false	Show donut gauge
differential	false	Gauge will fill starting from the center, rather than from the min value
relativeGaugeSize	false	Whether gauge size should follow changes in container element size
counter	false	Animate text value number change
decimals	0	Number of digits after floating point
customSectors	{}	Custom sectors colors. Expects an object
formatNumber	false	Formats numbers with commas where appropriate
pointer	false	Show value pointer
pointerOptions	{}	Pointer options. Expects an object
displayRemaining	false	Replace display number with the value remaining to reach max value

Custom Sectors

Example:

customSectors: {
  percents: true, // lo and hi values are in %
  ranges: [{
    color : "#43bf58",
    lo : 0,
    hi : 50
  },
  {
    color : "#ff3b30",
    lo : 51,
    hi : 100
  }]
}

Pointer options

Example:

pointerOptions: {
  toplength: null,
  bottomlength: null,
  bottomwidth: null,
  stroke: 'none',
  stroke_width: 0,
  stroke_linecap: 'square',
  color: '#000000'
}

Methods

Refresh

Used to refresh Gauge value and max value

guage.refresh(val, max, min, label)

• val : The Gauge value (required)
• max : The Gauge Max value (optional)
• min : The Gauge Min value (optional)
• label : The Gauge label text (optional)

Update

Used to dynamically update existing Gauge appearence

gauge.update(option, value)

vs

const options = {
  valueFontColor: '#ff0000',
  labelFontColor: '#ff0000',
}
gauge.update(options)

Update Options

Name	Description
valueFontColor	HEX color for gauge value text
labelFontColor	HEX color for gauge min, max and label text

Destroy

Used to destroy the Gauge element

guage.destroy()

Demo

Click here to see a demo

Examples

Click here for a list of examples

Changelog

Check out the auto-generated Changelog

Or here you can find the old changelog (up to version 1.2.9)

BREAKING CHANGES

• 1.2.9
  • customSectors expects an object and not an array (percent support, check docs for more info)
• 1.2.6
  • Removed title feature

License

This project is licensed under MIT License

Author

• Bojan Djuricic

justgage's Issues

Trailing Comma causing "Expected identifier, string or number" in IE 7

Line 176

Currently:

• relativeGaugeSize : (config.relativeGaugeSize != null) ? config.relativeGaugeSize : false,

Should be:

• relativeGaugeSize : (config.relativeGaugeSize != null) ? config.relativeGaugeSize : false

Double gauge

How is possible to draw two ore more gauge that will be same at all

no method generateShadow on ie8

Noticed that justgage was not rendering on ie8. Method generateShadow was undefined. Once i commented the line out, ie8 was working again:

https://gist.github.com/4196707

I was using browserstack.com to test and the version of ie8 was:

Version 8.0.6001.19222
Update Versions: 0

thx!

more than 100

Can justgage handle more than 100? For example I would like to show the range 4000-5000.
Currently, the number shows up but gauge doesn't work.

Setpoint Gauge

Hello Bojan,

I was hoping to be able to use justgage to build a widget for monitoring energy setpoint devices.
The generic idea is, a device ideal value should to be something like, let's say 0.5, but it has a range of possible values between 0 and 1. The gauge would then need to grow from the "ideal value" either for greater or smaller values. Is something like this in the future plans for Justgage?

Cheers, and thank you!

erros in Safari and iOS

TypeError: 'undefined' is not an object (evaluating 'q.pct') in justgage.1.0.1.min.js:12

the gage doesnt seem to render correctly..

and my gage:
function gauge(val, cycle) {
var g1 = new JustGage({
id: "g1",
value: val,
min: 1,
max: cycle,
title: "Cycle",
label: "day",
gaugeWidthScale: 0.1,
startAnimationTime: 1400,
//gaugeWidthScale: 2.6,
labelFontColor: "#fff",
titleFontColor: "#fff",
valueFontColor: "#fff",
//gaugeColor: "#fff",
levelColors: [
"#33CC33",
"#33CC33",
"#33CC33",
"#33CC33",
"#33CC33",
"#FFCC00",
"#FF0000"
]
//levelColorsGradient: false,
});
}

works fine in chrome and other browsers. any ideas what is going on for the apple devices?

Gage does not show at all when value is 0

I'd like my gages to render even when the value is 0, I'm getting blank images at the moment when the value is 0, which is not very nice.

Remove title zone if title option is false

Generate without ID in DOM

Is it possible to generate a gauge without integrating it yet in the DOM ?
In my code, I am generating elements that I have not integrated yet in the page (so the document.getElementById() will not work).

Adding another optional argument to pass a canevas instead of an idea maybe ?

Thanks

Value text size

Hi,

I'm having some issues trying to resize the size of the value number in donut mode.
I was under the impression that it would scale according to the value number of digits.

Is it possible to declare a specific size, or better have it be recalculated according to the number of digits in the value?

Cheers

Not working with Foundation

If you try to show a gauge inside a foundation grid, everything is shown in a wrong way.

This is a sample code:

<html>
    <head>
        <script src="javascript/raphael.2.1.0.min.js"></script>
        <script src="javascript/justgage.1.0.1.min.js"></script>
        <script src="javascript/foundation.min.js"></script>
        <link rel="stylesheet" href="css/foundation.css">
    </head>

    <body>
        <div class="row">
            <div class="eight columns">  
                <button onclick="javascript:g.refresh(getRandomInt(0, 100));">Update</button>
            </div>
            <div class="four columns">  
                <div id="gauge" class="200x160px">
                </div>
            </div>
        </div>
    </body>

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

Enhancement: ability to add a target value, thresholds

Great job with this, really nice. I'm interested in using this to display real time (or near real time) metrics. For us, I think being able to set and visualise a target value that we want to hit, or a threshold that we need to stay inside would be really cool. Plus as an aside, being able to alert on leaving that threshold so that we can act on it.

I've forked the repo but if you have any ideas on this it'd be great to hear them. Will let you know I get on.

Tank Going empty on Refresh

Hello Toorshia :) ,
i put justgage with zero value on my page and when ajax call returned refresh gauges with new values and everything is OK , but sometimes the gauge tank unexpectedly become empty , sometimes one or two and sometimes all of them .

Render when value unknown

Use case is that the values for the gauge take a while to become available and I'd like the gauge to render before then. I'd like it to show "?" but if I pass in "?" the gauge won't render.

Can it render when the value is null or non-numeric and just show "?" or something?

Gradual colour change

This is a great library - thanks!

I have almost everything working, but i cannot for the life of me figure out how to get the green -> yellow -> red animation working. I have looked at the source for the web site demo and i think I am doing it right. Do i need to do something in addition to the following or is here something i am missing? tia.

    var g = new JustGage({
        id: "gauge",            
        value: 1247,
        min: 300,
        max: 2300,
        title: "Efficiency",
        levelColorsGradient:false
    });

To clarify. What i mean is that the user will see it at green, moving to yellow and red as the counter moves up. Actually ideally i could define a section to stay at green even if you are in the red zone, just so a user can visualize the cut-off.

Real Time Updates

I set up a demo page using one of your examples. I tried to set up a .get function to call a php page that updates the value of the gauge. When I run the php it returns the value that I want to get out of the database but the gauge shows "objectObject". I am echoing it back as what looks like a number to me. I was wondering if you might have an example that would show how to update the gauge using a .get function?

thousands separator ?

hello,
i need to display on the gauge with some big numbers like this one : 1 200 000 , but i didin't any way to do it. My gauge only display 1200000. And if i put a separator, the gauge is not visible. Can someone tel me how to make this easy?

Thx

Seems justGage does not allow max value greater than 1000

I've tested JustGage for my new application and the rendering is just great.

It's just that we cannot put a max value greater than 1000..

Is it possible to fix it ?

AD

Enhancement idea: Parameter to define the starting angle.

Hi, great gadget!

I've been trying to change the starting angle in the donut mode, but I haven't found any solution for it. I guess one have to change the pki function in someway. Can you help me? I would need to change the starting angle to -90 degrees.

Ps. There is a small bug on "this.canvas.customAttributes.pki", path variable should be defined as empty string (path = "";)... Otherwise there comes "undefined" in the start of the return string (at least in Chrome).

Cheers: Janne

Set labels

Hi

it would cool to force labels. For example, i use justgage to show durations which are stored in minutes in a database, forcing the label would allow me to format my current data in a more readable way :)

Regards

justgage used in layouts without a initial fixed size

Love your work!

When using justgage in a layout that is built in a responsive fashion (http://twitter.github.com/bootstrap/ etc) you inevitably have to place the gauges themselves in divs of no specific size. A responsive layout dictates that the layout will change depending on the platform/device/orientation/screen width - so the div size might be set with a grid layout that calculates a percentage.

Can this be achieved? Can justgage render a chart to a div that has it size calculated as opposed to specifically set?

FF 14, IE9 and Opera 12 are all happy to render an initial gauge that works - however there is no recalculating of the gauge size on resize. Chrome and Safari both have a mental breakdown and render vectors all about the place :)

Older IE's don't seem to render at all. This was just the result of a quick test.

Fix memory leaks

Check for memory leaks and do the plumbing :)

iOS and/or iPhone

Hi Guys,

Does this work on the iPhone or any-touch based device for that matter ? Would be awesome to be able to drag the indicator left or right ?

String in Min and Max value

Amazing script, absolut gorgeous

I just find a small "bug"(maybe)

When creating the gauge, the min and max values dont accept string, but the value does, the easy workaround is parseFloat on those strings on the creation:

g = new JustGage({
id: idElement,
value: valor,
min: parseFloat($(this).attr("data-min")),
max: parseFloat($(this).attr("data-max")),
title: label
});

Second, when creting a gauge with square div's it gets ugly (firefox and chrome at least)

by the way, I'd love se 360 degrees gauges!

This would make a nice component

as in component/component (also see http://tjholowaychuk.com/post/27984551477/components)

Display issue when using inside twitter bootstrap tabs

When used inside bootstrap tab-pane it displays as attached image.

Removing following css snippet from bootstrap resolved the problem. Though tabs stopped working.

.tab-content > .tab-pane,
.pill-content > .pill-pane {
display: none;
}

Hyperlinkable?

How to make the colored region in the gauge hyperlinkable?

uncaught TypeError: Object has no method 'toFixed' when using refreshmax

I'm seeing this error crop up when I use the .refresh method: http://prntscr.com/x0kuo

Any ideas? I could be doing something very wrong on my end.

Thanks,

-James

Use element object to introduce element to gauge

I can be helpfull to be able to use element object instead of id when constructing JustGage.

Android

I am sorry, but I are sure that it works on Android?

Raphael uses VML SVG.
In Android SVG does not work.

Font options

Add option to set font family, weight, etc.

Twitter bootstrap rendering problem.

I was trying to figuring out what in the css of TB is messing with your fantastic js, but I cant, can you please take a look of this demo? http://infoabout.me/ISS/admin/demo.html

New property valueShown (vs value)

I am in need to show something different than the actual value.

For example the value might be 3.5 but I want to show 3:30 (a time value).
Another example might be the value is 1,000,000 but I want to show 1 M.
Yet another 1,024 but I want to show 1 MB.

Great widget!

Regards,
Jaime

elem.node.firstChild.attributes.dy is undefined

Hello,

I have an error in firefox (works fine in chrome) for the setDy method for the txtValue object. In the javascript console of firefox I have got :

Unexpected value meet parsing preserveAspectRatio attribute.
elem.node.firstChild.attributes.dy.value = 0;

It works for the first calls (with ids being numbers), it fails with id myid-txtValue
The quick fix I did was to replace the if in the code by

if ((!ie || ie > 9) && (elem.node.firstChild.attributes.dy)) {

But I assume it is not the correct behavior.

Double Gauges - two values one gauge

Hi - wouldn't it be great to have two values in one gauge? Like this mockup:

I would like to display temperature and humidity sensors - that would allow me to display both values in one gauge...

great project - thanks for making it available

JustGage and bootstrap from twitter

Hi,

I have problem with this library when I use twitter bootstrap as well.

Look at http://i.imgur.com/T2CA0.png . The shape of the gage is a little deformed. I used a example from the distribution. There is not any modification from my side.

It's possible, the error is not on library side, but i don't know how to solve this.

Please, have someone some advice?

refresh max

Hello toorshia, greate work! Is it possible to refresh the max-value?
Does any one know how I can solve the problem? Maybe destroy and create new? How I can destroy/delete the gaug? Greetings from Germany

Strange rendering issue.

I was just trying to build a simple layout, and I'm seeing some strange behaviour using JustGage.

It looks like the dy value is getting set, and with a non-zero dy value things some things have the dy value applied, whilst others do not.

If you try the following html, you will see the problem:

<!doctype html>
<html>
<head>
<title>Layout 1</title>
<script type="text/javascript" src="raphael.2.1.0.min.js"></script>
<script type="text/javascript" src="justgage.1.0.1.min.js"></script>
</head>
<body>
<style>
#container { 
    /* fixed cotainer */
    margin:0px auto;
    width:900px;
    height:700px;
}
div {
    /* enable to see div positions */
    box-sizing:border-box;
    -moz-box-sizing:border-box;
    -webkit-box-sizing:border-box;
    border: 1px dotted black;
}
#dash_layout1 {
    margin:0px auto;
    height:100%;
    width:100%;
}
#dash1_dials {
    width:100%;
    height:33.333%;
}
.dash1_dial {
    width:25%;
    height:100%;
    float:left;
}
.dash1_chart {
    clear:both;
    width:100%;
    height:33.333%;
}
#dash1_chart2 {
    clear:both;
    width:100%;
    height:33.333%;
}
.clear {
    clear:both;
}
#dialtest {
    display:inline-block;
    width:100%;
    height:100%;
}
</style>
<div id="container">
    <div id="dash_layout1">
        <div id="dash1_dials">
            <div id="dash1_dial1" class="dash1_dial">
                <div id="dialtest"/></div>
            </div>
            <div id="dash1_dial2" class="dash1_dial">
                DIAL
            </div>
            <div id="dash1_dial3" class="dash1_dial">
                DIAL
            </div>
            <div id="dash1_dial4" class="dash1_dial">
                DIAL
            </div>
        </div>
        <div id="dash1_chart1" class="dash1_chart">
            CHART
        </div>
        <div id="dash1_chart2" class="dash1_chart">
            CHART
        </div>
    </div>
</div>
<script>
  window.onload = function(){
    var g1 = new JustGage({
        id: "dialtest", 
        value: 6000, 
        min: 0,
        max: 12000,
        title: "Test"
      }); 
  }
</script>
</body>
</html>

refresh during startAnimation issue

If you have a long startAnimation and call refresh before it completes your meter zeroes out.

example
http://jsfiddle.net/tablatronix/CM8vD/

Labels placement when in donut mode

When in donut mode, the labels are being placed over the graphic.

Arc angle option

Implement parameter to define arc angle. Currently fixed to 180, should be anywhere from 0 to 360 (donut).

Value parameter in object instance not updated on change

Update value parameter in object's instance config after value change

Make a "knob" mode to support setting values

The value would be set by dragging value indicator left / right.
Should also support touch-based interfaces.

Further control over labels, colours,fonts and adornments

:)

Could I have more control over what is displayed in the UI?

I would love to be able to set or remove each label/string. Having just the vector arc is a very attractive prospect.

Setting the colour of each label/string is also a big want.

Setting an adornment for each string is also attractive (might be a "%" or a "$", eg 76% or $99 or 173°)

I'll keep on thinking!

Gauges don't respond to window resize in fluid layouts

In fluid layouts, everything updates when the window is resized, maximized, etc - but the gauges don't adjust. I might be blanking on something that should be handled in the layout itself, but I really can't think of anything.

Using fluid layout in Bootstrap.

Start angle of gauge value

Add option to define start angle when in donut mode. Currently fixed at 180deg, should be anywhere from 0 to 360.

Custom Colors for Bar

Is it possible to change the colors for the different values? EG: 100% green instead of red.

One gauge doesn't show the result

Again, one gauge ranged 4500-5000 shows only number. While i'm out, the issue#34 was closed, but I've set up min and max already for each gauge like below. Can this show more than 1000?

 var gage7 = new JustGage({
    id: "g7",
    value: oxhz_val, 
    min: 4500.0,
    max: 5000.0,
    title: "Oxgen Hz",
    label: ""
  });     

Spelling

From the homepage:

JustGage is a handy JavaScript plugin for generating and animating nice & clean gauges. It is based on Raphaël library for vector drawing, so it’s completely resolution independant and self-adjusting.

independant should be independent

counter: true makes max show up as value

Refreshmax works great, btw, so thanks for that feature!

Counter is very cool. However I noticed that when I turn it on, in some cases (couldn't nail down the root cause) the max value was used instead of the actual value field. This happened when putting specific #'s into the value: field. Here's an example.. value: 520, min: 0, max 77, so maybe something to do with the max being less than the value.

Also looks like showMinMax doesn't work any more. They are always showing. Decimals seems to work well!