Custom Elements

This is the fourth article of the intermediate section of the JointJS tutorial. Go back to serialization. Alternatively, you can return to index of all articles.

JointJS comes with several collections of built-in element shapes. We already saw two members of the joint.shapes.standard collection in the basic element and links demos.

However, even though there are many default shapes to choose from, you might find that you are missing one and want to create your own shape definition. Creating new shapes is very simple in JointJS if you already know SVG. The most important SVG elements are rect, text, circle, ellipse, image and path. Their thorough description with examples and illustrations can be found elsewhere on the Internet, e.g. on MDN. What is important for us is to realize that combining the basic SVG shapes, we can define any 2D shape we need.

For that, we use a builtin JointJS function:

If you want to create an Element subtype from scratch, you should inherit from the default joint.dia.Element class by calling joint.dia.Element.define(). You can also inherit from any shape in the predefined JointJS shape collections (e.g. joint.shapes.standard.Rectangle.define()) and even any custom element subtype you have previously defined.

Here is how the parameters of the define() function map to familiar building blocks of elements:

Let us use the familiar joint.shapes.standard.Rectangle shape definition as an example:

joint.dia.Element.define('standard.Rectangle', {
    attrs: {
        body: {
            refWidth: '100%',
            refHeight: '100%',
            strokeWidth: 2,
            stroke: '#000000',
            fill: '#FFFFFF'
        },
        label: {
            textVerticalAnchor: 'middle',
            textAnchor: 'middle',
            refX: '50%',
            refY: '50%',
            fontSize: 14,
            fill: '#333333'
        }
    }
}, {
    markup: [{
        tagName: 'rect',
        selector: 'body',
    }, {
        tagName: 'text',
        selector: 'label'
    }]
});

Name

The first argument of the define() function is a unique identifier under which you want to be able to find the new type. The first part of the name, joint.shapes, is implied. Thus, we can see that the name of a type accessed as joint.shapes.standard.Rectangle has to be 'standard.Rectangle'.

Markup

Markup is usually provided inside the third argument of the define() function (prototype properties) for improved performance. (This is because markup is something that all instances of the element type are expected to have in common, so inheriting from subtype prototype is more efficient. Nevertheless, it is still possible to provide custom markup to individual instances of your class by providing individual markup later.)

The markup property is specified as a JSON array. Each member of the array is taken to define one subelement of the new shape. Subelements are defined with objects containing a tagName (a string with the SVG tag name of the subelement) and a selector (a string identifier for this subelement in the shape). More advanced markup.attributes are explored in the custom links tutorial. Although JointJS can also understand SVG markup in string form, that approach is noticeably slower due to the need for parsing and lack of capacity for custom selectors.

We can see that joint.shapes.standard.Rectangle is composed of two subelements - an SVGRectElement named body and an SVGTextElement named label:

{
    markup: [{
        tagName: 'rect',
        selector: 'body',
    }, {
        tagName: 'text',
        selector: 'label'
    }]
}

Selectors are important for the targeting of subelements by element attributes. Although providing a selector to identify a subelement is not strictly required, it makes JointJS noticeably faster because it can avoid querying the DOM. If you really do not want to invent a custom name for the subelement selector, you can use the subelement's tagName. (For up to one subelement per tagName; selector names have to be unique.)

{
    markup: [{
        tagName: 'rect',
        selector: 'rect',
    }, {
        tagName: 'text',
        selector: 'text'
    }]
}

Default Attributes

Default attributes are usually provided inside the second argument of the define() function (default instance properties). (This is because all instances of the element type are expected to have their own individual attributes, so inheriting from the prototype is likely to cause unnecessary overhead.)

In the attrs object, keys correspond to subelement selectors, as defined in the markup. For each subelement, an object with attribute name-value pairs is then expected. Each of these attributes can be a native SVG attribute or a JointJS special attribute.

In joint.shapes.standard.Rectangle, we can see that the subelement referenced by body (i.e. the SVGRectElement component of the shape) has its default width and height set in terms of the model size (using the relative-dimension special attributes refWidth/refHeight), alongside the fill and stroke styling. The label subelement (the SVGTextElement component of the shape) has its text anchor set to the center of the text bbox; that point is then positioned into the center of the model bbox by the two relative-position special attributes refX/refY. Its font size is specified, and the font fill color:

