JointJS+ Inspector

Inspector plugin creates an editor and viewer of cell model properties. It creates a two-way data-binding between the cell model and a generated HTML form with input fields. These input fields can be defined in a declarative fashion using a plain JavaScript object. Not only visual attributes can be configured for editing in the inspector but also custom data that will be set on the cell model! This all makes the inspector an extremely flexible and useful widget for use in applications.

Install

Include joint.ui.inspector.css and joint.ui.inspector.js files to your HTML:

<link rel="stylesheet" type="text/css" href="joint.ui.inspector.css"/>
<script src="joint.ui.inspector.js"></script>

Create an inspector

You can create the Inspector instance as follows:

var inspector = new joint.ui.Inspector(options).render();
inspector.$el.appendTo($('body'))

Usually the applications display only one inspector at the time, which is used for various application models and differs in the configuration of input fields only. For this common use-case we've introduced a static helper - joint.ui.Inspector.create(). It makes sure the previous instance (if there is any) is properly removed, it creates a new one and renders it into the DOM. It also keeps track of open/closed groups and restores them based on the last used state. It can be used as follows:

joint.ui.Inspector.create('#inspector', options);

For more information about the create method visit the Inspector API chapter.

paper.on('element:pointerdown', function(elementView) {
    // open the inspector when the user interacts with an element
    joint.ui.Inspector.create('#inspector', {
        cell: cellView.model,
        inputs: {
            attrs: {
                circle: {
                    fill: {
                        type: 'color-palette',
                        options: [
                            { content: '#FFFFFF' },
                            { content: '#FF0000' },
                            { content: '#00FF00' },
                            { content: '#0000FF' },
                            { content: '#000000' }
                        ],
                        label: 'Fill color',
                        group: 'presentation',
                        index: 1
                    },
                    stroke: {
                        type: 'color-palette',
                        options: [
                            { content: '#FFFFFF' },
                            { content: '#FF0000' },
                            { content: '#00FF00' },
                            { content: '#0000FF' },
                            { content: '#000000' }
                        ],
                        label: 'Outline color',
                        group: 'presentation',
                        index: 2
                    },
                    'stroke-width': {
                        type: 'range',
                        min: 0,
                        max: 50,
                        unit: 'px',
                        label: 'Outline thickness',
                        group: 'presentation',
                        index: 3
                    }
                },
                text: {
                    text: {
                        type: 'textarea',
                        label: 'Text',
                        group: 'text',
                        index: 1
                    },
                    'font-size': {
                        type: 'range',
                        min: 5,
                        max: 30,
                        label: 'Font size',
                        group: 'text',
                        index: 2
                    },
                    'font-family': {
                        type: 'select',
                        options: ['Arial', 'Times New Roman', 'Courier New'],
                        label: 'Font family',
                        group: 'text',
                        index: 3
                    }
                }
            }
        },
        groups: {
        presentation: {
            label: 'Presentation',
            index: 1
        },
        text: {
            label: 'Text',
            index: 2
        }
        }
    });
});

Configuration

There are two ways to create an instance of the inspector. The first option is to use the joint.ui.Inspector.create(container, options) static function (where container is a CSS selector of an HTML element on your page). The second option is to directly create an instance with new joint.ui.Inspector(options). The inspector can be configured by the options object with the following properties:

function(element, path, type, inspector) {
    return (element.validity ? element.validity.valid : true);
}

Options properties storeGroupsState / restoreGroupsState are applicable only if they are passed into the static create() method. Otherwise, you can use the API methods storeGroupsState() and restoreGroupsState() to manually manipulate group states.

Inputs Configuration

The inputs object is extremely important. Its structure mimics the structure of properties of the cell model. Instead of the final values, it contains definitions of input fields. (The input field is in charge of setting the user input on the specified cell model.)

The options object of inputs can contain the following parameters:

workdays: {
  type: 'select',
  options: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
  multiple: true,
  overwrite: true,
  group: 'occupation'
}

// overwrite: false (default)
Model: { existingProperty: 'value1' }
Input: { newProperty: 'value2' }
=>
Model: { newProperty: 'value2', existingProperty: 'value1' }

// overwrite: true
Model: { existingProperty: 'value1' }
Input: { newProperty: 'value2' }
=>
Model: { newProperty: 'value2' }

['option1', 'option2']

