Add README

Wed, 24 Jun 2009 20:39:55 +0100

author
Matthew Wild <mwild1@gmail.com>
date
Wed, 24 Jun 2009 20:39:55 +0100
changeset 8
05052cfcefab
parent 7
a6977f303c2c
child 9
2712d960f70a

Add README

README file | annotate | diff | comparison | revisions
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Wed Jun 24 20:39:55 2009 +0100
@@ -0,0 +1,133 @@
+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());
+
+
+## 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. Use 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.
+

mercurial