## 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:

- `Element.define(type [, defaultInstanceProperties, prototypeProperties, staticProperties])` - define a new subtype of this `Element` class.

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:

- `type` - the name of the subtype class.
- `defaultInstanceProperties` - object that contains properties to be assigned to every constructed instance of the subtype. Used for specifying default attributes.
- `prototypeProperties` - object that contains properties to be assigned on the subtype prototype. Intended for properties intrinsic to the subtype, not usually modified. Used for specifying shape markup.
- `staticProperties` - object that contains properties to be assigned on the subtype constructor. Not very common, used mostly for alternative constructor functions.

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.