Add first four sections of ajax

Author: danheberden

content/jquery-fundamentals/ajax/ajax-and-forms.md

@@ -0,0 +1,29 @@
+---
+chapter : ajax
+section : 4
+title   : Ajax and Forms
+attribution:  jQuery Fundamentals
+---
+## Ajax and Forms
+
+jQuery’s ajax capabilities can be especially useful when dealing with forms. 
+The [jQuery Form Plugin](http://jquery.malsup.com/form/) 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 `$.fn.serializeArray`.
+
+<div class="example" markdown="1">
+Turning form data into a query string
+
+    $('#myForm').serialize();
+</div>
+
+<div class="example" markdown="1">
+Creating an array of objects containing form data
+
+    $('#myForm').serializeArray();
+    
+    // creates a structure like this:
+    [
+        { name : 'field1', value : 123 },
+        { name : 'field2', value : 'hello world' }
+    ]
+</div>

content/jquery-fundamentals/ajax/ajax-overview.md

@@ -0,0 +1,21 @@
+---
+chapter : ajax
+section : 1
+title   : Overview
+attribution:  jQuery Fundamentals
+---
+## Overview
+
+The XMLHttpRequest method (XHR) allows browsers to communicate with the server without requiring a page reload. 
+This method, also known as Ajax (Asynchronous JavaScript and XML), allows for web pages that provide rich, interactive experiences.
+
+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.
+
+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).
+
+In general, Ajax does not work across domains. 
+Exceptions are services that provide JSONP (JSON with Padding) support, which allow limited cross-domain functionality.

content/jquery-fundamentals/ajax/jquery-ajax-methods.md

