docs: improve the mxGraph migration guide (#206)
Added paragraphs - classes renames - moved methods - how-to migrating styles --------- Co-authored-by: Souchet Céline <celine.souchet@bonitasoft.com>development
Thomas Bouffard
GitHub
parent
452698660b
commit
926596722c
|
|
@ -1,43 +1,345 @@
|
|||
# Migrate from mxGraph
|
||||
# Migration guide: mxGraph to maxGraph
|
||||
|
||||
**This page is a work in progress. Comments are welcome by creating an [issue](https://github.com/maxGraph/maxGraph/issues)
|
||||
or opening a [discussion](https://github.com/maxGraph/maxGraph/discussions/categories/q-a).!**
|
||||
This documentation provides instructions for migrating from `mxGraph` to `maxGraph`.
|
||||
It includes information about application setup changes, code changes, styles, event handling and other relevant information.
|
||||
|
||||
Here's a breakdown of the proposed changes:
|
||||
|
||||
1. [Application setup](#application-setup)
|
||||
2. [General guidelines](#general-guidelines)
|
||||
3. [Specific code changes](#specific-code-changes)
|
||||
|
||||
> **Note:** **⚠️⚠️⚠️ This page is under construction. ⚠️⚠️⚠️
|
||||
Comments are welcome by creating an [issue](https://github.com/maxGraph/maxGraph/issues)
|
||||
or starting a [discussion](https://github.com/maxGraph/maxGraph/discussions/categories/q-a)!**.
|
||||
|
||||
The `maxGraph` APIs are not fully compatible with the `mxGraph` APIs, but the `maxGraph` APIs are close to the former `mxGraph` APIs.
|
||||
The concepts are the same, so experienced _mxGraph_ users should be able to switch from _mxGraph_ to _maxGraph_ without issues.
|
||||
The concepts are the same, so experienced `mxGraph` users should be able to switch from `mxGraph` to `maxGraph` without problems.
|
||||
|
||||
The major changes are the removal of support for Internet Explorer (including VML support) and Legacy Edge.
|
||||
The main changes are the removal of support for Internet Explorer (including VML support) and Legacy Edge.
|
||||
|
||||
|
||||
## Application setup
|
||||
|
||||
Remove the
|
||||
- `mxgraph` dependency and add `maxgraph@core` instead.
|
||||
- _mxGraph_ initialization code using the `factory` function. Access _maxGraph_ objects directly.
|
||||
To migrate your application setup from `mxGraph` to `maxGraph`, follow these steps:
|
||||
|
||||
### TypeScript
|
||||
### Replace the `mxgraph` dependency with `maxgraph@core`
|
||||
|
||||
Remove the
|
||||
- `@typed-mxgraph/typed-mxgraph` dependency in the `package.json` file
|
||||
- `typeroots` settings related to `typed-mxgraph` in the `tsconfig.json` file
|
||||
- Remove the `mxgraph` dependency from your project:
|
||||
```shell
|
||||
npm uninstall mxgraph
|
||||
```
|
||||
|
||||
As an example, you can check [this project](https://github.com/maxGraph/maxgraph-integration-examples/tree/main/projects/rollup-ts) which has been migrated
|
||||
from a [typed-mxgraph example](https://github.com/typed-mxgraph/typed-mxgraph-example-bundled-with-rollup).
|
||||
- Install the `maxgraph@core` dependency:
|
||||
```shell
|
||||
npm install maxgraph@core
|
||||
```
|
||||
ℹ️ The `maxgraph@core` package contains the core functionality of `maxGraph`.
|
||||
|
||||
### Initialize `maxGraph`
|
||||
|
||||
In your application setup code, replace the `mxGraph` initialization code that uses the `factory` function with direct access to `maxGraph` objects.
|
||||
|
||||
For example, if you had code like this in `mxGraph`:
|
||||
|
||||
```typescript
|
||||
import factory from 'mxgraph';
|
||||
|
||||
const mxgraph = factory({});
|
||||
const graph = mxgraph.mxGraph(container);
|
||||
|
||||
const point = new mxgraph.mxPoint(10, 50);
|
||||
// ... more initialization code
|
||||
```
|
||||
|
||||
Replace it with the corresponding code in `maxGraph`:
|
||||
|
||||
```typescript
|
||||
import { Graph } from 'maxgraph';
|
||||
|
||||
const graph = new Graph(container);
|
||||
|
||||
const point = new Point(10, 50);
|
||||
// ... more initialization code
|
||||
```
|
||||
|
||||
### TypeScript Setup
|
||||
|
||||
#### Remove the `typed-mxgraph` dependency
|
||||
|
||||
If you used the `@typed-mxgraph/typed-mxgraph` dependency in your project, remove it from your `package.json` file:
|
||||
|
||||
```shell
|
||||
npm uninstall @typed-mxgraph/typed-mxgraph
|
||||
```
|
||||
|
||||
#### Remove `typeroots` settings
|
||||
|
||||
Remove any `typeroots` settings related to `typed-mxgraph` from your `tsconfig.json` file.
|
||||
|
||||
For example, if you have a configuration like this:
|
||||
|
||||
```json
|
||||
"typeroots": ["./node_modules/@types", "./node_modules/@typed-mxgraph/typed-mxgraph", ...]
|
||||
```
|
||||
|
||||
Remove `"./node_modules/@typed-mxgraph/typed-mxgraph"`.
|
||||
|
||||
If you only configured `typeroots` to add the `typed-mxgraph` types, remove the line to restore the [TypeScript defaults](https://www.typescriptlang.org/tsconfig/#typeRoots).
|
||||
|
||||
|
||||
## General guidelines
|
||||
## General Guidelines
|
||||
|
||||
- The names of _mxGraph_ objects were all prefixed with `mx`. The prefix has been dropped in _maxGraph_.
|
||||
- Most names remain the same.
|
||||
- Some utility functions, whose implementation is natively available in modern versions of ECMAScript, have been removed.
|
||||
Here are some general guidelines to keep in mind when migrating from `mxGraph` to `maxGraph`:
|
||||
|
||||
- The names of `mxGraph` objects were all prefixed with `mx`. This prefix has been dropped in `maxGraph`.
|
||||
- Most names remain the same, but some utility functions whose implementation is natively available in modern versions of ECMAScript have been removed.
|
||||
|
||||
## Specific code changes
|
||||
|
||||
This section outlines specific code changes required when migrating from `mxGraph` to `maxGraph`.
|
||||
Please update your code accordingly.
|
||||
|
||||
> **Note:** Much information is available at https://github.com/maxGraph/maxGraph/pull/70.
|
||||
|
||||
### Overlay
|
||||
The `strokewidth` property has been renamed to `strokeWidth` in `maxGraph`.
|
||||
|
||||
### Shape
|
||||
|
||||
The shape names in `maxGraph` have been updated to have a consistent postfix. Please update the shape names in your code as follows:
|
||||
|
||||
- `mxRectangleShape` should be updated to `RectangleShape`.
|
||||
- `mxImageShape` should be updated to `ImageShape`.
|
||||
- `mxEllipse` should be updated to `EllipseShape`.
|
||||
- `mxRhombus` should be updated to `RhombusShape`.
|
||||
- `mxMarker` should be updated to `MarkerShape`.
|
||||
- `mxConnector` should be updated to `ConnectorShape`.
|
||||
- `mxText` should be updated to `TextShape`.
|
||||
|
||||
Additionally, some shape properties have been renamed:
|
||||
|
||||
- The `strokewidth` property should now be replaced by `strokeWidth`.
|
||||
|
||||
### `mxUtils` split
|
||||
Several functions in `mxUtils` have been moved to their own namespaces in `maxGraph`. Some remain in `utils`.
|
||||
|
||||
#### `domUtils`
|
||||
- `extractTextWithWhitespace()`: : Update your code to use `domUtils.extractTextWithWhitespace()` instead of `mxUtils.extractTextWithWhitespace()`.
|
||||
|
||||
#### `stringUtils`
|
||||
- `trim()`: Update your code to use `stringUtils.trim()` instead of `mxUtils.trim()`.
|
||||
|
||||
#### `styleUtils`
|
||||
- `convertPoint()`: Update your code to use `styleUtils.convertPoint()` instead of `mxUtils.convertPoint()`.
|
||||
|
||||
#### `xmlUtils`
|
||||
- `getXml`(): Update your code to use `xmlUtils.getXml()` instead of `mxUtils.getXml()`.
|
||||
- `createXmlDocument()`: Update your code to use `xmlUtils.createXmlDocument()` instead of `mxUtils.createXmlDocument()`.
|
||||
|
||||
### `mxAbstractCanvas2D`
|
||||
|
||||
The `mxAbstractCanvas2D` class has been renamed to `AbstractCanvas2D` in `maxGraph`, and there is a parameter type change in one of its methods.
|
||||
|
||||
#### `arcTo()`
|
||||
|
||||
The `arcTo()` method in `AbstractCanvas2D` has updated parameter types. The `largeArcFlag` and `sweepFlag` parameters, which were previously of type `number`, are now of type `boolean`.
|
||||
Here is the updated signature:
|
||||
|
||||
**Before**
|
||||
```typescript
|
||||
arcTo:(rx: number, ry: number, angle: number, largeArcFlag: number, sweepFlag: number, x: number, y: number) => void
|
||||
```
|
||||
|
||||
**Now**
|
||||
Some `number` parameters that took the `0` or `1` values have been transformed into `boolean` parameters.
|
||||
```typescript
|
||||
arcTo:(rx: number, ry: number, angle: number, largeArcFlag: boolean, sweepFlag: boolean, x: number, y: number) => void
|
||||
```
|
||||
|
||||
### `mxSvgCanvas2D`
|
||||
|
||||
The `mxSvgCanvas2D` class has been renamed to `SvgCanvas2D` in `maxGraph`.
|
||||
|
||||
#### Constructor
|
||||
|
||||
The constructor parameter has been updated. Instead of accepting an `Element`, it now expects a `SvgElement` and a `boolean` value.
|
||||
|
||||
**Before**
|
||||
```typescript
|
||||
// Old constructor
|
||||
const canvas = new mxgraph.mxSvgCanvas2D(element);
|
||||
```
|
||||
|
||||
**Now**
|
||||
```typescript
|
||||
// Updated constructor
|
||||
const canvas = new SvgCanvas2D(svgElement, oneBoolean);
|
||||
```
|
||||
|
||||
#### `getAlternateText()`
|
||||
|
||||
change types ???????
|
||||
|
||||
#### `format()`
|
||||
|
||||
The `value` parameter, which was previously of type `string`, is now of type `number`.
|
||||
|
||||
**Before**
|
||||
```typescript
|
||||
format:(value: string) => number
|
||||
```
|
||||
|
||||
**Now**
|
||||
```typescript
|
||||
format:(value: number) => number
|
||||
```
|
||||
|
||||
|
||||
## Style related properties
|
||||
### `mxGraph`
|
||||
|
||||
Property rename
|
||||
- `autosize` into `autoSize` (as of maxgraph@0.2.0)
|
||||
The `mxGraph` class has been renamed to `Graph` in `maxGraph`.
|
||||
There have also been some changes related to properties and methods.
|
||||
|
||||
Property type change from `number` (0 or 1) to `boolean` (if not specified, as of maxgraph@0.1.0):
|
||||
#### `panningHandler` property
|
||||
|
||||
The `panningHandler` property has been removed and replaced by a plugin. Instead of accessing `panningHandler` directly, you can use the `getPlugin()` method to get the `PanningHandler` plugin instance. Here's an example:
|
||||
|
||||
**Before**
|
||||
```typescript
|
||||
// Old way to access panningHandler
|
||||
const panningHandler = graph.panningHandler;
|
||||
```
|
||||
|
||||
**Now**
|
||||
```typescript
|
||||
// Updated way using getPlugin()
|
||||
const panningHandler = this.graph.getPlugin('PanningHandler') as PanningHandler;
|
||||
```
|
||||
|
||||
#### `getModel()`
|
||||
|
||||
Instead of calling `getModel()` that returned an instance of `mxGraphModel`, call `getDataModel` which returns an instance of `GraphDataModel`.
|
||||
Here's an example:
|
||||
|
||||
**Before**
|
||||
```typescript
|
||||
// Old way of accessing the model
|
||||
const model = graph.getModel();
|
||||
```
|
||||
|
||||
**Now**
|
||||
```typescript
|
||||
// Updated way to access the model
|
||||
const model = graph.getDataModel();
|
||||
```
|
||||
|
||||
#### `insertVertex()` and `insertEdge()`
|
||||
|
||||
The `insertVertex()` and `insertEdge()` methods in `maxGraph` now also accept one object as parameter instead of multiple parameters. Instead of passing individual parameters, you can pass an object containing all the required properties.
|
||||
|
||||
The former methods having several parameters still exist but the new signature should be used instead.
|
||||
|
||||
Here's an example:
|
||||
|
||||
**Before**
|
||||
```typescript
|
||||
// Old way of using insertVertex()
|
||||
graph.insertVertex(parent, id, value, x, y, width, height, style);
|
||||
|
||||
// Old way of using insertEdge()
|
||||
graph.insertEdge(parent, id, value, source, target, style);
|
||||
```
|
||||
|
||||
**Now**
|
||||
```typescript
|
||||
// New way to use an object parameter for insertVertex()
|
||||
graph.insertVertex({ parent, id, value, x, y, width, height, style });
|
||||
|
||||
// New way to use an object parameter for insertEdge()
|
||||
graph.insertEdge({ parent, id, value, source, target, style });
|
||||
```
|
||||
|
||||
|
||||
### Client
|
||||
renamed properties: TODO which
|
||||
|
||||
|
||||
### Cell manipulation
|
||||
Functions that existed in mxGraph and mxGraphModel have been removed. They provided a way to extend/override the default behavior of mxGraphModel or mxCell.
|
||||
Only the functions for mxCell/Cell remain. See https://github.com/maxGraph/maxGraph/pull/24
|
||||
|
||||
|
||||
Some functions previously available in `mxGraph` and `mxGraphModel` have been removed. These functions allowed for customizing the behavior of `mxGraphModel` and `mxCell`. However, now only the functions specific to `mxCell`/`Cell` remain.
|
||||
ℹ️ You can find more information about these changes in the following GitHub pull request: https://github.com/maxGraph/maxGraph/pull/24.
|
||||
|
||||
#### `mxCell`
|
||||
|
||||
The `mxCell` class has been renamed to `Cell` for simplicity.
|
||||
|
||||
The `style` property of `Cell` has undergone a type change from `string` to `CellStyle`.
|
||||
|
||||
|
||||
#### `mxGraphDataModel`
|
||||
|
||||
Several functions from the `mxGraphDataModel` class have been moved to the `Cell` class. These functions no longer need the `cell` parameter:
|
||||
|
||||
- `filterDescendants()`
|
||||
- `getGeometry()`
|
||||
- `isEdge()`
|
||||
- `getParent()`
|
||||
|
||||
|
||||
### Misc
|
||||
|
||||
Codec renaming and output: https://github.com/maxGraph/maxGraph/pull/70
|
||||
|
||||
mxDictionary<T> -> Dictionary<K, V>
|
||||
|
||||
### Event handling
|
||||
|
||||
The event handling mechanism in `maxGraph` has been updated. Use the following guidelines to update your event handling code:
|
||||
|
||||
- `mxEvent` has been replaced by `eventUtils` and `InternalEvent` for most event-related operations.
|
||||
- `mxMouseEvent` has been replaced by `InternalMouseEvent`.
|
||||
|
||||
#### `eventUtils`
|
||||
- Use the `eventUtils.isMultiTouchEvent()` method, to detect touch events, instead of `mxEvent.isMultiTouchEvent()`.
|
||||
- Use the `eventUtils.isLeftMouseButton()` method, to detect mouse events, instead of `mxEvent.isLeftMouseButton()`.
|
||||
|
||||
#### `InternalEvent`
|
||||
- Use the `eventUtils.PAN_START` property instead of `mxEvent.PAN_START`.
|
||||
- Use the `eventUtils.PAN_END` property instead of `mxEvent.PAN_END`.
|
||||
- Use the `eventUtils.addMouseWheelListener()` method instead of `mxEvent.addMouseWheelListener()`.
|
||||
- Use the `eventUtils.consume()` method instead of `mxEvent.consume()`.
|
||||
|
||||
|
||||
### Styling
|
||||
|
||||
`mxGraph`
|
||||
- Default styles defined with `mxStyleSheet`.
|
||||
- Style of a Cell: a string containing all properties and values, using a specific syntax and delimiter.
|
||||
- Style of a State Cell: a `StyleMap` instance (See [StyleMap](https://github.com/typed-mxgraph/typed-mxgraph/blob/187dd4f0dc7644c0cfbc998dae5fc90879597d81/lib/view/mxStylesheet.d.ts#L2-L4) as a `typed-mxgraph` type).
|
||||
|
||||
`maxGraph`
|
||||
- Default styles defined via `StyleSheet`.
|
||||
- Style of a Cell: a dedicated `CellStyle` object that reuses the same properties as the string form used by mxGraph (see below for changes).
|
||||
- Style of a State Cell: a `CellStateStyle` instance.
|
||||
|
||||
|
||||
#### Properties
|
||||
|
||||
In `mxGraph`, the properties are defined as string. The property keys are defined in `mxConstants` and are prefixed by `STYLE_` like `mxConstants.STYLE_FILLCOLOR`.
|
||||
|
||||
In `maxGraph`, they are object properties. `mxConstants.STYLE_*` have been replaced by the object properties (see PR [#31](https://github.com/maxGraph/maxGraph/pull/31)).
|
||||
|
||||
Property names and values are generally the same as in `mxGraph`. The ones that change are listed below.
|
||||
|
||||
<a name="style-properties-change"></a>
|
||||
Property renaming
|
||||
- `autosize` to `autoSize` (from maxgraph@0.2.0)
|
||||
|
||||
Property type changed from `number` (0 or 1) to `boolean` (if not specified, from maxgraph@0.1.0):
|
||||
- `anchorPointDirection`
|
||||
- `absoluteArcSize` (as of maxgraph@0.2.0)
|
||||
- `autosize`
|
||||
|
|
@ -72,3 +374,108 @@ Property type change from `number` (0 or 1) to `boolean` (if not specified, as o
|
|||
- `shadow`
|
||||
- `startFill`
|
||||
- `swimlaneLine`
|
||||
|
||||
|
||||
|
||||
### Migration of default styles defined with StyleSheet
|
||||
|
||||
**TODO: what is a StyleSheet? link to JSDoc/code**
|
||||
|
||||
The migration consists of converting [`StyleMap`](https://github.com/typed-mxgraph/typed-mxgraph/blob/187dd4f0dc7644c0cfbc998dae5fc90879597d81/lib/view/mxStylesheet.d.ts#L2-L4) objects to `CellStyle` objects.
|
||||
|
||||
If you have been using string or named properties, you can keep that syntax.
|
||||
You just need to rename the property or update its value as described in (TODO anchor to properties change paragraph)
|
||||
```ts
|
||||
style['propertyName1'] = value1
|
||||
style.propertyName2 = value2
|
||||
```
|
||||
|
||||
If you used `mxConstants`, remove it and use named properties instead.
|
||||
```ts
|
||||
// mxGraphStyle is a StyleMap
|
||||
mxGraphStyle[mxConstants.STYLE_STARTSIZE] = 8
|
||||
|
||||
// maxGraph style is a CellStyle
|
||||
style['startSize'] = 8;
|
||||
// or
|
||||
style.startSize = 8;
|
||||
```
|
||||
|
||||
|
||||
### Migration of specific style properties applied to dedicated cells
|
||||
|
||||
- **TODO: what is a style? link to JSDoc/code**
|
||||
|
||||
#### `mxGraph` style
|
||||
|
||||
[mxGraph line 50](https://github.com/jgraph/mxgraph/blob/v4.2.2/javascript/src/js/view/mxGraph.js#L50-L62)
|
||||
|
||||
> For a named style, the the stylename must be the first element
|
||||
of the cell style:
|
||||
(code)
|
||||
stylename;image=http://www.example.com/image.gif
|
||||
(end)
|
||||
A cell style can have any number of key=value pairs added, divided
|
||||
by a semicolon as follows:
|
||||
(code)
|
||||
[stylename;|key=value;]
|
||||
(end)
|
||||
|
||||
[mxGraph line 167](https://github.com/jgraph/mxgraph/blob/v4.2.2/javascript/src/js/view/mxGraph.js#L167-L171)
|
||||
|
||||
> Styles are a collection of key, value pairs and a stylesheet is a collection
|
||||
of named styles. The names are referenced by the cellstyle, which is stored
|
||||
in <mxCell.style> with the following format: [stylename;|key=value;]. The
|
||||
string is resolved to a collection of key, value pairs, where the keys are
|
||||
overridden with the values in the string.
|
||||
>
|
||||
|
||||
See also
|
||||
- https://jgraph.github.io/mxgraph/docs/tutorial.html#3.3
|
||||
- https://jgraph.github.io/mxgraph/docs/manual.html#3.1.3.1
|
||||
|
||||
|
||||
#### `maxGraph` style
|
||||
|
||||
In maxGraph, the style is no more defined as a string but as a `CellStyle` object.
|
||||
|
||||
Most of the time, the name of `CellStyle` properties is the same as the style keys in the mxGraph style.
|
||||
|
||||
⚠️⚠️⚠ **WARNING**: Be aware of the properties that have been renamed or whose value types have changed, as described in the [style-properties-change](./migrate-from-mxgraph.md#style-properties-change) paragraph.
|
||||
|
||||
|
||||
**Migration example**
|
||||
|
||||
|
||||
```js
|
||||
// Before
|
||||
graph.insertVertex(..., 'style1;style2;shape=cylinder;strokeWidth=2;fillColor:#ffffff');
|
||||
```
|
||||
|
||||
|
||||
```js
|
||||
// Now using the insertVertex method taking a single parameter
|
||||
graph.insertVertex({
|
||||
...
|
||||
style: {
|
||||
baseStyleNames: ['style1', 'style2']
|
||||
shape: 'cylinder',
|
||||
strokeWidth: 2,
|
||||
fillColor: '#ffffff'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**Special migration case**
|
||||
In `mxGraph`, to not merge properties of the default style, the style string must start with a `;` (semicolon) as in `;style1;style2;prop1=value1;.....`.
|
||||
This is documented in the [mxStylesheet documentation](jgraph/mxgraph@v4.2.2/javascript/src/js/view/mxStylesheet.js#L33-L38).
|
||||
> To override the default style for a cell, add a leading semicolon to the style definition, e.g. ;shadow=1
|
||||
|
||||
This is currently not supported in maxGraph: https://github.com/maxGraph/maxGraph/issues/154 "Add a way to not use default style properties when calculating cell styles".
|
||||
|
||||
|
||||
## Conclusion
|
||||
|
||||
By following these guidelines and updating your codebase accordingly, you should be able to migrate your application from `mxGraph` to `maxGraph`.
|
||||
Remember to test your application thoroughly after the migration to ensure that its functionality is preserved.
|
||||
If you encounter any problems during the migration process, please refer to the `maxGraph` documentation or ask the `maxGraph` community for help.
|
||||
|
|
|
|||
Loading…
Reference in New Issue