Validator

The plugin allows you keep the diagram in a valid state by running a set of callbacks to determine if a command is valid.

To learn more about the plugin, check out the Data validity section.

constructor

constructor(options: dia.Validator.Options);

The Validator constructor takes the following parameters:

cancelInvalid

cancelInvalid?: boolean;

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

The default is true.

commandManager

commandManager: dia.CommandManager;

[required] An instance of CommandManager the validator listens to.

Methods

addRule()

validator.addRule(actions: string, ...callback: Array<dia.Validator.Callback>): void;

Registers validation callbacks for a given set of actions.

The Validator listens to commands added to the stack of the linked CommandManager and runs the set of validation callbacks whenever a command with one of the registered actions is detected.

If the last callback returns next(err) (where err is not undefined) or throws an error, the validation of the action is considered unsuccessful and the command is cancelled.

note

Command cancellation can be suppressed by setting the cancelInvalid option to false.

If the last callback returns next() with no parameters, the validation of the action is considered successful and the command is kept.

actions

actions: string

The actions parameter is a whitespace-separated string specifying one or more names of events triggered on the CommandManager's linked model (i.e. a dia.Graph or mvc.Model), for which validation callbacks are to be run. See the list of triggered Graph events and model events for reference.

validator.addRule('add', () => { /* ... */ });
validator.addRule('change:source change:target', () => { /* ... */ });

If multiple sets of callbacks are associated with a single action (with multiple addRule() calls), the sets of callbacks are executed in the same order as the order in which the addRule() calls were executed.

...callbacks

...callbacks: Array<dia.Validator.Callback>

Any number of validation callbacks can be passed to the addRule() method.

const callback1 = (err, command, next) => { /* ... */ };
const callback2 = (err, command, next) => { /* ... */ };

validator.addRule(action, callback1, callback2);

When a command with a name listed in actions is added to the stack of the linked CommandManager, the callbacks are executed in the same order as the order in which they were passed to the addRule() method.

note

Validation callbacks are invoked in try-catch block. If a callback throws an error, the error is passed to the next callback in line.

Every validation callback has the following signature:

• The err parameter is an error passed from the previous callback to this callback (if any).
• The command parameter is the CommandManager command which is currently being evaluated.
• The next parameter is a function of type NextRule which accepts one argument - the error that should be passed by this callback to the next callback in line.
  • Calling the next() function means that the validation of the action should proceed to the next callback.
  • Omitting a call to the next() function means that the validation of the action should stop (and be considered successful).

clearRules()

validator.clearRules(): void;

Removes all validation callbacks previously registered for all actions.

removeRule()

validator.removeRule(actions: string): void;

If removeRule() is called with a single argument, it removes all validation callbacks previously registered for a given set of actions.

actions

actions: string

The actions parameter is a whitespace-separated string specifying one or more names of events triggered on the CommandManager's linked model (i.e. a dia.Graph or mvc.Model), for which previously-registered validation callbacks are to be removed.

validator.removeRule('add');
validator.removeRule('change:source change:target');

validator.removeRule(actions: string, ...callbacks: Array<dia.Validator.Callback>): void;

If removeRule() is called with additional arguments, those are understood as specific previously-registered callbacks which are to be removed for a given set of actions.

actions

actions: string

The actions parameter is a whitespace-separated string specifying one or more names of events triggered on the CommandManager's linked model (i.e. a dia.Graph or mvc.Model), for which specific previously-registered validation callbacks are to be removed.

...callbacks

...callbacks: Array<dia.Validator.Callback>

Any number of validation callbacks can be passed to the removeRule() method.

const callback1 = (err, command, next) => { /* ... */ };
const callback2 = (err, command, next) => { /* ... */ };

validator.addRule(action, callback1, callback2);
validator.removeRule(action, callback1);

// when action is detected, only callback2 is run

The array of registered callbacks is checked for each action, and all instances of all matching callbacks are removed.

validate()

validator.validate(actions: string, ...callbacks: Array<dia.Validator.Callback>): dia.Validator;

(deprecated) - Use addRule() instead.

Registers validation callbacks for a given set of actions.

The Validator listens to commands added to the stack of the linked CommandManager and runs the set of validation callbacks whenever a command with one of the registered actions is detected.

If the last callback returns next(err) (where err is not undefined) or throws an error, the validation of the action is considered unsuccessful and the command is cancelled.

note

Command cancellation can be suppressed by setting the cancelInvalid option to false.

If the last callback returns next() with no parameters, the validation of the action is considered successful and the command is kept.

actions

actions: string

The actions parameter is a whitespace-separated string specifying one or more names of events triggered on the CommandManager's linked model (i.e. a dia.Graph or mvc.Model), for which validation callbacks are to be run. See the list of triggered Graph events and model events for reference.

validator.validate('add', () => { /* ... */ });
validator.validate('change:source change:target', () => { /* ... */ });

...callbacks

...callbacks: Array<dia.Validator.Callback>

Any number of validation callbacks can be passed to the validate() method.

const callback1 = (err, command, next) => { /* ... */ };
const callback2 = (err, command, next) => { /* ... */ };

validator.validate(action, callback1, callback2);

When a command with a name listed in actions is added to the stack of the linked CommandManager, the callbacks are executed in the same order as the order in which they were passed to the validate() method.

note

Validation callbacks are invoked in try-catch block. If a callback throws an error, the error is passed to the next callback in line.

Every validation callback has the following signature:

• The err parameter is an error passed from the previous callback to this callback (if any).
• The command parameter is the CommandManager command which is currently being evaluated.
• The next parameter is a function of type NextRule which accepts one argument - the error that should be passed by this callback to the next callback in line.
  • Calling the next() function means that the validation of the action should proceed to the next callback.
  • Omitting a call to the next() function means that the validation of the action should stop (and be considered successful).

Events

The plugin fires the following events:

invalid

Triggered when an invalid command is detected.

validator.on('invalid', (command: dia.CommandManager.CommandData) => {
    console.warn('Invalid command:', command);
});

Types

The plugin uses the following types:

Callback

type Callback = (
    err: any,
    command: dia.CommandManager.CommandData,
    next: dia.Validator.NextRule
) => any;

NextRule

type NextRule = (err: any) => void;

Options

interface Options {
    commandManager: dia.CommandManager;
    cancelInvalid?: boolean;
}