O'Reilly logo

jQuery Pocket Reference by David Flanagan

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Chapter 1. Introduction to jQuery

JavaScript has an intentionally simple core API and an overly complicated client-side API that is marred by major incompatibilities between browsers. The arrival of IE9 eliminates the worst of those incompatibilities, but many programmers find it easier to write web applications using a JavaScript framework or utility library to simplify common tasks and hide the differences between browsers. At the time of this writing, jQuery is one of the most popular and widely used of these libraries.

Because it has become so widely used, web developers should be familiar with the jQuery library: even if you don’t use it in your own code, you are likely to encounter it in code written by others. Fortunately, jQuery is stable and small enough to document in pocket reference form.

jQuery makes it easy to find the elements of a document, and then manipulate those elements by adding content, editing HTML attributes and CSS properties, defining event handlers, and performing animations. It also has Ajax utilities for dynamically making HTTP requests, and general-purpose utility functions for working with objects and arrays.

As its name implies, the jQuery library is focused on queries. A typical query uses a CSS selector to identify a set of document elements and then returns an object that represents those elements. This returned object provides many useful methods for operating on the matching elements as a group. Whenever possible, these methods return the object on which they are invoked, allowing a succinct method-chaining idiom to be used. These features are at the heart of jQuery’s power and utility:

  • An expressive syntax (CSS selectors) for referring to elements in the document

  • An efficient query method for finding the set of document elements that match a CSS selector

  • A useful set of methods for manipulating selected elements

  • Powerful functional programming techniques for operating on sets of elements as a group, rather than one at a time

  • A succinct idiom (method chaining) for expressing sequences of operations

This book begins with an introduction to jQuery that shows how to make simple queries and work with the results. The chapters that follow explain:

  • How to set HTML attributes; CSS styles and classes; HTML form values; and element content, geometry, and data

  • How to alter the structure of a document by inserting, replacing, wrapping, and deleting elements

  • How to use jQuery’s cross-browser event model

  • How to produce animated visual effects with jQuery

  • jQuery’s Ajax utilities for making scripted HTTP requests

  • jQuery’s utility functions

  • The full syntax of jQuery’s selectors, and how to use jQuery’s advanced selection methods

  • How to extend jQuery by using and writing plugins

  • The jQuery UI library

The end of this book is a quick reference to all of jQuery’s methods and functions.

jQuery Basics

The jQuery library defines a single global function named jQuery(). This function is so frequently used that the library also defines the global symbol $ as a shortcut for it. These are the only two symbols jQuery defines in the global namespace.[1]

This single global function with two names is the central query function for jQuery. Here, for example, is how we ask for the set of all <div> tags in a document:

var divs = $("div");

The value returned by this function represents a set of zero or more DOM elements and is known as a jQuery object. Note that jQuery() is a factory function rather than a constructor: it returns a newly created object, but it is not used with the new keyword. jQuery objects define many methods for operating on the sets of elements they represent, and most of this book is devoted to explaining those methods. Below, for example, is code that finds, highlights, and quickly displays all hidden <p> tags that have a class of “more”:

$("p.more").css("background-color", "gray").show("fast");

The css() method operates on the jQuery object returned by $(), and returns that same object so that the show() method can be invoked next in a compact “method chain”. This method-chaining idiom is common in jQuery programming. As another example, the code below finds all elements in the document that have the CSS class “hide”, and registers an event handler on each one. That event handler is invoked when the user clicks on the element, making it slowly “slide up” and disappear:

$(".hide").click(function() { $(this).slideUp("slow"); });

The jQuery() Function

The jQuery() function (a.k.a. $()) is the most important one in the jQuery library. It is heavily overloaded, however, and there are four different ways you can invoke it.

The first and most common way to invoke $() is to pass a CSS selector (a string) to it. When called this way, it returns the set of elements from the current document that match the selector. jQuery supports most of the CSS3 selector syntax, plus some extensions of its own. Complete details of the jQuery selector syntax are in jQuery Selectors. If you pass an element or a jQuery object as the second argument to $(), it returns only matching descendants of the specified element (or elements). This optional second argument value defines the starting point (or points) for the query and is often called the context.

