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.
Include joint.dia.command.js to your HTML:
<script src="joint.dia.command.js"></script>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(); });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.
The joint.dia.CommandManager constructor takes up to three parameters.
Is the graph the CommandManager listens to.
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 });A regular expression specifying what cell's attributes the CommandManager listens to. Default regex is /^(?:add|remove|change:\w+)$/.
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 */
}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 */
}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' })
Function redo(opt) go back to whatever was previously undo()ed.
Function cancel(opt) same as undo() but does not store the undo-ed command to the redoStack. Canceled command therefore cannot be redo-ed.
Function hasUndo() true if there is something in the undoStack.
Function hasRedo() true if there is something in the redoStack
Function reset() clears both undoStack and redoStack.
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.
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.
The plugin fires the following events.
| Event Name | Handler Signature | Description |
|---|---|---|
| stack:undo | (commandUndone, opt) |
Triggered when a command was undone. |
| stack:redo | (commandRedone, opt) |
Triggered when a command were redone. |
| stack:push | (commandPushedToUndoStack, opt) |
Triggered when a command were added to the stack. |
| stack:cancel | (commandCanceled, opt) |
Triggered when a command was canceled. |
| stack:reset | (opt) |
Triggered when all commands were reset. |
| stack | (opt) |
Triggered when any change was made to stacks. |
commandManager.on('stack', function(opt) {
if (this.hasUndo()) { /* do something */ }
if (this.hasRedo()) { /* do something else */ }
});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).
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>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.)
The joint.dia.Validator constructor takes two parameters.
The CommandManager the validator listens to.
Determine whether to cancel an invalid command or not. If set to false, only the invalid event is triggered.
Default is true.
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.
validate("change:source change:target", function() { .. });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.
next() function means going to the next callback in the order passed to the validate() method.
If a call to the next() function is omitted, the validation for the specified action stops.