dojo/_base/xhr (version 1.10)

Summary

Deprecated. Use dojo/request instead.

Sends an HTTP request with the given method. See also dojo.xhrGet(), xhrPost(), xhrPut() and dojo.xhrDelete() for shortcuts for those HTTP methods. There are also methods for "raw" PUT and POST methods via dojo.rawXhrPut() and dojo.rawXhrPost() respectively.

Usage

xhr(method,args,hasBody);
Parameter Type Description
method String

HTTP method to be used, such as GET, POST, PUT, DELETE. Should be uppercase.
args Object
hasBody Boolean
Optional

If the request has an HTTP body, then pass true for hasBody.
Returns:undefined

See the dojo/_base/xhr reference documentation for more information.

Property Summary

Method Summary

  • _getText(url)
  • _ioAddQueryToUrl(ioArgs) Adds query params discovered by the io deferred construction to the URL.
  • _ioCancelAll() Cancels all pending IO requests, regardless of IO type (xhr, script, iframe).
  • _ioNotifyStart(dfd) If dojo.publish is available, publish topics about the start of a request queue and/or the the beginning of request.
  • _ioSetArgs(args,canceller,okHandler,errHandler) sets up the Deferred and ioArgs property on the Deferred so it can be used in an io call.
  • _ioWatch(dfd,validCheck,ioCheck,resHandle) Watches the io request represented by dfd to see if it completes.
  • _isDocumentOk(x)
  • _xhrObj()
  • del(args) Sends an HTTP DELETE request to the server.
  • fieldToObject(inputNode) Serialize a form field to a JavaScript object.
  • formToJson(formNode,prettyPrint) Create a serialized JSON string from a form node or string ID identifying the form to serialize
  • formToObject(formNode) Serialize a form node to a JavaScript object.
  • formToQuery(formNode) Returns a URL-encoded string representing the form passed as either a node or string ID identifying the form to serialize
  • get(args) Sends an HTTP GET request to the server.
  • objectToQuery(map) takes a name/value mapping object and returns a string representing a URL-encoded version of that object.
  • post(args) Sends an HTTP POST request to the server.
  • put(args) Sends an HTTP PUT request to the server.
  • queryToObject(str) Create an object representing a de-serialized query section of a URL.

Properties

contentHandlers
Defined by: dojo/_base/xhr

A map of available XHR transport handle types. Name matches the handleAs attribute passed to XHR calls.

Methods

_getText(url)
Defined by dojo/_base/xhr
Parameter Type Description
url undefined
Returns:undefined
_ioAddQueryToUrl(ioArgs)
Defined by dojo/_base/xhr

Adds query params discovered by the io deferred construction to the URL. Only use this for operations which are fundamentally GET-type operations.

Parameter Type Description
ioArgs Object

An object with the following properties:

  • args (Object):

    the original object argument to the IO call.

  • xhr (XMLHttpRequest):

    For XMLHttpRequest calls only, the XMLHttpRequest object that was used for the request.

  • url (String):

    The final URL used for the call. Many times it will be different than the original args.url value.

  • query (String):

    For non-GET requests, the name1=value1&name2=value2 parameters sent up in the request.

  • handleAs (String):

    The final indicator on how the response will be handled.

  • id (String):

    For dojo/io/script calls only, the internal script ID used for the request.

  • canDelete (Boolean):

    For dojo/io/script calls only, indicates whether the script tag that represents the request can be deleted after callbacks have been called. Used internally to know when cleanup can happen on JSONP-type requests.

  • json (Object):

    For dojo/io/script calls only: holds the JSON response for JSONP-type requests. Used internally to hold on to the JSON responses. You should not need to access it directly -- the same object should be passed to the success callbacks directly.
_ioCancelAll()
Defined by dojo/_base/xhr

Cancels all pending IO requests, regardless of IO type (xhr, script, iframe).

_ioNotifyStart(dfd)
Defined by dojo/_base/xhr

If dojo.publish is available, publish topics about the start of a request queue and/or the the beginning of request.

Used by IO transports. An IO transport should call this method before making the network connection.

Parameter Type Description
dfd dojo/_base/Deferred
_ioSetArgs(args,canceller,okHandler,errHandler)
Defined by dojo/_base/xhr

sets up the Deferred and ioArgs property on the Deferred so it can be used in an io call.

Parameter Type Description
args dojo/main.__IoArgs

The args object passed into the public io call. Recognized properties on the args object are:
canceller Function

The canceller function used for the Deferred object. The function will receive one argument, the Deferred object that is related to the canceller.
okHandler Function

