Configuring RGraph using JSON

New in July 2014 is the ability to use a JSON structure to configure your charts instead of (or as well as) the .set() method that has served RGraph very well for the last six years. The .set() method of configuration is by no means going away - in fact the new JSON method is parsed and then the .set() method is used to set the properties. This is because the .set methods of the various objects incorporate some backwards compatibility checking and modifications as well as just setting the properties.

"If that's the case - then why change everything to the new method?" you may ask. The JSON configuration looks and feels more natural, communicates the configuration intent better (because of the nesting) and minifies to a marginally smaller size.

But - this does not mean that you have to upgrade to the newer syntax if you don't wish to. If you want to continue to use the established style you can -it's not going away.

 

What does it look like?

There are two ways of using it - and neither has an advantage over the other. Which you use is down to your own personal preference. The first is the one that the RGraph site uses (incidentally this is the code that's used on the front page):

// Create the Bar chart using the new keyword as you would previously. The only argument though is a JSON object.
// Here a tree-like JSON structure is used for the configuration.
var bar = new RGraph.Bar({

    // The id of the canvas tag
    id: 'cvs',
    
    // The data that the Bar chart represents. Other charts may use different names (eg min/max/value
    // for dials - see the demos and
    // the individual docs pages for more information)
    data: [[45,56],[75,32],[39,47],[34,48],[46,47],[48,52]],
    
    // These are options that previously would be set by the .set() function
    options: {
        shadow: false,
        strokestyle: 'rgba(0,0,0,0)',
        grouping: 'grouped',
        colors: ['Gradient(white:#aaf:#aaf:#33f:#33f)','Gradient(white:#faa:#f33:#f33:#f33)'],
        
        // In options that contain a dot (eg background.grid.vlines) nesting is used in place of the period
        background: {
            grid: {
                vlines: false,
                border: false
            }
        },
        text: {
            color: 'white'
        },
        labels: ['2007','2008','2009','2011','2012','2013'],
        clearto: 'black'
    }
// When the configuration is finished the .draw() or animation functions can be called
// (in effect they're chained to the constructor)
}).wave()

The second way of using JSON configuration is by using quotes around the key names (which in theory is a requirement for JSON). This allows you to use dots in property names and nesting is no longer necessary. The above JSON becomes:

// Using quotes around property names
var bar = new RGraph.Bar({
    'id': 'cvs',
    'data': [[45,56],[75,32],[39,47],[34,48],[46,47],[48,52]],
    'options': {
        'shadow': false,
        'strokestyle': 'rgba(0,0,0,0)',
        'grouping': 'grouped',
        'colors': ['Gradient(white:#aaf:#aaf:#33f:#33f)','Gradient(white:#faa:#f33:#f33:#f33)'],
        'background.grid.vlines': false,
        'background.grid.border': false,
        'text.color': 'white',
        'labels': ['2007','2008','2009','2011','2012','2013'],
        'clearto': 'black'
    }
}).wave()

If you want to scrape every possible extraneous character out of the conguration then you could in theory leave out the quotes around the single word properties. Like this:

// Only use quotes around property names that have a dot in them
var bar = new RGraph.Bar({
    id: 'cvs',
    data: [[45,56],[75,32],[39,47],[34,48],[46,47],[48,52]],
    options: {
        shadow: false,
        strokestyle: 'rgba(0,0,0,0)',
        grouping: 'grouped',
        colors: ['Gradient(white:#aaf:#aaf:#33f:#33f)','Gradient(white:#faa:#f33:#f33:#f33)'],
        'background.grid.vlines': false,
        'background.grid.border': false,
        'text.color': 'white',
        labels: ['2007','2008','2009','2011','2012','2013'],
        clearto: 'black'
    }
}).wave()

 

How the new configuration works

To use the new style configuration lets start by looking at a set of current configuration parameters:

var obj = new RGraph.Line('cvs, [4,8,6,3,5])
    .set('gutter.left', 50)
    .set('gutter.right', 5)
    .set('tickmarks', 'endcircle')
    .set('background.image', '/images/bg.png')
    .set('background.image.stretch', true)
    .draw()

The basic starting point for the new configuration looks like this. The constructor is passed a single JavaScript object which contains the id, data and options.

var obj = new RGraph.Line({
    id: 'cvs',
    data: [4,8,6,3,5],
    options: {
    }
}).draw()

This will create a Line chart using the default settings. So now we can add in the tickmarks setting:

var obj = new RGraph.Line({
    id: 'cvs',
    data: [4,8,6,3,5],
    options: {
        tickmarks: 'endcircle'
    }
}).draw()

For simple one word configuration options the above example works just fine. But for configuration options that contain a period you can use nesting (ie a tree like structure) like this:

var obj = new RGraph.Line({
    id: 'cvs',
    data: [4,8,6,3,5],
    options: {
        tickmarks: 'endcircle',
        gutter: {
            left: 50,
            right: 5
        }
    }
}).draw()
The last type of option is where a property can contain a value and also there are child options. Like this:
obj.set('background.image', '/images/bg.png');
obj.set('background.image.stretch', true);

In this case the object which contains the child options can also contain a self option. This is the value that is applied to the parent option.Here's an example of this in practice:

var obj = new RGraph.Line({
    id: 'cvs',
    data: [4,8,6,3,5],
    options: {
        tickmarks: 'endcircle',
        gutter: {
            left: 50,
            right: 5
        },
        background: {
            image:
                self: '/images/bg.png', // background.image = /images/bg.png
                stretch: true           // background.image.stretch = true
            }
        }
    }
}).draw()

 

Using the new configuration syntax with the setter functions

If you need to use the setter function you can either use the established way - one option per call - or you can supply an object to the setter in a similar way to how you can with the constructor. For example - this is the established way (making use of chaining):

obj.set('gutter.left', 35)
   .set('gutter.right', 5)
   .set('background.grid.vlines', false)
   .set('background.grid.autofit.numhlines', 10)

And this is how you can now use an object with the setter functions. The format is the same as when you use an object with the constructor - except that you don't have to give an id, any data or nest the key/value pairs within an options property. So it looks like this:

obj.set({
    gutter: {
        left: 35,
        right: 5
    },
    background: {
        grid: {
            vlines: false,
            autofit: {
                numhlines: 10
            }
        }
    }
})

 

Examples of the new configuration style

Examples of each chart type are available on the options reference pages . All of the demos that are in the RGraph archive have also been updated to the new style.