[DOC] Improve readme (#643)

process-analytics · Sep 23, 2020 · 7aeaffd · 7aeaffd
1 parent 3fe450d
commit 7aeaffd
Show file tree

Hide file tree

Showing 4 changed files with 167 additions and 45 deletions.
diff --git a/README.md b/README.md
@@ -1,27 +1,40 @@
-# bpmn-visualization
-
-
-[![Build](https://github.com/process-analytics/bpmn-visualization-js/workflows/Build/badge.svg)](https://github.com/process-analytics/bpmn-visualization-js/actions)
-[![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/process-analytics/bpmn-visualization-js?color=orange&include_prereleases)](https://github.com/process-analytics/bpmn-visualization-js/releases)
-
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
-[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
-[![License](https://img.shields.io/github/license/process-analytics/bpmn-visualization-js?color=blue)](LICENSE)
-
-`bpmn-visualization` is a TypeScript library to visualize process execution data on [BPMN](https://www.omg.org/spec/BPMN/2.0.2/)
-diagrams with
+<h1 align="center">BPMN Visualization</h1>
+<p align="center">
+    <p align="center"> <img title="BPMN Visualization" src="docs/diagram-example.png" width="812" height="170"></p>
+    <p align="center"> 
+        <a href="https://github.com/process-analytics/bpmn-visualization-js/releases">
+          <img alt="GitHub release (latest by date including pre-releases" src="https://img.shields.io/github/v/release/process-analytics/bpmn-visualization-js?color=orange&include_prereleases"> 
+        </a> 
+        <a href="https://cdn.statically.io/gh/process-analytics/bpmn-visualization-examples/master/demo/index.html">
+          <img alt="Live Demo" src="https://img.shields.io/badge/demo-online-blueviolet.svg"> 
+        </a> 
+        <a href="https://github.com/process-analytics/bpmn-visualization-js/actions">
+        <img alt="Build" src="https://github.com/process-analytics/bpmn-visualization-js/workflows/Build/badge.svg"> 
+        </a> 
+        <br>
+        <a href="CONTRIBUTING.md">
+        <img alt="PRs Welcome" src="https://img.shields.io/badge/PRs-welcome-ff69b4.svg?style=flat-square"> 
+        </a> 
+        <a href="CODE_OF_CONDUCT.md">
+        <img alt="Contributor Covenant" src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg"> 
+        </a> 
+        <a href="LICENSE">
+        <img alt="License" src="https://img.shields.io/github/license/process-analytics/bpmn-visualization-js?color=blue"> 
+        </a> 
+    </p>
+</p>  
+<br>
+
+`bpmn-visualization` is a TypeScript library to visualize process execution data on [BPMN](https://www.omg.org/spec/BPMN/2.0.2/) diagrams with:
 - additional display options for execution data (highlight some transitions, counters, and more)
-- with interactive capacities (mouse hover, click)
-
-
-**Supported Browsers**: Chrome, Firefox, Safari, Edge.
+- interactive capacities (mouse hover, click)
 
+<br>
 
-# Demo and examples
 
-## Demo
+## 🎮 Demo
 
-Give a try to the [__:fast_forward: demo live environment__](https://cdn.statically.io/gh/process-analytics/bpmn-visualization-examples/master/demo/index.html).
+Give a try to the [__:fast_forward: demo live environment__][demo-live-environment].
 The demo let you load a BPMN file to see how `bpmn-visualization` renders it. Various versions of the lib are available. 
 
 If you need BPMN examples, you can use resources from 
@@ -31,28 +44,75 @@ If you need BPMN examples, you can use resources from
 - [bpmn-visualization BPMN test diagrams](https://github.com/process-analytics/bpmn-visualization-examples/blob/master/bpmn-files/README.md)
 
 
-## Examples
+## 🌏 Browser Support
 
-Want to know more about `bpmn-visualization` usage and extensibility? Have a look at the
-[__:fast_forward: live examples site__](https://cdn.statically.io/gh/process-analytics/bpmn-visualization-examples/master/examples/index.html).
+| <img src="https://www.google.com/chrome/static/images/chrome-logo.svg" alt="Chrome" width="18px" height="18px" /> Chrome | <img src="https://user-media-prod-cdn.itsre-sumo.mozilla.net/uploads/products/2020-04-14-08-36-13-8dda6f.png" alt="Firefox" width="18px" height="18px" /> Firefox | <img src="https://developer.apple.com/assets/elements/icons/safari/safari-96x96.png" alt="Safari" width="18px" height="18px" /> Safari | <img src="https://avatars0.githubusercontent.com/u/11354582?s=200&v=4" alt="Edge" width="18px" height="18px" /> Edge |
+| :---------: | :---------: | :---------: | :---------: |
+| Yes | Yes | Yes | Yes |
 
-For more technical details and how-to, go to the [bpmn-visualization-examples](https://github.com/process-analytics/bpmn-visualization-examples/)
-repository.
+**Note**: Internet Explorer won't never be supported. \
+The library may work with the other browsers, currently not list, if they support ES6.
+
+## 🎨 Features
+
+`bpmn-visualization` is in early development stages and is subject to changes prior to the `1.0.0` release.\
+\
+Implemented features:
+- Rendering of the most common BPMN elements.  
+Notice that there is currently no plan to support `Conversation` and `Choreography`.
 
+Current implementation:
+- The [packaging](https://github.com/process-analytics/bpmn-visualization-js/milestone/18) of the library.
 
-# Roadmap
+Future features:
+- BPMN extensions
+- The library extension points
+- Display options for execution data with interactive capacities.
 
-`bpmn-visualization` is in early development stages and is subject to changes prior to the `1.0.0` release.
 
-For now, we render the most common BPMN elements. Notice that there is currently no plan to support `Conversation` and `Choreography`.
+## ♻️ Usage
+For now, we don't put the released library on npm. So you need to clone the repository in local, get the last tag, and build it. \
+:warning: WE ARE CURRENTLY WORKING ON THE PACKAGING :warning: 
 
-We are currently focusing on the [packaging](https://github.com/process-analytics/bpmn-visualization-js/milestone/18) of the library.
+* Load necessary scripts 
+```html
+    <!-- load global settings -->
+    <script src="./static/js/configureMxGraphGlobals.js"></script>
+    <!-- load mxGraph client library -->
+    <script src="./static/js/mxClient.min.js"></script>
+    <!-- load BPMN Visualization library -->
+    <script src="<YOUR_PATH>/bpmn-visualization-js/dist/index.es.js"></script>
+```
+* Define your BPMN content using one of the following ways:
+  * Copy/Paste directly the XML content in a variable
+  * Load it from a url, like this [example](https://github.com/process-analytics/bpmn-visualization-examples/blob/master/examples/load-remote-bpmn-diagrams/index.html)
+  * Load from your computer, like the [demo example](https://github.com/process-analytics/bpmn-visualization-js/blob/master/src/demo/index.ts)
+```javascript
+    const bpmnContent = ``; // your BPMN 2.0 XML content
+```
+* Define the mxGraph container
+```html
+    <div id="graph"></div>
+```
+* Initialize BpmnVisualization from the container
+```javascript
+    console.log(`Initializing BpmnVisualization with container '${container}'...`);
+    const bpmnVisualization = new BpmnVisualization(window.document.getElementById(container));  
+```
+* Load the bpmn content from BpmnVisualization
+```javascript
+    console.log('Loading bpmn....');
+    bpmnVisualization.load(bpmnContent);
+    console.log('BPMN loaded');
+```
 
-Then, we will work on BPMN extensions, library extension points, display options for execution data with interactive
-capacities.
+💡 Want to know more about `bpmn-visualization` usage and extensibility? Have a look at the
+[__:fast_forward: live examples site__](https://cdn.statically.io/gh/process-analytics/bpmn-visualization-examples/master/examples/index.html).
 
+For more technical details and how-to, go to the [bpmn-visualization-examples](https://github.com/process-analytics/bpmn-visualization-examples/)
+repository.
 
-# Contributing
+## 🔧 Contributing
 
 To contribute to `bpmn-visualization`, fork and clone this repository locally and commit your code on a separate branch. \
 Please write tests for your code before opening a pull-request:
@@ -65,7 +125,8 @@ You can find more detail in our [Contributing guide](CONTRIBUTING.md). Participa
 
 :sparkles: A BIG thanks to all our contributors :slightly_smiling_face:
 
-# License
+
+## 📃 License
 
 `bpmn-visualization` is released under the [Apache 2.0](LICENSE) license. \
 Copyright &copy; 2020, Bonitasoft S.A.
@@ -77,8 +138,11 @@ for more details:
 - [noun project](https://thenounproject.com/) (mainly Creative Commons CCBY 3.0)
 
 
-# Powered by
+## ⚡ Powered by
 
 [![statically.io logo](https://statically.io/icons/icon-96x96.png "statically.io")](https://statically.io)
 
 **[statically.io](https://statically.io)** (<kbd>demo</kbd> and <kbd>examples</kbd> live environments)
+
+
+[demo-live-environment]: https://cdn.statically.io/gh/process-analytics/bpmn-visualization-examples/master/demo/index.html
diff --git a/docs/development/development.md b/docs/development/development.md
@@ -7,7 +7,7 @@
 ## Requirements
 
 - `Node.js` 12.16.x and 14.11.x (may work with other versions but without any guarantee)
-- `Supported OS` (see the Github Build workflow for more details): Windows/Linux/MacOs
+- `Supported OS` Windows/Linux/MacOs (see the Github Build workflow for more details)
 
 ## Build
 

diff --git a/docs/diagram-example.png b/docs/diagram-example.png
diff --git a/docs/intro.adoc b/docs/intro.adoc
@@ -1,34 +1,92 @@
 == Introduction
 
+image::diagram-example.png[]
+
 `bpmn-visualization` is a TypeScript library to visualize process execution data on https://www.omg.org/spec/BPMN/2.0.2/[BPMN]
 diagrams. It is in early development stages and is subject to changes prior to the `1.0.0` release.
 
-For now, we render the most <<supported-bpmn-elements,common BPMN elements>>. Notice that there is currently no plan to support `Conversation` and `Choreography`.
+Implemented features:
+
+- Rendering of the most  <<supported-bpmn-elements,common BPMN elements>>.
+Notice that there is currently no plan to support `Conversation` and `Choreography`.
+
 
-We are currently focusing on the https://github.com/process-analytics/bpmn-visualization-js/milestone/18[packaging] of the library.
+Current implementation:
 
-Then, we will work on BPMN extensions, library extension points, display options for execution data with interactive
-capacities.
+- The https://github.com/process-analytics/bpmn-visualization-js/milestone/18[packaging] of the library.
 
-**Supported Browsers**: Chrome, Firefox, Safari, Edge.
 
+Future features:
 
-== Demo and examples
+- BPMN extensions
+- The library extension points
+- Display options for execution data with interactive capacities.
 
-=== Demo
+
+== 🎮 Demo
 Give a try to the https://cdn.statically.io/gh/process-analytics/bpmn-visualization-examples/master/demo/index.html[**icon:forward[] demo live environment**].
 The demo let you load a BPMN file to see how `bpmn-visualization` renders it. Various versions of the lib are available.
 
-If you need BPMN examples, you can use resources from
+If you need BPMN examples, you can use resources from:
 
 * the http://www.omgwiki.org/bpmn-miwg[BPMN Model Interchange Working Group (BPMN MIWG)]
 ** https://github.com/bpmn-miwg/bpmn-miwg-test-suite
 ** https://github.com/bpmn-miwg/bpmn-miwg-demos
-* https://github.com/process-analytics/bpmn-visualization-examples/blob/master/bpmn-files/README.md[bpmn-visualization BPMN test diagrams] 
+* https://github.com/process-analytics/bpmn-visualization-examples/blob/master/bpmn-files/README.md[bpmn-visualization BPMN test diagrams]
+
+== 🌏 Browser Support
+
+|===
+| image:https://www.google.com/chrome/static/images/chrome-logo.svg[width=18] Chrome | image:https://user-media-prod-cdn.itsre-sumo.mozilla.net/uploads/products/2020-04-14-08-36-13-8dda6f.png[width=18] Firefox | image:https://developer.apple.com/assets/elements/icons/safari/safari-96x96.png[width=18] Safari | image:https://avatars0.githubusercontent.com/u/11354582?s=200&v=4[width=18] Edge
+
+|Yes
+|Yes
+|Yes
+|Yes
+
+|===
+
+**Note**: Internet Explorer won't never be supported. +
+The library may work with the other browsers, currently not list, if they support ES6.
+
+
+== ♻️ Usage
+For now, we don't put the released library on npm. So you need to clone the repository in local, get the last tag, and build it. +
+⚠️  WE ARE CURRENTLY WORKING ON THE PACKAGING ⚠️
 
+* Load necessary scripts
+```html
+    <!-- load global settings -->
+    <script src="./static/js/configureMxGraphGlobals.js"></script>
+    <!-- load mxGraph client library -->
+    <script src="./static/js/mxClient.min.js"></script>
+    <!-- load BPMN Visualization library -->
+    <script src="<YOUR_PATH>/bpmn-visualization-js/dist/index.es.js"></script>
+```
+* Define your BPMN content using one of the following ways:
+** Copy/Paste directly the XML content in a variable
+** Load it from a url, like this https://github.com/process-analytics/bpmn-visualization-examples/blob/master/examples/load-remote-bpmn-diagrams/index.html[example]
+** Load from your computer, like the https://github.com/process-analytics/bpmn-visualization-js/blob/master/src/demo/index.ts[demo example]
+```javascript
+    const bpmnContent = ``; // your BPMN 2.0 XML content
+```
+* Define the mxGraph container
+```html
+    <div id="graph"></div>
+```
+* Initialize BpmnVisualization from the container
+```javascript
+    console.log(`Initializing BpmnVisualization with container '${container}'...`);
+    const bpmnVisualization = new BpmnVisualization(window.document.getElementById(container));  
+```
+* Load the bpmn content from BpmnVisualization
+```javascript
+    console.log('Loading bpmn....');
+    bpmnVisualization.load(bpmnContent);
+    console.log('BPMN loaded');
+```
 
-=== Examples
-Want to know more about `bpmn-visualization` usage and extensibility? Have a look at the
+💡 Want to know more about `bpmn-visualization` usage and extensibility? Have a look at the
 https://cdn.statically.io/gh/process-analytics/bpmn-visualization-examples/master/examples/index.html[**icon:forward[] examples live environment**].
 
 For more technical details and how-to, go to the https://github.com/process-analytics/bpmn-visualization-examples/[bpmn-visualization-examples]