comparison: README
README
- changeset 8
- 05052cfcefab
- child 9
- 2712d960f70a
equal
deleted
inserted
replaced
| 7:a6977f303c2c | 8:05052cfcefab |
|---|---|
| 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 |
