Event maps

Event Maps

An event map is an object where the properties specify a set of events to handle, and the values are the handlers for those events. The property can be in one of several forms:

eventtype

Matches a particular type of event, such as 'click'.

eventtype selector

Matches a particular type of event, but only when it appears on an element that matches a certain CSS selector.

event1, event2

To handle more than one type of event with the same function, use a comma-separated list.

The handler function receives two arguments: event, an object with information about the event, and template, a template instance for the template where the handler is defined. The handler also receives some additional context data in this, depending on the context of the current element handling the event. In a template, an element's context is the data context where that element occurs, which is set by block helpers such as #with and #each.

Example:

{
  // Fires when any element is clicked
  'click': function (event) { ... },

  // Fires when any element with the 'accept' class is clicked
  'click .accept': function (event) { ... },

  // Fires when 'accept' is clicked or focused, or a key is pressed
  'click .accept, focus .accept, keypress': function (event) { ... }
}

Most events bubble up the document tree from their originating element. For example, 'click p' catches a click anywhere in a paragraph, even if the click originated on a link, span, or some other element inside the paragraph. The originating element of the event is available as the target property, while the element that matched the selector and is currently handling it is called currentTarget.

{
  'click p': function (event) {
    var paragraph = event.currentTarget; // always a P
    var clickedElement = event.target; // could be the P or a child element
  }
}

If a selector matches multiple elements that an event bubbles to, it will be called multiple times, for example in the case of 'click div' or 'click *'. If no selector is given, the handler will only be called once, on the original target element.

The following properties and methods are available on the event object passed to handlers:

type String

The event's type, such as "click", "blur" or "keypress".

target DOM Element

The element that originated the event.

currentTarget DOM Element

The element currently handling the event. This is the element that matched the selector in the event map. For events that bubble, it may be target or an ancestor of target, and its value changes as the event bubbles.

which Number

For mouse events, the number of the mouse button (1=left, 2=middle, 3=right). For key events, a character or key code.

stopPropagation()

Prevent the event from propagating (bubbling) up to other elements. Other event handlers matching the same element are still fired, in this and other event maps.

stopImmediatePropagation()

Prevent all additional event handlers from being run on this event, including other handlers in this event map, handlers reached by bubbling, and handlers in other event maps.

preventDefault()

Prevents the action the browser would normally take in response to this event, such as following a link or submitting a form. Further handlers are still called, but cannot reverse the effect.

isPropagationStopped()

Returns whether stopPropagation() has been called for this event.

isImmediatePropagationStopped()

Returns whether stopImmediatePropagation() has been called for this event.

isDefaultPrevented()

Returns whether preventDefault() has been called for this event.

Returning false from a handler is the same as calling both stopImmediatePropagation and preventDefault on the event.

Event types and their uses include:

click

Mouse click on any element, including a link, button, form control, or div. Use preventDefault() to prevent a clicked link from being followed. Some ways of activating an element from the keyboard also fire click.

dblclick

Double-click.

focus, blur

A text input field or other form control gains or loses focus. You can make any element focusable by giving it a tabindex property. Browsers differ on whether links, checkboxes, and radio buttons are natively focusable. These events do not bubble.

change

A checkbox or radio button changes state. For text fields, use blur or key events to respond to changes.

mouseenter, mouseleave

The pointer enters or leaves the bounds of an element. These events do not bubble.

mousedown, mouseup

The mouse button is newly down or up.

keydown, keypress, keyup

The user presses a keyboard key. keypress is most useful for catching typing in text fields, while keydown and keyup can be used for arrow keys or modifier keys.

Other DOM events are available as well, but for the events above, Meteor has taken some care to ensure that they work uniformly in all browsers.