Events are a powerful way of de-coupling interaction inside your application. They aren't just restricted to DOM elements, Spine gives you custom events that can be applied to any class or instance. If you're familiar with jQuery or Zepto's event API, then you'll feel right at home with Spine's event implementation. Events are a great way of de-coupling and abstracting out components inside your application.
Spine.Events is the module Spine uses for adding event support to classes. To use it, just include/extend a class with the module.
Spine.Events gives you the basic functions,
unbind(). All three have a very similar API to jQuery's event handling one, if you're familiar with that.
bind(name, callback) takes a event name and callback.
trigger(name, [*data]) takes an event name and optional data to be passed to handlers.
unbind(name, [callback]) takes a event name and optional callback.
//= CoffeeScript Tasks.bind "create", (foo, bar) -> alert(foo + bar) Tasks.trigger "create", "some", "data"
You can bind to multiple events by separating them with spaces. Callbacks are invoked in the context the event is associated with.
//= CoffeeScript Tasks.bind("create update destroy", -> @trigger("change"))
You can pass optional data arguments to
trigger() that will be passed onto event callbacks. Unlike jQuery, an event object will not be passed to callbacks.
//= CoffeeScript Tasks.bind "create", (name) -> alert(name) Tasks.trigger "create", "Take out the rubbish"
Spine has taken inspiration from backbone with
stopListening(). These allow an object to listen to a events on another object. The advantage of using:
//=CoffeeScript todolist = new TodoList() todoList.listenTo currentTask, 'work-done, completed', -> ...
//=CoffeeScript currentTask.bind 'work-done, completed' -> ...
is that the former allows the listening object to keep track of the events meaning they can be reliably removed all at once later on, for example if you
destroy() the listening object the events will automattically be unbound leaving things nice and tidy!
Although you might never use
Spine.Events in your own classes, you will use it with Spine's models and controllers.
You can also bind and trigger global events in your application by calling
However, keep in mind that is often not such a great idea, as it introduces a degree of coupling into your code. Always ask yourself if you can use routes instead, or perhaps local controller events.
For more information about events, please see the full API documentation.