jQuery.ajax how to use contents property

Question

Can anyone give me an example on how to use the contents property?

$.ajax(
{
   contents : {...}
}

jQuery's own documentation only states the following about it:

contents

An object of string/regular-expression pairs that determine how jQuery will parse the response, given its content type

Answer 1

From http://api.jquery.com/jQuery.ajax/ :

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

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

So, what this means is your server response's data-type could be mycustomtype. And when the AJAX call receives the data, it'll see that its data-type is mycustomtype and matches the regex we have set (in contents): /mycustomtype/ and throws the data into the converter we specified, eg. mycustomtype json() will attempt to convert the data into json.

To elaborate on the converters:

The converters["mycustomtype json"] means that the function specified here will be executed when you want to convert mycustomtype into json format, so the contents of that function will perform the parsing that will return JSON. You can specify other conversion types eg.

converters: {
    "mycustomtype json": converterFromCustomTypeToJson,      // mycustomtype -> json
    "mycustomtype jsonp": converterFromCustomTypeToJsonP,    // mycustomtype -> jsonp
    "mycustomtype text": converterFromCustomTypeToText,      // mycustomtype -> text 
    "text mycustomtype": converterFromTextToCustomType       // text -> mycustomtype 
}

And you would write your own converter functions:

var converterFromCustomTypeToJson = function(result) {
        var jsonResult = ...
        /* do conversion to JSON */
        return jsonResult;
    },
    converterFromCustomTypeToJsonP = function(result) {
        var jsonPResult = ...
        /* do conversion to JSONP */
        return jsonPResult;
    },
    converterFromCustomTypeToText = function(result) {
        var textResult = ...
        /* do conversion to text */
        return textResult;
    },
    converterFromTextToCustomType = function(result) {
        var customResult = ...
        /* do conversion to mycustomtype */
        return customResult;
    };

You'd also want to avoid messing with the default converters, they are:

{
    "* text": window.String, 
    "text html": true, 
    "text json": jQuery.parseJSON, 
    "text xml": jQuery.parseXML
}

Answer 2

The contents is used to define new dataTypes. There are 4 default data types defined in jQuery: xml, json, script, and html. If the dqataType is not specified for ajax call, jQuery will try to infer it based on the MIME type of the response. When defining new data type using contents, a regex expression need to be specified, which will be used to infer the custom dataType from the MIME type of the response.

For ex to define a CSV dataType which otherwise will be parsed as text:

$.ajaxSetup({
  // for: text/csv or application/csv
  contents: {
    csv: /csv/
  }
});

contents is used in conjunction with converters:

To transform csv into json define a custom converter:

$.ajaxSetup({
  contents: {
    csv: /csv/
  },
  converters: {
    "csv json": function (result) {
      // parse csv here
      return jsonresult;
    }
  }
});