Loading and Saving Graphs

The most common way to handle data in JavaScript is to use the JSON format. There are some helper classes in yFiles for HTML which allow for an easy transition from data to graph in yFiles for HTML.

yFiles for HTML supports also loading and saving graphs using the graph exchange format GraphML. GraphML is an XML based graph exchange format which supports reading and writing the structural information of a graph. Additionally, yFiles for HTML stores the visual and geometric information of a graph in this format.

Although the built-in support for GraphML and JSON provides a convenient way to read and write complete graphs, including additional graph-related information, it is not mandatory to use either of them. You can always parse a custom data format and build the graph accordingly using the creation methods introduced in the IGraph chapter.For example, if you have already established a custom format for your business model data, it might be more convenient to read and write the business model using your existing parsers and writers and build the graph based on the business model after or during parsing.

JSON

JSON is a common data format for exchanging data in JavaScript. Its flexible structure allows storing information about the graph’s structure, as well as additional data for labels, styles, layout, or analysis algorithms.

Loading Graphs from JSON

The section Creating a Graph from Business Data describes how to conveniently build a graph from JSON data with yFiles for HTML.

The yFiles for HTML package contains a multi-step code tutorial on using the GraphBuilder, starting with: Creating a graph from business data.

Besides the convenient way of generating a graph from JSON data with yFiles for HTML, you can still build your graph manually using the creation methods in chapter IGraph.This is recommended if your data format doesn’t directly translate to the configuration API of the classes mentioned above.

The following example shows how to load JSON data from a URL and GraphBuilder to populate the graph with nodes and edges.

const myData = {
  nodes: [{ id: 0 }, { id: 1 }],
  edges: [{ id: 0, source: 0, target: 1 }]
}

const graphComponent = new GraphComponent()
const response = await fetch(url)
const data = await response.json()
const builder = new GraphBuilder({
  nodes: [
    {
      data: data.nodes,
      id: (node) => node.id
    }
  ],
  edges: [
    {
      data: data.edges,
      sourceId: (edge) => edge.source,
      targetId: (edge) => edge.target
    }
  ]
})
graphComponent.graph = builder.buildGraph()
const graphComponent = new GraphComponent()
const response = await fetch(url)
const data = await response.json()
const builder = new GraphBuilder({
  nodes: [
    {
      data: data.nodes,
      id: (node: { id: number }) => node.id
    }
  ],
  edges: [
    {
      data: data.edges,
      sourceId: (edge: { id: number; source: number; target: number }) =>
        edge.source,
      targetId: (edge: { id: number; source: number; target: number }) =>
        edge.target
    }
  ]
})
graphComponent.graph = builder.buildGraph()

Some demos included in yFiles for HTML provide sample code on how to build a graph from JSON data. They are listed in the table below.

Saving Graphs to JSON

To save graph information in JSON format, you need to iterate through the nodes and edges in the graph and store the relevant information (e.g., element connections) in an object. See this tutorial step for an example: Building Swimlanes From Data.

The file <yfiles-package>/demos-ts/utils/json-writer.js contains helper classes with methods for writing an IGraph as JSON. This implementation does not support all visual features of yFiles but can be used as a starting point for including other information, such as item styles.

GraphML

GraphML is an XML-based graph exchange format that contains the graph’s structural information. yFiles for HTML extends this format with styling and geometric information, providing all the necessary data to load and store the graph.

The GraphML support in yFiles for HTML can be easily extended to add arbitrary data to the GraphML. This is useful when you want to save and load additional business data associated with graph elements, custom styles, or custom label and port models.

More control over the serialization or deserialization is provided by the GraphMLIOHandler class. Besides the option to read and write graphs that are not currently displayed in a GraphComponent, GraphMLIOHandler supports further customizations.

readFromDocument(graph: IGraph, document: Document): Promise<IGraph>

readFromGraphMLText(graph: IGraph, data: string): Promise<IGraph>

readFromURL(graph: IGraph, url: string): Promise<IGraph>

Parses GraphML from different sources and populates the given graph.

write(graph: IGraph): Promise<string>

Writes the given graph as GraphML to the provided targets.

The file format that yFiles for HTML uses to serialize graphs is called GraphML. It is the result of the joint effort of the graph drawing community to define a common, XML-based format for exchanging graph structure data. The GraphML file format is described in the GraphML Primer.

yFiles for HTML extends this file format for its needs using a so-called attribute extension that can also be used to add custom graph-related data to the GraphML. This is described in detail in Customizing Graph I/O.

The format of the additional data in the GraphML file is not standardized and is specific to yFiles for HTML. Other products, including yFiles for other platforms, will most likely not understand and use that data.