The first OK callback to be registered with Deferred. It has the opportunity to transform the OK response. It will receive one argument -- the Deferred object returned from this function.
errHandler Function

The first error callback to be registered with Deferred. It has the opportunity to do cleanup on an error. It will receive two arguments: error (the Error object) and dfd, the Deferred object returned from this function.
Returns:instance
_ioWatch(dfd,validCheck,ioCheck,resHandle)
Defined by dojo/_base/xhr

Watches the io request represented by dfd to see if it completes.

Parameter Type Description
dfd dojo/_base/Deferred

The Deferred object to watch.
validCheck Function

Function used to check if the IO request is still valid. Gets the dfd object as its only argument.
ioCheck Function

Function used to check if basic IO call worked. Gets the dfd object as its only argument.
resHandle Function

Function used to process response. Gets the dfd object as its only argument.
_isDocumentOk(x)
Defined by dojo/_base/xhr
Parameter Type Description
x undefined
Returns:undefined
_xhrObj()
Defined by dojo/_base/xhr
Returns:instance
del(args)
Defined by dojo/_base/xhr

Sends an HTTP DELETE request to the server.

Parameter Type Description
args Object

An object with the following properties:

  • handleAs (String, optional):

    Acceptable values are: text (default), json, json-comment-optional, json-comment-filtered, javascript, xml. See dojo/_base/xhr.contentHandlers

  • sync (Boolean, optional):

    false is default. Indicates whether the request should be a synchronous (blocking) request.

  • headers (Object, optional):

    Additional HTTP headers to send in the request.

  • failOk (Boolean, optional):

    false is default. Indicates whether a request should be allowed to fail (and therefore no console error message in the event of a failure)

  • contentType (String|Boolean):

    "application/x-www-form-urlencoded" is default. Set to false to prevent a Content-Type header from being sent, or to a string to send a different Content-Type.

  • load:

    This function will be called on a successful HTTP response code.

  • error:

    This function will be called when the request fails due to a network or server error, the url is invalid, etc. It will also be called if the load or handle callback throws an exception, unless djConfig.debugAtAllCosts is true. This allows deployed applications to continue to run even when a logic error happens in the callback, while making it easier to troubleshoot while in debug mode.

  • handle:

    This function will be called at the end of every request, whether or not an error occurs.

  • url (String):

    URL to server endpoint.

  • content (Object, optional):

    Contains properties with string values. These properties will be serialized as name1=value2 and passed in the request.

  • timeout (Integer, optional):

    Milliseconds to wait for the response. If this time passes, the then error callbacks are called.

  • form (DOMNode, optional):

    DOM node for a form. Used to extract the form values and send to the server.

  • preventCache (Boolean, optional):

    Default is false. If true, then a "dojo.preventCache" parameter is sent in the request with a value that changes with each request (timestamp). Useful only with GET-type requests.

  • rawBody (String, optional):

    Sets the raw body for an HTTP request. If this is used, then the content property is ignored. This is mostly useful for HTTP methods that have a body to their requests, like PUT or POST. This property can be used instead of postData and putData for dojo/_base/xhr.rawXhrPost and dojo/_base/xhr.rawXhrPut respectively.

  • ioPublish (Boolean, optional):

    Set this explicitly to false to prevent publishing of topics related to IO operations. Otherwise, if djConfig.ioPublish is set to true, topics will be published via dojo/topic.publish() for different phases of an IO operation. See dojo/main.__IoPublish for a list of topics that are published.
Returns:undefined
fieldToObject(inputNode)
Defined by dojo/_base/xhr

Serialize a form field to a JavaScript object.

Returns the value encoded in a form field as as a string or an array of strings. Disabled form elements and unchecked radio and checkboxes are skipped. Multi-select elements are returned as an array of string values.

Parameter Type Description
inputNode DOMNode | String
Returns:Object | undefined
formToJson(formNode,prettyPrint)
Defined by dojo/_base/xhr

Create a serialized JSON string from a form node or string ID identifying the form to serialize

Parameter Type Description
formNode DOMNode | String
prettyPrint Boolean
Optional
Returns:String | undefined
formToObject(formNode)
Defined by dojo/_base/xhr

Serialize a form node to a JavaScript object.

Returns the values encoded in an HTML form as string properties in an object which it then returns. Disabled form elements, buttons, and other non-value form elements are skipped. Multi-select elements are returned as an array of string values.

Parameter Type Description
formNode DOMNode | String
Returns:object

Examples

Example 1

This form: 

