Aristochart

General

Aristochart works by rendering graph data onto the canvas element. Canvas is fast and requires very little resources to render. This brings up the question of browser compatibility. Currently all major browsers support the canvas element but IE 6, 7 and 8 are left out in the cold. There are no plans to support these browsers in the near future.


Aristochart's API is very simple. To get started, check out some of the examples and then report back here to get a more indepth look at Aristochart.

Theming

Aristochart itself is more of a data manager, it's the theme that takes control of rendering the data on screen. Aristochart comes with a default set of render functions, each of which can be overridden by a theme. Below is a list of features that can be implemented by the theme and the data that is sent to each feature's render function. See here for a less than pretty view of the features are on the default theme. See here for the code on how different features are called.


The style object that is sent as the first parameter to all the functions is the style properties declared in the options.style for each feature. For example, the point feature gets sent options.style.<lineName>.line or if there is not style specifically associated with that line, options.style.default.line. Remember that your theme is merged with the options object so styles not explicitedly overridden by the user will default to your theme. The style object should consist of variable properties related to style that can be easily substituted in your render functions such as colors, stroke widths or offsets and all default values should go in style.default.

FeatureDescriptionParametersDefault
Point

A point on the graph.

style Style object, rx Raster coord x, ry Raster coord y, x Data x, y Data y, graph Line Name

Aristochart.point.circle
Axis

The graph's axis lines.

style Style object, x Start of the line x coord int, y Start of the line y coord int, x1 End of the line x coord int, y1 End of the line y coord int, type Axis type "x"|"y"

Aristochart.axis.line
Line

The graph's lines.

style Style object, points An array of Points {rx, ry, x, y}

Aristochart.line.line
Fill

The fill underneath a line.

style Style object, points An array of Points {rx, ry, x, y}

Aristochart.line.fill
Tick

The graph's ticks along the axes.

style Style object, rx Raster x coord int, ry Raster y coord int, type The axis type "x"|"y"

Aristochart.tick.line
Label

The numbers along the axis.

style Style object, text The string to print string, rx Raster x coord int, ry Raster y coord int, type The axis type "x"|"y"

Aristochart.label.text
Title

The axis titles.

style Style object, text The string to print string, rx Raster x coord int, ry Raster y coord int, type The axis type "x"|"y"

Aristochart.title.text

Data

Aristochart strived to make inputting data as simple as possible. To add data to an Aristochart graph, you edit the data property of your options object. You need to include an x dataset and at least one y dataset. A dataset, is an array of numbers you want to display on the graph.


The x dataset is special as there can only be one. It dictates how the horizontal axis reacts to the inputted y data. It allows Aristochart to determine and generate the horizontal labels. The x dataset can be an integer, a range in the form of [upper, lower] or an array of numbers. If given an array of numbers, it will only select the first and last integers and determine the labels.


The y dataset is what you see being outputted onto the graph. Aristochart allows you to input as many y datasets as you want in the form of y, y1, y2, yn. Each one will form their own line on the graph and be rendered in order. Each line can be styled individually by creating a style object for that line under options.style.<line>. Each individual style is then merged with the default.

Options

Aristochart has a vast amount of options, each of which can be overridden by a theme and then the user. Below is a the default options, each of which can be overridden. All the data in the style property is sent to that specific feature's render function so if you change the render function, these styles may not apply.

