Lately, I’ve been finding myself using raphael.js and g.raphael.js for all my charting and graphing needs. Having a very picky eye for design, I decided to pick g.raphael over other graphing libraries due to how flexible it is when it comes to customizing the look and feel of the data I’m displaying. While its parent project, raphael.js, ports some great documentation, g.raphael left me wanting. The examples on the g.raphael page are good and all, but they don’t expose other functions that are available for customizing each of the elements on a graph. This series of posts aims to demystify g.raphael and some of its plugins, but it’s by no means a complete guide. If you don’t feel like waiting around for me to post the documentation for the other plugins, I suggest you take a look at Kenny Shen’s g.raphael repo, which includes some initial documentation and forms the basis for this series. Feel free to ping me with suggestions and/or corrections to include in this guide.

The Overall Structure

g.raphael and its various graphing and charting plugins are split into separate files. The former includes some sensible defaults for the each of the plugins, along with the ability to render different symbols and tooltip forms, amongst others. Since this is the first article in the series, it’s appropriate to tackle g.raphael first.

Defaults

g.raphael.js defines some sensible defaults at the top of the plugin source code, including a default font and size, default hues, and some default markers and shortcuts.

Symbols

The symbols are showcased in the last example on the g.raphael page. Each symbol takes a center x and y value and a radius. The exceptions here are the flower and star symbols, which take in a fourth argument: the number of petals or rays, respectively.

…and the corresponding code to create them:

var r = Raphael('symbols', 600, 75)
  , set = r.set();

set.push(
  r.g.flower(0, 50, 20, 6),
  r.g.disc(50, 50, 20),
  r.g.line(100, 50, 20),
  r.g.square(150, 50, 20),
  r.g.triangle(200, 50, 20),
  r.g.diamond(250, 50, 20),
  r.g.star(300, 50, 20, 9),
  r.g.cross(350, 50, 20),
  r.g.plus(400, 50, 20),
  r.g.arrow(450, 50, 20)
).attr({ fill: '#000', stroke: 'none' })
 .translate(20,-20);

Tooltips

Tooltips are not as homogeneous in their intake of arguments as their symbols counterparts. The similarities stop after supplying x and y coordinates with a text parameter in most cases. Also note that drop and blob take the same arguments, but the angle and size arguments occur in a different order.

Here’s the code I used to create them, with additional options commented out:

r = Raphael('tooltips', 300, 110);
set.push(
  r.g.tag(0, 50, "$9.99", 130),
  r.g.popup(50, 50, "$9.99"),
  r.g.flag(100, 50, "$9.99", 60),
  r.g.label(0, 100, "$9.99"),
  r.g.drop(50, 100, "$10", 30, 70),
  r.g.blob(100, 100, "$9.99")
);

There are two other tooltip functions that you can use on Raphael sets: popupit and labelit. AFAIK, these functions are not called from other plugins. I played around with these, but could not find what they actually do :(

Other Functions

There are several other functions that g.raphaels makes available to you. The first is axis, which lets you add an axis to your graph. Internally, it uses snapEnds to calculate where to place interval markers on an axis. It takes in 10 arguments: x and y coordinates like all of the others elements discussed before; a length specifying how long/high you want the axis to span; the lowest and highest values you want the axis to span; the value to increment by on the axis; a value to specify the orientation of axis, that is, whether it should be vertical or horizontal; an array of labels to include at each step of the axis; and the last two I have no clue what they do.

Besides those, there are three more functions that let you operate on Raphael elements: lighter, darker, and original. The first two adjust the fill and stroke of an element based on the integer argument you pass in. The original function does what you expect—it restores the fill and stroke of an element to its original values.

Conclusion

In this introductory post, we looked at the defaults and functions that g.raphael.js offers. You can use these functions with other g.raphael.js plugins to customize the look and feel of your graphs and charts. We’ll take a look at the pie chart plugin in the next article, so stay tuned!