BPMN text annotation in EJ2 TypeScript Diagram control

4 Dec 202419 minutes to read

Text annotation

A BPMN object can be associated with a text annotation which does not affect the flow but gives details about objects within a flow.
A TextAnnotation points to or references another BPMN shape, which we call the textAnnotationTarget of the textAnnotation. When a target shape is moved or deleted, any TextAnnotations attached to the shape will be moved or deleted too. Thus, the TextAnnotations remain with their target shapes though you can reposition the TextAnnotation to any offset from its target. The textAnnotationTarget property of the BpmnTextAnnotation is used to connect an annotation element to the BPMN Node.
The annotation element can be switched from a BPMN node to another BPMN node simply by dragging the source end of the annotation connector into the other BPMN node.
By default, the TextAnnotation shape has a connection.
The textAnnotationDirection property is used to set the shape direction of the text annotation.
By default, the textAnnotationDirection is set to a Auto.
To set the size for text annotation, use the width and height properties of the node.
The offsetX and offsetY properties are used to set the distance between the BPMN node and the TextAnnotation.

index.ts
index.html
import { Diagram, NodeModel, BpmnShape, BpmnSubProcessModel, BpmnShapeModel,BpmnDiagrams, BpmnActivityModel, BpmnFlowModel, BpmnGatewayModel } from '@syncfusion/ej2-diagrams';
Diagram.Inject(BpmnDiagrams);
// A node is created and stored in nodes array.
let nodes: NodeModel[] = [ {
    id: 'event1', style: { strokeWidth: 2 },
    height:70,width:70,offsetX:400,offsetY:200,
    shape: { type: 'Bpmn', shape: 'Event',
        event: { event: 'Start', trigger: 'None' },
     } as BpmnShapeModel
},
//node with target
{
    id: 'textNode1', width: 70, height: 70,
    offsetX:400,offsetY:400,
    annotations:[{content:'textNode1'}],
        shape: {
            type: 'Bpmn', shape: 'TextAnnotation',
            textAnnotation:{ textAnnotationDirection:'Auto',textAnnotationTarget:'event1'}
        } as BpmnShapeModel
},
//Node without target
{
    id: 'textNode2', width: 70, height: 70,
    offsetX:600,offsetY:400,
    annotations:[{content:'textNode2'}],
        shape: {
            type: 'Bpmn', shape: 'TextAnnotation',
            textAnnotation:{ textAnnotationDirection:'Auto',textAnnotationTarget:''}
        } as BpmnShapeModel
},]
// initialize diagram component
let diagram: Diagram = new Diagram({
    width: '100%',
    height: '600px',
    // Add node
    nodes: nodes
});
// render initialized diagram
diagram.appendTo('#element');
<!DOCTYPE html>
<html lang="en">

<head>
    <title>EJ2 Diagram</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="Typescript UI Controls" />
    <meta name="author" content="Syncfusion" />
    <link href="index.css" rel="stylesheet" />
    <script src="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script>
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-base/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-buttons/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-popups/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-splitbuttons/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-diagrams/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-navigations/styles/fabric.css" rel="stylesheet" />
    <script src="systemjs.config.js"></script>
<script src="https://cdn.syncfusion.com/ej2/syncfusion-helper.js" type ="text/javascript"></script>
</head>

<body>
    <div id='loader'>Loading....</div>
    <div id='container'>
        <div id='element'></div>
    </div>
</body>

</html>

Text annotation in palette.

Text annotation node can be rendered in symbol palette like other bpmn shapes. The following example shows how to render Bpmn text annotation node in symbol palette.

index.ts
index.html
import { enableRipple } from '@syncfusion/ej2-base';
enableRipple(true);

/**
 * BPMNShapes_Events
 */

import {
  Diagram,
  NodeModel,
  Node,
  BpmnDiagrams,
  UndoRedo,
  SymbolPalette,
  BpmnShapeModel,
  DiagramContextMenu,
  ConnectorModel,
  BpmnGatewayModel,
  ContextMenuSettingsModel,
  IDragEnterEventArgs,
  BpmnEvents,
  BpmnFlowModel,
} from '@syncfusion/ej2-diagrams';
import { MenuEventArgs } from '@syncfusion/ej2-navigations';

