This document explains in detail how to create charts and graphs using the TeeChart for Javascript library.
Adding charts to your web pages or applications is fun and easy, see the one-minute Starting Guide , play with the Online Demos or discover the full TeeChart API Reference .
Compared with other programming environments (Java, .NET, Delphi VCL / FireMonkey, etc), the TeeChart Javascript api implements an essential subset of features in order to minimize both the script size and coding complexity.
Current script sizes are 64KB (minified) and 13KB (gzipped)
Full code is wrapped around a single “ Tee ” identifier (namespace) to avoid cluttering the browser Window global space. Several “classes” in an object-oriented manner exist Inside the Tee namespace, being Tee.Chart the main class that defines a chart.
Charts are displayed by default using HTML5 Canvas elements. The main class “Tee.Chart” should be initialized passing the <canvas> element or its id as string:
<canvas id="canvas1" width="300" height="200"></canvas>
Using the canvas id:
var Chart1=new Tee.Chart("canvas1");
…
Or using the element:
var Chart1=new Tee.Chart(document.getElementById("canvas1"));
Hidden charts can be created without passing any canvas parameter:
var Chart1=new Tee.Chart();
Drawing
Charts are rendered to canvas when calling the draw method:
Chart1.draw();
The default xy position of charts inside canvas is 0,0 (left-top corner), and the default size is the same as the associated canvas.
You can override them by changing the chart bounds property:
Chart1.bounds.x=50;
Chart1.bounds.y=20;
Chart1.bounds.width=200;
Chart1.bounds.height=150;
Most objects (like Series, Annotations and chart sub-objects) include a “format” property to
group all visual attributes in a common place.
The Format class provides the following properties:
fill : A color in css string format, for example: #123456, rgb(255,0,0), rgba(0,255,0,0.5), “blue”
Chart1.panel.format.fill = “blue”;
round : Amount in pixels of roundness of rectangle corners (x: horizontal, y: vertical)
Chart1.panel.format.round = { x:10, y:10 }
Chart1.legend.format.round.y = 5;
transparency : Amount of semi-glass effect, from 0 to 1. (default is zero)
Chart1.legend.format.transparency = 0.5;
shadow : Properties to control drop-shadow visibility behind filled shapes or stroked lines.
var s = Chart1.panel.format.shadow;
s.visible = true;
s.width = 4; // can be negative for left-side shadow
s.height = 4; // can be negative for top-side shadow
s.blur = 5;
s.color = “silver”;
gradient: Attributes to fill shapes using a gradient of colors:
var g = Chart1.panel.format.gradient;
g.visible = true;
g.colors = [ “red”, “yellow”, “green” ]; // array of colors
g.stops = [ 0, 0.1, 1 ]; // percentages from 0 to 1 for each color (default is null, automatic)
// “bottomtop”, “leftright”, “rightleft”, “radial”, “diagonalup”, “diagonaldown”
g.direction = “topbottom”;
stroke: Attributes used to draw lines and outlines around filled shapes:
var s = Chart1.panel.format.stroke;
s.fill = “black”;
s.size = 4; // line thickness
s.join = “round”; // segment joins (“round”, “miter”, “bevel” )
s.cap = “square”; // ending line terminators (“square”, “butt”, “round” )
s.dash = [ 5,10 ]; // dot-dash... array of pixels (default is null to draw solid lines)
s.gradient.visible = true; // gradient object with colors, direction, etc
font : Properties to display text:
var f = Chart1.title.format.font;
f.style = “22px Verdana”; // or: “bold italic 14px Tahoma”, etc, etc
f.fill = “blue”;
f.shadow.visible = true; // text drop-shadow
f.stroke.fill = “white”; // draws an outline around text
f.gradient.visible = true; // fills text with gradient instead of using font.fill
f.textAlign = “center”; // horizontal alignment: “start”, “end”, “left”, “center”, “right”
// vertical alignment: “top”, “middle”, “bottom”, “alphabetic”, “hanging”, “ideographic”
f.baseLine = “top”;
The chart background appearance is controlled by the “panel” sub-object:
Chart1.panel.transparent = false;
The panel property includes a format subproperty to control background’s appearance:
Chart1.panel.format.gradient.visible = true;
Chart1.panel.format.shadow.color=”black”;
… etc
These two chart properties are used to display text at chart top and bottom sides:
Chart1.title.text = “Hello”;
Chart1.footer.text = “World”;
Multiple-line text is done by adding “\n” line-feed delimiters:
Chart1.title.text = “Hello \n World”;
Title and Footer are Annotation-derived objects, and such they inherit the “format” sub-properties:
Chart1.title.visible = true;
Chart1.title.transparent = false;
Chart1.title.format.gradient.visible = true;
Chart1.title.format.round.x=20;
Data is added to a chart using “ Series ” objects.
Multiple series can exist in the same chart. Each series can be of a different type ( line , area , bar , pie , etc) so you can mix several styles altogether.
Direct data:
The simplest way to add data to a chart is by passing an array of values at chart construction time:
var Chart1=new Tee.Chart("canvas1", [ 5,6,2,9,1] );
This creates a new series object of type Tee.Bar by default, and assigns the array to series.data.values property.
Multiple series are created when passing a multi-dimensional array:
var Chart1=new Tee.Chart("canvas1", [ [ 5,6,2,9,1], [ 8,4,3,7,5] ] );
The default series style Tee.Bar can be changed passing a type parameter:
var Chart1=new Tee.Chart("canvas1", [ [ 5,6,2,9,1], [ 8,4,3,7,5] ] , Tee.Area);
Creating series:
Series are manually added into a chart using the addSeries method:
var bar =Chart1.addSeries(new Tee.Bar());
Series have a default “title” string property that is used at chart legend.
When series are added to a chart, title is assigned to “Series” plus the series index in the Chart1.series.items array (“Series1”, “Series2” and so on).
You can override the default title:
bar.title = “My Data”;
By default series are empty, they contain no data.
For testing purposes its handy to add random values, for example:
Chart1.addSeries(new Tee.Line()).addRandom(1000); // Thousand random points
Data can be specified inline when creating the series:
Chart1.addSeries(new Tee.Pie( [ 10, 20, 30, 40 ] ));
All data is stored under the series “data” property arrays.
You can access and modify data directly:
var a = new Tee.Area();
Chart1.addSeries( a );
a.data.values = [ 10, 20, 30, 40 ];
Each series point has an associated text label. By default labels are empty, you can modify them using the data.labels property:
a.data.labels = [ “a”, “b”, “c”, “d” ];
Some series allow specifying point positions or other point parameters.
For example, Line and PointXY series can optionally display each line segment or point at a specific “X” axis coordinate:
var p = new Tee.PointXY();
p.data.values = [5, 7, 9];
p.data.x = [0.23, 14, 16];
Chart1.addSeries(p);
Other series like Bubble have a “data.radius” array, and Candle series have data.open, data.close, data.high and data.low arrays.
Adding data from other sources
Several helper functions are provided in a separate script (teechart-table.js) to import data from different sources (see the online demos for details), for example:
From a textarea html element:
Chart1.addSeries(new Tee.Bar(document.getElementById("data")) );
<textarea id="data" rows="20" cols="20" wrap="off">
7,Apples
4
3,Oranges
9
1,Banana
6,Kiwis
2</textarea>
From a table html element:
Chart1.fromTable('table1', Tee.Bar, true, 0,0);
<table id=”table1”>...</table>
From a text file URL:
// Warning: data file url should be at “same domain origin”
Chart1.addSeries(new Tee.Bar(“http://myweb.com/mydata.txt”));
From another series in same or different chart:
// Simply assign the “data” property from one series to another:
Chart1.series.items[0].data = Chart2.series.items[3].data;
From xml formatted text:
var b=Chart1.addSeries(new Tee.Bar());
b.loadXML(document.getElementById("xml"));
...
<textarea id="xml" rows="10" cols="60" "wrap="off">
<series name="Friends" color="Blue" metric="Quantity">
<point name="Facebook" value="123"/>
<point name="Twitter" value="456"/>
<point name="Google+" value="789"/>
</series>
</textarea>
From JSON formatted text:
var b=Chart1.addSeries(new Tee.Bar());
b.loadJSON(document.getElementById("json"));
The indicator where series names and series points are displayed is called the legend.
Several properties can be used to customize the legend behaviour and appearance.
Chart1.legend.visible = true;
Chart1.legend.transparent = false;
Chart1.legend.format.fill = “yellow”;
Legend position and orientation:
Chart1.legend.position = “left”; // “top”, “bottom”, “right”
Chart1.legend.inverted = false; // draws items in normal order
Select what to display at legend:
Chart1.legend.legendStyle = “values”; // “auto”, “series”, “values”
Chart1.legend.textStyle = “percentlabel”; // show point value as percent, and point text label
Font and formatting:
Chart1.legend.format.font.style = “20px Arial”;
Margins to chart top and chart axes:
// distance from chart edge, percentage from 0 to 100 ( 0 means automatic )
Chart1.legend.align = 0;
// distance from legend to axes
Chart1.legend.padding = 5; // in pixels
Title text on top of items:
Chart1.legend.title.text = “My Legend”;
Chart1.legend.title.visible = true;
Symbols next to legend items:
Chart1.legend.symbol.visible = true;
Chart1.legend.symbol.width = 20;
Chart1.legend.symbol.format.shadow.width = 5;
Other legend properties:
Chart1.legend.fontColor = true; // each item text is painted using its point or series color
Chart1.dividing.fill = “blue”; // draws lines between legend items
Most Series data are displayed using axes to convert from data values to canvas pixel coordinates. Some series like Pie and Donut do not use axes.
There exist four default axes inside a chart: left, top, right and bottom.
var a = Chart1.axes.left;
Each series has two properties that control which horizontal and vertical axes are used.
By default, the horizontal axis is “bottom”, and the vertical axis is “left”.
Chart1.series.items[0].horizAxis = “top”;
Chart1.getSeries(1).vertAxis = “right”;
Series can also display using both axes:
Chart1.series.items[2].horizAxis = “both”;
Axis visibility is controlled globally by the Chart1.axes.visible property, and individually using the axis visible:
Chart1.axes.visible = true;
Chart1.axes.bottom.visible = true;
Scales are automatically controlled by default. Each axis calculates its minimum and maximum values based on its associated series values and visual properties.
You can override axis automatic scales and set them manually:
var a = Chart1.axes.left;
a.automatic = false;
a.minimum = 50;
a.maximum = 200;
The above code is equivalent to:
Chart1.axes.left.setMinMax( 50, 200 );
Logarithmic scales
Axes scales are linear by default. The log property determines the axis to use natural logarithm scaling instead of linear:
Chart1.axes.left.log = true;
Axis Labelling
Each axis automatically calculates the “best” distance from labels, using labels formatting properties like font.size. Custom labels can be controlled changing the axis increment property:
Chart1.axes.bottom.increment = 100; // one label at each 100 values in axis scale.
Increment is zero by default, meaning automatic calculation.
Labels can display series values or series point labels. This is controlled with the labelStyle property:
// options are: “auto”, “none”, “value”, “mark”, “text”, “x”
Chart1.axes.left.labels.labelStyle = “text”;
When series contain date-time values, labels are formatted according to dateFormat property using Steven Levithan <stevenlevithan.com> date.format.js library.
Chart1.series.items[0].data.x = [ new Date() ];
Chart1.axes.bottom.labels.dateFormat = “shortDate”;
Other properties that control labels:
Chart1.axes.left.labels.alternate = true; // double quantity of labels
Chart1.axes.right.labels.visible = false; // show or hide labels
Chart1.axes.left.labels.decimals = 3; // output numbers with up to 3 fixed decimals
Chart1.axes.bottom.labels.rotation = 90; // 90 degree rotation
Axis Grids
The axis grid property includes a format to draw grid lines that go across chart axes space.
Chart1.axes.left.grid.visible = true;
When grid fill color is not empty, grids are filled alternatively as “bands”:
Chart1.axes.left.grid.format.fill = “red”;
Grid lines format is controlled by stroke property:
Chart1.axes.left.grid.format.stroke.size = 5;
Default grid lines are solid lines. The lineDash property displays dash-dot grids:
Chart1.axes.left.grid.lineDash = true;
On browsers that natively support canvas dash strokes, the above code is equivalent to:
Chart1.axes.left.grid.format.stroke.dash = [10,5]; // see “dash” stroke property
Axis Ticks
Axis include ticks an innerTicks properties of type “Ticks”, that have a stroke property.
Ticks are drawn from labels to axis. Inner ticks display from axis towards inside.
Chart1.axes.bottom.innerTicks.visible = true;
Chart1.axes.left.ticks.length = 9;
Chart1.axes.top.ticks.stroke.fill = “blue”;
Minor Ticks
From tick to tick, the minorTicks axis property can be used to display small sub-ticks:
Chart1.axes.left.minorTicks.visible = true;
Chart1.axes.left.minorTicks.length = 2;
Chart1.axes.left.minorTicks.count = 5;
Chart1.axes.left.minorTicks.stroke.fill = “green”;
Axis Title
Close to an axis, the title property is used to display text that identifies the axis:
Chart1.axes.bottom.title.text = “Quantity”;
Chart1.axes.bottom.title.text.format.font.fill = “red”;
Axis positioning
Size and position of axes is automatic by default.
The axis startPos and endPos properties control the pixel coordinate of axes.
The rectangular space where axes are painted is called “the back wall”.
Formatting is provided using the walls.back property:
Chart1.walls.back.visible = true;
Chart1.walls.back.transparent = false;
Chart1.walls.back.format.gradient.visible = true;
Inheriting from a common Series class, several charting styles are provided, each as a different object class with its own properties and methods.
Series Marks
The marks property displays text annotations near series points:
var s = new Tee.Bar();
s.marks.visible = true;
s.marks.style = “percent”;
Charts have a palette property (an array [ ] of colors in string format).
This palette is used by series to paint its points, and by chart legend to display series items symbols.
Chart1.palette = [ “red”, “blue”, “green”, “yellow” ];
Colors in the palette are reused in a circular way when more series or more points in a series exist than the size of the palette.
Series also contain a palette of colors to override the chart palette. By default is a “null” empty array so they share the chart palette.
Charts can be zoomed and scrolled by manual code or mouse / touch events.
Default behaviour is to drag the right mouse button inside axes to scroll, and drag a rectangle using the left mouse button to zoom / unzoom (zoom dragging to bottom-right direction, and unzoom dragging to left-top direction).
This can be overridden using the chart zoom and scroll properties:
Chart1.zoom.enabled = true;
Chart1.zoom.mouseButton = 0; // 0=left button, 1=middle, 2=right button
Chart1.zoom.stroke.fill = “yellow”;
Chart1.scroll.enabled = true;
Chart1.scroll.mouseButton = 2;
Chart1.scroll.direction = “horizontal”; // can be: “vertical” or “both”
The chart onzoom event is triggered when the user releases the mouse button after the chart is zoomed.
The chart onscroll event is triggered while the user is scrolling the chart by dragging it.
To obtain a PNG or JPEG image from a chart, you can use the canvas toDataURL method, or the included toImage function:
Chart1.toImage( “img” ); // fills <img id=”img”> element with chart as PNG image.
Chart1.toImage( “img” , “jpg”, 90 ); // fills image with a jpeg image with 90% compression
Some features are implemented as a “tool” objects. These objects can be added to a chart tools array property to activate them.
Annotations
Custom text can be displayed at any chart position using annotation tools:
Chart1.tools.add( new Tee.Annotation( Chart1, “Hello”, 50, 50 ) );
The annotation object has a format, text and position properties.
Annotations can also act as buttons when using the onclick event:
var b1=new Tee.Annotation(Chart1, “button 1”, 100, 100);
b1.cursor="pointer";
b1.onclick=function(button,x,y) { alert("Clicked button 1"); }
Chart1.tools.add( b1 );
Tooltips
This tool displays series data when moving the mouse over series data point.
var tip=new Tee.ToolTip(Chart1);
tip.format.font.style="16px Tahoma";
Chart1.tools.add(tip);
The ToolTip tool provides onshow, onhide and ongettext events.
Cursors
Draggable cursor lines are implemented as a tool object:
var t=new Tee.CursorTool(Chart1);
t.format.stroke.size=2;
t.format.stroke.fill="#BB0000";
Chart1.tools.add(t);
The cursor tool includes a direction property (to display cursor as an horizontal line, vertical or both) and an onchange event that is triggered when the cursor is dragged.
Dragging Points
The DragTool implements mouse / touch point dragging.
Chart1.tools.add(new Tee.DragTool(Chart1));
Includes onchanging and onchanged events.
The target property determines which series and which series point index is being dragged.
Slider
A generic slider control that can be used inside a chart to change any value.
var slider=new Tee.Slider(Chart1);
slider.min=1;
slider.max=100;
slider.position=10;
slider.thumbSize=12;
slider.horizontal=true;
slider.bounds.x=50;
slider.bounds.y=10;
slider.bounds.width=150;
slider.bounds.height=20;
slider.onChanging=function(slider,value) {
Chart1.title.format.font.style = value.toFixed(0) + “ Verdana”;
return value;
}
Chart1.tools.add(slider);
Scroller
The scroller tool displays a simplified view of another chart and allows scrolling it.
Please refer to this demo for a complete example.
Simple animations performed by changing axis scales or rotating transformations:
var a=new Tee.SeriesAnimation(Chart1);
a.duration=500; // milliseconds
Chart1.tools.add(a);
The animate method to start the animation can be called for example from an html button:
<BUTTON type="button" onclick="Chart1.tools.items[0].animate();">Animate</BUTTON>
The following are libraries and code snippets that have been used to develop TeeChart for Javascript:
date.format.js by Steven Levithan
Used by chart axes to format date-time string labels from series data. (See axis dateFormat property).
splines Copyright 2010 by Robin W. Spencer
Custom modified code to draw smooth curves between series points (Line, Area, etc).
JQuery.js , JSON and Three.js are technologies used in TeeChart online demos that are optional (not required by TeeChart).