README.md

Backbone.ZingChart

Turning simple Models and Views into snazzy charts.

About

Backbone.ZingChart is a lighweight Backbone extension that allows for fast and simple creation of charts with a traditional Model and View structure.

Installation

Use our CDN: The easiest way to get started with backbone.zingchart is to use our snazzy CDN. Just paste these scripts in your HTML file after your backbone.js file.

<script src="cdn.zingchart.com/zingchart.min.js"></script>
<script src="cdn.zingchart.com/backbone/backbone.zingchart.min.js"></script>

The first script loads the ZingChart file and the second one loads the actual backbone.zingchart wrapper. Both are necessary for this wrapper to work.

Install with Bower: The next simplest solution is to install via bower. Just use bower install backbone-zingchart and reference the script in your HTML file after your backbone.js file.

Git Clone: Alternatively, you could simply clone this repo.

Getting Started

View the files in the example directory for working samples.

You must have the ZingChart library loaded. We suggest you use our CDN to keep up to date with the latest build.

In addition, you must include this library. We support inclusion through require.js and you can view an example in the examples directory. For now, we will do a simple script include.

A simple example:

// Create ZingChart Model Passing in Data to Plot
var chartData = new ZingChart.ZingChartModel(
            {
                data: [[3,2,3,3,9] , [1,2,3,4,5]],
                charttype: 'bar',
                width: 500,
                height: 400
            });


// Render the Chart
// Note that the el must already be added to the DOM
var chartView = new ZingChart.ZingChartView({model: chartData, el: $('#chartDiv')});
chartView.render();

Passing in a full JSON structure:

var json = {    
            "type":"pie",
            "series":[
                {
                    "text":"Apples",
                    "values":[5]
                },
                {
                    "text":"Oranges",
                    "values":[8]
                },
                {
                    "text":"Bananas",
                    "values":[22]
                }
            ]
        };
        
var chartData = new ZingChart.ZingChartModel(
            {
                json: json
            });


// Render the Chart
// Note that the el must already be added to the DOM
var chartView = new ZingChart.ZingChartView({model: chartData, el: $('#chartDiv')});
chartView.render();

After the chart is rendered, it is possible to change the json or data simply by updating the ZingChartModel.json or ZingChartModel.data property respectively.

Change the Chart Data:

var newData = [
	[50,32,36,8,10],
	[34,64,23,54,41],
	[12,43,51,39,29]
];

chartData.set('data', newData);

Change the entire Chart JSON:

var newJSON = {
	"type":"area",
	"series":[
	   	{
       	"values":[11,36,7,44,11,28,42,26,13,32,12,24,16,11,43,39]
	   	},
	   	{
       	"values":[21,29,14,16,28,35,21,18,11,7,4,9,25,15,33,13]
	   	}
	]
};
  
chartData.set('json', newJSON);

The Extension includes full access to the ZingChart API methods and events.

You can access the API methods by calling the view's exec method.

var values = [39,26,54,28,51,44];

chartView.exec('addplot', {
	data : {
   		values : values
   }
 });
  

If you include the extended javascript file, there is individual access to every API method.

var values = [39,26,54,28,51,44];

chartView.addPlot({
	data:{
   		values: values
   }
});

You can access the API events by using the view's bind method to bind to the ZingChart events.

chartView.bind('legend_item_click', myClickCallback);

If you include the extended javascript file, there is individual access to all of the events.

chartView.legendItemClick(myClickCallback);

ZingChart.ZingChartModel

Represents ZingChart object. Extends Backbone.Model.

Properties

Property	Default Value	Description
charttype	line	The chart type. Only used if rendering from data and not from full JSON
data	[]	Array of chart data. A chart can be automatically generated based soley on the data.
defaults	{}	Object of default render settings. Can be used to apply settings to all charts rendered from that model, even ones rendered from updates to json or data
height	480	The height of the rendered chart.
json	{}	A complete ZingChart JSON packet.
width	640	The width of the rendered chart.

Documentation

ZingChart.ZingChartView

View controller for a ZingChart.ZingChartView. Extends Backbone.View.

Properties

Property	Default Value	Description
el		The el where the chart should be rendered. The el must already be included in the DOM.
model	ZingChart.ZingChartView	The model that is used to generate the ZingChart.

Methods

Method	Parameters	Return Value	Description
render			Renders the ZingChart in the given el based on the ZingChartModel data.
bind	eventname, callback	this	Binds the ZingChart event to the given callback. View ZingChart Events
exec	apimethod, apioptions	The results of the API call	Calls a ZingChart API method and passes it the given options. View ZingChart Methods

In The Wild...

Here at ZingChart, we're currently using this extension on our gallery chart view. It allows us to tie the a ZingChartModel and ZingChartView to our Chart view, allowing for streamlined updating of charts via AJAX. The result is a smaller codebase and less boilerplate.

If you're using the backbone-zingchart extension on your own project, let us know! We'd love to feature it.

Issues

Found a bug or have a feature request? Submit an issue and we'll get to work.