Updates + News:

05 May 2012 Added Api Docs

Unfortunately, this project is dead. I am unable to support it. If you're interested in taking over, please ping me. --Eric Webb Aug. 19, 2013

Using d34raphael

Quick Start

If you already know a little bit of d3, you're ready to try d34raphael.

  1. Include the necessary Javascript

    • sizzle.js - Sizzle Javascript CSS Selector Engine (IE Only)
    • ie8/compat.js - Compatibility functions for IE 8 (IE Only)
    • raphael.js - Patched Raphael for d34raphel
    • d3.v2.js - d3 build with Raphael extensions

  2. Write Raphael compatible d3 code

    • Create a Raphael d3 Selection

    • Manipulate the paper

      It looks like stock d3 except it renders with Raphael. See the API documentation for full information on the d34raphael selection implementation.

    • Replace d3.svg.axis() calls with d3.raphael.axis().

      d3.svg.XXX calls that draw something need to be replaced with their d34raphael equivalent.

Write Raphael Compatible d3 Code

When using d34raphael, you must remember you aren't drawing with SVG, you are drawing with Raphael.

Raphael exposes shapes and attribute names that are largely identical to SVG which is why d3/SVG and d3/Raphael code look so similar.

Look at the Raphael API documentation to see what Raphael can do, and what attributes are supported for manipulation by d34raphael.

Differences between a d3/SVG and d34raphael Page

Since Raphael is a subset of both SVG and VML, there are differences when using d34raphael and pure SVG.

Some specifics:

d34raphael selections are on Raphael.Elements, not native DOM elements

Raphael uses a wrapper class that contains the native DOM element for the corresponding graphical representation. These are the objects that are contained in d34raphael selections. So, when you do d3_paper.selectAll("rect").each(function(d, i) {}, the this in the callback function is a Raphael.Element instance, not a DOM object.

You can get the native DOM object from a Raphael.Element by calling element.node, but remember that the element.node class will be different for SVG than VML.

Raphael doesn't have an SVG g equivalent

You can use Raphael's paper.setStart()/paper.setFinish().transform(["t", x, y]) to transform sets of Raphael elements created between the two calls.

You will see this method used in many of the examples.

Raphael elements aren't nested like SVG

Unlike SVG, all Raphael elements are peers in the context of the Raphael.Paper. So, you cannot have Raphael elements that are a child of another Raphael element.

Because of this, all d34raphael selections select on ALL elements in the Raphael.Paper, and are not limited to the scope of the elements in the existing selection.

For example, in stock d3:

When calling selectAll on an existing selection, the results are limited to those found as children of elements in the existing selection. Most likely, the result would be empty.

While, in d34raphael:

would give us the same set of rect instances, because the search scope hasn't changed between calls to selectAll, no mater how many times it is called.

CSS selectors are flat in d34raphael because the Raphael elements are flat hierarchically

Because (as discussed), all elements in Raphael are a direct child of the containing Raphael container, you never have a Raphael.Element that is the child of another element. So while you might see a CSS selector like g circle.point in an SVG version of a page, in a d34raphael version, it would likely be just circle.point as the circle could never be a child of g.

Annotated d34raphael Example

Below is an annotated d34raphael example that highlights most of the features of the d34raphael extensions to d3.

For more examples of d34raphael in use, see the examples page.