public/javascripts/jqplot/optionsTutorial.txt

   1 Title: Options Tutorial
   2
   3 This document will help you understand how jqPlot's options
   4 relate to the API documentation and the jqPlot object
   5 itself.  For a listing of options available to jqPlot,
   6 see <jqPlot Options> in the jqPlotOptions.txt file.
   7
   8 The key to effectively using jqPlot is understanding jqPlot's
   9 options.  The online documentation is API documentation.  While
  10 it explains what attributes and methods various objects posses,
  11 it doesn't explain how to use or set those attributes through
  12 options.  This tutorial will help explain that.
  13
  14 Lets assume you are creating a plot
  15 like this:
  16
  17 > chart = $.jqplot('chart', dataSeries, optionsObj);
  18
  19 First, note that you shouldn't try to directly set attributes on the
  20 "chart" object (like chart.grid.shadow) after your call to $.jqplot().
  21 At best this won't do anything **(see below). You should pass options in via
  22 the "optionsObj".
  23
  24 the optionsObj really represents the plot object (jqPlot object, not
  25 to be confused with the $.jqplot function which will create a jqPlot
  26 object).  Attributes you specify on that object will be merged with
  27 attributes in the jqPlot object.  The axes, legend, series, etc. are
  28 attributes on the jqPlot object.  The jqPlot/optionsObj object looks
  29 something like (only some attributes shown):
  30
  31 > jqPlot-|
  32 >        |-seriesColors
  33 >        |-textColor
  34 >        |-fontFamily
  35 >        |-fontSize
  36 >        |-stackSeries
  37 >        |-series(Array)-|
  38 >        |               |-Series1-|
  39 >        |               |         |-lineWidth
  40 >        |               |         |-linePattern
  41 >        |               |         |-shadow
  42 >        |               |         |-showLine
  43 >        |               |         |-showMarker
  44 >        |               |         |-color
  45 >        |               |-Series2...
  46 >        |               |-...
  47 >        |               |-SeriesN
  48 >        |
  49 >        |-grid(Object)-|
  50 >        |              |-drawGridLines
  51 >        |              |-background
  52 >        |              |-borderColor
  53 >        |              |-borderWidth
  54 >        |              |-shadow
  55 >        |
  56 >        |-title(Object)-|
  57 >        |               |-text
  58 >        |               |-show
  59 >        |               |-fontFamily
  60 >        |               |-fontSize
  61 >        |               |-textAlign
  62 >        |               |-textColor
  63 >        |
  64 >        |-axes(Object)-|
  65 >        |              |-xais-|
  66 >        |              |      |-min
  67 >        |              |      |-max
  68 >        |              |      |-numberTicks
  69 >        |              |      |-showTicks
  70 >        |              |      |-showTickMarks
  71 >        |              |      |-pad
  72 >        |
  73 >        | ... and so on
  74
  75 The optionsObj should follow the same construction as if it were a
  76 jqPlot object (with some exceptions/shortcuts I'll mention in a
  77 moment).  So generally, when you see something like
  78 "this.drawGridLines" in the grid properties in the docs, just replace
  79 "this" with "grid" in your options object.  So it becomes
  80 optionsObj.grid.drawGridLines.  Do likewise with the other objects in
  81 the plot, replacing "this", with the respective attribute on the plot
  82 like "legend" or "title".  Series and Axes are handled a little
  83 different, because series is an array and axes has 4 distinct children
  84 "xaxis", "yaxis", "x2axis" and "y2axis".
  85
  86 So, to remove the shadow from the grid and change the grid border size
  87 you would do:
  88
  89 > optionObj = {grid:{shadow:false, borderWidth:9.0}};
  90
  91 To do the same as above but also make all the text in the plot red you
  92 would do:
  93
  94 > optionObj = {
  95 >    textColor:"#ff0000",
  96 >    grid:{shadow:false, borderWidth:9.0}
  97 > }
  98
  99 Here is a more deeply nested example. Say you want to specify a min
 100 and max on your y axis and use a specific color for your second
 101 series.  That would look like:
 102
 103 > optionsObj = {
 104 >    axes:{yaxis:{min:5, max:230}},
 105 >    series:[{},{color:"#33ff66"}]
 106 > }
 107
 108 Note that series options are an array in order of the series data you
 109 sent in to your plot.  To get to the second series, you have to put an
 110 object (even if empty) in place of the first series.
 111
 112 There is a handy shortcut to assign options to all axes or all series
 113 at one go.  Use axesDefaults and seriesDefaults.  So, if you wanted
 114 both x and y axes to start at 0 and you wanted all series to not show
 115 markers, you could do:
 116
 117 > optionsObj = {axesDefaults:{min:0}, seriesDefaults:{showMarker:false}}
 118
 119 Another shortcut is for the plot title.  Normally, you would assign
 120 options to the title as an object.  If you specify a title option as a
 121 string, it will assign that to the title.text property automatically.
 122 So these two are equivalent:
 123
 124 > optionsObj = {title:{text:"My Plot"}}
 125
 126 and
 127
 128 > optionsObj = {title:"My Plot"}
 129
 130 Where things need more explaination is with renderers, plugins and
 131 their options.  Briefly, what's  renderer, what's a plugin.
 132
 133 A renderer is an object that is used to draw something and gets
 134 attached to an existing object in the plot in order to draw it.  A
 135 plugin does more than just provide drawing functionality to an
 136 object.  It will do more like calculate a trend line, change the
 137 cursor, provide event driven functionality, etc.  I consider renderers
 138 plugins, but plugins don't have to be renderers.
 139
 140 So, how do you use renderers, plugins, and specify their options?
 141 Some common renderes are for bar charts and category axes.  If you
 142 want to render your series as a bar chart with each set of bars
 143 showing up in a category on the x axis, you do:
 144
 145 > optionsObj = {
 146 >    seriesDefaults:{renderer:$.jqplot.BarRenderer},
 147 >    axes:{xaxis:{renderer:$.jqplot.CategoryAxisRenderer}}
 148 > }
 149
 150 This replaces the default renderer used for all series in the plot
 151 with a bar renderer and the x axis default renderer (but not any other
 152 axis) with a category renderer.
 153
 154 Now, how would I assign options to those renderers?  The renderer's
 155 attributes may not be present in the pre-existing jqPlot object, they
 156 may be specific to the renderer.  This is done through the
 157 "rendererOptions" option on the appropriate object. So, if I wanted my
 158 bars to be 25 pixels wide, I would do:
 159
 160
 161 > optionsObj = {
 162 >    seriesDefaults:{
 163 >        renderer:$.jqplot.BarRenderer},
 164 >        rendererOptions:{
 165 >            barWidth:25
 166 >        },
 167 >    axes:{xaxis:{renderer:$.jqplot.CategoryAxisRenderer}}
 168 > }
 169
 170 Again, this is using the "seriesDefaults" option, which will apply
 171 options to all series in the plot.  You could do the same on any
 172 particular series in the plot through the "series" options array.
 173
 174 Plugins are free to add their own options.  For example, the
 175 highlighter plugin has it's own set of options that are unique to it.
 176 As a result, it responds to options placed in the "highlighter"
 177 attribute of your options object.  So, if I wanted to change the
 178 highlighter tooltip to fade in and out slowly and be positioned
 179 directly above the point I'm highlighting:
 180
 181 > optionsObj = {
 182 >     highlighter:{tooltipFadeSpeed:'slow', tooltipLocation:'n'}
 183 > }
 184
 185 Other plugins, like dragable and trendlines, add their options in with
 186 the series.  This is because both of those plugins can have different
 187 options for different series in the plot.  So, if you wanted to specify the
 188 color of the dragable and constrain it to drag only on the x axis as well
 189 as specify the color of the trend line you could do:
 190
 191 > series:[{
 192 >     dragable: {
 193 >         color: '#ff3366',
 194 >         constrainTo: 'x'
 195 >     },
 196 >     trendline: {
 197 >         color: '#cccccc'
 198 >     }
 199 > }]
 200
 201 This would apply those options to the first series only.  If you had 2 series
 202 and wanted to turn off dragging and trend lines on the second series, you could do:
 203
 204 > series:[{
 205 >     dragable: {
 206 >         color: '#ff3366',
 207 >         constrainTo: 'x'
 208 >     },
 209 >     trendline: {
 210 >         color: '#cccccc'
 211 >     }
 212 > }, {
 213 >    isDragable: false,
 214 >    trendline:{
 215 >        show: false
 216 >    }
 217 > }]
 218
 219 Note, series dragability is turned off with the "isDragable" option directly on
 220 the series itself, not with a suboption of "dragable".  This may be improved
 221 in the future.
 222
 223 I hope this is helpful.
 224 A few key points to remember:
 225
 226 - When you see "this" in the api docs, you generally replace it with
 227 the name of the object (in lowercase) you are looking at in your
 228 options object.
 229 - seriesDefaults and axesDefaults are convenient shortcuts.
 230 - to assign options to a renderer, generally use the "rendererOptions"
 231 - plugins may add their own options attribute, like "highlighter" or
 232 "cursor".
 233
 234 ** Note:  you can set attributes after the plot is created (like
 235 plot.grid.shadow = false), but you'll have to issue the appropriate
 236 calls to possibly reinitialize and redraw the plot.  jqPlot can
 237 definitely handle this to change the plot after creation (this is how
 238 the dragable plugin updates the plot data and the trend line plugin
 239 recomputes itself when data changes).  This hasn't been documented
 240 yet, however.