{
    attrs: {
        body: {
            refWidth: '100%',
            refHeight: '100%',
            strokeWidth: 2,
            stroke: '#000000',
            fill: '#FFFFFF'
        },
        label: {
            textVerticalAnchor: 'middle',
            textAnchor: 'middle',
            refX: '50%',
            refY: '50%',
            fontSize: 14,
            fill: '#333333'
        }
    }
}

We mentioned model size - the dimensions of the body depend on it - but what is it? Model size is set by the user, whenever they call the element.resize() function on an instance of joint.shapes.standard.Rectangle. For example, if we used element.resize(100, 100), the referenced size would be 100px by 100px; consequently, if no transformations were applied, the body would have the dimensions (100,100). The model bbox is invisible on its own; it only becomes visible through subelements that reference it. Here, that subelement is the body subelement.

There does not need to be a direct mapping between model size and any visible subelements. It is perfectly possible to replace the refWidth/refHeight relative attributes with the native SVG (absolute) width/height; this would create a subelement with constant dimensions - 20px by 20px, for example - regardless of model size. That may be ideal for control buttons.

Similarly, the position of label anchor is defined in terms of model size and position. Model position is modified by calling the element.position() function on an instance of joint.shapes.standard.Rectangle. For example, if we called element.position(-100, -100), the origin of the reference coordinates would move to the point (-100,-100) on the paper.

We can see that the anchor of the label of joint.shapes.standard.Rectangle is placed at refX: '50%',refY: '50%' by default. The percentages refer to model size; thus, if model size were kept at (100,100), they would mean that the anchor of the label will be offset from the reference origin by (50,50). Thus, if model position were (-100,-100) and size were (100, 100), the label anchor would be positioned at (-50,-50).

Relative positioning and sizing of elements is explained in more detail in a separate section of the tutorial.

Static Properties

Static properties are not used by joint.shapes.standard.Rectangle, but let us discuss them a little bit to gain a complete overview of custom elements.

Imagine we wanted to define our own subtype of joint.shapes.standard.Rectangle (which we name 'examples.CustomRectangle'), with the added benefit of a constructor function that chose a random style for the rectangle body - maybe because we need to add a lot of diverse rectangle shapes quickly. We could do this with a static function createRandom; then, we would have two ways to obtain an instance of CustomRectangle:

With the standard constructor ...

var customRectangle = new joint.shapes.examples.CustomRectangle();

... or with the new static function:

var customRectangle = joint.shapes.examples.CustomRectangle.createRandom();

Both of these functions are demonstrated in our example.

Example

Let us apply everything we learned so far and create a new joint.shapes.examples.CustomRectangle class based on joint.shapes.standard.Rectangle. Keep in mind that the provided instance properties are mixined with the parent definition, but prototype and static properties are not. This means that it is enough for us to record only the attributes that changed in the definition of the custom element subtype (however, if we wanted to change the markup, we would have to do so explicitly).

joint.shapes.standard.Rectangle.define('examples.CustomRectangle', {
    attrs: {
        body: {
            rx: 10, // add a corner radius
            ry: 10,
            strokeWidth: 1,
            fill: 'cornflowerblue'
        },
        label: {
            textAnchor: 'left', // align text to left
            refX: 10, // offset text from right edge of model bbox
            fill: 'white',
            fontSize: 18
        }
    }
}, {
    // inherit joint.shapes.standard.Rectangle.markup
}, {
    createRandom: function() {

        var rectangle = new this();

        var fill = '#' + ('000000' + Math.floor(Math.random() * 16777215).toString(16)).slice(-6);
        var stroke = '#' + ('000000' + Math.floor(Math.random() * 16777215).toString(16)).slice(-6);
        var strokeWidth = Math.floor(Math.random() * 6);
        var strokeDasharray = Math.floor(Math.random() * 6) + ' ' + Math.floor(Math.random() * 6);
        var radius = Math.floor(Math.random() * 21);

        rectangle.attr({
            body: {
                fill: fill,
                stroke: stroke,
                strokeWidth: strokeWidth,
                strokeDasharray: strokeDasharray,
                rx: radius,
                ry: radius
            },
            label: { // ensure visibility on dark backgrounds
                fill: 'black',
                stroke: 'white',
                strokeWidth: 1,
                fontWeight: 'bold'
            }
        });

        return rectangle;
    }
});

The following example shows the default look of joint.shapes.standard.Rectangle (i.e. with no instance attributes set) alongside the default look of our custom element and the randomized results of the createRandom() constructor function. Try refreshing the page to see createRandom() in action.

JointJS source code: custom-elements.js

Now that we know how to create custom element models, let us learn about custom links.