🎉 JointJS has new documentation! ðŸ¥³

JointJS+ bpmn

shapes.bpmn

The BPMN plugin provides you with set of Business Process Model and Notation 2.0 shapes. They are designed to be easily configurable with the ui.Inspector plugin.

The plugin consists of flow objects (Activities, Events, Gateways), connection objects (Flows), swim lanes (Pools) and artifacts (DataObjects, Groups, Annotation). It also covers models introduced in version 2.0 as Conversations, Choreographies and Messages.

Install

Include joint.shapes.bpmn.js file to your HTML:

<script src="joint.shapes.bpmn.js"></script>

joint.shapes.bpmn.Activity

The Activity attributes:

activityType Changes the type of the shape.
'task' | 'transaction' | 'event-sub-process' | 'call-activity'
content A text inside the element (i.e 'My Content').
icon An icon name (list of icons).
subProcess Any truthy value makes the sub-process icon visible (sub-process handling).
attrs Allows to apply custom SVG attributes (fill, stroke, opacity, etc.)
'.body' (rect), '.label' (text)

Usage:

var activity = new joint.shapes.bpmn.Activity({
    attrs: {
        '.body': { fill: 'gold', stroke: 'black' },
        '.label': { text: 'My Activity' }
    },
    content: 'A content of the Activity',
    activityType: 'transaction'
});

joint.shapes.bpmn.Annotation

The Annotation attributes:

content A text inside the element (i.e 'My Content').
attrs Allows to apply custom SVG attributes (fill, stroke, opacity, etc.)
'.body' (rect), '.stroke' (path)

Usage:

var annotation = new joint.shapes.bpmn.Annotation({
    attrs: {
        '.body': { fill: 'gold' },
        '.stroke': { stroke: 'silver' }
    },
    content: 'A content of the Annotation'
});

joint.shapes.bpmn.Choreography

The Choreography attributes:

content A text inside the element (i.e 'My Content').
initiatingParticipant An index or name of the participant (case-sensitive). ( i.e 'participant 1' )
participants An array of participant names ( i.e ['participant 1','participant 2'] ).
subProcess Any truthy value makes the sub-process icon visible (sub-process handling).
attrs Allows to apply custom SVG attributes (fill, stroke, opacity, etc.)
'.body' (rect), '.label' (text), '.participant-rect' (rect), '.participant-label' (text)

Usage:

var choreography = new joint.shapes.bpmn.Choreography({
    attrs: {
        '.body': { fill: 'gold', stroke: 'black' },
        '.label': { fill: 'gray', text: 'My Choreography' },
        '.participant-rect': { fill: 'silver' }
    },
    participants: ['partic1', 'partic2', 'partic3'],
    initiatingParticipant: 2, // ='partic3',
    content: 'A content of the Choreography'
});

joint.shapes.bpmn.Conversation

The Conversation attributes:

conversationType Changes the type of the shape.
'conversation' | 'call-conversation'
attrs Allows to apply custom SVG attributes (fill, stroke, opacity, etc.)
'.body' (rect), '.label' (text)

Usage:

var conversation = new joint.shapes.bpmn.Conversation({
    attrs: {
        '.body': { fill: 'gold', stroke: 'black' },
        '.label': { fill: 'gray', text: 'My Conversation' }
    },
    conversationType: 'call-conversation'
});

joint.shapes.bpmn.DataObject

The Data Object attributes:

attrs Allows to apply custom SVG attributes (fill, stroke, opacity, etc.)
'.body' (rect), '.label' (text)

Usage:

var dataObject = new joint.shapes.bpmn.DataObject({
    attrs: {
        '.body': { fill: 'gold', stroke: 'black' },
        '.label': { fill: 'gray', text: 'My Data Object' }
    }
});

joint.shapes.bpmn.Event

The Event attributes:

eventType Changes the type of the shape.
'start' | 'end' | 'intermediate'
icon An icon name (list of icons).
attrs Allows to apply custom SVG attributes (fill, stroke, opacity, etc.)
'.body' (circle), '.label' (text)

Usage:

var event = new joint.shapes.bpmn.Event({
    attrs: {
        '.body': { fill: 'gold', stroke: 'black' },
        '.label': { fill: 'gray', text: 'My Event' }
    },
    icon: 'message',
    eventType: 'end'
});

joint.shapes.bpmn.Flow

The Flow as the only one inherits from joint.dia.Link.

The Annotation attributes:

flowType Changes the type of the link.
'default' | 'conditional' | 'normal' | 'association' | 'conversation' | 'message'

Usage:

var flow = new joint.shapes.bpmn.Flow({
    source: { id: task.id },
    target: { id: annotation.id },
    flowType: 'association'
});

joint.shapes.bpmn.Gateway

The Gateway attributes:

icon An icon name (list of icons).
attrs Allows to apply custom SVG attributes (fill, stroke, opacity, etc.)
'.body' (polygon), '.label' (text)

Usage:

var gateway = new joint.shapes.bpmn.Gateway({
    attrs: {
        '.body': { fill: 'gold', stroke: 'black' },
        '.label': { fill: 'gray', text: 'My Gateway' }
    },
    icon: 'cross'
});

joint.shapes.bpmn.Group

The Group attributes:

attrs Allows to apply custom SVG attributes (fill, stroke, opacity, etc.)
'.body', '.label', '.label-rect'

Usage:

var group = new joint.shapes.bpmn.Group({
    attrs: {
        '.label-rect': { fill: 'gold', stroke: 'black' },
        '.label': { fill: 'gray' }
    }
});

joint.shapes.bpmn.Message

The Message attributes:

attrs '.body' (polygon), '.label' (text)

Usage:

var message = new joint.shapes.bpmn.Message({
    attrs: {
        '.body': { fill:'gold', stroke: 'black' },
        '.label': { fill: 'gray' }
    }
});

joint.shapes.bpmn.Pool

The Pool attributes:

lanes An object consist of a label, headerWidth (optional, defaults to 20) and an array of sublanes (optional).
A sublane is an object consist of a label, a name (optional), headerWidth (optional), ratio (number <0-1>, optional) and an array of sublanes (optional).
attrs Allows to apply custom SVG attributes (fill, stroke, opacity, etc.)
'.body' (rect), '.header' (rect), '.lane-body' (rect), '.lane-header' (rect), '.blackbox-label' (text)

Usage:

var pool = new joint.shapes.bpmn.Pool({
    attrs: {
        '.header': { fill:'gold' },
        '.lane-header': { fill:'silver' },
        '.myClass .lane-body': { fill: 'goldenrod' } // customize a specific lane body color
    },
    lanes: {
        label: 'My Pool',
        sublanes: [
            {
                label: 'lane 1',
                name: 'myClass', // this lane has an unique css class and therefore can be targeted
                                 // in attrs above
                ratio: 0.6 // this lane will take up 60% of width of the parent lane
                           // the other lanes (in this case `lane 2`) will take up the rest i.e. 40%
            },
            {
                label: 'lane 2',
                headerWidth: 40, // sets the header size for `lane2` to 40px
                sublanes: [] // it may consist of another sublanes
            }
        ]
    }
});

Each rendered lane DOM element has class name lane and attribute data-lane-path, that references corresponding lane configuration inside the model's lanes attribute. e.g. data-lane-path="lanes/sublanes/1" for the `lane 2` in the example above. It's useful when one needs to know, what lane a user just clicked on.

paper.on('element:pointerup', function(elementView, evt) {
    var pool = elementView.model;
    if (pool.get('type') === 'bpmn.Pool') {
       var lanePath = $(evt.target).closest('.lane').data('lane-path') || 'lanes';
       console.log(pool.prop(lanePath + '/label')); // log the lane label
    }
});

joint.shapes.bpmn.icons

The joint.shapes.bpmn.icons namespace includes several icons that can be used within the shapes.

none No image.
message
user
plus
cross
circle
service

Usage:

gateway.set('icon', 'circle');
var task = new joint.shapes.bpmn.Activity({ icon: 'user' });

Adding custom icons can be made by inserting them into the joint.shapes.bpmn.icons namespace.

joint.shapes.bpmn.icons['myIcon'] = 'pathToImage'; // or data URI

// later on in the code
gateway.set('icon', 'myIcon');

Sub-process handling

The subProcess value is stored as a data attribute on the sub-process icon (SVG path) element. An interaction with the sub-process icon can be therefore caught and handled on the joint.dia.Paper. In the example bellow the model's subProcess value is shown after an user doubleclicks the icon.

conversation.set('subProcess', 'My sub-process ID');

paper.on('cell:pointerdblclick', function(cellView, evt) {

    var subProcess = $(evt.target).data('sub-process');

    if (subProcess) {
        alert(subProcess);
    }
});

// a doubleclick on conversation's sub-process icon will alert 'My sub-process ID'