Class mxEditor

Actions are functions stored in the array under their names. The functions take the as the first, and an optional as the second argument and are invoked using . Any additional arguments passed to execute are passed on to the action as-is.

A list of built-in actions is available in the description.

To read a diagram from an XML string, for example from a textfield within the page, the following code is used:

example

var doc = mxUtils.parseXML(xmlString);
var node = doc.documentElement;
editor.readGraphModel(node);

For reading a diagram from a remote location, use the open method.

To save diagrams in XML on a server, you can set the urlPost variable. This variable will be used in getUrlPost to construct a URL for the post request that is issued in the save method. The post request contains the XML representation of the diagram as returned by writeGraphModel in the xml parameter.

On the server side, the post request is processed using standard technologies such as Java Servlets, CGI, .NET or ASP.

Here are some examples of processing a post request in various languages.

• Java: URLDecoder.decode(request.getParameter("xml"), "UTF-8").replace("\n", " ")

Note that the linefeeds should only be replaced if the XML is processed in Java, for example when creating an image, but not if the XML is passed back to the client-side.

• .NET: HttpUtility.UrlDecode(context.Request.Params["xml"])
• PHP: urldecode($_POST["xml"])

Creating images:

A backend (Java, PHP or C#) is required for creating images. The distribution contains an example for each backend (ImageHandler.java, ImageHandler.cs and graph.php). More information about using a backend to create images can be found in the readme.html files. Note that the preview is implemented using VML/SVG in the browser and does not require a backend. The backend is only required to creates images (bitmaps).

Special characters:

Note There are five characters that should always appear in XML content as escapes, so that they do not interact with the syntax of the markup. These are part of the language for all documents based on XML and for HTML.

• < (<)
• > (>)
• & (&)
• " (")
• ' (')

Although it is part of the XML language, ' is not defined in HTML. For this reason the XHTML specification recommends instead the use of ' if text may be passed to a HTML user agent.

If you are having problems with special characters on the server-side then you may want to try the escapePostData flag.

For converting decimal escape sequences inside strings, a user has provided us with the following function:

example

function html2js(text)
{
  var entitySearch = /&#[0-9]+;/;
  var entity;

  while (entity = entitySearch.exec(text))
  {
    var charCode = entity[0].substring(2, entity[0].length -1);
    text = text.substring(0, entity.index)
           + String.fromCharCode(charCode)
           + text.substring(entity.index + entity[0].length);
  }

  return text;
}

Otherwise try using hex escape sequences and the built-in unescape function for converting such strings.

Local Files:

For saving and opening local files, no standardized method exists that works across all browsers. The recommended way of dealing with local files is to create a backend that streams the XML data back to the browser (echo) as an attachment so that a Save-dialog is displayed on the client-side and the file can be saved to the local disk.

For example, in PHP the code that does this looks as follows.

example

$xml = stripslashes($_POST["xml"]);
header("Content-Disposition: attachment; filename=\"diagram.xml\"");
echo($xml);

To open a local file, the file should be uploaded via a form in the browser and then opened from the server in the editor.

Cell Properties:

The properties displayed in the properties dialog are the attributes and values of the cell's user object, which is an XML node. The XML node is defined in the templates section of the config file.

The templates are stored in mxEditor.templates and contain cells which are cloned at insertion time to create new vertices by use of drag and drop from the toolbar. Each entry in the toolbar for adding a new vertex must refer to an existing template.

In the following example, the task node is a business object and only the mxCell node and its mxGeometry child contain graph information:

example

<Task label="Task" description="">
  <mxCell vertex="true">
    <mxGeometry as="geometry" width="72" height="32"/>
  </mxCell>
</Task>

The idea is that the XML representation is inverse from the in-memory representation: The outer XML node is the user object and the inner node is the cell. This means the user object of the cell is the Task node with no children for the above example:

example

<Task label="Task" description=""/>

The Task node can have any tag name, attributes and child nodes. The mxCodec will use the XML hierarchy as the user object, while removing the "known annotations", such as the mxCell node. At save-time the cell data will be "merged" back into the user object. The user object is only modified via the properties dialog during the lifecycle of the cell.

In the default implementation of createProperties, the user object's attributes are put into a form for editing. Attributes are changed using the mxCellAttributeChange action in the model. The dialog can be replaced by overriding the createProperties hook or by replacing the showProperties action in {@link action}. Alternatively, the entry in the config file's popupmenu section can be modified to invoke a different action.

If you want to displey the properties dialog on a doubleclick, you can set mxEditor.dblClickAction to showProperties as follows:

example

editor.dblClickAction = 'showProperties';

Popupmenu and Toolbar:

The toolbar and popupmenu are typically configured using the respective sections in the config file, that is, the popupmenu is defined as follows:

example

<mxEditor>
  <mxDefaultPopupMenu as="popupHandler">
        <add as="cut" action="cut" icon="images/cut.gif"/>
     ...

New entries can be added to the toolbar by inserting an add-node into the above configuration. Existing entries may be removed and changed by modifying or removing the respective entries in the configuration. The configuration is read by the {@link mxDefaultPopupMenuCodec}, the format of the configuration is explained in {@link mxDefaultPopupMenu.decode}.

The toolbar is defined in the mxDefaultToolbar section. Items can be added and removed in this section.

example

<mxEditor>
  <mxDefaultToolbar>
    <add as="save" action="save" icon="images/save.gif"/>
    <add as="Swimlane" template="swimlane" icon="images/swimlane.gif"/>
    ...

The format of the configuration is described in {@link mxDefaultToolbarCodec.decode}.

Ids:

For the IDs, there is an implicit behaviour in mxCodec: It moves the Id from the cell to the user object at encoding time and vice versa at decoding time. For example, if the Task node from above has an id attribute, then the mxCell.id of the corresponding cell will have this value. If there is no Id collision in the model, then the cell may be retrieved using this Id with the mxGraphModel.getCell function. If there is a collision, a new Id will be created for the cell using mxGraphModel.createId. At encoding time, this new Id will replace the value previously stored under the id attribute in the Task node.

See {@link mxEditorCodec}, {@link mxDefaultToolbarCodec} and {@link mxDefaultPopupMenuCodec} for information about configuring the editor and user interface.

Programmatically inserting cells:

For inserting a new cell, say, by clicking a button in the document, the following code can be used. This requires an reference to the editor.

example

var userObject = new Object();
var parent = editor.graph.getDefaultParent();
var model = editor.graph.model;
model.beginUpdate();
try
{
  editor.graph.insertVertex(parent, null, userObject, 20, 20, 80, 30);
}
finally
{
  model.endUpdate();
}

If a template cell from the config file should be inserted, then a clone of the template can be created as follows. The clone is then inserted using the add function instead of addVertex.

example

var template = editor.templates['task'];
var clone = editor.graph.model.cloneCell(template);

Resources:

resources/editor - Language resources for mxEditor

Callback: onInit

Called from within the constructor. In the callback, "this" refers to the editor instance.

Cookie: mxgraph=seen

Set when the editor is started. Never expires. Use resetFirstTime to reset this cookie. This cookie only exists if {@link onInit} is implemented.

Event: mxEvent.OPEN

Fires after a file was opened in open. The filename property contains the filename that was used. The same value is also available in filename.

Event: mxEvent.SAVE

Fires after the current file was saved in save. The url property contains the URL that was used for saving.

Event: mxEvent.POST

Fires if a successful response was received in postDiagram. The request property contains the , the url and data properties contain the URL and the data that were used in the post request.

Event: mxEvent.ROOT

Fires when the current root has changed, or when the title of the current root has changed. This event has no properties.

Event: mxEvent.BEFORE_ADD_VERTEX

Fires before a vertex is added in addVertex. The vertex property contains the new vertex and the parent property contains its parent.

Event: mxEvent.ADD_VERTEX

Fires between begin- and endUpdate in . The vertex property contains the vertex that is being inserted.

Event: mxEvent.AFTER_ADD_VERTEX

Fires after a vertex was inserted and selected in . The vertex property contains the new vertex.

Example:

For starting an in-place edit after a new vertex has been added to the graph, the following code can be used.

example

editor.addListener(mxEvent.AFTER_ADD_VERTEX, function(sender, evt)
{
  var vertex = evt.getProperty('vertex');

  if (editor.graph.isCellEditable(vertex))
  {
      editor.graph.startEditingAtCell(vertex);
  }
});

Event: mxEvent.ESCAPE

Fires when the escape key is pressed. The event property contains the key event.

Constructor: mxEditor

Constructs a new editor. This function invokes the {@link onInit} callback upon completion.

example

var config = mxUtils.load('config/diagrameditor.xml').getDocumentElement();
var editor = new mxEditor(config);