raphael.js - custom attributes

Question

Is it possible to define a custom attribute for a raphael element?

e.g.

r.circle(25,50,10).attr({fill:'#b71e16', stroke:'#71140f', 'my_custom_attribute':'a value'});

Reason I need this is I want to do some quite complex animation on a whole set of elements and I want somewhere to store the original y coordinate for each one.

Answer 1

Is the custom attribute you want:

1. A simple store for arbitrary data, to be recorded and retrieved?
2. An attribute where a custom action needs to be taken when it is changed (like the attributes controlled with Raphael's .attr() and .animate() )?
3. Something you want to force into the attributes of the output SVG / VML markup on the page / DOM? (not normally recommended, but sometimes needed)

1. Custom data storage and retrieval

I'm 99% sure that the official, intended way to store arbitrary data in Raphael is to use the .data() function, e.g.

var circle = r.circle(25,50,10).attr({fill:'#b71e16', stroke:'#71140f'});
// set it
circle.data('custom-attribute', 'value');

// get it
data = circle.data('custom-attribute');
alert(data);

Note that as of Raphael 2.1 this works for elements, not sets. When I need to assign data to a set I tend to set it with a for loop and get it with someSet[0].data() - a bit of a cludge, but it works.

Annoyingly the documentation for .data doesn't say anything at all about what it is for (at time of writing)... but .data() in jQuery, data-* in HTML5, etc etc all have this purpose, using it like this works, and others on SO talk about it being intended to be used it like this, so I'm pretty confident that this is the intended method for attaching arbitrary data to Raphael objects.

---

2. Custom functions triggered by attr() or animate()

If you need a custom attribute that behaves like Raphael attributes - triggering a function or transformation when changed using attr or animate (kind of like a Raphael hook) - that's what paper.customAttributes is for. It defines a function that is executed any time the named custom attr is set for any element in that paper object. The return object is applied to the element's standard attributes.

The offical docs have some pretty useful examples for this one, here's an adapted one:

// A custom attribute with multiple parameters:
paper.customAttributes.hsb = function (h, s, b) {
    return {fill: "hsb(" + [h, s, b].join(",") + ")"};
};
var c = paper.circle(10, 10, 10);
// If you want to animate a custom attribute, always set it first - null isNaN
c.attr({hsb: "0.5 .8 1"});
c.animate({hsb: [1, 0, 0.5]}, 1e3);

Note that this within each customAttribute execution is the Raphael object for which the attr is being set. This means...

---

3. Forcing custom attribute into the SVG or VML markup in the browser

Raphael doesn't really support this, so only do this if you really, really need to. But if you really do need something in the markup that Raphael just doesn't support, you can create a rudimentary control for manipulating it using attr and animate by using paper.customAttributes and element.node (note that the documentation for element.node is pretty much just the highly unhelpful "Don't mess with it" - the reason you shouldn't mess with it is, it gives you the SVG or VML element directly, which means Raphael doesn't know about any of the changes you make to it, which may put your Raphael object out of sync with the element it controls, potentially breaking stuff. Unless you're careful, and use a technique like this...).

Here's an example (assuming jQuery is also being used, jQuery isn't essential but is more convenient) that sets the SVG property dy, which allows you to control line spacing of Raphael text (note - example code not yet tested in VML/IE. will update if it doesn't work in VML mode):

Live jsfiddle example

paper.customAttributes.lineHeight = function( value ) {
    // Sets the SVG dy attribute, which Raphael doesn't control
    var selector = Raphael.svg ? 'tspan' : 'v:textpath';
    var $node = $(this.node);
    var $tspans = $node.find(selector);
    $tspans.each(function(){
        // use $(this).attr in jquery v1.6+, fails for SVG in <= v1.5
        // probably won't work in IE
        this.setAttribute('dy', value );
    });
    // change no default Raphael attributes
    return {};
}
    // Then to use it...
    var text = paper.text(50,50,"This is \n multi-line \n text");
    // If you want to animate a custom attribute, always set it first - null isNaN
    text.attr({lineHeight: 0});
    text.animate({lineHeight: 100},500);