OpenLayers OpenLayers

Table Of Contents

Previous topic

Deploying (Shipping OpenLayers in your Application)

Next topic

Spherical Mercator

This Page

Requesting Remote Data

There are a number of ways to get data from the server to the client. Setting image, script, and stylesheet sources can be done at any time to request new data without refreshing an entire document. These types of requests can be made to any origin. Another way to retrieve data from a server is to update the location of a document in a frame (iframe or otherwise). These types of requests can also be made to any origin. However, the code running in the original document is restricted to reading data in documents that come from the same origin. This means if your application is served from http://example.com, your code may load a document in a frame from any other origin (say http://example.net), but your code can only access data in that document if it was served via the same protocol (http), from the same domain (example.com), and on the same port (likely 80 in this case).

The above types of request are useful because they are asynchonous. That is, the user can continue to view and interact with the original page while additional data is being requested. A more common way to request data asynchronously is to use the XMLHttpRequst object. With an XMLHttpRequest object, you can open a conection to a server and send or receive data via HTTP (or HTTPS). XMLHttpRequest objects are a bit awkward to use and are unfortunately not supported in all browsers. OpenLayers provides a cross-browser XMLHttpRequest function and wraps it in some convenient OpenLayers.Request methods.

In general, all communication initiated by OpenLayers.Request methods is restricted to the same origin policy: requests may only be issued with the same protocol, to the same domain, and through the same port as the document the code is running from. The OpenLayers.Request methods allow you to access data asynchronously or synchronously (synchronous requests will lock the UI while the request is pending).

Note

Though you may read about cross-domain Ajax, unless a user has specifically configured their browser’s security settings, the same origin policy will apply to requests with XMLHttpRequest. The “cross-domain” functionality is typically achieved by either setting up a proxy (on the same origin) that passes on all communication to a remote server or by requesting data without the XMLHttpRequest object (in a script tag for example). One nuance of the same origin policy is that code running on a page from one domain may set the document.domain property to a suffix of the original domain. This means that code running on a document from sub.example.com may request data from example.com by setting document.domain to example.com. A document from example.com, however, cannot prefix the domain property to request data from a sub domain.

The OpenLayers.Request methods correspond to the common HTTP verbs: GET, POST, PUT, DELETE, HEAD, and OPTIONS. See the Request API documentation for a description of each of these methods. The short examples below demonstrate the use of these methods under a variety of conditions.

Example usage

  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
});
  1. 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
});
  1. 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
});
  1. Issue a synchronous GET request.
var request = OpenLayers.Request.GET({
    url: "http://host/path",
    async: false
});
// do something with the response
alert(request.responseXML);
  1. 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
});
  1. 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
});
  1. 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
})
  1. Issue a GET request and then abort it.
var request = OpenLayers.Request.GET(); // dumb, but possible
request.abort();
  1. 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
  1. 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
});
  1. (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
});