Rendering

To view the data managed by an instance of the jsPlumb Toolkit, you must arrange for it to be rendered. The Toolkit can render its data to an arbitrary number of elements, and each renderer is backed with its own instance of jsPlumb. The component used by the Toolkit to render is known as a Surface. It supports pan/zoom/select, and has the ability to save and load its state locally in the user's browser.

Before reading this section it is important that you are thoroughly acquainted with the data model used by the Toolkit. It would also be useful to be have at least a basic knowledge of jsPlumb, since the appearance of Endpoints and Connections is jsPlumb's responsibility and you'll want to learn the syntax.

Configuring a Surface

To configure a Surface, call the render method on an existing Toolkit instance. This can be done at any time - before or after data is loaded:

var myToolkit = jsPlumbToolkit.newInstance();
var surface = myToolkit.render({
  container:"someElementId",
  ... other options ...
});

The render method returns a Surface object. It is important to remember that for view related functionality you use a Surface object, whereas for operations on the data model you use a jsPlumb Toolkit instance. Operations on the data model are reflected in all registered Surfaces for the specific instance of the jsPlumb Toolkit as they occur. If you wish to add a Node to the data model, for instance, you need to call addNode on a Toolkit instance. If you want to center the view in some element, you would call centerContent on the Surface registered for that element.

There is one required parameter to a render call - container.

Container

