Skip to main content

Migrate from mxGraph

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
warning

This page is under construction.

Comments are welcome by creating an issue or starting a discussion!.

Feel free to create a Pull Request to enrich the content or fix errors.

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.

The initial description of the changes has been described in Pull Request #70.

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
info

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

A wide range of information is available in [Pull Request #70] (https://github.com/maxGraph/maxGraph/pull/70) to explain the reasons for some of the major changes.

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:

  • mxConnector should be updated to ConnectorShape.
  • mxEllipse should be updated to EllipseShape.
  • mxImageShape should be updated to ImageShape.
  • mxRectangleShape should be updated to RectangleShape.
  • mxMarker should be updated to MarkerShape.
  • mxRhombus should be updated to RhombusShape.
  • mxStencil should be updated to StencilShape.
  • mxText should be updated to TextShape.

Additionally, some shape properties have been renamed:

  • The strokewidth property should now be replaced by strokeWidth.

mxStencil to StencilShape​

In maxGraph@0.11.0, the allowEval and defaultLocalized properties have been removed. Configure these properties using StencilShapeConfig.

mxUtils split​

Several functions in mxUtils have been moved to their own namespaces in maxGraph. Some remain in utils.

Here are a few examples of the methods that have been moved.

domUtils​

  • extractTextWithWhitespace(): Update your code to use domUtils.extractTextWithWhitespace() instead of mxUtils.extractTextWithWhitespace().

mathUtils​

  • getBoundingBox(): Update your code to use mathUtils.getBoundingBox() instead of mxUtils.getBoundingBox().
  • getPortConstraints(): Update your code to use mathUtils.getPortConstraints() instead of mxUtils.getPortConstraints().
  • getRotatedPoint(): Update your code to use mathUtils.getRotatedPoint() instead of mxUtils.getRotatedPoint().

printUtils​

  • printScreen(): Update your code to use printUtils.printScreen() instead of mxUtils.printScreen().
  • show(): Update your code to use printUtils.show() instead of mxUtils.show().

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

Removed methods from mxUtils​

note

This list is not intended to be exhaustive

The following methods of mxUtils have been removed without replacements in maxGraph. Use your own implementation or 3rd party libraries instead:

  • mxUtils.button
  • mxUtils.error
  • mxUtils.prompt: use window.prompt instead. The mxGraph method was just a wrapper around window.prompt to manage nullish values. See the mxUtils.prompt for more details.

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);

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.

Some properties have been removed in favor of the usage of plugins. Plugins are registered at the Graph initialization by passing an array of plugins to the constructor.

property removedmethod removednew plugin
cellEditorcreateCellEditorCellEditorHandler
connectionHandlercreateConnectionHandlerConnectionHandler
graphHandlercreateGraphHandlerSelectionHandler
panningHandlercreatePanningHandlerPanningHandler
popupMenuHandlercreatePopupMenuHandlerPopupMenuHandler
selectionCellsHandlercreateSelectionCellsHandlerSelectionCellsHandler
tooltipHandlercreateTooltipHandlerTooltipHandler

Example of migration with the 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 });

Folding properties​

The following folding properties have been removed:

  • collapsedImage
  • collapseToPreferredSize
  • expandedImage
  • foldingEnabled

They are now set in the Graph.options object with the same property name.

For example, to set the foldingEnabled property, instead of doing Graph.foldingEnabled, you should set instead Graph.options.foldingEnabled.

Other properties​

  • the tolerance property has been renamed (and the get/set method as well). It is now named snapTolerance.

mxResources​

The mxResources class has been renamed to Translations in maxGraph.

mxClient​

The mxClient class has been renamed to Client.

Removed properties

  • defaultBundles
  • mxForceIncludes: it was used to force loading the JavaScript files in development mode in mxGraph. We are not managing development mode in that way anymore.
  • mxLoadResources: not used anymore
  • mxLoadStylesheets: not used anymore
  • mxResourceExtension: it was only used in Translations, so only keep the property in Translations

Removed methods

  • setForceIncludes: the mxForceIncludes property has been removed
  • setLoadResources: the mxLoadResources property has been removed
  • setLoadStylesheets: the mxLoadStylesheets property has been removed
  • setResourceExtension: the mxResourceExtension property has been removed

