API.md

API

jQuery.jsonp( options )

Overview

Loads a remote JSON object using a JSONP request.

$.jsonp() returns the extended options (the xOptions object) for the query (that is an object containing all the options passed to the function plus defaults for those not provided). In most cases you won't need xOptions to manipulate directly, but it is available if you need to abort the request manually (xOptions provides an abort() method to that end).

As of version 2.3.0, if you use jQuery-JSONP with jQuery 1.5+, the xOptions object is a Promise. See jQuery's documentation for more information on Promises and Deferreds.

$.jsonp() takes one argument, an object of key/value pairs, that are used to initialize and handle the request. All options are optional. A default can be set for any option with $.jsonp.setup(). See below for a full list of the key/values that can be used.

Options

beforeSend - function (undefined)

A function called before the request is even performed. You may return false in the callback to cancel the request.

function (xOptions) {
  this; // the xOptions object or xOptions.context if provided
}

cache - boolean (false)

If set to false it will force the data that you request not to be cached by the browser, unless the pageCache option is set to true.

callback - string ("_jqjsp")

Name of the JSONP callback as provided in the request url. Most of the time, you won't have to change this value but some JSONP providers have a predefined callback name that cannot be overidden. Set the name of said callback in the callback option and $.jsonp will catch the call.

As of version 2.0, the library defines a function for the callback in the global scope, so it is no longer safe to use the name of a function already defined: said function will be redefined by jQuery-JSONP.

On the other hand, it is still perfectly safe to have several concurrent requests using the same callback name: in that case, jQuery-JSONP ensures no collision occurs internally.

callbackParameter - string (undefined)

as of version 1.0.1

If provided, specifies the name of the url parameter that conveys the callback name to the service.

Example:

$.jsonp({
  url: "http://service.org/path?param1=xx&param2=xx",
  callbackParameter: "callback"
});

is strictly equivalent to:

$.jsonp({
  url: "http://service.org/path?param1=xx&param2=xx&callback=?"
});

charset - string (undefined)

as of version 2.1.1

Forces the request to be interpreted as a certain charset. Only needed for charset differences between the remote and local content.

complete - function (undefined)

A function to be called when the request finishes (after success and error callbacks are executed). The function gets passed two arguments: The xOptions object and a string describing the type of completion of the request ("success", "error" or "timeout").

function (xOptions, textStatus) {
  this; // the xOptions object or xOptions.context if provided
}

context - object (undefined)

as of version 2.1.1

This object will be made the context of all xOptions-related callbacks. For example specifying a DOM element as the context will make it the context for the complete callback of a request, like so:

$.jsonp({
  url: "test.php?callback=?",
  context: document.body,
  complete: function() {
    $(this).addClass("done");
  }
});

data - object | string (undefined)

Data to be sent to the server. It is converted to a query string, if not already a string, and then appended to the url. Object must be key/value pairs. If value is an array, jQuery serializes multiple values with same key i.e. { foo: [ "bar1", "bar2" ] } becomes "&foo=bar1&foo=bar2".

dataFilter - function (undefined)

A function to be used to handle the raw responsed JSON object. This is a pre-filtering function to sanitize the response. You should return the sanitized data. The function gets one argument: The raw JSON object returned from the server.

function (json) {
  // do something
  // return the sanitized json
  return json;
}

error - function (undefined)

A function to be called if the request fails. The function is passed two arguments: The xOptions object and a string describing the type of error that occurred. Possible values for the second argument are "error" (the request finished but the JSONP callback was not called) or "timeout".

function (xOptions, textStatus) {
  this; // the xOptions object or xOptions.context if provided
}

pageCache - boolean (false)

If set to true, will override the cache option and provide a page based caching of the result of the request. Whenever another request is made later on with pageCache set to true and with options inducing the exact same final url for the request, the cached response is used and no distant call is actually made.

Lifetime of this cache is page-based which means it gets erased at each page reload.

success - function (undefined)

A function to be called if the request succeeds. The function gets passed three arguments: The JSON object returned from the server, a string describing the status (always "success") and, as of version 2.4.0 the xOptions object.

function (json, textStatus, xOptions) {
  this; // the xOptions object or xOptions.context if provided
}

timeout - number (0)

If greater than 0, sets a local timeout (in milliseconds) for the request. This will override the global timeout, if one is set via $.jsonp.setup. For example, you could use this property to give a single request a longer timeout than all other requests that you've set to time out in one second.

traditional - boolean (false)

as of version 2.0.2

Set this to true if you wish to use the traditional style of param serialization.

url - string (location.href)

The URL to request. If more than one ? character is found in the url, the latest will be replaced by the value of the callback option. Note that, given this rule, no valid url can have more than two ? characters.

jQuery.jsonp.setup( options )

Overview

Setup global settings for JSONP requests.

Options

See $.jsonp for a description of all available options.