Events

edit this page

Like many libraries, Ractive implements the publish/subscribe mechanism to allow you to trigger behaviour at certain points.

There are three types of events - standard events, proxy events, and custom events. They all use the same interface - ractive.on():

ractive = new Ractive({
  el: myContainer,
  template: myTemplate
});

ractive.on( 'teardown', function () {
  alert( 'Bye!' );
});

In all cases, event handlers will be called with ractive as this.

Standard events

Standard events are those emitted by all Ractive instances:

change

Fired whenever any data changes inside of a Ractive instance. To observe only on specific keypaths see Observers.

teardown

Fired whenever ractive.teardown() is called. No arguments.

Proxy events

Proxy events are a convenient way of handling user interaction. Instead of doing someElement.addEventListener( eventName, handler ) or $( someSelector ).on( eventName, handler ), you can write the name of a proxy event right into your template:

<button on-click='activate'>Activate!</button>
<button on-click='deactivate'>Deactivate!</button>

ractive = new Ractive({
  el: myContainer,
  template: myTemplate
});

ractive.on({
  activate: function ( event ) {
    // do something
  },
  deactivate: function ( event ) {
    // do something
  }
});

This way we don't have to bother traversing the DOM or storing references to elements and handlers. We also don't need to worry about removing event handlers when we detach chunks of the DOM - Ractive takes care of it.

Proxy event handlers receive an event argument. This isn't the same as the event argument you'd receive in a traditional handler (i.e. bound with node.addEventListener or $(node).on() etc), but an object with five properties:

• node - the relevant element
• original - the underlying DOM event (useful for event.original.preventDefault() etc)
• keypath - the keypath of the current context
• context - the value of ractive.get(event.keypath)
• index - a map of index references

TODO - explain what the hell the last three of those things meant... In the meantime folks, do a console.log( event ) inside your handlers and all will be revealed!

Because of the way proxy events work, they more or less eliminate the need for event delegation.

Any standard DOM event that an element supports can be used (e.g. on-mouseover='highlight', on-touchstart='dragstart', on-blur='submit', on-error='loadFallbackImage', and so on), as can non-standard event plugins such as on-tap.

TODO - chained proxy events, additional arguments in custom event definitions

Reserved Event Names

In order for Ractive to provide a level of notification that is desirable there are 4 reserved event names. You may listen for these names as you would with normal events however these events will not contain the typical structure of an event that you'd exepect.

change

the change event is fired when any data changes from the template and the callback is called with a single argument that is the reference to the part of the data object that was updated.

update

the update event is fired when any data promatically changes and the callback is called with a single argument that is the new data object that was updated.

reset

the reset event is fired when the Ractive instance is reset from the reset function, the callback is called with an empty object

teardown

the teardown event is fired when the Ractive instance is destroyed from the teardown function, the callback is called with no arguments

Custom events

You can easily create events of your own with ractive.fire(). This is most useful in the context of subclasses created with Ractive.extend().

In this example, we respond to the user clicking on an item by firing a selected event with the item data as the first (and only) argument:

<div class='catalogue'>
  {{#items:i}}
    <div on-tap='select' data-index='{{i}}'>
      {{>content}}
    </div>
  {{/items}}
</div>

var Catalogue = Ractive.extend({
  template: catalogueTemplate,
  partials: { content: contentPartial }, // pretend we made one
  init: function ( options ) {
    var self = this, items = options.items;

    this.on( 'select', function ( event ) {
      var index = event.node.getAttribute( 'data-index' );
      self.fire( 'selected', items[ index ] );
    });
  }
});