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 oftarget
, 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 fireclick
.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, whilekeydown
andkeyup
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.
Please login to continue.