Anonymous committed 1fed537

Added options tutorial to documentation. Modifications for docs.

  • Participants
  • Parent commits 7688a54
  • Tags 0.7.0

Comments (0)

Files changed (4)

File NDdata/Menu.txt

 File: jqPlot  (no auto-title, jqplot.core.js)
 File: Usage  (no auto-title, usage.txt)
+File: Options Tutorial  (no auto-title, optionsTutorial.txt)
 File: Change Log  (changes.txt)
 Link: Unit Tests & Examples  (../../tests/)

File src/changes.txt

 Title: Change Log
 * Pie chart support
 * Enabled tooltipLocation option in highlighter. 
   around to first color at end.
 * Udates to docs about css file.
 * Fixed bug with String x values in series and IE error on sorting (Category Axis).
+* Added cursor changes in dragable plugin when cursor near dragable point.
 * Added excanvas.js and excanvas.min.js to compressed distributions.
 * Added example/test html pages I had locally into repository and to compressed distributions.
 * Removed absolute positioning from dom element and put back into css file.
 * Duplicate of 0.6.6 with a suffix to unambiguously differentiate between previously posted 0.6.6 release.
 * Fixed bug #5, trend line plugin failing when no trend line options specified.
 * Added absolute position css spec to axis tick dom element.
 * Enhancement to category axes, more intuitive handling of series with missing data values.
 * Fixed bug #4, series of unequal data length not rendering correctly.
   This is a bugfix release only.
 * Fixed bug (issue #1 in tracker) where flat line data series (all x and/or y values are euqal)
   or single value data series would crash.
 * Support for stacked line (a.k.a. area) and stacked bar (horizontal and vertical) charts.
 * Refactored barRenderer to use default shape and shadow renderers.
 * Added info (contacts & support information) page to web site.
 * This is a minor upgrade to docs and build only.  No functionality has changed.
 * Ant build script generates entire site, examples, tests and distribution.
 * Improvements to documentation.
 * New sprintf implementation from Ash Searle that implements %g.
 * Fix to sprintf e/f formats.
 * Updates to documentation.
 * Added license and copyright statement to source files.
 * Added rotated text support.  Uses native canvas text functionality in
 browsers that support it or draws text on canvas with Hershey font

File src/jqplot.core.js

  * See <jqPlot Usage>
+ * About: Options Usage
+ * 
+ * See <Options Tutorial>
+ * 
  * About: Changes
  * See <Change Log>

File src/optionsTutorial.txt

+Title: Options Tutorial
+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 posses,
+it doesn't explain how to use or set those attributes through 
+options.  This tutorial will help explain that.
+Lets 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
+>        |               |         |-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
+different, 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"}}
+> optionsObj = {title:"My Plot"}
+Where things need more explaination is with renderers, plugins and
+their options.  Briefly, what's  renderer, what's 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 will do more like 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, plugins, and specify their options?
+Some common renderes 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 it's 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'}
+> }
+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
+** 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.