diff --git a/README.md b/README.md index d51d6121..85e03a55 100644 --- a/README.md +++ b/README.md @@ -65,3 +65,8 @@ Code in the API documentation should follow the [jQuery Core Style Guide](http:/ * Authoritive * Tactful +## Referencing Bug Tracker Tickets + +Pull requests suggesting changes to documentation that were requested or recommended via the [jQuery Bug Tracker](http://bugs.jquery.com) should include a link back to the relevant bug ticket. Should a `#needsdocs` item be addressed here, the tag should be removed from the bug ticket to ensure the backlog is kept up to date. + + diff --git a/entries/jQuery.ajax.xml b/entries/jQuery.ajax.xml index 8c7e206c..b79ddd4e 100644 --- a/entries/jQuery.ajax.xml +++ b/entries/jQuery.ajax.xml @@ -282,6 +282,47 @@ jQuery.ajaxSettings.xhr = function () { }; + +

Using Converters

+ +

$.ajax() converters support mapping data types to other data types. If however we want to map a custom data type to a known type (e.g json), a correspondance must be added between the response Content-Type and actual data type using the contents option:

+ +
+$.ajaxSetup({
+    contents: {
+        mycustomtype: /mycustomtype/
+    },
+    converters: {
+        "mycustomtype json": function ( result ) {
+            // do stuff
+            return newresult;
+        }
+    }
+});
+
+ +

The reason we use another map for this is because the response Content-Types and data types never have a strict one-to-one correspondance (hence the regular expression).

+ +

If converting from a supported type (e.g text, json) to a custom data type and back again is desired, another pass-through converter can be used on top of this:

+ +
+$.ajaxSetup({
+    contents: {
+        mycustomtype: /mycustomtype/
+    },
+    converters: {
+        "text mycustomtype": true,
+        "mycustomtype json": function ( result ) {
+            // do stuff
+            return newresult;
+        }
+    }
+});
+
+ +

The above now allows passing from text to mycustomtype and then mycustomtype to json.

+ +

Extending Ajax

As of jQuery 1.5, jQuery's Ajax implementation includes prefilters, converters, and transports that allow you to extend Ajax with a great deal of flexibility. For more information about these advanced features, see the Extending Ajax page.