[Summary view] [Print] [Text view]

   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.