Building Custom jQuery Event Types: Hesitate Event

If you've worked with jQuery for a while, you've probably bound event handlers to DOM elements. And, if you've done that, you may have also bound and triggered handlers to event types that aren't natively supported by the browser (ex. "drag", "drop"). This kind of seamless event management is, without a doubt, a huge part of what makes jQuery so powerful; but event binding is only part of it. In the jQuery Cookbook, Ariel Flesler explains that beyond binding to custom events, you can actually create custom events that will be triggered implicitly by the jQuery library.

I have seen this a few times before, but was never really able to wrap my head around it. With Ariel's tutorial in hand, however, I felt determined to try and play with this concept myself. As an experiment, I wanted to see if I could create a "hesitate" event type. The idea behind "hesitate" is that it would fire if the user moused over a given element and then remained over the element - without clicking - for a certain duration. The idea being that they intend to click the element, but they are hesitating to act upon that intent.

Before we get into the internals of the custom event type creation, let's take a look at the code that uses it. In the following demo, I am going to bind to the "hesitate" event on some image thumbnail links. If the user hesitates to click a thumbnail, I am going to increase the size of that thumbnail in an attempt to entice them to click it. As you will see below, the calling code can bind to our custom event type, "hesitate", just as it could to any other event type, native or otherwise.

The first thing I am doing here is overriding the "duration" of the "hesitate" event type. This is the amount of time the user will have to be non-active over the target element before the "hesitate" event is fired. In my example, this is done across the board (as a generic event type) and not on a per-binding basis (which could also be done). Then, just as I would with any event type, I bind my event handlers to "hesitate" event on the target links.

If I mouse over one of the links, but do not commit to the click, the nested image will animate to a larger size and look like this:

What you'll notice above is that my demo code does not define the logic of the "hesitate" event type or how it gets triggered; it simply binds to the event type on the target elements. The logic and the mechanics of the event are all handled by jQuery and my custom event type setup, which is defined by the included Javascript file, jquery.event.hestiate.js. Now that you see how the event type is getting used, let's take a look at how the event type is defined:

jquery.event.hesitate.js

This is my first time trying this, so I am 100% how it all wires together. But, from what I understand, all custom jQuery events are defined as named-structures off of:

jQuery.event.special

This event definition object should contain, at the very least, two core methods, setup() and teardown(). The setup() method is a sort of event constructor that gets called exactly once for each element the first time the custom event is bound to it. The teardown() method is a sort of event destructor that gets called exactly once for each element when the custom event is unbound from it.

What you do in these methods is up to you; but, because we are building completely custom events, we need to build on top of events that are natively supported by the browser (or at least other events that might be triggered in some way). As such, from within our setup() method, we need to bind event handlers to the core events that will power our custom event. In this case, for the "hesitate" event, there are three crucial event types to monitor:

• MouseEnter. When the user mouses into the target element, we have to start keeping track of their subsequent hesitation to click.
• MouseLeave. When the user mouses out of the target element, we no longer need to keep track of their activity.
• Click. When the user clicks on the target element, they can no longer be considered inactive or hesitating.

Once we bind to these core methods, we can then go about using them to create our custom event. In our particular case, when the user enters the target area, we create a timer that waits for inactivity. If the user clicks on the target element, or mouses out of it, we kill the inactivity timer. If the user does neither of these two things, the timer will execute and its callback will trigger the "hesitate" event on the target element. At this point, any subsequent handlers bound to this target element for the "hesitate" event will be executed.

While this works well, it should be noted that the core events (upon which are custom event is powered) are not shielded in any way. Meaning, if someone were to trigger a "click" event on our target element, it would certainly trigger the "click" handler that we are using to power the "hesitate" event.

As this is the first time that I have created a custom jQuery event type, I am sure that I am leaving juicy pieces of information out of my explanation. For instance, I have not talked about namespaces, additional event data, or per-binding custom settings; hopefully I can address such things in a future post.

What Other People Are Searching For

[ local search ] creating custom events in jquery
[ local search ] creating custom event types in jquery
[ local search ] how do i create custom events in jquery
[ local search ] how do i create custom event types in jquery

You Might Also Be Interested In: