jQuery Documentation


With contributions by James Padolsey, Paul Irish, and others.
See the GitHub repository for a complete history of

Licensed by Rebecca Murphey under the Creative
Commons Attribution-Share Alike 3.0 United States license
. You
are free to copy, distribute, transmit, and remix this work, provided
you attribute the work to Rebecca Murphey as the original author and
reference the GitHub
repository for the work
. If you alter, transform, or build upon
this work, you may distribute the resulting work only under the same,
similar or a compatible license. Any of the above conditions can be
waived if you get permission from the copyright holder. For any reuse or
distribution, you must make clear to others the license terms of this
work. The best way to do this is with a link to
the license

Table of Contents

1. Welcome
Getting the Code
Adding JavaScript to Your Page
JavaScript Debugging
Conventions used in this book
Reference Material
I. JavaScript 101
2. JavaScript Basics
Syntax Basics
Basic Operators
Operations on Numbers & Strings
Logical Operators
Comparison Operators
Conditional Code
Truthy and Falsy Things
Conditional Variable Assignment with The Ternary Operator
Switch Statements
The for loop
The while loop
The do-while loop
Breaking and continuing
Reserved Words
Using Functions
Self-Executing Anonymous Functions
Functions as Arguments
Testing Type
II. jQuery: Basic Concepts
3. jQuery Basics
Selecting Elements
Does My Selection Contain Any Elements?
Saving Selections
Refining & Filtering Selections
Selecting Form Elements
Working with Selections
Getters & Setters
CSS, Styling, & Dimensions
Using CSS Classes for Styling
Manipulating Elements
Getting and Setting Information about Elements
Moving, Copying, and Removing Elements
Creating New Elements
Manipulating Attributes
4. jQuery Core
$ vs $()
Utility Methods
Checking types
Data Methods
Feature & Browser Detection
Avoiding Conflicts with Other Libraries
5. Events
Connecting Events to Elements
Connecting Events to Run Only Once
Disconnecting Events
Namespacing Events
Inside the Event Handling Function
Triggering Event Handlers
Increasing Performance with Event Delegation
Unbinding Delegated Events
Event Helpers
Create an Input Hint
Add Tabbed Navigation
6. Effects
Built-in Effects
Changing the Duration of Built-in Effects
Doing Something when an Effect is Done
Custom Effects with $.fn.animate
Managing Effects
Reveal Hidden Text
Create Dropdown Menus
Create a Slideshow
7. Ajax
Key Concepts
GET vs. Post
Data Types
A is for Asynchronous
Same-Origin Policy and JSONP
Ajax and Firebug
jQuery’s Ajax-Related Methods
Convenience Methods
Ajax and Forms
Working with JSONP
Ajax Events
Load External Content
Load Content Using JSON
8. Plugins
What exactly is a plugin?
How to create a basic plugin
Finding & Evaluating Plugins
Writing Plugins
Writing Stateful Plugins with the jQuery UI Widget Factory
Adding Methods to a Widget
Working with Widget Options
Adding Callbacks
Cleaning Up
Make a Table Sortable
Write a Table-Striping Plugin
III. Advanced Topics
This Section is a Work in Progress
9. Performance Best Practices
Cache length during loops
Append new content outside of a loop
Keep things DRY
Beware anonymous functions
Optimize Selectors
ID-Based Selectors
Avoid the Universal Selector
Use Event Delegation
Detach Elements to Work With Them
Use Stylesheets for Changing CSS on Many Elements
Use $.data Instead of $.fn.data
Don’t Act on Absent Elements
Variable Definition
Don’t Treat jQuery as a Black Box
10. Code Organization
Key Concepts
The Object Literal
The Module Pattern
Managing Dependencies
Getting RequireJS
Using RequireJS with jQuery
Creating Reusable Modules with RequireJS
Optimizing Your Code: The RequireJS Build Tool
Create a Portlet Module
11. Custom Events
Introducing Custom Events
A Sample Application

List of Examples

