The author would appreciate an email letting him know of any substantial use of jqPlot. You can reach the author at: chris at jqplot dot com or see http://www.jqplot.com/info.php. This is, of course, not required.

Introduction

jqPlot requires jQuery (1.4+ required for certain features). jQuery 1.4.2 is included in the distribution. To use jqPlot include jQuery, the jqPlot jQuery plugin, the jqPlot css file and optionally the excanvas script for IE support in your web page:

Options Usage

Changes

$.jqplot

Parameters

user defined options object. See the individual classes for available options.

Properties

config

object to hold configuration information for jqPlot plot object.

attributes

enablePlugins

False to disable plugins by default. Plugins must then be explicitly enabled in the individual plot options. Default: false. This property sets the “show” property of certain plugins to true or false. Only plugins that can be immediately active upon loading are affected. This includes non-renderer plugins like cursor, dragable, highlighter, and trendline.

defaultHeight

Default height for plots where no css height specification exists. This is a jqplot wide default.

defaultWidth

Default height for plots where no css height specification exists. This is a jqplot wide default.

label

showLabel

min

max

this.max = null

maximum value of the axis (in data units, not pixels).

autoscale

this.autoscale = false

DEPRECATED the default scaling algorithm produces superior results.

pad

this.pad = 1.2

Padding to extend the range above and below the data bounds. The data range is multiplied by this factor to determine minimum and maximum axis bounds. A value of 0 will be interpreted to mean no padding, and pad will be set to 1.0.

padMax

this.padMax = null

Padding to extend the range above data bounds. The top of the data range is multiplied by this factor to determine maximum axis bounds. A value of 0 will be interpreted to mean no padding, and padMax will be set to 1.0.

padMin

this.padMin = null

Padding to extend the range below data bounds. The bottom of the data range is multiplied by this factor to determine minimum axis bounds. A value of 0 will be interpreted to mean no padding, and padMin will be set to 1.0.

ticks

this.ticks = []

1D [val, val, ...] or 2D [[val, label], [val, label], ...] array of ticks for the axis. If no label is specified, the value is formatted into an appropriate label.

numberTicks

this.numberTicks

Desired number of ticks. Default is to compute automatically.

tickInterval

this.tickInterval

number of units between ticks. Mutually exclusive with numberTicks.

renderer

this.renderer = $.jqplot.LinearAxisRenderer

A class of a rendering engine that handles tick generation, scaling input data to pixel grid units and drawing the axis element.

rendererOptions

showTicks

Wether to show the ticks (both marks and labels) or not. Will not override showMark and showLabel options if specified on the ticks themselves.

showTickMarks

this.showTickMarks = true

Wether to show the tick marks (line crossing grid) or not. Overridden by showTicks and showMark option of tick itself.

showMinorTicks

this.showMinorTicks = true

Wether or not to show minor ticks. This is renderer dependent.

drawMajorGridlines

this.drawMajorGridlines = true

True to draw gridlines for major axis ticks.

drawMinorGridlines

this.drawMinorGridlines = false

True to draw gridlines for minor ticks.

drawMajorTickMarks

this.drawMajorTickMarks = true

True to draw tick marks for major axis ticks.

drawMinorTickMarks

this.drawMinorTickMarks = true

True to draw tick marks for minor ticks. This is renderer dependent.

useSeriesColor

this.useSeriesColor = false

Use the color of the first series associated with this axis for the tick marks and line bordering this axis.

borderWidth

this.borderWidth = null

width of line stroked at the border of the axis. Defaults to the width of the grid boarder.

borderColor

this.borderColor = null

color of the border adjacent to the axis. Defaults to grid border color.

scaleToHiddenSeries

this.scaleToHiddenSeries = false

True to include hidden series when computing axes bounds and scaling.

syncTicks

this.syncTicks = null

true to try and synchronize tick spacing across multiple axes so that ticks and grid lines line up. This has an impact on autoscaling algorithm, however. In general, autoscaling an individual axis will work better if it does not have to sync ticks.

tickSpacing

this.tickSpacing = 75

Approximate pixel spacing between ticks on graph. Used during autoscaling. This number will be an upper bound, actual spacing will be less.

Legend

