Charting guide¶

• Table of contents
• Charting guide
• Type of charts
• How to build a chart
  • • Chart common parameters
  • Creating a Chart definition object
  • Stuffing the Chart definition Object with parameters
    • Common parameters
    • Legend-Margin Object
    • Margin Object
    • Grid Object
    • Fill Object
    • Axis Object
    • Axis-Style Object
    • Axis-Title Object
    • Marker Object
    • Range-Marker Object
• Specialized chart parameters
  • Pie chart
    • Pie-Slice Object
  • Bar chart
    • Bar Object
  • Scatter chart
    • Scatter Object
  • Line chart
    • Line Object
    • Line-Style Object
  • XYLine chart
    • XYLine Object
  • GoogleOMeter chart
  • Dial chart
    • Dial-Range Object
  • Radar chart
    • Radial-Axis Object
    • Radial-Axis-Style Object
  • BoxPlot chart
    • Box Object
    • BoxLegend Object

The Velocity Report plugin helps you creating charts for the Google Charts engine or its Java emulation: the Eastwood project.

While the Google Charts engine is great for html preview and web sites, the maximum resolution of the images produced is very low and not suitable for printing or producing high resolution PDF.

This is why we adapted the Eastwood project (a Google Charts engine emulation using the JFreeCharts library). The Easwood project is basically a Servlet that will run in your Servoy server instance and will allow high resolution charts to be created.

But JFreeCharts is quite complex and to achieve good results it takes time and a good knowledge of the API, so we have used the Eastwood project which uses the same Google charts syntax to produce charts.

Except that the Google Charts API is quite big too and it would require a lot of Javascripting to be able to fully support its features if this was made with Servoy methods only.

That's how we created a special Java factory which is part of the Velocity Report plugin: Basically, with the Velocity Report plugin, you get an easy-to-use Servoy chart generator for free!

You don't use this factory directly in Java, instead you create a simple Javascript object, stuff all the chart parameters in it, and pass it to the getChart() method of the plugin to get a Chart object that can then be embedded inside a Servoy field of type HTML_AREA or used in a template with the Velocity Report plugin.

Type of charts¶

Most of the Google Charts can be created using the Velocity Reports plugin.
Only Venn Diagrams and Map charts are not implemented, because their definition is too low to be of any professional use.

The Velocity Report plugin exposes a set of variable in the CHART constant object for each of the available charts that you can use.

The type of charts currently available are:

TYPE	CONSTANT	GOOGLE?	EASTWOOD?
Pie	CHART.PIE	X	X
Bar	CHART.BAR	X	X
Scatter	CHART.SCATTER	X	X
Line	CHART.LINE	X	X
XYLine	CHART.XYLINE	X	X
GoogleOMeter	CHART.GOOGLEOMETER	X	X
Dial	CHART.DIAL	-	X
Radar	CHART.RADAR	X	X
BoxPlot	CHART.BOXPLOT	X	X

How to build a chart¶

All charts are build using one single method of the Velocity Report plugin.
Its signature is:

getChart(CHART type, Scriptable chartDefinition, [boolean useLocalEngine], [number resolution])

• type is one of the CHART constants listed above.
• chartDefinition is a Scriptable - meaning a simple Javascript Object -, this is where you will stuff all the parameters defining the chart...
• useLocalEngine, an optional boolean parameter that you can use to request a chart generated by Google Charts or the local (Eastwood) chart engine, - default value is true, meaning: use the local Eastwood engine
• resolution is also an optional number parameter that you can use to specify whether you want to generate a chart in high resolution (PDF for print) or low (to display on-screen). You can pass one of the constants REPORT.RESOLUTION_LOW or REPORT.RESOLUTION_HIGH * - Default is REPORT.RESOLUTION_LOW

* REPORT.RESOLUTION_LOW = 1 and REPORT.RESOLUTION_HIGH = 4

Note that this is in fact an integer factor that is passed to the chart engine to multiply the screen resolution.
The default screen resolution being 96dpi, you get 288dpi for RESOLUTION_HIGH (96x4).

You can pass a different number if you want, but beware of the memory your smart client will need to render high resolution images to PDF - you will have to experiment with this and find the optimal ratio between image quality and memory consumption.

For most PDF reports that you will produce for printing on a computer printer, 288dpi should be enough, and the memory consumption will still be correct (FYI, the max heap size set on the smart client to produce the 12 pages high resolution sample report was 128Mb on Mac OS X with 64-bit Java).

The main culprit in terms of memory consumption here is the iText library which is used (also by Jasper Reports) to render to PDF.

Chart common parameters¶

