A jQuery plugin that sets a division to request a Google chart. If you find this plugin useful please vote for it on the jQuery site.
This page provides a documentation reference for working with the plugin v1.3.1. See a demonstration of the Google chart plugin and download the code from there. Or see a minimal page that you could use as a basis for your own investigations.
A separate chart instance is created for each targetted division
and may have its own settings:
$(selector).gchart({series: [...]});.
Below are the options that may be applied to each Google chart instance.
Although all are optional, you probably want to provide at least the data values
to be plotted via the series setting.
axes | backgroundColor | barGroupSpacing | barSpacing | barWidth | barZeroPoint | chartColor | dataLabels | encoding | extension | format | gridLine | gridOffsets | gridSize | height | icons | legend | legendOrder | legendSize | mapArea | mapColors | mapDefaultColor | mapRegions | margins | markers | maxValue | minValue | onLoad | opacity | pieOrientation | provideJSON | qrECLevel | qrMargin | ranges | series | title | titleColor | titleSize | type | usePost | visibleSeries | width
| Name | Type | Default | Comments |
|---|---|---|---|
| width | number | 0 | Set the width of the desired chart. If not set explicitly it defaults to the width of its containing division. Google imposes size restrictions on the charts, being 1000 pixels in either direction, but with an overall maximum of 300,000 pixels in area (e.g. 1000 x 300, 600 x 500). If either dimension exceeds 1000 it is reduced to this amount. If the image size is greater than the area limit the height is recalculated so that it is valid again. Map charts are restricted to 440 x 220 pixels in size. |
| height | number | 0 | Set the height of the desired chart. If not set explicitly
it defaults to the height of its containing division.
See width for restrictions. |
| format | string | 'png' | Set the image format to be returned: 'png' or 'gif'. Since 1.3.1. |
| usePost | boolean | false | Google charts normally uses a GET URL, which is limited to 2K in size.
For larger charts, set this setting to true to use POST instead.
This allows for requests up to 16K in size, but requires that the chart appear
within an iframe that is embedded in your containing division.Since 1.3.1. |
| margins | number or number[2] or number[4] | null | Set the minimum margins around the chart. The value may be a single number
representing identical margins all around or an array containing either
left/right and top/bottom margins or left, right, top, and bottom
margins in pixels. Leave as null for default margins.Since 1.2.0. |
| title | string | '' | Set the title of the chart as a whole. Include pipe (|) characters to indicate new lines. |
| titleColor | string | '' | Set the colour of the title. See the section on colour for more details. |
| titleSize | number | 0 | Set the size (pixels) of the chart title. |
| opacity | number | 0 | Set the opacity of the chart as a whole. The value may be specified either
in the range 0.0 to 1.0, or as a percentage from 0 to 100, with the
higher values indicating fully opaque. Leave as zero for fully opaque. Since 1.3.0. |
| backgroundColor | string or object | null | Set the background colour to be used for the entire image.
See the section on
colour for more details. If more than a single colour is required you can set this option to an object with the following attributes: angle (string or number) either a descriptive term
for the angle ('horizontal' for left to right, 'vertical' for
bottom to top, 'diagonalUp' for bottom/left to top/right, or
'diagonalDown' for top/left to bottom/right) or
the number of degrees from the positive x-axis (may be negative),striped (boolean) true for a series of distinct stripes
or false for a continuous gradient,colorPoints ([][2]) an array of two-item arrays containing
a colour and an offset from 0.0 (bottom/left) to 1.0 (top/right).See the gradient and
stripe functions for
an easy way to create simple gradients and stripes. |
| chartColor | string or object | null | Set the background colour for the chart itself.
See backgroundColor
above for more details. |
| legend | string | '' | Set the position of the legend: 'top', 'topVertical', 'bottom',
'bottomVertical', 'left', or 'right', or '' for none. Since 1.2.0 - added 'topVertical' and 'bottomVertical'. |
| legendOrder | string | 'normal' | Set the order of entries in the legend: 'normal' (in the order given), 'reverse'
(in the reverse of the order given), 'automatic' (order by length), or a list of
indexes (zero-based) separated by commas (,).Since 1.3.0. |
| legendSize | number[2] | null | Set the minimum size of the legend. The array contains width and height
in pixels. Leave as null for default size.
This setting is ignored if margins
is not set.Since 1.2.0. |
| type | string | 'pie3D' | Specify the type of chart required. line is a simple line chart with implied x-values. lineXY is a line chart with explicit x- and y-values. sparkline is a simple line chart with implied x-values and no axes. barHoriz is a bar chart oriented horizontally with stacked series. barVert is a bar chart oriented vertically with stacked series. barHorizGrouped is a bar chart oriented horizontally with side-by-side series. barVertGrouped is a bar chart oriented vertically with side-by-side series. pie is a two-dimensional pie chart showing a single series. pie3D is a three-dimensional pie chart showing a single series. pieConcentric is a two-dimensional pie chart showing multiple series in concentric rings. venn is a Venn diagram showing relationships between up to three sets, see the venn function for assistance in creating these diagrams.scatter is a chart of individual points specified as x- and y-values along with a size, see the scatter function for assistance in creating these charts.radar is a circular graph with values plotted out towards the perimeter, series are joined by straight lines. radarCurved is a circular graph with values plotted out towards the perimeter, series are joined by curved lines. map is a country or US state map shaded based on data values, see the map function for assistance in creating these charts.meter is a Google meter showing a single value, see the meter function for assistance in creating these charts.qrCode is a two-dimensional bar code that can encode text, see the qrCode function for assistance in creating these bar codes.formula is a mathematical formula, with the actual formula appearing as the single dataLabels value for the chart
using the TeX notation
(don't forget to escape any backslashes (\)).Since 1.2.0 - added 'pieConcentric'. Since 1.3.0 - added 'formula'. |
| encoding | string | '' | Set the type of encoding of data values to be used. text normalises the values to 0-100 and presents them as normal text with commas (,) separating values and pipes (|) separating series (the default). scaled doesn't normalise the values and presents them as normal text with commas (,) separating values and pipes (|) separating series. simple normalises the values to 0-61 and presents them as one character (A-Za-z0-9) with no value separator and commas (,) separating series. extended normalises the values to 0-4095 and presents them as two characters (A-Za-z0-9-.) with no value separator and commas (,) separating series. |
| series | object[] | [this.series('Hello World', [60, 40])] | Provide the data values to be charted. You can create the
series objects directly or you can use the
series function to generate a new series object.
Since an x-y line chart requires a special format
for the series, you should use the
seriesForXYLines
function to assist in that case.
Series data can also be loaded from external sources via the
seriesFromCsv and
seriesFromXml functions.Each entry in the array is an object with the following attributes: label (string, optional) the display text for this series,data (number[]) the data values to be plotted,color (string or string[], optional) the colour for the series -
see the section on
colour for more details; provide an array to specify colours
for each item in the series; if fewer colours than the number of segments
are given, the colours are recycled for the remaining segments,fillColor (string, optional) the background colour between
this series and the next one,minValue (number, optional) the minimum value for this series,maxValue (number, optional) the maximum value for this series,lineThickness (number, optional together with lineSegments)
the width (pixels) of the line for this series,lineSegments (number[2], optional together with lineThickness)
the lengths (pixels) of line segments and gaps when drawing the line for this series.Since 1.2.0 - color may be an array. |
| visibleSeries | number | 0 | Indicate how many series should be drawn directly. The remainder are still available
for use with markers. A value of 0 means that all series should be drawn.
The visible series must appear first in the list of series. Since 1.2.0. |
| dataLabels | string[] | [] | Specify the labels to apply to each of the data items in the series. Whereas the series labels apply to the entire series, these labels apply to all the first, second, etc. items across all the series. |
| axes | object[] | [] | Define any number of axis labels for your chart,
including multiple sets of labels for one axis.
Default labels range from 0 to 100 with 10 steps in between.
You can use the
axis function to assist in creating axis definitions
and the GChartAxis functions to modify them.Each entry in the array is either a string giving the axis name or a GChartAxis object with the following attributes:axis (string) the name of the axis to which this
definition applies ('top', 'left' or 'y', 'bottom' or 'x', 'right'),labels (string[], optional) the text labels to appear along this axis;
unless positioned as described below, these labels are evenly spaced
along the axis starting and ending at the edges of the chart;
if omitted numeric labels corresponding to each tenth of the range are shown,positions (number[], optional) the positions of the labels along the
axis ranging from the range start (0 by default) at the bottom/left
to the range end (100 by default) at the top/right;
if positions are defined but no labels are supplied,
then these values become the labels as well,range (number[2 or 3], optional) the start and end points of the range
of values depicted, which may be given as highest to lowest to invert the labels;
an optional third entry specifies the interval between points in the range;
if not specified a range of 0 to 100 and an interval of 1/10th the range is assumed,color (string, optional) the text colour for the labels;
see the section on
colour for more details,alignment (string, optional) the alignment of the labels
('left', 'center', 'right'); the default alignment changes per axis,size (number, optional) the size (pixels) of the text for the labels,drawing (string, optional) the drawing control to specify
what is drawn for the axis ('line', 'ticks', 'both' (default)),tickColor (string, optional) the colour of the tick marks;
defaults to axis colour,tickLength (number, optional) the length of the tick marks;
negative values are drawn inside the chart; the maximum positive value is 25,format (object, optional) formatting definition for the
axis values.Since 1.2.0 - added drawing,
tickColor, and tickLength attributes.Since 1.3.0 - added format attribute. |
| ranges | object[] | [] | Define any number of data ranges to display on your chart.
You can use the
range function to assist in creating range definitions.
Each entry in the array is an object with the following attributes:vertical (boolean) true to draw the range vertically
across the chart or false to draw it horizontally,color (string) the colour to be used for this range;
see the section on
colour for more details,start (number) the starting value for the range
between 0.0 at the bottom/left and 1.0 at the top/right,end (number, optional) the ending value for the range
between 0.0 at the bottom/left and 1.0 at the top/right;
if omitted a line is drawn rather than a rectangular area. |
| markers | object[] | [] | Define any number of markers to display on your chart.
You can use the
marker function to assist in creating marker definitions.
Each entry in the array is an object with the following attributes:shape (string) the type of shape to draw for this marker
('annotation', 'arrow', 'candlestick', 'circle', 'cross', 'diamond', 'down',
'errorbar', 'flag', 'financial', 'horizbar', 'horizontal', 'number', 'plus',
'rectangle', 'sparkfill', 'sparkline', 'sparkslice', 'square', 'text', 'vertical'),color (string) the colour to be used for this marker;
see the section on
colour below for more details,series (number, optinal) the index of the series to which
this marker applies (0 (default) to n),item (number or string or number[2 or 3], optional) the index of
the point within that series to which this marker applies (0-n)
or -1 or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the markers
or 'everyn[start:end]' where the values are numbers
to regularly space the markers within the given range of points
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them
or [x, y] positions (see positioned below),size (number, optional) the size (pixels) for this marker (default 10),priority (string or number, optional) the rendering priority of
this marker ('behind' or -1, 'normal' or 0 (the default), 'above' or +1),text (string, optional) the text to show
if this is a 'text' or 'flag' type marker or the number format
for a 'number' type marker - see the
numberFormat
function for formatting options,positioned (boolean, optional) true to absolutely position
the marker - the item value must be an array of two values
in the range 0.0 to 1.0placement (string or string[], optional) the placement
justification(s) ('left', 'center' or 'centre', 'right', 'top', 'middle',
'bottom', 'barbase', 'barcenter' or 'barcentre', 'bartop'),offsets (number[2], optional) the pixel offsets, horizontal
and vertical, from the calculated position.Since 1.1.0 - 'sparkfill' and 'sparkline' types. Since 1.2.0 - 'flag', 'financial', and 'number' types, ranges on item, positioned setting.Since 1.3.0 - 'annotation', 'errorbar', 'horizbar', 'rectangle', 'sparkslice' types, placement
and offsets settings.Since 1.3.1 - 'candlestick' as a synonym for 'financial' type. |
| icons | object[] | [] | Define any number of
dynamic icons to display on your chart.
You can use any of the
icon functions to assist in creating icon definitions.
Each entry in the array is an object with the following attributes:name (string) the full name of the icon,data (string) the encoded paramaters for this type of icon,series (number, optional) the index of the series to which
this icon applies (0 (default) to n),item (number or string or number[2 or 3], optional) the index of
the point within that series to which this icon applies (0-n)
or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the markers
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them,zIndex (number, optional) the z-index of
this icon from -1.0 (behind) through 0.0 (normal) to 1.0 (above),position (number[2], optional) the absolute position of
the icon centre from 0.0 (bottom/left) to 1.0 (top/right); if present
this override the series and item settings,offsets (number[2], optional) any pixel offsets from
the calculated position.Since 1.3.0. |
| minValue | number | 0 | The minimum value displayed on the chart.
Set to $.gchart.calculate to calculate the
minimum from the actual data values. |
| maxValue | number | 100 | The maximum value displayed on the chart.
Set to $.gchart.calculate to calculate the
maximum from the actual data values. |
| gridSize | number[2] | [] | Specify the horizontal and vertical spacing (pixels) between grid lines on the chart. |
| gridLine | number[2] | [] | Specify the appearance of the grid lines by providing the
lengths (pixels) of the line segments and the gaps between them.
A continuous line has a gap of zero. This setting is ignored
if gridSize hasn't been specified. |
| gridOffsets | number[2] | [] | Specify the offsets of the grid lines by providing the
x and y values (pixels). This setting is ignored if
gridSize and gridLine haven't been specified.Since 1.2.0. |
| extension | object | {} | Additional parameters may be passed to the Google chart request
via this object, whose attributes are transferred across. For example: {xyz: 4} would add &xyz=4. |
| barWidth | number or string | null | Specify the width (pixels) of the bars in a bar chart.
The width can also be set to $.gchart.barWidthAuto to
automatically resize the bars to fill the chart, or
$.gchart.barWidthRelative to resize the bars
based on the spacing between bars and groups being relative
to the width of a bar.Since 1.2.0 - can use $.gchart.barWidthAuto
or $.gchart.barWidthRelative. |
| barSpacing | number | null | Specify the spacing (pixels) between the bars within a group in a bar chart.
This setting has no effect unless barWidth is also set.
If barWidth is $.gchart.barWidthRelative
the value should be between 0.0 and 1.0. |
| barGroupSpacing | number | null | Specify the spacing (pixels) between groups of bars in a bar chart.
This setting has no effect unless barWidth and
barSpacing are also set.
If barWidth is $.gchart.barWidthRelative
the value should be between 0.0 and 1.0. |
| barZeroPoint | number | null | Specify the position of the zero line in a bar chart, ranging from 0.0 at the bottom/left to 1.0 at the top/right. The bars in the chart then extend from this line up or down to the value for each data point. |
| pieOrientation | number | 0 | Specify the starting angle for a pie chart in degrees from the
positive x-axis. Since 1.2.0. |
| mapArea | string | 'world' | Define the area to show in a map chart ('world', 'africa', 'asia', 'europe', 'middle_east', 'south_america', 'usa'). |
| mapRegions | string[] | [] | Specify the codes for the regions to be coloured on the map. Use the appropriate
ISO 3166 country codes
or US state codes
to identify the regions. The order in this array needs to match
that in the series data array. You can use the map function to assist in creating map options. |
| mapDefaultColor | string | 'bebebe' | Specify the colour used for regions without associated data. See the section on colour for more details. |
| mapColors | string[] | ['blue', 'red'] | Specify the starting and ending colours, or a gradient of colours, for coloured
regions on a map. Colours are calculated between these end points based on the
data value for each region relative to the maximum for the chart. Since 1.3.0 - colour gradient. |
| qrECLevel | string | null | Specify the error correction level to use for a QR code ('low' (default), 'medium', 'quarter', 'high'). |
| qrMargin | number | null | Specify the margin (squares) to leave around the outside of a QR code. The default is 4. |
| onLoad | function | null | Provide a callback function that is invoked when the chart
has been loaded. There are no parameters unless
provideJSON is true, while this
refers to the surrounding division.Since 1.2.3. |
| provideJSON | boolean | false | When true invoking the onLoad
callback also passes a JSON
description of the chart as a parameter. This description identifies
the various regions within the chart and can be used to
provide imagemap-like capabilities for it. Use the built-in
findRegion
function to convert from a mouse position into a chart region.Since 1.3.1. |
axis | 'change' | color | 'destroy' | findRegion | gradient | lineXYSeries | map | marker | meter | numberFormat | qrCode | range | scatter | series | seriesForXYLines | seriesFromCsv | seriesFromXml | setDefaults | stripe | venn
| Signature | Returns | Comments |
|---|---|---|
| $.gchart.setDefaults(options) | void | Update the default instance options (see options tab) to use with all Google chart instances. |
| $(div).gchart('change', options) | jQuery object | Update the options for the Google chart instance(s)
attached to the given division(s).options (object) the new settings for this chart. |
| $(div).gchart('change', name, value) | jQuery object | Update a single option for the Google chart instance(s)
attached to the given division(s).name (string) the name of setting to change,value (any) the setting's new value.Since 1.3.0. |
| $(div).gchart('destroy') | jQuery object | Remove the Google chart functionality from the given division(s). |
| $.gchart.series(label, data, colour, fillColour, minValue, maxValue, thickness, segments) | object | Generate a new series object for a chart for use with the
series option.label (string, optional) the label for this series,data (number[]) the data values for this series,colour (string or string[], optional) the colour for this series; provide an
array to specify colours for each item in the series; if fewer colours than the number
of segments are given, the colours are recycled for the remaining segments,fillColour (string, optional) the fill colour for this series
- from this line to the next,minValue (number, optional) the minimum value for this series -
both this and the next parameter should be present or both omitted,maxValue (number, optional) the maximum value for this series,thickness (number, optional) the thickness
(pixels) of the line for this series -
both this and the next parameter should be present or both omitted,segments (number[2], optional) the line and gap lengths
(pixels) of the line for this series.Since 1.2.0 - colour may be an array. |
| $.gchart.lineXYSeries(series) | object[] | Deprecated in favour of
seriesForXYLines.Since 1.1.0. |
| $.gchart.seriesForXYLines( series) | object[] | Transform a series into the format required for an x-y line chart
for use with the
series option.series (object[]) the details of the points to plot
as normal series, where
each data value may be an array of two points specifying the
x- and y-coordinate of the point. If you want to use the default
even spacing for one of the series, provide just the y-values.Since 1.1.0 - previously was lineXYSeries. |
| $.gchart.seriesFromCsv(csv) | object[] | Generate a set of series objects from data in CSV (comma-separated values)
format for use with the
series option.csv (string or string[]) the CSV data for all the series.Each line represents one series and consists of any number of data values and, optionally, additional details about the series. For the latter, a header line is required to identify the columns. They should be named for the series attributes ( label, color,
fillColor, minValue, maxValue,
lineThickness, lineSegmentLine,
lineSegmentGap) or be of the form yn,
where n is a sequential number, for the data values.
If you want to specify x-y line values, include columns named
xn before the corresponding y-values.
If x-values are not required for one series, leave the fields blank on that line.
If there is no header line, all entries are treated as data values.If the data reside remotely, use Ajax to retrieve it as text and pass that to this function. Since 1.1.0. |
| $.gchart.seriesFromXml(xml) | object[] | Generate a set of series objects from data in XML format for use with the
series option.xml (string or Document) the XML data for all the series with the
structure shown below. All attributes except point/@y are optional.
Use the point/@x attribute to specify an X-Y line point.
If the data reside remotely, use Ajax to retrieve it as XML and
pass that to this function.Since 1.1.0. |
| $.gchart.scatter(values, labels, colours, options) | options | Generate the options required for a
scatter chart.values (number[][]) the details of the points to plot,
each data value is an array of two or three numbers: the x- and
y-coordinates and an optional point size (0-100),labels (string[], optional) labels for groups within
the chart to appear in a legend; use
markers to depict the groups,colours (string[], optional) matching colours for the above labelled groups,options (object, optional) any additional options for this chart.Since 1.3.0 - added labels and
colours parameters. |
| $.gchart.venn(size1, size2, size3, overlap12, overlap13, overlap23, overlap123, options) | options | Generate the options required for a
Venn diagram.size1, size2, size3 (number) the relative sizes of the three sets,overlap12, overlap13, overlap23 (number) the
percentage overlaps between each pair of the three sets,overlap123 (number) the percentage overlap of all three sets,options (object, optional) any additional options for this chart. |
| $.gchart.map(mapArea, values, defaultColour, colour, endColour, options) | options | Generate the options required for a
map chart.mapArea (string, optional) the region of the map to show
('world' (default), 'africa', 'asia', 'europe',
'middle_east', 'south_america', 'usa'),values (object) the data values to plot;
each country/state is identified by its two-character code
(ISO 3166 country codes
or US state codes)
as an attribute name and the plotted value is the associated value,defaultColour (string, optional) the colour used for
regions without associated data; see the section on
colour for more details,colour (string, optional) the starting colour for a range or
(string[]) a set of gradient colours used for regions with associated data,endColour (string, optional) the ending colour for a range
used for regions with associated data (omit if colour is an array),options (object, optional) any additional options for this chart.Since 1.3.0 - colour may be an array. |
| $.gchart.meter(text, values, maxValue, colours, labels, styles, options) | options | Generate the options required for a
Google meter chart.text (string or string[], optional) the text to display at the end of the arrow(s),values (number or number[] or [] of these)
the position(s) of the arrow(s) grouped by series,maxValue (number, optional) the maximum value for the meter (default 100),colours (string[], optional) the colours to display blended across the band,labels (string[], optional) the labels to appear beneath the band,styles (number[] or number[][3 or 4], optional)
the styling of the arrows per series as either just the width or an array of
width, dash length, space length, and arrow size (0-15, optional),options (object, optional) any additional options for this chart.Since 1.2.0 - added colours parameter.Since 1.3.0 - text and value
may be arrays, added labels and styles parameters. |
| $.gchart.qrCode(text, encoding, ecLevel, margin) | options | Generate the options required for a
QR code.text (string) the text to encode into the bar code or
(object) these parameters as attributes of an object,encoding (string, optional) the encoding scheme to use
('UTF-8' (default), 'ISO-8859-1', 'Shift_JIS'),ecLevel (string, optional) the error correction level
('low' (default), 'medium', 'quarter', 'high'),margin (number, optional) the margin (squares) to leave around
the outside of the bar code (default 4). |
| $.gchart.axis(axis, labels, positions, rangeStart, rangeEnd, rangeInterval, colour, alignment, size, format) |
GChartAxis object |
Create an axis definition for use with the
axes option.axis (string) the name of the axis being defined
('top', 'bottom' or 'x', 'left' or 'y', 'right'),labels (string[], optional) the labels shown on this axis -
unless positioning details are included the labels are evenly spaced
along the axis starting and ending at the edges of the chart;
if omitted numeric labels corresponding to each tenth of the range are shown,positions (number[], optional - may only be present if
labels is present) the positions of the labels along the
axis ranging from the range start (0 by default) at the bottom/left
to the range end (100 by default) at the top/right;
if positions are defined but no labels are supplied,
then these values become the labels as well,rangeStart (number, optional) the starting value for the range of the axis,rangeEnd (number, optional - may only be present if
rangeStart is present) the ending value for the range of the axis;
this value may be less than the start of the range to invert the axis,rangeInterval (number, optional - may only be present if
rangeStart and rangeEnd are present)
the interval between values for the range of the axis;
note that it must be negative for an inverted range,colour (string, optional) the text colour for the labels;
see the section on colour for more details,alignment (string, optional) the alignment of the labels
('left', 'center', 'right'),size (number, optional) the size (pixels) of the text for the labels.format (object, optional) the number format settings for the labels;
see the axis object
format for more details.Since 1.2.0 - added rangeInterval parameter.Since 1.3.0 - added format parameter. |
| $.gchart.color(r, g, b, a) | string | Create a colour value in the format required by Google charts
(six or eight hexadecimal digits). You can specify the red/green/blue
and optional alpha (transparency) values (0-255) or the name of
a standard colour with an optional alpha value. You can always pass colour names directly as values to all functions. The standard colours are: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, orange, purple, red, silver, teal, transparent, white, yellow. r (string) the colour name or hex digits or
(number) the red component of the colour,g (number, optional) the green component of the colour
or the alpha component if r is a string,b (number, optional) the blue component of the colour,a (number, optional) the alpha (transparency)
component of the colour. |
| $.gchart.gradient(angle, colour1, colour2) | object | Create a simple colour gradient for a background for use with the
backgroundColor or
chartColor options.angle (string or number) the direction of the gradient
as a name ('horizontal', 'vertical', 'diagonalUp', 'diagonalDown')
or the number of degrees from the positive x-axis (may be negative),colour1 (string[]) a list of colours to evenly transform between
or (string) the start colour for the gradient (bottom/left);
see the section on colour for more details,colour2 (string) the end colour for the gradient (top/right);
omit if colour1 is an array. |
| $.gchart.stripe(angle, colours) | object | Create a simple colour striping for a background with equal widths for each stripe
for use with the
backgroundColor or
chartColor options.angle (string or number) the direction along which the stripes
are drawn as a name ('horizontal', 'vertical', 'diagonalUp', 'diagonalDown')
or the number of degrees from the positive x-axis (may be negative),colours (string[]) the colours for the stripes;
see the section on colour for more details. |
| $.gchart.marker(shape, colour, series, item, size, priority, text, positioned, placement, offsets) | object | Create a marker definition for use with the
markers option.shape (string) the type of shape to draw
('annotation', 'arrow', 'candlestick', 'circle', 'cross', 'diamond', 'down',
'errorbar', 'flag', 'financial', 'horizbar', 'horizontal', 'number', 'plus',
'rectangle', 'sparkfill', 'sparkline', 'sparkslice', 'square', 'text', 'vertical'),colour (string) the colour to be used for this marker;
see the section on colour for more details,series (number) the index of the series to which
this marker applies (0-n),item (number or string or number[1 to 3], optional) the index of
the point within that series to which this marker applies (0-n)
or -1 or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the markers
or 'everyn[start:end]' where the values are numbers
to regularly space the markers within the given range of points
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them
or [x, y] positions (see positioned below),size (number, optional) the size (pixels) for this marker (default 10);
both this and the following parameter may be omitted and text specified instead,priority (string or number, optional) the rendering
priority of this marker ('behind' or -1, 'normal' or 0 (default),
'above' or +1),text (string, optional - takes precedence over priority
if size is absent) the text to show if this is a 'text'
or 'flag' type marker or the number format for a 'number' type
marker - see the numberFormat
function for formatting options,positioned (boolean, optional) true to absolutely position
the marker - the item value must be an array of two values
in the range 0.0 to 1.0,placement (string or string[], optional) the placement justification(s)
('left', 'center' or 'centre', 'right', 'top', 'middle', 'bottom',
'barbase', 'barcenter' or 'barcentre', 'bartop'),offsets (number[2], optional) the pixel offsets, horizontal
and vertical, from the calculated position.Since 1.1.0 - 'sparkfill' and 'sparkline' types. Since 1.2.0 - 'flag', 'financial', and 'number' types, ranges on item, and positioned setting.Since 1.3.0 - added placement
and offsets parameters.Since 1.3.1 - 'candlestick' as a synonym for 'financial' type. |
| $.gchart.range(vertical, colour, start, end) | object | Create a range definition for use with the
ranges option.vertical (boolean, optional) true if a vertical range
or false if horizontal (default),colour (string) the colour of the range;
see the section on colour for more details,start (number) the starting point for the range (0.0 to 1.0),end (number, optional) the ending point for the range (0.0 to 1.0);
if omitted a line is drawn instead of a rectangular area. |
| $.gchart.numberFormat(type, prefix, suffix, precision, showX, zeroes, separators) | string | Generate a number format string for use with a 'number'
marker.type (string) the type of format: $.gchart.formatFloat ('f'),
$.gchart.formatPercent ('p'), $.gchart.formatScientific ('e'), or
$.gchart.formatCurrency ('c') - with the last you also need to add
the three-character currency designation, e.g. AUD or EUR,prefix (string, optional) the text that appears before each number,suffix (string, optional - may only be present if prefix is present)
the text that appears after each number,precision (number, optional) the number of decimal places to display,showX (boolean, optional) is true to display the x-value for the point
or false (default) to show the y-value,zeroes (boolean, optional - may only be present if showX is present)
is true to display trailing zeroes or false (default) to drop them,separators (boolean, optional - may only be present if
showX and zeroes are present) is true to
display group separators or false (default) to omit them.Since 1.2.0. |
| $.gchart.findRegion(event, jsonData) | object | Convert a mouse position into the underlying region of the chart. The returned
object has attributes: type being the type of element beneath the mouse,
such as 'bar', 'line', 'axis', 'legend', etc., series being the index
of the series to which this element applies, and point being the
index of the point to which this element applies, or -1 if none.
If there is no matching region at the mouse position, null is returned.event (MouseEvent) the mouse event for the position of interest,jsonData (object) the JSON description of the chart; obtained through the
onLoad and
provideJSON options.Since 1.3.1. |
These functions allow you to create
dynamic icons that may be added to your charts via the
icons setting.
Since 1.3.0.
To use functions other than icon you need to add the
jquery.gchart.icons.js module to your page.
bubbleIcon | icon | mapPinIcon | noteIcon | outlineIcon | weatherIcon
| Signature | Returns | Comments |
|---|---|---|
| $.gchart.icon(name, data, series, item, zIndex, position, offsets) | icon object | Create an icon definition. This is the basic interface, requiring
you to manually encode all parameters. Normally you would use one of the
more specific icon functions, but this one would be appropriate
for icons not covered by those.name (string) the name of the icon to use,data (string) the icon's encoded parameters, separated by commas (,),series (number, optional) the series to which the icon
applies (0 (default) to n),item (number or string or number[2 or 3], optional)
the item (default 0) in the series to which it applies
(include a fractional part for intermediate positioning)
or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the icons
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them,zIndex (number, optional) the z-index: -1.0 (behind)
through 0.0 (normal) to 1.0 (above),position (number[2], optional) an absolute chart position
(0.0 at bottom/left to 1.0 at top/right), which overrides a series and item,offsets (number[2], optional) pixel offsets from the calculated position. |
| $.gchart.bubbleIcon(text, image, tail, large, shadow, bgColour, colour, series, item, zIndex, position, offsets) | icon object | Create a
bubble icon definition, containing text and an optional image.text (string) the text content, use '|' for line breaks,image (string, optional) the
name of an inset image,tail (string, optional) the type of tail to use: 'bottomLeft' (default),
'topLeft', 'topRight', 'bottomRight', or 'none',large (boolean, optional) true if a large bubble is required,shadow (string, optional) indicate whether a shadow is included:
'no', 'yes' (default), 'only' (shadow but no text box),bgColour (string, optional) the icon background's
colour (default 'white'),colour (string, optional) the icon text's
colour (default 'black'),series (number, optional) the series to which the icon
applies (0 (default) to n),item (number or string or number[2 or 3], optional)
the item (default 0) in the series to which it applies
(include a fractional part for intermediate positioning)
or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the icons
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them,zIndex (number, optional) the z-index: -1.0 (behind)
through 0.0 (normal) to 1.0 (above),position (number[2], optional) an absolute chart position
(0.0 at bottom/left to 1.0 at top/right), which overrides a series and item,offsets (number[2], optional) pixel offsets from the calculated position. |
| $.gchart.mapPinIcon(letter, image, style, shadow, bgColour, colour, series, item, zIndex, position, offsets) | icon object | Create a
map pin icon definition, containing a letter or an image.letter (string) the single letter to show,image (string, optional) the
name of an inset image; if present it overrides the letter above,style (string, optional) the style of pin to use:
'' or 'none' (plain), 'star', 'left' (slant), or 'right' (slant),shadow (string, optional) indicate whether a shadow is included:
'no', 'yes', 'only' (shadow but no map pin),bgColour (string, optional) the icon background's
colour (default 'white'),colour (string, optional) the icon text's
colour (default 'black'),series (number, optional) the series to which the icon
applies (0 (default) to n),item (number or string or number[2 or 3], optional)
the item (default 0) in the series to which it applies
(include a fractional part for intermediate positioning)
or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the icons
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them,zIndex (number, optional) the z-index: -1.0 (behind)
through 0.0 (normal) to 1.0 (above),position (number[2], optional) an absolute chart position
(0.0 at bottom/left to 1.0 at top/right), which overrides a series and item,offsets (number[2], optional) pixel offsets from the calculated position. |
| $.gchart.noteIcon(title, text, type, large, alignment, colour, series, item, zIndex, position, offsets) | icon object | Create a
fun note icon definition, containing text and an optional image.title (string) the note title (displayed in bold),text (string, optional) the text content, use '|' for line breaks,type (string, optional) the type of note to show: 'arrow',
'balloon', 'pinned', 'sticky' (default), 'taped', or 'thought',large (boolean, optional) true if a large note is required,alignment (string, optional) the text alignment within the note:
'left', 'right', or 'center'/'centre' (default),colour (string, optional) the icon text's
colour (default 'black'),series (number, optional) the series to which the icon
applies (0 (default) to n),item (number or string or number[2 or 3], optional)
the item (default 0) in the series to which it applies
(include a fractional part for intermediate positioning)
or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the icons
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them,zIndex (number, optional) the z-index: -1.0 (behind)
through 0.0 (normal) to 1.0 (above),position (number[2], optional) an absolute chart position
(0.0 at bottom/left to 1.0 at top/right), which overrides a series and item,offsets (number[2], optional) pixel offsets from the calculated position. |
| $.gchart.weatherIcon(title, text, type, image, series, item, zIndex, position, offsets) | icon object | Create a
weather icon definition, containing text and an image.title (string) the note title (displayed in bold),text (string, optional) the text content, use '|' for line breaks,type (string, optional) the type of note to show: 'arrow',
'balloon', 'pinned', 'sticky' (default), 'taped', or 'thought',image (string, optional) the
name of an inset weather image (default 'sunny'),series (number, optional) the series to which the icon
applies (0 (default) to n),item (number or string or number[2 or 3], optional)
the item (default 0) in the series to which it applies
(include a fractional part for intermediate positioning)
or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the icons
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them,zIndex (number, optional) the z-index: -1.0 (behind)
through 0.0 (normal) to 1.0 (above),position (number[2], optional) an absolute chart position
(0.0 at bottom/left to 1.0 at top/right), which overrides a series and item,offsets (number[2], optional) pixel offsets from the calculated position. |
| $.gchart.outlineIcon(text, size, bold, alignment, colour, outline, series, item, zIndex, position, offsets) | icon object | Create a
outlined text icon definition, containing text and an optional image.text (string) the text content, use '|' for line breaks,size (number, optional) the text size in pixels (default 10),bold (boolean, optional) true if bold text is required (default false),alignment (string, optional) the text alignment within the note:
'left', 'right', or 'center'/'centre' (default),colour (string, optional) the icon text's fill
colour (default 'white'),outline (string, optional) the icon text's outline
colour (default 'black'),series (number, optional) the series to which the icon
applies (0 (default) to n),item (number or string or number[2 or 3], optional)
the item (default 0) in the series to which it applies
(include a fractional part for intermediate positioning)
or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the icons
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them,zIndex (number, optional) the z-index: -1.0 (behind)
through 0.0 (normal) to 1.0 (above),position (number[2], optional) an absolute chart position
(0.0 at bottom/left to 1.0 at top/right), which overrides a series and item,offsets (number[2], optional) pixel offsets from the calculated position. |
Various constants are available for your use.
| Name | Type | Comments |
|---|---|---|
| $.gchart.barWidthAuto | string | Assign this value to the barWidth
setting to have the bars in a bar chart automatically resize to fill the chart.Since 1.2.0. |
| $.gchart.barWidthRelative | string | Assign this value to the barWidth
setting to have the bars in a bar chart resized based on the
barSpacing and
barGroupSpacing
settings being relative values (0.0 to 1.0).Since 1.2.0. |
| $.gchart.calculate | number | Use this value for the
minValue or
maxValue settings to calculate from the actual data values. |
| $.gchart.formatFloat | string | Use this value for the type in a
numberFormat call for a floating point number.Since 1.2.0. |
| $.gchart.formatPercent | string | Use this value for the type in a
numberFormat call for a percentage value - multiplies the value by 100 and appends '%'.Since 1.2.0. |
| $.gchart.formatScientific | string | Use this value for the type in a
numberFormat call for a number in scientific notation (e.g. 1.234e5).Since 1.2.0. |
| $.gchart.formatCurrency | string | Use this value for the type in a
numberFormat call for a currency value in conjunction with the three-character
currency code - automatically displays the currency sign.Since 1.2.0. |
Due to the large number of details that define an axis,
they are now represented by a separate object (GChartAxis).
Use the
axis function to create GChartAxis objects and add them to the
chart with the axes
setting. Thereafter they may be updated via the functions listed below.
Since 1.2.0.
axis | drawing | format | labels | positions | range | style | ticks
| Signature | Returns | Comments |
|---|---|---|
| axis(axis) | GChartAxis object or string | Update the axis position for this axis or retrieve its
current value (if no parameters are supplied).axis (string) is the new position:
'top', 'bottom' or 'x', 'left' or 'y', or 'right'. |
| labels(labels) | GChartAxis object or string[] | Update the labels for this axis or retrieve the
current labels (if no parameters are supplied).
Unless positioned, these labels are evenly spaced
along the axis starting and ending at the edges of the chart.labels (string[]) is the new labels. |
| positions(positions) | GChartAxis object or number[] | Update the axis label positions for this axis or retrieve
the current label positions (if no parameters are supplied).
The positions of the labels along the axis are values from
the range start (0 by default) at the bottom/left
to the range end (100 by default) at the top/right.
If positions are defined but no labels are
supplied, then these values become the labels as well.positions (number[]) is the new label positions. |
| range(start, end, interval) | GChartAxis object or object | Update the range of values for this axis or retrieve
the current range (if no parameters are supplied)
as an object with start, end,
and interval attributes.start (number) is the starting value for the range,end (number) is the ending value for the range,
which may be less than the starting value to invert the labels,interval (number, optional) is the interval between values
in the range, and defaults to 1/10th of the range. |
| style(colour, alignment, size) | GChartAxis object or object | Update the style for this axis or retrieve
the current style (if no parameters are supplied)
as an object with color, alignment,
and size attributes.colour (string) is the colour for the axis, and also applies to the
tick marks unless tick colour is specified;
see the section on
colour for more details,alignment (string, optional) is the alignment for
the axis labels: 'left', 'center', or 'right',size (number, optional) is the size of the label font in pixels. |
| drawing(drawing) | GChartAxis object or string | Update the drawing control for this axis or retrieve
the current drawing control (if no parameters are supplied).drawing (string) is the new drawing control:
'line', 'ticks', or 'both'. |
| ticks(colour, length) | GChartAxis object or object | Update the tick mark style for this axis or retrieve
the current tick mark style (if no parameters are supplied)
as an object with color and length attributes.colour (string) is the colour for the tick marks, and
overrides the axis colour setting;
see the section on
colour for more details,length (number, optional) is the length of the tick marks;
negative values draw inside the chart; the maximum positive value is 25. |
| format(type, prefix, suffix, precision, showX, zeroes, separators) | GChartAxis object or object | Update the number format for the axis labels or retrieve
the current number format style (if no parameters are supplied)
as an object with type, prefix, suffix,
precision, showX, zeroes,
and separators attributes.type (string) the type of format: $.gchart.formatFloat ('f'),
$.gchart.formatPercent ('p'), $.gchart.formatScientific ('e'), or
$.gchart.formatCurrency ('c') - with the last you also need to add
the three-character currency designation, e.g. AUD or EUR,prefix (string, optional) the text that appears before each number,suffix (string, optional - may only be present if prefix is present)
the text that appears after each number,precision (number, optional) the number of decimal places to display,showX (boolean, optional) is true to display the x-value for the point
or false (default) to show the y-value,zeroes (boolean, optional - may only be present if showX is present)
is true to display trailing zeroes or false (default) to drop them,separators (boolean, optional - may only be present if
showX and zeroes are present) is true to
display group separators or false (default) to omit them.Since 1.3.0. |
Contact Keith Wood at kbwood{at}iinet.com.au with comments or suggestions.