Rewrote the page on Handling Events

page/events/events-to-elements.md

@@ -1,108 +1,154 @@
 ---
-title   : Connecting Events to Elements
+title   : Handling Events
+attribution:  David Mazza, jQuery Fundementals
 level: beginner
 ---
-jQuery offers convenience methods for most common events, and these are the
-methods you will see used most often.  These methods — including `$.fn.click`,
-`$.fn.focus`, `$.fn.blur`, `$.fn.change`, etc. — are shorthand for jQuery's
-`$.fn.bind` method.  The bind method is useful for binding the same handler
-function to multiple events, when you want to provide data to the event hander,
-when you are working with custom events, or when you want to pass an object of
-multiple events and handlers.
-
-```
-// Event binding using a convenience method
-$('p').click(function() {
-  console.log('click');
+jQuery provides a method `.on()` to 
+respond to any event on the selected elements. This is called an _event binding_.
+Although `.on()` isn't the only method provided for event binding, it is a best
+practice to use this for jQuery 1.7+. See history of event binding for more info.
+<!-- TODO: link to history page -->
+
+The on method provides several useful features:
+<ul>
+<li><a href="#simple-event-binding">Bind any event triggered on the selected elements to an event handler</a></li>
+<li><a href="#multiple-events-one-handler">Bind multiple events to one event handler</a></li>
+<li><a href="#multiple-events-multiple-handlers">Bind multiple events and multiple handlers to the selected elements</a></li>
+<li><a href="#event-object">Use details about the event in the event handler</a></li>
+<li><a href="#passing-data">Pass data to the event handler for custom events</a></li>
+<li><a href="#event-delegation">Bind events to elements that will be rendered in the future</a></li>
+</ul>
+### Examples
+
+#### <a name="simple-event-binding">Simple event binding</a>
+```
+// When any <p> tag is clicked, we expect to see '<p> was clicked' in the console.
+$('p').on('click', function() {
+  console.log('<p> was clicked');
 });
 ```
 
+#### <a name="multiple-events-one-handler">Many events, but only one event handler</a>
+
+Suppose you want to trigger the same event whenever the mouse hovers over or leaves 
+the selected elements. The best practice for this is to use "mouseenter mouseleave". 
+Note the difference between this and the next example.
+
+```
+// When a user focuses on or changes any input element, we expect a console message
+
+$('div').on('mouseenter mouseleave',  // bind to multiple events
+  function() {
+    console.log('mouse hovered over or left a div');
+  }
+);
 ```
-// Event biding using the `$.fn.bind` method
-$('p').bind('click', function() {
-  console.log('click');
+
+#### <a name="multiple-events-multiple-handlers">Many events and handlers</a>
+
+Suppose that instead you want different event handlers for when the mouse enters and 
+leaves an element. This is more common than the previous example. For example, if you 
+want to show and hide a tooltip on hover, you would use this. 
+
+`.on()` accepts an object containing multiple events and handlers.
+
+```
+$('div').on({
+  mouseenter: function() {
+      console.log('hovered over a div');
+    },
+  mouseleave: function() {
+      console.log('mouse left a div');
+    },
+  click: function() {
+      console.log('clicked on a div');
+    }
 });
 ```
+
+#### <a name="event-object">The event object</a>
+
+Handling events can be tricky. It's often helpful to use the extra information contained
+in the event object passed to the event handler for more control. To become familiar with 
+the event object, use this code to inspect it in your browser console after you click on 
+a `<div>` in the page. For a breakdown of the event object, see 
+<a href="/events/inside-event-handling-function/">Inside the Event Handling Function</a>.
 
 ```