// tslint:disable
Diagram.Inject(BpmnDiagrams, UndoRedo, DiagramContextMenu);
SymbolPalette.Inject(BpmnDiagrams);

let diagram: Diagram;
let nodes: NodeModel[] = [];
let shape: BpmnFlowModel = {
  type: 'Bpmn',
  flow: 'Association',
  association: 'Directional',
};
let connectors: ConnectorModel[] = [];
let bpmnShapes: NodeModel[] = [
  {
    id: 'Start',
    width: 35,
    height: 35,
    shape: {
      type: 'Bpmn',
      shape: 'Event',
      event: { event: 'Start' },
    },
  },
  {
    id: 'Gateway',
    width: 35,
    height: 35,
    offsetX: 100,
    offsetY: 100,
    shape: {
      type: 'Bpmn',
      shape: 'Gateway',
      gateway: { type: 'Exclusive' } as BpmnGatewayModel,
    },
  },
  {
    id: 'DataObject',
    width: 35,
    height: 35,
    offsetX: 500,
    offsetY: 100,
    shape: {
      type: 'Bpmn',
      shape: 'DataObject',
      dataObject: { collection: false, type: 'None' },
    },
  },
  {
    id: 'textAnnotation',
    width: 35,
    height: 35,
    shape: {
      type: 'Bpmn',
      shape: 'TextAnnotation',
    },
    annotations: [{ content: 'textAnnotation' }],
  },
];

function dragEnter(args: IDragEnterEventArgs): void {
  let obj: NodeModel = args.element as NodeModel;
  if (obj instanceof Node) {
    let bpmnShape: BpmnShapeModel = obj.shape as BpmnShapeModel;
    if (!bpmnShape.activity.subProcess.collapsed) {
      bpmnShape.activity.subProcess.transaction.cancel.visible = true;
      bpmnShape.activity.subProcess.transaction.failure.visible = true;
      bpmnShape.activity.subProcess.transaction.success.visible = true;
    } else {
      let oWidth: number = obj.width;
      let oHeight: number = obj.height;
      let ratio: number = 100 / obj.width;
      obj.width = 100;
      obj.height *= ratio;
      obj.offsetX += (obj.width - oWidth) / 2;
      obj.offsetY += (obj.height - oHeight) / 2;
    }
  }
}

function getSymbolDefaults(symbol: NodeModel): void {
  symbol.style.strokeColor = '#757575';
}

diagram = new Diagram({
  width: '800px',
  height: '445px',
  nodes: nodes,
  connectors: connectors,
  snapSettings: { constraints: 0 },
  dragEnter: dragEnter,
});
diagram.appendTo('#element');
diagram.fitToPage({ mode: 'Width' });

let palette: SymbolPalette = new SymbolPalette({
  expandMode: 'Multiple',
  symbolMargin: { left: 15, right: 15, top: 15, bottom: 15 },
  symbolHeight: 60,
  symbolWidth: 60,
  palettes: [
    {
      id: 'Bpmn',
      expanded: true,
      symbols: bpmnShapes,
      iconCss: 'shapes',
      title: 'BPMN Shapes',
    },
  ],
  width: '100%',
  height: '471px',
  getNodeDefaults: getSymbolDefaults,
});
palette.appendTo('#palette');
<!DOCTYPE html>
<html lang="en">

<head>
    <title>EJ2 Diagram</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="Typescript UI Controls" />
    <meta name="author" content="Syncfusion" />
    <link href="index.css" rel="stylesheet" />
    <script src="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script>
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-base/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-buttons/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-popups/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-splitbuttons/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-diagrams/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-navigations/styles/fabric.css" rel="stylesheet" />
    <script src="systemjs.config.js"></script>
<script src="https://cdn.syncfusion.com/ej2/syncfusion-helper.js" type ="text/javascript"></script>
</head>