Legend object. Cannot be instantiated directly, but created by the Plot object. Legend properties can be set or overridden by the options passed in from the user.

Properties

show

location

labels

Array of labels to use. By default the renderer will look for labels on the series. Labels specified in this array will override labels specified on the series.

showLabels

this.showLabels = true

true to show the label text on the legend.

showSwatch

this.showSwatches = true

true to show the color swatches on the legend.

placement

this.placement = "insideGrid"

”insideGrid” places legend inside the grid area of the plot. “outsideGrid” places the legend outside the grid but inside the plot container, shrinking the grid to accomodate the legend. “inside” synonym for “insideGrid”, “outside” places the legend ouside the grid area, but does not shrink the grid which can cause the legend to overflow the plot container.

xoffset

this.xoffset = 0

DEPRECATED. Set the margins on the legend using the marginTop, marginLeft, etc. properties or via CSS margin styling of the .jqplot-table-legend class.

yoffset

this.yoffset = 0

DEPRECATED. Set the margins on the legend using the marginTop, marginLeft, etc. properties or via CSS margin styling of the .jqplot-table-legend class.

border

this.border

css spec for the border around the legend box.

background

this.background

css spec for the background of the legend box.

textColor

this.textColor

css color spec for the legend text.

fontFamily

this.fontFamily

css font-family spec for the legend text.

fontSize

this.fontSize

css font-size spec for the legend text.

rowSpacing

this.rowSpacing = '0.5em'

css padding-top spec for the rows in the legend.

rendererOptions

this.rendererOptions = {}

renderer specific options passed to the renderer.

predraw

Wether to draw the legend before the series or not. Used with series specific legend renderers for pie, donut, mekko charts, etc.

marginTop

this.marginTop = null

CSS margin for the legend DOM element. This will set an element CSS style for the margin which will override any style sheet setting. The default will be taken from the stylesheet.

marginRight

this.marginRight = null

CSS margin for the legend DOM element. This will set an element CSS style for the margin which will override any style sheet setting. The default will be taken from the stylesheet.

marginBottom

this.marginBottom = null

CSS margin for the legend DOM element. This will set an element CSS style for the margin which will override any style sheet setting. The default will be taken from the stylesheet.

marginLeft

this.marginLeft = null

CSS margin for the legend DOM element. This will set an element CSS style for the margin which will override any style sheet setting. The default will be taken from the stylesheet.

escapeHtml

this.escapeHtml = false

True to escape special characters with their html entity equivalents in legend text. “<” becomes &lt; and so on, so html tags are not rendered.

Title

Plot Title object. Cannot be instantiated directly, but created by the Plot object. Title properties can be set or overridden by the options passed in from the user.

Properties

Properties will be assigned from a series array at the top level of the options. If you had two series and wanted to change the color and line width of the first and set the second to use the secondary y axis with no shadow and supply custom labels for each:

showLabel

color

negativeColor

css color spec used for filled (area) plots that are filled to zero and the “useNegativeColors” option is true.

lineWidth

this.lineWidth = 2.5

width of the line in pixels. May have different meanings depending on renderer.

lineJoin

this.lineJoin = 'round'

Canvas lineJoin style between segments of series.

lineCap

this.lineCap = 'round'

Canvas lineCap style at ends of line.

linePattern

this.linePattern = 'solid'

line pattern ‘dashed’, ‘dotted’, ‘solid’, some combination of ‘-’ and ‘.’ characters such as ‘.-.’ or a numerical array like [draw, skip, draw, skip, ...] such as [1, 10] to draw a dotted line, [1, 10, 20, 10] to draw a dot-dash line, and so on.

shadowAngle

this.shadowAngle = 45

Shadow angle in degrees

shadowOffset

this.shadowOffset = 1.25

Shadow offset from line in pixels

shadowDepth

this.shadowDepth = 3

Number of times shadow is stroked, each stroke offset shadowOffset from the last.

shadowAlpha

this.shadowAlpha = '0.1'

Alpha channel transparency of shadow. 0 = transparent.

breakOnNull

this.breakOnNull = false

Wether line segments should be be broken at null value. False will join point on either side of line.

markerRenderer

this.markerRenderer = $.jqplot.MarkerRenderer

