Events
Direct Subclass:
Indirect Subclass:
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 replaced. "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, resp, options) — when a model or collection has been successfully synced with the server. "error" (model_or_collection, resp, 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.
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 |
|
public |
Tell an object to listen to a particular event on an other object. |
|
public |
listenToOnce(obj: object, name: string, callback: function): Events Just like |
|
public |
Remove a previously-bound callback function from an object. |
|
public |
Bind a callback function to an object. |
|
public |
Just like |
|
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 |
Public Constructors
public constructor source
Public Methods
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.
Example:
view.listenTo(model, 'change', view.render);
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.
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.
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();
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).
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
});
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
Return:
* |
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.
Example:
view.stopListening();
view.stopListening(model);