Animation and visual effects that are available in RGraph

Documentation about the animation and visual effects that are available to you in RGraph. A CSS library is also supplied which provides numerous CSS based effects.

 

Introduction

The animation and visual effects code is available in RGraph from August 2011. It greatly simplifies the process of animating your graphs or using visual effects.

The old way of using effects:
<script>
    bar = new RGraph.Bar('cvs', [3,6,5])
        .set('margin.left', 50)
        .set('xaxis.labels', ['John','Fred','Lucy'])
    RGraph.Effects.Bar.Grow(bar)
</script>
The new way of using effects:
<script>
    new RGraph.Bar({
        id: 'cvs',
        data: [3,6,5],
        options: {
            marginLeft: 50,
            xaxisLabels: ['John','Fred','Lucy']
        }
    }).grow();  
</script>

 

Example use

To use the effects, you simply change your call to the draw() method to the appropriate effect function, like this:

<script src="RGraph.common.core.js" ></script>
<script src="RGraph.common.effects.js" ></script>
<script src="RGraph.line.js" ></script>

<!-- Only needed for some effects (eg generic effects, scatter chart trace etc) -->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js" ></script>

<script>
    new RGraph.Line({
        id: 'cvs',
        data: [
            [14,13,16,18,14,12,11,14,19,18,17,18],
            [11,12,14,12,11,13,13,15,14,15,13,14]
        ],
        options: {
            xaxisLabels: ['Jane','Geoff','Lou','Pob','Verity','Baz','Hue','Olga','Pete','Lou','Kev','Fred'],
            marginTop: 35,
            marginLeft: 40,
            marginRight: 5,
            marginBottom: 10,
        }
    }).fadeIn(); // Was .draw()    
</script>

 

CSS animation vs <canvas> animation

CSS animation (which the generic jQuery effects are) can be smoother than canvas animation (ie changing the CSS properties vs redrawing the canvas). This is because CSS animation (ie changing the CSS properties) does not have the side effect of clearing the canvas, so does not incur redraws. As such you may find that choosing a CSS based effect instead of a canvas based effect is smoother. Also you may wish to use the CSS3 animations library if you don't need to support older browsers (or you could use one effect for modern browsers and another effect for older browsers).

An alternative to the widely known and understood setTimeout() function is the newer requestAnimationFrame(). This is a function which has been optimised for animation compared to the older setTimeout() function. Some of the animation functions use this over the setTimeout() function and going forward newer animation functions will use it. RGraph has a fall-back though so that if the function isn't available the older setTimeout() will be used.

 

CSS3 animations

If you're interested in animating your charts then you may also be interested in new CSS animations. These are new to CSS and as such browser support is not complete (Chrome, Firefox, IE10, Safari, Opera) but they can be a very easy and efficient way to add effects to your charts.

Note: The front page effect is one of these CSS animations (but not in IE9 or lower) - called expand.

 

Combining effects

Some of the animation effects (ie those that work on separate aspects of the chart) can be combined. As an example the fade in/out can be combined with most other animation effects, allowing you to add a fade effect to the other animation types. An example of this is below - this chart uses the grow() and fadeIn() effects.

[No canvas support]
<script>
    // A global variable on purpose
    bar = new RGraph.Bar({
        id: 'cvs',
        data: [30, 32, 33, 30, 27, 30, 29, 27, 21, 21, 21,19],
        options: {
            yaxisScaleUnitsPre: '$',
            title: 'Sales in the last 8 months',
            titleVpos: 0.5,
            colors: ['Gradient(#fdd:red)'],
            marginTop: 40,
            marginBottom: 50,
            marginLeft: 40,
            marginRight: 15,
            shadowBlur: 3,
            shadowColor: '#bbb',
            backgroundBarsColor1: 'white',
            backgroundBarsColor2: 'white',
            grouping: 'stacked',
            xaxisLabels: [
                'January', '\r\nFebruary',
                'March', '\r\nApril',
                'May', '\r\nJune',
                'July', '\r\nAugust',
                'September','\r\nOctober',
                'November','\r\nDecember'
            ],
            labelsAbove: true,
            colorsStroke: 'rgba(0,0,0,0)'
        }
    })

    function showCombination(obj)
    {
        obj.fadeIn().grow()
    }
</script>

<button onclick="showCombination(bar)">Show Combining animations example</button>

 

Available effects

The effects that are available are listed on each charts documentation page and you can also see all of the effects easily by looking at the demos that are bundled with RGraph in the download archive. You can also use the jQuery animate() function to animate the <canvas> tag and its CSS properties.

 

Things to note

  1. With Fade in/out effects remember that just because you can't see the canvas (ie the opacity is 0) doesn't mean that you can't interact with it, so tooltip hotspots will still be active. If you want to get rid of the canvas entirely you need to remove it from the DOM. You can do this with the standard removeChild() function:
    obj.canvas.parentNode.removeChild(obj.canvas)
    This will leave a hole in the page though and will cause the page layout to change. If this is an issue you may want to use the jQuery wrap() function first (which wraps a DIV around the <canvas> or the RGraph wrap() function (which essentially does the same thing):
    var div = RGraph.Effects.wrap(canvas);
    The function replaces the canvas with a DIV which has the same dimensions meaning your page structure won't change.
  2. Because canvas based animations may need to redraw the entire chart, they can be slower than CSS based animations and depend on a variety of things - eg the speed of the user's PC and the work necessary to redraw the canvas.

    Note: If you're using a chart with a background grid along with a canvas based effect you can increase the frame rate by turning off the background grid - the background grid has shown itself to be a drain on performance.