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