# HG changeset patch # User Matthew Wild # Date 1245872395 -3600 # Node ID 05052cfcefab42e449759eefafc0f0c2ab1933c6 # Parent a6977f303c2c180811b254b376b3617ea69029eb Add README diff -r a6977f303c2c -r 05052cfcefab README --- /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: ,,,, + 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. +