Ajax.JSONRequest is JSONP for Prototype.js

The Basics

Your options are:

• onCreate: When the request is built but before it is invoked
• onSuccess: When the request is completed
• onFailure: When the request times out and fails
• onComplete: When the request is completed, regardless of success or failure
• callbackParamName: The name of the callback query parameter to use (defaults to "callback")
• parameters: Parameters to pass to the request
• timeout: The seconds before canceling the request and invoking onFailure

Handling response content:

The first (and only) argument passed to your response handlers is a Ajax.JSONResponse object. Access the resulting JSON data via that object's responseJSON property or get at the raw JSON string with that object's responseText property.

new Ajax.JSONRequest('http://api.flickr.com/services/feeds/photos_public.gne', {
  callbackParamName: "jsoncallback",
  parameters: {
    tags: 'cat', tagmode: 'any', format: 'json'
  },
  onCreate: function(response) {
    console.log("1: create", response, response.responseJSON);
  },
  onSuccess: function(response) {
    console.log("1: success", response, response.responseJSON);
  },
  onFailure: function(response) {
    console.log("1: fail", response, response.responseJSON);
  },
  onComplete: function(response) {
    console.log("1: complete", response, response.responseJSON);
  }
});

Handling Failures

Since there is no way to inspect what happens after we make a request with the JSONP technique, we're stuck having to make informed guesses about what's going on.

This example makes a request to an invalid URL. Since the callback is not invoked within the default timeout period (10 seconds) the request is "cancelled" and the onFailure callback is invoked if specified. The Ajax.JSONResponse will have the status of 504 and statusText of "Gateway Timeout".

new Ajax.JSONRequest('http://api.flickr.com/services/feeds/asdfasdfasdfasdfasdfsdf', {
  callbackParamName: "jsoncallback",
  parameters: {
    tags: 'cat', tagmode: 'any', format: 'json'
  },
  onCreate: function(response) {
    console.log("2: create", response, response.responseJSON);
  },
  onSuccess: function(response) {
    console.log("2: success", response, response.responseJSON);
  },
  onFailure: function(response) {
    console.log("2: fail", response, response.responseJSON);
  },
  onComplete: function(response) {
    console.log("2: complete", response, response.responseJSON);
  }
});

Using a custom timeout period

You can set your own timeout period. This example sets this timeout to 0.1 seconds which is pretty much guaranteed to fail.

new Ajax.JSONRequest('http://api.flickr.com/services/feeds/photos_public.gne', {

  // Short timeout illustrates failure mechanism. This will "fail" because we don't
  // get a response in time.
  timeout: 0.1,

  callbackParamName: "jsoncallback",
  parameters: {
    tags: 'cat', tagmode: 'any', format: 'json'
  },
  onCreate: function(response) {
    console.log("3: create", response, response.responseJSON);
  },
  onSuccess: function(response) {
    console.log("3: success", response, response.responseJSON);
  },
  onFailure: function(response) {
    console.log("3: fail", response, response.responseJSON);
  },
  onComplete: function(response) {
    console.log("3: complete", response, response.responseJSON);
  }
});

Credits

Ajax.JSONRequest is based on a gist originally posted by Tobie Langel at http://gist.github.com/145466

The version you see here is basically an enhancement on top of that, with most all of the core structure originating from there.