Proxy events

See also: method calls from templates

Ractive has a concept of proxy events, which translate a user action (e.g. a mouseclick) defined via an event directive into an intention (e.g. 'select this option'). This allows you to handle user interaction in a readable, declarative fashion, without resorting to peppering your markup with class names to use as 'hooks' (which must then be kept consistent between your markup and your JavaScript code).

As with all events in Ractive, you subscribe with ractive.on() (also see publish-subscribe). Proxy events declare the handler name of the event that will be fired, along with any optional arguments:

ractive = new Ractive({
  el: 'body',
  template: '<button on-click="activate">click me!</button>'
});
ractive.on( 'activate', function ( event ) {
  alert( 'Activating!' );
});

In this example, it is activate (and not click!) that is the name of the handler event that will be fired for any registered handlers created via ractive.on().

Event arguments

The event object

The first argument to a proxy event handler is always a Ractive event object. It contains various properties:

In the example above, event.keypath might be items.0 for the first item in the list, items.1 for the second, and so on. The event.index map would have a property i, which would correspond to those indices.

The event object is also available in event handlers using this.event, see publish-subscribe for more details.

Custom arguments

NOTE: Arguments to proxy events have been deprecated because they are too easy to break. If you need to pass arguments with your event, you can use @this.fire('myEvent', event, arg1, arg2, etc).

We might want to pass arguments to our handler in addition to the event object. We can do that by listing them, comma-separated, after the event name:

<h1>Let's shop!</h1>
<ul>
  {{#each items: i}}
    <li>
      <p>{{i+1}}: {{description}}</p>
      <label><input value='{{qty}}'> Quantity</label>
      <!-- when the user clicks this button, add {\{qty}} of this item -->
      <button on-click='addToCart:{{this}},{{qty}}'>Add to cart</button>
    </li>
  {{/each}}
</ul>
ractive.on( 'addToCart', function ( event, item, qty ) {
  /* code goes here */
});

Cancelling DOM events

If you return false from a proxy event handler, ractive will automatically call both preventDefault() and stopPropagation() on the original DOM event.

Note that returning false has a dual purpose of both cancelling further bubbling up the view hierarchy event bubbling as well as cancelling the DOM Event if the event was DOM-based.

If you only want to cancel the DOM event, you can call the appropriate methods directly on event.original or this.event.original, which are both references to the current DOM event object.

Reserved event names

Note: the built-in lifecycle events are reserved, which means you can't use their names as proxy events.

Dynamic proxy event names

Note: This functionality is deprecated and will be removed in 0.9. If you need dynamic event names to fire, you can use a method event calling fire with an expression for the name. If you just need an event to be dynamically subscribed, you can place it in an {{#if}} conditional.

Mustache references can be used as proxy event names:

<button on-click="{{handler}}">click me!</button>

In practice this is of limited value, but a more important side effect is that if no handler is specified (a falsey value) the DOM event is not subscribed and will unsubscribe or resubscribe as the handler value changes. Combined with a conditional section, this allows a proxy event to be conditionally subscribed at the DOM level:

<button on-click="{{#active}}select{{/}}">click me!</button>

In this example, the DOM click event is subscribed and unsubscribed as the value of active is truthy or falsey.