You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
243 lines
8.7 KiB
243 lines
8.7 KiB
Title: Options Tutorial |
|
|
|
This document will help you understand how jqPlot's options |
|
relate to the API documentation and the jqPlot object |
|
itself. For a listing of options available to jqPlot, |
|
see <jqPlot Options> in the jqPlotOptions.txt file. |
|
|
|
The key to effectively using jqPlot is understanding jqPlot's |
|
options. The online documentation is API documentation. While |
|
it explains what attributes and methods various objects possess, |
|
it doesn't explain how to use or set those attributes through |
|
options. This tutorial will help explain that. |
|
|
|
Let's assume you are creating a plot |
|
like this: |
|
|
|
> chart = $.jqplot('chart', dataSeries, optionsObj); |
|
|
|
First, note that you shouldn't try to directly set attributes on the |
|
"chart" object (like chart.grid.shadow) after your call to $.jqplot(). |
|
At best this won't do anything **(see below). You should pass options in via |
|
the "optionsObj". |
|
|
|
The optionsObj really represents the plot object (jqPlot object, not |
|
to be confused with the $.jqplot function which will create a jqPlot |
|
object). Attributes you specify on that object will be merged with |
|
attributes in the jqPlot object. The axes, legend, series, etc. are |
|
attributes on the jqPlot object. The jqPlot/optionsObj object looks |
|
something like (only some attributes shown): |
|
|
|
> jqPlot-| |
|
> |-seriesColors |
|
> |-textColor |
|
> |-fontFamily |
|
> |-fontSize |
|
> |-stackSeries |
|
> |-series(Array)-| |
|
> | |-Series1-| |
|
> | | |-lineWidth |
|
> | | |-linePattern |
|
> | | |-shadow |
|
> | | |-showLine |
|
> | | |-showMarker |
|
> | | |-color |
|
> | |-Series2... |
|
> | |-... |
|
> | |-SeriesN |
|
> | |
|
> |-grid(Object)-| |
|
> | |-drawGridLines |
|
> | |-background |
|
> | |-borderColor |
|
> | |-borderWidth |
|
> | |-shadow |
|
> | |
|
> |-title(Object)-| |
|
> | |-text |
|
> | |-show |
|
> | |-fontFamily |
|
> | |-fontSize |
|
> | |-textAlign |
|
> | |-textColor |
|
> | |
|
> |-axes(Object)-| |
|
> | |-xais-| |
|
> | | |-min |
|
> | | |-max |
|
> | | |-numberTicks |
|
> | | |-showTicks |
|
> | | |-showTickMarks |
|
> | | |-pad |
|
> | |
|
> | ... and so on |
|
|
|
The optionsObj should follow the same construction as if it were a |
|
jqPlot object (with some exceptions/shortcuts I'll mention in a |
|
moment). So generally, when you see something like |
|
"this.drawGridLines" in the grid properties in the docs, just replace |
|
"this" with "grid" in your options object. So it becomes |
|
optionsObj.grid.drawGridLines. Do likewise with the other objects in |
|
the plot, replacing "this", with the respective attribute on the plot |
|
like "legend" or "title". Series and Axes are handled a little |
|
differently, because series is an array and axes has 4 distinct children |
|
"xaxis", "yaxis", "x2axis" and "y2axis". |
|
|
|
So, to remove the shadow from the grid and change the grid border size |
|
you would do: |
|
|
|
> optionObj = {grid:{shadow:false, borderWidth:9.0}}; |
|
|
|
To do the same as above but also make all the text in the plot red you |
|
would do: |
|
|
|
> optionObj = { |
|
> textColor:"#ff0000", |
|
> grid:{shadow:false, borderWidth:9.0} |
|
> } |
|
|
|
Here is a more deeply nested example. Say you want to specify a min |
|
and max on your y axis and use a specific color for your second |
|
series. That would look like: |
|
|
|
> optionsObj = { |
|
> axes:{yaxis:{min:5, max:230}}, |
|
> series:[{},{color:"#33ff66"}] |
|
> } |
|
|
|
Note that series options are an array in order of the series data you |
|
sent in to your plot. To get to the second series, you have to put an |
|
object (even if empty) in place of the first series. |
|
|
|
There is a handy shortcut to assign options to all axes or all series |
|
at one go. Use axesDefaults and seriesDefaults. So, if you wanted |
|
both x and y axes to start at 0 and you wanted all series to not show |
|
markers, you could do: |
|
|
|
> optionsObj = {axesDefaults:{min:0}, seriesDefaults:{showMarker:false}} |
|
|
|
Another shortcut is for the plot title. Normally, you would assign |
|
options to the title as an object. If you specify a title option as a |
|
string, it will assign that to the title.text property automatically. |
|
So these two are equivalent: |
|
|
|
> optionsObj = {title:{text:"My Plot"}} |
|
|
|
and |
|
|
|
> optionsObj = {title:"My Plot"} |
|
|
|
Where things need more explanation is with renderers, plugins and |
|
their options. Briefly, what's the difference between a renderer and |
|
a plugin. |
|
|
|
A renderer is an object that is used to draw something and gets |
|
attached to an existing object in the plot in order to draw it. A |
|
plugin does more than just provide drawing functionality to an |
|
object; it can calculate a trend line, change the |
|
cursor, provide event driven functionality, etc. I consider renderers |
|
plugins, but plugins don't have to be renderers. |
|
|
|
So, how do you use renderers and plugins, and specify their options? |
|
Some common renderers are for bar charts and category axes. If you |
|
want to render your series as a bar chart with each set of bars |
|
showing up in a category on the x axis, you do: |
|
|
|
> optionsObj = { |
|
> seriesDefaults:{renderer:$.jqplot.BarRenderer}, |
|
> axes:{xaxis:{renderer:$.jqplot.CategoryAxisRenderer}} |
|
> } |
|
|
|
This replaces the default renderer used for all series in the plot |
|
with a bar renderer and the x axis default renderer (but not any other |
|
axis) with a category renderer. |
|
|
|
Now, how would I assign options to those renderers? The renderer's |
|
attributes may not be present in the pre-existing jqPlot object, they |
|
may be specific to the renderer. This is done through the |
|
"rendererOptions" option on the appropriate object. So, if I wanted my |
|
bars to be 25 pixels wide, I would do: |
|
|
|
|
|
> optionsObj = { |
|
> seriesDefaults:{ |
|
> renderer:$.jqplot.BarRenderer}, |
|
> rendererOptions:{ |
|
> barWidth:25 |
|
> }, |
|
> axes:{xaxis:{renderer:$.jqplot.CategoryAxisRenderer}} |
|
> } |
|
|
|
Again, this is using the "seriesDefaults" option, which will apply |
|
options to all series in the plot. You could do the same on any |
|
particular series in the plot through the "series" options array. |
|
|
|
Plugins are free to add their own options. For example, the |
|
highlighter plugin has its own set of options that are unique to it. |
|
As a result, it responds to options placed in the "highlighter" |
|
attribute of your options object. So, if I wanted to change the |
|
highlighter tooltip to fade in and out slowly and be positioned |
|
directly above the point I'm highlighting: |
|
|
|
> optionsObj = { |
|
> highlighter:{tooltipFadeSpeed:'slow', tooltipLocation:'n'} |
|
> } |
|
|
|
Other plugins, like dragable and trendlines, add their options in with |
|
the series. (Yes, that's the correct name for the dragable plugin; it |
|
doesn't use the correct spelling of "draggable".) |
|
This is because both of those plugins can have different |
|
options for different series in the plot. So, if you wanted to specify the |
|
color for the dragable plugin and constrain it to drag only on the x axis as well |
|
as specify the color of the trend line you could do: |
|
|
|
> series:[{ |
|
> dragable: { |
|
> color: '#ff3366', |
|
> constrainTo: 'x' |
|
> }, |
|
> trendline: { |
|
> color: '#cccccc' |
|
> } |
|
> }] |
|
|
|
This would apply those options to the first series only. If you had 2 series |
|
and wanted to turn off dragging and trend lines on the second series, you could do: |
|
|
|
> series:[{ |
|
> dragable: { |
|
> color: '#ff3366', |
|
> constrainTo: 'x' |
|
> }, |
|
> trendline: { |
|
> color: '#cccccc' |
|
> } |
|
> }, { |
|
> isDragable: false, |
|
> trendline:{ |
|
> show: false |
|
> } |
|
> }] |
|
|
|
Note, series draggability is turned off with the "isDragable" option directly on |
|
the series itself, not with a suboption of "dragable". This may be improved |
|
in the future. |
|
|
|
I hope this is helpful. |
|
A few key points to remember: |
|
|
|
- When you see "this" in the api docs, you generally replace it with |
|
the name of the object (in lowercase) you are looking at in your |
|
options object. |
|
- seriesDefaults and axesDefaults are convenient shortcuts. |
|
- to assign options to a renderer, generally use the "rendererOptions" |
|
- plugins may add their own options attribute, like "highlighter" or |
|
"cursor". |
|
|
|
** Note: you can set attributes after the plot is created (like |
|
plot.grid.shadow = false), but you'll have to issue the appropriate |
|
calls to possibly reinitialize and redraw the plot. jqPlot can |
|
definitely handle this to change the plot after creation (this is how |
|
the dragable plugin updates the plot data and the trend line plugin |
|
recomputes itself when data changes). This hasn't been documented |
|
yet, however.
|
|
|