Leveraging jQuery's Special Events API (JSConf 2012)

Editor's Notes

1. Hello! My name is James “Gunslinger” Greene and I’m going to be talking to you today about leveraging jQuery’s Special Events API to extend the event system with your own custom events.Oh, hey, quick side note: did you guys already hear the secret password for getting into the Red Revolver Lounge tonight?
2. Just kidding! There is no secret password — at least not that anyone told me about. 
3. So, let’s talk about the problem that led me to stumble upon jQuery’s Special Events API.
4. What I wanted was a way for both myself and other JavaScript consumers to bind to synthetic events that don’t have to manually trigger. In particular, I was seeking an event that would fire on text selection. Alas, my initial searches yielded unfortunate results: even modern browsers don’t seem to support such an event.†  †More on this later. So, we have some alternative options....
5. First, we could attach to the relevant corresponding DOM event (mouseup, in this case) with a callback that manually triggers a synthetic “textSelect” event when appropriate. This is bit cheesy, plus I really don’t want to have to hook up an event like this each time.
6. Perhaps better: I could wrap this same basic code up as a simple jQuery plugin. However, I still think this ugly AND I was given recent direction from the jQuery Foundation discouraging jQuery plugin functions for event-related shortcuts.
7. Let’s dive in and take a closer look at jQuery’s Special Events API.
8. jQuery 1.3 introduced a rudimentary form of the Special Events API.jQuery 1.7 introduced a major overhaul to the long-neglected Special Events API. This revamped API is the true basis of my talk today.An important disclaimer, though: this API is still under review and therefore still subject to change. Proceed with caution!
9. So what doesjQuery’s Special Events API do?The Special Events API has two main responsibilities: 1. Allow hooks for “fixing” events. This is primarily to standardize event behavior across browsers. 2. Allow for the creation of custom events defined by the browsers. This includes the ultra-famous “ready” event that we all know and love, as well as “mouseenter” and “mouseleave”… but it doesn’t have to stop there! This also allows developers to create their own custom bindable events that snap right into the jQuery Event System for a smooth, integrated feeling. This is where the rest of the talk will focus.
10. The API for custom events has a number of properties and methods that can be set. In practice, however, most of them are optional or must be used in combinations. A quick rundown of each: - noBubble: Indicates whether or not this event type should be bubbled when the .trigger() method is called; defaults to false, which enables bubbling. - bindType and delegateType: Specify that a special event should be handled like another event type until the event is delivered; bindType if attached directly, delegateType for delegated events. - handle: The handle hook is basically a pre-condition checker. If the handle hook exists, jQuery calls it INSTEAD OF the attached event handler, passing it the event and any data passed from .trigger() if it was not a native event. Based in the information it has, the handle hook should decide whether to call the original handler function.
11. The API for custom events has a number of properties and methods that can be set. In practice, however, most of them are optional or must be used in combinations. A quick rundown of each: - noBubble: Same as on the previous slide! - setup: Called the first time an event of a particular type is attached to an element. - teardown: Called when the final event of a particular type is removed from an element. - add: Called each time an event handler is added to an element. - remove: Called each time an event handler is removed from an element. - trigger: Called when the .trigger() or .triggerHandler() methods are used to trigger an event for the special type from code, as opposed to events that originate from within the browser. - _default: When the .trigger() method finishes running all the event handlers for an event, it also looks for and runs any method on the target object by the same name unless at least one of the handlers called event.preventDefault(). The _default hook is called just prior to checking for and executing the element's default method; sort of a last-chance event handler for jQuery.
12. Alright, so enough background: let’s see what this API can do. Demo time!
13. Note: This demo will show off Syntax #1.
14. Note: This demo will show off Syntax #2.
15. Whoops! As you can see,I didn’t have time to create the basic “swipe” demo that I had planned… but that’s OK. Another comment on that later.
16. Alright, so I think this is a pretty handy API for allowing us to abstract creative custom events that we consider to be missing. But, I also want to share with you a few other things I learned in the process.
17. Surprise! IE turns out to be the dark horse innovators for JavaScript once again, introducing an updated version of the “select” event that kind of supports this behavior. The issue with it? The deepest element reference you can get to it is the body element. Sadness.
18. When I decided to start updating my “textSelect” event for mobile, I decided to look at jQuery Mobile’s source code to find out what test they do to detect support for touch events. In doing so, I found another missing link: jQuery Mobile is loaded with usage of the Special Events API. They use it to abstract out the many custom event types you see on this slide. Should’ve drawn this connection earlier, but all the same, it was nice to discover that the API receives more usage than I originally thought.
19. Thanks for coming to my talk! Are there any questions?