Tue, 01 Dec 2009 13:53:46 +0000
Use correct seperator between ranges
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. 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.