The second way to invoke $() is to pass it an Element, Document, or Window object. Called like this, it simply wraps the element, document, or window in a jQuery object and returns that object, allowing you to use jQuery methods to manipulate the element rather than using raw DOM methods. It is common to see jQuery programs call $(document) or $(this), for example. jQuery objects can represent more than one element in a document, and you can also pass an array of elements to $(). In this case, the returned jQuery object represents the set of elements in your array.

The third way to invoke $() is to pass it a string of HTML text. When you do this, jQuery creates the HTML element (or elements) described by that text and then returns a jQuery object representing those elements. jQuery does not automatically insert the newly created elements into the document, but the jQuery methods described in Chapter 3 allow you to easily insert them where you want them. Note that you cannot pass plain text when you invoke $() in this way, or jQuery will think you are passing a CSS selector. For this style of invocation, the string you pass to $() must include at least one HTML tag with angle brackets.

When invoked in this third way, $() accepts an optional second argument. You can pass a Document object to specify the document with which the elements are to be associated. (If you are creating elements to be inserted into an <iframe>, for example, you’ll need to explicitly specify the document object of that frame.) Or, you can pass an object as the second argument. If you do this, the object properties are assumed to specify the names and values of HTML attributes to be set on the object. But, if the object includes properties with any of the names “css”, “html”, “text”, “width”, “height”, “offset”, “val” or “data”, or properties that have the same name as any of the jQuery event-handler registration methods, then jQuery will invoke the method of the same name on the newly created element and pass the property value to it. (Methods like css(), html() and text() are covered below in Chapter 2 and event handler registration methods are in Chapter 4. For example:

var img = $("<img/>",        // Create a new <img> tag
     { src:url,              // with this HTML attribute,
       css: {borderWidth:5}, // this CSS style,
       click: handleClick    // and this event handler.
     }); 

Finally, the fourth way to invoke $() is to pass a function to it. If you do this, the function you pass will be invoked when the document has been loaded and the DOM is ready to be manipulated. It is very common to see jQuery programs written as anonymous functions defined within a call to jQuery():

jQuery(function() { // Invoked when document has loaded
    // All jQuery code goes here
});

You’ll sometimes see $(f) written using the older and more verbose form: $(document).ready(f).

The function you pass to jQuery() will be invoked with the document object as its this value and with the jQuery function as its single argument. This means that you can undefine the global $ function and still use that convenient alias locally with this idiom:

jQuery.noConflict();  // Restore $ to its original state
jQuery(function($) {  
    // Use $ as a local alias for the jQuery object
    // Put all your jQuery code here
});

jQuery triggers functions registered through $() when the “DOMContentLoaded” event is fired, or, in browsers that don’t support that event, when the “load” event is fired. This means that the document will be completely parsed, but that external resources such as images may not be loaded yet. If you pass a function to $() after the DOM is ready, that function will be invoked immediately—before $() returns.

The jQuery library also uses the jQuery() function as its namespace, and defines a number of utility functions and properties under it. The jQuery.noConflict() function mentioned above is one such utility function. Others include jQuery.each() for general-purpose iteration and jQuery.parseJSON() for parsing JSON text. Chapter 7 lists general-purpose utility functions, and other jQuery functions are described throughout this book.

Queries and Query Results

When you pass a jQuery selector string to $(), it returns a jQuery object that represents the set of matched (or “selected”) elements. jQuery selectors are very much like the CSS selectors you use in stylesheets. For example:

div            // all <div> elements
#surname       // the element with id="surname"
.warning       // all elements with class="warning"

The specific selector syntax supported by jQuery is detailed in jQuery Selectors. Rather than focus on those advanced selector details now, we’re going to first explore what you can do with the results of a query.

The value returned by $() is a jQuery object. jQuery objects are array-like: they have a length property and numeric properties from 0 to length-1. This means that you can access the contents of the jQuery object using standard square-bracket array notation:

$("body").length  // => 1: documents have only one body
$("body")[0]      // This the same as document.body

If you prefer not to use array notation with jQuery objects, you can use the size() method instead of the length property, and the get() method instead of indexing with square brackets. If you need to convert a jQuery object to a true array, call the toArray() method.

In addition to the length property, jQuery objects have three other properties that are sometimes of interest. The selector property is the selector string (if any) that was used when the jQuery object was created. The context property is the context object that was passed as the second argument to $(), or the Document object otherwise. Finally, all jQuery objects have a property named jquery, and testing for the existence of this property is a simple way to distinguish jQuery objects from other array-like objects. The value of the jquery property is the jQuery version number as a string:

// Find all <script> elements in the document body
var bodyscripts = $("script", document.body);
bodyscripts.selector   // => "script"
bodyscripts.context    // => document.body
bodyscripts.jquery     // => "1.4.2"

If you want to loop over all elements in a jQuery object, call the each() method instead of writing a for loop. The each() method is something like the ECMAScript 5 (ES5) forEach() array method. It expects a callback function as its sole argument, and invokes that callback function once for each element in the jQuery object (in document order). The callback is invoked as a method of the matched element, so within the callback the this keyword refers to an Element object. each() also passes the index and the element as the first and second arguments to the callback. Note that this and the second argument are raw document elements, not jQuery objects; if you want to use a jQuery method to manipulate the element, you’ll need to pass it to $() first.

jQuery’s each() method has one feature that is quite different than forEach(): if your callback returns false for any element, iteration is terminated after that element (this is like using the break keyword in a normal loop). each() returns the jQuery object on which it is called so that it can be used in method chains. Here is an example (it uses the prepend() method that will be explained in Chapter 3):

// Number the divs of the document, up to div#last
$("div").each(function(idx) { // Invoke for each <div>
    // Create a jQuery object from the element
    // And insert the index at start of it.
    $(this).prepend(idx + ": ");  
    // Stop iterating when we reach #last
    if (this.id === "last") 
        return false;
});

Despite the power of the each() method, it is not very commonly used since jQuery methods usually iterate implicitly over the set of matched elements and operate on them all. You typically only need to use each() if you need to manipulate the matched elements in different ways. Even then, you may not need to call each() since a number of jQuery methods allow you to pass a callback function.

The jQuery library predates the ES5 array methods and defines a couple of other methods that provide similar functionality. The jQuery method map() works much like the Array.map() method. It accepts a callback function as its argument and invokes that function once for each element of the jQuery object, collecting the return values of those invocations, and returning a new jQuery object holding those return values. map() invokes the callback in the same way as the each() method: the element is passed as the this value and as the second argument, and the index of the element is passed as the first argument. If the callback returns null or undefined, that value is ignored and nothing is added to the new jQuery object for that invocation. If the callback returns an array or an array-like object (such as a jQuery object), it is “flattened” and its elements are added individually to the new jQuery object. Note that the jQuery object returned by map() may not hold document elements, but it still works as an array-like object. Here is an example:

$(":header")                // Find all headings.
    .map(function() {       // Map them to
            return this.id; // their ids.
         })
    .toArray()              // Convert to a true array
    .sort();                // And sort that array

Along with each() and map(), another fundamental jQuery method is index(). This method expects an element as its argument, and it returns the index of that element in the jQuery object, or -1 if it is not found. In typical jQuery fashion, however, this index() method is overloaded. If you pass a jQuery object as the argument, index() searches for the first element of that object. If you pass a string, index() uses it as a CSS selector and returns the index of the first element of this jQuery object in the set of elements matching that selector. And if you pass no argument, index() returns the index of the first element within its sibling elements.

The final general-purpose jQuery method we’ll discuss here is is(). It takes a selector as its argument and returns true if at least one of the selected elements also matches the specified selector. You might use it in an each() callback function, for example:

$("div").each(function() {     // For each <div> element
    if ($(this).is(":hidden")) // Skip hidden elements
        return;
    // Do something with the visible ones here
});


[1] If you use $ in your own code, or are using another library—such as Prototype—that uses $, you can call jQuery.noConflict() to restore $ to its original value.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required