jqPlot deep customization examples

[a0]

Could you please post some examples of JS code how to customize jqPlot
deeply? I am especially interested in how to:
1. Remove shadow from the whole grid container
2. Change grid border size
3. Remove shadow from ticks

But the properties in the manual don't give me much clue, they are
references through this. and I tried something like plot.grid.shadow
etc. but I think I'm not approaching it right. Thanks!

[Chris Leonello]

I'm glad you asked. The docs are pretty weak from a usage stand
point. They are more api documentation and not really usage
documentation.

Here is a brief options tutorial to get you started. I'll add
something more in depth to the wiki.

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. You should pass options in via
the "optionsObj"**(see below).

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}};

borderWidth must be a number and represents the pixel width of the
border.

Note, there are no shadows on the ticks or the tick marks themselves.
It may appear so because the grid has a shadow.

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 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}}
}

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 and to be empty (not filled), I would do:


optionsObj = {
seriesDefaults:{
renderer:$.jqplot.BarRenderer},
rendererOptions:{
barWidth:25,
fill:false
},
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
"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
anywhere, however.

[a0]

Awesome description Chris! That clears out almost everything! Thanks
very much!

Two detailed question though:

1. I have declared to show the highlight tooltip on top, like below,
but it doesn't seem to work, tooltip appears at 'nw':
highlighter: {
tooltipLocation:'n'
},

2. Is it possible to display only one axis value in the tooltip, for
example just the Y value of the point?

[Chris Leonello]

I picked really bad example :-0

tooltipLocation isn't actually implemented yet for highlighter.

There currently isn't a way to display just x or y axis value in the
tooltip. I can add that, should be easy.

[Chris Leonello]

I've added these features into trunk. I'm not planning on building
another distribution until I've finished pie charts, only exception
being for more bug fixes. Pie charts shouldn't be far away, though
(maybe a couple of days).

--
Chris Leonello

[a0]

Awesome! I'll be waiting for the next version! In the meantime, you
might also wanna consider adding something like a
categoryDateRenderer, or some solution to remove the first and last
tick. Here is why:

Look at the screen: http://img99.imageshack.us/img99/3582/jqplotting.png
I want to have the plot line dots exactly on the vertical lines of the
ticks, thus I had to declare a min value less than 1 unit measure. But
this produces a tick at 0 value, and there's also a tick at the end -
they are obsolete to me, and I'd love to be able to remove them, if
you know what I mean. Thanks and cheers!

[Chris Leonello]

Yes, I see the usefulness of your CategoryDateAxis.  I'll have to think about how best to implement that.

The way I currently approach this it to use either a date axis or a category axis but specify my ticks array so things line up exactly:

With a date axis:

line1 = [['1/1/2006', 5], ['2/1/2006', 1], ['3/1/2006', 3], ['4/1/2006', 7]];
line2 = [['1/1/2006', 2], ['2/1/2006', 6], ['3/1/2006', 4], ['4/1/2006', 3]];

plot1 = $.jqplot('chart', [line1, line2], {
 legend: {show:true, location: 'nw'},
 axes:{
   xaxis:{
     renderer:$.jqplot.DateAxisRenderer,
     tickOptions:{
       formatString:'%m.%y'},
       ticks:['12/1/2005', '1/1/2006', '2/1/2006', '3/1/2006', '4/1/2006', '5/1/2006']
   }
 }
});

or, probably more straight forward but giving a different look, with a category axis:

line1 = [5, 1, 3, 7];
line2 = [2, 6, 4, 3];

plot2 = $.jqplot('chart2', [line1, line2], {
 legend: {show:true, location: 'nw'},
 axes:{
   xaxis:{
     renderer:$.jqplot.CategoryAxisRenderer,
     ticks:['01.06', '02.06', '03.06', '04.06']
   }
 }
});

I'm having some trouble attaching the images of what these look like.  I'll try that separately later.

--

----
Chris Leonello

[Chris Leonello]

I've given this some thought and know how I will implment. It only
requires that I enable category axes to handle Strings as well as
Number data and be able to tell the two apart. You will then be able
to use a category axis out of the box and override the default tick
formatter with a $.jqplot.DateTickFormatter to get what you want.

This plays on the strength of jqPlots pluggability. By default,
linear and category axis renderers use a sprintf style formatter.
But, it is a plugin, so you can swap it out with a date formatter.

You could swap tick formatters right now if you wanted. You would
need to include the jqplot.dateAxisRenderer.js file (that file
contains the date formatter, I'll move it into core). Then, specify
your axis as a category axis, but set options to override the default
tick formatter like so:

plot2 = $.jqplot('chart2', [line1, line2], {
legend: {show:true, location: 'nw'},
axes:{
xaxis:{
renderer:$.jqplot.CategoryAxisRenderer,

ticks:['2006-01-01', '2006-02-01', '2006-03-01', '2006-04-01'],
tickOptions:{
formatter:$.jqplot.DateTickFormatter,
formatSring:'%m.%y'
}
}
}
});

Note, you currently still need to specify your x axis values in a tick
array, since category axes currently only handle Numbers *if* you pass
in x values with the data. When you pass in a tick array, you can use
numbers or strings.

--

----
Chris Leonello

[a0]

Using your great tutorial here (thanks again!), I managed to customize everything the way I wanted, even with a watermark ;) http://img5.imageshack.us/img5/687/jqplotpro.png Now, maybe you would be able to implement more specific highlighter formatting control? Now, I can override axis formatting, but I can control the numbers separately - it would be great if I could control the whole highlighter string, so for example I could just display the x or y value, or even add html to do some more fancy stuff, what do you think, is it possible?

2009/6/11 Chris Leonello <chris.l...@gmail.com>

[Chris Leonello]

Not sure I know what you mean.  You can completely customize the format string.  For example, here is a tooltip that prefixes the value with the word hello in bold italic red font:

You can do this with options like:

highlighter: {

    tooltipLocation: 'n',

    tooltipAxes: 'y',

    tooltipFormatString: '<b><i><span style="color:red;">hello</span></i></b> %.2f',

    useAxesFormatters: false

},

The one piece that is missing is to be able to separately format the x and y axis tooltips.  I can add that also.  Right now the format string applies to both axes in the tooltip.

--

Chris Leonello

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "jqplot-users" group.
To post to this group, send email to jqplot...@googlegroups.com
To unsubscribe from this group, send email to jqplot-users...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/jqplot-users?hl=en
-~----------~----~----~----~------~----~------~--~---

[Chris Leonello]

Sorry, I meant to include an image in the last post:

http://img99.imageshack.us/img99/7719/screenshot04b.png

a0, Is that what you are looking for? If you can customize both x and y
format strings would that do the trick?

--
Chris Leonello

--
Chris

[a0]

Yes, i your example and screenshot I can see you implemented
displaying just one axis value in the tooltip - that will work for me,
no need to separately format x and y, as I would display just one
value. But this is not yet in the online jqPlot package is it?

One thing worth implementing is manual overriding of the tooltip ticks
- like with the axis. Say I'm using a CategoryAxisRenderer, and I
override my x ticks with date strings - now, the tooltip will still
show the numerical, meaningless value of the x axis. It would be great
if I could pass the same array to the highlighter as I did with xaxis,
so it would display it. Something like:

xaxis: {
renderer: $.jqplot.CategoryAxisRenderer,
ticks: ['23-May-08','24-May-08','25-May-08','26-
May-08'],
...
highlighter: {
useAxisTicks: true,
tooltipLocation: 'n'

what do you think?

[Chris Leonello]

I think I understand. Your data may look like:

[[12304958, 4.55], [12309877, 5.66], ...]

and your axis ticks are specified like:

['May 1, 2009', 'June 1, 2009', ...]

and when you mouse over the first data point, your tooltip shows
"12304958" or maybe just shows "1" (because it is the first category)
but you want it to show "May 1, 2009", right?

That is a good idea. I'll think about how to implement.

--

----
Chris Leonello

[a0]

Yes, almost exactly. I would like it to show the data in the tooltip,
but if there are custom ticks declared, the tooltip would show that,
so, if my data is:

[[12304958, 4.55], [12309877, 5.66], ...]

and X axis ticks are:

['May 1, 2009', 'June 1, 2009', ...]

my tooltip would show "May 1, 2009, 4.55"

(btw it would be perfect if i also could change the semicolon to
something else, ie. "May 1, 2009 <br /> 4.55")

[Chris Leonello]

> my tooltip would show "May 1, 2009, 4.55"
>
> (btw it would be perfect if i also could change the semicolon to
> something else, ie. "May 1, 2009 <br /> 4.55")

You mean the comma not the semicolon, right? I'll think about how to
best implement.

--

----
Chris Leonello

[a0]

Yes yes, my mistake - the comma :P Thanks!

[Chris Leonello]

I've added a tooltipSeparator option to control this. Please let me
know if you have any issues.
--
Chris Leonello

[Chris Leonello]

> I've added a tooltipSeparator option to control this.

And it is available in 0.7.0, which you can download now :-)

--
Chris

[jatin maini]

Hi Chris,

let me introduce myself. I am a UI developer from India, and have been using this awesome library from past 6 months or so. 

Let me describe the scenario I am stuck at and I really hope I would get some quality advice from you regarding the same. 

scenario:

I have to plot an area graph which is to be sampled on a weekly basis for all the 12 months of the year. The x-axis however should aggregate the 4 weeks of the month into one data point and should show the corresponding month instead of individual weeks 

So the y axis will have data points corresponding to weeks but the x axis will show months much like below:

x-axis : jan feb mar april may june july aug sep oct nov dec

y-asix : co-ordinates corresponding to the 4 weeks of each month.

Is this grouping of x-axis ticks possible? IF so, kindly help me out figuring the same.

Again, let me express my gratitude for providing such a fantastic library.Thanks

[Biplab De]

Hi,

I am trying to implement JQ plot in my android app(native). how is it possible to do?. If any one know please let me know.