gchart: README

gchart.lua - Create charts using the Google Charts API
 
Google Charts API works on a very simple principle. You encode all the data about the chart you want 
to render into a URL, and when you request this URL you will receive a PNG image of your chart.
 
The API is very fussy about the format of the data you pass it, so this library abstracts all that away, 
and lets you create charts, manipulate them, and then build the URL when you are ready.
 
## Example
 
   gchart = require "gchart"
   gchart.default:set_color("C6D9FD");
   
   mychart = gchart.new("bar")
   mychart:add_series({ 100, 200, 100, 400 })
   
   print("Chart:", chart:url());
   --> Chart: http://chart.apis.google.com/chart?cht=bvs&chco=00CC00,CC0000&&chd=e:DwS0Dww7&chs=320x200
 
## Reference
 
### Defaults
 
gchart.lua exposes a default chart object. All charts will 'inherit' the properties from this chart unless you override them. For example:
 
   gchart.default:set_color("C6D9FD") -- All charts will now be this colour by default
 
### Core
 
 gchart.set_base_url(url): Set the base URL of the API. Default: "http://chart.apis.google.com/chart"
	For example if another provider supports an API compatible with Google Charts, you could use this to switch gchart.lua to using their service instead.
 
 gchart.new(type): Creates a new chart. Default type is "line".
	Returns the new chart object.
 
### Charts
 
All these functions assume that 'chart' is a chart object returned from gchart.new().
 
 chart:set_type(type): Set the type of chart.
	May be one of "line", "sparkline", "plot", "bar" or a type code straight from the Google API, like "bhs".
 
 chart:add_series(series): Add a new data series
	Takes an array of numbers, each represinting a data point. For example { 10, 20, 30 }.
 
 chart:set_scale(min, max): Set the minimum and maximum values for the chart
	The Google Chart API does not automatically scale input data. By default gchart.lua will attempt
	to scale the graph so that the base line is 25% lower than the lowest value on the graph, and the 
	top axis 25% higher than the highest value on the graph. Supply custom numbers for either or both of 
	min and max, or set to true for gchart.lua to auto-scale that value (default is to auto-scale both min 
	and max).
 
 chart:set_size(width, height): Set the width and height of the generated chart in pixels
 	Google Chart API limits the maximum size of generated charts, the default size is 320x200.
 
 chart:set_title(title): Set the title of the chart
 	The title will be displayed at the top of the chart. Both the '|' (pipe) and \n (newline) characters 
 	will start a new line (use for sub-titles).
 
 chart:set_legend(entries): Add a legend to a chart
	Set entries to a list of legend entries, in the same order as your data series were added. For example 
	{ "Temperature", "Rainfall", "Humidity" }.
 
 chart:set_legend_position(position, layout): Set the position of the legend
 	position may be one of "top", "bottom", "left" or "right". Default is "right".
 	layout may be one of "vertical" or "horizontal". Default is "vertical". When using 
 	the "horizontal" layout, the only valid positions are "top" and "bottom".
 
 chart:add_axis(location, options): Add an axis to the chart
	location may be one of "top", "bottom", "left" or "right".
	options is an (optional) table allowing you to configure how the axis is displayed. For more info see
	the 'Axes' section below.
 
 chart:add_marker(marker): Add a marker to one or more datapoints
 	'marker' is a table of options. For more info see the 'Markers' section below.
 
 chart:set_color(color): Set the colour of the graph lines
 	Colours are specified as hexidecimal values of red, green and blue, just as in HTML. An optional addition 
 	is appending 2 further digits to specify the opacity. For example 50% transparent blue would be: 0000FFCC.
 	It is possible to specify multiple colours, separated by commas, which will be used differently according 
 	to the chart type. For example "0000FFCC,FF0000CC".
 
 chart:url(): Return the URL to render the chart
 	Last but not least, call this function to retrieve the URL to generate the graph with all properties applied.
 
## Axes
 
