Showing with 1,545 additions and 1,808 deletions.
  1. +1 −1 CONTRIBUTING.md
  2. +1 −1 README.md
  3. +7 −7 page/about-jquery/additional-support.md
  4. +64 −64 page/about-jquery/how-jquery-works.md
  5. +8 −8 page/about.md
  6. +5 −5 page/ajax.md
  7. +37 −59 page/ajax/ajax-and-forms.md
  8. +9 −14 page/ajax/ajax-events.md
  9. +70 −87 page/ajax/jquery-ajax-methods.md
  10. +25 −30 page/ajax/key-concepts.md
  11. +17 −21 page/ajax/working-with-jsonp.md
  12. +18 −29 page/code-organization/beware-anonymous-functions.md
  13. +143 −163 page/code-organization/concepts.md
  14. +29 −29 page/code-organization/deferreds.md
  15. +159 −161 page/code-organization/deferreds/examples.md
  16. +39 −40 page/code-organization/deferreds/jquery-deferreds.md
  17. +10 −20 page/code-organization/dont-repeat-yourself.md
  18. +18 −26 page/code-organization/feature-browser-detection.md
  19. +2 −2 page/effects.md
  20. +19 −23 page/effects/custom-effects.md
  21. +73 −74 page/effects/intro-to-effects.md
  22. +27 −36 page/effects/queue-and-dequeue-explained.md
  23. +143 −181 page/effects/uses-of-queue-and-dequeue.md
  24. +2 −2 page/events.md
  25. +79 −79 page/events/event-basics.md
  26. +34 −49 page/events/event-delegation.md
  27. +69 −75 page/events/event-extensions.md
  28. +10 −14 page/events/event-helpers.md
  29. +46 −47 page/events/handling-events.md
  30. +40 −39 page/events/history-of-events.md
  31. +11 −17 page/events/inside-event-handling-function.md
  32. +236 −276 page/events/introduction-to-custom-events.md
  33. +45 −61 page/events/introduction-to-events.md
  34. +23 −31 page/events/triggering-event-handlers.md
  35. +17 −19 page/index.html
  36. +7 −18 page/javascript-101/reserved-words.md
  37. +2 −0 page/using-jquery-core/understanding-index.md
2 CONTRIBUTING.md
View file
@@ -7,7 +7,7 @@ customFields:
---