-// Event binding using the `$.fn.bind` method with data
-$('input').bind(
-  'click change',  // bind to multiple events
-  { foo : 'bar' }, // pass in data
-  function(eventObject) {
-    console.log(eventObject.type, eventObject.data);
-    // logs event type, then { foo : 'bar' }
-  }
-);
+$('div').on('click', function(event) {
+  console.log('event object:');
+  console.dir(event);
+});
+```
+
+#### <a name="passing-data">Passing data to the event handler</a>
+
+You can pass your own data to the event object.
+
+```
+$('p').on('click', {foo: 'bar'}, function(event) {
+  console.log('event data: ' + event.data.foo + ' (should be "bar")');
+});
+```
+
+
+#### <a name="event-delegation">Binding events to elements that don't exist yet</a>
+
+This is called _event delegation_. Here's an example just for completeness, but see the 
+page on <a href="/events/event-delegation/">Event Delegation</a> for a full explanation.
+
+```
+$('ul').on('click', 'li', function() {
+  console.log('Something in a <ul> was clicked, and we detected that it was an <li> element.
+});
 ```
 
 ### Connecting Events to Run Only Once
 
 Sometimes you need a particular handler to run only once — after that, you may
 want no handler to run, or you may want a different handler to run.  jQuery
-provides the `$.fn.one` method for this purpose.
+provides the `.one()` method for this purpose.
 
 ```
-// Switching handlers using the `$.fn.one` method
+// Switching handlers using the `.one()` method
 $('p').one('click', function() {
   console.log('You just clicked this for the first time!');
   $(this).click(function() { console.log('You have clicked this before!'); });
 });
 ```
 
-The `$.fn.one` method is especially useful if you need to do some complicated
+The `.one()` method is especially useful if you need to do some complicated
 setup the first time an element is clicked, but not subsequent times.
 
+`.one()` accepts the same arguments as `on()` which means it supports multiple events to one
+or multiple handlers, passing custom data and event delegation.
+
 ### Disconnecting Events
 
-To disconnect an event handler, you use the `$.fn.unbind` method and pass in
-the event type to unbind.  If you attached a named function to the event, then
-you can isolate the unbinding to that named function by passing it as the
-second argument.
+Although all the fun of jQuery occurs in the `.on()` method, it's counterpart is just as important 
+if you want to be a responsible developer. `.off()` cleans up that event 
+binding when you don't need it anymore. Complex user interfaces with lots of event bindings 
+can bog down browser performance, so using the `.off()` method diligently is a best practice to 
+ensure that you only have the event bindings that you need, when you need them.
 
 ```
 // Unbinding all click handlers on a selection
-$('p').unbind('click');
+$('p').off('click');
 ```
 
 ```
 // Unbinding a particular click handler, using a reference to the function
 var foo = function() { console.log('foo'); };
 var bar = function() { console.log('bar'); };
 
-$('p').bind('click', foo).bind('click', bar);
-$('p').unbind('click', bar); // foo is still bound to the click event
+$('p').on('click', foo).bind('click', bar);
+$('p').off('click', bar); // foo is still bound to the click event
 ```
 
 ### Namespacing Events
 
 For complex applications and for plugins you share with others, it can be
 useful to namespace your events so you don't unintentionally disconnect events
-that you didn't or couldn't know about.
-
-```
-// Namespacing events
-$('p').bind('click.myNamespace', function() { /* ... */ });
-$('p').unbind('click.myNamespace');
-$('p').unbind('.myNamespace'); // unbind all events in the namespace
-```
-
-### Binding Multiple Events
-
-Quite often elements in your application will be bound to multiple events, each
-having a different function for handing the event.  In these cases you can pass
-an object into `$.fn.bind` with one or more key/value pairs, with the key being
-the event name and the value being the function to handle the event.
-
-```
-// Binding Multiple Events
-$('p').bind({
-  'click': function() { console.log('clicked!'); },
-  'mouseover': function() { console.log('hovered!'); }
-});
-```
+that you didn't or couldn't know about. For details, see Event Namespacing.
 
-<div class="note" markdown="1">
-The option to pass an object of multiple events and handlers to `$.fn.bind` was
-introduced in jQuery 1.4.4.
-</div>
+<!-- TODO: Link to namespacing -->