Home

VizShare lets you reuse visualisations easily with only a few lines of extra code.

At the moment lots of great visualisations are being created but we’re getting very little reuse out of them. Typically someone will copy visualisation code from somewhere like the D3 website and adapt it to their needs by changing the hard coded data fields to their own data. By taking the hard coded field references out of the javascript code we can make our visualisations much more reusable.

VizShare lets you put a wrapper around your visualisation to separate the visualisation code from the data definition. You supply the data fields when you render the visualisation by passing a JSON structure which matches up the references used in the visualisation code with the names of the fields in the real data.

VizShare is agnostic about which visualisation libraries you use. By having lots of visualisation plug-ins we can create reusable libraries that can be shared amongst different applications.

Basic Usage

VizShare comes with some basic renderers to get you started. Here's how to draw a visualisation:

vizshare.render({
    rendererName: "vizshare.barchart", // Use the default bar chart renderer
    selector: "#output",               // CSS style selector where you want the output to appear
    data: dataSettings,                // The data settings - see below
    vizOptions: {}                     // Any visualisation settings
});

You'll need to include the js libraries libraries used by the default renderer in your html page. You can see a full example in the default renderer example.

<script src="js/jquery-1.7.1.js"></script>
<script src="../lib/d3.min.js"></script>
<script src="../lib/vega.min.js"></script>
<script src="../vizshare-0.1.0.js"></script>
<script src="../lib/vizshare-renderers-0.1.0.js"></script>

You can reuse the same renderer with any number of datasets. For each dataset just create a JSON data mapping which matches the field names used in the renderer to fields in a CSV file.

var dataSettings = [
    {
        "name": "default",
        "url": "data/data1.csv",
        "contentType": "text/csv",
        "fields": [
            {
                "vizField": "xAxis",
                "dataField": "Country"
            },
            {
                "vizField": "yAxis",
                "dataField": "Number"
            }
        ]
    }
];

The data mapping is an array of datasets as some renderers will use more than one dataset. We only need one dataset for the bar chart example. Let's look at the data mapping in a bit more detail.

Each dataset gets a name so the visualisation code can find the right dataset ("default" in this case). It contains a url to point to the location of the data ("data/data1.csv" - note: inline data coming soon). The content type lets the renderer know how to load the data ("text/csv").

The 'fields' property of the dataset mapping matches up references used in the visualisation code with the name of the field in the data. We can see the data field name 'Country' should be used for 'xAxis' in the visualisation code, and the 'Number' field should be used for 'yAxis'. The CSV file may have more fields than the ones mentioned ('Country' and 'Number'), but they are the only ones used in this visualisation.

The Visualisation Wrapper

The basic renderers are there for simple cases or inspiration. VizShare is all about sharing our rendering code, so let's look at how you build your own renderers.

We start off by putting our visualisation rendering code into a wrapper function. This function is then registered with VizShare. Later, when the function is called, the 'dataHelper' parameter will be populated with a helper which makes it easier to fetch the field names from the data. Here's the template for a render function:

var renderBarChart = function (selector, dataHelper, vizSettings) {
    // References to look up in the data mapping JSON (see data mapping example above)
    var dataSetRef = "default",
        xAxisFieldRef = "xAxis",
        yAxisFieldRef = "yAxis",

        // Actual field names in the data
        dataset = dataHelper.getDataset(dataSetRef),
        fieldXAxis = dataset.getDataField(xAxisFieldRef),
        fieldYAxis = dataset.getDataField(yAxisFieldRef);

    // Create the visualisation and write it to the html selector (selector)
    // based on actual data fields.
    // Based on the example data mapping above, the fieldXAxis variable will 
    // have the value 'Country' and fieldYAxis will have the value 'Number'

The rendering function can be registered with VizShare like so:

var rendererName = "mycompany.barchart",           // The name of the renderer
    rendererOpts = {'renderFunc': renderBarChart}; // Set the renderer options
vizshare.registerRenderer(rendererName, rendererOpts);

The render function is wrapped in a render options object so further options can be added later. The renderer name let's us call the renderer again in the future. It's probably a good idea to use a 'namespace' in the renderer name, for example the name of your organisation, so it doesn't clash with visualisations made by other people used in the same page.

Finally to render the code you just call the render function on VizShare with a valid data mapping:

vizshare.render({
    rendererName: "mycompany.barchart", // The name of the renderer to use
    selector: "#output",                // CSS style selector to identify html tag to render to
    data: {...},                        // See data mapping example above
    vizOptions: {}                      // Any viz options supported by rendering function
});

Please see the examples directory for some sample code. For example this page shows the same bar chart renderer being reused with two different sets of data.

Note that VizShare makes no assumptions about the visualisation, it just gives you the option to pass through an object containing visualisation settings. The visualisation could be a bar chart, force directed graph, bouncing ball animation or some completely new visualisation type that uses a new methodology.

Coming soon...

• Renderer dependencies (CSS and javascript)
• Option for inline data
• Viz metadata - for validating data against what the viz expects
• Visualisation discovery - find a visualisation that matches your data