mxCodec

XML codec for JavaScript object graphs.  See mxObjectCodec for a description of the general encoding/decoding scheme.  This class uses the codecs registered in mxCodecRegistry for encoding/decoding each object.

References

In order to resolve references, especially forward references, the mxCodec constructor must be given the document that contains the referenced elements.

Examples

The following code is used to encode a graph model.

var encoder = new mxCodec();
var result = encoder.encode(graph.getModel());
var xml = mxUtils.getXml(result);

Example

Using the code below, an XML document is decoded into an existing model.  The document may be obtained using one of the functions in mxUtils for loading an XML file, eg.  mxUtils.get, or using mxUtils.parseXml for parsing an XML string.

var doc = mxUtils.parseXml(xmlString);
var codec = new mxCodec(doc);
codec.decode(doc.documentElement, graph.getModel());

Example

This example demonstrates parsing a list of isolated cells into an existing graph model.  Note that the cells do not have a parent reference so they can be added anywhere in the cell hierarchy after parsing.

var xml = '<root><mxCell id="2" value="Hello," vertex="1"><mxGeometry x="20" y="20" width="80" height="30" as="geometry"/></mxCell><mxCell id="3" value="World!" vertex="1"><mxGeometry x="200" y="150" width="80" height="30" as="geometry"/></mxCell><mxCell id="4" value="" edge="1" source="2" target="3"><mxGeometry relative="1" as="geometry"/></mxCell></root>';
var doc = mxUtils.parseXml(xml);
var codec = new mxCodec(doc);
var elt = doc.documentElement.firstChild;
var cells = [];

while (elt != null)
{
  cells.push(codec.decode(elt));
  elt = elt.nextSibling;
}

graph.addCells(cells);

Example

Using the following code, the selection cells of a graph are encoded and the output is displayed in a dialog box.

var enc = new mxCodec();
var cells = graph.getSelectionCells();
mxUtils.alert(mxUtils.getPrettyXml(enc.encode(cells)));

Newlines in the XML can be converted to <br>, in which case a ‘<br>’ argument must be passed to mxUtils.getXml as the second argument.

Debugging

For debugging I/O you can use the following code to get the sequence of encoded objects:

var oldEncode = mxCodec.prototype.encode;
mxCodec.prototype.encode = function(obj)
{
  mxLog.show();
  mxLog.debug('mxCodec.encode: obj='+mxUtils.getFunctionName(obj.constructor));

  return oldEncode.apply(this, arguments);
};

Note that the I/O system adds object codecs for new object automatically.  For decoding those objects, the constructor should be written as follows:

var MyObj = function(name)
{
  // ...
};
Summary
mxCodecXML codec for JavaScript object graphs.
Functions
mxCodecConstructs an XML encoder/decoder for the specified owner document.
Variables
documentThe owner document of the codec.
objectsMaps from IDs to objects.
elementsLookup table for resolving IDs to elements.
encodeDefaultsSpecifies if default values should be encoded.
Functions
putObjectAssoiates the given object with the given ID and returns the given object.
getObjectReturns the decoded object for the element with the specified ID in document.
lookupHook for subclassers to implement a custom lookup mechanism for cell IDs.
getElementByIdReturns the element with the given ID from document.
updateElementsReturns the element with the given ID from document.
addElementAdds the given element to elements if it has an ID.
getIdReturns the ID of the specified object.
referenceHook for subclassers to implement a custom method for retrieving IDs from objects.
encodeEncodes the specified object and returns the resulting XML node.
decodeDecodes the given XML node.
encodeCellEncoding of cell hierarchies is built-into the core, but is a higher-level function that needs to be explicitely used by the respective object encoders (eg.
isCellCodecReturns true if the given codec is a cell codec.
decodeCellDecodes cells that have been encoded using inversion, ie.
insertIntoGraphInserts the given cell into its parent and terminal cells.
setAttributeSets the attribute on the specified node to value.

Functions

mxCodec

function mxCodec(document)

Constructs an XML encoder/decoder for the specified owner document.

Parameters

documentOptional XML document that contains the data.  If no document is specified then a new document is created using mxUtils.createXmlDocument.

Variables

document

mxCodec.prototype.document

The owner document of the codec.

objects

mxCodec.prototype.objects

Maps from IDs to objects.

elements

mxCodec.prototype.elements

Lookup table for resolving IDs to elements.

encodeDefaults

mxCodec.prototype.encodeDefaults

Specifies if default values should be encoded.  Default is false.

Functions

putObject

mxCodec.prototype.putObject = function(id,
obj)

Assoiates the given object with the given ID and returns the given object.

Parameters

idID for the object to be associated with.
objObject to be associated with the ID.

getObject

mxCodec.prototype.getObject = function(id)

Returns the decoded object for the element with the specified ID in document.  If the object is not known then lookup is used to find an object.  If no object is found, then the element with the respective ID from the document is parsed using decode.

lookup

mxCodec.prototype.lookup = function(id)

Hook for subclassers to implement a custom lookup mechanism for cell IDs.  This implementation always returns null.

Example

var codec = new mxCodec();
codec.lookup = function(id)
{
  return model.getCell(id);
};

Parameters

idID of the object to be returned.

getElementById

mxCodec.prototype.getElementById = function(id)

Returns the element with the given ID from document.

Parameters

idString that contains the ID.

updateElements

mxCodec.prototype.updateElements = function()

Returns the element with the given ID from document.

Parameters

idString that contains the ID.

addElement

mxCodec.prototype.addElement = function(node)

Adds the given element to elements if it has an ID.

getId

mxCodec.prototype.getId = function(obj)

Returns the ID of the specified object.  This implementation calls reference first and if that returns null handles the object as an mxCell by returning their IDs using mxCell.getId.  If no ID exists for the given cell, then an on-the-fly ID is generated using mxCellPath.create.

Parameters

objObject to return the ID for.

reference

mxCodec.prototype.reference = function(obj)

Hook for subclassers to implement a custom method for retrieving IDs from objects.  This implementation always returns null.

Example

var codec = new mxCodec();
codec.reference = function(obj)
{
  return obj.getCustomId();
};

Parameters

objObject whose ID should be returned.

encode

mxCodec.prototype.encode = function(obj)

Encodes the specified object and returns the resulting XML node.

Parameters

objObject to be encoded.

decode

mxCodec.prototype.decode = function(node,
into)

Decodes the given XML node.  The optional “into” argument specifies an existing object to be used.  If no object is given, then a new instance is created using the constructor from the codec.

The function returns the passed in object or the new instance if no object was given.

Parameters

nodeXML node to be decoded.
intoOptional object to be decodec into.

encodeCell

mxCodec.prototype.encodeCell = function(cell,
node,
includeChildren)

Encoding of cell hierarchies is built-into the core, but is a higher-level function that needs to be explicitely used by the respective object encoders (eg.  mxModelCodec, mxChildChangeCodec and mxRootChangeCodec).  This implementation writes the given cell and its children as a (flat) sequence into the given node.  The children are not encoded if the optional includeChildren is false.  The function is in charge of adding the result into the given node and has no return value.

Parameters

cellmxCell to be encoded.
nodeParent XML node to add the encoded cell into.
includeChildrenOptional boolean indicating if the function should include all descendents.  Default is true.

isCellCodec

mxCodec.prototype.isCellCodec = function(codec)

Returns true if the given codec is a cell codec.  This uses mxCellCodec.isCellCodec to check if the codec is of the given type.

decodeCell

mxCodec.prototype.decodeCell = function(node,
restoreStructures)

Decodes cells that have been encoded using inversion, ie. where the user object is the enclosing node in the XML, and restores the group and graph structure in the cells.  Returns a new mxCell instance that represents the given node.

Parameters

nodeXML node that contains the cell data.
restoreStructuresOptional boolean indicating whether the graph structure should be restored by calling insert and insertEdge on the parent and terminals, respectively.  Default is true.

insertIntoGraph

mxCodec.prototype.insertIntoGraph = function(cell)

Inserts the given cell into its parent and terminal cells.

setAttribute

mxCodec.prototype.setAttribute = function(node,
attribute,
value)

Sets the attribute on the specified node to value.  This is a helper method that makes sure the attribute and value arguments are not null.

Parameters

nodeXML node to set the attribute for.
attributesAttributename to be set.
valueNew value of the attribute.
function mxCodec(document)
Constructs an XML encoder/decoder for the specified owner document.
mxCodec.prototype.document
The owner document of the codec.
mxCodec.prototype.objects
Maps from IDs to objects.
mxCodec.prototype.elements
Lookup table for resolving IDs to elements.
mxCodec.prototype.encodeDefaults
Specifies if default values should be encoded.
mxCodec.prototype.putObject = function(id,
obj)
Assoiates the given object with the given ID and returns the given object.
mxCodec.prototype.getObject = function(id)
Returns the decoded object for the element with the specified ID in document.
mxCodec.prototype.lookup = function(id)
Hook for subclassers to implement a custom lookup mechanism for cell IDs.
mxCodec.prototype.getElementById = function(id)
Returns the element with the given ID from document.
mxCodec.prototype.updateElements = function()
Returns the element with the given ID from document.
mxCodec.prototype.addElement = function(node)
Adds the given element to elements if it has an ID.
mxCodec.prototype.getId = function(obj)
Returns the ID of the specified object.
mxCodec.prototype.reference = function(obj)
Hook for subclassers to implement a custom method for retrieving IDs from objects.
mxCodec.prototype.encode = function(obj)
Encodes the specified object and returns the resulting XML node.
mxCodec.prototype.decode = function(node,
into)
Decodes the given XML node.
mxCodec.prototype.encodeCell = function(cell,
node,
includeChildren)
Encoding of cell hierarchies is built-into the core, but is a higher-level function that needs to be explicitely used by the respective object encoders (eg.
mxCodec.prototype.isCellCodec = function(codec)
Returns true if the given codec is a cell codec.
mxCodec.prototype.decodeCell = function(node,
restoreStructures)
Decodes cells that have been encoded using inversion, ie.
mxCodec.prototype.insertIntoGraph = function(cell)
Inserts the given cell into its parent and terminal cells.
mxCodec.prototype.setAttribute = function(node,
attribute,
value)
Sets the attribute on the specified node to value.
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.
Singleton class that acts as a global registry for codecs.
get: function(url,
onload,
onerror,
binary,
timeout,
ontimeout,
headers)
Loads the specified URL asynchronously and invokes the given functions depending on the request status.
parseXml: function()
Parses the specified XML string into a new XML document and returns the new document.
getXml: function(node,
linefeed)
Returns the XML content of the specified node.
createXmlDocument: function()
Returns a new, empty XML document.
Cells are the elements of the graph model.
mxCell.prototype.getId = function()
Returns the Id of the cell as a string.
create: function(cell)
Creates the cell path for the given cell.
Codec for mxGraphModels.
Codec for mxChildChanges.
Codec for mxRootChanges.
codec.isCellCodec = function()
Returns true since this is a cell codec.
Close