Skip to content
February 21, 2011 / J A Burrows

Documentation for gRaphael: g.line.js

Update: I found another library that is superior to gRaphael. It’s called Ico by Alex Young. You can find it here: http://alexyoung.github.com/ico/. It doesn’t support all of the graph types, but the options more thorough.

gRaphael provides an easy way of creating charts through JavaScript. Unfortunately, many people have complained about how poorly it is documented. In the interest of seeing more good looking charts on websites, I decided to go through the code and post documentation here. This first post is on the line chart library, but I will be posting more on the rest of the library in the future.

To start using the line chart, we need to include the Raphael and the line chart library:


<script src="/script/raphael.js" type="text/javascript" charset="utf-8"></script>
<script src="/script/g.raphael.js" type="text/javascript" charset="utf-8"></script>
<script src="/script/g.line.js" type="text/javascript" charset="utf-8"></script>

Then initialize the chart by passing in the options to the constructor:


var r = Raphael("element");
r.g.linechart(x_offset, y_offset, width, height, x_values_array, y_values_array, options);

x_values_array is either an array of x values, or an array of multiple arrays of x values.
y_values_array is the same as above, but for the y-axis.
If only one array of x values is specified, multiple y value arrays will share these values. If both are specified, each plot will be completely independent of each other.

options is an object with the following possible elements:

var options = {
  gutter: 10,
  symbol: "",
  colors: Raphael.fn.g.colors,
  nostroke: false,
  smooth: false;
  shade: false,
  dash: "",
  axis: "",
  axisxstep: 1,
  axisystep: 1
};

options.gutter is the default spacing between the edge of the chart area and the graph itself.

options.symbol is either a single symbol or an array of multiple symbols for each line. Just leaving it as a blank (“”) means that it will be a line graph without any decoration at the points. The list of allowable options is:

"" - no symbol
"o" - "disc"
"f" - "flower"
"d" - "diamond"
"s" - "square"
"t" - "triangle"
"*" - "star"
"x" - "cross"
"+" - "plus"
"->"; - "arrow"

options.colors must be an array, even if there is only one line.

options.nostroke controls the line drawing. Set to false (default), it will draw the line. If this is set to true and a symbol is chosen, a scatter type plot can be made.

options.smooth turns on smoothing. No jagged angles will be seen, just smooth curves.

options.shade controls shading the area below the line. No shading happens by default. Set this to true to create an area chart.

options.dash sets the ‘stroke-dasharray’ property on the line element. According to the SVG spec:

‘stroke-dasharray’ controls the pattern of dashes and gaps used to stroke paths. Contains a list of comma and/or white space separated integers that specify the lengths of alternating dashes and gaps. If an odd number of values is provided, then the list of values is repeated to yield an even number of values. Thus, stroke-dasharray: 5,3,2 is equivalent to stroke-dasharray: 5,3,2,5,3,2.

options.axis is a comma or space separated list of axes to show. Seems like it follows the order of css lists: top, right, bottom, left.

option.axisxstep determines how far apart the ticks and axis numbers are placed.

option.axisystep is the same as above, but for the y-axis.

Unfortunately, this is as far as the axis customization goes. I’ve been looking at the parent object and it looks like it wouldn’t be hard to customize the axes further. I’ll post more on this as I figure it out. If anyone wants to look at the g.axis() function and figure out how to add labels and customize the labels on the axis, please let me know what you find.

r.g.linechart() returns a chart object:

chart = {lines, shades, symbols, axis, columns, dots};

That chart object has the following default functions. All of these are overridable.

chart.hoverColumn = function (fin, fout) {
  !columns && createColumns();
  columns.mouseover(fin).mouseout(fout);
  return this;
};

chart.clickColumn = function (f) {
  !columns && createColumns();
  columns.click(f);
  return this;
};

chart.hrefColumn = function (cols) {
  var hrefs = that.raphael.is(arguments[0], "array") ? arguments[0] : arguments;
  if (!(arguments.length - 1) && typeof cols == "object") {
    for (var x in cols) {
      for (var i = 0, ii = columns.length; i < ii; i++) if (columns[i].axis == x) {
        columns[i].attr("href", cols[x]);
      }
    }
  }
  !columns && createColumns();
  for (i = 0, ii = hrefs.length; i < ii; i++) {
    columns[i] && columns[i].attr("href", hrefs[i]);
  }
  return this;
};

