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 hadler function to multiple events, and is also used when you want to provide data to the event hander, or when you are working with custom events.
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.
The $.fn.one
method is especially useful if you need to do some complicated setup the first time an element is clicked, but not subsequent times.
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.
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.
As mentioned in the overview, the event handling function receives an event object, which contains many properties and methods. The event object is most commonly used to prevent the default action of the event via the preventDefault method. However, the event object contains a number of other useful properties and methods, including:
pageX, pageY
-
The mouse position at the time the event occurred, relative to the top left of the page.
type
-
The type of the event (e.g. "click").
which
-
The button or key that was pressed.
data
-
Any data that was passed in when the event was bound.
target
-
The DOM element that initiated the event.
preventDefault()
-
Prevent the default action of the event (e.g. following a link).
stopPropagation()
-
Stop the event from bubbling up to other elements.
In addition to the event object, the event handling function also has access to the DOM element that the handler was bound to via the keyword this
. To turn the DOM element into a jQuery object that we can use jQuery methods on, we simply do $(this)
, often following this idiom:
var $this = $(this);
Example 5.8. Preventing a link from being followed
$('a').click(function(e) {
var $this = $(this);
if ($this.attr('href').match('evil')) {
e.preventDefault();
$this.addClass('evil');
}
});
As mentioned in the overview, the event handling function receives an event object, which contains many properties and methods. The event object is most commonly used to prevent the default action of the event via the preventDefault method. However, the event object contains a number of other useful properties and methods, including:
-
pageX, pageY
-
The mouse position at the time the event occurred, relative to the top left of the page.
type
-
The type of the event (e.g. "click").
which
-
The button or key that was pressed.
data
-
Any data that was passed in when the event was bound.
target
-
The DOM element that initiated the event.
preventDefault()
-
Prevent the default action of the event (e.g. following a link).
stopPropagation()
-
Stop the event from bubbling up to other elements.
In addition to the event object, the event handling function also has access to the DOM element that the handler was bound to via the keyword this
. To turn the DOM element into a jQuery object that we can use jQuery methods on, we simply do $(this)
, often following this idiom:
var $this = $(this);
Example 5.8. Preventing a link from being followed
$('a').click(function(e) { var $this = $(this); if ($this.attr('href').match('evil')) { e.preventDefault(); $this.addClass('evil'); } });
jQuery provides a way to trigger the event handlers bound to an element without any user interaction via the $.fn.trigger
method. While this method has its uses, it should not be used simply to call a function that was bound as a click handler. Instead, you should store the function you want to call in a variable, and pass the variable name when you do your binding. Then, you can call the function itself whenever you want, without the need for $.fn.trigger
.
You'll frequently use jQuery to add new elements to the page, and when you do, you may need to bind events to those new elements -- events you already bound to similar elements that were on the page originally. Instead of repeating your event binding every time you add elements to the page, you can use event delegation. With event delegation, you bind your event to a container element, and then when the event occurs, you look to see which contained element it occurred on. If this sounds complicated, luckily jQuery makes it easy with its $.fn.live
and $.fn.delegate
methods.
While most people discover event delegation while dealing with elements added to the page later, it has some performance benefits even if you never add more elements to the page. The time required to bind event handlers to hundreds of individual elements is non-trivial; if you have a large set of elements, you should consider delegating related events to a container element.
Note
The $.fn.live
method was introduced in jQuery 1.3, and at that time only certain event types were supported. As of jQuery 1.4.2, the $.fn.delegate
method is available, and is the preferred method.
If you need to remove delegated events, you can't simply unbind them. Instead, use$.fn.undelegate
for events connected with $.fn.delegate
, and $.fn.die
for events connected with $.fn.live
. As with bind, you can optionally pass in the name of the bound function.
jQuery offers two event-related helper functions that save you a few keystrokes.
The $.fn.hover
method lets you pass one or two functions to be run when the mouseenter
andmouseleave
events occur on an element. If you pass one function, it will be run for both events; if you pass two functions, the first will run for mouseenter
, and the second will run for mouseleave
.
Note
Prior to jQuery 1.4, the $.fn.hover
method required two functions.
Much like $.fn.hover
, the $.fn.toggle
method receives two or more functions; each time the event occurs, the next function in the list is called. Generally, $.fn.toggle
is used with just two functions, but technically you can use as many as you'd like.