Wed, 24 Jun 2009 20:41:37 +0100
Minor fixes for the 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. | |
9 | 35 | |
8 | 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 | ||
9 | 119 | marker.series: Which data series the marker should be on. Default is 0 (the first series) |
8 | 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. | |
134 |