From a789a41bc549d9354f67c29da3b6840bf7754bbd Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Tue, 26 May 2020 09:31:33 +0200 Subject: [PATCH 01/13] wip: architecture overview --- docs/architecture/00-index.adoc | 2 + docs/architecture/architecture-overview.adoc | 7 ++ .../architecture/architecture_overview.svg | 92 +++++++++++++++++++ 3 files changed, 101 insertions(+) create mode 100644 docs/architecture/architecture-overview.adoc create mode 100644 docs/architecture/images/architecture/architecture_overview.svg diff --git a/docs/architecture/00-index.adoc b/docs/architecture/00-index.adoc index e3c91b2a81..8be6b515c2 100644 --- a/docs/architecture/00-index.adoc +++ b/docs/architecture/00-index.adoc @@ -5,6 +5,8 @@ To know how to build the project, please have a look at the https://github.com/process-analytics/bpmn-visualization-js/blob/master/CONTRIBUTING.md[contributing guide]. +include::architecture-overview.adoc[] + include::bpmn-internal-model.adoc[] include::bpmn-parsing.adoc[] diff --git a/docs/architecture/architecture-overview.adoc b/docs/architecture/architecture-overview.adoc new file mode 100644 index 0000000000..5f7324c888 --- /dev/null +++ b/docs/architecture/architecture-overview.adoc @@ -0,0 +1,7 @@ +=== Architecture Overview + +*WIP* architecture + +image::images/architecture/architecture_overview.svg[] + + diff --git a/docs/architecture/images/architecture/architecture_overview.svg b/docs/architecture/images/architecture/architecture_overview.svg new file mode 100644 index 0000000000..aa98ba709f --- /dev/null +++ b/docs/architecture/images/architecture/architecture_overview.svg @@ -0,0 +1,92 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + xml parser + json parser + BPMN parser + + From 6786836883386c32581b924dfff829682e79afae Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Tue, 26 May 2020 12:15:55 +0200 Subject: [PATCH 02/13] 1st version of the architecture overview --- docs/architecture/architecture-overview.adoc | 2 - .../architecture/architecture_overview.svg | 382 ++++++++++++++++-- 2 files changed, 350 insertions(+), 34 deletions(-) diff --git a/docs/architecture/architecture-overview.adoc b/docs/architecture/architecture-overview.adoc index 5f7324c888..0f2d2b1d68 100644 --- a/docs/architecture/architecture-overview.adoc +++ b/docs/architecture/architecture-overview.adoc @@ -1,7 +1,5 @@ === Architecture Overview -*WIP* architecture - image::images/architecture/architecture_overview.svg[] diff --git a/docs/architecture/images/architecture/architecture_overview.svg b/docs/architecture/images/architecture/architecture_overview.svg index aa98ba709f..0f764d1e2f 100644 --- a/docs/architecture/images/architecture/architecture_overview.svg +++ b/docs/architecture/images/architecture/architecture_overview.svg @@ -5,20 +5,103 @@ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + sodipodi:docname="architecture_overview.svg" + inkscape:version="1.0 (6e3e5246a0, 2020-05-07)" id="svg8" version="1.1" - viewBox="0 0 210 297" - height="297mm" - width="210mm"> + viewBox="0 0 213.82216 207.17613" + height="207.17613mm" + width="213.82216mm"> + + + + + + + + + + + + + @@ -32,61 +115,296 @@ + transform="translate(7.0010919,-0.3056346)" + id="layer1" + inkscape:groupmode="layer" + inkscape:label="Calque 1"> + + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.326;stroke-linejoin:round;stroke-miterlimit:20;stroke-dasharray:none;stroke-opacity:1;paint-order:normal" /> - xml parser + y="38.665062" + x="70.899597" + id="tspan845" + sodipodi:role="line">xml parser json parser BPMN parser + y="17.785177" + x="68.540382" + id="tspan845-6-5" + sodipodi:role="line">BPMN parser + + + + + mxGraph Integration + + + + mxGraph configuration + stylesshapes + + + + BPMN Shapes + mxGraph extensions + + + mxGraph rendering + + graphmodel + + + + graph renderer + + + BPMN source/file + + + + BPMN model + + + + + From 27fcf998909f391563407f86052fa65ebde81514 Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Tue, 26 May 2020 16:22:45 +0200 Subject: [PATCH 03/13] add architecture overview content --- docs/architecture/architecture-overview.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/architecture/architecture-overview.adoc b/docs/architecture/architecture-overview.adoc index 0f2d2b1d68..5e7e036b99 100644 --- a/docs/architecture/architecture-overview.adoc +++ b/docs/architecture/architecture-overview.adoc @@ -1,5 +1,10 @@ === Architecture Overview +The lib consists on 2 main modules + +* parsing: read a BPMN source (xml string) and convert it into its own internal Model +* rendering: display the BPMN diagrams represented by the internal Model, using the https://jgraph.github.io/mxgraph/[mxGraph library] + image::images/architecture/architecture_overview.svg[] From 187992b6d1ae7de92ce9fd1ebb8f975060dd7115 Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Tue, 26 May 2020 16:47:19 +0200 Subject: [PATCH 04/13] wip: doc mxgraph integration --- docs/architecture/00-index.adoc | 2 ++ docs/architecture/mxgraph-integration.adoc | 1 + 2 files changed, 3 insertions(+) create mode 100644 docs/architecture/mxgraph-integration.adoc diff --git a/docs/architecture/00-index.adoc b/docs/architecture/00-index.adoc index 8be6b515c2..6a99271e71 100644 --- a/docs/architecture/00-index.adoc +++ b/docs/architecture/00-index.adoc @@ -12,3 +12,5 @@ include::bpmn-internal-model.adoc[] include::bpmn-parsing.adoc[] include::bpmn-support-how-to.adoc[] + +include::mxgraph-integration.adoc[] diff --git a/docs/architecture/mxgraph-integration.adoc b/docs/architecture/mxgraph-integration.adoc new file mode 100644 index 0000000000..c19b386db2 --- /dev/null +++ b/docs/architecture/mxgraph-integration.adoc @@ -0,0 +1 @@ +=== mxGraph Integration \ No newline at end of file From 35da37119d27eb14edb97490d45ba047252d0c78 Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Tue, 26 May 2020 17:58:11 +0200 Subject: [PATCH 05/13] bpmn support: fix call activity display in the table --- docs/bpmn-support.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bpmn-support.adoc b/docs/bpmn-support.adoc index dd41352a1c..b659305a9d 100644 --- a/docs/bpmn-support.adoc +++ b/docs/bpmn-support.adoc @@ -63,11 +63,11 @@ The default rendering uses `white` as fill color and `black` as stroke color. |icon:flask[] |Icon will be subject to a large change + *icon*: the task icon is currently derived from the https://github.com/primer/octicons/blob/638c6683c96ec4b357576c7897be8f19c933c052/icons/person.svg[primer octicons person svg] -|=== |Call Activity | | +|=== === Events From 1b67de45a03d43126ef7e864abc4371f0fcc177d Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Tue, 26 May 2020 18:05:12 +0200 Subject: [PATCH 06/13] start describing the mxgraph integration --- docs/architecture/00-index.adoc | 4 ++-- docs/architecture/bpmn-support-how-to.adoc | 4 ++-- docs/architecture/mxgraph-integration.adoc | 8 +++++++- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/architecture/00-index.adoc b/docs/architecture/00-index.adoc index 6a99271e71..0eabd376d2 100644 --- a/docs/architecture/00-index.adoc +++ b/docs/architecture/00-index.adoc @@ -11,6 +11,6 @@ include::bpmn-internal-model.adoc[] include::bpmn-parsing.adoc[] -include::bpmn-support-how-to.adoc[] - include::mxgraph-integration.adoc[] + +include::bpmn-support-how-to.adoc[] diff --git a/docs/architecture/bpmn-support-how-to.adoc b/docs/architecture/bpmn-support-how-to.adoc index 1cffcb8634..26a74c99f9 100644 --- a/docs/architecture/bpmn-support-how-to.adoc +++ b/docs/architecture/bpmn-support-how-to.adoc @@ -24,10 +24,10 @@ flow` support (see `ShapeBpmnElementKind` for more details) * Add end-to-end tests, mainly to ensure that the new BPMN element is now stored in the `mxGraph model`, see `mxGraph.model.test.ts`. * No need to create specific XML tests, the XML parsing is tested globally using BPMN files for various BPMN vendors. - +[[bpmn-support-howto-elements-rendering]] ==== Elements rendering -When inserting an element on the graph, a style is passed to identify the way it will be rendered. +When inserting an element on the `mxGraph` graph, a style is passed to identify the way it will be rendered. The https://jgraph.github.io/mxgraph/docs/js-api/files/view/mxStylesheet-js.html[style] is defined and registered in `StyleConfigurator`. In particular, it refers to the name of a https://jgraph.github.io/mxgraph/docs/js-api/files/shape/mxShape-js.html[mxShape] diff --git a/docs/architecture/mxgraph-integration.adoc b/docs/architecture/mxgraph-integration.adoc index c19b386db2..28b4568dd7 100644 --- a/docs/architecture/mxgraph-integration.adoc +++ b/docs/architecture/mxgraph-integration.adoc @@ -1 +1,7 @@ -=== mxGraph Integration \ No newline at end of file +=== mxGraph Integration + +The https://jgraph.github.io/mxgraph/[mxGraph] integration is in charge of displaying the BPMN diagrams, by filling the +https://jgraph.github.io/mxgraph/docs/manual.html#3.1.1:[mxGraph model] from the BPMN model and the mxGraph BPMN styles. + +The lib defines the mxGraph BPMN styles and associates them to the right render, using dedicated BPMN mxGraph shapes. +For more technical details, see the <> From 685ef87249dde403fa60befa34800a2f66120317 Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Tue, 26 May 2020 18:08:18 +0200 Subject: [PATCH 07/13] wip: bpmn elements positioning --- docs/architecture/mxgraph-integration.adoc | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/architecture/mxgraph-integration.adoc b/docs/architecture/mxgraph-integration.adoc index 28b4568dd7..c0e90941d6 100644 --- a/docs/architecture/mxgraph-integration.adoc +++ b/docs/architecture/mxgraph-integration.adoc @@ -5,3 +5,13 @@ https://jgraph.github.io/mxgraph/docs/manual.html#3.1.1:[mxGraph model] from the The lib defines the mxGraph BPMN styles and associates them to the right render, using dedicated BPMN mxGraph shapes. For more technical details, see the <> + +==== BPMN elements positioning + +*WIP* +Apply to both BPMN shapes and edges + +* mxGraph coordinates: relative to parent +* BPMN: absolute + +--> required a transformation layer \ No newline at end of file From 3f239ac4cdb1118f3b48a99ad8f89b8f9982b194 Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Wed, 27 May 2020 07:09:19 +0200 Subject: [PATCH 08/13] wip: wording improvements --- docs/architecture/mxgraph-integration.adoc | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/architecture/mxgraph-integration.adoc b/docs/architecture/mxgraph-integration.adoc index c0e90941d6..05431a7770 100644 --- a/docs/architecture/mxgraph-integration.adoc +++ b/docs/architecture/mxgraph-integration.adoc @@ -1,9 +1,15 @@ === mxGraph Integration The https://jgraph.github.io/mxgraph/[mxGraph] integration is in charge of displaying the BPMN diagrams, by filling the -https://jgraph.github.io/mxgraph/docs/manual.html#3.1.1:[mxGraph model] from the BPMN model and the mxGraph BPMN styles. +https://jgraph.github.io/mxgraph/docs/manual.html#3.1.1:[mxGraph model] from the BPMN model. + +It defines the https://jgraph.github.io/mxgraph/docs/manual.html#3.1.3.1[BPMN styles] including dedicated BPMN shapes +which are associated to the `mxGraph` https://jgraph.github.io/mxgraph/docs/manual.html#3.1.3.4[mxCell] when the elements +are inserted into the `mxGraph` model: + +* `vertex` for BPMN Shapes +* `edge` for BPMN Edges -The lib defines the mxGraph BPMN styles and associates them to the right render, using dedicated BPMN mxGraph shapes. For more technical details, see the <> ==== BPMN elements positioning From 9d062bc4cc4b92e40848a88349847643a564050e Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Wed, 27 May 2020 07:19:42 +0200 Subject: [PATCH 09/13] Add 'Logical Groups of BPMN Elements' --- docs/architecture/mxgraph-integration.adoc | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/architecture/mxgraph-integration.adoc b/docs/architecture/mxgraph-integration.adoc index 05431a7770..dc943784e9 100644 --- a/docs/architecture/mxgraph-integration.adoc +++ b/docs/architecture/mxgraph-integration.adoc @@ -20,4 +20,19 @@ Apply to both BPMN shapes and edges * mxGraph coordinates: relative to parent * BPMN: absolute ---> required a transformation layer \ No newline at end of file +--> required a transformation layer + + +==== Logical Groups of BPMN Elements + +https://jgraph.github.io/mxgraph/docs/manual.html#3.1.4[mxGraph group structure] allows to define a parent-child relationship +that leverages various rendering feature like collapse/expand, group move/hide, ... +The following group of BPMN elements are created + +* `pool` is the parent of `lanes` and `inter-lane elements` (for instance, `message flows`) +* `lane` is the parent of elements it includes in the BPMN source + +The default mxGraph parent is the parent of + +* inter pool elements ( (for instance, `message flows)`) +* elements when the the BPMN source doesn't define any lane/pool From 8da305c118415f92d8751269a8a2ed36f2012ddb Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Wed, 27 May 2020 07:22:47 +0200 Subject: [PATCH 10/13] 'Logical Groups of BPMN Elements' improvements --- docs/architecture/mxgraph-integration.adoc | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/architecture/mxgraph-integration.adoc b/docs/architecture/mxgraph-integration.adoc index dc943784e9..df12744142 100644 --- a/docs/architecture/mxgraph-integration.adoc +++ b/docs/architecture/mxgraph-integration.adoc @@ -25,14 +25,16 @@ Apply to both BPMN shapes and edges ==== Logical Groups of BPMN Elements -https://jgraph.github.io/mxgraph/docs/manual.html#3.1.4[mxGraph group structure] allows to define a parent-child relationship -that leverages various rendering feature like collapse/expand, group move/hide, ... -The following group of BPMN elements are created +https://jgraph.github.io/mxgraph/docs/manual.html#3.1.4[mxGraph Group Structure] allows to define a parent-child relationship +that leverages various rendering features like collapsing/expanding, layering, drill down, group move/hide, ... +See https://jgraph.github.io/mxgraph/docs/manual.html#3.1.5[mxGraph Complexity Management] for more details. + +On `mxGraph` graph creation, the lib fills the following group of BPMN elements: * `pool` is the parent of `lanes` and `inter-lane elements` (for instance, `message flows`) * `lane` is the parent of elements it includes in the BPMN source The default mxGraph parent is the parent of -* inter pool elements ( (for instance, `message flows)`) -* elements when the the BPMN source doesn't define any lane/pool +* inter pool elements (for instance, `message flows`) +* elements when the BPMN source doesn't define any lane/pool From 40a1cdeeeecef3e0b455bdacc3818a09699a4e7e Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Wed, 27 May 2020 07:56:45 +0200 Subject: [PATCH 11/13] Add 'BPMN elements positioning' --- docs/architecture/mxgraph-integration.adoc | 66 ++++++++++++++++++---- 1 file changed, 56 insertions(+), 10 deletions(-) diff --git a/docs/architecture/mxgraph-integration.adoc b/docs/architecture/mxgraph-integration.adoc index df12744142..ee64f49ac5 100644 --- a/docs/architecture/mxgraph-integration.adoc +++ b/docs/architecture/mxgraph-integration.adoc @@ -10,17 +10,9 @@ are inserted into the `mxGraph` model: * `vertex` for BPMN Shapes * `edge` for BPMN Edges -For more technical details, see the <> +The main entry point for `mxGraph` rendering is `MxGraphRenderer`. -==== BPMN elements positioning - -*WIP* -Apply to both BPMN shapes and edges - -* mxGraph coordinates: relative to parent -* BPMN: absolute - ---> required a transformation layer +For more technical details, see <>. ==== Logical Groups of BPMN Elements @@ -38,3 +30,57 @@ The default mxGraph parent is the parent of * inter pool elements (for instance, `message flows`) * elements when the BPMN source doesn't define any lane/pool + + +==== BPMN elements positioning + +*Note*: the following applies to both BPMN shapes and edges (including waypoints) + +The bpmn input source coordinates are absolute whereas mxgraph uses coordinates in the referential of the parent cell. +As we define a parent-child relationship when inserting BPMN elements in the mxGraph model, a coordinate transformation +layer is required. See `MxGraphRenderer` for more details. + + +===== Resources + +====== mxGraph + +.https://jgraph.github.io/mxgraph/docs/manual.html#3.1.3.2[mxgraph Geometry] +[quote] +The coordinate system in JavaScript is x is positive to the right and y is positive +downwards, and in terms of the graph, the positioning is absolute to the container +within which the mxGraph is placed. + +.https://jgraph.github.io/mxgraph/docs/manual.html#3.1.4[mxgraph Group Structure] +[quote] +The x,y position of a vertex is its position relative to its parent, so in the case of +default grouping (all cells sharing the default parent) the cell positioning is also +the absolute co-ordinates on the graph component. + + +====== BPMN specification + +.BPMNPlane (page 371) +[quote] +BPMNPlane element is always owned by a BPMNDiagram and represents the root diagram element of that diagram. +The plane represents a 2 dimensional surface with an origin at (0, 0) along the x and y axes with increasing coordinates +to the right and bottom. Only positive coordinates are allowed for diagram elements that are nested in a BPMNPlane. + +.BPMNShape (page 372) +[quote] +All BPMNShape elements are owned directly by a BPMNPlane (that is the root element in a BPMNDiagram), i.e., shapes +are not nested within each other in the BPMN DI model although they may appear that way when depicted. The bounds +of a BPMNShape are always relative to that plane’s origin point and are REQUIRED to be positive coordinates. Note that +the bounds’ x and y coordinates are the position of the upper left corner of the shape (relative to the upper left corner of +the plane). + + +.BPMNEdge (page 375) +[quote] +All BPMNEdge elements are owned directly by a BPMNPlane (that is the root element in a BPMNDiagram). The +waypoints of BPMNEdge are always relative to that plane’s origin point and are REQUIRED to be positive coordinates. + +.BPMNLabel (page 377) +[quote] +The bounds of BPMNLabel are always relative to the containing plane’s origin point. Note that the bounds’ x and y +coordinates are the position of the upper left corner of the label (relative to the upper left corner of the plane). From 5a407e641a81c36e40c4ac70201a02a5f510dcf2 Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Wed, 27 May 2020 10:20:23 +0200 Subject: [PATCH 12/13] Add link to mxgraph tutorial and manual --- docs/architecture/mxgraph-integration.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/architecture/mxgraph-integration.adoc b/docs/architecture/mxgraph-integration.adoc index ee64f49ac5..9f284e9c4d 100644 --- a/docs/architecture/mxgraph-integration.adoc +++ b/docs/architecture/mxgraph-integration.adoc @@ -14,6 +14,9 @@ The main entry point for `mxGraph` rendering is `MxGraphRenderer`. For more technical details, see <>. +If you are new to `mxGraph` or want to know more about it, please have a look at the https://jgraph.github.io/mxgraph/docs/tutorial.html[mxGraph tutorial] +and https://jgraph.github.io/mxgraph/docs/manual.html[mxGraph manual] + ==== Logical Groups of BPMN Elements From d7bbe5f15c045152393e5f16492083068eb09f27 Mon Sep 17 00:00:00 2001 From: Thomas Bouffard <27200110+tbouffard@users.noreply.github.com> Date: Wed, 27 May 2020 11:17:53 +0200 Subject: [PATCH 13/13] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Souchet Céline <4921914+csouchet@users.noreply.github.com> --- docs/architecture/architecture-overview.adoc | 3 +-- docs/architecture/mxgraph-integration.adoc | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/architecture/architecture-overview.adoc b/docs/architecture/architecture-overview.adoc index 5e7e036b99..b76ec99fa8 100644 --- a/docs/architecture/architecture-overview.adoc +++ b/docs/architecture/architecture-overview.adoc @@ -2,9 +2,8 @@ The lib consists on 2 main modules -* parsing: read a BPMN source (xml string) and convert it into its own internal Model +* parsing: read a BPMN source (xml string) and convert it into its own link:bpmn-internal-model.adoc[internal Model] * rendering: display the BPMN diagrams represented by the internal Model, using the https://jgraph.github.io/mxgraph/[mxGraph library] image::images/architecture/architecture_overview.svg[] - diff --git a/docs/architecture/mxgraph-integration.adoc b/docs/architecture/mxgraph-integration.adoc index 9f284e9c4d..f0dcea4857 100644 --- a/docs/architecture/mxgraph-integration.adoc +++ b/docs/architecture/mxgraph-integration.adoc @@ -15,7 +15,7 @@ The main entry point for `mxGraph` rendering is `MxGraphRenderer`. For more technical details, see <>. If you are new to `mxGraph` or want to know more about it, please have a look at the https://jgraph.github.io/mxgraph/docs/tutorial.html[mxGraph tutorial] -and https://jgraph.github.io/mxgraph/docs/manual.html[mxGraph manual] +and https://jgraph.github.io/mxgraph/docs/manual.html[mxGraph manual]. ==== Logical Groups of BPMN Elements