// select & select-box
[
    { value: 'value1', content: 'option1' },
    { value: 'value2', content: 'option2' }
]
// color-palette
[
    { content: 'red', icon: 'image1.svg' },
    { content: 'blue' }
]
// select-button-group
[
    {
        value: 'value1',
        content: 'option1',
        buttonWidth: 20,
        icon: 'image.png',
        iconSelected: 'image2.png',
        iconWidth: 20,
        iconHeight: 20
    }
]

'path'
=>
cell.prop('path')
=>
['option1', 'option2']

In preview mode, when the user hovers over one of the items in the widget (e.g. it being a dropdown item in the case of the 'select-box' type), the Inspector still changes the connected model but triggers the change with the dry flag set to true. You can then react to this by using:

myCell.on('change:myProperty', function(cell, change, opt) {
    if (opt.dry) {
        /* do something when in preview mode */
    } else {
        sendToDatabase(JSON.stringify(graph));
    }
});

This is useful, for example, if your application wants to reflect the values of the hovered items in the diagram but does not want to store the change to the database.

Note that the 'list' and 'object' types allow you to create input fields in the Inspector for arbitrary nested structures. If your cell contains an object as a property (cell.set('myobject', { first: 'John', last: 'Good' })), you can instruct the inspector to use the 'object' type for myobject property and then define types for each of the nested properties of that object:

var inspector = new joint.ui.Inspector({
    cellView: cellView,
    inputs: {
        myobject: {
            type: 'object',
            properties: {
                first: { type: 'text' },
                last: { type: 'text' }
            }
        }
    },
    groups: {}
});

Similarly, if your cell contains a list as a property (cell.set('mylist', [{ first: 'John', last: 'Good' }, { first: 'Jane', last: 'Good' }])), you can instruct the inspector to use the 'list' type for mylist property and then define the type of the list item. Importantly, the 'list' input type enables users to add and remove list items. In our example, the mylist item contains a nested object, so we need to define its properties as well:

var inspector = new joint.ui.Inspector({
    cellView: cellView,
    inputs: {
        mylist: {
            type: 'list',
            item: {
                type: 'object',
                properties: {
                    first: { type: 'text' },
                    last: { type: 'text' }
                }
            }
        }
    },
    groups: {}
});

Groups Configuration

Each group options object in the groups object can contain the following parameters:

Expressions

The inspector relies on expressions defined in the when parameter to switch the visibility of an input field based on the values of other inputs. Whenever an input field's expression is evaluated to false (meaning the condition is not met), the input field is hidden. Otherwise, the input field is shown.

Definition of Expressions

When evaluated in a model context, expressions return a boolean (true/false) based on the value of specified model attributes. Expressions are defined recursively as follows:

• { <primitive>: { <path>: <value> }, <*options> } is an expression
• { <unary-operator>: expression, <*options> } is an expression
• { <multiary-operator>: [expression-1, expression-2, ..., expression-n], <*options> } for n > 0 is an expression

...where:

Examples on using Expressions

Here are a few valid expressions:

{ eq: { 'size/width': 300 }}
{ regex: { 'attrs/text/text' : 'JointJS|Rappid' }}
{ lt: { 'count': 10 }}
{ in: { 'index': [0,2,4] }}
{ not: { eq: { 'day': 'Monday' }}}
{ and: [{ gte: { 'position/x': 100 }}, { lte: { 'position/x': 400 }}]}

Imagine a scenario where you have a 'select' input field with options 'email' and 'tel'. Below this input field, you want to show either a text field or a number input field, based on the selected option. Assuming your cell properties structure is as follows: { contact_option: 'email', contact_email: '', contact_tel: '' }, your inspector could look like this:

var inspector = new joint.ui.Inspector({
    cell: mycell,
    inputs: {
        contact_option: { type: 'select', options: ['email', 'tel'] },
        contact_email: { type: 'text', when: { eq: { 'contact_option': 'email' }}},
        contact_tel: { type: 'number', when: { eq: { 'contact_option': 'tel' }}}
    }
});

It is also possible to refer to input fields inside nested objects, by using more complicated paths:

var inspector = new joint.ui.Inspector({
    cell: mycell,
    inputs: {
        user_info: {
            type: 'object',
            properties: {
                contact_option: { type: 'select', options: ['email', 'tel'] },
                name: { type: 'text'}
            }
        },
        contact_email: { type: 'text', when: { eq: { 'user_info/contact_option': 'email' }}},
        contact_tel: { type: 'number', when: { eq: { 'user_info/contact_option': 'tel' }}}
    }
});

It does not make sense to reference list items from the outside, but it does make sense to reference sibling input fields within a list item's when clause. To do that, a wildcard ('${index}') has to be placed within the path - it will be dynamically substituted for the actual index of the item inside which the when clause is being evaluated:

var inspector = new joint.ui.Inspector({
    cell: mycell,
    inputs: {
        user_list: {
            type: 'list',
            item: {
                type: 'object',
                properties: {
                    contact_option: { type: 'select', options: ['email', 'tel'] },
                    contact_email: { type: 'text', when: { eq: { 'user_list/${index}/contact_option': 'email' }}},
                    contact_tel: { type: 'number', when: { eq: { 'user_list/${index}/contact_option': 'tel' }}}
                }
            }
        }
    }
});

It is also possible to toggle groups with when expressions.

var inspector = new joint.ui.Inspector({
    groups: {
        first: { label: 'F' },
        second: { label: 'S', when: { eq: { 'attribute2': true }}}
    }
});

Custom Operators in Expressions

As you can see above, ui.Inspector provides a good list of useful built-in primitive operators (eq, lt, in, ...). However, sometimes this is not enough and applications have special requirements for when fields in the inspector should be hidden/displayed based on other information. To meet this requirement while still taking advantage of the inspector configurability through expressions, ui.Inspector provides a way to define your own custom operators.

First, the custom primitive operator has to be defined inside the operators array option on the Inspector. Each operator definition is an object of the form: { custom-primitive: function(cell, value, *arguments) }. The provided callback function should return true when the operator condition is successful, and false otherwise. The cell parameter is the cell associated with the Inspector, value is the value of the field at the path specified in the when clause (see below), and *arguments is anything that was passed to the operator (see below).

Second, in the when clause of a definition within the Inspector's inputs object, an expression with a custom operator has to be defined according to the following format:

• { <custom-primitive>: { <path>: <*arguments> }, <*options> }

The custom primitive expression can be used as an operand in unary and multiary operators, the same as if it was a built-in primitive expression.

For example, let's say you want to show an inspector field only when a value of another input field is longer (has more characters) than the value of a numeric property set on the associated inspector cell:

var inspector = new joint.ui.Inspector({
    cell: mycell,
    inputs: {
        title: { type: 'text' },
        description: { type: 'text', when: { longerThan: { 'title': 'titleThreshold' } } },
    },
    operators: {
        longerThan: function(cell, value, prop, valuePath) {
            // value === contents of 'title' input field
            // prop === 'titleThreshold'
            // valuePath === 'title'
            return (value ? (value.length > cell.prop(prop)) : false);
        }
    }
});

The example above displays the description field only when the content of title is longer than a numeric threshold which we have stored in a property on the cell model named titleThreshold. Now whenever the user types within the 'title' input field in the inspector and the text becomes longer than cell.get('titleThreshold'), the description field appears (and vice versa, if the text becomes shorter than titleThreshold, the description field gets hidden).

However, the example above has a small problem. If the value of the titleThreshold property changes on the cell model (e.g. due to some other change somewhere else in the application), that change is not taken into account by the expression. In order to fix this, we have to tell the inspector that there are prop dependencies that could affect the resolution of the expression in the when clause - we do that by providing a dependencies list inside the when clause. Here's the fixed version of the code provided above:

var inspector = new joint.ui.Inspector({
    cell: mycell,
    inputs: {
        title: { type: 'text' },
        description: {
            type: 'text',
            when: {
                longerThan: { 'title': 'titleThreshold' },
                dependencies: ['titleThreshold']
            }
        },
    },
    operators: {
        longerThan: function(cell, value, prop, valuePath) {
            // value === contents of 'title' input field
            // prop === 'titleThreshold'
            // valuePath === 'title'
            return (value ? (value.length > cell.prop(prop)) : false);
        }
    }
});

Validation

The following example shows how to reflect a custom shape's validation functions inside your Inspector. The inspector definition provides a custom validateInput method. That method then refers to Shape's custom validateProperty method, which uses some common regex validators. Notice that this architecture makes the Shape (the model instance) responsible for accepting/rejecting user input data, not the Inspector. As such, this arrangement manages to fulfill one of the goals of the JointJS framework, namely the separation of Model-View-Controller components from each other.

(function(joint, Shape) {

    joint.setTheme('modern');

    var paper = new joint.dia.Paper({
        el: document.getElementById('paper'),
        width: 500,
        height: 500
    });

    var shape = new Shape();
    shape.position(150,50);
    shape.size(200,200);
    shape.addTo(paper.model);

    var inspector = joint.ui.Inspector.create('#inspector', {
        cell: shape,
        inputs: shape.getInspectorDefinition(),
        validateInput: function(el, path, type, inspector) {
            var $el = $(el);
            var value = inspector.parse(type, inspector.getFieldValue(el, type), el);
            $el.removeClass('error').parent().find('error').remove();
            var error = shape.validateProperty(path, value);
            if (error) {
                var $error = $('<error/>').text(error);
                $el.addClass('error').before($error);
            }
            return !error;
        }
    });

    // run the first validity check
    inspector.updateCell();

})(joint, joint.dia.Element.define('Shape', {

    attrs: {
        body: {
            refWidth: '100%',
            refHeight: '100%',
            fill: '#dddddd',
            stroke: 'lightblue',
            strokeWidth: 2
        }
    },

    phoneNumber: '',
    emailAddress: 'org@client.io'

}, {

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

    REGEX_PHONE_NUMBER: /^(\+\d{1,2}\s)?\(?\d{3}\)?[\s.-]\d{3}[\s.-]\d{4}$/,
    REGEX_HEXCOLOR: /^#([a-f0-9]{3}){1,2}\b/i,
    REGEX_EMAIL_ADDRESS: /^\w+@[a-zA-Z_]+?\.[a-zA-Z]{2,3}$/,

    validateProperty: function(path, value) {
        switch (path) {
            case 'attrs/body/stroke':
            case 'attrs/body/fill':
                if (this.REGEX_HEXCOLOR.test(value)) break;
                return 'Invalid Color (e.g. #ff0000)';
            case 'attrs/body/strokeWidth':
                if (_.isNumber(value) && value >= 0) break;
                return 'Invalid Stroke Width (A positive number)';
            case 'phoneNumber':
                if (this.REGEX_PHONE_NUMBER.test(value)) break;
                return 'Invalid Phone Number (e.g. 123-456-7890)';
            case 'emailAddress':
                if (this.REGEX_EMAIL_ADDRESS.test(value)) break;
                return 'Invalid Email Address.';
        }
        return null;
    },

    getInspectorDefinition: function() {
        return {
            'attrs/body/fill': {
                type: 'text',
                label: 'Fill Color'
            },
            'attrs/body/stroke': {
                type: 'text',
                label: 'Stroke Color'
            },
            'attrs/body/strokeWidth': {
                type: 'number',
                label: 'Stroke Width'
            },
            'phoneNumber': {
                type: 'text',
                label: 'Phone Number'
            },
            'emailAddress': {
                type: 'text',
                label: 'Email Address'
            }
        };
    }

}));

Custom Fields

The Inspector has a useful built-in set of ready-to-use field types. However, in some cases, you might want to render your own custom fields (or to integrate a third party widget) while still taking advantage of the two-way data binding and the configuration options provided by Inspector. This can be done with two Inspector options: renderFieldContent(options, path, value) and getFieldValue(attribute, type).

The following example shows how to render two buttons in a single custom field and how to integrate the Select2 widget for advanced select boxes:

function createInspector(cellView) {

    joint.ui.Inspector.create('.inspector-container', {
        cellView: cellView,
        inputs: {
            attrs: {
                label: {
                    style: {
                        textDecoration: {
                            label: 'Text Style',
                            type: 'select2',
                            group: 'text-decoration',
                            options: ['none', 'underline', 'overline', 'line-through']
                        }
                    },
                    text: {
                        label: 'Text Content',
                        type: 'my-button-set',
                        group: 'text'
                    }
                }
            }
        },
        groups: {
            'text-decoration': { label: 'Text Decoration (Select2)' },
            'text': { label: 'Text' }
        },

        renderFieldContent: function(options, path, value, inspector) {

            switch (options.type) {

                case 'my-button-set':

                    var $buttonSet = $('<div/>');
                    var $yes = $('<button/>').text('Say YES!');
                    var $no = $('<button/>').text('Say NO!');
                    var $buttons = $('<div/>').append([$yes, $no]).css({
                        margin: 10,
                        display: 'inline-block'
                    });
                    var $label = $('<label/>').text(options.label || path);
                    $buttonSet.append([$label, $buttons]);
                    $buttonSet.data('result', value);
                    // When the user clicks one of the buttons, set the result to our field attribute
                    // so that we can access it later in `getFieldValue()`.
                    $yes.on('click', function() {
                        $buttonSet.data('result', 'YES');
                        inspector.updateCell($buttonSet, path, options);
                    });
                    $no.on('click', function() {
                        $buttonSet.data('result', 'NO');
                        inspector.updateCell($buttonSet, path, options);
                    });

                    return $buttonSet;

                case 'select2':

                    var $select = $('<select/>').width(170).hide();

                    $select.select2({ data: options.options }).val(value || 'none').trigger('change');
                    $select.data('select2').$container.css('margin', 10);
                    $select.on('change', function() {
                        inspector.updateCell($select, path, options);
                    });

                    return $('<div/>').append([
                        $('<label/>').text(options.label || path),
                        $select.data('select2').$container
                    ]);
            }
        },

        getFieldValue: function(attribute, type) {

            if (type === 'my-button-set') {
                return { value: $(attribute).data('result') };
            }

            if (type === 'select2') {
                const $select = $(attribute).find('.select2').data('element');
                return { value: $select.val() };
            }
        }
    });
}

source code

Custom Labels

It is also possible to customize the appearance and behavior of field labels in your Inspector. This can be used to create labels with custom HTML - as demonstrated by the myList label (an <a> tag with a <label> tag inside), which links to an address specified in myList.url. Additionally, our templating functionality can be used to define dynamic labels. We use this for myList.item elements; when an element is added to the array with the + button, the '{{index}}' placeholder is replaced with the element's actual index within myList.

joint.ui.Inspector.create('#container', {
    cell: model,
    inputs: {
        myList: {
            type: 'list',
            url: 'https://jointjs.com',
            item: {
                type: 'text',
                label: 'Item {{index}}'
            }
        }
    },
    renderLabel: function(opt, path) {
        // returns an HTMLElement (`$el`) as a custom label
        // this method is called for every element inside inspector when being rendered
        // in this case, it is called when the example loads, to create a label for the whole `myList`
        // it is also called whenever the + button is pressed, to create a label for each element added to `myList`

        var $label = document.createElement('label');
        var $el = $label;

        // List numbering:
        var text = opt.label;
        var indexPlaceholder = '{{index}}';
        // is this an inspector element with a `label` text specified (i.e. one of `myList` items)?
        // does this inspector element contain a substring to replace?
        if (text && text.indexOf(indexPlaceholder) > -1) {

            // every input field in the inspector is addressed via a `path`
            // elements added to `myList` are addressed as 'myList/0', 'myList/1', etc.
            // we can use this in a regex to identify list elements
            // we do this by checking if there is a '/' followed by a digit at the end of the path
            var match = path.match(/\/(\d+)$/);
            if (match) {

                // if this is a list element, use its index as index
                // (+1 to make sure the rendered labels start from 1)
                var index = parseInt(match[1], 10) + 1;
                // actually add the human-readable index to the label
                text = text.replace(indexPlaceholder, index);
            }
        }
        // then, set the text of the label to the text we generated

        // else: set it to the raw `path` string
        // (this happens for `myList` itself - so it gets a label that says 'myList')
        $label.textContent = text || path;

        // item labels are hidden via CSS by default, we need to unhide them
        $label.style.cssText = 'display:block !important;';

        // Clickable label:
        // is this an inspector element with an `url` specified (i.e. `myList` itself)?
        if (opt.url) {
            // then create a new <a> element and add <label> to it
            var $a = document.createElement('a');
            $a.href = opt.url;
            $a.target = 'blank';
            $a.appendChild($el);
            $el = $a;
        }

        // we have created a custom label
        return $el;
    }
});

Inspector Events

The Inspector object triggers events when the user changes its inputs or when the Inspector needs to re-render itself partially. These events can be handled by using the Inspector on() method.

Inspector API

static

public