jQuery Events: Browser/Document Events
This page discusses events related to browser and HTML document. jQuery supports several events that support the same. While we can use .on() method to add various types of events, jQuery also provides shorthand methods to do the same. Let us begin with a table that lists these shorthand events along with a short description.
| Event | Shortcut Method | Event Description |
|---|---|---|
| ready | .ready() | when the browser-window's DOM is ready |
| scroll | .scroll() | when we scroll the browser window. |
| resize | .resize() | when we resize the browser window. |
The first method in the above table is for documents and is the .ready() method -- it is a popular method and it is likely that you would have seen it earlier. This event is triggered when the HTML DOM of the page becomes ready (or gets loaded). This event is actually one of the first events that gets triggered when we load a page. It is after this event that the page content is loaded. But since the basic HTML DOM is ready, it is usually the right time to start running the jQuery code without having to wait any further.
The next element in the above table, scroll event is triggered when a user scrolls a browser page or elements that support scrolling like frames and CSS elements with overflow property set to scroll. In addition, the user can scroll the page either using the mouse or using the Page-Up or Page-Down keys.
The last element in the above table is the resize event and is triggered when a user resizes the browser window.
Out of these events, none of the events are cancellable. This means that even if the handlers were to return false, no cancellation would occur. This is fairly easy to explain since for most of the cases, we gain little by making these browser-events cancellable. For example, if a user resizes the window, then canceling it would mean that we change the size of the window back to its original size. This would very likely end up annoying the user!
In terms of being able to bubble, all of the above events do bubble.
So, let us provide signature of these three methods right away.
.ready(eventHandlerFunction); [Added in 1.0] .scroll(eventHandlerFunction(eventObject)); [Added in 1.0] .scroll(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .scroll(); [Added in 1.0] .resize(eventHandlerFunction(eventObject)); [Added in 1.0] .resize(optionalData, eventHandlerFunction(eventObject)); [Added in 1.4.3] .resize(); [Added in 1.0]
For both .scroll() and .resize(), the first variant accepts a callback handler function. For both of them, the second variant also accepts data that gets passed to the event handler. Lastly, for both of them, the third variant generates them as an event -- this way, these variants resemble the .trigger() method.
Next, we provide a simple example that attaches event handlers to various window-events. All of the events are tucked under the document ready event such that registering events happen only when the page is ready. The event handlers merely print a message on the page once the event is fired. Here is the example:
<!doctype html>
<html>
<head> <h2> A Trivial Page </h2></head>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js">
</script>
<body>
<script type="text/javascript">
// Attach an event-handler when the document is ready.
$(document).ready(function() {
$("body").append("Document is ready!<br>");
// Attach an event-handler when someone scrolls the window.
$(window).scroll(function() {
$("body").append("Scrolling the window<br>");
});
// Attach an event-handler when someone resizes the window.
$(window).resize(function() {
$("body").append("Resizing the window<br>");
});
});
</script>
</body>
</html>
Let us load this page (assuming that the file-name is "window_events.html"). When we resize and scroll the window (we do that several times!), we would see the output provided below.
Figure: Window Events
Deprecated Events
For the sake of completeness, we mention the document related events that are now deprecated in the following table. We also list the jQuery version that deprecated these methods.
| Event | Shortcut Method | Event Description | Version Deprecated |
|---|---|---|---|
| load | .load() | when all content of the window (or an element) is loaded | 1.8 |
| unload | .unload() | when all content of the window (or an element) is removed | 1.8 |
| error | .error() | when an error occurs during loading of window or an element | 1.8 |
For all of the above deprecated methods, we can now use the .on() method. For .load() method, the recommended method is to use .on( "load", eventHandlerFunction). For .unload() method, the recommended method is to use .on( "unload", eventHandlerFunction). For .error() method, the recommended method is to use .on( "error", eventHandlerFunction).