Free cookie consent management tool by TermsFeed Policy Generator

source: branches/HiveStatistics/sources/HeuristicLab.Services.Hive.Statistics/3.3/Scripts/jqPlot/optionsTutorial.txt @ 9617

Last change on this file since 9617 was 9617, checked in by pfleck, 11 years ago

#2063:
Started integrating Hive statistics into statistics web project.
Added jqPlot library for charting.

File size: 8.6 KB
Line 
1Title: Options Tutorial
2
3This document will help you understand how jqPlot's options
4relate to the API documentation and the jqPlot object
5itself.  For a listing of options available to jqPlot,
6see <jqPlot Options> in the jqPlotOptions.txt file.
7
8The key to effectively using jqPlot is understanding jqPlot's
9options.  The online documentation is API documentation.  While
10it explains what attributes and methods various objects posses,
11it doesn't explain how to use or set those attributes through
12options.  This tutorial will help explain that.
13
14Lets assume you are creating a plot
15like this:
16
17> chart = $.jqplot('chart', dataSeries, optionsObj);
18
19First, note that you shouldn't try to directly set attributes on the
20"chart" object (like chart.grid.shadow) after your call to $.jqplot(). 
21At best this won't do anything **(see below). You should pass options in via
22the "optionsObj".
23
24the optionsObj really represents the plot object (jqPlot object, not
25to be confused with the $.jqplot function which will create a jqPlot
26object).  Attributes you specify on that object will be merged with
27attributes in the jqPlot object.  The axes, legend, series, etc. are
28attributes on the jqPlot object.  The jqPlot/optionsObj object looks
29something 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 
75The optionsObj should follow the same construction as if it were a
76jqPlot object (with some exceptions/shortcuts I'll mention in a
77moment).  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
80optionsObj.grid.drawGridLines.  Do likewise with the other objects in
81the plot, replacing "this", with the respective attribute on the plot
82like "legend" or "title".  Series and Axes are handled a little
83different, because series is an array and axes has 4 distinct children
84"xaxis", "yaxis", "x2axis" and "y2axis".
85
86So, to remove the shadow from the grid and change the grid border size
87you would do:
88
89> optionObj = {grid:{shadow:false, borderWidth:9.0}};
90
91To do the same as above but also make all the text in the plot red you
92would do:
93
94> optionObj = {
95>    textColor:"#ff0000",
96>    grid:{shadow:false, borderWidth:9.0}
97> }
98
99Here is a more deeply nested example. Say you want to specify a min
100and max on your y axis and use a specific color for your second
101series.  That would look like:
102
103> optionsObj = {
104>    axes:{yaxis:{min:5, max:230}},
105>    series:[{},{color:"#33ff66"}]
106> }
107
108Note that series options are an array in order of the series data you
109sent in to your plot.  To get to the second series, you have to put an
110object (even if empty) in place of the first series.
111
112There is a handy shortcut to assign options to all axes or all series
113at one go.  Use axesDefaults and seriesDefaults.  So, if you wanted
114both x and y axes to start at 0 and you wanted all series to not show
115markers, you could do:
116
117> optionsObj = {axesDefaults:{min:0}, seriesDefaults:{showMarker:false}}
118
119Another shortcut is for the plot title.  Normally, you would assign
120options to the title as an object.  If you specify a title option as a
121string, it will assign that to the title.text property automatically.
122So these two are equivalent:
123
124> optionsObj = {title:{text:"My Plot"}}
125
126and
127
128> optionsObj = {title:"My Plot"}
129
130Where things need more explaination is with renderers, plugins and
131their options.  Briefly, what's  renderer, what's a plugin.
132
133A renderer is an object that is used to draw something and gets
134attached to an existing object in the plot in order to draw it.  A
135plugin does more than just provide drawing functionality to an
136object.  It will do more like calculate a trend line, change the
137cursor, provide event driven functionality, etc.  I consider renderers
138plugins, but plugins don't have to be renderers.
139
140So, how do you use renderers, plugins, and specify their options?
141Some common renderes are for bar charts and category axes.  If you
142want to render your series as a bar chart with each set of bars
143showing 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
150This replaces the default renderer used for all series in the plot
151with a bar renderer and the x axis default renderer (but not any other
152axis) with a category renderer.
153
154Now, how would I assign options to those renderers?  The renderer's
155attributes may not be present in the pre-existing jqPlot object, they
156may be specific to the renderer.  This is done through the
157"rendererOptions" option on the appropriate object. So, if I wanted my
158bars 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
170Again, this is using the "seriesDefaults" option, which will apply
171options to all series in the plot.  You could do the same on any
172particular series in the plot through the "series" options array.
173
174Plugins are free to add their own options.  For example, the
175highlighter plugin has it's own set of options that are unique to it.
176As a result, it responds to options placed in the "highlighter"
177attribute of your options object.  So, if I wanted to change the
178highlighter tooltip to fade in and out slowly and be positioned
179directly above the point I'm highlighting:
180
181> optionsObj = {
182>     highlighter:{tooltipFadeSpeed:'slow', tooltipLocation:'n'}
183> }
184
185Other plugins, like dragable and trendlines, add their options in with
186the series.  This is because both of those plugins can have different
187options for different series in the plot.  So, if you wanted to specify the
188color of the dragable and constrain it to drag only on the x axis as well
189as 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
201This would apply those options to the first series only.  If you had 2 series
202and 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
219Note, series dragability is turned off with the "isDragable" option directly on
220the series itself, not with a suboption of "dragable".  This may be improved
221in the future.
222
223I hope this is helpful.
224A few key points to remember:
225
226- When you see "this" in the api docs, you generally replace it with
227the name of the object (in lowercase) you are looking at in your
228options 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
235plot.grid.shadow = false), but you'll have to issue the appropriate
236calls to possibly reinitialize and redraw the plot.  jqPlot can
237definitely handle this to change the plot after creation (this is how
238the dragable plugin updates the plot data and the trend line plugin
239recomputes itself when data changes).  This hasn't been documented
240yet, however.
Note: See TracBrowser for help on using the repository browser.