Class Codec

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

References

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

Examples

The following code is used to encode a graph model.

const encoder = new Codec();
const result = encoder.encode(graph.getDataModel());
const xml = mxUtils.getXml(result);

WARN: as of version 0.6.0, the codecs provided by maxGraph are no longer registered by default, they MUST be registered before performing encode or decode. For instance, you can use the registerAllCodecs function (or other related functions) to register the codecs.

Example

Using the code below, an XML document is decoded into an existing model. The document may be obtained using parseXml for parsing an XML string.

const doc = xmlUtils.parseXml(xmlString);
const codec = new Codec(doc);
codec.decode(doc.documentElement, graph.getDataModel());

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.

const 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>';
const doc = mxUtils.parseXml(xml);
const codec = new Codec(doc);
let elt = doc.documentElement.firstChild;
const 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.

const enc = new Codec();
const cells = graph.getSelectionCells();
const xml = xmlUtils.getPrettyXml(enc.encode(cells));

Newlines in the XML can be converted to
, in which case a '
' argument must be passed to getXml as the second argument.

Debugging

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

const oldEncode = encode;
encode(obj)
{
  GlobalConfig.logger.show();
  GlobalConfig.logger.debug('Codec.encode: obj=' + StringUtils.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(name)
{
  // ...
};

Constructors

constructor

Properties

document elements encodeDefaults objects

Methods

addElement decode decodeCell encode encodeCell getElementById getId getObject insertIntoGraph isCellCodec lookup putObject reference setAttribute updateElements

Constructors

constructor

Properties

document

document: XMLDocument

The owner document of the codec.

elements

elements: any = null

Lookup table for resolving IDs to elements.

encodeDefaults

encodeDefaults: boolean = false

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

objects

objects: {
    [key: string]: Element;
}

Maps from IDs to objects.

Methods

addElement

decode

  • decode(node, into?): any

  • 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

    • node: null | Element

      XML node to be decoded.

    • Optionalinto: any

      Optional object to be decoded into.

    Returns any

decodeCell

  • decodeCell(node, restoreStructures?): null | Cell

  • 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 Cell instance that represents the given node.

    Parameters

    • node: Element

      XML node that contains the cell data.

    • restoreStructures: boolean = true

      Optional boolean indicating whether the graph structure should be restored by calling insert and insertEdge on the parent and terminals, respectively. Default is true.

    Returns null | Cell

encode

  • encode(obj): null | Element

  • Encodes the specified object and returns the resulting XML node.

    Parameters

    • obj: any

      Object to be encoded.

    Returns null | Element

encodeCell

  • encodeCell(cell, node, includeChildren?): void

  • 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. ModelCodec, ChildChangeCodec and RootChangeCodec). 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

    • cell: Cell

      mxCell to be encoded.

    • node: Node

      Parent XML node to add the encoded cell into.

    • OptionalincludeChildren: boolean

      Optional boolean indicating if the function should include all descendents. Default is true.

    Returns void

getElementById

  • getElementById(id): Element

  • Returns the element with the given ID from document.

    Parameters

    • id: string

      String that contains the ID.

    Returns Element

getId

  • getId(obj): string

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

    Parameters

    • obj: any

      Object to return the ID for.

    Returns string

getObject

  • getObject(id): any

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

    Parameters

    • id: string

    Returns any

insertIntoGraph

  • insertIntoGraph(cell): void

  • Inserts the given cell into its parent and terminal cells.

    Parameters

    Returns void

isCellCodec

lookup

  • lookup(id): any

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

    Example:

    const codec = new Codec();
    codec.lookup(id)
    {
      return model.getCell(id);
    };

    Parameters

    • id: string

      ID of the object to be returned.

    Returns any

putObject

  • putObject(id, obj): any

  • Associates the given object with the given ID and returns the given object.

    Parameters

    • id: string

      ID for the object to be associated with.

    • obj: any

      Object to be associated with the ID.

    Returns any

reference

  • reference(obj): any

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

    Example:

    const codec = new Codec();
    codec.reference(obj)
    {
      return obj.getCustomId();
    };

    Parameters

    • obj: any

      Object whose ID should be returned.

    Returns any

setAttribute

  • setAttribute(node, attribute, value): void

  • 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

    • node: Element

      XML node to set the attribute for.

    • attribute: string

      The name of the attribute to be set.

    • value: any

      New value of the attribute.

    Returns void

updateElements

Settings

Member Visibility

On This Page

ReferencesExamplesDebugging
Constructors
Properties
Methods