bpmn-js Properties Panel

To contribute to or develop the library locally, follow these steps:

1. Install dependencies: npm install
2. Run the desired command:
   • npm run all: Build the library and run all tests.
   • npm start: Spin up a single local modeler instance.
   • npm run dev: Run the full development setup.

npm install

# 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

For the properties panel to render correctly, you must include its CSS stylesheet in your application. You can load it via unpkg:

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

To use the properties panel, you must provide two HTML elements: one for the BPMN diagram canvas and one for the properties panel container. You then bootstrap bpmn-js (specifically BpmnModeler) by passing the propertiesPanel.parent configuration and including the required modules in additionalModules.

Required HTML structure:

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

```javascript
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
  ]
});
```},{

The getEntryId(element, path) method resolves the unique ID of the UI entry that edits a specific moddle property path. This is useful for identifying which specific input field corresponds to a deep path in the element's business object.

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

const entryId = propertiesPanel.getEntryId(element, [
  'extensionElements', 'values', 0, 'inputParameters', 1, 'source'
]);
// returns something like 'ServiceTask_1-input-1-source'

To add custom property groups or modify existing ones, implement a PropertiesProvider and register it using registerProvider(priority, provider).

Providers are asked in reverse render order based on their priority. A provider with a lower priority (e.g., a higher number) will be asked first if it intends to override others.

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

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

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

      return groups;
    };
  }
}

ExamplePropertiesProvider.$inject = [ 'propertiesPanel' ];

You can manipulate the properties panel's location at runtime by retrieving it from the modeler instance using modeler.get('propertiesPanel').

• Use .detach() to remove the panel from the DOM.
• Use .attachTo(container) to attach it to a new element.
• Use .attachTo(container, headerContainer) to separate the panel body and the header into different containers.

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

// detach the panel
propertiesPanel.detach();

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

// or attach the panel body and header to different containers
propertiesPanel.attachTo('#properties', '#panel-header');

Setting the SINGLE_START environment variable modifies the Karma configuration to facilitate debugging. It appends the Debug browser to the existing browser list and adds SINGLE_START to the environment preprocessor.

# Example: Run tests in debug mode
SINGLE_START=true npm test

To generate code coverage reports during testing, set the COVERAGE environment variable. This triggers the following behaviors:

• Uses test/coverageBundle.js as the test suite instead of test/testBundle.js.
• Adds the coverage reporter to Karma.
• Configures the coverageReporter to output lcov reports in the current directory.
• Injects the istanbul plugin via Babel to instrument the code (excluding files in test/**/*).

# Example: Run tests with coverage
COVERAGE=true npm test

When running tests, you can specify which browsers to use by setting the TEST_BROWSERS environment variable. The value should be a comma-separated list of browser names. Supported browsers include:

• ChromeHeadless (default)
• Chrome
• Firefox
• IE
• PhantomJS
• Debug (added if SINGLE_START is set)

# Example: Run tests in Chrome and Firefox
TEST_BROWSERS=Chrome,Firefox npm test