1.1. An example of inline Javascript
1.2. An example of including external JavaScript
1.3. Example of an example
2.1. A simple variable declaration
2.2. Whitespace has no meaning outside of quotation marks
2.3. Parentheses indicate precedence
2.4. Tabs enhance readability, but have no special meaning
2.5. Concatenation
2.6. Multiplication and division
2.7. Incrementing and decrementing
2.8. Addition vs. concatenation
2.9. Forcing a string to act as a number
2.10. Forcing a string to act as a number (using the unary-plus
2.11. Logical AND and OR operators
2.12. Comparison operators
2.13. Flow control
2.14. Values that evaluate to true
2.15. Values that evaluate to false
2.16. The ternary operator
2.17. A switch statement
2.18. Loops
2.19. A typical for loop
2.20. A typical while loop
2.21. A while loop with a combined conditional and
2.22. A do-while loop
2.23. Stopping a loop
2.24. Skipping to the next iteration of a loop
2.25. A simple array
2.26. Accessing array items by index
2.27. Testing the size of an array
2.28. Changing the value of an array item
2.29. Adding elements to an array
2.30. Working with arrays
2.31. Creating an “object literal”
2.32. Function Declaration
2.33. Named Function Expression
2.34. A simple function
2.35. A function that returns a value
2.36. A function that returns another function
2.37. A self-executing anonymous function
2.38. Passing an anonymous function as an argument
2.39. Passing a named function as an argument
2.40. Testing the type of various variables
2.41. Functions have access to variables defined in the same
2.42. Code outside the scope in which a variable was defined does not
have access to the variable
2.43. Variables with the same name can exist in different scopes with
different values
2.44. Functions can “see” changes in variable values after the function
is defined
2.45. Scope insanity
2.46. How to lock in the value of i?
2.47. Locking in the value of i with a closure
3.1. A $(document).ready() block
3.2. Shorthand for $(document).ready()
3.3. Passing a named function instead of an anonymous function
3.4. Selecting elements by ID
3.5. Selecting elements by class name
3.6. Selecting elements by attribute
3.7. Selecting elements by compound CSS selector
3.8. Pseudo-selectors
3.9. Testing whether a selection contains elements
3.10. Storing selections in a variable
3.11. Refining selections
3.12. Using form-related pseduo-selectors
3.13. Chaining
3.14. Formatting chained code
3.15. Restoring your original selection using
3.16. The $.fn.html method used as a setter
3.17. The html method used as a getter
3.18. Getting CSS properties
3.19. Setting CSS properties
3.20. Working with classes
3.21. Basic dimensions methods
3.22. Setting attributes
3.23. Getting attributes
3.24. Moving around the DOM using traversal methods
3.25. Iterating over a selection
3.26. Changing the HTML of an element
3.27. Moving elements using different approaches
3.28. Making a copy of an element
3.29. Creating new elements
3.30. Creating a new element with an attribute object
3.31. Getting a new element on to the page
3.32. Creating and adding an element to the page at the same
3.33. Manipulating a single attribute
3.34. Manipulating multiple attributes
3.35. Using a function to determine an attribute’s new value
4.1. Checking the type of an arbitrary value
4.2. Storing and retrieving data related to an element
4.3. Storing a relationship between elements using
4.4. Putting jQuery into no-conflict mode
4.5. Using the $ inside a self-executing anonymous function
5.1. Event binding using a convenience method
5.2. Event biding using the $.fn.bind method
5.3. Event binding using the $.fn.bind method with
5.4. Switching handlers using the $.fn.one
5.5. Unbinding all click handlers on a selection
5.6. Unbinding a particular click handler
5.7. Namespacing events
5.8. Preventing a link from being followed
5.9. Triggering an event handler the right way
5.10. Event delegation using $.fn.delegate
5.11. Event delegation using $.fn.live
5.12. Unbinding delegated events
5.13. The hover helper function
5.14. The toggle helper function
6.1. A basic use of a built-in effect
6.2. Setting the duration of an effect
6.3. Augmenting jQuery.fx.speeds with custom speed
6.4. Running code when an animation is complete
6.5. Run a callback even if there were no elements to
6.6. Custom effects with $.fn.animate
6.7. Per-property easing
7.1. Using the core $.ajax method
7.2. Using jQuery’s Ajax convenience methods
7.3. Using $.fn.load to populate an element
7.4. Using $.fn.load to populate an element based on a
7.5. Turning form data into a query string
7.6. Creating an array of objects containing form data
7.7. Using YQL and JSONP
7.8. Setting up a loading indicator using Ajax Events
8.1. Creating a plugin to add and remove a class on hover
8.2. The Mike Alsup jQuery Plugin Development Pattern
8.3. A simple, stateful plugin using the jQuery UI widget
8.4. Passing options to a widget
8.5. Setting default options for a widget
8.6. Creating widget methods
8.7. Calling methods on a plugin instance
8.8. Responding when an option is set
8.9. Providing callbacks for user extension
8.10. Binding to widget events
8.11. Adding a destroy method to a widget
10.1. An object literal
10.2. Using an object literal for a jQuery feature
10.3. The module pattern
10.4. Using the module pattern for a jQuery feature
10.5. Using RequireJS: A simple example
10.6. A simple JavaScript file with dependencies
10.7. Defining a RequireJS module that has no dependencies
10.8. Defining a RequireJS module with dependencies
10.9. Defining a RequireJS module that returns a function
10.10. A RequireJS build configuration file

jQuery is fast becoming a must-have skill for front-end developers.
The purpose of this book is to provide an overview of the jQuery JavaScript
library; when you’re done with the book, you should be able to complete
basic tasks using jQuery, and have a solid basis from which to continue your
learning. This book was designed as material to be used in a classroom
setting, but you may find it useful for individual study.

This is a hands-on class. We will spend a bit of time covering a
concept, and then you’ll have the chance to work on an exercise related to
the concept. Some of the exercises may seem trivial; others may be downright
daunting. In either case, there is no grade; the goal is simply to get you
comfortable working your way through problems you’ll commonly be called upon
to solve using jQuery. Example solutions to all of the exercises are
included in the sample code.

The code we’ll be using in this book is hosted in a repository on
. You can download a .zip or .tar file of the code, then
uncompress it to use it on your server. If you’re git-inclined, you’re
welcome to clone or fork the repository.

Logical operators allow you to evaluate a series of operands using
AND and OR operations.

Though it may not be clear from the example, the ||
operator returns the value of the first truthy operand, or, in cases
where neither operand is truthy, it’ll return the last of both operands.
The && operator returns the value of the first
false operand, or the value of the last operand if both operands are

Be sure to consult the section called “Truthy and Falsy Things” for more details on
which values evaluate to true and which evaluate to


You’ll sometimes see developers use these logical operators for
flow control instead of using if statements. For

// do something with foo if foo is truthy
foo && doSomething(foo);

// set bar to baz if baz is truthy;
// otherwise, set it to the return
// value of createBar()
var bar = baz || createBar();

This style is quite elegant and pleasantly terse; that said, it
can be really hard to read, especially for beginners. I bring it up
here so you’ll recognize it in code you read, but I don’t recommend
using it until you’re extremely comfortable with what it means and how
you can expect it to behave.

Sometimes you only want to run a block of code under certain
conditions. Flow control — via if and else
blocks — lets you run code only under certain conditions.

Be mindful not to define functions with the same name multiple times
within separate if/else blocks, as doing so may
not have the expected result.

Loops let you run a block of code a certain number of times.

Note that in
Example 2.18, “Loops” even though we use the
keyword var before the variable name i,
this does not “scope” the variable i to the loop block.
We’ll discuss scope in depth later in this chapter.

Functions contain blocks of code that need to be executed
repeatedly. Functions can take zero or more arguments, and can optionally
return a value.

Functions can be created in a variety of ways:

I prefer the named function expression method of setting a
function’s name, for some rather
and technical reasons
. You are likely to see both methods used in
others’ JavaScript code.

“Scope” refers to the variables that are available to a piece of
code at a given time. A lack of understanding of scope can lead to
frustrating debugging experiences.

When a variable is declared inside of a function using the
var keyword, it is only available to code inside of that
function — code outside of that function cannot access the variable. On
the other hand, functions defined inside that
function will have access to to the declared

Furthermore, variables that are declared inside a function without
the var keyword are not local to the function — JavaScript
will traverse the scope chain all the way up to the window scope to find
where the variable was previously defined. If the variable wasn’t
previously defined, it will be defined in the global scope, which can have
extremely unexpected consequences;

The most basic concept of jQuery is to “select some elements and do
something with them.” jQuery supports most CSS3 selectors, as well as some
non-standard selectors. For a complete selector reference, visit

Following are a few examples of common selection techniques.


When you use the :visible and :hidden
pseudo-selectors, jQuery tests the actual visibility of the element, not
its CSS visibility or display — that is, it looks to see if the
element’s physical height and width on the page are
both greater than zero. However, this test doesn’t work with
<tr> elements; in this case, jQuery does check the
CSS display property, and considers an element hidden if
its display property is set to none. Elements
that have not been added to the DOM will always be considered hidden,
even if the CSS that would affect them would render them visible. (See
the Manipulation section later in this chapter to learn how to create
and add elements to the DOM.)

For reference, here is the code jQuery uses to determine whether
an element is visible or hidden, with comments added for clarity:

jQuery.expr.filters.hidden = function( elem ) {
    var width = elem.offsetWidth, height = elem.offsetHeight,
        skip = elem.nodeName.toLowerCase() === "tr";

    // does the element have 0 height, 0 width,
    // and it's not a <tr>?
    return width === 0 && height === 0 && !skip ?

        // then it must be hidden
        true :

        // but if it has width and height
        // and it's not a <tr>
        width > 0 && height > 0 && !skip ?

            // then it must be visible
            false :

            // if we get here, the element has width
            // and height, but it's also a <tr>,
            // so check its display property to
            // decide whether it's hidden
            jQuery.curCSS(elem, "display") === "none";

jQuery.expr.filters.visible = function( elem ) {
    return !jQuery.expr.filters.hidden( elem );

Every time you make a selection, a lot of code runs, and jQuery
doesn’t do caching of selections for you. If you’ve made a selection
that you might need to make again, you should save the selection in a
variable rather than making the selection repeatedly.


In Example 3.10, “Storing selections in a variable”,
the variable name begins with a dollar sign. Unlike in other
languages, there’s nothing special about the dollar sign in JavaScript
– it’s just another character. We use it here to indicate that the
variable contains a jQuery object. This practice — a sort of Hungarian
— is merely convention, and is not mandatory.

Once you’ve stored your selection, you can call jQuery methods on
the variable you stored it in just like you would have called them on
the original selection.


A selection only fetches the elements that are on the page when
you make the selection. If you add elements to the page later, you’ll
have to repeat the selection or otherwise add them to the selection
stored in the variable. Stored selections don’t magically update when
the DOM changes.

Once you have a selection, you can call methods on the selection.
Methods generally come in two different flavors: getters and setters.
Getters return a property of the first selected element; setters set a
property on all selected elements.

jQuery includes a handy way to get and set CSS properties of

Note the style of the argument we use on the second line — it is
an object that contains multiple properties. This is a common way to pass
multiple arguments to a function, and many jQuery setter methods accept
objects to set mulitple values at once.

Once you’ve made a selection, the fun begins. You can change, move,
remove, and clone elements. You can also create new elements via a simple

For complete documentation of jQuery manipulation methods, visit

There are any number of ways you can change an existing element.
Among the most common tasks you’ll perform is changing the inner HTML or
attribute of an element. jQuery offers simple, cross-browser methods for
these sorts of manipulations. You can also get information about
elements using many of the same methods in their getter incarnations.
We’ll see examples of these throughout this section, but specifically,
here are a few methods you can use to get and set information about

There are a variety of ways to move elements around the DOM;
generally, there are two approaches:

For example, jQuery provides $.fn.insertAfter and
$.fn.after. The $.fn.insertAfter method places
the selected element(s) after the element that you provide as an
argument; the $.fn.after method places the element provided
as an argument after the selected element. Several other methods follow
this pattern: $.fn.insertBefore and
$.fn.before; $.fn.appendTo and
$.fn.append; and $.fn.prependTo and

The method that makes the most sense for you will depend on what
elements you already have selected, and whether you will need to store a
reference to the elements you’re adding to the page. If you need to
store a reference, you will always want to take the first approach –
placing the selected elements relative to another element — as it
returns the element(s) you’re placing. In this case,
$.fn.insertAfter, $.fn.insertBefore,
$.fn.appendTo, and $.fn.prependTo will be your
tools of choice.

jQuery offers a trivial and elegant way to create new elements
using the same $() method you use to make

Note that in the attributes object we included as the second
argument, the property name class is quoted, while the property names
text and href are not. Property names generally do not need to be quoted
unless they are reserved words (as class is in this case).

When you create a new element, it is not immediately added to the
page. There are several ways to add an element to the page once it’s
been created.

Strictly speaking, you don’t have to store the created element
in a variable — you could just call the method to add the element to
the page directly after the $(). However, most of the time you will want
a reference to the element you added, so you don’t need to select it

You can even create an element as you’re adding it to the page,
but note that in this case you don’t get a reference to the newly
created element.

jQuery offers several utility methods in the $
namespace. These methods are helpful for accomplishing routine programming
tasks. Below are examples of a few of the utility methods; for a complete
reference on jQuery utility methods, visit

Removes leading and trailing whitespace.

$.trim('    lots of extra whitespace    ');
// returns 'lots of extra whitespace'
Iterates over arrays and objects.

$.each([ 'foo', 'bar', 'baz' ], function(idx, val) {
    console.log('element ' + idx + 'is ' + val);

$.each({ foo : 'bar', baz : 'bim' }, function(k, v) {
    console.log(k + ' : ' + v);


There is also a method $.fn.each, which is used
for iterating over a selection of elements.

Returns a value’s index in an array, or -1 if the value is not
in the array.

var myArray = [ 1, 2, 3, 5 ];

if ($.inArray(4, myArray) !== -1) {
    console.log('found it!');
Changes the properties of the first object using the
properties of subsequent objects.

var firstObject = { foo : 'bar', a : 'b' };
var secondObject = { foo : 'baz' };

var newObject = $.extend(firstObject, secondObject);
console.log(firstObject.foo); // 'baz'
console.log(newObject.foo);   // 'baz'

If you don’t want to change any of the objects you pass to
$.extend, pass an empty object as the first

var firstObject = { foo : 'bar', a : 'b' };
var secondObject = { foo : 'baz' };

var newObject = $.extend({}, firstObject, secondObject);
console.log(firstObject.foo); // 'bar'
console.log(newObject.foo);   // 'baz'
Returns a function that will always run in the provided scope
— that is, sets the meaning of this inside the passed
function to the second argument.

var myFunction = function() { console.log(this); };
var myObject = { foo : 'bar' };

myFunction(); // logs window object

var myProxyFunction = $.proxy(myFunction, myObject);
myProxyFunction(); // logs myObject object

If you have an object with methods, you can pass the object
and the name of a method to return a function that will always run
in the scope of the object.

var myObject = {
    myFn : function() {

$('#foo').click(myObject.myFn); // logs DOM element #foo
$('#foo').click($.proxy(myObject, 'myFn')); // logs myObject

As your work with jQuery progresses, you’ll find that there’s often
data about an element that you want to store with the element. In plain
JavaScript, you might do this by adding a property to the DOM element, but
you’d have to deal with memory leaks in some browsers. jQuery offers a
straightforward way to store data related to an element, and it manages
the memory issues for you.

You can store any kind of data on an element, and it’s hard to
overstate the importance of this when you get into complex application
development. For the purposes of this class, we’ll mostly use
$.fn.data to store references to other elements.

For example, we may want to establish a relationship between a list
item and a div that’s inside of it. We could establish this relationship
every single time we interact with the list item, but a better solution
would be to establish the relationship once, and then store a pointer to
the div on the list item using $.fn.data:

In addition to passing $.fn.data a single key-value
pair to store data, you can also pass an object containing one or more

Although jQuery eliminates most JavaScript browser quirks, there are
still occasions when your code needs to know about the browser

jQuery offers the $.support object, as well as the
deprecated $.browser object, for this purpose. For complete
documentation on these objects, visit
and http://api.jquery.com/jQuery.browser/.

The $.support object is dedicated to determining what
features a browser supports; it is recommended as a more “future-proof”
method of customizing your JavaScript for different browser

The $.browser object was deprecated in favor of the
$.support object, but it will not be removed from jQuery
anytime soon. It provides direct detection of the browser brand and

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

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.

Frequently used effects are built into jQuery as methods:

Proper use of Ajax-related jQuery methods requires understanding
some key concepts first.

While jQuery does offer many Ajax-related convenience methods, the
core $.ajax method is at the heart of all of them, and
understanding it is imperative. We’ll review it first, and then touch
briefly on the convenience methods.

I generally use the $.ajax method and do not use convenience
methods. As you’ll see, it offers features that the convenience methods do
not, and its syntax is more easily understandable, in my opinion.

jQuery’s core $.ajax method is a powerful and
straightforward way of creating Ajax requests. It takes a configuration
object that contains all the instructions jQuery requires to complete
the request. The $.ajax method is particularly valuable
because it offers the ability to specify both success and failure
callbacks. Also, its ability to take a configuration object that can be
defined separately makes it easier to write reusable code. For complete
documentation of the configuration options, visit

There are many, many options for the $.ajax method, which is
part of its power. For a complete list of options, visit
here are several that you will use frequently:

Set to false if the request should be sent
synchronously. Defaults to true. Note that if you
set this option to false, your request will block execution of
other code until the response is received.

Whether to use a cached response if available. Defaults to
true for all dataTypes except “script” and “jsonp”.
When set to false, the URL will simply have a cachebusting
parameter appended to it.

A callback function to run when the request is complete,
regardless of success or failure. The function receives the raw
request object and the text status of the request.

The scope in which the callback function(s) should run
(i.e. what this will mean inside the callback
function(s)). By default, this inside the callback
function(s) refers to the object originally passed to

The data to be sent to the server. This can either be an
object or a query string, such as

The type of data you expect back from the server. By
default, jQuery will look at the MIME type of the response if no
dataType is specified.

A callback function to run if the request results in an
error. The function receives the raw request object and the text
status of the request.

The callback name to send in a query string when making a
JSONP request. Defaults to “callback”.

A callback function to run if the request succeeds. The
function receives the response data (converted to a JavaScript
object if the dataType was JSON), as well as the text status of
the request and the raw request object.

The time in milliseconds to wait before considering the
request a failure.

Set to true to use the param serialization style in use
prior to jQuery 1.4. For details, see http://api.jquery.com/jQuery.param/.

The type of the request, “POST” or “GET”. Defaults to
“GET”. Other request types, such as “PUT” and “DELETE” can be
used, but they may not be supported by all browsers.

The URL for the request.

The url option is the only required property of the
$.ajax configuration object; all other properties are

If you don’t need the extensive configurability of
$.ajax, and you don’t care about handling errors, the Ajax
convenience functions provided by jQuery can be useful, terse ways to
accomplish Ajax requests. These methods are just “wrappers” around the
core $.ajax method, and simply pre-set some of the options
on the $.ajax method.

The convenience methods provided by jQuery are:

In each case, the methods take the following arguments, in

jQuery’s ajax capabilities can be especially useful when dealing
with forms. The
Form Plugin
is a well-tested tool for adding Ajax capabilities to
forms, and you should generally use it for handling forms with Ajax rather
than trying to roll your own solution for anything remotely complex. That
said, there are a two jQuery methods you should know that relate to form
processing in jQuery: $.fn.serialize and

The notation for creating a typical plugin is as follows:

    $.fn.myNewPlugin = function() {
        return this.each(function(){
            // do something

Don’t let that confuse you though. The point of a jQuery plugin is
to extend jQuery’s prototype object, and that’s what’s happening on this

$.fn.myNewPlugin = function() { //...

We wrap this assignment in an immediately-invoked function:


This has the effect of creating a “private” scope that allows us to
extend jQuery using the dollar symbol without having to risk the
possibility that the dollar has been over-written by another

So our actual plugin, thus far, is this:

$.fn.myNewPlugin = function() {
    return this.each(function(){
        // do something

The this keyword within the new plugin refers to the
jQuery object on which the plugin is being called.

var somejQueryObject = $('#something');

$.fn.myNewPlugin = function() {
    alert(this === somejQueryObject);

somejQueryObject.myNewPlugin(); // alerts 'true'

Your typical jQuery object will contain references to any number of
DOM elements, and that’s why jQuery objects are often referred to as

So, to do something with a collection we need to loop through it,
which is most easily achieved using jQuery’s each()

$.fn.myNewPlugin = function() {
    return this.each(function(){


jQuery’s each() method, like most other jQuery methods,
returns a jQuery object, thus enabling what we’ve all come to know and
love as ‘chaining’ ($(...).css().attr()...). We wouldn’t want
to break this convention so we return the this object. Within
this loop you can do whatever you want with each element. Here’s an
example of a small plugin using some of the techniques we’ve

    $.fn.showLinkLocation = function() {
        return this.filter('a').each(function(){
                ' (' + $(this).attr('href') + ')'

// Usage example:

This handy plugin goes through all anchors in the collection and
appends the href attribute in brackets.

<!-- Before plugin is called: -->
<a href="page.html">Foo</a>

<!-- After plugin is called: -->
<a href="page.html">Foo (page.html)</a>

Our plugin can be optimised though:

    $.fn.showLinkLocation = function() {
        return this.filter('a').append(function(){
              return ' (' + this.href + ')';

We’re using the append method’s capability to accept a
callback, and the return value of that callback will determine what is
appended to each element in the collection. Notice also that we’re not
using the attr method to retrieve the href
attribute, because the native DOM API gives us easy access with the aptly
named href property.

Here’s another example of a plugin. This one doesn’t require us to
loop through every elememt with the each() method. Instead,
we’re simply going to delegate to other jQuery methods directly:

    $.fn.fadeInAndAddClass = function(duration, className) {
        return this.fadeIn(duration, function(){

// Usage example:
$('a').fadeInAndAddClass(400, 'finishedFading');

Sometimes you want to make a piece of functionality available
throughout your code; for example, perhaps you want a single method you
can call on a jQuery selection that performs a series of operations on the
selection. In this case, you may want to write a plugin.

Most plugins are simply methods created in the $.fn
namespace. jQuery guarantees that a method called on a jQuery object will
be able to access that jQuery object as this inside the
method. In return, your plugin needs to guarantee that it returns the same
object it received, unless explicitly documented otherwise.

Here is an example of a simple plugin:

For more on plugin development, read Mike Alsup’s essential post,
Plugin Development Pattern
. In it, he creates a plugin called
$.fn.hilight, which provides support for the metadata plugin
if it’s present, and provides a centralized method for setting global and
instance options for the plugin.

While most existing jQuery plugins are stateless — that is, we
call them on an element and that is the extent of our interaction with the
plugin — there’s a large set of functionality that doesn’t fit into the
basic plugin pattern.

In order to fill this gap, jQuery UI has implemented a more advanced
plugin system. The new system manages state, allows multiple functions to
be exposed via a single plugin, and provides various extension points.
This system is called the widget factory and is exposed as
jQuery.widget as part of jQuery UI 1.8; however, it can be
used independently of jQuery UI.

To demonstrate the capabilities of the widget factory, we’ll build a
simple progress bar plugin.

To start, we’ll create a progress bar that just lets us set the
progress once. As we can see below, this is done by calling
jQuery.widget with two parameters: the name of the plugin to
create and an object literal containing functions to support our plugin.
When our plugin gets called, it will create a new plugin instance and all
functions will be executed within the context of that instance. This is
different from a standard jQuery plugin in two important ways. First, the
context is an object, not a DOM element. Second, the context is always a
single object, never a collection.

The name of the plugin must contain a namespace; in this case we’ve
used the nmk namespace. There is a limitation that namespaces
be exactly one level deep — that is, we can’t use a namespace like
nmk.foo. We can also see that the widget factory has provided
two properties for us. this.element is a jQuery object
containing exactly one element. If our plugin is called on a jQuery object
containing multiple elements, a separate plugin instance will be created
for each element, and each instance will have its own
this.element. The second property, this.options,
is a hash containing key/value pairs for all of our plugin’s options.
These options can be passed to our plugin as shown here.

When we call jQuery.widget it extends jQuery by adding
a method to jQuery.fn (the same way we’d create a standard
plugin). The name of the function it adds is based on the name you pass to
jQuery.widget, without the namespace; in our case it will
create jQuery.fn.progressbar. The options passed to our
plugin get set in this.options inside of our plugin instance.
As shown below, we can specify default values for any of our options. When
designing your API, you should figure out the most common use case for
your plugin so that you can set appropriate default values and make all
options truly optional.

Now that we can initialize our progress bar, we’ll add the ability
to perform actions by calling methods on our plugin instance. To define
a plugin method, we just include the function in the object literal that
we pass to jQuery.widget. We can also define “private”
methods by prepending an underscore to the function name.

To call a method on a plugin instance, you pass the name of the
method to the jQuery plugin. If you are calling a method that accepts
parameters, you simply pass those parameters after the method name.

One of the easiest ways to make your plugin extensible is to add
callbacks so users can react when the state of your plugin changes. We
can see below how to add a callback to our progress bar to signify when
the progress has reached 100%. The _trigger method takes
three parameters: the name of the callback, a native event object that
initiated the callback, and a hash of data relevant to the event. The
callback name is the only required parameter, but the others can be very
useful for users who want to implement custom functionality on top of
your plugin. For example, if we were building a draggable plugin, we
could pass the native mousemove event when triggering a drag callback;
this would allow users to react to the drag based on the x/y coordinates
provided by the event object.

Callback functions are essentially just additional options, so you
can get and set them just like any other option. Whenever a callback is
executed, a corresponding event is triggered as well. The event type is
determined by concatenating the plugin name and the callback name. The
callback and event both receive the same two parameters: an event object
and a hash of data relevant to the event, as we’ll see below.

If your plugin has functionality that you want to allow the user
to prevent, the best way to support this is by creating cancelable
callbacks. Users can cancel a callback, or its associated event, the
same way they cancel any native event: by calling
event.preventDefault() or using return false.
If the user cancels the callback, the _trigger method will
return false so you can implement the appropriate functionality within
your plugin.

Please visit http://github.com/rmurphey/jqfundamentals
to contribute!

This chapter covers a number of jQuery and JavaScript best practices,
in no particular order. Many of the best practices in this chapter are based
on the
jQuery Anti-Patterns for
presentation by Paul Irish.

Selector optimization is less important than it used to be, as more
browser implement document.querySelectorAll() and the burden
of selection shifts from jQuery to the browser. However, there are still
some tips to keep in midn.

When you move beyond adding simple enhancements to your website with
jQuery and start developing full-blown client-side applications, you need
to consider how to organize your code. In this chapter, we’ll take a look
at various code organization patterns you can use in your jQuery
application and explore the RequireJS dependency management and build

The first step to code organization is separating pieces of your
application into distinct pieces; sometimes, even just this effort is
sufficient to lend

An object literal is perhaps the simplest way to encapsulate
related code. It doesn’t offer any privacy for properties or methods,
but it’s useful for eliminating anonymous functions from your code,
centralizing configuration options, and easing the path to reuse and

The object literal above is simply an object assigned to a
variable. The object has one property and several methods. All of the
properties and methods are public, so any part of your application can
see the properties and call methods on the object. While there is an
init method, there’s nothing requiring that it be called before the
object is functional.

How would we apply this pattern to jQuery code? Let’s say that we
had this code written in the traditional jQuery style:

// clicking on a list item loads some content
// using the list item's ID and hides content
// in sibling list items
$(document).ready(function() {
  $('#myFeature li')
    .click(function() {
      var $this = $(this);
      var $div = $this.find('div');
      $div.load('foo.php?item=' +
        function() {

If this were the extent of our application, leaving it as-is would
be fine. On the other hand, if this was a piece of a larger application,
we’d do well to keep this functionality separate from unrelated
functionality. We might also want to move the URL out of the code and
into a configuration area. Finally, we might want to break up the chain
to make it easier to modify pieces of the functionality later.

The first thing you’ll notice is that this approach is obviously
far longer than the original — again, if this were the extent of our
application, using an object literal would likely be overkill. Assuming
it’s not the extent of our application, though, we’ve gained several

For non-trivial features, object literals are a clear improvement
over a long stretch of code stuffed in a $(document).ready() block, as
they get us thinking about the pieces of our functionality. However,
they aren’t a whole lot more advanced than simply having a bunch of
function declarations inside of that $(document).ready() block.

The module pattern overcomes some of the limitations of the object
literal, offering privacy for variables and functions while exposing a
public API if desired.

In the example above, we self-execute an anonymous function that
returns an object. Inside of the function, we define some variables.
Because the variables are defined inside of the function, we don’t have
access to them outside of the function unless we put them in the return
object. This means that no code outside of the function has access to
the privateThing variable or to the
changePrivateThing function. However,
sayPrivateThing does have access to
privateThing and changePrivateThing, because
both were defined in the same scope as

This pattern is powerful because, as you can gather from the
variable names, it can give you private variables and functions while
exposing a limited API consisting of the returned object’s properties
and methods.

Below is a revised version of the previous example, showing how we
could create the same feature using the module pattern while only
exposing one public method of the module,

When a project reaches a certain size, managing the script modules
for a project starts to get tricky. You need to be sure to sequence the
scripts in the right order, and you need to start seriously thinking about
combining scripts together into a bundle for deployment, so that only one
or a very small number of requests are made to load the scripts. You may
also want to load code on the fly, after page load.

RequireJS, a dependency management tool by James Burke, can help you
manage the script modules, load them in the right order, and make it easy
to combine the scripts later via the RequireJS optimization tool without
needing to change your markup. It also gives you an easy way to load
scripts after the page has loaded, allowing you to spread out the download
size over time.

RequireJS has a module system that lets you define well-scoped
modules, but you do not have to follow that system to get the benefits of
dependency management and build-time optimizations. Over time, if you
start to create more modular code that needs to be reused in a few places,
the module format for RequireJS makes it easy to write encapsulated code
that can be loaded on the fly. It can grow with you, particularly if you
want to incorporate internationalization (i18n) string bundles, to
localize your project for different languages, or load some HTML strings
and make sure those strings are available before executing code, or even
use JSONP services as dependencies.

The easiest way to use RequireJS with jQuery is to download a build of
jQuery that has RequireJS built in
. This build excludes portions
of RequireJS that duplicate jQuery functionality. You may also find it
useful to download a
sample jQuery project that uses RequireJS

RequireJS makes it easy to define reusable modules via
require.def(). A RequireJS module can have dependencies
that can be used to define a module, and a RequireJS module can return a
value — an object, a function, whatever — that can then be consumed by
yet other modules.

If your module does not have any dependencies, then just specify
the name of the module as the first argument to
require.def(). The second argument is just an object
literal that defines the module’s properties. For example:

Example 10.7. Defining a RequireJS module that has no dependencies

        color: "black",
        size: "unisize"

This example would be stored in a my/simpleshirt.js file.

If your module has dependencies, you can specify the
dependencies as the second argument to require.def() (as
an array) and then pass a function as the third argument. The function
will be called to define the module once all dependencies have loaded.
The function receives the values returned by the dependencies as its
arguments (in the same order they were required in the array), and the
function should return an object that defines the module.

In this example, a my/shirt module is created. It depends on
my/cart and my/inventory. On disk, the files are structured like this:


The function that defines my/shirt is not called
until the my/cart and my/inventory modules
have been loaded, and the function receives the modules as the
cart and inventory arguments. The order of
the function arguments must match the order in which the dependencies
were required in the dependencies array. The object returned by the
function call defines the my/shirt module. Be defining
modules in this way, my/shirt does not exist as a global
object. Modules that define globals are explicitly discouraged, so
multiple versions of a module can exist in a page at a time.

Modules do not have to return objects; any valid return value
from a function is allowed.

Only one module should be required per JavaScript file.

Once you incorporate RequireJS for dependency management, your
page is set up to be optimized very easily. Download the RequireJS
source and place it anywhere you like, preferrably somewhere outside
your web development area. For the purposes of this example, the
RequireJS source is placed as a sibling to the
webapp directory, which contains the HTML page and
the scripts directory with all the scripts. Complete directory

requirejs/ (used for the build tools)

Then, in the scripts directory that has
require-jquery.js and app.js, create a file called
app.build.js with the following contents:

To use the build tool, you need Java 6 installed. Closure Compiler
is used for the JavaScript minification step (if optimize:
is commented out), and it requires Java 6.

To start the build, go to the webapp/scripts directory, execute
the following command:

# non-windows systems
../../requirejs/build/build.sh app.build.js

# windows systems
..\..\requirejs\build\build.bat app.build.js

Now, in the webapp-build directory, app.js
will have the app.js contents,
jquery.alpha.js and
jquery.beta.js inlined. If you then load the
app.html file in the
webapp-build directory, you should not see any
network requests for jquery.alpha.js and

We’re all familiar with the basic events — click, mouseover, focus,
blur, submit, etc. — that we can latch on to as a user interacts with the
browser. Custom events open up a whole new world of event-driven
programming. In this chapter, we’ll use jQuery’s custom events system to
make a simple Twitter search application.

It can be difficult at first to understand why you’d want to use
custom events, when the built-in events seem to suit your needs just fine.
It turns out that custom events offer a whole new way of thinking about
event-driven JavaScript. Instead of focusing on the element that triggers
an action, custom events put the spotlight on the element being acted
upon. This brings a bevy of benefits, including:

Why should you care? An example is probably the best way to explain.
Suppose you have a lightbulb in a room in a house. The lightbulb is
currently turned on, and it’s controlled by two three-way switches and a

<div class="room" id="kitchen">
    <div class="lightbulb on"></div>
    <div class="switch"></div>
    <div class="switch"></div>
    <div class="clapper"></div>

Triggering the clapper or either of the switches will change the
state of the lightbulb. The switches and the clapper don’t care what state
the lightbulb is in; they just want to change the state.

Without custom events, you might write some code like this:

$('.switch, .clapper').click(function() {
    var $light = $(this).parent().find('.lightbulb');
    if ($light.hasClass('on')) {
    } else {

With custom events, your code might look more like this:

$('.lightbulb').bind('changeState', function(e) {
    var $light = $(this);
    if ($light.hasClass('on')) {
    } else {

$('.switch, .clapper').click(function() {

This last bit of code is not that exciting, but something important
has happened: we’ve moved the behavior of the lightbulb to the lightbulb,
and away from the switches and the clapper.

Let’s make our example a little more interesting. We’ll add another
room to our house, along with a master switch, as shown here:

<div class="room" id="kitchen">
    <div class="lightbulb on"></div>
    <div class="switch"></div>
    <div class="switch"></div>
    <div class="clapper"></div>
<div class="room" id="bedroom">
    <div class="lightbulb on"></div>
    <div class="switch"></div>
    <div class="switch"></div>
    <div class="clapper"></div>
<div id="master_switch"></div>

If there are any lights on in the house, we want the master switch
to turn all the lights off; otherwise, we want it to turn all lights on.
To accomplish this, we’ll add two more custom events to the lightbulbs:
turnOn and turnOff. We’ll make use of them in
the changeState custom event, and use some logic to decide
which one the master switch should trigger:

    .bind('changeState', function(e) {
        var $light = $(this);
        if ($light.hasClass('on')) {
        } else {
    .bind('turnOn', function(e) {
    .bind('turnOff', function(e) {

$('.switch, .clapper').click(function() {

$('#master_switch').click(function() {
    if ($('.lightbulb.on').length) {
    } else {

Note how the behavior of the master switch is attached to the master
switch; the behavior of a lightbulb belongs to the lightbulbs.

To demonstrate the power of custom events, we’re going to create a
simple tool for searching Twitter. The tool will offer several ways for
a user to add search terms to the display: by entering a search term in
a text box, by entering multiple search terms in the URL, and by
querying Twitter for trending terms.

The results for each term will be shown in a results container;
these containers will be able to be expanded, collapsed, refreshed, and
removed, either individually or all at once.

When we’re done, it will look like this:

We’ll start with some basic HTML:

<h1>Twitter Search</h1>
<input type="button" id="get_trends"
    value="Load Trending Terms" />

    <input type="text" class="input_text"
        id="search_term" />
    <input type="submit" class="input_submit"
        value="Add Search Term" />

<div id="twitter">
    <div class="template results">
        <h2>Search Results for
        <span class="search_term"></span></h2>

This gives us a container (#twitter) for our widget, a template
for our results containers (hidden via CSS), and a simple form where
users can input a search term. (For the sake of simplicity, we’re
going to assume that our application is JavaScript-only and that our
users will always have CSS.)

There are two types of objects we’ll want to act on: the results
containers, and the Twitter container.

The results containers are the heart of the application. We’ll
create a plugin that will prepare each results container once it’s
added to the Twitter container. Among other things, it will bind the
custom events for each container and add the action buttons at the top
right of each container. Each results container will have the
following custom events:

The plugin is also responsible for adding the action buttons to
the container. It binds a click event to each action’s list item, and
uses the list item’s class to determine which custom event will be
triggered on the corresponding results container.

$.fn.twitterResult = function(settings) {
    return $(this).each(function() {
        var $results = $(this),
            $actions = $.fn.twitterResult.actions =
                $.fn.twitterResult.actions ||
            $a = $actions.clone().prependTo($results),
            term = settings.term;


            ['refresh', 'populate', 'remove', 'collapse', 'expand'],
            function(i, ev) {
                    { term : term },

        // use the class of each action to figure out
        // which event it will trigger on the results panel
        $a.find('li').click(function() {
            // pass the li that was clicked to the function
            // so it can be manipulated if needed
            $results.trigger($(this).attr('class'), [ $(this) ]);

$.fn.twitterResult.createActions = function() {
    return $('<ul class="actions" />').append(
        '<li class="refresh">Refresh</li>' +
        '<li class="remove">Remove</li>' +
        '<li class="collapse">Collapse</li>'

$.fn.twitterResult.events = {
    refresh : function(e) {
           // indicate that the results are refreshing
        var $this = $(this).addClass('refreshing');

        $results.append('<p class="loading">Loading ...</p>');

        // get the twitter data using jsonp
            'http://search.twitter.com/search.json?q=' +
                escape(e.data.term) + '&rpp=5&callback=?',
            function(json) {
                $this.trigger('populate', [ json ]);

    populate : function(e, json) {
        var results = json.results;
        var $this = $(this);


        $.each(results, function(i,result) {
            var tweet = '<p class="tweet">' +
                '<a href="http://twitter.com/' +
                result.from_user +
                '">' +
                result.from_user +
                '</a>: ' +
                result.text +
                ' <span class="date">' +
                result.created_at +
                '</span>' +

        // indicate that the results
        // are done refreshing

    remove : function(e, force) {
        if (
            !force &&
            !confirm('Remove panel for term ' + e.data.term + '?')
        ) {

        // indicate that we no longer
        // have a panel for the term
        search_terms[e.data.term] = 0;

    collapse : function(e) {


    expand : function(e) {


The Twitter container itself will have just two custom events:

Here’s how the Twitter container bindings look:

    .bind('getResults', function(e, term) {
        // make sure we don't have a box for this term already
        if (!search_terms[term]) {
            var $this = $(this);
            var $template = $this.find('div.template');

            // make a copy of the template div
            // and insert it as the first results box
            $results = $template.clone().
                    'term' : term

            // load the content using the "refresh"
            // custom event that we bound to the results container
            search_terms[term] = 1;
    .bind('getTrends', function(e) {
        var $this = $(this);
        $.getJSON('http://search.twitter.com/trends.json?callback=?', function(json) {
                var trends = json.trends;
                $.each(trends, function(i, trend) {
                    $this.trigger('getResults', [ trend.name ]);

So far, we’ve written a lot of code that does approximately
nothing, but that’s OK. By specifying all the behaviors that we want
our core objects to have, we’ve created a solid framework for rapidly
building out the interface.

Let’s start by hooking up our text input and the “Load Trending
Terms” button. For the text input, we’ll capture the term that was
entered in the input and pass it as we trigger the Twitter container’s
getResults event. Clicking the “Load Trending Terms” will
trigger the Twitter container’s getTrends event:

$('form').submit(function(e) {
    var term = $('#search_term').val();
    $('#twitter').trigger('getResults', [ term ]);

$('#get_trends').click(function() {

By adding a few buttons with the appropriate IDs, we can make it
possible to remove, collapse, expand, and refresh all results
containers at once, as shown below. For the remove button, note how
we’re passing a value of true to the event handler as its second
argument, telling the event handler that we don’t want to verify the
removal of individual containers.

$.each(['refresh', 'expand', 'collapse'], function(i, ev) {
    $('#' + ev).click(function(e) { $('#twitter div.results').trigger(ev); });

$('#remove').click(function(e) {
    if (confirm('Remove all results?')) {
        $('#twitter div.results').trigger('remove', [ true ]);

About admin

My Developer Forum is a non-profit, open source website dedicated to empowering young, eager designers and developers to take the web to a higher level of complexity, and elegance.
This entry was posted in cis mhcc, CSS & HTML, Featured, jQuery, Kitchen Sink and tagged . Bookmark the permalink.

19 Responses to jQuery Documentation

  1. Travel Deals says:

    Hi I like this article and it was so fabulous and I am definetly going to save it. I Have to say the Superb analysis this article has is trully remarkable.Who goes that extra mile these days? Bravo :) Just another suggestion you caninstall a Translator for your Worldwide Readers !!!

  2. Sometimes I lie awake at night, and I ask, ‘Where have I gone wrong?’ Then a voice says to me, ‘This is going to take more than one night.’ !l13w!

  3. Buy Links says:

    Way to focus and straight to your point, i love it. Keep up the work people. Dont let anyone stop us bloggers.

  4. Thank you for give very nice info What a cool site.

  5. Viva Palardy says:

    Oh, this is quite interesting. Actulally, I found your blog on google search. I will tell my friend about your blog later.

  6. Can I make a suggestion? I think youve got something good here. But what if you added a couple links to a page that backs up what youre saying? Or maybe you could give us something to look at, something that would connect what youre saying to something tangible? Just a suggestion.

  7. The new Zune browser is surprisingly good, but not as good as the iPod’s. It works well, but isn’t as fast as Safari, and has a clunkier interface. If you occasionally plan on using the web browser that’s not an issue, but if you’re planning to browse the web alot from your PMP then the iPod’s larger screen and better browser may be important.

  8. Cool post, thank you for the info – I dont really ever post on these thingy’s but enjoyed the info. Awesome stuff!, I bookmarked your blog!

  9. Jenny says:

    Greetings, I I stumbled upon your site on yahoo and browse pretty much all your other pages. I just added you to my RSS feeder. Keep up the amazing job. Looking forward to reading more from you in the future. You know, I must say, I really enjoy this site and the insight from everyone who participates. I find it to be refreshing and very informative. I wish there were more blogs like it. Anyway, I felt it was about time I posted, I?ve spent most of my time here just lurking and reading, but today for some reason I just felt compelled to say this.

  10. frostwire says:

    Hello there, You’ve done an incredible job. I’ll certainly digg it and personally suggest to my friends. I am sure they will be benefited from this website.

  11. Your post fashion and blog page template are not harmonious, transform a good blog’s template.

  12. Halley Hemp says:

    I am constantly looking online for posts that can facilitate me. Thank you!

  13. frostwire says:

    Hi there, You have done an excellent job. I’ll definitely digg it and personally suggest to my friends. I’m sure they’ll be benefited from this site.

  14. Xnxx says:

    Interesting thoughts here. I appreciate you taking the time to share them with us all. It’s people like you that make my day :)

  15. Corset Tops says:

    “~. I am very thankful to this topic because it really gives up to date information “`.

  16. UV Paint says:

    :”‘ that seems to be a great topic, i really love it .~”

  17. Eldon Bussy says:

    Great beat ! I would like to apprentice at the same time as you amend your website, how could i subscribe for a weblog site? The account helped me a applicable deal. I were tiny bit acquainted of this your broadcast offered vibrant transparent idea

Leave a Reply

Your email address will not be published. Required fields are marked *


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>