Events
Direct Subclass:
backbone-esnext-events / Provides the ability to bind and trigger custom named events.
(http://backbonejs.org/#Events)
An important consideration of Backbone-ESNext is that Events are no longer an object literal, but a full blown ES6 class. This is the biggest potential breaking change for Backbone-ESNext when compared to the original Backbone.
Previously Events could be mixed in to any object. This is no longer possible with Backbone-ESNext 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.
Backbone-ESNext also separates Backbone into separate modules which may be used independently of Backbone itself. In particular backbone-esnext-events is a standalone NPM module that has no other dependencies. Underscore is being removed / minimized for Backbone-ESNext where possible.
This class essentially implements the default Backbone events functionality and is extended by TyphonEvents which provides additional trigger mechanisms.
Example:
One must now use ES6 extends syntax for Backbone.Events when inheriting events functionality from Backbone-ESNext:
import Backbone from 'backbone';
class MyClass extends Backbone.Events {}
Or if importing this module directly use:
import Events from 'backbone-esnext-events';
class MyClass extends Events {}
A nice ES6 pattern for creating a named events instance is the following:
import Backbone from 'backbone';
export default new Backbone.Events();
Or if importing this module directly use:
import Events from 'backbone-esnext-events';
export default new 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.
backbone-esnext-events provides a default main eventbus implementation found in `src/mainEventbus.js`.
Constructor Summary
Public Constructor | ||
public |
|
Member Summary
Private Members | ||
private |
_events: * |
Method Summary
Public Methods | ||
public |
bind(): * Delegates to |
|
public |
Tell an object to listen to a particular event on an other object. |
|
public |
Just like |
|
public |
Remove a previously-bound callback function from an object. |
|
public |
Bind a callback function to an object. |
|
public |
Just like |
|
public |
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
Private Members
private _events: * source
Public Methods
public listenTo(obj: object, name: string, callback: function, context: object): 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, context: object): 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, context: object): 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);