JointJS+ Stencil

Stencil plugin implements a palette of JointJS elements. These elements can be dragged onto a paper.

Installation

Include joint.ui.stencil.js and joint.ui.stencil.css to your HTML:

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

Creating a stencil

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

var stencil = new joint.ui.Stencil({
    paper: paper,
    width: 200,
    height: 300
});

$('#stencil-holder').append(stencil.render().el);

The joint.ui.Stencil constructor takes a paper object and the dimensions of the stencil area. The next thing to do is rendering the stencil widget (stencil.render()) and appending the stencil element to a holder which can be any element in your HTML. Please see the demo for reference on how to do that if you're in doubts.

Stencil Configuration

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

search: {
    '*': ['attrs/text/text'],
    'standard.Image': ['description'],
    'standard.Path': ['description']
}

search: function(cell, keyword, group, stencil) {
    var description = cell.get('description');
    return typeof description === 'string' && description.indexOf(keyword) > -1;
}

groups: {
    basic: { label: 'Basic Elements', index: 1 },
    text: { label: 'Text', index: 2, closed: true },
    advanced: { label: 'Advanced Elements', index: 3, closed: true }
}

dropAnimation: {
    duration: 300,
    easing: 'linear'
}

layout: {
    columnWidth: 100,
    columns: 3,
    rowHeight: 100,
}

layout: function(graph, group) {
    const groupName = graph.get('group');
    if (groupName === 'my-group-1') {
        // layout the elements in this group only
        graph.getElements().forEach(function(el, index) {
            el.position(0, index * 100);
        });
    }
});

paperOptions: {
  elementView: CustomElementView,
  background: { color: 'red' }
}

groups: {
  myGroup: {
    index: 1,
    label: 'My Group',
    paperOptions: { color: 'blue' }
  }
}

paperOptions: function() {
  return {
    elementView: CustomElementView,
    model: new joint.dia.Graph([], { cellNamespace: CustomElementNamespace }),
    background: { color: 'red' }
  }
}

Populating Stencil with elements

const r = new joint.shapes.standard.Rectangle({
    position: { x: 10, y: 10 }, size: { width: 50, height: 30 }
});
const c = new joint.shapes.standard.Circle({
    position: { x: 70, y: 10 }, size: { width: 50, height: 30 }
});

// Stencil is rendered in the DOM now.

// load the elements into the default group
stencil.load([r, c]);

// load the elements into multiple groups
stencil.load({ group1: [r], group2: [c] });

// load the elements into the `group2` group
stencil.loadGroup([r, c], 'group2');

As you can see, there is multiple way how to populate the stencil with elements. Use either stencil.load() or stencil.loadGroup() which make sure the elements are rendered into the stencil.

Note: Populating the stencil with elements needs to be done after the stencil is rendered in the DOM.

Stencil groups (a.k.a. Accordion)

Creating an accordion-like Stencil is as easy as passing the groups object to the stencil constructor. groups object is a hash table mapping group identifiers to the configuration of the particular group. Each group configuration object contains these properties:

const stencil = new joint.ui.Stencil({
     graph: graph,
     paper: paper,
     width: 200,
     groups: {
          one: { label: 'First group', index: 1 },
          two: { label: 'Second group', index: 2, closed: true }
     }
  });

Searchable Stencil

The Stencil allows users to filter the elements by an arbitrary keyword. That is useful especially when the palette contains a lot of elements. To enable this add search: { /* rules */ } option to the Stencil constructor.

The rules determine what attributes we match a given keyword with and are defined by an object with ELEMENT_TYPE: [ATTRIBUTE_PATH1, ATTRIBUTE_PATH2, ..] key-value pairs. Where ELEMENT_TYPE is either an element type (e.g standard.Rectangle) or '*' to match any type. ATTRIBUTE_PATH is a path to element's attribute or property (e.g 'attrs/text/text', 'description').

const stencil = new joint.ui.Stencil({
  search: {
    '*': ['attrs/text/text'],
    'standard.Image': ['description'],
    'standard.Path': ['description']
  }
});

The rules can be alternatively defined as a function, which, upon search, will be invoked for each element with the element model, string keyword, the group id the element belongs to, and the stencil instance as its arguments.

const stencil = new joint.ui.Stencil({
  search: function(element, keyword, groupId, stencil) {
    return element.get('type').includes(keyword) || groupId.includes(keyword);
  }
});

By default all the unmatched elements and groups are hidden (display: none; is set on them). Alternatively you can add .joint-stencil .joint-element.unmatched { display: block; } and .joint-stencil .group.unmatched { display: block } rules to your css stylesheet in order to have the unmatched elements translucent.

Here's a list of all CSS classes toggled by filtering.

The Stencil triggers the 'filter' event with a matched subset of elements wrapped in joint.dia.Graph as the first argument every time the elements get filtered.

The default text of the Stencil can be modified as shown below.

// No Matches Found
stencil.el.dataset.textNoMatchesFound = 'No matches found!';
// Search Placeholder
stencil.el.querySelector('.search').placeholder = 'My Placeholder';

API

stencil.load({
    group1: [{ type: 'standard.Rectangle' },{ type: 'standard.Circle' }],
    group2: [{ type: 'standard.Image' }]
});

<ul>
    <li data-type="element">Element</li>
    <li data-type="link">Link</li>
</ul>

const stencil = new ui.Stencil({ paper });

const listEl = document.querySelector('ul');
listEl.addEventListener('pointerdown', (evt) => {
    const { type } = evt.target.dataset;
    let cell;
    switch (type) {
        case 'element':
            cell = new shapes.standard.Rectangle({
                size: { width: 100, height: 100 }
            });
            break;
        case 'link':
            cell = new shapes.standard.Link({
                source: { x: 0, y: 0 },
                target: { x: 100, y: 100 }
            });
            break;
        default:
            throw new Error(`Unknown type: ${type}`);
    }
    stencil.startDragging(cell, evt);
});

Reacting on elements added to the paper

Many times, you might want to perform some action as a reaction on a new element dragged from the stencil to the paper. This can be achieved by usual means, i.e. by reacting on new elements added to the graph:

graph.on('add', function(cell, collection, opt) {
      // The stencil adds the `stencil` property to the option object with value
      // set to a client id (`cid`) of the stencil view.
      if (opt.stencil) {
          console.log('A cell with id', cell.id, 'was just added to the paper from the stencil.');
      }
  });

Events

The Stencil object triggers events that you can react on in your applications. These events can be handled by using the Stencil on(eventName, handler) method.

cloneView: dia.ElementView,
evt: dia.Event,
dropArea: g.Rect,
validDropTarget: boolean

cloneView: dia.ElementView,
evt: dia.Event,
dropArea: g.Rect,
validDropTarget: boolean

stencil.on('element:drag', (cloneView, evt, dropArea, validDropTarget) => {
  cloneView.vel.attr('opacity', validDropTarget ? 1 : 0.3);
});

cloneView: dia.ElementView,
evt: dia.Event,
dropArea: g.Rect,
validDropTarget: boolean

elementView: dia.ElementView,
evt: dia.Event,
x: number,
y: number

stencil.on('element:drop', (elementView) => {
  const halo = new joint.ui.Halo({ cellView: elementView });
  halo.render();
});

evt: dia.Event,
element: dia.Element

graph: dia.Graph,
groupName: string,
keyword: string

groupName: string

groupName: string