<form id="test_form">
    <input type="text" name="blah" value="blah">
    <input type="text" name="no_value" value="blah" disabled>
    <input type="button" name="no_value2" value="blah">
    <select type="select" multiple name="multi" size="5">
        <option value="blah">blah</option>
        <option value="thud" selected>thud</option>
        <option value="thonk" selected>thonk</option>
    </select>
</form>

yields this object structure as the result of a call to formToObject(): 

{
    blah: "blah",
    multi: [
        "thud",
        "thonk"
    ]
};
formToQuery(formNode)
Defined by dojo/_base/xhr

Returns a URL-encoded string representing the form passed as either a node or string ID identifying the form to serialize

Parameter Type Description
formNode DOMNode | String
Returns:String | undefined
get(args)
Defined by dojo/_base/xhr

Sends an HTTP GET request to the server.

Parameter Type Description
args Object

An object with the following properties:

  • handleAs (String, optional):

    Acceptable values are: text (default), json, json-comment-optional, json-comment-filtered, javascript, xml. See dojo/_base/xhr.contentHandlers

  • sync (Boolean, optional):

    false is default. Indicates whether the request should be a synchronous (blocking) request.

  • headers (Object, optional):

    Additional HTTP headers to send in the request.

  • failOk (Boolean, optional):

    false is default. Indicates whether a request should be allowed to fail (and therefore no console error message in the event of a failure)

  • contentType (String|Boolean):

    "application/x-www-form-urlencoded" is default. Set to false to prevent a Content-Type header from being sent, or to a string to send a different Content-Type.

  • load:

    This function will be called on a successful HTTP response code.

  • error:

    This function will be called when the request fails due to a network or server error, the url is invalid, etc. It will also be called if the load or handle callback throws an exception, unless djConfig.debugAtAllCosts is true. This allows deployed applications to continue to run even when a logic error happens in the callback, while making it easier to troubleshoot while in debug mode.

  • handle:

    This function will be called at the end of every request, whether or not an error occurs.

  • url (String):

    URL to server endpoint.

  • content (Object, optional):

    Contains properties with string values. These properties will be serialized as name1=value2 and passed in the request.

  • timeout (Integer, optional):

    Milliseconds to wait for the response. If this time passes, the then error callbacks are called.

  • form (DOMNode, optional):

    DOM node for a form. Used to extract the form values and send to the server.

  • preventCache (Boolean, optional):

    Default is false. If true, then a "dojo.preventCache" parameter is sent in the request with a value that changes with each request (timestamp). Useful only with GET-type requests.

  • rawBody (String, optional):

    Sets the raw body for an HTTP request. If this is used, then the content property is ignored. This is mostly useful for HTTP methods that have a body to their requests, like PUT or POST. This property can be used instead of postData and putData for dojo/_base/xhr.rawXhrPost and dojo/_base/xhr.rawXhrPut respectively.

  • ioPublish (Boolean, optional):

    Set this explicitly to false to prevent publishing of topics related to IO operations. Otherwise, if djConfig.ioPublish is set to true, topics will be published via dojo/topic.publish() for different phases of an IO operation. See dojo/main.__IoPublish for a list of topics that are published.
Returns:undefined
objectToQuery(map)
Defined by dojo/_base/xhr

takes a name/value mapping object and returns a string representing a URL-encoded version of that object.

Parameter Type Description
map Object
Returns:undefined

Examples

Example 1

this object: 

{
    blah: "blah",
    multi: [
        "thud",
        "thonk"
    ]
};

yields the following query string: 

"blah=blah&multi=thud&multi=thonk"
post(args)
Defined by dojo/_base/xhr

Sends an HTTP POST request to the server. In addition to the properties listed for the dojo.__XhrArgs type, the following property is allowed:

Parameter Type Description
args Object