@@ -0,0 +1,200 @@
+---
+chapter : ajax
+section : 3
+title   : jQuery's Ajax-Related Methods
+attribution:  jQuery Fundamentals
+---
+## jQuery's Ajax-Related Methods
+
+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.
+
+### `$.ajax`
+
+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 [http://api.jquery.com/jQuery.ajax/](http://api.jquery.com/jQuery.ajax/ "$.ajax documentation on api.jquery.com").
+
+<div class="example" markdown="1">
+Using the core `$.ajax` method
+
+    $.ajax({
+        // the URL for the request
+        url : 'post.php',
+    
+        // the data to send
+        // (will be converted to a query string)
+        data : { id : 123 },
+    
+        // whether this is a POST or GET request
+        type : 'GET',
+    
+        // the type of data we expect back
+        dataType : 'json',
+    
+        // code to run if the request succeeds;
+        // the response is passed to the function
+        success : function(json) {
+            $('&lt;h1/>').text(json.title).appendTo('body');
+            $('&lt;div class="content"/>')
+                .html(json.html).appendTo('body');
+        },
+        
+        // code to run if the request fails;
+        // the raw request and status codes are
+        // passed to the function
+        error : function(xhr, status) {
+            alert('Sorry, there was a problem!');
+        },
+    
+        // code to run regardless of success or failure
+        complete : function(xhr, status) {
+            alert('The request is complete!');
+        }
+    });
+</div>
+
+<div class="note" markdown="1">
+### Note
+
+A note about the dataType setting: if the server sends back data that is in a different format than you specify, your code may fail, and the reason will not always be clear, because the HTTP response code will not show an error. 
+When working with Ajax requests, make sure your server is sending back the data type you're asking for, and verify that the Content-type header is accurate for the data type. 
+For example, for JSON data, the Content-type header should be `application/json`.
+</div>
+
+### `$.ajax` Options
+
+There are many, many options for the `$.ajax` method, which is part of its power. 
+For a complete list of options, visit [http://api.jquery.com/jQuery.ajax/](http://api.jquery.com/jQuery.ajax/ "$.ajax documentation on api.jquery.com"); here are several that you will use frequently:
+
+#### async
+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.
+
+#### cache
+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.
+
+#### complete
+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.
+
+#### context
+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 `$.ajax`.
+
+#### data
+The data to be sent to the server. This can either be an object or a query string, such as `foo=bar&amp;baz=bim`.
+
+#### dataType
+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.
+
+#### error
+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.
+
+#### jsonp
+The callback name to send in a query string when making a JSONP request. Defaults to "callback".
+
+#### success
+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.
+
+#### timeout
+The time in milliseconds to wait before considering the request a failure.
+
+#### traditional
+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/](http://api.jquery.com/jQuery.param/ "$.param documentation on api.jquery.com").
+
+#### type
+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.
+
+#### url
+The URL for the request.
+
+The `url` option is the only required property of the `$.ajax` configuration object; all other properties are optional. This can also be passed as the first argument to $.ajax, and the options object as the second argument.
+
+### Convenience Methods
+
+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:
+
+#### $.get
+Perform a GET request to the provided URL.
+
+#### $.post
+Perform a POST request to the provided URL.
+
+#### $.getScript
+Add a script to the page.
+
+#### $.getJSON
+Perform a GET request, and expect JSON to be returned.
+
+In each case, the methods take the following arguments, in order:
+
+#### url
+The URL for the request. Required.
+
+#### data
+The data to be sent to the server. Optional. This can either be an object or a query string, such as `foo=bar&amp;baz=bim`.
+
+<div class="note" markdown="1">
+### Note
+
+This option is not valid for `$.getScript`.
+</div>
+
+#### success callback
+A callback function to run if the request succeeds. Optional. The function receives the response data (converted to a JavaScript object if the data type was JSON), as well as the text status of the request and the raw request object.
+
+#### data type
+The type of data you expect back from the server. Optional.
+
+<div class="note" markdown="1">
+### Note
+
+This option is only applicable for methods that don't already specify the data type in their name.
+</div>
+
+<div class="example" markdown="1">
+Using jQuery's Ajax convenience methods
+
+    // get plain text or html
+    $.get('/users.php', { userId : 1234 }, function(resp) {
+        console.log(resp);
+    });
+    
+    // add a script to the page, then run a function defined in it
+    $.getScript('/static/js/myScript.js', function() {
+        functionFromMyScript();
+    });
+    
+    // get JSON-formatted data from the server
+    $.getJSON('/details.php', function(resp) {
+        $.each(resp, function(k, v) {
+            console.log(k + ' : ' + v);
+        });
+    });
+</div>
+
+### `$.fn.load`
+
+The `$.fn.load` method is unique among jQuery’s Ajax methods in that it is called on a selection. 
+The `$.fn.load` method fetches HTML from a URL, and uses the returned HTML to populate the selected element(s). 
+In addition to providing a URL to the method, you can optionally provide a selector; jQuery will fetch only the matching content from the returned HTML.
+
+<div class="example" markdown="1">
+Using `$.fn.load` to populate an element
+
+    $('#newContent').load('/foo.html');
+</div>
+
+<div class="example" markdown="1">
+Using `$.fn.load` to populate an element based on a selector
+
+    $('#newContent').load('/foo.html #myDiv h1:first', function(html) {
+      alert('Content updated!');
+    });
+</div>

content/jquery-fundamentals/ajax/key-concepts.md

@@ -0,0 +1,87 @@
+---
+chapter : ajax
+section : 2
+title   : Key Concepts
+attribution:  jQuery Fundamentals
+---
+## Key Concepts
+
+Proper use of Ajax-related jQuery methods requires understanding some key concepts first.
+
+### GET vs. Post
+
+The two most common “methods” for sending a request to a server are GET and POST. 
+It’s important to understand the proper application of each.
+
+The GET method should be used for non-destructive operations — that is, operations where you are only “getting” data from the server, not changing data on the server. 
+For example, a query to a search service might be a GET request. 
+GET requests may be cached by the browser, which can lead to unpredictable behavior if you are not expecting it. 
+GET requests generally send all of their data in a query string.
+
+The POST method should be used for destructive operations — that is, operations where you are changing data on the server. 
+For example, a user saving a blog post should be a POST request. 
+POST requests are generally not cached by the browser; a query string can be part of the URL, but the data tends to be sent separately as post data.
+
+### Data Types
+
+jQuery generally requires some instruction as to the type of data you expect to get back from an Ajax request; in some cases the data type is specified by the method name, and in other cases it is provided as part of a configuration object. There are several options:
+
+#### text
+For transporting simple strings
+
+#### html
+For transporting blocks of HTML to be placed on the page
+
+#### script
+For adding a new script to the page
+
+#### json
+For transporting JSON-formatted data, which can include strings, arrays, and objects
+	
+<div class="note" markdown="1">
+### Note
+
+As of jQuery 1.4, if the JSON data sent by your server isn't properly formatted, the request may fail silently. 
+See [http://json.org](http://json.org) for details on properly formatting JSON, but as a general rule, use built-in language methods for generating JSON on the server to avoid syntax issues.
+
+#### jsonp
+For transporting JSON data from another domain
+
+#### xml
+For transporting data in a custom XML schema
+
+I am a strong proponent of using the JSON format in most cases, as it provides the most flexibility. It is especially useful for sending both HTML and data at the same time.
+
+### A is for Asynchronous
+
+The asynchronicity of Ajax catches many new jQuery users off guard. 
+Because Ajax calls are asynchronous by default, the response is not immediately available. 
+Responses can only be handled using a callback. 
+So, for example, the following code will not work:
+
+<div class="example" markdown="1">
+    var response;
+    $.get('foo.php', function(r) { response = r; });
+    console.log(response); // undefined!
+</div>
+
+Instead, we need to pass a callback function to our request; 
+this callback will run when the request succeeds, at which point we can access the data that it returned, if any.
+
+<div class="example" markdown="1">
+    $.get('foo.php', function(response) { console.log(response); });
+</div>
+
+### Same-Origin Policy and JSONP
+
+In general, Ajax requests are limited to the same protocol (http or https), the same port, and the same domain as the page making the request. 
+This limitation does not apply to scripts that are loaded via jQuery's Ajax methods.
+
+The other exception is requests targeted at a JSONP service on another domain. 
+In the case of JSONP, the provider of the service has agreed to respond to your request with a script that can be loaded into the page using a `&lt;script>` tag, thus avoiding the same-origin limitation; that script will include the data you requested, wrapped in a callback function you provide.
+
+### Ajax and Firebug
+
+Firebug (or the Webkit Inspector in Chrome or Safari) is an invaluable tool for working with Ajax requests. 
+You can see Ajax requests as they happen in the Console tab of Firebug (and in the Resources > XHR panel of Webkit Inspector), and you can click on a request to expand it and see details such as the request headers, response headers, response content, and more. 
+If something isn't going as expected with an Ajax request, this is the first place to look to track down what's wrong.