A class of a renderer which will draw marker (e.g. circle, square, ...) at the data points, see $.jqplot.MarkerRenderer.

markerOptions

showLine

whether to actually draw the line or not. Series will still be renderered, even if no line is drawn.

showMarker

this.showMarker = true

whether or not to show the markers at the data points.

index

this.index

0 based index of this series in the plot series array.

fill

this.fill = false

true or false, whether to fill under lines or in bars. May not be implemented in all renderers.

fillColor

this.fillColor

CSS color spec to use for fill under line. Defaults to line color.

fillAlpha

this.fillAlpha

Alpha transparency to apply to the fill under the line. Use this to adjust alpha separate from fill color.

fillAndStroke

this.fillAndStroke = false

If true will stroke the line (with color this.color) as well as fill under it. Applies only when fill is true.

disableStack

this.disableStack = false

true to not stack this series with other series in the plot. To render properly, non-stacked series must come after any stacked series in the plot’s data series array. So, the plot’s data series array would look like:

disableStack will put a gap in the stacking order of series, and subsequent stacked series will not fill down through the non-stacked series and will most likely not stack properly on top of the non-stacked series.

neighborThreshold

this.neighborThreshold = 4

how close or far (in pixels) the cursor must be from a point marker to detect the point.

fillToZero

this.fillToZero = false

true will force bar and filled series to fill toward zero on the fill Axis.

fillToValue

this.fillToValue = 0

fill a filled series to this value on the fill axis. Works in conjunction with fillToZero, so that must be true.

fillAxis

this.fillAxis = 'y'

Either ‘x’ or ‘y’. Which axis to fill the line toward if fillToZero is true. ‘y’ means fill up/down to 0 on the y axis for this series.

useNegativeColors

this.useNegativeColors = true

true to color negative values differently in filled and bar charts.

Grid

Object representing the grid on which the plot is drawn. The grid in this context is the area bounded by the axes, the area which will contain the series. Note, the series are drawn on their own canvas. The Grid object cannot be instantiated directly, but is created by the Plot object. Grid properties can be set or overridden by the options passed in from the user.

This method requires jQuery 1.4+ Restore the series canvas order to its original order when the plot was created.

Properties

These properties are specified at the top of the options object like so:

{
axesDefaults:{min:0},
series:[{color:'#6633dd'}],
title: 'A Plot'
}

animate

this.animate = false

True to animate the series on initial plot draw (renderer dependent). Actual animation functionality must be supported in the renderer.

animateReplot

this.animateReplot = false

True to animate series after a call to the replot() method. Use with caution! Replots can happen very frequently under certain circumstances (e.g. resizing, dragging points) and animation in these situations can cause problems.

axes

this.axes = {xaxis: new Axis('xaxis'), yaxis: new Axis('yaxis'), x2axis: new Axis('x2axis'), y2axis: new Axis('y2axis'), y3axis: new Axis('y3axis'), y4axis: new Axis('y4axis'), y5axis: new Axis('y5axis'), y6axis: new Axis('y6axis'), y7axis: new Axis('y7axis'), y8axis: new Axis('y8axis'), y9axis: new Axis('y9axis'), yMidAxis: new Axis('yMidAxis')}

up to 4 axes are supported, each with its own options, See Axis for axis specific options.

data

this.data = []

user’s data. Data should NOT be specified in the options object, but be passed in as the second argument to the $.jqplot() function. The data property is described here soley for reference. The data should be in the form of an array of 2D or 1D arrays like

[ [[x1, y1], [x2, y2],...], [y1, y2, ...] ].

dataRenderer

this.dataRenderer

A callable which can be used to preprocess data passed into the plot. Will be called with 3 arguments: the plot data, a reference to the plot, and the value of dataRendererOptions.

dataRendererOptions

this.dataRendererOptions

Options that will be passed to the dataRenderer. Can be of any type.

axesDefaults

default options that will be applied to all axes. see Axis for axes options.

seriesDefaults

seriesDefaults: {}, series:[] }

default options that will be applied to all series. see Series for series options.

defaultAxisStart

this.defaultAxisStart = 1