{
	width: 640, //Width of the graph in pixels
	height: 400, //Height of the graph in pixels
	margin: 70, //Margin between the axis and border. See dimensions.
	padding: 20, //Padding between the axis and data. See dimensions.
	render: true, //Toggle Aristochart automatically calling .render

	fill: { //The fill feature which fill under any given line.
		index: 0, //The features index. Each feature has its own.
		render: Aristochart.line.fill, //The default fill render function
		fillToBaseLine: true, //Toggle filling to the baseline (or x axis).
	},

	axis: { //The axis feature which renders the axes
		index: 1,
		render: Aristochart.axis.line, //The default axis render function

		x: {
			steps: 5, //The amount of steps on the x axis
			render: Aristochart.axis.line  //X specific axis render function
		},

		y: {
			steps: 10, //The amount of steps on the y axis
			render: Aristochart.axis.line //Y specific axis render function
		}
	},

	tick: {
		index: 2,
		render: Aristochart.tick.line //The default tick render function
	},

	line: {
		index: 3,
		render: Aristochart.line.line //The default line render function
	},

	point: {
		index: 4,
		render: Aristochart.point.circle //The default point render function
	},

	label: {
		index: 5,
		render: Aristochart.label.text,

		x: {
			step: 1 //The x axis label step/increment.
		},

		y: {
			step: 1 //The y axis label step/increment.
		}
	},

	title: {
		index: 6,
		render: Aristochart.title.text, //The default title render function
		x: "x", //The x axis title
		y: "y" //The y axis title
	},

	style: { //The style object
		default: { 
			point: { //The styles sent to the point render function
				stroke: "#000",
				fill: "#fff",
				radius: 4,
				width: 3,
				visible: true
			},

			line: { //The styles sent to the line render function
				stroke: "#298281",
				width: 3,
				fill: "rgba(150, 215, 226, 0.4)",
				visible: true
			},

			axis: { //The styles sent to the axis render function
				stroke: "#ddd",
				width: 3,
				visible: true,

				x: {
					visible: true,
					fixed: true //Determines whether the axis is fixed to the bottom
				},

				y: {
					visible: true,
					fixed: true //Determines whether the axis is fixed to the left
				}
			},

			tick: {
				align: "middle", //The tick alignment; "outside", "inside",
				stroke: "#ddd",
				width: 2,
				minor: 10, //The length of the minor ticks in pixels
				major: 15, //The length of the major ticks in pixels
				visible: true,

				x: {
					fixed: true //Determines whether the ticks are fixed to the bottom
				},

				y: {
					fixed: true	//Determines whether the ticks are fixed to the left
				}
			},

			label: { //The label styling
				x: {
					font: "Helvetica",
					fontSize: 14,
					fontStyle: "normal",
					color: "#000",
					align: "center",
					baseline: "bottom",
					offsetY: 8,
					offsetX: 3,
					visible: true,
					fixed: true
				},

				y: {
					font: "Helvetica",
					fontSize: 10,
					fontStyle: "normal",
					color: "#000",
					align: "center",
					baseline: "bottom",
					offsetY: 8,
					offsetX: 8,
					visible: true,
					fixed: true
				}
			},

			title: { //The title styling
				color: "#777",
				font: "georgia",
				fontSize: "16",
				fontStyle: "italic",
				visible: true,

				x: {
					offsetX: 0,
					offsetY: 120,
					visible: true
				},

				y: {
					offsetX: -135,
					offsetY: 10,
					visible: true
				}
			}
		}
	}
};
				

API

Aristochart aims for simplicity so it's API follows that philosophy. Usually, the Aristochart constructor will satisfy most your needs but below is all the exposed functions you can hook your application into to work even better with Aristochart.

class Aristochart( ?element, options, ?theme )

  1. element The canvas element or element to place canvas into. (optional)
  2. options Aristochart's options object. See Options.
  3. theme A theme object. See Themes. (optional)

This is Aristochart's constructor. If you pass a canvas, Aristochart will render onto this. If you pass a wrapper, Aristochart will generate the canvas and append it into the wrapper. If no elements are passed, Aristochart will generate a canvas and will make it accessible via <instance>.canvas for your own placement at a later time.

The options object is where Aristochart takes all it's settings from. There is only one property required in the options object and that's the data property. See Data for more information. Once passed, the object runs through a number of merges. First of all, the options object is merged with the theme passed if any, writing any settings not set by the user. Next, it's merged with the defaults and overwrites any settings not set by the user or theme. This is done to ensure the objects continuity throughout Aristochart. These merges are completed within the constructor during initialization. To edit any options after initializing Aristochart, you can access the options object at <instance>.options and edit at will but changes will not appear till <instance>.render is called.

<instance>.update( )

Updates all of Aristochart's graphs variables such as the graph bounds and axis steps. This function should be called if the data property was updated on a graph.

<instance>.render( )

Renders the chart onto the supplied or generated canvas.

<instance>.getPoints( ) { origin, points }

This method returns an object with the graph's raster origin coordinates and each separate line's points. For example, if multiple y lines are passed in the data, getPoints would c

<instance>.refreshBounds( )

Refreshs the y.min, y.max, x.min, x.max variables. These represent the upper and lower bounds of the supplied data which is used in calculating the labels and spacing on the chart. <instance>.refreshBounds() is called in <instance>.render().

<instance>.toImage( ) Image

Base64 encodes the canvas element and returns a printable Image element.

Aristochart.themes

The variable where theme's are stored. Aristochart's default theme is store in Aristochart.themes.default.

Aristochart.point|line|tick|axis|label|title

These variables are where Aristochart's feature's render functions are stored. These stores hold the functions that render specific items onto the canvas. Aristochart.point.circle for example renders the graph points you see in the default theme. See Theming for information on parameters passed to these functions and how to implement your own functions.

Dimensions

Below is an image depicting the margin and padding properties that can be passed in the options object.

Pipeline

  • Expand to pie charts, histograms etc.
  • Animation.
  • Input functions as data.
  • Legend.
  • Text labels.
  • HTML style markup or custom elements.

Changelog

Upcoming release: v0.3

  • jQuery support.
  • Legible documentation.

Release: v0.2 (download)

  • Data is handled better on negative axes.
  • Fluid axes.
  • 3 themes added: Orange, dot, flat.

Initial Release: v0.1 (download)