Axes are extremely flexible in Google Charts API. Add an axis with chart:add_axis(location, options) as described above. The 'options'
table may contain any of the following options:
 
 options.range: Specify the range of the axis markers
 	For example: options.range = { min = 0, max = 500 }
 
 options.labels: Specify text labels along the axis instead of numbers
	For example: options.labels = { "Jan", "Feb", "Mar", "Apr" }
	or with positions: options.labels = { Jan = 10, Feb = 20, Mar = 30, May = 50 }
 
 options.style: Specify the style of an axis
 	Currently a string of the form: <axis color>,<font size>,<alignment>,<drawing control>,<tick mark color>
 	Only the colour is required, and further parameters are optional.
 	For example, a green axis: options.style = "00CC00"
 	and with 12pt text: options.style = "00CC00,12"
 	
 options.ticklength: Specify the length of the tickmarks on the axis
 	Must be a number. From the Google documentation:
 	"Positive values are drawn outside the chart area. The maximum positive value is 25."
 	"Negative values are drawn inside the chart area. Use this feature to draw gridlines on a chart."
 
 
## Markers
 
Markers can be used to draw attention to specific points on the chart. They can be added using chart:add_marker(marker), 
where 'marker' is a table of marker options, as described below:
 
  marker.label: Text label for the marker. Default is to use marker.index.
  
  marker.color: Colour for the marker. A simple hexadecimal value like 00FF00.
  
  marker.series: Which data series the marker should be on. Default is 0 (the first series)
  
  marker.index: The index of the data point to add the marker at. Default is 0 (the start of the series)
  
  marker.size: Text size of the marker's label. Default is 11 (for 11pt text)
 
  marker.priority: When to draw the marker
  	From the Google documentation:
  	 -1 specifies that the label is drawn before all other parts of the chart. The label will be 
  	    hidden if another chart element is drawn in the same place.
  	    
  	  0 specifies that the label is drawn after bars or lines, but before other labels. This is the default.
  	  
  	  1 specifies that the label is drawn after all other parts of the chart. If more than one label has this 
  	    value, the first one will be drawn first, the second one drawn second, and so on.

