JointJS+ Validator

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

Action is the name of the event triggered on the graph (see List of triggered events). Multiple actions may be given separated by whitespaces.

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.

Calling 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.