[Summary view] [Print] [Text view]

   1  @title Concepts: Event Delegation
   2  @group concepts
   3  
   4  Explains Javelin event delegation with @{class:JX.Stratcom}.
   5  
   6  = Overview =
   7  
   8  Javelin provides event delegation as a core feature of the library, orchestrated
   9  with @{class:JX.Stratcom}. Event delegation means that the library listens to
  10  every event in the document and then delegates them to handlers you install,
  11  as opposed to you installing handlers on specific nodes for specific events you
  12  are interested in.
  13  
  14  Event delegation can greatly simplify event handling for many types of user
  15  interactions, and can also be used to do more traditional event listening for
  16  specific events on specific nodes. The goal is to provide a strictly more
  17  powerful event model, which gives you a very general delegation toolkit for
  18  interactions where delegation makes sense but refines into a very specific
  19  toolkit when you need less generality.
  20  
  21  Beyond DOM events, Stratcom provides a general event delegation framework which
  22  Javelin classes integrate with.
  23  
  24  = Event Delegation Basics =
  25  
  26  Javelin routes events based on the **event type** and **sigil set**.
  27  
  28  The **event type** is a string with a general description of the event, and
  29  includes the DOM event types like 'click' and 'keydown'. It may also be a
  30  class-specific event (JX.Duck might emit 'quack').
  31  
  32  The **sigil set** is a list of sigils (see @{article:Concepts: Sigils and
  33  Metadata}) for the event. If the event is a DOM event, Javelin builds the
  34  sigil set by walking up the DOM tree from the event target and collecting all
  35  the sigils on nodes (it also collects some other data into the sigil set,
  36  see "Magic Sigils" below). If the event is a class event, Javelin walks up
  37  the class hierarchy collecting class names. If the event is a raw event invoked
  38  with @{method:JX.Stratcom.invoke}, the caller must provide the sigil set.
  39  
  40  When you install an event handler, you specify the event type and the (possibly
  41  empty) sigil set you want to listen for.
  42  
  43  When an event is invoked, Javelin finds all the listeners for that event type
  44  and compares their sigil sets with the event's sigil set. If all of the sigils
  45  in a callback's sigil set appear in the event's sigil set, the callback is
  46  invoked. Generally, this mechanism allows you to ignore events you are not
  47  interested in.
  48  
  49  = Listening to General DOM Events =
  50  
  51  You can listen to general DOM events with @{method:JX.Stratcom.listen}. This
  52  method allows you to select which types of events you want to receive, and
  53  which elements must be involved in the event:
  54  
  55    lang=js
  56    JX.Stratcom.listen(
  57      'click',          // Node
  58      null,             // Sigil set
  59      function(e) {     // Callback
  60        // ...
  61      });
  62  
  63  This listens to all clicks on all elements in the document. More likely, you
  64  want to listen only to some clicks. You accomplish this by annotating your
  65  document with Javelin sigils (see @{article:Concepts: Sigils and Metadata})
  66  and specifying a set of sigils which must be present between the target node
  67  and the document root. For instance, your document might look like this:
  68  
  69    lang=html
  70    <a href="#" data-sigil="important">Important!</a>
  71    <a href="#">Some Other Link</a>
  72  
  73  If you install a handler like the one above, you'll get callbacks for every
  74  click, no matter which link it is or even if it's on the document itself. If
  75  you just want clicks on the "Important!" link, you can install a more specific
  76  handler:
  77  
  78    lang=js
  79    JX.Stratcom.listen(
  80      'click',
  81      'important',    // Listen only to this sigil set
  82      function(e) {
  83        // ...
  84      });
  85  
  86  Now you will receive a callback only when the event target or some ancestor of
  87  it has the "important" sigil, i.e., only when the user clicks on the
  88  "Important!" link. You can also specify multiple sigils; ancestors must have
  89  all of the sigils for you to get a callback:
  90  
  91    lang=js
  92    JX.Stratcom.listen(
  93      'click',
  94      ['menu', 'item'], // Listen only for clicks on menu items.
  95      function(e) {
  96        // ...
  97      });
  98  
  99  = Listening to Specific DOM Events =
 100  
 101  You can listen to specific DOM events with @{method:JX.DOM.listen}. This method
 102  works like @{method:JX.Stratcom.listen} but takes a DOM node as the first
 103  parameter and listens only for events within that node:
 104  
 105    lang=js
 106    JX.DOM.listen(
 107      node,             // Node
 108      'click',          // Event type(s)
 109      null,             // Sigil set
 110      function(e) {     // Callback
 111        // ...
 112      });
 113  
 114  This is similar to setting ##node.onclick## or ##node.addEventListener##, but
 115  uses the Javelin delegation core. You can also provide a sigil set, which works
 116  just like @{method:JX.Stratcom.listen} general events. This is useful if your
 117  node is a container, like a ##<div />##, with a lot of stuff in it.
 118  
 119  
 120  = DOM Event Flow =
 121  
 122  Events dispatched within the DOM propagate using a bubbling method, as detailed
 123  by http://www.w3.org/TR/DOM-Level-3-Events/#event-flow
 124  Listeners assigned using @{method:JX.Stratcom.listen} or @{method:JX.DOM.listen}
 125  are called in order of the deepest node in the DOM of the nodes which match the
 126  sigil set listened to.
 127  
 128  In this example the second listener, subscribed to 'inner', will be called
 129  before the listener subscribed to 'outer'
 130  
 131    lang=html
 132    <div data-sigil="outer">
 133      <div data-sigil="inner">
 134        Click Me
 135      </div>
 136    </div>
 137  
 138    <script type="text/javascript">
 139    JX.Stratcom.listen('click', ['outer'], function(e) { ... });
 140    JX.Stratcom.listen('click', ['inner'], function(e) { ... });
 141    </script>
 142  
 143  
 144  = Listening to Class Events =
 145  
 146  Beyond DOM events, you can also listen to class events. Every class installed
 147  by Javelin has static and instance methods called ##listen## (see
 148  @{method:JX.Base.listen}). The static method allows you to listen for all events
 149  emitted by every instance of a class and its descendants:
 150  
 151    lang=js
 152    JX.Animal.listen(
 153      'meow',
 154      function(e) {
 155        // Listen for ANY 'meow' from any JX.Animal instance or instance which
 156        // extends JX.Animal.
 157      });
 158  
 159  The instance method allows you to listen for all events emitted by that
 160  specific instance:
 161  
 162    lang=js
 163    var cat = new JX.Cat();
 164    cat.listen(
 165      'meow',
 166      function(e) {
 167        // Listen for 'meow' from only this cat.
 168      });
 169  
 170  = Magic Sigils =
 171  
 172  Javelin implements general delegation by building and comparing sigil sets. Some
 173  of these sigils are not DOM sigils, but derived from other things:
 174  
 175    - ##id:*## ID sigils are generated when an examined node has an "id" property.
 176    - ##obj:*## Object sigils are generated when an event affects a class
 177      instance.
 178    - ##class:*## Class sigils are generated while walking an affected instance's
 179      class chain.
 180    - ##tag:*## Tag sigils are generated by examining the tag names of DOM nodes.
 181  
 182  For instance, you can listen to all clicks on ##<a />## tags in a document like
 183  this:
 184  
 185    lang=js
 186    JX.Stratcom.listen(
 187      'click',
 188      'tag:a',
 189      function(e) {
 190        // ...
 191      });