Skip to content
This repository has been archived by the owner on Oct 10, 2017. It is now read-only.

Latest commit

 

History

History
138 lines (91 loc) · 4.55 KB

readme.md

File metadata and controls

138 lines (91 loc) · 4.55 KB
Raw

Deprecation notice: This library is deprecated as of Backbone v0.9.9

Backbone.EventBinder

Manage Backbone v0.9.2 events

About Backbone.EventBinder

Backbone's events are a great way to decouple parts of your system, but they have some limitations and behaviors that you need to be aware of which can cause zombie objects and memory leaks if you're not careful.

Backbone.EventBinder provides a simple mechanism for cleaning up your event bindings, including the ability to clean up anonymous callback functions!

Obsolete With Backbone v0.9.9+

Backbone v0.9.9 introduced two new methods to the Backbone.Events object: listenTo and stopListening. These methods are direct replacements for Backbone.EventBinder.

If you are using Backbone v0.9.9 or higher, you do not need this plugin. This repository will stick around for those using Backbone v0.9.2, though.

A note about context and Backbone v0.9.9: the listenTo and stopListening methods in v0.9.9 do not account for a context parameter. This means you must manually bind your callback function if you are using this version of Backbone.

Downloads And Source

Grab the source from the src folder above. Grab the most recent builds from the links below.

Standard Builds

RequireJS (AMD) Builds

Documentation

The EventBinder object provides event binding management for related events, across any number of objects that trigger the events. This allows events to be grouped together and unbound with a single call during the clean-up of an object that is bound to the events.

Ultimately, the EventBinder calls back to the standard Backbone on method of the object for which events are being handled. The benefit of using the EventBinder then, is that you no longer have to manually manage calling off for each of these events, and you can safely use anonymous callback functions as event arguments and stil be able to unbind them when needed.

Bind Events

The basic syntax for binding events is to use the bindTo method which follows the path of Backbone's on method for events, but adds one parameter to the beginning of the method call: the object that triggers the event.

For example, if you have a model that you want to listen for events from, you can use the EventBinder to manage the event for you:

var binder = new Backbone.EventBinder();

var model = new MyModel();

var handler = {
  doIt: function(){ /* ... */ }
}

// same args list as model.on, but putting the model as the first parameter
binder.bindTo(model, "change:foo", handler.doIt, handler);

You can specify a 4th parameter as the context in which the callback method for the event will be executed. If you leave the empty, the default context will be used (varies depending on other circumstances) just like Backbone's events.

binder.bindTo(model, "change:foo", someCallback, someContext);

Unbind A Single Event

When you call bindTo, it returns a "binding" object that can be used to unbind from a single event with the unbindFrom method:

var binding = binder.bindTo(model, "change:foo", someCallback, someContext);

// later in the code
binder.unbindFrom(binding);

This will unbind the event that was configured with the binding object, and remove it from the EventBinder bindings.

Unbind All Events

You can call unbindAll to unbind all events that were bound with the bindTo method:

binder.unbindAll();

This even works with in-line callback functions.

When To Use EventBinder vs on Handlers

See the wiki: When to use the EventBinder

Release History

  • v1.0.0 No changes, promoted stable code to 1.0 status
  • v0.1.0 Added support for jQuery style objects
  • v0.0.0 initial release, pulled from Marionette

License

MIT - see LICENSE.md