SilverAjax Documentation

About

This is the documentation for Silverajax

Creating a new Silverajax object

To create a new Silverajax object, just use the "new" keyword and pass the desired options like this:

var myAjax = new Silverajax(url, {options});

The parameters

url

A string, The url where to send the request

options

An object, a set of options (described below)

The options

method
Type: string
Default: 'GET'
Description: The method to use when sending the request, eighter 'POST' or 'GET'

timeout
Type: number
Default: 5000
Description: The amount of milliseconds to let the request run, after which it will be aborted and the onCancel event will be fired…

update
Type: string or object
Default: empty string ('')
Description: The element to update with the response text. If it's a string, document.getElementById will be used to retrieve the element, if it's an object, the script will assume it's an element and assing the response to it's innerHTML property.

expectJson
Type: boolean
Default: false
Description: Set to true if you expect a json response and you want to evaluate it. The evaluated response will be stored into response.responseJson as a javascript object.

expectJavascript
Type: boolean
Default: false
Description: For now this will only evaluate the response… it's not so safe and it will be secured eventually…

encoding
Type: string
Default: 'utf-8'
Description: The encoding to use for POST requests

headers
Type: object
Description: The headers to use for the request. You shouldn't have to mess with this one, you can use the addHeader method instead.
Default:

headers = {
    'X-Requested-With': 'XMLHttpRequest',
    'Accept': 'text/javascript, text/html, application/xml, text/xml, */*'
}

Useful Methods

send(data)

Parameters

data

string The data to send in a query string format (no ?) for example: 'id=0&action=delete'

Description

This method performs the request and sends the data passed in as a parameter (works for both GET and POST requests)

Example

myAjax.send('id=1&action=delete');

addHeader(key, value)

Parameters

key

string The header name

value

string The value for that header

Description

This method adds a header to the request

Example

myAjax.addHeader('Accept', 'text/javascript);

deleteHeader(key)

Parameters

key

string Which header to delete

Description

This method removes a header from the request

Example

myAjax.deleteHeader('Accept');

abort()

Description
Aborts the current request.

Example

myAjax.abort();

Pseudo-Events

Well, I call them pseudo-events because those aren't DOM Events, but overridable functions that will be called when certain events occurs.

onComplete(resp)

Is called when the request is completed, no matter if it was a failure or a success. If you want to hide your little ajax indicator image, this is where you can do it…

onSuccess(resp)

Is called when the request was a success (status code === 200). A custom response object is passed to the function (see below for the response object's description)

onFailure(resp)

Is called when the request failed (status code !== 200). A custom response object is passed to the function (see below for the response object's description)

onTimeout()

Is called when the request timed out (according to the timeout option).

Custom Response Object

Both the onTimeout and onFailure methods will be called with a custom response object, this is what this object is made of (with example values):

response = {
    status: 200,
    statusText: 'OK',
    responseText: '{"firstname": "Jean-Nicolas", "lastname": "Jolivet"}',
    responseXml: null,
    responseJson: {firstname: "Jean-Nicolas", lastname: "Jolivet"}
}

So, to sum it up:

status

The numeric status code of the request

statusText

The statusText of the request

responseText

The textual response of the request

responseXml

The XML response of the request (if the response was an XML document)

responseJson

The evaluated JSON response (if options.expectJson was set to true)

Catching Events Example

This is a quick example of how you can catch the various events

// Create a Silverajax object first
var myAjax = new Silverajax('getinfo.php', {
    method: 'GET',     // Send a GET request
    expectJson: true    // We expect a json response (ex: {"firstname": "Jean-Nicolas", "lastname": "Jolivet"})
});
 
// Override the onSuccess method, making sure to accept the response parameter
myAjax.onSuccess = function(resp) {
    // Assign a property of the responseJson object to an element in my page...
    document.getElementById('myDiv').innerHTML = resp.responseJson.firstname;
}
// Send the actual request..
myAjax.send('person_id=2');