Native: Element

Extends the Element native object to include delegations in the addEvent and addEvents methods.

Note

This library recreates in portion the functionality coming in MooTools 2.0 that supports event delegation and mirrors 2.0's syntax. Also note that this library does not support all custom events nor does it support focus and blur events.

Credits

Event checking based on the work of Daniel Steigerwald found here originally. License: MIT-style license. Copyright: Copyright (c) 2008 Daniel Steigerwald, daniel.steigerwald.cz

Element method: addEvent

Delegates the methods of an element's children to the parent element for greater efficiency when a filter is provided. Otherwise works normally as addEvent always does.

Syntax

myElement.addEvent(typeSelector, fn);

Arguments

1. typeSelector - (string) An event name (click, mouseover, mouseenter, etc) that should be monitored paired with a selector (see example) to limit functionality to child elements.
2. fn - (function) The callback to execute when the event occurs (passed the event just like any other addEvent usage and a second argument, the element that matches your selector that was clicked).

Example

$(element).addEvent('click:relay(a)', function(event, clicked){
    event.preventDefault(); //don't follow the link
    alert('you clicked a link!');
    //you can reference the element clicked with the second
    //argument passed to your callback
    clicked.setStyle('color', '#777'); 
});

Returns

• element - This element.

Notes

• By delegating events to parent objects you can dramatically increase the efficiency of your pages. Consider the example above. You could attach events to every link on a page - which may be hundreds of DOM elements - or you can delegate the event to the document body, evaluating your code only when the user actually clicks a link (instead of on page load/domready).
• Include Selectors.js to use more complex selectors.
• You can use any selector in combination with any event
• You cannot delegate the blur or focus events for elements. This is a limitation in how MooTools manages events internally (and prevents memory leaks) and these two events cannot be delegated until this code is refactored. Look for it in MooTools 2.0.
• Be wary of the cost of delegation; for example, mouseover/mouseout delegation on an entire document can cause your page to run the selector constantly as the user moves his or her mouse around the page. Delegation is not always the best solution.
• Delegation is especially useful if you are using AJAX to load content into your pages dynamically, as the contents of an element can change with new elements added or others removed and your delegated events need not change.
• In general it is always better to delegate to the closest parent to your elements as possible; delegate to an element in the page rather than the document body for example.

Element method: addEvents

Delegates the events to the parent just as with addEvent above.

Syntax

myElement.addEvents(events);

Arguments

1. events - (events) A key/value set of event names and methods to attach as event listeners

Example

myElement.addEvents({
    //monitor an element for mouseover
    mouseover: fn,
    //but only monitor child links for click
    'click:relay(a)':fn2
});

Element method: removeEvent

Removes a method from an element as removeEvent always does. Provided here just for clarity.

Syntax

myElement.removeEvent(type, fn);

Arguments

1. type - (string) An event name (click, click:relay(selector), etc) that should was originally added.
2. fn - (function; optional) A pointer to the original call back passed when the event was originally added.

Example

var monitor = function(event, element){ alert('you clicked a link!')};
$(element).addEvent('click:relay(a)', monitor);
//link clicks are delegated to element
//...now we remove the delegation:
$(element).removeEvent('click:relay(a)', monitor);

Returns

• element - This element.

Notes

This syntax is exactly the same as removeEvent always works. If your method was used to delegate that event previously, the delegation will be removed.

Element method: removeEvents

Removes a series of methods from delegation if the functions were used for delegation or else works as removeEvents always does. Provided here for clarity.

Syntax

myElement.removeEvents(events, fn);

Arguments

1. events - (mixed) If a string (like 'click' or 'click:relay(a)'), all click events are removed as removeEvents normally works. Otherwise each method defined in the key/value set of event types/functions is removed. If the method was used for delegation, the delegation is removed.
2. fn - (function) A pointer to the original call back passed when the event was originally added.

Example

var monitor = function(){ alert('you clicked or moused over a link!')};
$(element).addEvents({
    'mouseover:relay(a)': monitor,
    'click:relay(a)': monitor
});
//link clicks are delegated to element
//...now we remove the delegation:
$(element).removeEvents({
    'mouseover:relay(a)': monitor,
    'click:relay(a)': monitor
});
//or we could remove all click:relay(a) events
$(element).removeEvents('click:relay(a)');

Returns

• element - This element.

Notes

This syntax is exactly the same as removeEvents always works. If your methods were used to delegate those events previously, the delegations will be removed.

Element method: set

Adds delegation when you pass in an object with selector/events pairs, otherwise works normally as element.set({events...}) always does.

Examples

//same as MooTools events with set always work:
myElement.set({
    events: {
        click: function1,
        mouseover: function2
    }
});
//delegation:
myElement.set({
    events: {
        'click:relay(a)': function1,
        'mouseover:relay(a)': function2
    }
});
//mixed
myElement.set({
    events: {
        'click:relay(a)': function1,
        mouseover: function2
    }
});