We've seen that to create a chart we use the getChart() method of the plugin, passing a CHART type, optional parameters, and most importantly a Javascript object defining all the parameters of the chart.
There are loads of parameters that you can use, some of them specific to certain type of charts, but a lot of them common to all charts, and this is what we will see here.

Note that some of the extended options are not yet fully supported by the Eastwood chart engine (refer to the Issues list) but we made our best to patch the Easwtood engine and make it petty usable as-is with high resolution definition, actually it is pretty close and in some case even better.

Note IMPORTANT The chart renderer expects all values to be within the default range of 0...100 - in other words, percentages. Any value under 0 or over 100 will be ignored.
To workaround that limitation, you need to use the chart specific min[Value] and max[Value] to indicate that you are using values out of the default boundaries. min[Value] can be set to more than 0 if you want to calculate percentages based on the difference between min and max, the default of 0 is fine in most cases, but max[Value] in particular is important because it will be used to translate your values to a percent value suitable for the renderer. Not setting this parameter to at least the maximum value of your data will mean values over 100 will be ignored, since they will be considered percentages.

Creating a Chart definition object¶

First you need to create a Javascript object that will contain all these parameters.
You can do it either like this:

var chartDef = new Object();

or like that:

var chartDef = {};

The end result will be a Javascript Object that will act as a container for all your chart parameters.

Stuffing the Chart definition Object with parameters¶

Now you need to add parameters to the Chart definition Object. You do it like this:

chartDef.title = 'Chart title';
chartDef.width = 600;
chartDef.height = 300;
chartDef.threeD = true;

As you can see, all you need to do is define a property and set its value. That's it!

Now you really need to know what property names are available and what values are expected.

Common parameters¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	USED BY	GOOGLE?	EASTWOOD?
width	Integer	Y	200	ALL	X	X
height	Integer	Y	125	ALL	X	X
title	String (i18n)	N	null	ALL	X	X
titleSize	Integer	N	14	ALL	X	X
titleColor	Color-String	N	'#000000' (Black)	ALL	X	X
legendPosition	String ('top', 'bottom', 'left', 'right')	N	null	ALL except GoogleOMeter and Dial	X	X
legendMargins	Legend-Margin Object	N	null	ALL except GoogleOMeter and Dial	X	X
margins	Margin Object	N	null	ALL	X	X
useLocalEngine	Boolean	N	true	ALL	-	X
resolution	Integer	N	REPORT.RESOLUTION_LOW	ALL	-	X
grid	Grid Object	N	null	ALL except Pie, Radar, GoogleOMeter and Dial	X	X
background	Color-String or Fill Object	N	'#FFFFFF' (White)	ALL	X	X
areaFill	Color-String or Fill Object	N	'#FFFFFF' (White)	ALL except Pie, Radar, GoogleOMeter and Dial	X	X
xAxis	Axis Object	N	null	ALL except Pie, Radar, GoogleOMeter and Dial	X	X
yAxis	Axis Object	N	null	ALL except Pie, Radar and Dial	X	-
rightAxis	Axis Object	N	null	ALL except Pie, Radar, GoogleOMeter, BoxPlot and Dial	X	X
topAxis	Axis Object	N	null	ALL except Pie, Radar, GoogleOMeter, BoxPlot and Dial	X	X
transparency	Integer (0-100)	N	100	ALL	X	X
markers	Array of General Marker Object	N	null	Line, XYLine and Scatter only in Eastwood, + Bar in google	X	X
rangeMarkers	Array of Range-Marker Object	N	null	ALL except Pie, Radar, GoogleOMeter, BoxPlot and Dial	X	X
urlLimit*	Integer	N	-1	ALL	X	X
autoScaling	Boolean	N	true	All except Pie, Radar, GoogleOMeter and Dial	X	X

• See Issue #99 to know more about this parameter (-1 means no limit)

Color-String can use alpha parameter, where '#000000FF' is Black without transparency and '#00000000' is fully transparent.

Title, legends and labels inside data uses i18n syntax, so for example

chartDef.title = "i18n:chart.title";

will use the chart.title key of your i18n properties.

Legend-Margin Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
h[orizontal]	Integer	N	0	X	X
v[ertical]	Integer	N	0	X	X

// Legend-Margin Object can also be expressed as a simple array
// Each value is then required (even if 0) and the order is horizontal, vertical:
chartDef.legendMargins = [ 10, 2 ];
// is equivalent to:
chartDef.legendMargins = { horizontal: 10, vertical: 2 };
// or 
chartDef.legendMargins = { h: 10, v: 2 };

Margin Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
top	Integer	N	0	X	X
right	Integer	N	0	X	X
bottom	Integer	N	0	X	X
left	Integer	N	0	X	X