Moved methods

  • link method moved and renamed domUtils.addLinkToHead

mxConstants​

The mxConstants value object has been replaced by the constants namespace.

The properties prefixed by STYLE_ like mxConstants.STYLE_FILLCOLOR have been removed because they are no longer used. See the Styling Properties paragraph for a replacement.

The other properties are still available.

warning

In mxGraph, the constants were used everywhere in the code and changing them would have a global effect.

In maxGraph, it is no longer possible to update the value of the properties in the constants namespace. There are global configuration objects that allow to set the default values previously defined in mxConstants and these configurations are used everywhere in the code.

But it is possible to configure their values globally. See the Global Configuration documentation for more details.

Cell manipulation​

Some methods previously available in mxGraph and mxGraphModel have been removed. These methods allowed for customizing the behavior of mxGraphModel and mxCell. However, now only the methods specific to Cell remain.

note

You can find more information about these changes in the GitHub Pull Request #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. See the paragraph about "Migration of specific style properties applied to dedicated cells" for more details about how to migrate the style property.

mxGraph​

Some methods were removed:

mxGraphModel​

Several methods from the mxGraphModel class have been moved to the Cell class. These methods no longer need the cell parameter:

  • filterDescendants()
  • getGeometry()
  • getParent(cell), use Cell.getParent() instead
  • isAncestor(parent, child), use Cell.isAncestor(child) instead
  • isEdge()

Some methods in mxGraphModel that were general manipulation of cells and independent of the model have been moved to the cellArrayUtils namespace and are now available as individual functions.

  • cloneCell() (from version 0.11.0)
  • cloneCells()
  • getOpposite()
  • getParents()
  • getTopmostCells()

Others were removed:

  • cloneImpl()
  • isVisible(cell) see discussion #179 for rationale
  • restoreClone() (from version 0.11.0)

Misc​

  • Codec renaming and output: see Pull Request #70
  • mxCellEditor to CellEditorHandler
  • mxDictionary<T> to Dictionary<K, V>
  • mxRubberband to RubberBandHandler
  • mxVertexHandler.rotationEnabled has been removed. Use VertexHandlerConfig.rotationEnabled instead (since 0.12.0).

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 InternalEvent.PAN_START property instead of mxEvent.PAN_START.
  • Use the InternalEvent.PAN_END property instead of mxEvent.PAN_END.
  • Use the InternalEvent.addMouseWheelListener() method instead of mxEvent.addMouseWheelListener().
  • Use the InternalEvent.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. The usage of mxConstants.STYLE_* strings is replaced by the object properties (see Pull Request #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
  • portConstraintRotation
  • resizable
  • resizeHeight
  • resizeWidth
  • rotatable
  • rounded
  • shadow
  • startFill
  • swimlaneLine

Migration of default styles defined with StyleSheet​

mxGraph stylesheet​

What is a StyleSheet?

The appearance of the cells in a graph is defined by the stylesheet, which is an instance of mxStylesheet. The stylesheet maps from style names to styles.

See also

maxGraph stylesheet​

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 the Styling Properties paragraph.

warning

Be aware of the properties that have been renamed or whose value types have changed, as described in the Styling Properties 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​

mxGraph style​

A style is an array of key, value pairs to be used with the cells.

mxGraph line 50

For a named style, the style name 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 longer 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.

For more details about styles in maxGraph, see the Styles documentation manual.

warning

Be aware of the properties that have been renamed or whose value types have changed, as described in the Styling Properties paragraph.

Migration example

If you want to write code to migrate mxGraph to maxGraph style, you can have a look at packages/core/src/serialization/codecs/mxGraph/utils.ts.

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

From version 0.11.0 of maxGraph, you can replicate this behavior by setting ignoreDefaultStyle to true in the CellStyle object.

Codecs​

warning

From version 0.6.0 of maxGraph, codecs supplied by maxGraph are no longer registered by default, they ** MUST** be registered before performing an encode or decode

For example:

  • You can use the registerCoreCodecs function (or other related functions) to register codecs.
  • To serialize the maxGraph model, you can use the ModelXmlSerializer class, which registers codecs under the hood.

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.