1-D data series are internally converted into 2-D [x,y] data point arrays by jqPlot. This is the default starting value for the missing x or y value. The added data will be a monotonically increasing series (e.g. [1, 2, 3, ...]) starting at this value.

fillBetween

Fill between 2 line series in a plot. Options object: { series1: first index (0 based) of series in fill series2: second index (0 based) of series in fill color: color of fill [default fillColor of series1] baseSeries: fill will be drawn below this series (0 based index) fill: false to turn off fill [default true]. }

noDataIndicator

Options to set up a mock plot with a data loading indicator if no data is specified.

negativeSeriesColors

this.negativeSeriesColors = $.jqplot.config.defaultNegativeColors

colors to use for portions of the line below zero.

series

this.series = []

Array of series object options. see Series for series specific options.

seriesColors

this.seriesColors = $.jqplot.config.defaultColors

Ann array of CSS color specifications that will be applied, in order, to the series in the plot. Colors will wrap around so, if their are more series than colors, colors will be reused starting at the beginning. For pie charts, this specifies the colors of the slices.

sortData

this.sortData = true

false to not sort the data passed in by the user. Many bar, stacked and other graphs as well as many plugins depend on having sorted data.

stackSeries

this.stackSeries = false

true or false, creates a stack or “mountain” plot. Not all series renderers may implement this option.

title

this.title = new Title()

Title object. See Title for specific options. As a shortcut, you can specify the title option as just a string like: title: ‘My Plot’ and this will create a new title object with the specified text.

methods

init

this.init = function(

target,

data,

options

)

sets the plot target, checks data and applies user options to plot.

resetAxesScale

this.resetAxesScale = function(

axes,

options

)

Reset the specified axes min, max, numberTicks and tickInterval properties to null or reset these properties on all axes if no list of axes is provided.

Parameters

axes

Boolean to reset or not reset all axes or an array or object of axis names to reset.

reInitialize

this.reInitialize = function (

data,

opts

)

reinitialize plot for replotting. not called directly.

quickInit

this.quickInit = function ()

Quick reinitialization plot for replotting. Does not parse options ore recreate axes and series. not called directly.

destroy

this.destroy = function()

Releases all resources occupied by the plot

replot

this.replot = function(

options

)

Does a reinitialization of the plot followed by a redraw. Method could be used to interactively change plot characteristics and then replot.

Parameters

options

Options used for replotting.

Properties

clear

false to not clear (empty) the plot container before replotting (default: true).

redraw

this.redraw = function(

clear

)

Empties the plot target div and redraws the plot. This enables plot data and properties to be changed and then to comletely clear the plot and redraw. redraw will not reinitialize any plot elements. That is, axes will not be autoscaled and defaults will not be reapplied to any plot elements. redraw is used primarily with zooming.

Parameters

clear

false to not clear (empty) the plot container before redrawing (default: true).

draw

this.draw = function()

Draws all elements of the plot into the container. Does not clear the container before drawing.

drawSeries

this.drawSeries = function(

options,

idx

)

Redraws all or just one series on the plot. No axis scaling is performed and no other elements on the plot are redrawn. options is an options object to pass on to the series renderers. It can be an empty object {}. idx is the series index to redraw if only one series is to be redrawn.

moveSeriesToFront

this.moveSeriesToFront = function (

idx

)

This method requires jQuery 1.4+ Moves the specified series canvas in front of all other series canvases. This effectively “draws” the specified series on top of all other series, although it is performed through DOM manipulation, no redrawing is performed.

Parameters

idx

0 based index of the series to move. This will be the index of the series as it was first passed into the jqplot function.

moveSeriesToBack

this.moveSeriesToBack = function (

idx

)

This method requires jQuery 1.4+ Moves the specified series canvas behind all other series canvases.

Parameters

idx

0 based index of the series to move. This will be the index of the series as it was first passed into the jqplot function.

restorePreviousSeriesOrder

this.restorePreviousSeriesOrder = function ()

This method requires jQuery 1.4+ Restore the series canvas order to its previous state. Useful to put a series back where it belongs after moving it to the front.

restoreOriginalSeriesOrder

this.restoreOriginalSeriesOrder = function ()

This method requires jQuery 1.4+ Restore the series canvas order to its original order when the plot was created.