Home Manual ReferenceGraphs Source Repository
public class | source

Events

Backbone.Events - Provides the ability to bind and trigger custom named events. (http://backbonejs.org/#Events)

An important consideration of Backbone-ES6 is that Events are no longer an object literal, but a full blown ES6 class. This is the biggest potential breaking change for Backbone-ES6 when compared to the original Backbone.

Previously Events could be mixed in to any object. This is no longer possible with Backbone-ES6 when working from source or the bundled versions. It should be noted that Events is also no longer mixed into Backbone itself, so Backbone is not a Global events instance.

Catalog of Events: Here's the complete list of built-in Backbone 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 or removed from 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. "change:[attribute]" (model, value, options) — when a specific attribute has been updated. "destroy" (model, collection, options) — when a model is destroyed. "request" (model_or_collection, xhr, options) — when a model or collection has started a request to the server. "sync" (model_or_collection, response, options) — when a model or collection has been successfully synced with the server. "error" (model_or_collection, response, options) — when a model's or collection's request to the server has failed. "invalid" (model, error, options) — when a model's validation fails on the client. "route:[name]" (params) — Fired by the router when a specific route is matched. "route" (route, params) — Fired by the router when any route has been matched. "route" (router, route, params) — Fired by history when any route has been matched. "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.

Example:

This no longer works:

let object = {};
_.extend(object, Backbone.Events);
object.on('expand', function(){ alert('expanded'); });
object.trigger('expand');

One must now use ES6 extends syntax for Backbone.Events when inheriting events functionality:
import Backbone from 'backbone';

class MyClass extends Backbone.Events {}
A nice ES6 pattern for creating a named events instance is the following:

import Backbone from 'backbone';

export default new Backbone.Events();

This module / Events instance can then be imported by full path or if consuming in a modular runtime by creating
a mapped path to it.

Constructor Summary

Public Constructor
public

Method Summary

Public Methods
public

bind(): *

Delegates to on.

public

listenTo(obj: object, name: string, callback: function): Events

Tell an object to listen to a particular event on an other object.

public

listenToOnce(obj: object, name: string, callback: function): Events

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

public

off(name: string, callback: function, context: object): Events

Remove a previously-bound callback function from an object.

public

on(name: string, callback: function, context: object): *

Bind a callback function to an object.

public

once(name: string, callback: function, context: object): *

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

public

stopListening(obj: object, name: string, callback: function): Events

Tell an object to stop listening to events.

public

Trigger callbacks for the given event, or space-delimited list of events.

public

unbind(): *

Delegates to off.

Public Constructors

public constructor source

Public Methods

public bind(): * source

Delegates to on.

Return:

*

public listenTo(obj: object, name: string, callback: function): Events source

Tell an object to listen to a particular event on an other object. The advantage of using this form, instead of other.on(event, callback, object), is that 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.

Params:

NameTypeAttributeDescription
obj object

Event context

name string

Event name(s)

callback function

Event callback function

Return:

Events

Example:

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

See:

public listenToOnce(obj: object, name: string, callback: function): Events source

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

Params:

NameTypeAttributeDescription
obj object

Event context

name string

Event name(s)

callback function

Event callback function

Return:

Events

See:

public off(name: string, callback: function, context: object): Events source

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.

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

Params:

NameTypeAttributeDescription
name string

Event name(s)

callback function

Event callback function

context object

Event context

Return:

Events

Example:

// 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 `object`.
object.off();

See:

public on(name: string, callback: function, context: object): * source

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

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

Params:

NameTypeAttributeDescription
name string

Event name(s)

callback function

Event callback function

context object

Event context

Return:

*

Example:

The event string may also be a space-delimited list of several events...
book.on("change:title change:author", ...);
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 Backbone 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,
   "destroy": bookView.remove
});

See:

public once(name: string, callback: function, context: object): * source

Just like on, but causes the bound callback to fire only once before being removed. Handy for saying "the next time that X happens, do this". 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

Params:

NameTypeAttributeDescription
name string

Event name(s)

callback function

Event callback function

context object

Event context

Return:

*

See:

public stopListening(obj: object, name: string, callback: function): Events source

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.

Params:

NameTypeAttributeDescription
obj object

Event context

name string

Event name(s)

callback function

Event callback function

Return:

Events

Example:

view.stopListening();

view.stopListening(model);

See:

public trigger(name: string): Events source

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

Params:

NameTypeAttributeDescription
name string

Event name(s)

Return:

Events

See:

public unbind(): * source

Delegates to off.

Return:

*