maxGraph · tbouffard · Jan 6, 2025 · Jan 3, 2025 · Jan 3, 2025 · Jan 3, 2025
diff --git a/README.md b/README.md
@@ -129,16 +129,7 @@ You will see something like in the following _maxGraph panning_ demo:
 The maxGraph documentation is available on the [maxGraph website](https://maxgraph.github.io/maxGraph).
 
 > [!WARNING]  
-> This is a **work in progress**, the content of the original _mxGraph_ documentation will be progressively migrated there.
-> For more details, see [#345](https://github.com/maxGraph/maxGraph/issues/345).
-
-Documentation partially migrated:
-- https://maxgraph.github.io/maxGraph/docs/manual/
-
-Documentation to be migrated:
-- https://jgraph.github.io/mxgraph/docs/tutorial.html
-
-> Be aware that the maxGraph API doesn't fully match the mxGraph API (see the paragraph below about "[Migrating from mxGraph](#migrate-from-mxgraph)").
+> This is a **work in progress**, the content will be progressively improved.
 
 
 ## Examples

diff --git a/packages/core/src/util/MaxXmlRequest.ts b/packages/core/src/util/MaxXmlRequest.ts
@@ -344,7 +344,7 @@ class MaxXmlRequest {
     const params = <string>this.params;
     const pars = params.indexOf('&') > 0 ? params.split('&') : params.split(' ');
 
-    // Adds the parameters as textareas to the form
+    // Adds the parameters as text areas to the form
     for (let i = 0; i < pars.length; i += 1) {
       const pos = pars[i].indexOf('=');
 
@@ -378,57 +378,51 @@ class MaxXmlRequest {
 }
 
 /**
- * Loads the specified URL *synchronously* and returns the <MaxXmlRequest>.
- * Throws an exception if the file cannot be loaded. See {@link Utils#get} for
- * an asynchronous implementation.
+ * Loads the specified URL *synchronously* and returns the {@link MaxXmlRequest}.
+ * Throws an exception if the file cannot be loaded.
+ * See {@link get} for  an asynchronous implementation.
  *
  * Example:
  *
  * ```javascript
- * try
- * {
- *   let req = mxUtils.load(filename);
- *   let root = req.getDocumentElement();
+ * try {
+ *   const req = load(filename);
+ *   cont root = req.getDocumentElement();
  *   // Process XML DOM...
- * }
- * catch (ex)
- * {
- *   mxUtils.alert('Cannot load '+filename+': '+ex);
+ * } catch (e) {
+ *   console.error(`Cannot load $filename`, e);
  * }
  * ```
  *
  * @param url URL to get the data from.
  */
-export const load = (url: string) => {
+export const load = (url: string): MaxXmlRequest => {
   const req = new MaxXmlRequest(url, null, 'GET', false);
   req.send();
   return req;
 };
 
 /**
- * Loads the specified URL *asynchronously* and invokes the given functions
- * depending on the request status. Returns the <MaxXmlRequest> in use. Both
- * functions take the <MaxXmlRequest> as the only parameter. See
- * {@link Utils#load} for a synchronous implementation.
+ * Loads the specified URL *asynchronously* and invokes the given functions depending on the request status.
+ * Returns the {@link MaxXmlRequest} in use.
+ * Both functions take the {@link MaxXmlRequest} as the only parameter.
+ * See {@link load} for a synchronous implementation.
  *
  * Example:
  *
  * ```javascript
- * mxUtils.get(url, (req)=>
- * {
- *    let node = req.getDocumentElement();
+ * get(url, (req) => {
+ *    const node = req.getDocumentElement();
  *    // Process XML DOM...
  * });
  * ```
  *
- * So for example, to load a diagram into an existing graph model, the
- * following code is used.
+ * So for example, to load a diagram into an existing graph model, the following code is used.
  *
  * ```javascript
- * mxUtils.get(url, (req)=>
- * {
- *   let node = req.getDocumentElement();
- *   let dec = new Codec(node.ownerDocument);
+ * get(url, (req) => {
+ *   const node = req.getDocumentElement();
+ *   const dec = new Codec(node.ownerDocument);
  *   dec.decode(node, graph.getDataModel());
  * });
  * ```

diff --git a/packages/website/docs/development/_category_.json b/packages/website/docs/development/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Development",
-  "position": 13,
+  "position": 21,
   "link": {
     "type": "generated-index",
     "description": "Everything you need to know when you are developing maxGraph."

diff --git a/packages/website/docs/intro.md b/packages/website/docs/intro.md
@@ -18,14 +18,6 @@ which requires finer-grained customization of functionality than off-the-shelf p
 
 ## About this documentation
 
-:::warning
-
-This documentation is a **work in progress**.
-
-Please be patient, as content will be gradually updated, especially the content of the original `mxGraph` documentation.
-
-:::
-
 :::tip
 
 The documentation hosted at https://maxgraph.github.io/maxGraph includes the latest development changes.

diff --git a/packages/website/docs/known-issues.md b/packages/website/docs/known-issues.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 20
+sidebar_position: 100
 ---
 
 # Known Issues

diff --git a/packages/website/docs/tutorials/_category_.json b/packages/website/docs/tutorials/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Tutorials",
+  "position": 12,
+  "link": {
+    "type": "generated-index",
+    "description": "Everything you need to know to use specific features of maxGraph."
+  }
+}
diff --git a/...ges/website/old-mxgraph/images/editor.png → ...e/docs/tutorials/assets/graphs/editor.png b/...ges/website/old-mxgraph/images/editor.png → ...e/docs/tutorials/assets/graphs/editor.png
diff --git a/...ages/website/old-mxgraph/images/graph.png → ...te/docs/tutorials/assets/graphs/graph.png b/...ages/website/old-mxgraph/images/graph.png → ...te/docs/tutorials/assets/graphs/graph.png
diff --git a/...ages/website/old-mxgraph/images/model.png → ...te/docs/tutorials/assets/graphs/model.png b/...ages/website/old-mxgraph/images/model.png → ...te/docs/tutorials/assets/graphs/model.png
diff --git a/packages/website/docs/tutorials/assets/hello-world-example.png b/packages/website/docs/tutorials/assets/hello-world-example.png
diff --git a/packages/website/docs/tutorials/editor-input-output.md b/packages/website/docs/tutorials/editor-input-output.md
@@ -0,0 +1,81 @@
+---
+sidebar_position: 4
+description: Learn how to save and open Editor data stored in a XML file.
+---
+
+# Editor Input/Output
+
+:::note
+
+This tutorial is licensed under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/). \
+It is adapted from the original [mxGraph tutorial](https://github.com/jgraph/mxgraph/blob/v4.2.2/docs/tutorial.html).
+
+> Copyright 2021-present The maxGraph project Contributors \
+Copyright (c) JGraph Ltd 2006-2017
+
+:::
+
+
+## Codecs
+
+See the dedicated [codecs page](../usage/codecs.md) for more information on how to use codecs.
+
+For encoding other objects, or if no editor instance is available, the [Codec](https://maxgraph.github.io/maxGraph/api-docs/classes/Codec.html) can be used to create and read XML data.
+
+
+<a id="Files"></a>
+## Files
+
+The `save`, `open`, `readGraphModel` and `writeGraphModel` functions implement a standard mechanism for handling files in [Editor](https://maxgraph.github.io/maxGraph/api-docs/classes/Editor.html).
+
+The default implementation of `Editor.save` is called with an argument to indicate if the save was triggered by the user or by the system.
+It then uses the `urlPost` variable of the editor object to check if a post request should be issued.
+If the variable is defined, the editor issues a post request to the specified URL passing the XML along as a POST variable called xml.
+
+
+<a id="Post"></a>
+## Post
+
+As an example, consider the following PHP file which is located in the same directory as the HTML page.
+If the filename is `server.php` then the `urlPost` variable must be set to `server.php` on the editor in order to post the diagram to the server.
+The PHP file will get the XML from the POST request and write it to a file called `diagram.xml`.
+
+```php
+<?php
+// Validate request method
+if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
+    http_response_code(405);
+    exit('Method not allowed');
+}
+
+$xml = $_POST['xml'] ?? null;
+if ($xml != null) {
+    // Validate XML content
+    if (!simplexml_load_string($xml)) {
+        http_response_code(400);
+        exit('Invalid XML');
+    }
+    $fh=fopen("diagram.xml","w");
+    fputs($fh, stripslashes($xml));
+    fclose($fh);
+}
+?>
+```
+
+To set the URL to post to, change the respective entry in the `Editor` node of the config file as follows:
+
+```xml
+<Editor urlPost="http://www.example.com/server.php" ... >
+```
+
+Keep in mind that the JavaScript can only post to the server where it originated from, so we recommend to use relative URLs, e.g. `server.php`.
+
+<a id="FormFields"></a>
+## Form Fields
+
+If you need to read/write the graph from/to a string (e.g. to fill a form-field), you can use the following methods:
+
+```javascript
+const data = editor.writeGraphModel();
+editor.readGraphModel(xmlUtils.parseXml(data));
+```
diff --git a/packages/website/docs/tutorials/editor.md b/packages/website/docs/tutorials/editor.md
@@ -0,0 +1,115 @@
+---
+sidebar_position: 3
+description: Learn how to use the maxGraph Editor.
+---
+
+# Editor
+
+:::warning
+
+The content of this page is a **work in progress**.
+The original `mxGraph` tutorial was used to create this page which still contains `mxGraph` class diagrams to migrate to the maxGraph API.
+
+:::
+
+:::note
+
+This tutorial is licensed under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/). \
+It is adapted from the original [mxGraph tutorial](https://github.com/jgraph/mxgraph/blob/v4.2.2/docs/tutorial.html).
+
+> Copyright 2021-present The maxGraph project Contributors \
+Copyright (c) JGraph Ltd 2006-2017
+
+:::
+
+
+Instantiate [Editor](https://maxgraph.github.io/maxGraph/api-docs/classes/Editor.html) in order to create an editor.
+This is the central class in the editor package. Everything else in this package is auxiliary.
+
+To create a new editor instance and configure it using a config file, you can pass the name of the config file to the
+[Editor constructor](https://maxgraph.github.io/maxGraph/api-docs/classes/Editor.html).
+
+![Class diagram showing the Editor class hierarchy and its relationships](assets/graphs/editor.png)
+
+To create a new editor instance and configure it, the following code is used:
+
+```javascript
+import { load } from '@maxgraph/core';
+const config = load('editors/config/keyhandler-commons.xml').getDocumentElement();
+const editor = new Editor(config);
+```
+
+The configuration file is an XML file that is passed to [Codec](https://maxgraph.github.io/maxGraph/api-docs/classes/Codec.html),
+which in turn uses [EditorCodec](https://maxgraph.github.io/maxGraph/api-docs/classes/EditorCodec.html) and others to read the XML into the editor object hierarchy.
+
+This is normally done at startup time to configure the editor, graph, model, toolbar, popupmenus, etc. using the [I/O subsystem](./editor-input-output.md).
+
+
+<a id="CSS"></a>
+## CSS
+
+The CSS stylesheet contains the style definitions for various elements of the user interface, such as the rubberband selection,
+the in-place editor or the popup menu.
+
+Additional stylesheets may either be added via a stylesheet tag of the UI section in the editor configuration, e.g.:
+
+
+```xml
+<Editor>
+  <ui>
+    <stylesheet name="examples/editors/css/process.css"/>
+  </ui>
+</Editor>
+```
+
+
+<a id="Templates"></a>
+## Templates
+
+To add new cell types, create a template in the templates array section of the model in the config file (Editor/Graph/GraphDataModel/Array[as=templates]) as follows:
+
+```xml
+<add as="symbol">
+  <Symbol label="Symbol" customAttribute="whatever">
+    <Cell vertex="1" connectable="true">
+      <Geometry as="geometry" width="32" height="32"/>
+      <Object fillColor="green" image="images/event.png" as="style">
+        <Array as="baseStyleNames">
+          <add value="symbol" />
+        </Array>
+      </Object>        
+    </Cell>
+    <CustomChild customAttribute="whatever"/>
+  </Symbol>
+</add>
+```
+
+The `as`-attribute of the `add`-element contains the name under which the template will be accessible for later use.
+The `Symbol`-child element is a custom (ie workflow) element, and can have any name and any number of child elements and custom attributes.
+
+The label attribute is a special one that is used for the textual representation of the cell in the graph.
+The `Cell` element is another special child node which contains the graphical information for the cell, namely, the cell-type, -style, -size and -position.
+
+See `Graph.convertValueToString` if you would like to use another attribute or a combination of attributes for the textual representation,
+and `Cell.valueChanged` to handle in-place editing by storing the new text value in the respective attribute(s).
+
+
+<a id="Toolbar"></a>
+## Toolbar
+
+
+To use the template in the graph, a toolbar item must be added which refers to the template in the `DefaultToolbar` section
+of the config file (Editor/DefaultToolbar[as=toolbar]) as follows:
+
+```xml
+<add as="symbolTool" template="symbol"
+  style="symbol;image=wf/images/bpmn/special_event.png"
+  icon="wf/images/bpmn/small_event.gif"/>
+```
+
+The `as` attribute specifies the tooltip to be displayed for the icon in the toolbar, the `template`-attribute refers to the name under which the template was previously added.
+The `style`- attribute is optional, and may be used to override the style defined in the template definition.
+Finally, the icon specifies the icon to be used for the toolbar item.
+
+Note that the `as` attribute is assumed to be the key for a language resource, in this case `symbolTool`.
+If the resource is not defined in [Translations resources](https://maxgraph.github.io/maxGraph/api-docs/classes/Translations.html#resources), then the attribute value is used as the label.