// Margin Object can also be expressed as a simple array
// Each value is then required (even if 0) and the order is top, right, bottom, left:
chartDef.margins = [ 0, 10, 0, 10 ];
// is equivalent to:
chartDef.margins = { right: 10, left: 10 };

Grid Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
x[AxisStepSize]	Float	N	0	X	X
y[AxisStepSize]	Float	N	0	X	X
[lengthOf]Line[Segment]	Integer	N	4	X	X
[lengthOf]Blank[Segment]	Integer	N	1	X	X
xOffset	Integer	N	0	X	X
yOffset	Integer	N	0	X	X

// Grid Object can also be expressed as a simple array
// Each value is then required (even if 0) and the order is x, y, line, blank, [xOffset, yOffset]:
chartDef.grid = [ 20, 25, 3, 2, 5, 5 ];
// is equivalent to:
chartDef.grid = { xAxisStepSize: 20, yAxisStepSize: 10, lengthOfLineSegment: 3, lengthOfBlankSegment: 2, xOffset: 5, yOffset: 5 };
// or
chartDef.grid = { x: 20, y: 10, line: 3, blank: 2 };

Fill Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
type	String (gradient, striped)	N	gradient	X	X (striped not supported)
angle	Integer	N	0	X	X
colors	Array of [Color-String, Integer offset]	Y	null	X	X (2 colors supported)

Axis Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
labels	Array of String (i18n)	Y	null	X	X
positions	Arrray of Float	N	null	X	X
style	Axis-Style Object	N	null	X	X
minRange	Double	N	0.0	X	X
maxRange	Double	N	100.0	X	X
step	Double	N	null	X	X

Axis-Style Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
textColor	Color-String	N	'#000000' (Black)	ALL except Pie, Radar, GoogleOMeter, BoxPlot and Dial	ALL except Pie, Radar, GoogleOMeter, BoxPlot and Dial
fontSize	Integer	N	12	ALL except Pie, Radar, GoogleOMeter, BoxPlot and Dial	ALL except Pie, Radar, GoogleOMeter, BoxPlot and Dial
alignment	String ('left', 'center', 'right')	N	null	X	AUTO
draw[TickMarks]	Boolean	N	true	X	-
[tickMark]Length	Integer	N	null	X	-
[tickMark]Color	Color-String	N	'#000000' (Black)	X	-
title	Axis-Title Object	N	null	X	X

Axis-Title Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
text	String	Y	null	X	X
size	Integer	N	12	X	X
color	Color-String	N	'#000000' (Black)	X	X

Marker Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
shape	String ('arrow', 'cross', 'diamond', 'circle', 'square', 'x')	Y (if no text)	null	X	X
text	String (i18n)	Y (if no shape)	null	X	X
color	Color-String	N	'#000000' (Black)	X	X
size	Integer	N	10	X	X
flagged	Boolean	N	false	X	X
x	Float	Y (general markers)	null	X	X
y	Float	Y (general markers)	null	X	X
index	Integer	N (bar, lines and scatter)	0	X	-
start[Index]	Integer	N (bar, lines and scatter)	0	X	-
end[Index]	Integer	N (bar, lines and scatter)	auto	X	-
nth	Integer	N (bar, lines and scatter)	1	X	-

Range-Marker Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
orientation	String ('h[orinzontal]', 'v[ertical]')	N	'h'	X	X
color	Color-String	Y	null	X	X
start[Point]	Float (>=0)	N	0	X	X
end[Point]	Float (>startPoint, <=100)	N	100	X	X

Specialized chart parameters¶

Pie chart¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
slices	Pie-Slice Object	Y	null	X	X
threeD	Boolean	N	false	X	X
orientation	Integer	N	0	X	X
shadow	Boolean	N	true (if not threeD)	-	X
proportional	Boolean	N	false	-	X
labelFontSize	Integer	N	12	-	X

Pie-Slice Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
percent	Float	Y	null	X	X
label	String (i18n)	Y	null	X	X
color	Color-String	N	auto	X	X
legend	String (i18n)	N	null	X	X

Bar chart¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
bars	Array of Bar Object	Y	null	X	X
stacked	Boolean	N	false	X	X
h[orizontal]	Boolean	N	false	X	X
barWidth	Integer	N	23 (0=auto)	X	AUTO
spaceBetween[GroupsOfBars]	Integer	N	8	X	AUTO
spaceWithin[GroupsOfBars]	Integer	N	4	X	X
threeD	Boolean	N	false	-	X
shadow	Boolean	N	true (if not threeD)	-	X
min[Value]	Double	N	0.0	X	X
max[Value]	Double	N	100.0	X	X
spline	Integer	N	0	-	X

the 'spline' factor is used for DataLines in Bar charts