An object with the following properties:

  • handleAs (String, optional):

    Acceptable values are: text (default), json, json-comment-optional, json-comment-filtered, javascript, xml. See dojo/_base/xhr.contentHandlers

  • sync (Boolean, optional):

    false is default. Indicates whether the request should be a synchronous (blocking) request.

  • headers (Object, optional):

    Additional HTTP headers to send in the request.

  • failOk (Boolean, optional):

    false is default. Indicates whether a request should be allowed to fail (and therefore no console error message in the event of a failure)

  • contentType (String|Boolean):

    "application/x-www-form-urlencoded" is default. Set to false to prevent a Content-Type header from being sent, or to a string to send a different Content-Type.

  • load:

    This function will be called on a successful HTTP response code.

  • error:

    This function will be called when the request fails due to a network or server error, the url is invalid, etc. It will also be called if the load or handle callback throws an exception, unless djConfig.debugAtAllCosts is true. This allows deployed applications to continue to run even when a logic error happens in the callback, while making it easier to troubleshoot while in debug mode.

  • handle:

    This function will be called at the end of every request, whether or not an error occurs.

  • url (String):

    URL to server endpoint.

  • content (Object, optional):

    Contains properties with string values. These properties will be serialized as name1=value2 and passed in the request.

  • timeout (Integer, optional):

    Milliseconds to wait for the response. If this time passes, the then error callbacks are called.

  • form (DOMNode, optional):

    DOM node for a form. Used to extract the form values and send to the server.

  • preventCache (Boolean, optional):

    Default is false. If true, then a "dojo.preventCache" parameter is sent in the request with a value that changes with each request (timestamp). Useful only with GET-type requests.

  • rawBody (String, optional):

    Sets the raw body for an HTTP request. If this is used, then the content property is ignored. This is mostly useful for HTTP methods that have a body to their requests, like PUT or POST. This property can be used instead of postData and putData for dojo/_base/xhr.rawXhrPost and dojo/_base/xhr.rawXhrPut respectively.

  • ioPublish (Boolean, optional):

    Set this explicitly to false to prevent publishing of topics related to IO operations. Otherwise, if djConfig.ioPublish is set to true, topics will be published via dojo/topic.publish() for different phases of an IO operation. See dojo/main.__IoPublish for a list of topics that are published.
Returns:undefined
put(args)
Defined by dojo/_base/xhr

Sends an HTTP PUT request to the server. In addition to the properties listed for the dojo.__XhrArgs type, the following property is allowed:

Parameter Type Description
args Object

An object with the following properties:

  • handleAs (String, optional):

    Acceptable values are: text (default), json, json-comment-optional, json-comment-filtered, javascript, xml. See dojo/_base/xhr.contentHandlers

  • sync (Boolean, optional):

    false is default. Indicates whether the request should be a synchronous (blocking) request.

  • headers (Object, optional):

    Additional HTTP headers to send in the request.

  • failOk (Boolean, optional):

    false is default. Indicates whether a request should be allowed to fail (and therefore no console error message in the event of a failure)

  • contentType (String|Boolean):

    "application/x-www-form-urlencoded" is default. Set to false to prevent a Content-Type header from being sent, or to a string to send a different Content-Type.

  • load:

    This function will be called on a successful HTTP response code.

  • error:

    This function will be called when the request fails due to a network or server error, the url is invalid, etc. It will also be called if the load or handle callback throws an exception, unless djConfig.debugAtAllCosts is true. This allows deployed applications to continue to run even when a logic error happens in the callback, while making it easier to troubleshoot while in debug mode.

  • handle:

    This function will be called at the end of every request, whether or not an error occurs.

  • url (String):

    URL to server endpoint.

  • content (Object, optional):

    Contains properties with string values. These properties will be serialized as name1=value2 and passed in the request.

  • timeout (Integer, optional):

    Milliseconds to wait for the response. If this time passes, the then error callbacks are called.

  • form (DOMNode, optional):

    DOM node for a form. Used to extract the form values and send to the server.

  • preventCache (Boolean, optional):

    Default is false. If true, then a "dojo.preventCache" parameter is sent in the request with a value that changes with each request (timestamp). Useful only with GET-type requests.

  • rawBody (String, optional):

    Sets the raw body for an HTTP request. If this is used, then the content property is ignored. This is mostly useful for HTTP methods that have a body to their requests, like PUT or POST. This property can be used instead of postData and putData for dojo/_base/xhr.rawXhrPost and dojo/_base/xhr.rawXhrPut respectively.

  • ioPublish (Boolean, optional):

    Set this explicitly to false to prevent publishing of topics related to IO operations. Otherwise, if djConfig.ioPublish is set to true, topics will be published via dojo/topic.publish() for different phases of an IO operation. See dojo/main.__IoPublish for a list of topics that are published.
Returns:undefined
queryToObject(str)
Defined by dojo/_base/xhr

Create an object representing a de-serialized query section of a URL. Query keys with multiple values are returned in an array.

Parameter Type Description
str String
Returns:object

Examples

Example 1

This string: 

"foo=bar&foo=baz&thinger=%20spaces%20=blah&zonk=blarg&"

results in this object structure: 

{
    foo: [ "bar", "baz" ],
    thinger: " spaces =blah",
    zonk: "blarg"
}

Note that spaces and other urlencoded entities are correctly handled.

Error in the documentation? Can’t find what you are looking for? Let us know!