bpmn-js

You can automate the entire development environment setup using the provided scripts. This is the fastest method if you have git, NodeJS, and npm ready.

• Linux / OS X: Use ./setup.sh
• Windows: Use setup.bat

To set up a local development environment for bpmn-js that allows for immediate cross-project changes, follow these steps:

1. Prerequisites: Ensure git, NodeJS, and npm are installed.
2. Clone Repositories: Clone bpmn-js, diagram-js, and bpmn-moddle into a common directory.
3. Link Projects: Link the dependent projects so bpmn-js uses your local versions of diagram-js and bpmn-moddle instead of npm versions.
   • OS X / Linux: Use npm link or ln -s <target> <link>.
   • Windows: Use mklink /d <link> <target>.
4. Install Dependencies: Run npm install in each project directory.
5. Verify: Run npm run all in each project to ensure everything is working correctly.

To set up the development environment, first install all dependencies using npm install.

Depending on your goal, use one of the following commands:

• npm run all: Builds the library and runs all tests.
• npm start: Spins up a single local modeler instance.
• npm run dev: Runs 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

To render a BPMN 2.0 diagram, create a new BpmnJS instance by providing a container (the ID of a DOM element or the element itself). Use the importXML method to load the XML content. The importXML method returns an object containing warnings and is asynchronous.

const xml = '...'; // my BPMN 2.0 xml
const viewer = new BpmnJS({
  container: 'body'
});

try {
  const { warnings } = await viewer.importXML(xml);

  console.log('rendered');
} catch (err) {
  console.log('error rendering', err);
}

Generate SVG path strings for various BPMN shape geometries based on a ShapeLike object (which must contain x, y, width, and height).

• getCirclePath(shape): Returns a path for a circle.
• getRectPath(shape): Returns a path for a rectangle.
• getDiamondPath(shape): Returns a path for a diamond.
• getRoundRectPath(shape, borderRadius): Returns a path for a rectangle with rounded corners using the provided borderRadius.

Utilities to extract dimensions from an element or a bounding box, with support for overrides.

• getBounds(bounds, overrides): Returns an object { width, height }.
• getWidth(bounds, overrides): Returns the width. If overrides.width is present, it is used; otherwise, it returns bounds.width.
• getHeight(bounds, overrides): Returns the height. If overrides.height is present, it is used; otherwise, it returns bounds.height.

Use these utilities to calculate where labels should be positioned or how much space they occupy:

• getFlowLabelPosition(waypoints): Calculates the optimal position for a label on a flow (like a Sequence Flow) based on its waypoints and an indentation constant.
• getExternalLabelMid(element): Returns the center point of an element's external label.
• getExternalLabelBounds(di, element): Returns the bounding box (Rect) of an element's label, using either the provided DI (Diagram Interchange) information or default sizes.
• getWaypointsMid(waypoints): Returns the geometric midpoint of a set of waypoints.

Use isExpanded(element, di) to determine if a BPMN element is currently expanded in the diagram.

• For bpmn:CallActivity, it always returns false.
• For bpmn:SubProcess, it checks the provided DI (Diagram Interchange) or retrieves it via getDi(element). It returns true if the DI is a bpmndi:BPMNPlane or if the DI object has a truthy isExpanded property.
• For bpmn:Participant, it returns true if the associated business object has a processRef.
• For other elements, it defaults to true.

Use isHorizontal(element) to determine the orientation of a bpmn:Participant or bpmn:Lane.

• Returns undefined if the element is neither a bpmn:Participant nor a bpmn:Lane.
• Returns the isHorizontal property from the element's DI.
• Defaults to true if the isHorizontal property is not defined on the DI.