API Specification

Overview

This JavaScript library is divided into 8 packages.  The top-level mxClient class includes (or dynamically imports) everything else.  The current version is stored in mxClient.VERSION.

The editor package provides the classes required to implement a diagram editor.  The main class in this package is mxEditor.

The view and model packages implement the graph component, represented by mxGraph.  It refers to a mxGraphModel which contains mxCells and caches the state of the cells in a mxGraphView.  The cells are painted using a mxCellRenderer based on the appearance defined in mxStylesheet.  Undo history is implemented in mxUndoManager.  To display an icon on the graph, mxCellOverlay may be used.  Validation rules are defined with mxMultiplicity.

The handler, layout and shape packages contain event listeners, layout algorithms and shapes, respectively.  The graph event listeners include mxRubberband for rubberband selection, mxTooltipHandler for tooltips and mxGraphHandler for basic cell modifications.  mxCompactTreeLayout implements a tree layout algorithm, and the shape package provides various shapes, which are subclasses of mxShape.

The util package provides utility classes including mxClipboard for copy-paste, <mxDatatransfer> for drag-and-drop, mxConstants for keys and values of stylesheets, mxEvent and mxUtils for cross-browser event-handling and general purpose functions, mxResources for internationalization and mxLog for console output.

The io package implements a generic mxObjectCodec for turning JavaScript objects into XML.  The main class is mxCodec.  mxCodecRegistry is the global registry for custom codecs.

Events

There are three different types of events, namely native DOM events, mxEventObjects which are fired in an mxEventSource, and mxMouseEvents which are fired in mxGraph.

Some helper methods for handling native events are provided in mxEvent.  It also takes care of resolving cycles between DOM nodes and JavaScript event handlers, which can lead to memory leaks in IE6.

Most custom events in mxGraph are implemented using mxEventSource.  Its listeners are functions that take a sender and mxEventObject.  Additionally, the mxGraph class fires special mxMouseEvents which are handled using mouse listeners, which are objects that provide a mousedown, mousemove and mouseup method.

Events in mxEventSource are fired using mxEventSource.fireEvent.  Listeners are added and removed using mxEventSource.addListener and mxEventSource.removeListener.  mxMouseEvents in mxGraph are fired using mxGraph.fireMouseEvent.  Listeners are added and removed using mxGraph.addMouseListener and mxGraph.removeMouseListener, respectively.

Key bindings

The following key bindings are defined for mouse events in the client across all browsers and platforms:

  • Control-Drag: Duplicates (clones) selected cells
  • Shift-Rightlick: Shows the context menu
  • Alt-Click: Forces rubberband (aka. marquee)
  • Control-Select: Toggles the selection state
  • Shift-Drag: Constrains the offset to one direction
  • Shift-Control-Drag: Panning (also Shift-Rightdrag)

Configuration

The following global variables may be defined before the client is loaded to specify its language or base path, respectively.

  • mxBasePath: Specifies the path in mxClient.basePath.
  • mxImageBasePath: Specifies the path in mxClient.imageBasePath.
  • mxLanguage: Specifies the language for resources in mxClient.language.
  • mxDefaultLanguage: Specifies the default language in mxClient.defaultLanguage.
  • mxLoadResources: Specifies if any resources should be loaded.  Default is true.
  • mxLoadStylesheets: Specifies if any stylesheets should be loaded.  Default is true.

Reserved Words

The mx prefix is used for all classes and objects in mxGraph.  The mx prefix can be seen as the global namespace for all JavaScript code in mxGraph.  The following fieldnames should not be used in objects.

  • mxObjectId: If the object is used with mxObjectIdentity
  • as: If the object is a field of another object
  • id: If the object is an idref in a codec
  • mxListenerList: Added to DOM nodes when used with mxEvent
  • window._mxDynamicCode: Temporarily used to load code in Safari and Chrome (see mxClient.include).
  • _mxJavaScriptExpression: Global variable that is temporarily used to evaluate code in Safari, Opera, Firefox 3 and IE (see mxUtils.eval).

Files

The library contains these relative filenames.  All filenames are relative to mxClient.basePath.

Built-in Images

All images are loaded from the mxClient.imageBasePath, which you can change to reflect your environment.  The image variables can also be changed individually.

  • mxGraph.prototype.collapsedImage
  • mxGraph.prototype.expandedImage
  • mxGraph.prototype.warningImage
  • mxWindow.prototype.closeImage
  • mxWindow.prototype.minimizeImage
  • mxWindow.prototype.normalizeImage
  • mxWindow.prototype.maximizeImage
  • mxWindow.prototype.resizeImage
  • mxPopupMenu.prototype.submenuImage
  • mxUtils.errorImage
  • mxConstraintHandler.prototype.pointImage

The basename of the warning image (images/warning without extension) used in mxGraph.setCellWarning is defined in mxGraph.warningImage.

Resources

The mxEditor and mxGraph classes add the following resources to mxResources at class loading time:

  • resources/editor*.properties
  • resources/graph*.properties

By default, the library ships with English and German resource files.

Images

Recommendations for using images.  Use GIF images (256 color palette) in HTML elements (such as the toolbar and context menu), and PNG images (24 bit) for all images which appear inside the graph component.

  • For PNG images inside HTML elements, Internet Explorer will ignore any transparency information.
  • For GIF images inside the graph, Firefox on the Mac will display strange colors.  Furthermore, only the first image for animated GIFs is displayed on the Mac.

For faster image rendering during application runtime, images can be prefetched using the following code:

var image = new Image();
image.src = url_to_image;

Deployment

The client is added to the page using the following script tag inside the head of a document:

<script type="text/javascript" src="js/mxClient.js"></script>

The deployment version of the mxClient.js file contains all required code in a single file.  For deployment, the complete javascript/src directory is required.

Source Code

If you are a source code customer and you wish to develop using the full source code, the commented source code is shipped in the javascript/devel/source.zip file.  It contains one file for each class in mxGraph.  To use the source code the source.zip file must be uncompressed and the mxClient.js URL in the HTML page must be changed to reference the uncompressed mxClient.js from the source.zip file.

Compression

When using Apache2 with mod_deflate, you can use the following directive in src/js/.htaccess to speedup the loading of the JavaScript sources:

SetOutputFilter DEFLATE

Classes

There are two types of “classes” in mxGraph: classes and singletons (where only one instance exists).  Singletons are mapped to global objects where the variable name equals the classname.  For example mxConstants is an object with all the constants defined as object fields.  Normal classes are mapped to a constructor function and a prototype which defines the instance fields and methods.  For example, mxEditor is a function and mxEditor.prototype is the prototype for the object that the mxEditor function creates.  The mx prefix is a convention that is used for all classes in the mxGraph package to avoid conflicts with other objects in the global namespace.

Subclassing

For subclassing, the superclass must provide a constructor that is either parameterless or handles an invocation with no arguments.  Furthermore, the special constructor field must be redefined after extending the prototype.  For example, the superclass of mxEditor is mxEventSource.  This is represented in JavaScript by first “inheriting” all fields and methods from the superclass by assigning the prototype to an instance of the superclass, eg. mxEditor.prototype = new mxEventSource() and redefining the constructor field using mxEditor.prototype.constructor = mxEditor.  The latter rule is applied so that the type of an object can be retrieved via the name of it’s constructor using mxUtils.getFunctionName(obj.constructor).

Constructor

For subclassing in mxGraph, the same scheme should be applied.  For example, for subclassing the mxGraph class, first a constructor must be defined for the new class.  The constructor calls the super constructor with any arguments that it may have using the call function on the mxGraph function object, passing along explitely each argument:

function MyGraph(container)
{
  mxGraph.call(this, container);
}

The prototype of MyGraph inherits from mxGraph as follows.  As usual, the constructor is redefined after extending the superclass:

MyGraph.prototype = new mxGraph();
MyGraph.prototype.constructor = MyGraph;

You may want to define the codec associated for the class after the above code.  This code will be executed at class loading time and makes sure the same codec is used to encode instances of mxGraph and MyGraph.

var codec = mxCodecRegistry.getCodec(mxGraph);
codec.template = new MyGraph();
mxCodecRegistry.register(codec);

Functions

In the prototype for MyGraph, functions of mxGraph can then be extended as follows.

MyGraph.prototype.isCellSelectable = function(cell)
{
  var selectable = mxGraph.prototype.isSelectable.apply(this, arguments);

  var geo = this.model.getGeometry(cell);
  return selectable && (geo == null || !geo.relative);
}

The supercall in the first line is optional.  It is done using the apply function on the isSelectable function object of the mxGraph prototype, using the special this and arguments variables as parameters.  Calls to the superclass function are only possible if the function is not replaced in the superclass as follows, which is another way of “subclassing” in JavaScript.

mxGraph.prototype.isCellSelectable = function(cell)
{
  var geo = this.model.getGeometry(cell);
  return selectable &&
      (geo == null ||
      !geo.relative);
}

The above scheme is useful if a function definition needs to be replaced completely.

In order to add new functions and fields to the subclass, the following code is used.  The example below adds a new function to return the XML representation of the graph model:

MyGraph.prototype.getXml = function()
{
  var enc = new mxCodec();
  return enc.encode(this.getModel());
}

Variables

Likewise, a new field is declared and defined as follows.

MyGraph.prototype.myField = 'Hello, World!';

Note that the value assigned to myField is created only once, that is, all instances of MyGraph share the same value.  If you require instance-specific values, then the field must be defined in the constructor instead.

function MyGraph(container)
{
  mxGraph.call(this, container);

  this.myField = new Array();
}

Finally, a new instance of MyGraph is created using the following code, where container is a DOM node that acts as a container for the graph view:

var graph = new MyGraph(container);
Bootstrapping mechanism for the mxGraph thin client.
VERSION: '4.0.6'
Contains the current version of the mxGraph library.
Extends mxEventSource to implement a application wrapper for a graph that adds actions, I/O using mxCodec, auto-layout using mxLayoutManager, command history using undoManager, and standard dialogs and widgets, eg.
Extends mxEventSource to implement a graph component for the browser.
Extends mxEventSource to implement a graph model.
Cells are the elements of the graph model.
Extends mxEventSource to implement a view for a graph.
Renders cells into a document object model.
Defines the appearance of the cells in a graph.
Implements a command history.
Extends mxEventSource to implement a graph overlay, represented by an icon and a tooltip.
Defines invalid connections along with the error messages that they produce.
Event handler that selects rectangular regions.
Graph event handler that displays tooltips.
Graph event handler that handles selection.
Extends mxGraphLayout to implement a compact tree (Moen) algorithm.
Base class for all shapes.
Singleton that implements a clipboard for graph cells.
Defines various global constants.
Cross-browser DOM event support.
A singleton class that provides cross-browser helper methods.
Implements internationalization.
A singleton class that implements a simple console.
Generic codec for JavaScript objects that implements a mapping between JavaScript objects and XML nodes that maps each field or element to an attribute or child node, and vice versa.
XML codec for JavaScript object graphs.
Singleton class that acts as a global registry for codecs.
The mxEventObject is a wrapper for all properties of a single event.
Base class for objects that dispatch named events.
Base class for all mouse events in mxGraph.
mxEventSource.prototype.fireEvent = function(evt,
sender)
Dispatches the given event to the listeners which are registered for the event.
mxEventSource.prototype.addListener = function(name,
funct)
Binds the specified function to the given event name.
mxEventSource.prototype.removeListener = function(funct)
Removes all occurrences of the given listener from eventListeners.
mxGraph.prototype.fireMouseEvent = function(evtName,
me,
sender)
Dispatches the given event in the graph event dispatch loop.
mxGraph.prototype.addMouseListener = function(listener)
Adds a listener to the graph event dispatch loop.
mxGraph.prototype.removeMouseListener = function(listener)
Removes the specified graph listener.
Basepath for all URLs in the core without trailing slash.
Basepath for all images URLs in the core without trailing slash.
Defines the language of the client, eg.
Defines the default language which is used in the common resource files.
include: function(src)
Dynamically adds a script node to the document header.
eval: function(expr)
Evaluates the given expression using eval and returns the JavaScript object that represents the expression result.
mxGraph.prototype.setCellWarning = function(cell,
warning,
img,
isSelect)
Creates an overlay for the given cell using the warning and image or warningImage and returns the new mxCellOverlay.
mxGraph.prototype.warningImage
Specifies the mxImage for the image to be used to display a warning overlay.
Close