uvCharts

Introduction

uvCharts is a JavaScript based charting library built using the famous d3.js library. uvCharts lets you skip all the tough learning and coding part involved with d3.js and yet build simple, robust, completely customisable charts on any page on the web with utmost ease.

You'll have to include both d3.js and uvCharts on any webpage where you wish to use the library.

<script type="text/javascript" src="$PATH_TO_D3JS"></script>
<script type="text/javascript" src="$PATH_TO_UVCHARTS"></script>

Quick Start Guide

If you want a whirlwind 5 minutes tour of how to use uvCharts within your web page, do read our Quick Start Guide.

API

We started off wanting to make it easier for people to harness the power of d3.js and at the end, we've managed to build something really amazing, a single function API for all your charting needs. In the lighter sense, We call it the one function to rule them all (charts, we mean).

var chartObject = uv.chart(chartType, graphDefinition, optionalConfiguration)

The function returns a uvChart object which exposes d3 selections so more adventurous users can harness the power of d3 even after the chart is created.

Chart Types

A charting library is only as strong as the no.of Charts it supports and we currently support 12 with definite expansion plans on this front.

The first parameter of uv.chart is Charttype which defines the type of chart rendered by uvCharts. You'll have to pass in a chart type string as mentioned in the table below based on which type of chart you prefer to see your data in.

Chart Type	Key String
Bar Chart	'Bar'
Line Chart	'Line'
Area Chart	'Area'
Stacked Bar Chart	'StackedBar'
Stacked Area Chart	'StackedArea'
Pie Chart	'Pie'
Percent Bar Chart	'PercentBar'
Percent Area Chart	'PercentArea'
Donut Chart	'Donut'
Step Up Bar Chart	'StepUpBar'
Polar Area Chart	'PolarArea'
Waterfall Chart	'Waterfall'

Graph Definition

The second parameter to our function is Graph Definition, which is a representation of the data which uvCharts can comprehend. Its a simple JSON object with 2 name-value pairs, categories and dataset.

var graphdef = {
	categories : [],
	dataset : {}
}

Categories:

Categories is an array of strings, each representing a series of data. Categories not only defines which series of data among the dataset is rendered in the final chart but also the order in which it is rendered.

A single element category array will define a single series chart whereas any number more than that will lead to a multiseries chart except in the case of Pie, Donut, Polar Area in which only the first Category will be rendered in the final chart.

var graphdef = {
	categories : ['uvCharts', 'Matisse', 'SocialByWay'],
	dataset : {}
}

Dataset:

Dataset is the details of the data corresponding to each series mentioned in the categories array. There can be data for other series too, those are simply ignored by the uvCharts library.

A dataset per category is an array of Objects. Each object containing 2 key-value pairs: name, the label corresponding to that data element and value, the measure itself.

var graphdef = {
	categories : ['uvCharts', 'Matisse', 'SocialByWay'],
	dataset : {
		'uvCharts' : [
			{ name : '2008', value: 15},
			{ name : '2009', value: 28},
			{ name : '2010', value: 42},
			{ name : '2011', value: 88},
			{ name : '2012', value: 100},
			{ name : '2013', value: 143}
		],
		'Matisse' : [
			{ name : '2008', value: 15},
			{ name : '2009', value: 28},
			{ name : '2010', value: 42},
			{ name : '2011', value: 88},
			{ name : '2012', value: 100},
			{ name : '2013', value: 143}
		],	
		'SocialByWay' : [
			{ name : '2008', value: 15},
			{ name : '2009', value: 28},
			{ name : '2010', value: 42},
			{ name : '2011', value: 88},
			{ name : '2012', value: 100},
			{ name : '2013', value: 143}
		]
	}
}

Configuration

The third parameter, Configuration, is optional yet an important parameter because inside it lies the entire ability to customise the chart from the colors used to the font size, styles, padding and more.

Configuration is a plain JavaScript object with group-like sub-objects which segregate the various configurable properties.

The structure of a configuration is like:

var config = {
	groupname1 : {
		property1 : value1,
		property2 : value2,
		property3 : value3
	},
	
	groupname2 : {
		property4 : value4,
		property5 : value5
	}
}

Group name and their corresponding properties follows: