Introduction / Basic Concepts
☰

Basic Concepts

The jsPlumb Toolkit is a data binding and rendering wrapper around the open source jsPlumb Community edition library. At its core is the concept of a graph, representing the entities and relationships in your data model. Each instance of the Toolkit manages a single data model (a single graph), and can be rendered to zero or more UI elements. Each of these renderers is assigned its own instance of jsPlumb.

You create a new instance of the Toolkit by calling the newInstance method:

var toolkit = jsPlumbToolkit.newInstance();

This gives you an instance of the Toolkit with no data loaded and with no renderers assigned.

When you construct an instance of the Toolkit, you can also provide a few different functions that will be used to test for the validity of certain operations such as connect, move and detach. See this page for a discussion of these "interceptors".

You can get data into the Toolkit in a few different ways:

Passing it in to the newInstance method:

var toolkit = jsPlumbToolkit.newInstance({
  data:[
    "nodes":[
      { "id":"foo", "name":"foo" },
      { "id":"bar", "name":"bar" }
    ],
    "edges":[
      { "source":"foo", "target":"bar" }
    ]
  ]
});

Calling load:

toolkit.load({
  data:[ .... ]
});

Notice the format of the data in the first example here. This is the Toolkit's default data format, which is a close analog of the structure of GraphML, but in JSON of course. In examples 1 and 2 here, there is an implicit dataType parameter whose value defaults to json, which indicates data in this format.

There are two default data formats supported by the Toolkit:

  • Graph JSON

The syntax shown above. Discussed in detail on this page

  • Hierarchical JSON

An alternative syntax in which every Node has an optional children list; there is an implicit Edge between each Node and the contents of its children list. the entire graph is nested in this way. Discussed in more detail on this page.

It is possible to write and supply your own data loader to an instance of the jsPlumb Toolkit. This is discussed in more detail here.

Note that the load method does not remove any existing data. You need to call clear() yourself if you wish to load the data into an empty Toolkit instance.

Calling an add*** method on a Toolkit instance

Nodes, groups, ports and edges can all be added programmatically:

  • addNode(data) Adds a new node, with the node's ID derived from the current ID function.
  • addGroup(data) Adds a new group, with the group's ID derived from the current ID function.
  • addPort(nodeOrGroup, data) Adds a new port to an node or group, with the port's ID derived from the current Port ID function.
  • addNewPort(nodeOrGroup, type, [data]) Adds a new port of the given type to the given node or group, using the current port factory
  • addEdge(data) Adds a new edge, with the edge's ID derived from the current Edge ID function.
  • addFactoryNode(type) Adds a new node using the current node factory.

Instead of passing in the data directly, you can use the url parameter to have the Toolkit load data via json.

toolkit.load({
  url:"http://foo.com/myGraph.json"
});

Here we've loaded myGraph.json from foo.com.

Rendering your data is handled by what the Toolkit calls a Surface.

You can register an arbitrary number of elements as renderers with any given Toolkit instance, using the render method:

let toolkit = jsPlumbToolkit.newInstance({...});
let renderer = toolkit.render({
  container:"someElement",
  jsPlumb:{  ... jsPlumb defaults ... }
});

Notice here the jsPlumb parameter: these are defaults for the underlying jsPlumb instance. Every Surface is backed by its own instance of jsPlumb, which can be configured however you like, but which of course ultimately defers to jsPlumb.Defaults.

Whenever a change occurs to the graph - addition/deletion of nodes, import of data etc - every renderer is notified to repaint itself.

Rendering is discussed in detail on this page