/bpmn-js-properties-panel

A properties panel for bpmn-js.

Primary LanguageJavaScriptMIT LicenseMIT

Extending the properties panel changed significantly with bpmn-js-properties-panel>=1. For the 0.x version of the library, check out the 0.x branch. Read more on the changes in the changelog.

bpmn-js-properties-panel

CI

A properties panel extension for bpmn-js that adds the ability to edit technical properties (generic and Camunda).

bpmn-js-properties-panel screenshot

Features

The properties panel allows users to edit invisible BPMN properties in a convenient way.

Some of the features are:

  • Edit element ids, multi-instance details and more
  • Edit execution related Camunda properties
  • Redo and undo (plugs into the bpmn-js editing cycle)

Usage

Provide two HTML elements, one for the properties panel and one for the BPMN diagram:

<div class="modeler">
  <div id="canvas"></div>
  <div id="properties"></div>
</div>

Bootstrap bpmn-js with the properties panel and a properties provider:

import BpmnModeler from 'bpmn-js/lib/Modeler';
import {
  BpmnPropertiesPanelModule,
  BpmnPropertiesProviderModule,
} from 'bpmn-js-properties-panel';

const modeler = new BpmnModeler({
  container: '#canvas',
  propertiesPanel: {
    parent: '#properties'
  },
  additionalModules: [
    BpmnPropertiesPanelModule,
    BpmnPropertiesProviderModule
  ]
});

Styling

For proper styling include the necessary stylesheets:

<link rel="stylesheet" href="https://unpkg.com/bpmn-js-properties-panel/dist/assets/properties-panel.css">

If you use the ElementTemplatesProviderModule, include also its stylesheet:

<link rel="stylesheet" href="https://unpkg.com/bpmn-js-properties-panel/dist/assets/element-templates.css">

Dynamic Attach/Detach

You may attach or detach the properties panel dynamically to any element on the page, too:

const propertiesPanel = bpmnJS.get('propertiesPanel');

// detach the panel
propertiesPanel.detach();

// attach it to some other element
propertiesPanel.attachTo('#other-properties');

Use with Camunda properties

In order to be able to edit Camunda related properties, use the camunda platform properties provider. In addition, you need to define the camunda namespace via camunda-bpmn-moddle.

import BpmnModeler from 'bpmn-js/lib/Modeler';
import {
  BpmnPropertiesPanelModule,
  BpmnPropertiesProviderModule,
  
  // use Camunda Platform properties provider
  CamundaPlatformPropertiesProviderModule
} from 'bpmn-js-properties-panel';

// use Camunda BPMN Moddle extension
import CamundaExtensionModule from 'camunda-bpmn-moddle/lib';

// use Camunda BPMN namespace
import camundaModdleDescriptors from 'camunda-bpmn-moddle/resources/camunda';

const modeler = new BpmnModeler({
  container: '#canvas',
  propertiesPanel: {
    parent: '#properties'
  },
  additionalModules: [
    BpmnPropertiesPanelModule,
    BpmnPropertiesProviderModule,
    CamundaPlatformPropertiesProviderModule,
    CamundaExtensionModule
  ],
  moddleExtensions: {
    camunda: camundaModdleDescriptors
  }
});
...

API

BpmnPropertiesPanelRenderer#attachTo(container: HTMLElement) => void

Attach the properties panel to a parent node.

const propertiesPanel = modeler.get('propertiesPanel');

propertiesPanel.attachTo('#other-properties');

BpmnPropertiesPanelRenderer#detach() => void

Detach the properties panel from its parent node.

const propertiesPanel = modeler.get('propertiesPanel');

propertiesPanel.detach();

BpmnPropertiesPanelRenderer#registerProvider(priority: Number, provider: PropertiesProvider) => void

Register a new properties provider to the properties panel.

class ExamplePropertiesProvider {
  constructor(propertiesPanel) {
    propertiesPanel.registerProvider(500, this);
  }

  getGroups(element) {
    return (groups) => {

      // add, modify or remove groups
      // ...

      return groups;
    };
  }
}

ExamplePropertiesProvider.$inject = [ 'propertiesPanel' ];

Additional Resources

Development

Prepare the project by installing all dependencies:

npm install

Then, depending on your use-case, you may run any of the following commands:

# build the library and run all tests
npm run all

# spin up a single local modeler instance
npm start

# run the full development setup
npm run dev

License

MIT