back to Overview

.on()

Registers the function as event handler for all items in the list.
Web module only.

Syntax Variants

list.on(names, eventHandler)
list.on(selector, names, eventHandler)
list.on(names, customFunc, args)
list.on(selector, names, customFunc, args)
list.on(names, eventHandler, bubbleSelector)
list.on(names, customFunc, args, bubbleSelector)

Parameters

selector (optional)
a selector string for $() to register the event only on those children of the list elements that match the selector. Supports all valid parameters for $() except functions.
names
the space-separated names of the events to register for, e.g. 'click'. Case-sensitive. The 'on' prefix in front of the name must not used. You can register the handler for more than one event by specifying several space-separated event names. If the name is prefixed with '|' (pipe), the event will be passed through and the event's default actions will be executed by the browser. If the name is prefixed with '?', the event will only be passed through if the handler returns true.
eventHandler
the callback function(event, index) to invoke when the event has been triggered:
event
The original DOM event object.
index
The index of the target object in the Minified list .
this
A Minified list containing the target element as only item (same as event.target).
(callback return value)
The return value will only be used if the event name prefix was '?'. Then, a return value false will stop all further processing of the event and disable event bubbling. true will keep the event alive.
customFunc
a function to be called instead of a regular event handler with the arguments given in args. 'this' will be a Minified list containing the target element as only item (same element as event.target).
args (optional)
an array of arguments to pass to the custom callback function instead of the event objects. If omitted, the function is called as event handler with the event object as argument.
bubbleSelector (optional)
a selector string for $() to receive only events that bubbled up from an element that matches this selector. Supports all valid parameters for $() except functions. Analog to is(), the selector is optimized for the simple patterns '.classname', 'tagname' and 'tagname.classname'.
(return value)
the list

Description

Registers the function as event handler for all items in the list.

By default, Minified cancels event propagation and disables element's default behavior for all elements that have an event handler. You can override this, either by prefixing the event name with a '|', or by prefixing them with '?' and returning a true in the handler. Both will reinstate the original JavaScript behavior.

Handlers are called with the original event object as first argument, the index of the source element in the list as second argument and 'this' set to the source element of the event (e.g. the button that has been clicked).

Instead of the event objects, you can also pass an array of arguments that will be passed instead of event object and index.

Optionally you can specify two a selector strings to qualify only certain events. The first one is a selector that allows you to select only specific children of the list elements. This is mostly useful for adding events to DOM trees generated using HTML() or EE().

The second type of selector is the bubble selector that allows you to receive only events that bubbled up from elements matching the selector. The selector is executed in the context of the element you registered on to identify whether the original target of the event qualifies. If not, the handler is not called.

Minified always registers event handlers with event bubbling enabled. Event capture is not supported.

Event handlers can be unregistered using $.off().

Example

Adds a handler to all divs which paints the div background color to red when clicked. 

$('div').on('click', function() {
   this.style.backgroundColor = 'red';    // 'this' contains the element that caused the event
});

Example

Registers a handler to call a method setStatus('running') using an inline function: 

$('#myButton').on('click', function() {
   setStatus('running');
});
The previous example can bere written like this, using on()'s args parameter: 
$('#myButton').on('click', setStatus, ['running']);

Example

Adds two handlers on an input field. The event names are prefixed with '|' and thus keep their original behavior: 

$('#myInput').on('|keypress |keydown', function() {
   // do something
});

Example

Adds a click handler that will abort the operation by returning false, unless the user confirms it: 

$('#myLink').on('?click', function() {
   return window.confirm('Really leave?');
});

Example

Adds a button and registers a click handler for it using a sub-selector. 

$('#myForm').add(HTML("<li><button>click me</button></li>").on('button', 'click', myClickHandler));

Example

Adds listeners for all clicks on a table's rows using the bubble selector 'tr'. 

$('#table').on('change', 'tr', function(event, index, selectedIndex) {
   alert("Click on table row number: " + selectedIndex);
}, 'tr');
Please note that bubble selectors will even listen to events for table rows that have been added after you registered for the events.

See also..

  • off() allows you to unregister an event handler.
  • onClick() as a shortcut for 'click' events.
  • onOver() to simplify mouseover/mouseout events.
  • onFocus() as convenient way to register for focus events.
  • onChange() to get notified when an input's content changes.

Comments

comments powered by Disqus

back to Overview

Functions