Rappid - dia

CommandManager keeps track of graph changes and allows you to travel the history of those changes back and forth. There is no limitation put into the number of levels one can undo/redo.

Installation

Include joint.dia.command.js to your HTML:

<script src="joint.dia.command.js"></script>

Creating CommandManager

var graph = new joint.dia.Graph;
var paper = new joint.dia.Paper({ el: $('#paper'), width: 500, height: 500, model: graph });

var commandManager = new joint.dia.CommandManager({ graph: graph });

$('#undo-button').click(function() { commandManager.undo(); });
$('#redo-button').click(function() { commandManager.redo(); });

How does CommandManager work?

CommandManager listens to graph changes and when any cell's attribute is changed it stores the difference (command). CommandManager stores every change made on graph's cells into undoStack and every reverted change into redoStack. It allows you to revert the changes stored in those stacks.

CommandManager API

constructor

The joint.dia.CommandManager constructor takes up to three parameters.

graph

Is the graph the CommandManager listens to.

cmdBeforeAdd

A function evaluated before any command is added. If the function returns false, the command does not get stored. This way you can control which commands do not get registered for undo/redo.

var commandManager = new joint.dia.CommandManager({
    graph: graph,
    cmdBeforeAdd: function(cmdName, cell, graph, options) {
        options = options || {};
        return !options.ignoreCommandManager;
    }
});

// ...

// Note that the last argument to set() is an options object that gets passed to the cmdBeforeAdd() function.
element.set({ foo: 'bar' }, { ignoreCommandManager: true });

cmdNameRegex

A regular expression specifying what cell's attributes the CommandManager listens to. Default regex is /^(?:add|remove|change:\w+)$/.

revertOptionsList

An array of options property names that are meant to be passed in undo actions. It defaults to ['propertyPath'].

commandManager = new joint.dia.CommandManager({
    revertOptionsList: ['myOptionAttribute1']
})
element.set('attribute', 'value', { myOptionAttribute1: 5, myOptionAttribute2: 6 });
commandManager.undo(); // -> calls element.set('attribute', 'prevValue', { myOptionAttribute1: 5 });

Alternatively the revertOptionList can be defined as a function.

revertOptionsList: function(attrValue, attrName) {
    return attrName !== 'doNotPassMe'; /* pass over everything except `doNotPassMe` attribute */
}

applyOptionsList

An array of options property names that are meant to be passed in redo actions. It defaults to ['propertyPath'].

commandManager = new joint.dia.CommandManager({
    applyOptionsList: ['myOptionAttribute1']
})
element.set('attribute', 'value', { myOptionAttribute1: 5, myOptionAttribute2: 6 });
commandManager.undo();
commandManager.redo(); // -> calls element.set('attribute', 'value', { myOptionAttribute1: 5 });

Alternatively the applyOptionList can be defined as a function.

applyOptionsList: function(attrValue, attrName) {
    return attrName !== 'doNotPassMe'; /* pass over everything except `doNotPassMe` attribute */
}

undo

Function undo(opt) travels the history one command back. It accepts an option parameter (opt) that is applied when function makes changes to the graph. e.g commandManager.undo({ undoneBy: 'user123' })

redo

Function redo(opt) go back to whatever was previously undo()ed.

cancel

Function cancel(opt) same as undo() but does not store the undo-ed command to the redoStack. Canceled command therefore cannot be redo-ed.

hasUndo

Function hasUndo() true if there is something in the undoStack.

hasRedo

Function hasRedo() true if there is something in the redoStack

reset

Function reset() clears both undoStack and redoStack.

initBatchCommand

Function initBatchCommand() gives you the ability to gather multiple changes into a single command. These commands could be revert with single undo() call.

From the moment the function is called every change made on graph is not stored into the undoStack. Changes are temporarily kept in the CommandManager until storeBatchCommand() is called.

storeBatchCommand

Calling function storeBatchCommand() tells the CommandManager to store all changes temporarily kept in the undoStack. In order to store changes you have to call this function as many times as initBatchCommand() had been called.

Events

The plugin fires the following events.

commandManager.on('stack', function(opt) {
    if (this.hasUndo()) { /* do something */ }
    if (this.hasRedo()) { /* do something else */ }
});

dia.GraphUtils adds additional methods to the joint.dia.Graph. Currently, it adds only two methods: constructTree() and shortestpath().

Installation

Include joint.dia.graphUtils.js file to your HTML:

<script src="joint.dia.graphUtils.js"></script>

