chore(api): update comments and README

Author: MaxTru

modeling-api/README.md

@@ -1,39 +1,29 @@
-# Modeling in bpmn-js using the API
+# bpmn-js Example: Modeling Using the Api
 
-This example builds a simple learning page to get started with modeling using the [bpmn-js](https://github.com/bpmn-io/bpmn-js) APIs.
+A step-by-step introduction to modeling using the API. You'll learn how create and edit shapes and connections.
 
-## About
+![Screenshot of the example](docs/screenshot.png "Screenshot of the example")
 
-The learning page built in this example includes various code snippets which show basic use cases of the modeling APIs. 
-![Overview of the examples screenshot](docs/overview.png "Overview of the modeling via API example")
+## About This Example
 
-### APIs and concepts covered
+This example is built as a webpage that introduces you to the basics of working with bpmn-js' API, including:
 
-In particular, the learning page covers:
+* creating and editing shapes and connections
+* editing the BPMN properties of an element
+* creating collaborations, participants and lanes
 
-* `elementRegistry` a registry that keeps track of all shapes in a diagram 
-* `elementFactory` a factory for [diagram-js](https://github.com/bpmn-io/diagram-js) shapes
-* `bpmnFactory` a factory for [bpmn-moddle](https://github.com/bpmn-io/bpmn-moddle) BPMN 2.0 XML element representations
-* `modeling` an API to perform BPMN 2.0 modeling operations
+## Running the Example
 
-Using the learning page, you should get familiar with the these key APIs and concepts. However, this is not meant to be a full reference by any means. Therefore you are encouraged to use the learning page as a starting point and then continue with the various other resources:
-
-* [Other examples](https://github.com/bpmn-io/bpmn-js-examples)
-* [Testing specification](https://github.com/bpmn-io/diagram-js/blob/develop/test/spec/core/ElementRegistrySpec.js) showing more `elementRegistry` methods
-* [Testing specification](https://github.com/bpmn-io/bpmn-js/blob/develop/test/spec/features/modeling/ElementFactorySpec.js) showing more `elementFactory` methods
-* [Testing specifications](https://github.com/bpmn-io/bpmn-js/tree/develop/test/spec/features/modeling) showing more `modeling` methods
-
-## Running the example
-
-Install all required dependencies:
+Install the dependencies:
 
 ```
 npm install
 ```
 
-Build and run the project in the browser
+Build and open the example in the browser:
+
 ```
-npm run dev
+npm start
 ```
 
 ## License

modeling-api/app/snippets/businessObjects.js

@@ -14,8 +14,8 @@ function fn(modeler) {
    * * ElementRegistry: A registry of all shapes and connections of the diagram.
    * * Modeling: The main module for modeling.
    *
-   * We will use these modules to create a new shape and add it to the diagram, connect it to an
-   * existing shape.
+   * We will use these modules to create a new business object representing a shape,
+   * add it to the diagram, and connect it to an existing shape.
    */
 
   // (1) Get the modules
@@ -38,7 +38,7 @@ function fn(modeler) {
   // (4) Create a new diagram shape using the business object you just created
   const task = elementFactory.createShape({ type: 'bpmn:Task', businessObject: taskBusinessObject });
 
-  // (4) Add the new task to the diagram
+  // (5) Add the new task to the diagram
   modeling.createShape(task, { x: 400, y: 100 }, process);
 
   // Using the `id` property we specified you can now access the new task through the element registry

modeling-api/app/snippets/collaborations.js

@@ -8,8 +8,9 @@ function fn(modeler) {
    * * ElementRegistry: A registry of all shapes and connections of the diagram.
    * * Modeling: The main module for modeling.
    *
-   * We will use these modules to create a new shape and add it to the diagram, connect it to an
-   * existing shape.
+   * We will use these modules to create Participants, add them to the diagram (thereby
+   * turning the process into a collaboration), create lanes and connect participants
+   * using Message Flows.
    */
 
   // (1) Get the modules
@@ -30,19 +31,20 @@ function fn(modeler) {
   // The existing start event is now a child of the participant
   console.log(startEvent.parent); // Shape { "type": "bpmn:Participant", ... }
 
-  // (4) Create a lane
+  // (5) Create a lane
   const lane = modeling.addLane(participant, 'bottom');
 
-  // (5) Create two nested lanes
+  // (6) Create two nested lanes
   modeling.splitLane(lane, 2);
 
-  // (6) Create another participant shape that is collapsed
-  const collapsedParticipant = elementFactory.createParticipantShape({ type: 'bpmn:Participant', isExpanded: false });
+  // (7) Create another participant shape that is collapsed
+  const collapsedParticipant = elementFactory
+    .createParticipantShape({ type: 'bpmn:Participant', isExpanded: false });
 
-  // (7) Add the participant to the diagram
+  // (8) Add the participant to the diagram
   modeling.createShape(collapsedParticipant, { x: 300, y: 500 }, process);
 
-  // (8) Connect the two participants through a message flow
+  // (9) Connect the two participants through a message flow
   modeling.connect(collapsedParticipant, participant);
 }
 

modeling-api/app/snippets/connectingShapes.js

@@ -7,6 +7,8 @@ function fn(modeler) {
    * * ElementFactory: Creates new shapes and connections.
    * * ElementRegistry: A registry of all shapes and connections of the diagram.
    * * Modeling: The main module for modeling.
+   *
+   * We will use these modules to create shapes and connect them on two different ways.
    */
 
   // (1) Get the modules
@@ -27,13 +29,13 @@ function fn(modeler) {
   // (5) Connect the existing start event to new task using `connect`
   modeling.connect(startEvent, task);
 
-  // (3) Create a end event shape
+  // (6) Create a end event shape
   const endEvent = elementFactory.createShape({ type: 'bpmn:EndEvent' });
 
-  // (4) Add the new end event shape to the diagram
+  // (7) Add the new end event shape to the diagram
   modeling.createShape(endEvent, { x: 600, y: 100 }, process);
 
-  // (5) Create a new sequence flow connection that connects the task to the end event
+  // (8) Create a new sequence flow connection that connects the task to the end event
   modeling.createConnection(task, endEvent, { type: 'bpmn:SequenceFlow' }, process);
 }
 
@@ -42,4 +44,4 @@ export default {
   name: 'Connecting Shapes',
   description: 'Various ways of connecting shapes.',
   fn
-}
+};

modeling-api/app/snippets/creatingShapes.js

@@ -8,6 +8,9 @@ function fn(modeler) {
    * * ElementFactory: Creates new shapes and connections.
    * * ElementRegistry: A registry of all shapes and connections of the diagram.
    * * Modeling: The main module for modeling.
+   *
+   * We will use these modules to create some more shapes including a BoundaryEvent and
+   * a SubProcess.
    */
 
   // (1) Get the modules
@@ -33,39 +36,40 @@ function fn(modeler) {
   // (6) Add the new boundary event to the diagram attaching it to the service task
   modeling.createShape(boundaryEvent, { x: 400, y: 140 }, serviceTask, { attach: true });
 
-  // (7) Create an event sub process
+  // (7) Create an event sub process business object
   const eventSubProcessBusinessObject = bpmnFactory.create('bpmn:SubProcess', {
     triggeredByEvent: true,
     isExpanded: true
   });
 
+  // (8) Create the SubProcess shape, set the previously created event sub process business object
   const eventSubProcess = elementFactory.createShape({
     type: 'bpmn:SubProcess',
     businessObject: eventSubProcessBusinessObject,
     isExpanded: true
   });
 
-  // (8) Add the event sub process
+  // (9) Add the event sub process to the diagram
   modeling.createShape(eventSubProcess, { x: 300, y: 400 }, process);
 
-  // (9) Create a timer start event specifying `eventDefinitionType` so an event definition will
+  // (10) Create a timer start event specifying `eventDefinitionType` so an event definition will
   // be added
   const timerStartEvent = elementFactory.createShape({
     type: 'bpmn:StartEvent',
     eventDefinitionType: 'bpmn:TimerEventDefinition'
   });
 
-  // (10) Add the new timer start event to the diagram specifying the event sub process as the target
+  // (11) Add the new timer start event to the diagram specifying the event sub process as the target
   // so the event will be a child of it
   modeling.createShape(timerStartEvent, { x: 200, y: 400 }, eventSubProcess);
 
-  // (11) Finally, create a new group shape specifying width and height
+  // (12) Finally, create a new group shape specifying width and height
   const group = elementFactory.createShape({ type: 'bpmn:Group', width: 400, height: 200 });
 
-  // (12) Add the new group to the diagram
+  // (13) Add the new group to the diagram
   modeling.createShape(group, { x: 325, y: 100 }, process);
 
-  // (13) Create multiple elements at once specifying x and y which will be treated as relative
+  // (14) Create two shapes specifying x and y which will be treated as relative
   // coordinates, not absolute
   const messageStartEvent = elementFactory.createShape({
     type: 'bpmn:StartEvent',
@@ -80,6 +84,7 @@ function fn(modeler) {
     y: 0
   });
 
+  // (15) Add multiple shapes to the diagram
   modeling.createElements([ messageStartEvent, userTask ], { x: 300, y: 600 }, process);
 }
 

modeling-api/app/snippets/editingElements.js

@@ -10,10 +10,9 @@ function fn(modeler) {
    * * ElementRegistry: A registry of all shapes and connections of the diagram.
    * * Modeling: The main module for modeling.
    *
-   * We will use these modules to create a new shape and add it to the diagram, connect it to an
-   * existing shape.
+   * We will use these modules to update the properties of two existing shapes.
    */
-  
+
   // (1) Get the modules
   const bpmnFactory = modeler.get('bpmnFactory'),
         elementRegistry = modeler.get('elementRegistry'),
@@ -33,7 +32,7 @@ function fn(modeler) {
     default: sequenceFlow.businessObject
   });
 
-  // (5) Make a task multi-instance
+  // (5) Change a task to be multi-instance
   const multiInstanceLoopCharacteristics = bpmnFactory.create('bpmn:MultiInstanceLoopCharacteristics');
 
   modeling.updateProperties(task, {
@@ -47,4 +46,4 @@ export default {
   description: 'How to edit existing elements.',
   diagram,
   fn
-}
+};

modeling-api/app/snippets/introduction.js

@@ -9,10 +9,10 @@ function fn(modeler) {
    * * ElementRegistry: A registry of all shapes and connections of the diagram.
    * * Modeling: The main module for modeling.
    *
-   * We will use these modules to create a new shape and add it to the diagram, connect it to an
-   * existing shape.
+   * We will use these modules to create a new shape, add it to the diagram, and
+   * connect it to an existing shape.
    */
-  
+
   // (1) Get the modules
   const elementFactory = modeler.get('elementFactory'),
         elementRegistry = modeler.get('elementRegistry'),
@@ -40,4 +40,4 @@ export default {
   name: 'Introduction',
   description: 'An introduction to the modules of bpmn-js that can be used to create and connect shapes.',
   fn
-}
+};