Bar Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
data	Array of Float	Y	null	X	X
color[s]	Color-String or Array of Color-String	N	auto	X	X
legend	String (i18n)	N	null	X	X
zeroLine	Float	N	0	X	-
dataLineSize	Integer	N	null	X	X
dataLineColor	Color-String	N	'#000000' (Black)	X	X
markers	Array of Marker Object	N	null	X	-

Scatter chart¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
scatter	Scatter Object	Y	null	X	X
xMin[Value]	Double	N	0.0	X	X
xMax[Value]	Double	N	100.0	X	X
yMin[Value]	Double	N	0.0	X	X
yMax[Value]	Double	N	100.0	X	X
markers	Array of Marker Object	N	null	X	X

Scatter Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
xData	Array of Float	Y	null	X	X
yData	Array of Float	Y	null	X	X
pointSizes	Array of Float	N	auto	X	-
color	Color-String	N	'#FF0000' (Red)	X	X
legend	String (i18n)	N	null	X	X

Line chart¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
lines	Array of Line Object	Y	null	X	X
isSparkline	Boolean	N	false	X	X
min[Value]	Double	N	0.0	X	X
max[Value]	Double	N	100.0	X	X
spline	Integer	N	0	-	X

Line Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
data	Array of Float	Y	null	X	X
color	Color-String	N	auto	X	X
legend	String (i18n)	N	null	X	X
fillArea[Color]	Color-String	N	null	X	X
lineStyle	Line-Style Object	N	auto	X	X
markers	Array of Marker Object	N	null	X	X

Line-Style Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
[line]Thickness	Integer	N	1	X	X
[lengthOf]Line[Segment]	Integer	N	1	X	X
[lengthOf]Blank[Segment]	Integer	N	0	X	X

XYLine chart¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
lines	Array of XYLine Object	Y	null	X	X
xMin[Value]	Double	N	0.0	X	X
xMax[Value]	Double	N	100.0	X	X
yMin[Value]	Double	N	0.0	X	X
yMax[Value]	Double	N	100.0	X	X

XYLine Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
xdata	Array of Float	Y	null	X	X
ydata	Array of Float	Y	null	X	X
color	Color-String	N	auto	X	X
legend	String (i18n)	N	null	X	X
fillArea[Color]	Color-String	N	null	X	X
lineStyle	Line-Style Object	N	auto	X	X
markers	Array of Marker Object	N	null	X	X
spline	Integer	N	0	-	X

GoogleOMeter chart¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
data	Float	Y	null	X	X
colors	Array of Color-String	N	['#EE0000', '#EEEE00', '#00EE00']	X	X
start[Color]	Color-String	N (not used if colors provided)	'#FF0000' (Red)	X	X
end[Color]	Color-String	N (not used if colors provided)	'#00FF00' (Green)	X	X
steps	Integer	N	11	-	X
interpolation	String ('linear', 'hue')	N	'linear'	-	X
label	String (i18n)	N	null	X	X
legend	String (i18n)	N	null	X	X

Dial chart¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
data	Float	Y	null	-	X
ranges	Dial-Range Object	N	null	-	X
legend	String (i18n)	N	null	-	X
minor[Ticks]	Integer	N	4	-	X
major[Ticks]	Integer	N	10	-	X
lower[Bounds]	Float	N	0	-	X
upper[Bound]	Float	N	100	-	X
proportional	Boolean	N	false	-	X
[tickLabel]Precision	Integer	N	0	-	X

Dial-Range Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
start[Point]	Float	Y	null	-	X
end[Point]	Float	Y	null	-	X
color	Color-String	Y	null	-	X

Radar chart¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
radars	Array of Line Object	Y	null	X	X
spline	Boolean	N	false	X	-
concentricAxis	Axis Object	N	null	X	X
radialAxis	Radial-Axis Object	N	null	X	X

Radial-Axis Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
labels	Array of String (i18n)	Y	null	X	X
style	Radial-Axis-Style Object	N	null	X	-

Radial-Axis-Style Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
textColor	Color-String	Y	null	X	-
fontSize	Integer	Y	null	X	-

BoxPlot chart¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
boxes	Array of Box Object	Y	null	X	X
legend	Array of BoxLegend Object	Y	null	X	X
secondaryXAxisLabels	Array of String	N	null	X	X

Box Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
data	Array of Float	Y	null	X	X
extreme	Boolean	N	false	X	X

BoxLegend Object¶

PROPERTY	TYPE	REQUIRED?	DEFAULT	GOOGLE?	EASTWOOD?
title	String	N	null	X	X
color	Color-String	Y	null	X	X

For more information on how to use some of the charts extended features/parameters, you can also refer to the Google Chart API