chart.hover = function (fin, fout) {
  !dots && createDots();
  dots.mouseover(fin).mouseout(fout);
  return this;
};

chart.click = function (f) {
  !dots && createDots();
  dots.click(f);
  return this;
};

chart.each = function (f) {
  createDots(f);
  return this;
};

chart.eachColumn = function (f) {
  createColumns(f);
  return this;
};
About these ads

15 Comments

Leave a Comment
  1. brennannovak / Feb 21 2011 11:27 am

    Sounds interesting Jillian. Do you have any demos online of how it looks? :)

  2. craig / Apr 8 2011 3:09 am

    thanks for posting this, documentation is definitely needed.

  3. Manu / May 20 2011 12:32 pm

    Tks for posting this documentation. :)

  4. Jeremy / May 20 2011 3:27 pm

    Thanks a lot. I like Raphael, but yes, the documentation is horrible… actually, non-existent might be a better word.

    Ico is an extension of Raphael and certainly appears easier to use. Thanks for surfacing this option as well as in-depth info the line chart configuration!

  5. jeffatstepup / Jun 15 2011 11:33 am

    Thanks a lot for writing this documentation, but thanks even more for the tip on Ico – looks exactly what I was after.

    Good karma coming your way.

  6. Erik van Gameren / Nov 1 2011 2:18 am

    This is great! Please more documentation about the other charts!

  7. Alf / Jan 19 2012 11:00 am

    How to change labels for the x axis, at the bottom of this page:

    http://www.exratione.com/2011/10/a-few-tips-for-graphael-line-charts.php

    • Jill Burrows / Mar 28 2012 10:39 am

      Hey thanks! That’s interesting, but there is still no way to pass an array of axis values in. It still automatically computes the labels — even if it is using dates.

  8. rhite / Feb 14 2012 1:13 pm

    Hey, Thanks for posting this, even just knowing the argument names has really helped me get along.

    For such a great library it’s a shame it’s so poorly documented.

  9. Alan s / Mar 12 2012 5:54 am

    Thanks for this much-needed post!

    btw, is Alex Young’s ico an extension of Raphael as stated above? It doesn’t seem to work with IE8, and the fact that Raphael and gRaphael work with IE6-8 is their main selling point for me.

    • Jill Burrows / Mar 28 2012 10:36 am

      ICO uses Raphaël to draw. It was originally written with the first version of Raphaël. Raphaël was completely rewritten in version 2.0. ICO was tested (not sure of how thoroughly) with Raphaël 2.0 to make sure it still works. If you’re experiencing problems, send Alex Young a bug request at the Github page linked to above.

  10. Chrishas / Apr 9 2012 3:42 pm

    Thanks for the documentation, but I can’t get the symbol option to work. The only thing that works is if use circle, I’ve tried using an array and a blank value but I get this:
    paper[Raphael.is(sym, “array”) ? sym[j] : sym] is not a function @ js/g.line.js:154

    The updating of gRaphael seems to be really slow, I’ve come across another bug with createColumns() which has already been reported and a fix is available, but it hasn’t been applied in the version distributed yet.:/.

  11. RaphAlytics / Jul 1 2012 5:54 am

    If you are looking for a nice way of implementing line charts using Raphael that gives you quite a few options to customize you should also check out RaphAlytics on GitHub => https://github.com/tataencu/raphalytics and post any feedback you might have!

  12. bubuzzz / Jul 6 2012 8:31 pm

    Hi Jill,
    Do you know how to add onclick event to the hover tag of the linechart ? I tried the suggestion at http://stackoverflow.com/questions/9096461/adding-padding-to-graphael-charts but it still does not work :(

  13. I know this if off topic but I’m looking into starting my own weblog and was curious what all is required to get setup? I’m assuming having a
    blog like yours would cost a pretty penny? I’m not very web savvy so I’m not 100% positive. Any recommendations or advice would be greatly appreciated. Many thanks Check out my website to get more info about forex, if you like.

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 2,119 other followers

%d bloggers like this: