Animation and visual effects

Share RGraph:   

Summary
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.

Update for upgraders

Starting with RGraph3 the chart-specific effects have been moved to be contained in each charts file - so there is no need to also include the effects file (RGraph.common.effects.js). The generic effects (eg the fade in/out effects) are still held in this file so if you use one of these you will still need to include the effects file.

The old way of using effects:
<script>
    var bar = new RGraph.Bar('cvs', [3,6,5])
        .set('gutter.left', 50)
        .set('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: {
            gutterLeft: 50,
            labels: ['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: {
            labels: ['Jane','Geoff','Lou','Pob','Verity','Baz','Hue','Olga','Pete','Lou','Kev','Fred'],
            gutterTop: 35,
            gutterLeft: 40,
            gutterRight: 5,
            gutterBottom: 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, and 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 fallback 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 suport is not complete (Chrome, Firefox, IE10, Safai, 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: {
            unitsPre: '$',
            title: 'Sales in the last 8 months',
            titleVpos: 0.5,
            colors: ['Gradient(#fdd:red)'],
            gutterTop: 40,
            gutterBottom: 50,
            gutterLeft: 40,
            gutterRight: 15,
            shadowBlur: 3,
            shadowColor: '#bbb',
            backgroundBarcolor1: 'white',
            backgroundBarcolor2: 'white',
            grouping: 'stacked',
            labels: [
                'January', '\r\nFebruary',
                'March', '\r\nApril',
                'May', '\r\nJune',
                'July', '\r\nAugust',
                'September','\r\nOctober',
                'November','\r\nDecember'
            ],
            labelsAbove: true,
            strokestyle: '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 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 users 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 increase the frame rate by turning off the background grid - the background grid has shown itself to be a drain on performance.

Comments

Add a new comment...