Depending on your level of experience with some of the workflows common to many
open source projects, e.g., git/Github, the command line, and setting up a
open source projects, e.g. git/GitHub, the command line, and setting up a
local development environment, contributing to this site may be a breeze or
come with a bit of a learning curve. If you fit into the former group, great!
Jump ahead to learn how to get started.
2 README.md
View file
@@ -36,7 +36,7 @@ Each of the articles on the site has some [YAML "Front Matter"](https://github.c

`level: advanced`

## Building && Working Locally
## Building & Working Locally

As this site is part of the jQuery network of sites, its presentation is controlled by our [web base template](https://github.com/jquery/jquery-wp-content). To preview the site locally, first follow the [instructions there](https://github.com/jquery/jquery-wp-content) to set up a local version of the jQuery WordPress network. Then, clone this repo and run the following steps (node.js required).

14 page/about-jquery/additional-support.md
View file
@@ -27,7 +27,7 @@ There are many subforums where you can discuss jQuery, ask questions, talk about
* [Developing jQuery Plugins](http://forum.jquery.com/developing-jquery-plugins)
* This forum covers development of jQuery plugins.
* [Developing jQuery UI](http://forum.jquery.com/developing-jquery-ui)
* This is the place to discuss development of [jQuery UI](http://jqueryui.com/) itself - including bugs, new plugins, and how you can help.
* This is the place to discuss development of [jQuery UI](http://jqueryui.com/) itself — including bugs, new plugins, and how you can help.
* All jQuery UI svn commits are posted to this list to facilitate feedback, discussion, and review.
* Also note that a lot of the development and planning of jQuery UI takes place on the [jQuery UI Development and Planning Wiki](http://wiki.jqueryui.com/).
* [Developing jQuery Mobile](http://forum.jquery.com/developing-jquery-mobile)
@@ -41,12 +41,12 @@ To ensure that you'll get a useful answer in no time, please consider the follow

* Ensure your markup is valid.
* Use Firebug/Developer Tools to see if you have an exception.
* Use Firebug/Developer Tools to inspect the html classes, css. etc.
* Try expected resulting html and css without javascript/jQuery and see if the problem could be isolated to those two.
* Use Firebug/Developer Tools to inspect the HTML classes, CSS, etc.
* Try expected resulting HTML and CSS without JavaScript/jQuery and see if the problem could be isolated to those two.
* Reduce to a minimal test case (keep removing things until the problem goes away, etc.)
* Provide that test case as part of your mail. Either upload it somewhere or post it on jsbin.com.
* Provide that test case as part of your mail. Either upload it somewhere or post it on [jsbin.com](http://jsbin.com/).

In general, keep your question short and focused and provide only essential details - others can be added when required.
In general, keep your question short and focused and provide only essential details — others can be added when required.

### Mailing List Archives

@@ -71,8 +71,8 @@ The IRC Channel is best if you need quick help with any of the following:

* JavaScript
* jQuery syntax
* problem solving
* strange bugs.
* Problem solving
* Strange bugs

If your problem is more in-depth, we may ask you to post to the mailing list, or the bug tracker, so that we can help you in a more-suitable environment.

128 page/about-jquery/how-jquery-works.md
View file
@@ -5,22 +5,22 @@ level: beginner
### jQuery: The Basics

This is a basic tutorial, designed to help you get started using jQuery. If you
don't have a test page setup yet, start by creating the following HTML page:
don't have a test page setup yet, start by creating the following HTML page:

```
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Demo</title>
</head>
<body>
<a href="http://jquery.com/">jQuery</a>
<script src="jquery.js"></script>
<script>
// Your code goes here
</script>
</body>
<head>
<meta charset="utf-8">
<title>Demo</title>
</head>
<body>
<a href="http://jquery.com/">jQuery</a>
<script src="jquery.js"></script>
<script>
// Your code goes here
</script>
</body>
</html>
```

@@ -30,77 +30,77 @@ and store the `jquery.js` file in the same directory as your HTML file.

### Launching Code on Document Ready

To ensure that their code runs after the browser finishes loading the document,
To ensure that their code runs after the browser finishes loading the document,
many JavaScript programmers wrap their code in an `onload` function:

```
window.onload = function() {
alert("welcome");
alert( "welcome" );
}
```

Unfortunately, the code doesn't run until all images are finished downloading, including banner ads.
To run code as soon as the `document` is ready to be manipulated, jQuery has a statement
known as the [ ready event ](http://api.jquery.com/ready):
To run code as soon as the `document` is ready to be manipulated, jQuery has a statement
known as the [ready event](http://api.jquery.com/ready):

```
$( document ).ready( function() {
// Your code here
$( document ).ready(function() {
// Your code here
});
```

For example, inside the `ready` event, you can add a click handler to the link:

```
$( document ).ready(function() {
$("a").click(function( event ) {
alert("Thanks for visiting!");
});
$( "a" ).click(function( event ) {
alert( "Thanks for visiting!" );
});
});
```

Save your HTML file and reload the test page in your browser.
Clicking the link should now first display an alert pop-up,
Save your HTML file and reload the test page in your browser.
Clicking the link should now first display an alert pop-up,
then continue with the default behavior of navigating to http://jquery.com.

For `click` and most other [events](http://api.jquery.com/category/events/),
For `click` and most other [events](http://api.jquery.com/category/events/),
you can prevent the default behavior by calling `event.preventDefault()` in the event handler:

```
$( document ).ready(function() {
$("a").click(function( event ) {
alert("As you can see, the link no longer took you to jquery.com");
event.preventDefault();
});
$( "a" ).click(function( event ) {
alert( "As you can see, the link no longer took you to jquery.com" );
event.preventDefault();
});
});
```

### Complete Example

The following example illustrates the click handling code discussed above,
embedded directly in the HTML `<body>`. Note that in practice,
it is usually better to place your code in a separate JS file
it is usually better to place your code in a separate JS file
and load it on the page with a `<script>` element's `src` attribute.

```
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Demo</title>
</head>
<body>
<a href="http://jquery.com/">jQuery</a>
<script src="jquery.js"></script>
<script>
$( document ).ready(function() {
$("a").click(function( event ) {
alert("The link will no longer take you to jquery.com");
event.preventDefault();
});
});
</script>
</body>
<head>
<meta charset="utf-8">
<title>Demo</title>
</head>
<body>
<a href="http://jquery.com/">jQuery</a>
<script src="jquery.js"></script>
<script>
$( document ).ready(function() {
$( "a" ).click(function( event ) {
alert( "The link will no longer take you to jquery.com" );
event.preventDefault();
});
});
</script>
</body>
</html>
```

@@ -114,24 +114,24 @@ First, add some style information into the `<head>` of the document, like this:

```
<style>
a.test {
font-weight: bold;
}
a.test {
font-weight: bold;
}
</style>
```

Next, add the [addClass()](http://api.jquery.com/addClass) call to the script:

```
$("a").addClass("test");
$( "a" ).addClass( "test" );
```

All `a` elements are now bold.

To remove an existing `class`, use [removeClass()](http://api.jquery.com/removeClass):

```
$("a").removeClass("test");
$( "a" ).removeClass( "test" );
```

### Special Effects
@@ -141,9 +141,9 @@ to help you make your web sites stand out.
For example, if you create a click handler of:

```
$("a").click(function( event ){
event.preventDefault();
$( this ).hide("slow");
$( "a" ).click(function( event ){
event.preventDefault();
$( this ).hide( "slow" );
});
```

@@ -155,7 +155,7 @@ Unlike many other programming languages, JavaScript enables you to freely pass f
A *callback* is a function that is passed as an argument to another function and
is executed after its parent function has completed. Callbacks are special because
they patiently wait to execute until their parent finishes.
Meanwhile, the browser can be executing other functions or doing all sorts of other work.
Meanwhile, the browser can be executing other functions or doing all sorts of other work.

To use callbacks, it is important to know how to pass them into their parent function.

@@ -172,31 +172,31 @@ When [$.get](http://api.jquery.com/jQuery.get/) finishes getting the page `myhtm

### Callback *with* Arguments

Executing callbacks with arguments can be tricky.
Executing callbacks with arguments can be tricky.

#### Wrong
This code example will ***not*** work:

```
$.get( "myhtmlpage.html", myCallBack(param1, param2) );
$.get( "myhtmlpage.html", myCallBack( param1, param2 ) );
```

The reason this fails is that the code executes `myCallBack( param1, param2 )` immediately
and then passes the myCallBack's *return value* as the second parameter to `$.get`.
We actually want to pass the function `myCallBack`, not `myCallBack( param1, param2)`'s return value
The reason this fails is that the code executes `myCallBack( param1, param2 )` immediately
and then passes myCallBack's *return value* as the second parameter to `$.get`.
We actually want to pass the function `myCallBack`, not `myCallBack( param1, param2 )`'s return value
(which might or might not be a function). So, how to pass in `myCallBack` *and* include its arguments?

#### Right

To defer executing `myCallBack` with its parameters, you can use an anonymous function as a wrapper.
Note the use of `function() {`. The anonymous function does exactly one thing: calls
`myCallBack`, with the values of `param1` and `param2`.
`myCallBack`, with the values of `param1` and `param2`.

```
$.get( "myhtmlpage.html", function() {
myCallBack( param1, param2 );
});
$.get( "myhtmlpage.html", function() {
myCallBack( param1, param2 );
});
```

When `$.get` finishes getting the page `myhtmlpage.html`, it executes the anonymous function,
which executes `myCallBack( param1, param2 )`.
which executes `myCallBack( param1, param2 )`.
16 page/about.md
View file
@@ -1,6 +1,6 @@
---
title: About This Site
customFields:
customFields:
-
key: "is_chapter"
value: 0
@@ -15,7 +15,7 @@ how to do exactly what they need to do.

However, API documentation alone cannot serve as a guide to solving problems
and fostering a true understanding of web development. Over the years, an
ecosystem of blog posts, books, support forums and channels has grown to help
ecosystem of blog posts, books, support forums, and channels has grown to help
cover the **hows** and **whys** of developing with jQuery, as well as explaining
best practices, techniques, and workarounds for common problems. This type of
documentation has been invaluable resource for millions of people, but the
@@ -29,8 +29,8 @@ curate this information in order to provide this crucial "narrative
documentation" to our community and serve the following goals:

1. Provide our **users** with a digestible reference on all aspects of using jQuery, from the basics of getting started and performing common tasks to more advanced topics like approaches to structuring code and where jQuery fits into modern web application development.
2. Provide our **contributors** a central, open place to collaborate and provide a dependable, highly sharable resource that will improve our users' support experiences
3. Foster an environment by which users are encouraged to become contributors and build the skills to help them work on jQuery -- or any other open source project!
2. Provide our **contributors** a central, open place to collaborate and provide a dependable, highly sharable resource that will improve our users' support experiences.
3. Foster an environment by which users are encouraged to become contributors and build the skills to help them work on jQuery — or any other open source project!

In order to achieve these goals, all of [this site's content is maintained
publicly on GitHub](http://github.com/jquery/learn.jquery.com) and is licensed
@@ -53,18 +53,18 @@ for some sort of "learning center."
The second is [docs.jquery.com](http://docs.jquery.com), that erstwhile
chestnut still living out its final days before it will be shut down in early
2013. Since we've moved the API documentation for jQuery Core off that domain,
we needed a place that could serve a similar need -- documentation (that anyone
can contribute to) that gets into the "how-to" and FAQs -- without clumsy
we needed a place that could serve a similar need — documentation (that anyone
can contribute to) that gets into the "how-to" and FAQs — without clumsy
barriers to entry like finding the right person to set you up with a special
wiki account and forcing all authoring into a `textarea`.

<h2><a name="beta">About the Beta</a></h2>
<h2><a name="beta">About the Beta</a></h2>

Though this resource will never truly be "done," the current version of this
site should still be considered something of a preview. We still have a number
of improvements we want to make to the content, user experience, and site build
before we're ready to call it a "final release." At the same time, however,
it's important for us to open the doors now so we can begin providing better
docs to people who need the right away and spread the word about this effort.
docs to people who need them right away and spread the word about this effort.
If you're interested in helping us reach the finish line, we invite you to
please read more about how [you can get involved with contributing](/contributing)!
10 page/ajax.md
View file
@@ -7,14 +7,14 @@ customFields:
value: "refresh"
---

Traditionally webpages required reloading to update their content. For web-based email this meant that users had to manually reload their inbox to check and see if they had new mail. This had huge drawbacks: it was slow and it required user input. When the user reloaded their inbox, the server had to reconstruct the entire web page and resend all of the HTML, CSS, JavaScript, as well as the user's email. This was hugely inefficient. Ideally, the server should only have to send the user's new messages, not the entire page. By 2003 all the major browsers, solved this issue by adopting the XMLHttpRequest (XHR) object, allowing browsers to communicate with the server without requiring a page reload.
Traditionally webpages required reloading to update their content. For web-based email this meant that users had to manually reload their inbox to check and see if they had new mail. This had huge drawbacks: it was slow and it required user input. When the user reloaded their inbox, the server had to reconstruct the entire web page and resend all of the HTML, CSS, JavaScript, as well as the user's email. This was hugely inefficient. Ideally, the server should only have to send the user's new messages, not the entire page. By 2003, all the major browsers solved this issue by adopting the XMLHttpRequest (XHR) object, allowing browsers to communicate with the server without requiring a page reload.

The XMLHttpRequest object is part of a technology called Ajax (Asynchronous JavaScript and XML). Using Ajax, data could then be passed between the browser and the server, using the XMLHttpRequest API, without having to reload the web page. With the widespread adoption of the XMLHttpRequest object it quickly became possible to build web applications like Google Maps, and GMail that used XMLHttpRequest to get new map tiles, or new email without having to reload the entire page.
The XMLHttpRequest object is part of a technology called Ajax (Asynchronous JavaScript and XML). Using Ajax, data could then be passed between the browser and the server, using the XMLHttpRequest API, without having to reload the web page. With the widespread adoption of the XMLHttpRequest object it quickly became possible to build web applications like Google Maps, and Gmail that used XMLHttpRequest to get new map tiles, or new email without having to reload the entire page.

Ajax requests are triggered by JavaScript code; your code sends a request to a URL, and when it receives a response, a callback function can be triggered to handle the response. Because the request is asynchronous, the rest of your code continues to execute while the request is being processed, so it’s imperative that a callback be used to handle the response.
Ajax requests are triggered by JavaScript code; your code sends a request to a URL, and when it receives a response, a callback function can be triggered to handle the response. Because the request is asynchronous, the rest of your code continues to execute while the request is being processed, so it's imperative that a callback be used to handle the response.

Unfortunately, different browsers implement the Ajax API differently. Typically this meant that developers would have to account for all the different browsers to ensure that Ajax would work universally. Fortunately, jQuery provides Ajax support that abstracts away painful browser differences. It offers both a full-featured `$.ajax()` method, and simple convenience methods such as `$.get()`, `$.getScript()`, `$.getJSON()`, `$.post()`, and `$().load()`.

Most jQuery applications don’t in fact use XML, despite the name “Ajax”; instead, they transport data as plain HTML or JSON (JavaScript Object Notation).
Most jQuery applications don't in fact use XML, despite the name "Ajax"; instead, they transport data as plain HTML or JSON (JavaScript Object Notation).

In general, Ajax does not work across domains. For instance, a webpage loaded from example1.com is unable to make an Ajax request to example2.com as it would violate the same origin policy. As a work around, JSONP (JSON with Padding) uses `<script>` tags to load files containing arbitrary JavaScript content and JSON, from another domain. More recently browsers have implemented a technology called Cross-origin resource sharing (CORS), that allows Ajax requests to different domains.
In general, Ajax does not work across domains. For instance, a webpage loaded from example1.com is unable to make an Ajax request to example2.com as it would violate the same origin policy. As a work around, JSONP (JSON with Padding) uses `<script>` tags to load files containing arbitrary JavaScript content and JSON, from another domain. More recently browsers have implemented a technology called Cross-Origin Resource Sharing (CORS), that allows Ajax requests to different domains.