******************** * * * GOOGLE CHART API * * WRAPPER MODULE * * * ******************** Version 0.1 (until accepted) Copyright (c) Wiktor W. Brodlo Copyright (c) Drupal Google Chart Copyright (c) Google ~~~ CONTENTS ~~~ 1. Introducion/Abstract 2. Requirements 3. Basic concepts a) getting started b) data c) settings d) return values i ) success values ii) error values 4. Minimum needed 5. Settings reference ~~~ 1. Introduction/Abstract ~~~ This document explains how to use the Drupal wrapper module for Google Chart API. It is aimed at Drupal developers, documentation editors, other contributors as well as users. The Google Chart API takes some data and generates charts. User can submit a query (though a properly formed URL) and Google's servers will return a PNG image with the chart. It supports five types of graphs (and a few subtypes). It allows many different options and settings to be changed, as well as styles (sizes, colours, gradients) through modifying the URL (however, the over-use of styles is discouraged, it can potentially make your chart hard to read). This wrapper module helps in producing such URLs. See http://code.google.com/apis/chart/ for Google Chart API Guide. ~~~ 2. Requirements ~~~ A PHP interpreter is required. The code has been tested on PHP 5.2.2, but should work fine with other versions as well. No special configuration is needed as long as you can include or require files. It is designed to be a Drupal module, but will work fine with almost any system as long as you stick to the rules outlined in this document. ~~~ 3. Basic concepts ~~~ a) getting started First, you have to include the module file. You can, for example, do this through, require_once 'gchart.php'; or any other way deemed suitable. You are then ready to call chart(), the main function (there are a few other functions defined in the file but, unless you're doing development, you should not be bothered about them). The arguments and their possible use are explained in the later sections of this document. chart() takes two arguments, both of which are arrays. The first argument is $data, and the other is $settings: chart ( array $data, array $settings ) b) data $data is a single-dimensional array, each of the elements being arrays themselves. The arrays represent the datasets. There could be as few as one dataset, but it is not specified how many data sets could be passed. The elements of the dataset arrays are the data points (even if your dataset contains only one point, it should still be an array, however, if you have only one dataset, you do not have to create another array inside of it). The keys must be consecutive integers, starting from 0 (0, 1, 2, 3 and so on). The values can either be integers or floating point values with one decimal place. Use -1 to specify a missing value. You don't have to bother about converting the values into one of the encodings; the module does it automatically for you. $data = array( integer/float element1, integer/float element2, ... ) $data = array( array( integer/float element1, integer/float element2, ... ), array( integer/float element1, integer/float element2, ... ), ... ) Examples: $data = array(array(1, 4, 6, 10, -1, 40), array(1, 5, 10, 101, 27, 80)); $settings = (some settings, see ch. 3c); chart($data, $settings); Two datasets, six elements each. One value is missing (-1). $data = array(1); $settings = (some settings, see ch. 3c); chart($data, $settings); One data set, one element. $data = array(array(2, 3, 5, 11, 17, 80), array(100, 80, 60, 30, 30, 30, 10)); $settings = (some settings, see ch. 3c); chart($data, $settings); Two data sets, each having different number of points. $data = array(0.5, 3, 5.1, 11, 17, 80.9); $settings = (some settings, see ch. 3c); chart($data, $settings); An example of floating point fractions and integers. c) settings $settings is a multi-dimensional associative array, the first dimension always being a string identifying the setting. The next dimensions might contain additional parameters needed by a particular setting, but in most cases the last dimensions will correspond to the dataset, a point in that dataset, or both. Some of the settings accept numbers, others strings, others arrays, and some just about anything. All the settings, as well as the parameters they take and the accepted inputs are described in ch. 5. $settings[ string setting_key ][ param1 ][ param2 ]... = value; Required settings are: * width : width of the graph (integer, in pixels, 1 - 1000) * height : height of the graph (integer, in pixels, 1 - 1000) the total area of the graph cannot exceed 300 000 pixels * type : type of chart (string, one of the following: - lc - a simple line chart, each dataset is drawn as a line - lxy - line chart, a pair of datasets required, the first dataset corresponds to the x-axis, the second to the y-axis; multiple lines can be specified as pairs of datasets accordingly - bhs - horizontal bar chart, multiple datasets are stacked - bvs - vertical bar chart, multiple datasets are stacked - bhg - horizontal bar chart, multiple datasets are grouped - bvg - vertical bar chart, multiple datasets are grouped - p - a standard pie chart (only single dataset, subsequent sets are ignored) - p3 - a 3D pie chart (only single dataset, subsequent sets are ignored) - v - Venn diagram, single dataset (subsequent sets are ignored) with seven values: values 1-3: relative sizes of the three circles A, B, C (use -1 to remove one of the circles) value 4: area of A intersecting B value 5: area of B intersecting C value 6: area of C intersecting A value 7: area of A intersecting B intersecting C additional values are ignored - s - scatter plot; same as lxy, but the chm setting has to be set (see ch.s 4 and 5) Example: $settings['height'] = 300; $settings['width'] = 500; $settings['type'] = 'p'; The example should be self-explanatory. d) return values chart() returns a value on exit. The type of returned value will determine whether the function was successful (string) or not (integer). i ) success values This part is straight-forward, if the returned value is a string then the function exited successfully, and the returned string is the entire URL you need in order to get your chart. You could then eg. use the HTML tag with the URL to query for your chart, or do whatever you wish with it. ii) error values You get errors if one of the required settings and/or data was missed out or invalid. When an error occurs the function stops and returns an error code. When one of the optional settings is invalid, the value will simply be ignored, so you should always check your chart before you show it to audience. The error values, as defined in the module: Literal Hex Int Description ERROR_INVALID_DATASET 0x10 16 Data points are arrays (for multiple data sets) ERROR_INVALID_DATASET_TYPE 0x11 17 Data points are of wrong datatype ERROR_INVALID_WIDTH 0x12 18 Width is invalid (too small, too large, not an integer) ERROR_INVALID_HEIGHT 0x13 19 Height is invalid (too small, too large, not an integer) ERROR_INVALID_TYPE 0x14 20 Invalid graph type ERROR_CHART_TOO_LARGE 0x15 21 The chart is too large ~~~ 4. Minimum needed ~~~ In order to get the chart, you NEED to at least specify, depending on the chart type, one dataset (with at least one value in it; in some cases, like lxy or venn, you'll have to specify more datasets/values), and the following settings: chart height, width and type. Example: $data = array(5); $settings['height'] = 100; $settings['width'] = 200; $settings['type'] = 'lc' chart($data, $settings); An example of a 'minimum'. ~~~ 5. Settings reference ~~~ Most of the setting keys should be self-explanatory. All the parameters are required, except noted. All the numeric values can also be numeric strings. (color_code) is a 6 or 8 character RRGGBB or RRGGBBAA string representing a colour code. All values are inclusive. The format is: setting-key [parameter1][parameter2]... (type) defaults accepted values Explanation REQUIRED SETTINGS width (no parameters) (int) (no defaults) between 1 and 1000 The width of the chart, in pixels. height (no parameters) (int) (no defaults) between 1 and 1000 The height of the chart, in pixels. type (no parameters) (string) (no defaults) one of (lc,lxy,bhs,bvs,bhg,bvg,p,p3, v,s) The type of chart. See ch. 3c for more details about chart type. COLOURS datasetcolor [(int)dataset] (color_code) (ff9900) valid colour code Specifies the colour of the dataset line/bar/circle/part. (The following settings also work with the chart, just change 'background' to 'chart' in the key name.) backgroundfilltype (no parameters) (string) (no defaults) one of (s,lg,ls) Background fill type. s - solid fill lg - linear gradient fill ls - linear stripes fill This setting is required for background to be filled. backgroundfillcolor (no parameters) or [(int)id] (color_code) (no defaults) valid colour code Background colour. No parameters are accepted if fill type is s. If fill type is lg or ls, the parameter is required and will correspond to the identifier of the coloured area (used with offset/width, see below). This setting is required for background to be filled. backgroundfilloffset [(int)id] (float) (no defaults) between 0 and 1, 1 decimal place Background fill area offset. This is where the coloured area will reach full colour. The parameter is the identifier of the coloured area. 0 is the left-hand side (the rightmost point) of background, and 1 is the right-hand side (the leftmost point). This setting is required for gradient fill. This setting is ignored for any other fill type. backgroundfillwidth [(int)id] (float) (no defaults) between 0 and 1, 1 decimal place Background fill stripe width. This setting has nearly the same function as backgroundfilloffset, but is intended for linear stripes fill. It specifies the width of that particular stripe. This setting is required for stripe fill. This setting is ignored for any other fill type. backgroundfillangle (no parameters) (int) (no defaults) between 0 and 90 Background fill angle. The angle at which the stripes/gradients are drawn. This setting is required for stripe and gradient fill. This setting is ignored for any other fill type. LABELS title (no parameters) (string) (no defaults) any valid string The title of the chart. Use | or a line break to make a new line. This setting is required for the chart title to be shown. titlecolor (no parameters) (color_code) (000000) valid colour code The colour of the title. titlesize (no parameters) (float) (no defaults) any possible font size The size of the title font. label [(int)dataset] or [(int)datapoint] or [(int)circle] (string) (no defaults) any valid string The label of a dataset. For line, scatter and bar charts, they will appear on a legend (associated with the dataset), for pie charts as labels with lines pointing at an appropriate datapoint. For Venn diagrams, a legend will appear for the circles, same as with line charts. axis [(string)axis][(int)level] (array of string/int/float) (no defaults) anything Axis label. The axis parameter takes one of the values (x,y,r,t) and corresponds to the axis: t | ____/ y | ___/ |/ r |___________ x The level parameter corresponds to the level of the axis. You can have multiple levels of labels on one axis. These should be continuous. The values that should be displayed on the axes are assigned to that property. If you wish to set only one label, you don't need to make an array, but an array is required to use more labels on the same level. The values will be spaced out equally unless you use the axisposition setting. This setting is required for axis labels to be displayed. axisposition [(string)axis][(int)level] (array of int) (no defaults) between 0 and 100 The parameters are the same as for the axis setting. The values of the array correspond to the labels from that setting (and here you don't need to make an array for a single label, but you are required to be consistent). The values are the percentages along the axis, from the origin (0) to the end of the axis (100). This is where the values will be put, instead of being automatically spread out. axisrange [(string)axis][(int)level][(string)point] (int) (no defaults) valid integer Defines the range of the particular axis. The first two parameters are the same as with the two previous settings. The last parameter is one of (start, end). Both start and end have to be defined in order for this to work. The values can be anything, but if the range is too large the values will be too squeezed, and if the range is too small, not every value might be displayed. axiscolor [(string)axis][(int)level] (color_code) 666666 valid colour code The colour of the axis labels on the particular level. axissize [(string)axis][(int)level] (float) 11.5 any possible font size The font size of the axis labels on the particular level. STYLES datasetstyle [(int)dataset][(string)property] (float) (defaults depend on the property) single decimal place floats Defines the line style of the particular dataset. Applies only to line graphs. The property might be either of these (defaults are in brackets) - line - enables 'dashed-line'; defines how long the dash is (1) - blank - enables 'dashed-line'; defines how far apart are the dashes (0) - thick - defines how thick the line is (1.5) You may set as many properties as you want, the others will just remain as defaults. grid [(string)axisstep] (float) (no defaults) single decimal place floats Enables displaying of grid lines. The axisstep parameter allows to set how far apart are the lines. When set to xstep, it defines the step (how far apart are the lines) between the vertical lines, and when set to ystep - horizontal. If you do not specify the step for a particular direction, the fallback is first the labels (the step will be defined by the amount of labels), and then no gridlines in that direction at all. This setting is required for gridlines to be shown. gridstyle [(string)property] (float) (no defaults) single decimal place floats Defines the line style of the grid lines. Same as for datastyle (but here there is no thick property), but both properties have to be set for this to work. shapemarker [(int)dataset][(int)datapoint] (string) (no defaults) one of (a,c,d, o,s,v,V,h,x) The shape of the shape marker, for the particular datapoint of a particular dataset. a - arrow c - cross d - diamond o - circle s - square v - vertical line from the x-axis to the data point V - vertical line to the top of the chart h - horizontal line across the chart x - x shape This setting is required for shape markers to be shown. shapemarkercolor [(int)dataset][(int)datapoint] (color_code) 000000 valid colour code The colour code of the particular datapoint's (in the particular dataset) shape marker. shapemarkersize [(int)dataset][(int)datapoint] (int) 10 valid integer The size of the shape marker in pixels. Do not make it too large or it might clutter your diagram.