Commit d5258c73 authored by James Burke's avatar James Burke

Fixes #3526. IO docs. Also updated port guide at...

Fixes #3526. IO docs. Also updated port guide at http://dojotoolkit.org/book/dojo-porting-guide-0-4-x-0-9/io-transports-ajax

git-svn-id: http://svn.dojotoolkit.org/src/dojo/trunk@9416 560b804f-0ae3-0310-86f3-f6aa0a117693
parent 3c1fedd6
......@@ -217,7 +217,43 @@ dojo._contentHandlers = {
// sets up the Deferred and ioArgs property on the Deferred so it
// can be used in an io call.
// args:
// The args object passed into the public io call.
// The args object passed into the public io call. Recognized properties on
// the args object are:
// url:
// String URL to server endpoint.
// content:
// Object containing properties with string values. These properties will be serialized as name1=value2 and passed in the request.
// timeout:
// Milliseconds to wait for the response. If this time passes, the then error callbacks are called.
// form:
// DOM node for a form. Used to extract the form values and send to the server.
// preventCache:
// Boolean. 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.
// handleAs:
// String. Acceptable values depend on the type of IO transport (see below).
// load:
// function(response, ioArgs){}. The load function will be called on a successful response.
// error:
// function(response, ioArgs){}. The error function will be called in an error case.
// handle
// function(response, ioArgs){}. The handle function will be called in either the successful or error case.
// For the load, error and handle functions, the ioArgs object will contain the following properties:
// args:
// the original object argument to the IO call.
// xhr:
// For XMLHttpRequest calls only, the XMLHttpRequest object that was used for the request.
// url:
// The final URL used for the call. Many times it will be different than the original args.url value.
// query:
// For non-GET requests, the name1=value1&name2=value2 parameters sent up in the request.
// handleAs:
// The final indicator on how the response will be handled.
// id:
// For dojo.io.script calls only, the internal script ID used for the request.
// canDelete:
// 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:
// 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.
// canceller:
// The canceller function used for the Deferred object. The function
// will receive one argument, the Deferred object that is related to the
......@@ -458,26 +494,49 @@ dojo._contentHandlers = {
// TODOC: FIXME!!!
dojo.xhrGet = function(/*Object*/ args){
//summary: Sends an HTTP GET request to the server. See dojo._ioSetArgs in this file
//for a list of commonly accepted properties on the args argument. Additional properties
//that apply to all of the dojo.xhr* methods:
//handleAs:
// String. Acceptable values are "text" (default), "json", "json-comment-optional", "json-comment-filtered", "javascript", "xml"
//sync:
// Boolean. false is default. Indicates whether the request should be a synchronous (blocking) request.
//headers:
// Object. Additional HTTP headers to send in the request.
var dfd = _makeXhrDeferred(args);
dojo._ioAddQueryToUrl(dfd.ioArgs);
return _doIt("GET", dfd); // dojo.Deferred
}
dojo.xhrPost = function(/*Object*/ args){
//summary: Sends an HTTP POST request to the server. See dojo.xhrGet in this file
//for a list of commonly accepted properties on the args argument.
return _doIt("POST", _makeXhrDeferred(args)); // dojo.Deferred
}
dojo.rawXhrPost = function(/*Object*/ args){
//summary: Sends an HTTP POST request to the server. See dojo.xhrGet in this file
//for a list of commonly accepted properties on the args argument. Additional properties
//that apply only to this function:
//postData:
// String. The raw data to send in the body of the POST request.
var dfd = _makeXhrDeferred(args);
dfd.ioArgs.query = args.postData;
return _doIt("POST", dfd); // dojo.Deferred
}
dojo.xhrPut = function(/*Object*/ args){
//summary: Sends an HTTP PUT request to the server. See dojo.xhrGet in this file
//for a list of commonly accepted properties on the args argument.
return _doIt("PUT", _makeXhrDeferred(args)); // dojo.Deferred
}
dojo.rawXhrPut = function(/*Object*/ args){
//summary: Sends an HTTP PUT request to the server. See dojo.xhrGet in this file
//for a list of commonly accepted properties on the args argument. Additional properties
//that apply only to this function:
//putData:
// String. The raw data to send in the body of the PUT request.
var dfd = _makeXhrDeferred(args);
var ioArgs = dfd.ioArgs;
if(args["putData"]){
......@@ -488,12 +547,15 @@ dojo._contentHandlers = {
}
dojo.xhrDelete = function(/*Object*/ args){
//summary: Sends an HTTP DELETE request to the server. See dojo.xhrGet in this file
//for a list of commonly accepted properties on the args argument.
var dfd = _makeXhrDeferred(args);
dojo._ioAddQueryToUrl(dfd.ioArgs);
return _doIt("DELETE", dfd); // dojo.Deferred
}
dojo.wrapForm = function(formNode){
//summary: A replacement for FormBind, but not implemented yet.
// was FormBind
// FIXME: need to think harder about what extensions to this we might
// want. What should we allow folks to do w/ this? What events to
......
......@@ -106,16 +106,12 @@ dojo.io.iframe = {
//summary: function that sends the request to the server.
//This transport can only process one send() request at a time, so if send() is called
//multiple times, it will queue up the calls and only process one at a time.
//The following are acceptable properties in args:
//url:
// String: URL the server URL to use for the request.
//See dojo._ioArgs() in _base/xhr.js for a list of commonly accepted
//properties on the args argument. Additional properties accepted by send():
//method:
// The HTTP method to use. "GET" or "POST" are the only supported values.
// It will try to read the value from the form node's method, then try this
// argument. If neither one exists, then it defaults to POST.
//form:
// DOMNode: a form element node. The form elements' names and values will be used in
// the request. This makes it possible to upload files using this transport.
//handleAs:
// Specifies what format the result data should be given to the load/handle callback. Valid values are:
// text/plain, text/html, text/javascript, text/json, application/json. IMPORTANT: For all values EXCEPT text/html,
......
......@@ -3,7 +3,24 @@ dojo.provide("dojo.io.script");
dojo.io.script = {
get: function(/*Object*/args){
//summary: sends a get request using a dynamically created script tag.
//TODOC: valid arguments.
//See dojo._ioArgs() in _base/xhr.js for a list of commonly accepted
//properties on the args argument. Additional properties
//that apply to all of the dojo.xhr* methods:
//callbackParamName:
// String. The URL parameter name that indicates the JSONP callback string.
// For instance, when using Yahoo JSONP calls it is normally,
// callbackParamName: "callback". For AOL JSONP calls it is normally
// callbackParamName: "c".
//checkString:
// String. A string of JavaScript that when evaluated like so:
// "typeof(" + checkString + ") != 'undefined'"
// being true means that the script fetched has been loaded.
// Do not use this if doing a JSONP type of call (use callbackParamName instead).
//"handleAs" is NOT applicable to dojo.io.script.get() calls, since it is
//implied by the usage of "callbackParamName" (response will be a JSONP call
//returning JSON) or "checkString" (response is pure JavaScript defined in
//the body of the script that was attached).
var dfd = this._makeScriptDeferred(args);
var ioArgs = dfd.ioArgs;
dojo._ioAddQueryToUrl(ioArgs);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment