Docs/Element/Element.Delegation.md

   1 Type: Element {#Element}
   2 ========================
   3
   4 Extends the [Element][] type to include event-delegation in its event system.
   5
   6 Event delegation is a common practice where an event listener is attached to a parent element to monitor its children rather than attach events to every single child element. It's more efficient for dynamic content or highly interactive pages with a lot of DOM elements.
   7
   8 ### Demo:
   9
  10 * [Element.Delegation](http://mootools.net/demos/?demo=Element.Delegation)
  11
  12 ### Example:
  13
  14 An example of how delegation is usually applied. Delegation is extra useful when working with dynamic content like AJAX.
  15
  16         var myElement = $('myElement');
  17         var request = new Request({
  18                 // other options
  19                 onSuccess: function(text){
  20                         myElement.set('html', text); // No need to attach more click events.
  21                 }
  22         });
  23         // Adding the event, notice the :relay syntax with the selector that matches the target element inside of myElement.
  24         // Every click on an anchor-tag inside of myElement executes this function.
  25         myElement.addEvent('click:relay(a)', function(event, target){
  26                 event.preventDefault();
  27                 request.send({
  28                         url: target.get('href')
  29                 });
  30         });
  31
  32 ### Notes:
  33
  34 * 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.
  35 * 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).
  36 * You can use any selector in combination with any event
  37 * 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.
  38 * 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.
  39
  40 Element method: addEvent {#Element:addEvent}
  41 --------------------------------------------
  42
  43 Delegates the methods of an element's children to the parent element for greater efficiency when a selector is provided. Otherwise it will work like [addEvent][].
  44
  45 ### Syntax:
  46
  47         myElement.addEvent(typeSelector, fn);
  48
  49 ### Arguments:
  50
  51 2. typeSelector - (*string*) An event name (click, mouseover, etc) that should be monitored paired with a selector (see example) to limit functionality to child elements.
  52 3. 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).
  53
  54
  55 ### Example:
  56
  57         // Alerts when an anchor element with class 'myStyle' is clicked inside of myElement
  58         document.id(myElement).addEvent('click:relay(a.myStyle)', function(){
  59                 alert('hello');
  60         });
  61
  62
  63         document.id('myElement').addEvent('click:relay(a)', function(event, clicked){
  64                 event.preventDefault(); //don't follow the link
  65                 alert('you clicked a link!');
  66                 // You can reference the element clicked with the second
  67                 // Argument passed to your callback
  68                 clicked.setStyle('color', '#777');
  69         });
  70
  71 ### Returns:
  72
  73 * *element* - This element.
  74
  75 Element method: addEvents {#Element:addEvents}
  76 ----------------------------------------------
  77
  78 Delegates the events to the parent just as with addEvent above. Works like [addEvents][].
  79
  80 ### Example:
  81
  82         $('myElement').addEvents({
  83                 // monitor an element for mouseover
  84                 mouseover: fn,
  85                 // but only monitor child links for clicks
  86                 'click:relay(a)': fn2
  87         });
  88
  89
  90 Element method: removeEvent {#Element:removeEvent}
  91 --------------------------------------------------
  92
  93 Removes a method from an element like [removeEvent][].
  94
  95 ### Example:
  96
  97         var monitor = function(event, element){
  98                 alert('you clicked a link!');
  99         };
 100
 101         $('myElement').addEvent('click:relay(a)', monitor);
 102         // link clicks are delegated to element
 103
 104         // remove delegation:
 105         $('myElement').removeEvent('click:relay(a)', monitor);
 106
 107
 108 Element method: removeEvents {#Element:removeEvents}
 109 ----------------------------------------------------
 110
 111 Removes a series of methods from delegation if the functions were used for delegation or else works like [removeEvents][].
 112
 113 ### Example:
 114
 115         var monitor = function(){
 116                 alert('you clicked or moused over a link!');
 117         };
 118
 119         $('myElement').addEvents({
 120                 'mouseover:relay(a)': monitor,
 121                 'click:relay(a)': monitor
 122         });
 123
 124         // link clicks are delegated to element
 125         // remove the delegation:
 126         $('myElement').removeEvents({
 127                 'mouseover:relay(a)': monitor,
 128                 'click:relay(a)': monitor
 129         });
 130
 131         // remove all click:relay(a) events
 132         $('myElement').removeEvents('click:relay(a)');
 133
 134
 135
 136 [Element]: /core/Element/Element
 137 [addEvent]: /core/Element/Element.Event#Element:addEvent
 138 [addEvents]: /core/Element/Element.Event#Element:addEvents
 139 [removeEvent]: /core/Element/Element.Event#Element:removeEvent
 140 [removeEvents]: /core/Element/Element.Event#Element:removeEvents