Xhr

Xhr is the standard XmlHTTPRequest handler for RightJS.

Options

Xhr objects support the following options:

NameDefaultDescription
method‘post’request method (get/post/put/delete)
encoding‘utf-8’encoding
asynctrueasynchronous request
evalScriptsfalseextract/eval JavaScripts from the response
evalResponsefalseeval response as JavaScript code
evalJSONtrueeval JSON responses automatically
secureJSONtrueshould JSON responses be validated?
urlEncodedtrueurlencode the parameters
spinnernullcommon spinner element
spinnerFx‘fade’fx name to show/hide the spinner
paramsnulldefault parameters

Any of the options can be set globally by altering the Options object or be passed along with any Xhr functionality interface.

Spinners

The Xhr class in RightJS handles the spinners automatically. You can specify them as an element object instance or as an element-id.

Xhr.Options.spinner = $('spinner');

// now the spinner element will appear before the request
// and automatically get hidden on complete or cancel
new Xhr('/foo/bar').send();

// in this case Xhr will process both the global and custom spinners
new Xhr('/foo/bar', {
spinner: 'custom-spinner'
}).send();

Parameters

You can send custom parameters with XHR requests. Specify them either as a url-encoded string or as an object.

There are three different levels.

You can specify global params, which will be sent with all subsequent XHR requests:

Xhr.Options.params = 'myapp=true';

// will send 'myapp=true' params with any following requests.
Xhr.load('/foo/bar');

new Xhr('/foo/bar').send();

You can specify per-request parameters by sending them as constructor options:

var xhr = new Xhr('/foo/bar', {
params: {myapp: true}
});

xhr.send(); // the server will see the 'myapp=true' params

And you can specify the per-send params using of the send method:

var xhr = new Xhr('/foo/bar').send('myapp=true');

NOTE: If you specify params on several levels, they will be merged into a single hash once a request is being made.

Events

The RightJS Xhr class is inherited from the standard Observer class, which means that Xhr instances follow all the standard observer rules. You can add, list and remove event handlers the usual way.

The Xhr class supports the following events:

NameDescription
createafter the XmlHTTPRequest object has been instanciated
requestafter the request has been sent
completeafter the request has completed (either successfully or not)
successafter the request bas completed successfully
failureafter the request has failed
cancelafter the request has been canceled manually

NOTE: Every callback will receive two arguments. The first one is the request instance and the second one is the actual original request instance.

You can attach listeners to these events globally as well as using the Xhr class level observers:

Xhr.onCreate(function() {...});
Xhr.onFailure(function() {...});

In this case Xhr will call your listeners on every XHR request.

JSON handling

If the option evalJSON is true, Xhr will try to evaluate responses that come with a JSON content-type and assign the result to the responseJSON property.

Xhr.load('/some.json', {
onSuccess: function(request) {
var json = request.responseJSON;

// ....
}
});

Short Response Names

To access the server responses use either the standard names responseText, responseXML, responseJSON or any of the shortified names:

  • this.text -> this.responseText
  • this.xml -> this.responseXML
  • this.json -> this.responseJSON

Methods

Options, load, initialize, cancel, getHeader, send, setHeader, successful, update

top ↑Options

Xhr.Options -> Object

Description

Default Xhr options, see the options chapter above for more details.

Example

Xhr.load('/some/url'); // -> 'post' request

Xhr.Options.method = 'get';

Xhr.load('/some/url'); // -> 'get' request

top ↑load

Xhr.load(String url[, Object options]) -> Xhr new

Description

Shortcut for new Xhr(url, options).send(); which creates a new XHR request instance and sends it.

NOTE: Will perform a GET request by default.

Example

Xhr.load('/some/url', {
onSuccess: function(request) {
// do something about it
}
});

top ↑initialize

initialize(String url[, Object options]) -> Xhr new

Description

Standard constructor. The second argument is an options hash with any of the standard keys.

Example

var xhr = new Xhr('/some/url');
var xhr = new Xhr('/some/url', {
method: 'get',
onSuccess: some_success_handler
});

top ↑cancel

cancel() -> Xhr self

Description

Cancels an active request.

Example

var xhr = new Xhr('/foo/bar');
xhr.send();

xhr.cancel();

top ↑getHeader

getHeader(String name) -> String value

Description

Reads the response headers.

Example

var xhr = new Xhr('/foo/bar');
xhr.send();
// ...
xhr.getHeader('Content-type');

top ↑send

send([String params]) -> Xhr self
send([Object params]) -> Xhr self
send([Form element]) -> Xhr self

Description

Sends the request to the server.

Example

var xhr = new Xhr('/foo/bar');
xhr.send();

// or

xhr.send('foo=bar&moo=boo');

// or

xhr.send({foo: 'bar'});

top ↑setHeader

setHeader(String name, String value) -> Xhr self

Description

Setter for additional headers which should be sent along with the request.

Example

var xhr = new Xhr('/some/url');
xhr.setHeader('Content-type', 'application/x-www-form-urlencoded');

top ↑successful

successful() -> boolean

Description

Checks if the request has completed with a successful status.

Example

var xhr = new Xhr('/foo/bar', {
onComplete: function(request) {
if (request.successful()) {
// do something
}
}
}).send();

top ↑update

update(Element element[, mixed params]) -> Xhr self
update(String element_id[, mixed params]) -> Xhr self

Description

Sends the request and then updates the given element with the result of the request.

Example

var xhr = new Xhr('/foo/bar');

xhr.update(element);
xhr.update('element-id');
xhr.udpate(element, 'foo=bar');
xhr.udpate(element, {foo: 'bar'});