1	gchart.lua - Create charts using the Google Charts API
2
3	Google Charts API works on a very simple principle. You encode all the data about the chart you want
4	to render into a URL, and when you request this URL you will receive a PNG image of your chart.
5
6	The API is very fussy about the format of the data you pass it, so this library abstracts all that away,
7	and lets you create charts, manipulate them, and then build the URL when you are ready.
8
9	## Example
10
11	gchart = require "gchart"
12	gchart.default:set_color("C6D9FD");
13
14	mychart = gchart.new("bar")
15	mychart:add_series({ 100, 200, 100, 400 })
16
17	print("Chart:", chart:url());
18	--> Chart: http://chart.apis.google.com/chart?cht=bvs&chco=00CC00,CC0000&&chd=e:DwS0Dww7&chs=320x200
19
20	## Reference
21
22	### Defaults
23
24	gchart.lua exposes a default chart object. All charts will 'inherit' the properties from this chart unless you override them. For example:
25
26	gchart.default:set_color("C6D9FD") -- All charts will now be this colour by default
27
28	### Core
29
30	gchart.set_base_url(url): Set the base URL of the API. Default: "http://chart.apis.google.com/chart"
31	For example if another provider supports an API compatible with Google Charts, you could use this to switch gchart.lua to using their service instead.
32
33	gchart.new(type): Creates a new chart. Default type is "line".
34	Returns the new chart object.
35
36	### Charts
37
38	All these functions assume that 'chart' is a chart object returned from gchart.new().
39
40	chart:set_type(type): Set the type of chart.
41	May be one of "line", "sparkline", "plot", "bar" or a type code straight from the Google API, like "bhs".
42
43	chart:add_series(series): Add a new data series
44	Takes an array of numbers, each represinting a data point. For example { 10, 20, 30 }.
45
46	chart:set_scale(min, max): Set the minimum and maximum values for the chart
47	The Google Chart API does not automatically scale input data. By default gchart.lua will attempt
48	to scale the graph so that the base line is 25% lower than the lowest value on the graph, and the
49	top axis 25% higher than the highest value on the graph. Supply custom numbers for either or both of
50	min and max, or set to true for gchart.lua to auto-scale that value (default is to auto-scale both min
51	and max).
52
53	chart:set_size(width, height): Set the width and height of the generated chart in pixels
54	Google Chart API limits the maximum size of generated charts, the default size is 320x200.
55
56	chart:set_title(title): Set the title of the chart
57	The title will be displayed at the top of the chart. Both the '\|' (pipe) and \n (newline) characters
58	will start a new line (use for sub-titles).
59
60	chart:set_legend(entries): Add a legend to a chart
61	Set entries to a list of legend entries, in the same order as your data series were added. For example
62	{ "Temperature", "Rainfall", "Humidity" }.
63
64	chart:set_legend_position(position, layout): Set the position of the legend
65	position may be one of "top", "bottom", "left" or "right". Default is "right".
66	layout may be one of "vertical" or "horizontal". Default is "vertical". When using
67	the "horizontal" layout, the only valid positions are "top" and "bottom".
68
69	chart:add_axis(location, options): Add an axis to the chart
70	location may be one of "top", "bottom", "left" or "right".
71	options is an (optional) table allowing you to configure how the axis is displayed. For more info see
72	the 'Axes' section below.
73
74	chart:add_marker(marker): Add a marker to one or more datapoints
75	'marker' is a table of options. For more info see the 'Markers' section below.
76
77	chart:set_color(color): Set the colour of the graph lines
78	Colours are specified as hexidecimal values of red, green and blue, just as in HTML. An optional addition
79	is appending 2 further digits to specify the opacity. For example 50% transparent blue would be: 0000FFCC.
80	It is possible to specify multiple colours, separated by commas, which will be used differently according
81	to the chart type. For example "0000FFCC,FF0000CC".
82
83	chart:url(): Return the URL to render the chart
84	Last but not least, call this function to retrieve the URL to generate the graph with all properties applied.
85
86	## Axes
87
88	Axes are extremely flexible in Google Charts API. Add an axis with chart:add_axis(location, options) as described above. The 'options'
89	table may contain any of the following options:
90
91	options.range: Specify the range of the axis markers
92	For example: options.range = { min = 0, max = 500 }
93
94	options.labels: Specify text labels along the axis instead of numbers
95	For example: options.labels = { "Jan", "Feb", "Mar", "Apr" }
96	or with positions: options.labels = { Jan = 10, Feb = 20, Mar = 30, May = 50 }
97
98	options.style: Specify the style of an axis
99	Currently a string of the form: <axis color>,<font size>,<alignment>,<drawing control>,<tick mark color>
100	Only the colour is required, and further parameters are optional.
101	For example, a green axis: options.style = "00CC00"
102	and with 12pt text: options.style = "00CC00,12"
103
104	options.ticklength: Specify the length of the tickmarks on the axis
105	Must be a number. From the Google documentation:
106	"Positive values are drawn outside the chart area. The maximum positive value is 25."
107	"Negative values are drawn inside the chart area. Use this feature to draw gridlines on a chart."
108
109
110	## Markers
111
112	Markers can be used to draw attention to specific points on the chart. They can be added using chart:add_marker(marker),
113	where 'marker' is a table of marker options, as described below:
114
115	marker.label: Text label for the marker. Default is to use marker.index.
116
117	marker.color: Colour for the marker. A simple hexadecimal value like 00FF00.
118
119	marker.series: Which data series the marker should be on. Default is 0 (the first series)
120
121	marker.index: The index of the data point to add the marker at. Default is 0 (the start of the series)
122
123	marker.size: Text size of the marker's label. Default is 11 (for 11pt text)
124
125	marker.priority: When to draw the marker
126	From the Google documentation:
127	-1 specifies that the label is drawn before all other parts of the chart. The label will be
128	hidden if another chart element is drawn in the same place.
129
130	0 specifies that the label is drawn after bars or lines, but before other labels. This is the default.
131
132	1 specifies that the label is drawn after all other parts of the chart. If more than one label has this
133	value, the first one will be drawn first, the second one drawn second, and so on.