README.md

Plugins 🔌

Plugins allow you to change the appearance and behavior of the Camunda Modeler and add new features.

Camunda Modeler Plugins

Using the Camunda Modeler with a Plugin

Plugging into the Camunda Modeler

You can plug into the modeler in order to change its appearance, add new menu entries or extend the modeling tools for BPMN, CMMN and DMN. Adding a plugin is as easy as putting the files into the directory {MODELER_LOCATION}/plugins. On macOS, the application searches for plugins in the directory /Users/{USER_NAME}/Library/Application Support/camunda-modeler/plugins.

So let's dive into how to add your own plugins.

Regardless of the type of your plugin you have to export it as a Node.js module. In order for the modeler to recognize your plugin the filename must be index.js.

Example:

module.exports = {
  name: 'My Awesome Plugin', // the name of your plugin
  style: './style.css', // changing the appearance of the modeler
  menu: './menu.js', // adding menu entries to the modeler
  script: './script.js' // extend the modeling tools for BPMN, CMMN and DMN
};

The modeler will automatically load your plugins on startup.

Changing the appearance of the modeler

You can change the appearance of the modeler using CSS.

Your stylesheet might look like this:

body {
  background: linear-gradient(0deg, #52b415, #eee);
}

Plug it into the modeler like this:

module.exports = {
  style: './style.css'
};

Adding menu entries to the modeler

You can add new menu entries to the modelers menu.

Describe your menu entries like this:

module.exports = function(electronApp, menuState) {
  return [{
    label: 'Open BPMN Reference',
    accelerator: 'CommandOrControl+[',
    enabled: function() {

      // only enabled for BPMN diagrams
      return menuState.bpmn;
    },
    action: function() {
      var shell = require('electron').shell;
      shell.openExternal('https://camunda.org/bpmn/reference/');
    }
  }];
});

Plug them into the modeler like this:

module.exports = {
  menu: './menu-entries'
};

You can use a Node.js module here since the modeler is built with Electron which uses Node.js.

For more information on how the modelers menu works have a look at its implementation here.

Extend the modeling tools for BPMN, CMMN and DMN

Currently you can only extend bpmn-js

You can extend the modeling tools for BPMN, CMMN and DMN with your own modules.

Since the client of the modeler uses Chromium you can't use Node.js modules to extend the modeling tools. You need to bundle your plugin first. The easiest way to get started with client-side plugins is through this example project.

First, clone the repository:

git clone https://github.com/camunda/camunda-modeler-plugin-example.git

Next, install the dependencies:

npm install

Now, create your module:

function LoggingPlugin(eventBus) {
  eventBus.on('shape.added', function() {
    console.log('A shape was added to the diagram!');
  });
}

module.exports = {
  __init__: [ 'loggingPlugin' ],
  loggingPlugin: [ 'type', LoggingPlugin ]
};

Make sure to require your file in client.js:

var registerBpmnJSPlugin = require('camunda-modeler-plugin-helpers').registerBpmnJSPlugin;
var plugin = require('./LoggingPlugin');

registerBpmnJSPlugin(plugin);

You can use the globally available functions getModelerDirectory and getPluginsDirectory to load additional resources:

function LoggingPlugin(eventBus, canvas) {
  var img = document.createElement(img);
  img.src = getPluginsDirectory + '/logging-plugin/image.png';

  canvas.getContainer().appendChild(img);
}

Bundle your plugin:

npm run build

Finally, put the folder into the plugins directory relative to your Camunda Modeler installation directory. You can now use your plugin!

Development Workflow

When creating a plugin you can place the directory containing your plugin in the aforementioned plugins directory.

Plugins will be loaded on application startup (menu plugins) or reload (style and modeling tool plugins). To reload the application, open the developer tools F12 and press CtrlOrCmd+R. This will clear all unsaved diagrams!

Additional Resources