class method Event.on
Event.on(element, eventName[, selector], callback) → Event.Handler
-
element
(Element
|String
) – The DOM element to observe, or its ID. -
eventName
(String
) – The name of the event, in all lower case, without the "on" prefix — e.g., "click" (not "onclick"). -
selector
(String
) – A CSS selector. If specified, will callcallback
only when it can find an element that matchesselector
somewhere in the ancestor chain between the event's target element and the givenelement
. -
callback
(Function
) – The event handler function. Should expect two arguments: the event object and the element that received the event. (Ifselector
was given, this element will be the one that satisfies the criteria described just above; if not, it will be the one specified in theelement
argument). This function is always bound toelement
.
Listens for events on an element's descendants, optionally filtering to match a given CSS selector.
Creates an instance of Event.Handler
, calls Event.Handler#start
,
then returns that instance. Keep a reference to this returned instance if
you later want to unregister the observer.
Usage
Event.on
can be used to set up event handlers with or without event
delegation. In its simplest form, it works just like Event.observe
:
$("messages").on("click", function(event) { // ... });
An optional second argument lets you specify a CSS selector for event
delegation. This encapsulates the pattern of using Event#findElement
to retrieve the first ancestor element matching a specific selector.
$("messages").on("click", "a.comment", function(event, element) { // ... });
Note the second argument in the handler above: it references the
element matched by the selector (in this case, an a
tag with a class
of comment
). This argument is important to use because within the
callback, the this
keyword will always refer to the original
element (in this case, the element with the id of messages
).
Event.on
differs from Event.observe
in one other important way:
its return value is an instance of Event.Handler
. This instance
has a stop
method that will remove the event handler when invoked
(and a start
method that will attach the event handler again after
it's been removed).
// Register the handler: var handler = $("messages").on("click", "a.comment", this.click.bind(this)); // Unregister the handler: handler.stop(); // Re-register the handler: handler.start();
This means that, unlike Event.stopObserving
, there's no need to
retain a reference to the handler function.