For anyone who has used jsPlumb, the container parameter is probably familiar (and it's perhaps useful to know that the Toolkit passes container into the jsPlumb instance backing the Surface as the Container for that instance of jsPlumb). This is the element to be used as the parent for every element added by the Surface. In addition, all artefacts added to the UI by the associated jsPlumb instance will have this element as their parent. For a deeper discussion of this, see the jsPlumb documentation.

The vast majority of setups will also need to specify a view (the only exception being when you are happy to use the Community edition's default connection styles and you're using inferred template ids.

View

A View contains configuration information for all of the Nodes, Ports, Groups and Edges in your UI; it is what you use to define the appearance and behaviour of the various parts of your UI, and also offers event binding to numerous lifecycle events. For a full discussion of Views, see here.

Rendering to Multiple Elements

You can call render as many times as you like on a single Toolkit instance. If the target container already has a Surface, that Surface is discarded. Every Surface that an instance of the Toolkit is tracking will be notified of changes to the data model. An example of multiple views on one Toolkit instance is given in the Multiple Renderers demonstration.

The Surface Widget

For a full discussion of the capabilities and usage of the Surface widget, see this page. Here on this page we provide a short summary of its features.

Surface is a widget with several useful features:

- Zoom

Change the zoom using the mouse wheel, pinch (on touch devices), right click + mouse move, or programmatically.

- Pan/Drag

Click/tap and hold then drag the contents around. The Surface also, by default, provides 'nudge' bars on the edges of the work area, which you can click to pan the contents by a given amount automatically, or click and hold to pan continuously. These nudge bars can be programmatically suppressed or simply hidden via CSS.

  • Save/Restore state

By default, the Surface writes the current position of elements contained to local storage. When the user comes back to a page that they have already viewed, these saved positions are used to restore the UI to the state it was in when they left it. The current zoom and pan position are also saved and restored. This behaviour can be set to automatic or manual.

- Node Select

In select mode, click/tap and drag to lasso a group of Nodes. Hold down the shift key to add to the current selection. When you drag from left to right you need only intersect some Node to select it. When you drag from right to left you must fully enclose a Node before it is selected.

- Background Images

You can supply a background image for a Surface widget to display. You can also use a tiled image.

TOP


Hiding/Showing Elements

The Surface widget has a setVisible method that takes a variety of arguments:

..or an array of any of these. When you hide a Node, any Edges connected to that Node are also hidden. When you make a Node visible, only Edges that are not connected to a hidden Node are made visible.

Say you want to select and hide a few Nodes, for instance (assume, in these example, the existence of a toolkit and a surface widget):

var sel = toolkit.select(["node1", "node2"]);
surface.setVisible(sel, false);

or perhaps you want to select the Path from some node to another and then hide it:

var path = toolkit.getPath({ source:"node1", target:"node23" });
surface.setVisible(sel, false);

Or maybe even you just want to hide a DOM element that you got through jQuery and you don't need to know what its underlying Node is:

$("aContainerElement").on("click", "aNodeSelector", function() {
    surface.setVisible(this, false);
});

TOP


Dragging Nodes

The vast majority of applications using the Toolkit will want to support dragging of Nodes in the Surface. For this reason, dragging is automatically enabled for any Nodes in your UI.

The Toolkit uses, via jsPlumb, Katavorio to support dragging.

Switching off Dragging

To switch off dragging:

var surface = myToolkitInstance.render({
  container:"someElement",
  view:{ ... },
  elementsDraggable:false
});

Drag Options

var surface = myToolkitInstance.render({
  container:"someElement",
  view:{ ... },
  dragOptions:{
    start:function() {

    },
    drag:function() {

    },
    stop:function() {

    }
  }
});

Dragging on a grid

Katavorio supports constraining dragged elements to a grid:

var surface = myToolkitInstance.render({
  container:"someElement",
  view:{ ... },
  dragOptions:{
    grid:[ 50, 50 ]
  }
});

TOP


Drag Filters

Nodes are automatically made draggable by the Toolkit, unless you set elementsDraggable:false in the render call. By default, a mousedown event on any part of a draggable Node will cause a drag to begin. This can mean that it is difficult to interact with Nodes that have complex content. In these cases, you will need to set a filter in your dragOptions:

var surface = myToolkitInstance.render({
  container:"someElement",
  view:{ ... },
  dragOptions:{
    filter:"button, .dontDragHere"
  }
});

So here we have said that we don't want a mousedown on a button or an element with class "dontDragHere" to start a drag. Valid values for filter are any valid CSS selector.

Drag Posses

A drag Posse is a set of Nodes that should always be dragged as a unit. Unlike in a group (an as-yet unsupported concept, in which a set of Nodes share a common element as parent, which is collapsible etc), these Nodes do not necessarily have any visual indication that they belong together (although you could achieve that using a decorator.

Any given Node can belong to multiple Posses at a time. Additionally, each Node's participation in a Posse is either active, in which dragging the Node causes all Nodes in the Posse to be dragged, or passive, in which the Node drags independently but is dragged when one of the Posse's active Nodes is dragged.

Configuring a Posse

Nodes are assigned to a Posse via an optional assignPosse function that you provide to a render method call:

 var surface = myToolkitInstance.render({
   container:"someElement",
   view: { ... },
   assignPosse:function(node) {
     return node.data.parentId || node.data.id;
   }
});

Note the object passed to assignPosse is a Toolkit Node object; its backing data is available via the data property.

This posse assign function returns either the parentId of the Node's data, or just the Node's id. So we're saying that the Posse consists of some "parent" node and any other nodes marked as "children" of the node. An example few nodes conforming to this data model might be:

 [
   {
     "id":"001",
     "foo":"FOO"
   },
   {
     "id":"z59-b",
     "parentId":"001",
     "foo":"bar",
   },
   {
     "id":"qx-78",
     "parentId":"001",
     "foo":"ok"
   }
 ]

If assignPosse returns null then the relevant Node is not added to a Posse. Note that in this case if there were any "parent" nodes that had no "children" then they would just be in a Posse of one. That's ok; a bit boring, perhaps, around the campfire, but ok.

Active Nodes and Passive Nodes

In the previous example we returned a String to identify the Posse to which each Node belongs. This indicates that the Node should play an active role in the Posse, ie. when it is dragged, all Nodes in the Posse are dragged:

assignPosse:function(node) {
    return node.data.parentId || node.data.id;
}

You can, however, pass back an array in which the second argument indicates whether or not the Node should be active:

assignPosse:function(node) {
    return node.data.parentId  ? [ node.data.parentId, false ] : node.data.id;
}

In this second example we check if a Node has a parentId. If so, the Node is added to the Posse with that value, but as a passive Node: dragging it will not cause the other Nodes to be dragged. Otherwise if there is no parentId then the Node is a parent and it is added as a master to its own Posse.

Adding Nodes Manually

You can at any time manually add a Node to a Posse with this method:

surface.addToPosse(aNode, posseId);

aNode may be the ID of a Node, an actual Node, a DOM element representing a Node, or a list-like object of any of these. Note here that the method is on the Surface widget and not on the Toolkit; it is a view concern. The Toolkit is unaware of the concept of Posses - only the Surface widget knows about them.

Removing Nodes Manually

You can at any time manually remove a Node from its Posse with this method:

surface.removeFromPosse(aNode, posseId);

aNode may be the ID of a Node, an actual Node, a DOM element representing a Node, or a list-like object of any of these.

Updating via the Toolkit

If you call this method:

toolkit.updateNode(someNode, { ... });

The Toolkit updates its data model and then informs any Surface widgets that are attached. The Surface widgets then re-render the Node and run the Node's data through the assignPosse function, updating - or clearing - the Posse as required.

TOP


The Miniview Widget

Every Surface widget can have a Miniview associated with it - a small window displaying the structure of the UI, which is independently pannable and zoomable, and which controls the Surface's view. It is zoomed out to such an extent that all of the nodes in the Surface are visible within its viewport, and contains a "panner" element that maps the current visible viewport of the Surface to which it is related.

Instantiating a Miniview

To get a Miniview you can either first get a Surface:

var toolkit = jsPlumbToolkit.newInstance();
var surface = toolkit.render({
  container:"someElId"
});

...and then ask that Surface to create a Miniview:

var miniview = surface.createMiniview({ 
  container:"someMiniviewContainerId"  
});

or, you can supply Miniview parameters to the render call and then subsequently get the Miniview from the Surface:

var toolkit = jsPlumbToolkit.newInstance();
var surface = toolkit.render({
  container:"someElId",
  miniview:{
    container:"someMiniContainerId"  
  }
});
var miniview = surface.getMiniview();

NB These code samples show how you can retrieve a Miniview from some Surface after it has been created. In reality you will not need to work directly with a Miniview very often, if at all.

Configuring a Miniview

The size of a Miniview is something you set yourself, either through CSS, or via inline styles on the Miniview's container element. The jsPlumb Toolkit uses the size of a Miniview's container combined with the extents of the visible content in the related Surface to compute the appropriate zoom level for the Miniview.

The zoom wheel can be used to zoom in and out on a Surface via its associated Miniview. When this occurs, the visible node set does not change - the Miniview always shows the entire dataset - but the panner element changes size to reflect the fact that the Nodes that are visible in the related Surface's viewport have changed.

CSS

These are the classes you can use to style the Miniview widget. Note that nodes in the Miniview are sized to be identical to their mapped nodes in the related Surface (but the Miniview is zoomed out, so they are not 1:1 in size with their related nodes). You could of course use CSS to force a size for nodes in the Miniview, but this is not recommended; if your Surface contains nodes of various sizes but the Miniview uses a uniform size, the user may experience a certain discontinuity between the two views.

ClassDescription
jtk-miniviewAssigned to an element that is acting as a Miniview's container
jtk-miniview-canvasAssigned to the work area in the Miniview
jtk-miniview-pannerAssigned to the element used to pan the Surface from the Miniview
jtk-miniview-elementAssigned to all elements on the Miniview's canvas

Node type in Miniview

To give you an extra degree of control over the rendering of elements in the Miniview, you can supply a typeFunction, which will be called whenever a Node/Group is rendered, and whose result value is written as the jtk-miniview-type attribute on the DOM element in the Miniview:

 var toolkit = jsPlumbToolkit.newInstance();
 var surface = toolkit.render({
   container:"someElId",
   miniview:{
     container:"someMiniContainerId",
       typeFunction:function(obj) {
         return "foo";
       }
   }
 });

Here we'd end up with an element like:

 <div jtk-miniview-type="foo">...</div>

Of course in a real world scenario you'd like inspect the contents of obj to figure out what value to write. We use an attribute here rather than class because it keeps things simple for the Miniview renderer. If you have not yet encountered this, it is entirely possible to style an element using "attribute selectors".

TOP


Drop/Detach Interceptors

In jsPlumb you can attach interceptors for connection drop and connection detach; these are functions which, should they return false, cause the associated action to be aborted. This is supported in the Toolkit via interceptors in a view.

TOP


Repainting Objects

To force a Surface to repaint some object, you can use the repaint method:

surface.repaint(someObject);

Valid values for someObject are:

  • a Toolkit Node
  • a Toolkit Port
  • a DOM element representing a Toolkit Node or Port
  • the ID of a Toolkit Node or Port
  • an element that has a Toolkit Node or Port element as an ancestor.

The last item in this list might need a little explanation: the idea is that you might have made some changes to part of your UI and you want to repaint the Toolkit object to which it belongs. Rather than forcing you to go off and find the appropriate ancestor, or the id of the appropriate ancestor, you can just pass some element in here and have the Surface figure out what it would be best to repaint.

TOP


CSS Classes

For a discussion of how the Toolkit handles CSS, see this page.


Saving and Restoring UI State

The state of a given renderer can be written to, and subsequently read from, local storage (or a cookie, depending on the capabilities of the browser). This is achieved through a few methods and/or constructor parameters:

Constructor Parameters for automatically saving state

var surface = toolkit.render({
  container:"someElement",
  saveStateOnExit:true,              // serialize state on page unload automatically. defaults to false.
  saveStateOnDrag:true,              // serialize state after each drag. defaults to false.
  stateHandle:"someString"           // required for either of the auto state save options. the handle to store the state by.
});

Methods for saving/restoring state

saveState([String handle], [Function preprocessor]);

Saves the state with the given handle. If handle is not supplied but stateHandle was provided as a constructor parameter, that value is used. If neither is supplied then the state is not saved.

The optional preprocessor argument allows you to pre-process the data loaded from localStorage before it is applied to the Surface. This could be used for many things, but the main intended usage for this mechanism is to allow you to apply compression/decompression to the data that is placed into localStorage. Limits vary, but at the time of writing you could consider as a rough guide that the limit on data that can be placed in localStorage is about 5MB.

The preprocessor function must take two arguments:

function(data, callback);

and is required to call callback with the pre-processed data. As a spurious example, maybe you want to prepend a timestamp to the data before storing:

surface.State.save("myHandle", function(data, callback) {
  callback(new Date().getTime() + "-" + data);
});

Or perhaps you might decide to use the LZMA library to compress your data. The compress method of LZMA has this signature:

compress(data, [level], callback);
surface.State.save("myHandle", function(data, callback) {
  LZMA.compress(state, 1, callback);
});

Notice here that we passed callback directly to LZMA; it wasn't necessary to wrap it in another function.

Note that you can call this method with the preprocessor as the single argument, since the Surface can figure out that if you supply a Function it is not a handle with which to save the data.

restoreState(String handle, [Function preprocessor]);

Restores the state with the given handle. If handle is not supplied but stateHandle was provided as a constructor parameter, that value is used. If neither is supplied then the state is not restored.

See the note on saveState for a discussion of the optional preprocessor Function. Note also that you can call this method with the preprocessor as the single argument, since the Surface can figure out that if you supply a Function it is not a handle with which to save the data.

This might be the matching decompression preprocessor you'd use for the timestamp example above:

surface.State.restore("myHandle", function(data, callback) {
  var parts = data.split(/^([0-9]+)(?:-)/),
      timestamp = new Date(parseInt(parts[1], 10));

  callback(parts[2]);
});

For the LZMA decompression example, you could do this:

surface.State.save("myHandle", function(data, callback) {
  LZMA.decompress(layout.payload, callback);
});
clearState([String handle]);

Clears the state stored with the given handle. If handle is not supplied but stateHandle was provided as a constructor parameter, that value is used. If neither is supplied then the state is not cleared.

serialize();

Serialize the state of the Surface and return the serialized string. This is of course the method that saveState uses internally.

 deserialize(String serializedData);

Deserialize the state of the Surface from the given string. This is of course the method that restoreState uses internally.

Saving and Restoring Custom Properties

The Surface widget exposes the functionality used to save/restore state as four methods that you can call to store arbitrary data of your own:

surface.State.store({String} handle, {String} data);

Stores a string using the provided handle as the key.

surface.State.storeJSON({String} handle, {Object} data);

Stores an object using the provided handle as the key. This method actually serializes the given object to a string, and therefore expects that there is a global JSON object available in the browser, which is true of many modern browsers, and is also provided by jQuery. If JSON is not available in the browser this method fails silently.

{String} surface.State.retrieve({String} handle);

Retrieves a string using the provided handle as the key. Will return null if nothing is stored against the given handle.

{Object} surface.State.retrieveJSON({String} handle, {Object} data);

Retrieves an object using the provided handle as the key. See the note above about the required JSON dependency. Will return null if nothing is stored against the given handle.

TOP


Dragging Nodes from a Palette

A common use case for applications using the jsPlumb Toolkit is the requirement for a palette of nodes from which items can be dragged into the work area. The Surface widget has a method that supports this for elements in your UI, as well as - in browsers that support it - items dragged from the file system.

Configuring a Node Palette

The Toolkit makes no assumptions about the structure of your node palette - you create the palette yourself, using whatever markup you like, and then you supply to the Toolkit either a selector it can use to identify draggable nodes or a list of elements. This is an example from the Database Visualizer application:

var toolkit = jsPlumbToolkit.newInstance();
var renderer = toolkit.render(...params...);

renderer.registerDroppableNodes({
  droppables:nodePalette.querySelectorAll("li"), 
  dragOptions:{
    zIndex:50000,
    cursor:"move",
    clone:true
  },
  typeExtractor:function(el, dropInfo, isNative, eventLocation) { 
    return  el.getAttribute("jtk-node-type"); 
  }, 
  dataGenerator:function(type, dragElement, dropInfo, eventLocation) { return { name:type }; }
});

The parameters to this method are:

  • droppables Provides the individual nodes that should be draggable. You can also provide source and selector, which is a better option for some use cases as you can subsequently refresh the handler to add more droppables.
  • dragOptions Optional values to pass through to the underlying code that makes nodes draggable.
  • typeExtractor This function takes an element and returns to the Toolkit the type of node that is represented by that element. In this application, that information is stored in the jtk-node-type attribute of each element. The typeExtractor is optional; if not supplied, it will be assumed that the Node type is default.
  • dataGenerator This function takes four arguments and returns some default data for that Node type.
    • type - type of the dropped node. Note that type might be null: if a typeExtractor function was not provided this will be the case, but also it may be the case that your typeExtractor returns null. So you should program defensively in this function. Note also that this function is again optional; if not provided then a Node is initialised with an empty object as its backing data.
    • dragElement - the element that was dragged and dropped. Perhaps you have marked this up with a set of attributes that describe what you want to do when it is dropped.
    • dropInfo - An object containing the underlying Drag, Drop and mouse event. Not something most applications will need to use.
    • eventLocation An object containing { left:.., top:... } values that provides the location on the canvas at which the drop occurred.

The example from above but using source and selector might look like:

var handler = renderer.registerDroppableNodes({
  source:document.getElementById("nodePalette"),
  selector:"li", 
  dragOptions:{
    zIndex:50000,
    cursor:"move",
    clone:true
  },
  typeExtractor:function(el, dropInfo, isNative, eventLocation) { 
    return  el.getAttribute("jtk-node-type"); 
  }, 
  dataGenerator:function(type, dragElement, dropInfo, eventLocation) { return { name:type }; }
});

As mentioned, the benefit of this is that the return value has a refresh method you can use if you add more elements that you need to be droppable:

 handler.refresh();

The selector will be run against source again, and any new elements that are encountered will be configured as droppables using the same parameters.

Drag Clones

One important point to note here is that in the dragOptions we have set clone:true. This is how, in Katavorio (the drag library used by the Toolkit) you say you want to drag a copy of the original item and not the item itself, and is most likely what you will want for your application.

Drag CSS

You should ensure that the drag clone is positioned absolute.

Dragging Native Objects

The Surface renderer also supports drag and drop of native objects - if the browser in which the Toolkit is running supports it. Let's add support for native drag/drop to the example from before:

var toolkit = jsPlumbToolkit.newInstance();
var renderer = toolkit.render(...params...);

renderer.registerDroppableNodes({
  dragOptions:{
    zIndex:50000,
    cursor:"move",
    clone:true
  },
  typeExtractor:function(el, event, isNative) { 
    return isNative? event.dataTransfer.items[0].type : el.getAttribute("jtk-node-type"); 
  }, 
  dataGenerator:function(type, dragElement, dropInfo, eventLocation) { return { name:type }; },
  allowNative:true,
  nativeFilter:[ "image/jpeg", "image/png" ]
});

The three things to note here are:

  • allowNative is the flag used to switch on native drag/drop (it is off by default)
  • nativeFilter is an optional array of MIME types for supported objects. If this is not provided then any object is allowed to be dropped.
  • The typeExtractor function is passed a third argument, which, if true, indicates that a native object was dropped. In that case the value of el is a placeholder element that jsPlumb has used for dragging, and holds nothing of interest to you. You will be interested in the dataTransfer property of the event.

TOP


Suspending Event Consumption

By default, the Surface will consume any right click events it catches. You can turn this off, which is handy when developing, in one of two ways:

  • Supply a parameter to the render call:
var surface = toolkit.render({
  ...
  consumeRightClick:false,
  ...
});
  • Call this method on an existing Surface:
surface.setConsumeRightClick(false);

Disabling a Surface

To temporarily "switch off" a Surface (ie. have it stop responding to mouse events), you can use the setEnabled method:

renderer.setEnabled(false);
... time passes, things happen....
renderer.setEnabled(true);