Skip to content

migrate-from-mxgraph.md

Latest commit

 

History

History
481 lines (328 loc) · 15.9 KB

migrate-from-mxgraph.md

File metadata and controls

481 lines (328 loc) · 15.9 KB

Migration guide: mxGraph to maxGraph

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
  2. General guidelines
  3. Specific code changes

Note: ⚠️⚠️⚠️ This page is under construction. ⚠️⚠️⚠️
Comments are welcome by creating an issue or starting a discussion!.

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 problems.

The main changes are the removal of support for Internet Explorer (including VML support) and Legacy Edge.

Application setup

To migrate your application setup from mxGraph to maxGraph, follow these steps:

Replace the mxgraph dependency with maxgraph@core

  • Remove the mxgraph dependency from your project:
npm uninstall mxgraph
  • Install the maxgraph@core dependency:
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:

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:

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:

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:

"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.

General Guidelines

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 maxGraph#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

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.

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

// Old constructor
const canvas = new mxgraph.mxSvgCanvas2D(element);

Now

// 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

format:(value: string) => number

Now

format:(value: number) => number

mxGraph

The mxGraph class has been renamed to Graph in maxGraph. There have also been some changes related to properties and methods.

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

// Old way to access panningHandler
const panningHandler = graph.panningHandler;

Now

// 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

// Old way of accessing the model
const model = graph.getModel();

Now

// 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

// 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

// 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 maxGraph#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: maxGraph#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: maxGraph#70

mxDictionary -> 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 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).

Property names and values are generally the same as in mxGraph. The ones that change are listed below.

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
  • backgroundOutline (as of maxgraph@0.2.0)
  • bendable
  • cloneable
  • curved
  • dashed
  • deletable
  • editable
  • endFill
  • entryPerimeter
  • exitPerimeter
  • fixDash
  • flipH
  • flipV
  • foldable
  • glass
  • horizontal
  • imageAspect
  • movable
  • noEdgeStyle
  • noLabel
  • orthogonal
  • orthogonalLoop
  • pointerEvents
  • resizable
  • resizeHeight
  • resizeWidth
  • rotatable
  • rounded
  • 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 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)

style['propertyName1'] = value1
style.propertyName2 = value2

If you used mxConstants, remove it and use named properties instead.

// 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

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

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

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 paragraph.

Migration example

// Before
graph.insertVertex(..., 'style1;style2;shape=cylinder;strokeWidth=2;fillColor:#ffffff');
// 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.

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: maxGraph#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.