OpenLayers.Request Methods

Background

The XMLHttpRequest constructor provides functionality for transferring data between client and server. The shortcomings with XMLHttpRequest include the following:

• It is not supported in all browsers.
• Where XMLHttpRequest exists, it is not always standard-compliant (W3C).
• It doesn't provide convenience methods to capture the pattern of creating a request, setting headers, dealing with readystatechange, and sending requests.

Our solution

OpenLayers includes a cross-browser XMLHttpRequest function. Around this, we provide convenience methods for issuing requests, setting headers, sending data, and specifying callbacks. The convenience methods are named like the HTTP verbs they support. The examples below demonstrate their use.

Examples

A decent understanding of XMLHttpRequest is nice to have before embarking on web development. With that knowledge, the examples below should make some sense.

Ex. 1: Issue a GET request and deal with the response.

function handler(request) {
    // if the response was XML, try the parsed doc
    alert(request.responseXML);
    // otherwise, you've got the response text
    alert(request.responseText);
    // and don't forget you've got status codes
    alert(request.status);
    // and of course you can get headers
    alert(request.getAllResponseHeaders());
    // etc.
}

var request = OpenLayers.Request.GET({
    url: "http://host/path",
    callback: handler
});

Ex. 2: Issue a GET request with a query string based on key:value pairs.

function handler(request) {
    // do something with the response
    alert(request.responseXML);
}

var request = OpenLayers.Request.GET({
    url: "http://host/path",
    params: {somekey: "some value & this will be encoded properly"},
    callback: handler
});

Ex. 3: Issue a GET request where the handler is a public method on some object.

// assuming obj was constructed earlier
obj.handler = function(request) {
    this.doSomething(request);
}

var request = OpenLayers.Request.GET({
    url: "http://host/path",
    callback: obj.handler,
    scope: obj
});

Ex. 4: Issue a synchronous GET request.

var request = OpenLayers.Request.GET({
    url: "http://host/path",
    async: false
});
// do something with the response
alert(request.responseXML);

Ex. 5: Issue a POST request with some data.

// assuming you already know how to create your handler
var request = OpenLayers.Request.POST({
    url: "http://host/path",
    data: "my data to post",
    callback: handler
});

Ex. 6: Issue a POST request with a custom content type (application/xml is default).

// again assuming you have a handler
var request = OpenLayers.Request.POST({
    url: "http://host/path",
    data: "this is text not xml!",
    headers: {
        "Content-Type": "text/plain"
    },
    callback: handler
});

Ex. 7: Issue a POST request with form-encoded data.

var request = OpenLayers.Request.POST({
    url: "http://host/path",
    data: OpenLayers.Util.getParameterString({foo: "bar"}),
    headers: {
        "Content-Type": "application/x-www-form-urlencoded"
    },
    callback: handler
})

Ex. 8: Issue a GET request and then abort it.

var request = OpenLayers.Request.GET(); // dumb, but possible
request.abort();

Ex. 9: Deal with the many ways that a request can "fail."

function handler(request) {
    // the server could report an error
    if(request.status == 500) {
        // do something to calm the user
    }
    // the server could say you sent too much stuff
    if(request.status == 413) {
        // tell the user to trim their request a bit
    }
    // the browser's parser may have failed
    if(!request.responseXML) {
        // get ready for parsing by hand
    }
    // etc.
}
// issue a request as above

Ex. 10: Issue DELETE, PUT, HEAD, and OPTIONS requests.

// handlers defined elsewhere

var deleteRequest = OpenLayers.Request.DELETE({
    url: "http://host/path",
    callback: deleteHandler
});

var putRequest = OpenLayers.Request.PUT({
    url: "http://host/path",
    callback: putHandler
});

var headRequest = OpenLayers.Request.HEAD({
    url: "http://host/path",
    callback: headHandler
});

var optionsRequest = OpenLayers.Request.OPTIONS({
    url: "http://host/path",
    callback: optionsHandler
});

Ex. 11: (Rare) Issue a GET request using a proxy other than the one specified in OpenLayers.ProxyHost (same origin policy applies).

// handler defined elsewhere
var request == OpenLayers.Request.GET({
    url: "http://host/path",
    params: {somekey: "some value"},
    proxy: "http://sameorigin/proxy?url=" // defaults to OpenLayers.ProxyHost
});