Charts

Code
Specific Chart Documentation and Demos

Overview

Web applications often need some sort of charts or graphs, but there are few viable options that aren't commercial, poorly-documented, bound up in a restrictive open source license, or Flash-based. The charts in VM UI Framework are SVG-based and responsive, meaning that you can use them easily for all modern browsers and devices. There are alse options for making each chart interactive and animated.

Return to top

Usage

There are five basic chart types, each of which has the ability to be customized. The chart type is assigned via class to a <div> element. Additional chart types like histograms and pyramid charts can be created by modifiying the basic chart types. Inline charts (sometimes called sparklines) are also possible by prefixing the word inline to the chart class.

Chart Types
Chart Types
Type Class Inline Class
Area chart areaChart inlineAreaChart
Bar chart barChart inlineBarChart
Line chart lineChart inlineLineChart
Pie chart pieChart inlinePieChart
Scatter chart scatterChart inlineScatterChart

Data is passed into a chart via the data-chartData attribute. The value for data-chartData should be an array of objects, formatted like the example below:

Chart Data Example
<div class="areaChart" data-chartData="[
{
	x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], 
	y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20]
},
{
	x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100],
	y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60]
}
]"></div>

Not all chart types will require both x and y values for each series. Some charts will support empty data sets and pie charts will accept only one series of data. See the documentation for each specific chart for more information.

Each chart also supports numerous options through the data-chartOptions attribute, which accepts a JSON-formatted string of options, which are detailed in the options section. An example of the data-chartOptions attribute formatting is below:

Chart Options Example
<div class="areaChart" data-chartData="[
	{
		x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], 
		y:[0,1,6,3,17,12,24,38,15,87,75,45,23,12,73,17,45,87,99,34,20]
	},
	{
		x:[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100], 
		y:[23,15,65,33,37,32,34,36,25,47,75,40,63,22,43,10,46,68,69,68,60]
	}
]"

data-chartOptions="{
	showAxisLabels: true, 
	showAxisLines: true, 
	showTicksY: true, 
	showTicksX: true,
	showIntervalLabels: true,
	showTitle: true,
	title: 'Axis & Labels'
}"></div>
Current Chart Limitations

Charts are very flexible and dynamic, but they have some limitations. Future versions may or may not fix these issues.

  • No animation in Internet Explorer or Safari. Charts will animate in other browsers, but remain static in current versions Internet Explorer and Safari.
  • Dates can only be on the x-axis.
  • Updating the graph requires refreshing the canvas. The chart will be erased and redrawn rather than manipulated directly. See the events section for more detail on how to update a chart.
  • Missing values are not supported. Each series must be continuous, without gaps.
When To Use Each Chart Type
Chart Use Cases
Chart Use Cases
Chart Type Use Cases
Area Chart Track one or more sets of data over time or to compare multiple sets of data. Area charts are similar in purpose to line charts, but provide more visual emphasis.
Bar Chart Compare many items in multiple categories to each other.
Column Chart Compare a few items to each other. Track a single or a minimal number of categories over time.
Histogram (bar) Compare many items in a single category to each other.
Histogram (column) Track a single variable over time. Chart the distribution of a single variable.
Inline Charts (any) Only use when the general scope of information is needed at a glance. If there is a need for specific data points, use a larger chart.
Line Chart Track one or more sets of data over time or to compare multiple sets of data.
Pie Chart Show the relationship of individual parts to the whole for a single series of data.
Pyramid Chart Compare two similar sets of data that differ in only one aspect.
Scatter Chart Show the relationship between or plot the distribution of two variables.

Return to top

Options

Not every option will apply to every chart type. See the documentation for each specific chart for relevant options for that particular chart. No options are required for the most basic chart types.

Chart Options
Chart Options
Option Description Default Value Values
animate Animates the chart. false true, false
animationDuration The duration of the chart animation in seconds. 1 Any positive number
axisColor The hex color of the axis lines. #333 Any hex color code as a string
aspectRatio The aspect ratio of the entire chart area, including labels and keys. [16, 9] An array of 2 positive integers [x, y]
colors The hex colors for each series of chart data. ['#058DC7', '#A006C7', '#C7062D', '#06C740', '#C7A006', '#EEE', '#CCC', '#999', '#666', '#333', '#000'] An array of hex codes [color1, color2, ...]
dataLabels Labels for each series of data, will also show in the key. If no labels are provided, labels will be 'Series 1', 'Series 2', etc. [] An array of strings equal to the number of series ['Label 1', 'Label 2', ...]
dateEnd Sets the end date for a time-based chart. xAxisIsDate must be enabled. null 'now' or any date string
dateFormat Formats the date by replacing placeholders in a string. xAxisIsDate must be enabled. '%b %d' A string of any combination of options from the MooTools Date Object
dateIntervalUnit Sets the inverval unit for a date. xAxisIsDate must be enabled. 'day' 'year', 'month', 'week', 'day', 'hour', 'minute', 'second', 'ms'
dateIntervalValue Sets the interval value for a date. xAxisIsDate must be enabled. 1 Any positive integer
dateStart Sets the start date for a time-based chart. xAxisIsDate must be enabled. null 'now' or any date string
decimalPrecisionX The number of decimal places shown on x-axis interval labels or pie tips; does not affect placement or other tip types. 0 0 or any positive integer
decimalPrecisionY The number of decimal places shown on y-axis interval labels; does not affect placement or any tips. 0 0 or any positive integer
gridColor The hex color of the grid lines. '#DDD' Any hex color string
histogram Removes the gap between columns or bars to create a histogram. false true, false
keyPosition The position of the key. The showKey option must also be enabled. 'bottom' 'top', 'bottom', 'left', 'right'
keyWidthPercentage The width percentage of the key in relation to the entire chart area, applicable only for left and right key positions. 12 Any positive integer
maxX The maximum value of the x-axis. null Any number
maxY The maximum value of the y-axis. null Any number
minX The minimum value of the x-axis. 0 Any number
minY The minimum value of the y-axis. 0 Any number
pyramid Turns a bar chart with exactly 2 data series, one with all positive values and the other with all negative values, into a pyramid chart. false true, false
showAreaLines Toggles a line chart overlay on an area chart. false true, false
showAxisLabels Toggles both the x and y axis labels. false true, false
showAxisLines Toggles both the x and y axis lines. false true, false
showGridX Toggles the x-axis grid lines. false true, false
showGridY Toggles the y-axis grid lines. false true, false
showIntervalLabels Toggles interval labels on both axises. false true, false
showIntervalLabelsX Toggles interval labels on the x-axis. false true, false
showIntervalLabelsY Toggles interval labels on the y-axis. false true, false
showKey Toggles the chart key. false true, false
showLineFill Toggles an area chart overlay for line charts. false true, false
showPoints Toggles individual data points for area and line charts. false true, false
showTicksX Toggles tick marks along the x-axis. false true, false
showTicksY Toggles tick marks along the y-axis. false true, false
showTips Toggles tooltips for all charts. Line charts and area charts must have showPoints enabled for tips to show. false true, false
showTitle Toggles the chart title. false true, false
textColor The color of all text in the chart. "#000" Any hex color string
title The title of the chart. "Untitled Chart" Any string
tickColor The color of all tick marks. "#333" Any hex color string
tipText An array of HTML text strings to customize the tip text, one string for each series. Placeholders in the string (surrounded by curly braces {}) can be replaced by values or labels from the chart. Placeholders options include: {x}, {y}, {xAxis}, {yAxis}, {piePercent} and {label}. [] An array of HTML strings with placeholders, one string for each series
xAxisLabel The label for the x-axis. "x-axis" Any string
xInterval The interval for the x-axis. 25 Any positive number
xAxisIsDate Toggles the date options for a chart. Any coordinate values for the x-axis entered in the data-chartData attribute will be ignored. false true, false
xLabels An array of labels for the x-axis matching the number of intervals. If no labels are entered, the chart will default to using numbers. To skip labels for an interval, use null as a placeholder in the array. [] An array of any combination of numbers, strings, or nulls matching the number of intervals
yAxisLabel The label for the y-axis. "y-axis" Any string
yInterval The interval for the y-axis. 25 Any positive number
yLabelWidthPercentage The width percentage (in relation to the entire chart area) of y interval labels, if they are enabled. 5 Any positive number
yLabels An array of labels for the y-axis matching the number of intervals. If no labels are entered, the chart will default to using numbers. To skip labels for an interval, use null as a placeholder in the array. [] An array of any combination of numbers, strings, or nulls matching the number of intervals

Return to top

Events

Each chart type has an updateChart event, which allows the chart to be updated dynamically. The event is bound to the chart container element and can be fired using MooTools' fireEvent method.

New data can be passed directly to the chart via fireEvent. If no new data is passed through fireEvent, then the plugin will pull the data and options from the data attributes.

Note When the updateChart event is fired, the plugin will rerender the chart completely.

Examples of how to use the updateChart event can be found in the Dynamic Data examples on the individual chart documentation.

Return to top

Want to continue the tour?

VM UI Framework is created, owned, maintained by Virtuosi Media, Inc. © 2012-2013.