<body>
    <div id='loader'>Loading....</div>
    <div id='container'>
        <div id="palette" style="float: left">
        </div>
        <div id="element" style="float: right"></div>
    </div>
</body>

</html>

Connect the TextAnnotation to BPMN node

Drag and drop any bpmn shapes from the palette to diagram and connect the BPMN Node and textAnnotation.

The following image shows how to drag a symbol from the palette and connect the textAnnotation to the BPMNNode with interaction.

Text annotation GIF

Text annotation direction

There are several types of Text annotation directions as follows:

Text annotation direction	Image
Auto
Left
Right
Top
Bottom

Add text annotation at runtime

Text annotations can be added dynamically using either the addTextAnnotation method or the add method of the diagram. The following example shows how to use these methods to add a text annotation node.

index.ts
index.html
import {
  Diagram,
  BpmnDiagrams,
  randomId,
  Node,
} from '@syncfusion/ej2-diagrams';
Diagram.Inject(BpmnDiagrams);
let diagram: Diagram = new Diagram({
  width: '100%',
  height: '600px',
  nodes: [
    {
      id: 'event',
      offsetX: 200,
      offsetY: 200,
      width: 70,
      height: 70,
      shape: { type: 'Bpmn', shape: 'Event' },
      style: { fill: '#64Abbd' },
    },
  ],
});
diagram.appendTo('#element');

(document.getElementById('addTextAnnotationNode') as HTMLInputElement).onclick = () => {
  let textAnnotation = {
    id: 'textAnnotation' + randomId(),
    offsetX: 300,
    offsetY: 100,
    width: 100,
    height: 40,
    annotations: [{ content: 'Text Annotation' }],
    shape: {
      type: 'Bpmn',
      shape: 'TextAnnotation',
      textAnnotation: {
        //Parent node of text annotation
        textAnnotationTarget: 'event',
        textAnnotationDirection: 'Auto',
      },
    },
  };
  /**
   * parameter 1 - TextAnnotation to be added to the event node
   */
  diagram.add(textAnnotation as Node);
};

(document.getElementById('addTextAnnotationAlone') as HTMLInputElement).onclick = () => {
  let textAnnotation = {
    id: 'textAnnotationAlone' + randomId(),
    offsetX: 300,
    offsetY: 300,
    width: 100,
    height: 70,
    annotations: [{ content: 'Text Annotation' }],
    shape: {
      type: 'Bpmn',
      shape: 'TextAnnotation',
    },
  };
  /**
   * parameter 1 - TextAnnotation to be added to diagram without parent
   */
  diagram.add(textAnnotation as Node);
};

(document.getElementById('addTextAnnotation') as HTMLInputElement).onclick = () => {
  let event = diagram.nodes[0];
  let textAnnotation = {
    name: 'newAnnotation' + randomId(),
    angle: 0,
    length: 100,
    width: 100,
    height: 40,
    text: 'New Annotation',
  };
  /**
   * parameter 1 - TextAnnotation to be added
   * parameter 2 - The parent node where the text annotation will be added as a child.
   */
  diagram.addTextAnnotation(textAnnotation, event);
};
<!DOCTYPE html>
<html lang="en">

<head>
    <title>EJ2 Diagram</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="Typescript UI Controls" />
    <meta name="author" content="Syncfusion" />
    <link href="index.css" rel="stylesheet" />
    <script src="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script>
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-base/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-buttons/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-popups/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-splitbuttons/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-diagrams/styles/material.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/28.2.3/ej2-navigations/styles/fabric.css" rel="stylesheet" />
    <script src="systemjs.config.js"></script>
<script src="https://cdn.syncfusion.com/ej2/syncfusion-helper.js" type ="text/javascript"></script>
</head>

<body>
    <div id='loader'>Loading....</div>
    <div id='container'>
        <input type="button" value="addTextAnnotation" id="addTextAnnotation" />
        <input type="button" value="addTextAnnotationNode" id="addTextAnnotationNode" />
        <input type="button" value="addTextAnnotationAlone" id="addTextAnnotationAlone" />
        <div id="element" style="float: right"></div>
    </div>
</body>

</html>