Rappid - ui

Rappid now comes with a variety of themes ("material", "modern", "dark", and the default theme). It is possible to set the theme globally (applied to all UI components) and to set a different theme for each UI component individually.

Setting the theme globally:

joint.setTheme('material');

This will update the theme for all the components currently rendered, as well as for any components that are rendered from now on.

Setting the theme for an individual component:

var colorPalette = new joint.ui.ColorPalette({
    theme: 'material',
    options: [
        { content: '#90C3D4' },
        { content: '#D4A190' },
        { content: '#A1D490' },
        { content: '#ffffff' }
    ]
});
document.body.appendChild(colorPalette.render().el);

And to change the theme of a component that has already been rendered:

colorPalette.setTheme('modern');

Here you can view all the Rappid UI plugins for every theme (you can also open it in a separate window) :

Clipboard implements copy-pasting of cells. Optionally, clipboard also supports storing cells in an HTML 5 localStorage so that copy-pasting of cells works despite a browser tab being refreshed or closed/reopened. Additionally, clipboard is also able to copy cells from one paper and paste them to another. However, the determination of the targeted paper is left to the application layer.

Installation

Include joint.ui.clipboard.js to your HTML:

<script src="joint.ui.clipboard.js"></script>

Clipboard Configuration

Instantiating a clipboard is a matter of creating a joint.ui.Clipboard object:

var clipboard = new joint.ui.Clipboard({ useLocalStorage: false });>

Clipboard API

Clipboard Setup

The next step is hooking these methods to relevant user events.

var selection = new joint.ui.Selection({ paper: paper });
var keyboard = new joint.ui.Keyboard;

keyboard.on('ctrl+c', function() { clipboard.copyElements(selection.collection, paper.model); });
keyboard.on('ctrl+x', function() { clipboard.cutElements(selection.collection, paper.model); });
keyboard.on('ctrl+v', function() { clipboard.pasteCells(paper.model); });

Note that the selection.collection is a Backbone.Collection that stores the selected elements. The clipboard is probably the best when used in combination with the Selection JointJS plugin. We suggest you to look at the documentation to the Selection plugin for further details on using selections.

Also, it is advisable to look at our Kitchen Sink application to see how the Selection and Clipboard work together.

ui.ColorPalette is a UI widget for displaying dropdowns with color palette.

Installation

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

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

Usage

Create an object of ui.ColorPalette type, render it with the render() method and append the generated HTML element anywhere in your DOM:

var colorPalette = new joint.ui.ColorPalette({
    options: [
	{ content: '#000000' },
	{ content: '#FFFFFF' },
	{ content: 'transparent', icon: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGoAAABrCAYAAACffRcyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAABPxJREFUeNrsnc9rU1kUx+/LS2LTBtI4VMiqjYjiQgQ3IoIUuhvGUmYzUBgV8SdWLS7sooLgxm0XgjKg0P+gMDC7ggjDzGwGOt1psS2WBptioiYVmrbxnviiSc17eaPvvdzz7vcLlyTk5vVyPtzzzv3mtDWq1arYrVwuNyAfxuUYkaNfQEFoWY4ZOaYymczS7jeNRlASUC9NlOMs4tZRTdNGkcCKX4GyID2V4yjipITm5Bisw4oAkrIiFk8tNp9AWekOkNSENVVLfaurq1Q4LCImSisbtao7R5mmWTQMYxPx8l6yRohvb2/3tpk2HrVKcFtA6XT6WSwWKyOk/qlSqfQUCoVTDsBGIk7nJEAKRhRjirXDlP6I024CpGBhUczt3rcFhXtS8HKKeQTh4aHot35Q3vyObW1tpdvNSyQSi8lk8iWu1yFQtGg59rWbJyuZNVzv+4XUx0QABVCa68+/0mJi8oj4/Y99Xlwuioj6BOn8lSHx4UOs9vr0j2vYUYrJ/G++6zOkRKIihn9aQepTzV14viB6Lo5lP0N68mhWnDxRACjFIP1w9YYwNjZMryEBlNeQSmVR7e7e9hoSib44rLasMqLRtb6+vlm7D5ZKpf3ycNfj4qCY2tnZ2dM2t5tmSY4NbtejexKlO9pJBOndbw/ym4cPtd0ArRyMfD4/ZHeo/uaqz61N4vTDGxWPx9dSqdQ8q+tRdXfhGhUOtXRnPH44u3nwwDE/HAykPi9KcB/uSQDFEBJAMYEEUEwgAdT3OA4BQgIoBRwHgGLiOAAUE8fBrXzvmaATPR0W3TgEdPhU5Xo1x+Hy9WbHQR5m5QnZk/XJOa8DAeW2h0A3x8Ht+pD6GJfgAMUcEkDZQSLdmfhbFUgAZQfp9q1/xK+jKyotUXtQTY5DHdLYlZeqrVNrUE2Og8KQtAbV5DgoDklbUI2OAwdIJO16Jhp7HOh1eXLizcbPw1tBrw89E24dB2snSUjZTqwPPRP/pwRXPN3pB4o5JD1AhQBS+EGFBFKoQXFxHLQGxclx0BYUN8dBS1CR9yWRuneflePgVqHpmTCKb83kxWvZyOJSV4PjkJUn0KwK62txgNawZyKfj4vRc0Pi1UpXpx0H9EzYRzAuRn4hSL1hS3fhAaUJJN6gNILEF5RmkFiCoupON0jsQNE5KXnmQlY3SKxAEaS9V2+K+jlJJ0hsQNUhxV4sCB0h1VK+6j0TNcdBprtdjkPgPQ7omQiZ46Bfz4SGJTg/UIDEABQgMQAFSOqD0tVxYAVKZ8eBDSjdHQcWoOA4uFfHeia49Tjo2TMRYschPD0TKMEZgAIkBqAAiQEoQFIfFBwHBqDgODAABceBASg4Dj7cQrzumQhrj0O4eibgODDomUAJzuAeBUhMQF0aOw5IHECVy3FA8lfe/HvXu5P/1h4V+husANVKAMTXmYAACqnPD9EJ3M3hzm0PgW7XCwyU29/6wPWQ+nCPghQAVa1W4whPsHKKuS0oeUPsrVQqPQhfMKJYU8ydQC3bvVkoFE4BVjCQKNYOU5ap6puR46bdrlpfXx82TbNoGMYmQupPunPaSZZm6BveAflkESFTWtlIJpNZkk+mEQtlNU2M6sXEuBxziIlymrPYfKr6JLGifBgELOUgDVpsvpTnDbCQBhVId42QSIasOr6alcvlBqwtNyJHP+IWiJatCnzKqhua1BIUpJ4+CjAAVnYzLhKE5pcAAAAASUVORK5CYII=' },
	{ content: '#B3B3B3' },
	{ content: '#808080' },
	{ content: '#4D4D4D' },
	{ content: '#E6E6E6' },
	{ content: '#FFC7C9' },
	{ content: '#FFA0A4' },
	{ content: '#E3686D' },
	{ content: '#D71920' },
	{ content: '#FFE3D1' },
	{ content: '#FFCBA8' },
	{ content: '#FFAB73' },
	{ content: '#F58235' }
    ]
});
document.body.appendChild(colorPalette.render().el);

Configuration

The following table lists options that you can pass to the ui.ColorPalette constructor function. You might notice that many of the options are similar to the ui.SelectBox widget. This is because the ui.ColorPalette inherits from this widget.

API

Events

The ui.ColorPalette object triggers various events that you can react on. Events can be handled by using the on() method (see above).

ui.ContextToolbar is a UI widget for displaying context toolbars (usually a set of buttons) below a certain target element (HTML or SVG). There can always be only one context toolbar opened at a time. This is automatically handled by the ui.ContextToolbar component which simplifies the process and makes sure you don't have to keep track of opened context toolbars yourself.

Installation

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

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

Usage

Create an object of joint.ui.ContextToolbar type, add tool buttons and call the render() method in order to open the context toolbar.

var ct = new joint.ui.ContextToolbar({
    tools: [
        { action: 'yes', content: 'Yes' },
        { action: 'no', content: 'No' },
        { action: 'maybe', content: 'Maybe' },
        { action: 'sure', content: 'Sure' }
    ],
    target: this
});

ct.on('action:yes', function() { alert('Yes') });
ct.on('action:no', function() { alert('No') });
ct.on('action:maybe', function() { alert('Maybe') });
ct.on('action:sure', function() { alert('Sure') });

ct.render();

A common usage is to open the context toolbar on click on a certain element (either HTML or SVG):

$('circle').on('click', function() {

    var circle = this;

    var ct = new joint.ui.ContextToolbar({
	tools: [
	    { action: 'hide', content: 'Hide' },
	    { action: 'info', content: 'Info' },
	    { action: 'remove', content: 'Remove' }
	],
        target: circle
    });

    ct.on('action:hide', ct.remove, ct);
    ct.on('action:remove', function() {
        V(circle).remove();
    });
    ct.on('action:info', function() {
        alert('This is an SVG circle');
    });

    ct.render();
});

Configuration

The following table lists options that you can pass to the ui.ContextToolbar constructor function:

API

Events

The ui.ContextToolbar object triggers events that correspond to the actions that you defined in the tools array. Events can be handled by using the on() method (see above).

ui.Dialog is a UI widget for displaying both modal and non-modal dialog boxes. It's a little window that overlays all other elements on the page. ui.Dialog supports an arbitrary HTML content, allows you to define buttons in an easy way and can even be inlined on the page in any HTML container. The dialog can be optionally draggable.

Installation

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

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

Usage

Simply create an object of ui.Dialog type and call open() method on it:

var dialog = new joint.ui.Dialog({
    width: 300,
    title: 'My title',
    content: 'This is my dialog box.'
});
dialog.open();

Configuration

The following table lists options that you can pass to the ui.Dialog constructor function:

API

Events

The ui.Dialog object triggers events when the user clicks one of its buttons. Events can be handled by using the on() method.

ui.FlashMessage is a UI component for displaying flash messages. This is very useful for informing the user that something has happened. As you will see later on on this page, ui.FlashMessage plugin provides a quick way of displaying messages without you having to worry about closing the message boxes or cascading them on top of each other.

Installation

Include joint.ui.flashMessage.js and joint.ui.flashMessage.css files and joint.ui.dialog.js and joint.ui.dialog.css dependencies (ui.FlashMessage inherits from ui.Dialog) to your HTML:

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

Usage

There are two ways to display flash messages. One is by creating an object of joint.ui.FlashMessage type and call the open() method on it. However, for convenience, there is also a static method joint.ui.FlashMessage.open() that is much shorter:

// The longer method of displaying a flash message.
(new joint.ui.FlashMessage({
    title: 'Message',
    type: 'alert',
    content: 'An error occurred. Try again later.'
})).open();

// A shorter alternative.
joint.ui.FlashMessage.open('I am a flash message.');

Couple more examples of common usage:

$('#btn-display').on('click', function() {
    (new joint.ui.FlashMessage({
	title: 'Message',
        type: 'alert',
	content: 'An error occurred. Try again later.'
    })).open();
});

$('#btn-display-width').on('click', function() {
    (new joint.ui.FlashMessage({
        width: 150,
	title: 'Message',
	content: 'An error occurred. Try again later.'
    })).open();
});

$('#btn-display-modal').on('click', function() {
    (new joint.ui.FlashMessage({
        type: 'alert',
        closeAnimation: false,
        modal: true,
	title: 'Modal Message',
	content: 'This is a modal Flash message requiring the user to close the message manually.'
    })).open();
});

$('#btn-close-all').on('click', function() {
    joint.ui.FlashMessage.close();
});

joint.ui.FlashMessage.open('ui.FlashMessage 1');
joint.ui.FlashMessage.open('ui.FlashMessage alert', '', { type: 'alert', closeAnimation: { delay: 1000 } });
joint.ui.FlashMessage.open('ui.FlashMessage warning', '', { type: 'warning', closeAnimation: { delay: 2000 } });
joint.ui.FlashMessage.open('ui.FlashMessage success', '', { type: 'success', closeAnimation: { delay: 3000 } });
joint.ui.FlashMessage.open('ui.FlashMessage neutral', '', { type: 'neutral' });
joint.ui.FlashMessage.open('ui.FlashMessage info', '', { type: 'info' });
joint.ui.FlashMessage.open('ui.FlashMessage close delay 3s', '', { type: 'neutral', closeAnimation: { delay: 3000 } });
joint.ui.FlashMessage.open('ui.FlashMessage with title', 'Title');
joint.ui.FlashMessage.open('ui.FlashMessage without close animation', '', { closeAnimation: false });

Configuration

The following table lists options that you can pass to the ui.FlashMessage constructor function:

API

Events

The ui.FlashMessage object triggers events that you can react on. Events can be handled by using the on() method (see above).

FreeTransfrom plugin creates a control panel above an element giving an user the ability to resize an element in any direction or rotate it.

Installation

Include joint.ui.freetransform.css, joint.ui.freetransform.js and joint.dia.freetransform.js files to your HTML:

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

Usage

The usage of the ui.FreeTransform plugin is pretty straightforward. Just instantiate an object of the joint.ui.FreeTransform type and pass in the view for the element you want to have the free transform handles hooked onto:

var graph = new joint.dia.Graph;
var paper = new joint.dia.Paper({ el: $('#paper'), width: 500, height: 500, model: graph });

paper.on('cell:pointerup', function(cellView) {
    // We don't want to transform links.
    if (cellView.model instanceof joint.dia.Link) return;

    var freeTransform = new joint.ui.FreeTransform({ cellView: cellView });
    freeTransform.render();
});

Configuration

The joint.ui.FreeTransform constructor accepts the following options:

API

The joint.ui.FreeTransform objects provide the following methods:

Halo creates a control panel above an element with various tools. This gives the user control over your elements with tools located right at hand.

Installation

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

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

Creating a Halo

var graph = new joint.dia.Graph;
    var paper = new joint.dia.Paper({ el: $('#paper'), width: 500, height: 500, model: graph });

    paper.on('cell:pointerup', function(cellView) {
        // We don't want a Halo for links.
        if (cellView.model instanceof joint.dia.Link) return;

        var halo = new joint.ui.Halo({ cellView: cellView });
        halo.render();
    });

The joint.ui.Halo constructor takes a graph and paper objects + it also requires the view of a cell we want to display the halo above.

Default handles (tools)

The ui.Halo control panel has the following built-in tools. To add custom tools, please see the section Customizing halo tools.

Configuration

The joint.ui.Halo constructor function takes an options object as an argument. The options object can have the following parameters:

new joint.dia.Halo({
  cellView: elementView,
  magnet: function(elementView, end, evt) {
    // where `end` is either "source" (linking and forking) or "target" (forking only)
    // and `evt` is a `mousedown` event
    // connect the link directly to a rectangle element as opposed to the element group
    return elementView.el.querySelector('rect') || elementView.el;
  }
})

Disabling halo tools

Built-in tools are remove, resize, rotate, clone, fork, link and unlink. You can call the removeHandle() method to remove any of these tools just by passing its name:

halo.removeHandle('clone');

Alternatively, you can disable tools via CSS:

.halo .handle.clone { display: none; } /* disables the clone tool */

Also, the same way you would hide halo tools, as explained above, you can reposition them. For example, to reposition the remove icon tool to the bottom left corner, you could do:

.halo .handle.remove {
       left: -25px;
       bottom: -25px;
       top: auto;
       right: auto;
    }

Another way to remove/reposition tool handles in the Halo is in JavaScript:

halo.removeHandle('clone');
    halo.changeHandle('remove', { position: 'se' });

The code above removes the clone tool from the Halo and re-positions the remove tool to the bottom right (south-east).

Each Halo can also be styled in CSS (disabling tools, repositioning, changing icons, ...) based on the type of element the Halo is displayed for. The Halo <div> container stores the type of the element in its data-type attribute. This makes it easy to target a halo for a certain type of element in your CSS. For instance, let's say we want to hide the remove tool only for an element of type "basic.Rect". We can do this:

.halo[data-type="basic.Rect"] .remove { display: none; }

Customizing halo tools

Halo provides three methods for adding, removing and changing custom tools: addHandle(), removeHandle() and changeHandle(). Use the addHandle() method to add new tools to your halo:

halo.addHandle({ name: 'myaction', position: 's', icon: 'myaction.png' });
    halo.on('action:myaction:pointerdown', function(evt) {
        evt.stopPropagation();
        alert('My custom action.');
    });

In the example above, we added a new tool named myaction, positioned the tool to the south (bottom-center) and used our own icon myaction.png. When the user clicks on our tool, Halo triggers an event named action:[name]:pointerdown. We can handle the event by listening on the halo object. Similarly, the Halo triggers action:[name]:pointermove and action:[name]:pointerup events. This gives us a high flexibility in implementing our own actions.

For removing a halo tool, use the removeHandle(name) method:

halo.removeHandle('myaction')

changeHandle() method allows us to change halo tool handles. For instance, if we want to change a position of the clone tool, we could use:

halo.changeHandle('clone', { position: 'se' })

Pie menu type of Halo

To display the Halo control panel as a pie menu, just set the type option to 'pie':

new joint.ui.Halo({ cellView: myElementView, type: 'pie' })

You can still add your own actions as you would normally do with the default 'surrounding' type of Halo.

Toolbar type of Halo

To display the Halo control panel as a small toolbar above an element, just set the type option to 'toolbar':

new joint.ui.Halo({ cellView: myElementView, type: 'toolbar' })

Links with Halo

It is also possible to use the Halo plugin with links, as the following demo illustrates.

API

Events

The Halo object triggers events when the user manipulates its tools. These events can be handled by using the Halo on() method.

halo.on('action:link:add', function(link) {
        if (!link.get('source').id || !link.get('target').id) {
            link.remove();
        }
    });

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 on open/closed groups and restore 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. being it a dropdown item in 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 on 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, 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 on 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, 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) {
            // value === contents of 'title' input field
            // prop === 'titleThreshold'
            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) {
            // value === contents of 'title' input field
            // prop === 'titleThreshold'
            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:

var graph = new joint.dia.Graph;
var paper = new joint.dia.Paper({
    el: document.getElementById('paper'),
    width: 500,
    height: 300,
    gridSize: 1,
    model: graph
});

var r1 = new joint.shapes.standard.Rectangle({
    position: { x: 80, y: 80 },
    size: { width: 130, height: 80 },
    attrs: { label: {
        text: 'My Element',
        textDecoration: 'none'
    }}
});
graph.addCell(r1);

var r2 = new joint.shapes.standard.Rectangle({
    position: { x: 290, y: 80 },
    size: { width: 130, height: 80 },
    attrs: { label: {
        text: 'My Second Element',
        textDecoration: 'none'
    }}
});
graph.addCell(r2);

function createInspector(cellView) {

    joint.ui.Inspector.create('.inspector-container', {
        cellView: cellView,
        inputs: {
            attrs: {
                text: {
                    style: {
                        textDecoration: {
                            type: 'select2',
                            group: 'text-decoration',
                            options: ['none', 'underline', 'overline', 'line-through']
                        }
                    },
                    text: {
                        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/>').css('margin', 20);
                    var $yes = $('<button/>').text('Say YES!');
                    var $no = $('<button/>').text('Say NO!');
                    $buttonSet.append([$yes, $no]);
                    $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();

                    // select2 requires the element to be in the live DOM.
                    // Therefore, postpone the select2 initialization for after we
                    // add the Inspector container to the live DOM (see below).
                    setTimeout(function() {
                        $select.show().select2({ data: options.options }).val(value || 'none').trigger('change');
                        $select.data('select2').$container.css('margin', 20);
                        $select.on('change', function() {
                            inspector.updateCell($select, path, options);
                        });
                    }, 0);

                    return $select;
            }
        },

        getFieldValue: function(attribute, type) {

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

            // Note that for our select2 select, we do not need to write
            // a special value extraction code. This is because
            // Inspector will use the .val() method on the <select/> input by default.
        }
    });
}

// start with inspector for `r1`
createInspector(paper.findViewByModel(r1));

// switch inspector at pointerup
paper.on('cell:pointerup', createInspector);

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

The ui.Keyboard is an essential plugin for creating keyboard shortcuts in your Rappid application. It allows you to bind custom handlers (functions) to arbitrary keyboard events (e.g a single keystroke, key combination).

API

Event description

The shortcut can be defined as a string, either a single keystroke e.g. enter, esc, up, down, left or a combination like ctr+c, ctrl+alt+t etc. If you need to be more specific - in terms of keydown, keyup, keypress events - you can also define shortcut as keydown:a, keyup:enter or even keyup:ctrl+x.

Multiple shortcuts bound to a single handler can be defined as a list of shortcuts, separated by a space.

keyboard.on('ctrl+v shift+insert', pasteHandler);

Please note that all Backbone event methods also support an event map syntax.

keyboard.on({
    'enter': addNewHandler,
    'ctrl+enter' : createNewHandler,
    'up down left right': moveHandler
})

Demo

ui.Lightbox is a UI component for displaying images by filling the screen and dimming out the rest of the application. ui.Lightbox component nicely auto-adjusts based on the size of the screen.

Installation

Include joint.ui.lightbox.js and joint.ui.lightbox.css files and joint.ui.dialog.js and joint.ui.dialog.css dependencies (ui.Lightbox inherits from ui.Dialog) to your HTML:

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

Usage

Create an object of joint.ui.Lightbox type and call the open() method in order to open the lightbox.

var lightbox = new joint.ui.Lightbox({
    title: 'Image caption goes here.',
    image: 'images/lightbox.png'
});
lightbox.open();

Another common usage is opening images in lightbox on click:

$('img').on('click', function(evt) {
    new joint.ui.Lightbox({
        title: $(evt.target).attr('title'),
        image: $(evt.target).attr(src)
    }).open();
});

The downloadable option offers an easy way to download an image:

$('img').on('click', function(evt) {
    new joint.ui.Lightbox({
        title: $(evt.target).attr('title'),
        image: $(evt.target).attr(src),
        downloadable: true
    }).open();
});

Configuration

The following table lists options that you can pass to the ui.Lightbox constructor function:

API

Events

The ui.Lightbox object triggers various events that you can react on. Events can be handled by using the on() method (see above).

ui.Navigator is a UI widget that displays a smaller view into a larger diagram. It's a quick way for users to navigate in diagrams with pannable and resizable rectangle.

Installation

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

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

Usage

Simply create an object of ui.Navigator type, append the navigator HTML DOM element to any container and call the render() method. The navigator requires a ui.PaperScroller object as a parameter.

var nav = new joint.ui.Navigator({
    paperScroller: paperScroller,
    width: 300,
    height: 200,
    padding: 10,
    zoomOptions: { max: 2, min: 0.2 }
});
nav.$el.appendTo('#navigator');
nav.render();

Configuration

The following table lists options that you can pass to the ui.Navigator constructor function:

API

Events

The joint.ui.Navigator object triggers various events that you can react on:

Paper scroller wraps the paper element and implements scrolling, panning, centering and auto-resizing of the paper content.

Installation

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

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

Create a PaperScroller

PaperScroller creates a window to the paper area. This way, the actual paper can be large but the user will see only the PaperScroller area which he can scroll & pan. First, we create a PaperScroller object. Then we pass the automatically created PaperScroller element as a container for our paper. Once we have our paper object created, we pass it back to the PaperScroller as it needs a reference to the actual paper.

var paper = new joint.dia.Paper({
    width: 2000,
    height: 2000,
    model: graph
});

var paperScroller = new joint.ui.PaperScroller({
    paper: paper
});

$('#paper-container').append(paperScroller.render().el);

The next step is to hook the startPanning method of the paper scroller on the blank:pointerdown paper event which will cause panning whenever the user drags a blank area of the paper:

paper.on('blank:pointerdown', paperScroller.startPanning);

In order to help users understand what action will happen when they drag the paperScroller, use setCursor(cursor) method. It sets the mouse cursor, which is displayed when the mouse pointer is over the PaperScroller. It accepts any valid CSS cursor property value. Alternatively the cursor can be passed to the constructor. It defaults to 'default' (an arrow).

var paperScroller = new joint.ui.PaperScroller({
    paper: paper,
    cursor: 'grab'
});
// Or dynamically change cursor e.g. when user is about to select elements.
paperScroller.setCursor('crosshair');

Scrolling the paper

User scrolling of the paper is allowed by default. Two methods are provided to toggle this functionality:

PaperScroller also provides methods for programmatic scrolling. These methods try scroll the paper so that a specified point on the paper lies at the center of the paper scroller viewport. If this is not possible (e.g. if the requested point lies in a corner of the paper), the paper is scrolled as far as possible without requiring paddings. This means that the requested point will not actually move into the center of the viewport if there is not enough room for it. (Use the center functions to add paddings if necessary and force the requested point to move to the center of paper scroller viewport.)

All scroll methods optionally support animation if an opt.animation object is provided. The object may contain jQuery animation properties, most notably opt.animation.duration - a number specifying the time, in milliseconds, determining how long the animation will run. (Note that animated transitions are better supported with the transition functions.)

paperScroller.scroll(100, 200); // scroll to the point (100,200)
paperScroller.scroll(100); // scroll to the point (100,[y of center of visible area])
paperScroller.scroll(null, 200); // center at the point ([x of center of visible area],200)

paperScroller.scroll(100, 200, { animation: { duration: 400 }});
paperScroller.scroll(100, null, { animation: { duration: 200, easing: 'linear' }});
paperScroller.scroll(null, 200, { animation: { duration: 600 }});

paperScroller.scrollToContent();
paperScroller.scrollToContent({ animation: { duration: 600 }});

paperScroller.scrollToElement(element);
paperScroller.scrollToElement(element, { animation: { duration: 600 }});

The PaperScroller constructor takes an optional parameter scrollWhileDragging. When this parameter is set to true, the PaperScroller automatically scrolls the paper to ensure that the dragged shape stays within the viewport. This scrolling behavior can be adjusted further by providing the following options:

(distance) => ((distance < 20) ? 5 : 20)

Centering and positioning paper content

The center methods are more aggressive than the scroll methods. These methods position the paper so that a specific point on the paper lies at the center of the paper scroller viewport, adding paddings around the paper if necessary (e.g. if the requested point lies in a corner of the paper). This means that the requested point will always move into the center of the viewport. (Use the scroll functions to avoid adding paddings and only scroll the paper scroller viewport as far as the paper boundary.)

The position methods are a more general version of the center methods. They position the paper so that a specific point on the paper lies at requested coordinates inside the paper scroller viewport.

Padding can be added with opt.padding, to offset positioned elements away from the edges of client viewport. This stacks up with the x and y coordinates; it also affects the center calculations. The padding value is normalized using the joint.util.normalizeSides function; either a single number may be passed (e.g. padding: 10 applies padding of 10px to all edges), or an object with numeric properties (e.g. padding: { top: 20, horizontal: 10 } applies padding of 20px to the top edge and 10px to the right and left edges).

paperScroller.center();

paperScroller.center({ padding: { left: 100 }});

paperScroller.center(100, 200); // center at the point (100,200)
paperScroller.center(100); // center at the point (100,[y of center of visible area])
paperScroller.center(null, 200); // center at the point ([x of center of visible area],200)

paperScroller.center(100, 200, { padding: { left: 100 }});
paperScroller.center(100, null, { padding: { left: 100 }});
paperScroller.center(null, 200, { padding: { left: 100 }});

paperScroller.centerContent();
paperScroller.centerContent({ padding: { left: 100 }});

paperScroller.centerElement(element);
paperScroller.centerContent(element, { padding: { left: 100 }});

paperScroller.positionContent('bottom-left');
paperScroller.centerContent('bottom-left', { padding: { horizontal: 20, vertical: 10 }});

paperScroller.positionElement(element, 'right');
paperScroller.centerContent('right', { padding: { right: 50 }});

paperScroller.positionElement(element1.getBBox().union(element2.getBBox()), 'left-top');
paperScroller.centerContent(path.bbox(), 'right-top', { padding: { vertical: 10, right: 50 }});

paperScroller.positionPoint(new g.Point(0,0), 0, 0);
paperScroller.positionPoint(new g.Point(0,0), '-100%', '-100%'); // same result

paperScroller.positionPoint(point, '25%', -40);

paperScroller.positionPoint(point, 10, -10, { padding: { horizontal: 20, vertical: 10 }})

Paper visiblity

ui.PaperScroller provides methods for checking whether elements or points are visible and not scrolled outside the viewport.

// return elements currenly visible in the paperScroller viewport.
var visibleElements = graph.findModelsInArea(paperScroller.getVisibleArea());

// Scroll to an element only if it is not completely in the viewport.
if (!paperScroller.isElementVisible(rect, { strict: true })) {
    paperScroller.scrollToElement(rect);
}

Zooming the paper

The PaperScroller exposes an API to scale the contained paper more easily:

paperScroller.zoom();

Return the current zoom level of the paper. Technically speaking, the zoom level is the scaling factor (sx) of the paper's SVGElement.

paperScroller.zoom(value [, opt]);

The zoom() method accepts a value by which we want to increase/decrease the scaling factor of the paper. A positive value increases the scaling factor, which causes the paper to be zoomed in. A negative value decreases the scaling factor, which causes the paper to be zoomed out.

You can pass two options to cap the range of possible scaling factors as part of an opt object - min and max. The scaling factor cannot then be decreased below min (if provided) or increased above max (if provided). These options are often useful in practice, with UI buttons bound to the paperScroller's zooming operations:

$('#zoom-in').on('click', function() {
   paperScroller.zoom(0.2, { max: 4 });
});

$('#zoom-out').on('click', function() {
   paperScroller.zoom(-0.2, { min: 0.2 });
});

Additionally, passing a value for the grid option causes the resulting scaling factor to be rounded to the closest multiple of the grid value.

Passing absolute: true as an option sets the scaling factor directly to the provided value (instead of treating it as a relative value). The constraints imposed by the min, max, and grid are still in effect, however.

paperScroller.zoomToFit([opt]);

Scale the paper so that all of the contents of its graph fit into the user's viewport. For a list of available options, refer to paper.scaleContentToFit() documentation.

paperScroller.zoomToRect(rect [, opt]);

Zoom and reposition the paper so that the area defined by rect (in the paper local coordinates) fits into the user's viewport. For a list of available options, refer to paper.scaleContentToFit() documentation.

Animated transitions

The paperScroller provides few methods for panning and zooming in animated fashion. These are:

paperScroller.transitionToPoint(x, y [, opt])
paperScroller.transitionToPoint(point [, opt])

The method pans and optionally zooms the paperScroller to a given point. It accepts a point defined in the paper local coordinate system and an option object with several properties to control the transition.

// Move paper point (x=100, y=100) to the center of the viewport.
paperScroller.transitionToPoint(100, 100);
// Move and scale paper, so the point { x: 100, y: 100 } will appear in the center of the viewport.
paperScroller.transitionToPoint(100, 100, { scale: 2 });
// Move the the center of the `element` to the center of the viewport.
paperScroller.transitionToPoint(element.getBBox().center(), {
    duration: '500ms',
    onTransitionEnd: function(transitionEvent) {
      // do something when the animation ends
    }
});

paperScroller.transitionToRect(rect [, opt]);

The method pans and zooms the paperScroller over a specific period so the given rectangular area is at the end of the transition entirely visible in the viewport. The rectangular area is an object with x, y, width and height properties and defined in the paper local coordinate system. The method accepts all options from transitionToPoint() (but scale) and the following options from the table below.

// Zoom the paperScroller so the given area covers 90% of the viewport.
// Also do not let the paperScroller exceed the zoom level 3.
paperScroller.transitionToRect({
  x: 100,
  y: 100
  width: 200,
  height: 200
}, {
    visibility: 0.9,
    maxScale: 3,
    onTransitionEnd: function(transitionEvent) {
      // do something when the animation ends
    }
});
// Zoom the paperScroller in a way the elements `el1`, `el2`, `el3` cover the entire viewport
// and the center of the `el1` moves to the center of the viewport.
var rect = graph.getCellsBBox([el1, el2, el3]);
paperScroller.transitionToRect(rect, {
    duration: '500ms',
    center: el1.getBBox().center()
});

paperScroller.removeTransition();

When method called, the ongoing (if any) paperScroller transition is removed and the associated onTransitionEnd callback is not fired.

Paper auto-resize/shrink

The PaperScroller constructor takes an optional parameter autoResizePaper. When this parameter is set to true, the PaperScroller automatically resizes the paper so that it fits the content inside it. This makes it possible to have a fixed (even smaller) size of the paper and when the user drags an element outside this area, the PaperScroller extends this paper in order to accommodate for the new element. By default, the ui.PaperScroller resizes the paper by the paper width/height. If you want the paper to extend by a different amount, pass the baseWidth/baseHeight options to the ui.PaperScroller constructor function. The paper adjustment is internally handled by calculating proper parameters for the joint.dia.Paper:fitToContent method. You can further adjust the behavior by setting the contentOptions object to the ui.PaperScroller constructor function. This object can contain additional parameters that will be mixed with the calculated ones before calling the joint.dia.Paper:fitToContent method. This is handy if you, for example, want to set the maximum width and height of the paper. In this case, you can just set contentOptions: { maxWidth: 3000, maxHeight: 3000 } to the ui.PaperScroller constructor function. contentOptions can be also defined as a function returning the options.

new joint.ui.PaperScroller({
  padding: 0,
  contentOptions: function(paperScroller) {
    var visibleArea = paperScroller.getVisibleArea();
    return {
        padding: {
            bottom: visibleArea.height / 2,
            top: visibleArea.height / 2,
            left: visibleArea.width / 2,
            right: visibleArea.width / 2
        },
        allowNewOrigin: 'any'
    };
  }
});

Try how this works in the following demo by zooming the paper out so that you see its borders and move your element outside the paper area. You should see how the paper gets automatically resized. When you drag the element back to its original location, the PaperScroller resizes the paper back to its original size.

var paperScroller = new joint.ui.PaperScroller({ autoResizePaper: true });

Events

The plugin fires the following events.

paperScroller.on('scroll', function(evt) {
  console.log('The visible area has been changed:', this.getVisibleArea());
});