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 use either of them. It is always possible to parse a custom data format and build the graph accordingly using the creation methods introduced in chapter IGraph.For instance, 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 very common data format used to pass data along in JavaScript. Due to its flexible structure, it can store information about the graph structure as well as additional data which can be used to add labels, style the graph elements or provide additional information for the layout or analysis algorithms.

Loading Graphs from JSON

The section Creating a Graph from Business Data shows a convenient way to build a graph from JSON data with yFiles for HTML.

The yFiles for HTML package contains a multistep code tutorial on how to use the GraphBuilder, starting with the first step: Creating a graph from business data.

In addition to the convenient way provided by yFiles for HTML to generate a graph from JSON data, you can still build your graph manually from JSON using the creation methods in chapter IGraph.This is recommended in case you have a data format which doesn’t directly translate to the configuration API the classes mentioned before.

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

{
  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

In order to save graph information using the JSON format, you need to iterate the nodes and edges in the graph and store the important information, e.g. which elements are connected, in an Object. To see how this is accomplished, have a look at this tutorial step: Building Swimlanes From Data.

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

GraphML

GraphML is an XML based graph exchange format. It contains the graph’s structural information. yFiles for HTML also adds styling and geometric information to be able to have all necessary data to load and store the graph.

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

The GraphMLSupport class provides convenient support for (de)serializing the graph model it displays via the following methods:

openFile(graphComponent: GraphComponent, storageLocation: StorageLocation): Promise<IGraph>

openFile(graph: IGraph, storageLocation: StorageLocation): Promise<IGraph>

Methods for reading in a graph in GraphML into a GraphComponent or an IGraph.

saveFile(graph: IGraph, storageLocation: StorageLocation): Promise<string>

Method for writing out the IGraph to a GraphML file.

commands provide convenient access to these methods:

More control over the serialization or deserialization is provided by the GraphMLIOHandler class. Besides the option to read and write graphs which are not currently displayed in a GraphComponentGraphMLIOHandler 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 results from 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 very specific for yFiles for HTML. Other products, including yFiles for other platforms, will most likely not understand and use that data.