Skip to main content

Element tools

JointJS allows creating fully customizable. These tools show up on user interaction (e.g. mouseover) with an element view and allow the user to interact with the underlying element model. For example:

Open on CodeSandboxOpen Sandbox

The process of getting element tools up and running on your element view is relatively straightforward:

We will explain every step in turn. In this section we will also touch on creating custom buttons.

Create a tool​

An element tool (type dia.ToolView) is a view that renders a certain type of control elements on top of the element view it is attached to; for example the Boundary tool renders an outline around the bounding box of the element.

The JointJS library comes with a collection of pre-made element tool definitions in the elementTools namespace. The pre-made element tools include several common tools such as button, control, etc.

To create a new element tool, we call its constructor:

import { elementTools } from '@joint/core';

const boundaryTool = new elementTools.Boundary();

The element tool constructors also accept optional arguments that modify the appearance and function of the created tools:

import { elementTools } from '@joint/core';

const boundaryTool = new elementTools.Boundary({
    padding: 20,
    rotate: true,
    useModelGeometry: true,
});

Add to tools view​

Element tools always need to come bundled in a tools view object (type dia.ToolsView). This allows them to be shown/hidden as a group above an element. We create a new tools view and add our tools to it:

import { dia, elementTools } from '@joint/core';

const boundaryTool = new joint.elementTools.Boundary();
const removeButton = new joint.elementTools.Remove();

const toolsView = new joint.dia.ToolsView({
    tools: [
        boundaryTool,
        removeButton
    ]
});

Remember, it is necessary to create a new set of tools for every new tools view object we create; tools are automatically reassigned to the last tools view that uses them.

Add to element view​

Finally, we need to add our tools view to an element view. The dia.ElementView class comes with a suite of tools-related methods:

We can thus show all of our tools in one place:

Open on CodeSandboxOpen Sandbox

const elementView = element.findView(paper);
elementView.addTools(toolsView);

Remember, it is necessary to create a new tools view object for every element view; tools view objects are automatically reassigned to the last element view that uses them.

Interaction​

You can easily toggle visibility of element tools using the 'element:mouseenter'/'element:mouseleave' Paper events:

Open on CodeSandboxOpen Sandbox

paper.on('element:mouseenter', elementView => {
    elementView.showTools();
});

paper.on('element:mouseleave', elementView => {
    elementView.hideTools();
});

More complex interaction scenarios might require showing, hiding or removing all tools at once. You can find relevant functions in the Paper class:

Note that our example toggles visibility of element tools by using the showTools()/hideTools() functions. Element tools may also be toggled by addTools()/removeTools() functions, which are demonstrated in the link tools section. For element tools, there is no practical difference between the two approaches.

Custom buttons​

It is possible to create custom buttons to complement the built-in Remove button tool; JointJS exposes the elementTools.Button class for you to extend. The markup of the new button can be sent as options.markup, while the behavior of the button on pointerdown interaction is determined by the callback function provided in options.action.

Open on CodeSandboxOpen Sandbox

You can add the extended button to the elementTools namespace and then just use that class in the code:

import { dia, elementTools } from '@joint/core';

elementTools.InfoButton = elementTools.Button.extend({
    name: 'info-button',
    options: {
        markup: [{
            tagName: 'circle',
            selector: 'button',
            attributes: {
                'r': 7,
                'fill': '#001DFF',
                'cursor': 'pointer'
            }
        }, {
            tagName: 'path',
            selector: 'icon',
            attributes: {
                'd': 'M -2 4 2 4 M 0 3 0 0 M -2 -1 1 -1 M -1 -4 1 -4',
                'fill': 'none',
                'stroke': '#FFFFFF',
                'stroke-width': 2,
                'pointer-events': 'none'
            }
        }],
        x: '100%',
        y: '100%'
        offset: {
            x: 0,
            y: 0
        },
        rotate: true,
        action: function(evt) {
            alert('View id: ' + this.id + '\n' + 'Model id: ' + this.model.id);
        }
    }
});

const infoButton = new elementTools.InfoButton();
const toolsView = new dia.ToolsView({
    tools: [infoButton]
});

const elementView = element.findView(paper);
elementView.addTools(toolsView);

A single-use custom button can also be created by direct reference to the Button class, without making an entry in the elementTools namespace:

import { dia, elementTools } from '@joint/core';

const infoButton = new elementTools.Button({
    markup: [{
        tagName: 'circle',
        selector: 'button',
        attributes: {
            'r': 7,
            'fill': '#001DFF',
            'cursor': 'pointer'
        }
    }, {
        tagName: 'path',
        selector: 'icon',
        attributes: {
            'd': 'M -2 4 2 4 M 0 3 0 0 M -2 -1 1 -1 M -1 -4 1 -4',
            'fill': 'none',
            'stroke': '#FFFFFF',
            'stroke-width': 2,
            'pointer-events': 'none'
        }
    }],
    x: '100%',
    y: '100%',
    offset: {
        x: 0,
        y: 0
    },
    rotate: true,
    action: function(evt) {
        alert('View id: ' + this.id + '\n' + 'Model id: ' + this.model.id);
    }
});

const toolsView = new dia.ToolsView({
    tools: [infoButton]
});

const elementView = element.findView(paper);
elementView.addTools(toolsView);

Stay in the know

Be where thousands of diagramming enthusiasts meet

Star us on GitHub