Events

A module that can be mixed in to any object in order to provide it with a custom event channel. You may bind a callback to an event with on or remove with off; trigger-ing an event fires all callbacks in succession. Events do not have to be declared before they are bound, and may take passed arguments.

const object = {};
joint.util.assign(object, joint.mvc.Events);
object.on('expand', function(msg){ alert('expanded' + msg); });
object.trigger('expand', 'the example');

Built-in JointJS events

Here's the complete list of built-in JointJS events, with arguments. You're also free to trigger your own events on Models, Collections and Views as you see fit.

• "add" (model, collection, options) - when a model is added to a collection.
• "remove" (model, collection, options) - when a model is removed from a collection.
• "update" (collection, options) - single event triggered after any number of models have been added, removed or changed in a collection.
• "reset" (collection, options) - when the collection's entire contents have been reset.
• "sort" (collection, options) - when the collection has been re-sorted.
• "change" (model, options) - when a model's attributes have changed.
• "changeId" (model, previousId, options) - when the model's id has been updated.
• "change:[attribute]" (model, value, options) - when a specific attribute has been updated.
• "invalid" (model, error, options) - when a model's validation fails.
• "all" - this special event fires for any triggered event, passing the event name as the first argument followed by all trigger arguments.

Generally speaking, when calling a function that emits an event (model.set, collection.add, and so on...), if you'd like to prevent the event from being triggered, you may pass {silent: true} as an option. Note that this is rarely, perhaps even never, a good idea. Passing through a specific flag in the options for your event callback to look at, and choose to ignore, will usually work out better.

Static methods

listenTo()

object.listenTo(other, event, callback)

Tell an object to listen to a particular event on an 'other' object. listenTo allows the object to keep track of the events, and they can be removed all at once later on. The callback will always be called with object as context.

view.listenTo(model, 'change', view.render);

listenToOnce()

object.listenToOnce(other, event, callback)

Just like listenTo, but causes the bound callback to fire only once before being removed.

off()

object.off([event], [callback], [context])

Remove a previously-bound callback function from an object. If no context is specified, all of the versions of the callback with different contexts will be removed. If no callback is specified, all callbacks for the event will be removed. If no event is specified, callbacks for all events will be removed.

// Removes just the `onChange` callback.
object.off('change', onChange);

// Removes all "change" callbacks.
object.off('change');

// Removes the `onChange` callback for all events.
object.off(null, onChange);

// Removes all callbacks for `context` for all events.
object.off(null, null, context);

// Removes all callbacks on `model`(including internal JointJS events).
model.off();

Note that calling model.off(), for example, will indeed remove all events on the model — including events that JointJS uses for internal bookkeeping.

on()

object.on(event, callback, [context])

Bind a callback function to an object. The callback will be invoked whenever the event is fired. If you have a large number of different events on a page, the convention is to use colons to namespace them: "poll:start", or "change:selection".

model.on('change', ...);

// Space-delimited list for more than one event
film.on('change:title change:director', ...);

// Supply a context value for "this" when the callback is invoked by passing the optional last argument
model.on('change', this.render, this);

Callbacks bound to the special "all" event will be triggered when any event occurs, and are passed the name of the event as the first argument. For example, to proxy all events from one object to another:

proxy.on("all", function(eventName) {
    object.trigger(eventName);
});

All JointJS event methods also support an event map syntax, as an alternative to positional arguments:

book.on({
    "change:author": authorPane.update,
    "change:title change:subtitle": titleView.update
});

To supply a context value for this when the callback is invoked, pass the optional last argument: model.on('change', this.render, this) or model.on({change: this.render}, this).

once()

object.once(event, callback, [context])

Just like on, but causes the bound callback to fire only once before being removed. When multiple events are passed in using the space separated syntax, the event will fire once for every event you passed in, not once for a combination of all events.

stopListening()

object.stopListening([other], [event], [callback])

Tell an object to stop listening to events. Either call stopListening with no arguments to have the object remove all of its registered callbacks ... or be more precise by telling it to remove just the events it's listening to on a specific object, or a specific event, or just a specific callback.

view.stopListening();

view.stopListening(model);

trigger()

object.trigger(event, [*args])

Trigger callbacks for the given event, or space-delimited list of events. Subsequent arguments to trigger will be passed along to the event callbacks.