Ajax Docs

The Ajax library provides a uniform API across the various browsers for XMLHttpRequest-type client-server requests.

API

isSupported()

Attempts to create a new XMLHttpRequest object. If successful returns true. Otherwise false.

Examples

if (FORK.Ajax.isSupported()) {
  new FORK.Ajax('GET', '/foo');
} else {
  alert('Your browser is not capable of Ajax.');
}




setButton(element)

Enables the button clicked to initiate a form submission to be serialized with the other form data and submitted with an Ajax form submission.


  element
  the button element


Examples
  
<form method="post"
      action="http://example.com/fallback/url"
      onclick="new FORK.Ajax('post', 'http://example.com/ajax/submit/url', {form:this});return false;">
      
  <p><input type="text" name="username"></p>
  <p><input type="submit" onclick="FORK.Ajax.setButton(this);" name="button" value="login"></p>
  <p><input type="submit" onclick="FORK.Ajax.setButton(this);" name="button" value="buy"></p>
</form>



new FORK.Ajax(method, url, options)

Make and Ajax request to the server. This constructor function returns a JavaScript object with two properties of interest. One property is called request and is the XMLHttpRequest object provided by the browser. The other property is abort() which is a function that can abort the Ajax request.


  method
  A string for the method for the request. This will be either "GET" or "POST". With Rails 1.2 applications using REST routes the method may also be "PUT" or "DELETE".
  
  url
  A string. Where the request will be sent. If using this library with Rails, use the file extension to specify the format. For example, if you want a JavaScript response send to a url like "http://example.com/somewhere.js". This technique was introduced in Rails 1.2 instead of depending on the 'Accepts' header automatically set by this Ajax library. The Accepts header technique may be deprecated some day.
  
  options
  an object. An optional argument. If included, the options object can have any number of the options listed below. The use of any particular option does not require the use of any other option. However some options have interactions.


options

The most commonly used options will likely be


 form
 on200
 onComplete
 scope



form
A form element or the name or id attribute of the form to be submitted. You will likely be submitting forms with a POST request but a form can be submitted with any method. In the case of a GET request, the form values are added to the URL. For other methods, the form values are the body of the request. A form submitted through this library cannot include a file upload.

headers

The headers option is an object. Each header property is added to request. The property name is the header name and the property value is the header value. For example, the headers options may be something like {"Accept-Encoding": "x-compress; x-zip"}



body

The body option is an object. It is a set of parameters to be added to the URL in the case of a GET request or to be added to the body of requests with other methods. For example, the body options may be something like {foo:"asdf",poiu:7}


If the request is a form submission then the body parameters are appended to the URL or body after the form parameters. Make sure that the parameter names of the form elements do not collide. There is no checking if they do collide but this situation is not likely to occur.


argument

The argument can be a primitive or an object (and therefore an array or function as these are objects in JavaScript). Using an object as a hash will likely be the most common argument.


The argument is available in the callback methods described below as o.argument. This gives the call to new FORK.Ajax a way to pass data to the callbacks.


before

A callback that executes before any of the other callbacks. This could be used to turn off a throbber. This could also be used to mangle the response before one of the other callbacks handles the response. This callback will execute even if the request times out or the response is JavaScript to be automatically eval'ed.


timeout

The number of milliseconds after which the request is aborted.


onTimeout

The callback that executes when the request times out as specified by the timeout option. Without the timeout option this will never execute.



on200, on305, on 501 etc

The callback that executes when a particular status code is returned by the server.


onSuccess

If the status code of the response is in the range [200, 300) and a corresponding on*** callback didn't exist then onSuccess will be called. Don't use this. It is better to use the on*** and onComplete callbacks.


onFailure

If the status code of the response is outside the range [200, 300) and a corresponding on*** callback didn't exist then onFailure will be called. Don't use this. It is better to use the on*** and onComplete callbacks.


onComplete

If onComplete exists and none of the other "on" callbacks applied to the response status code then onComplete will be called.


after

A callback that executes after the other callbacks. This is a perfect place to use setTimeout() to call new FORK.Ajax() again and create a polling of the server. This callback will execute even if the request times out or the response is JavaScript to be automatically eval'ed.


scope

The object that is given as the value of this option will be the value of this when the callback functions execute.


Callback Arguments

The callback functions are passed the XMLHttpRequest object as their first argument. If the argument option was specified then it is passed as the second argument to the callbacks.


Examples

Here is an example of almost every possible option that can be passed to the new FORK.Ajax function.

new FORK.Ajax("POST",
                  "http://www.freecause.com/blah.pl",
                  {form: document.theForm,
                   body: {asdf:43s, fff:844},
                   argument: {foo:"bar"},
                   before: function(o){},
                   timeout: 5000,
                   onTimeout: function(o){},
                   on200: function(o){},
                   on305: function(o){},
                   onSuccess: function(o){},
                   onFailure: function(o){},
                   onComplete: function(o){},
                   after: function(o){},
                   scope: object});

Credits

Influenced by David Flanagan's JavaScript: The Definitive Guide Chapter 20, Yahoo! UI connection library, Matt Kruse's AjaxToolbox form serialization, Prototype Ajax API,  and Richard Cornford's reply about the IE memory leak