If you plan to use shortestPath() method, you're going to also need to include joint.alg.priorityQueue.js and joint.alg.dijkstra.js plugins:

<script src="joint.alg.priorityQueue.js"></script>
<script src="joint.alg.dijkstra.js"></script>

This will add more methods to the joint.dia.Graph object:

Methods

{
  name: 'my label',
  children: [ { name: 'my label 2', children: [...] }, ...]
}
	

var cells = graph.constructTree(
    {
        name: 'my top,
        children: [ { name: 'my child 1' }, { name: 'my child 2' } ]
    }, {
    makeElement: function(node) {
	    return new joint.shapes.basic.Rect({
		size: { width: 80, height: 30 },
		attrs: { text: { text: node.name } }
	    });
    },
    makeLink: function(parentElement, childElement) {
	    return new joint.dia.Link({
		source: { id: parentElement.id },
		target: { id: childElement.id }
	    });
    }
});
graph.addCells(cells);
	

Validator runs a set of callbacks to determine if a command is valid. This is useful for checking if a certain action in your application does lead to an invalid state of the diagram (from your application specific perspective). You can not only cancel such command but e.g. also give the user a hint that this action is not allowed).

Installation

Include joint.dia.command.js and joint.dia.validator.js to your HTML:

<script src="joint.dia.command.js"></script>
<script src="joint.dia.vaidator.js"></script>

Creating Validator

var graph = new joint.dia.Graph;
var paper = new joint.dia.Paper({ el: $('#paper'), width: 500, height: 500, model: graph });

var commandManager = new joint.dia.CommandManager({ graph: graph });
var validator = new joint.dia.Validator({ commandManager: commandManager });
validator.validate('remove',
    function(err, command, next) {
        if (command.data.type === 'basic.Rect') return next('Rectangles cannot be removed.');
        return next();
    },
    function(err, command, next) {
        if (err) console.log(err);
        return next(err);
    }
);

(Those that know the great ExpressJS application framework might have recognized a similar API to what ExpressJS provides for registering URL route handlers.)

Validator API

constructor

The joint.dia.Validator constructor takes two parameters.

commandManager

The CommandManager the validator listens to.

cancelInvalid

Determine whether to cancel an invalid command or not. If set to false, only the invalid event is triggered.

Default is true.

validate

Function validate(action [, callback]*) registers callbacks for a given action.

The validator listens on commands added to the CommandManager and runs this set of callbacks registered for the action. If the last callback returns an error the command is canceled (see joint.dia.CommandManager.cancel()). This behaviour can be suppressed by setting the cancelInvalid to false in options passed to the Validator constructor.

action

validate("change:source change:target", function() { .. });

callback

callback(err, command, next)

The validation function. An arbitrary number of validation functions can be passed to validate(). Every callback has the following signature:

Where err is an error from the previous callback.

The command parameter is a record from the CommandManager stack. It holds information about an action in the graph.

See below for the structure of a command. This command says that a basic.Rect element has been moved by 50px down.

{
  "action" : "change:position"
  "data": {
    "id":"e0552cf2-fb05-4444-a9eb-3636a4589d64", // id of the cell it was manipulated with
    "type":"basic.Rect", // type of the cell

    // change:attribute events have always these two attributes filled
    "previous": { "position":{"x":50,"y":50} },
    "next": { "position": {"x":50,"y":100}},
  },
  "batch":true, // is command part of a batch command?
  "options":{} // Backbone options that are passed through the listeners when passed as the last argument to the Backbone Model set() method.
}

The add and remove actions have previous and next object empty. They hold all the cell attributes in the attributes object so that the CommandManager is able to reconstruct the whole cell if it has to. See below for an example of such a command structure:

{
  "action": "add",
  "data" : {
    "id" : "28de715b-62a7-4130-a729-1bcf7dbb1f2b",
    "type":"basic.Circle",

    //empty attributes
    "previous":{},
    "next":{},

    // all cells attributes
    "attributes": {
      "type":"basic.Circle",
      "size": {
        "width":50,
       "height":30
      },
     "position":{"x":1220,"y":680},
     "id":"28de715b-62a7-4130-a729-1bcf7dbb1f2b",
     "attrs" : {
       "circle" : {
         "width":50,
         "height":30
       }
     }
  "batch":true,
  "options" : {
    "add":true,
    "merge":false,
    "remove":false
  }
}

The next parameter is a function accepting one argument - an error passed to the next callback in a row.