1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the Clear BSD
2 * license. See http://svn.openlayers.org/trunk/openlayers/license.txt for the
3 * full text of the license. */
6 * @requires OpenLayers/Events.js
10 * Namespace: OpenLayers.Request
11 * The OpenLayers.Request namespace contains convenience methods for working
12 * with XMLHttpRequests. These methods work with a cross-browser
13 * W3C compliant <OpenLayers.Request.XMLHttpRequest> class.
15 OpenLayers.Request = {
18 * Constant: DEFAULT_CONFIG
19 * {Object} Default configuration for all requests.
23 url: window.location.href,
28 proxy: OpenLayers.ProxyHost,
31 callback: function() {},
39 * {<OpenLayers.Events>} An events object that handles all
40 * events on the {<OpenLayers.Request>} object.
42 * All event listeners will receive an event object with three properties:
43 * request - {<OpenLayers.Request.XMLHttpRequest>} The request object.
44 * config - {Object} The config object sent to the specific request method.
45 * requestUrl - {String} The request url.
47 * Supported event types:
48 * complete - Triggered when we have a response from the request, if a
49 * listener returns false, no further response processing will take
51 * success - Triggered when the HTTP response has a success code (200-299).
52 * failure - Triggered when the HTTP response does not have a success code.
54 events: new OpenLayers.Events(this, null, ["complete", "success", "failure"]),
58 * Create a new XMLHttpRequest object, open it, set any headers, bind
59 * a callback to done state, and send any data. It is recommended that
60 * you use one <GET>, <POST>, <PUT>, <DELETE>, <OPTIONS>, or <HEAD>.
61 * This method is only documented to provide detail on the configuration
62 * options available to all request methods.
65 * config - {Object} Object containing properties for configuring the
66 * request. Allowed configuration properties are described below.
67 * This object is modified and should not be reused.
69 * Allowed config properties:
70 * method - {String} One of GET, POST, PUT, DELETE, HEAD, or
71 * OPTIONS. Default is GET.
72 * url - {String} URL for the request.
73 * async - {Boolean} Open an asynchronous request. Default is true.
74 * user - {String} User for relevant authentication scheme. Set
75 * to null to clear current user.
76 * password - {String} Password for relevant authentication scheme.
77 * Set to null to clear current password.
78 * proxy - {String} Optional proxy. Defaults to
79 * <OpenLayers.ProxyHost>.
80 * params - {Object} Any key:value pairs to be appended to the
81 * url as a query string. Assumes url doesn't already include a query
82 * string or hash. Typically, this is only appropriate for <GET>
83 * requests where the query string will be appended to the url.
84 * Parameter values that are arrays will be
85 * concatenated with a comma (note that this goes against form-encoding)
86 * as is done with <OpenLayers.Util.getParameterString>.
87 * headers - {Object} Object with header:value pairs to be set on
89 * data - {String | Document} Optional data to send with the request.
90 * Typically, this is only used with <POST> and <PUT> requests.
91 * Make sure to provide the appropriate "Content-Type" header for your
92 * data. For <POST> and <PUT> requests, the content type defaults to
93 * "application-xml". If your data is a different content type, or
94 * if you are using a different HTTP method, set the "Content-Type"
95 * header to match your data type.
96 * callback - {Function} Function to call when request is done.
97 * To determine if the request failed, check request.status (200
99 * success - {Function} Optional function to call if request status is in
100 * the 200s. This will be called in addition to callback above and
101 * would typically only be used as an alternative.
102 * failure - {Function} Optional function to call if request status is not
103 * in the 200s. This will be called in addition to callback above and
104 * would typically only be used as an alternative.
105 * scope - {Object} If callback is a public method on some object,
106 * set the scope to that object.
109 * {XMLHttpRequest} Request object. To abort the request before a response
110 * is received, call abort() on the request object.
112 issue: function(config) {
113 // apply default config - proxy host may have changed
114 var defaultConfig = OpenLayers.Util.extend(
116 {proxy: OpenLayers.ProxyHost}
118 config = OpenLayers.Util.applyDefaults(config, defaultConfig);
120 // create request, open, and set headers
121 var request = new OpenLayers.Request.XMLHttpRequest();
122 var url = config.url;
124 var paramString = OpenLayers.Util.getParameterString(config.params);
125 if(paramString.length > 0) {
126 var separator = (url.indexOf('?') > -1) ? '&' : '?';
127 url += separator + paramString;
130 if(config.proxy && (url.indexOf("http") == 0)) {
131 url = config.proxy + encodeURIComponent(url);
134 config.method, url, config.async, config.user, config.password
136 for(var header in config.headers) {
137 request.setRequestHeader(header, config.headers[header]);
140 // bind callbacks to readyState 4 (done)
141 var complete = (config.scope) ?
142 OpenLayers.Function.bind(config.callback, config.scope) :
145 // optional success callback
148 success = (config.scope) ?
149 OpenLayers.Function.bind(config.success, config.scope) :
153 // optional failure callback
156 failure = (config.scope) ?
157 OpenLayers.Function.bind(config.failure, config.scope) :
161 var events = this.events;
163 request.onreadystatechange = function() {
164 if(request.readyState == OpenLayers.Request.XMLHttpRequest.DONE) {
165 var proceed = events.triggerEvent(
167 {request: request, config: config, requestUrl: url}
169 if(proceed !== false) {
171 if (!request.status || (request.status >= 200 && request.status < 300)) {
174 {request: request, config: config, requestUrl: url}
180 if(request.status && (request.status < 200 || request.status >= 300)) {
183 {request: request, config: config, requestUrl: url}
193 // send request (optionally with data) and return
194 // call in a timeout for asynchronous requests so the return is
195 // available before readyState == 4 for cached docs
196 if(config.async === false) {
197 request.send(config.data);
199 window.setTimeout(function(){
200 request.send(config.data);
208 * Send an HTTP GET request. Additional configuration properties are
209 * documented in the <issue> method, with the method property set
213 * config - {Object} Object with properties for configuring the request.
214 * See the <issue> method for documentation of allowed properties.
215 * This object is modified and should not be reused.
218 * {XMLHttpRequest} Request object.
220 GET: function(config) {
221 config = OpenLayers.Util.extend(config, {method: "GET"});
222 return OpenLayers.Request.issue(config);
227 * Send a POST request. Additional configuration properties are
228 * documented in the <issue> method, with the method property set
229 * to POST and "Content-Type" header set to "application/xml".
232 * config - {Object} Object with properties for configuring the request.
233 * See the <issue> method for documentation of allowed properties. The
234 * default "Content-Type" header will be set to "application-xml" if
235 * none is provided. This object is modified and should not be reused.
238 * {XMLHttpRequest} Request object.
240 POST: function(config) {
241 config = OpenLayers.Util.extend(config, {method: "POST"});
242 // set content type to application/xml if it isn't already set
243 config.headers = config.headers ? config.headers : {};
244 if(!("CONTENT-TYPE" in OpenLayers.Util.upperCaseObject(config.headers))) {
245 config.headers["Content-Type"] = "application/xml";
247 return OpenLayers.Request.issue(config);
252 * Send an HTTP PUT request. Additional configuration properties are
253 * documented in the <issue> method, with the method property set
254 * to PUT and "Content-Type" header set to "application/xml".
257 * config - {Object} Object with properties for configuring the request.
258 * See the <issue> method for documentation of allowed properties. The
259 * default "Content-Type" header will be set to "application-xml" if
260 * none is provided. This object is modified and should not be reused.
263 * {XMLHttpRequest} Request object.
265 PUT: function(config) {
266 config = OpenLayers.Util.extend(config, {method: "PUT"});
267 // set content type to application/xml if it isn't already set
268 config.headers = config.headers ? config.headers : {};
269 if(!("CONTENT-TYPE" in OpenLayers.Util.upperCaseObject(config.headers))) {
270 config.headers["Content-Type"] = "application/xml";
272 return OpenLayers.Request.issue(config);
277 * Send an HTTP DELETE request. Additional configuration properties are
278 * documented in the <issue> method, with the method property set
282 * config - {Object} Object with properties for configuring the request.
283 * See the <issue> method for documentation of allowed properties.
284 * This object is modified and should not be reused.
287 * {XMLHttpRequest} Request object.
289 DELETE: function(config) {
290 config = OpenLayers.Util.extend(config, {method: "DELETE"});
291 return OpenLayers.Request.issue(config);
296 * Send an HTTP HEAD request. Additional configuration properties are
297 * documented in the <issue> method, with the method property set
301 * config - {Object} Object with properties for configuring the request.
302 * See the <issue> method for documentation of allowed properties.
303 * This object is modified and should not be reused.
306 * {XMLHttpRequest} Request object.
308 HEAD: function(config) {
309 config = OpenLayers.Util.extend(config, {method: "HEAD"});
310 return OpenLayers.Request.issue(config);
315 * Send an HTTP OPTIONS request. Additional configuration properties are
316 * documented in the <issue> method, with the method property set
320 * config - {Object} Object with properties for configuring the request.
321 * See the <issue> method for documentation of allowed properties.
322 * This object is modified and should not be reused.
325 * {XMLHttpRequest} Request object.
327 OPTIONS: function(config) {
328 config = OpenLayers.Util.extend(config, {method: "OPTIONS"});
329 return OpenLayers.Request.issue(config);