domapi.ajax
AJAX stands for "Asynchronous JavaScript And XML" and is really just a fancier way of doing rpc. Some of the benefits of using AJAX over RPC are better error handling, ease of use and the ability to perform operations asynchronously.
The AJAX unit contains just one main method, ajax.request(). This method is used for all operations. Additionally, you can define your own global hooks into the AJAX engine, for custom debugging or tasks. The global hooks you can optionally use are as follows:
- onajaxrequest
- onajaxloading
- onajaxloaded
- onajaxsuccess
- onajaxtimeout
- onajaxerror
- onajaxqueuepop
- onajaxqueueappend
- onajaxdispatch
These hooks all correspond to the events defined in the ajax.request() call, and fire at the same times that those do. Each of these hooks are passed an inline object that contains "request" and "arg" attributes. Here is an example of using a global hook, this hook will fire whenever ANY ajax requests complete successfully:
domapi.regHook("onajaxsuccess", my_onsuccess);
function my_onsuccess(arg){
alert(arg.request.responseText);
};
Methods unique to domapi.ajax
Properties unique to domapi.ajax
| getNodeText ( node ) | type : String |
|---|
A useful function when parsing xml nodes. Pass it a node, and it will return its contents, regardless of whitespace.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| node | variant | Y |
| request( arg ) | type : XmlHttpRequest |
|---|
The "arg" parameter fed to this method is an inline Object. See below for accepted parameters.
Any parameters not listed here that you add may also be attached to any returned Object.
The main interface into the AJAX engine. This method takes many different arguments that alter its behaviour.
Example:
// synchronous call
alert(
domapi.ajax.request(
{
url : "mypage.cfm",
requestHeaders : { userid : 2, usertype : "emp" },
async : false
}
).responseText
);
// asynchronous call
domapi.ajax.request(
{
url : "mypage.cfm",
requestHeaders : { userid : 2, usertype : "emp" },
async : true,
onsuccess : myFunc
}
);
function myFunc(req, arg){
alert(req.responseText);
};
Available "arg" Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| url | String | about:blank | URI to the desired resource. Note, in the default security mode of most browsers, this must reside on the originating server. | |
| hint | String | This is displayed in the debugger. You can provide some explanatory or descriptive text, to help identify the request within the debugger. | ||
| doCacheBuster | boolean | true | When true, the engine will add a url param to the request to guard against a cached copy being returned. This param is named "dacb" (domapi cache buster) as is a random number using the current datetime as a seed. | |
| method | String | GET | Http method, either GET or POST. | |
| async | boolean | true | When true, the request will not return right away, but will instead be returned in another thread. You must use event handlers when using this mode. When async is false, code execution stops and waits for the result before continuing. | |
| username | String | Useful if you require authentication. | ||
| password | String | Useful if you require authentication. | ||
| request | variant | This is any data you are sending to the server as part of your request. It can be of any type, but it is ultimately converted to a string before being transmitted. | ||
| requestType | String | string | The data type of the request field. Accepted values are "string", "integer", "float", "boolean", "xml", "json" and "object". Only "json" and "object" have any special meaning right now. These objects are converted to strings using the json unit. All other types are converted to strings using their built-in toString methods. A value of "xml" causes the request contentType to become "text/xml", otherwise it is "application/x-www-form-urlencoded". | |
| returnType | String | string | not currently used | |
| id | variant | auto incremented | id is used by the debugger for displaying and labeling requests. By default, the engine provides these in the form "request_x", when x is an integer. You can provide your own id if you prefer, but they MUST be unique. | |
| contentType | String | application/x-www-form-urlencoded | If your requestType is "xml", the default is instead "text/xml". | |
| requestHeaders | Object | {} | Collection (object) of name=value pairs, that will all be sent in the requests HTTP header. | |
| onrequest | Event | Fires when a request is made (not the same as dispatch). A copy of the request object and the original request arg are passed to the event handler | ||
| onloading | Event | Fires when a requests readystate changes to 'loading'. A copy of the request object and the original request arg are passed to it. | ||
| onloaded | Event | Fires when the readystate changes to 'loaded'. A copy of the request object and the original request arg are passed to the event handler | ||
| onsuccess | Event | Fires when a request finishes successfully. This is the main event you will use when making asynchronous requests. A copy of the request object and the original request arg are passed to the event handler. You can read the requests responseText or responseXml properties for any data returned from the server. | ||
| ontimeout | Event | Fires if a request times out before the server responds. A copy of the request object and the original request arg are passed to the event handler. | ||
| onerror | Event | Fires if an error occurs during the request to the server. A copy of the request object and the original request arg are passed to the event handler | ||
| onqueuepop | Event | Fires when the request object is taken off the queue, presumably to be dispatched. A copy of the request object and the original request arg are passed to the event handler. | ||
| onqueueappend | Event | Fires when the request object is added to the queue, presumably because the ajax.maxConcurrentRequests value has been exceeded. A copy of the request object and the original request arg are passed to the event handler. | ||
| ondispatch | Event | Fires when the request has been dispatched to the server. A copy of the request object and the original request arg are passed to the event handler. |
| active | type : Array |
|---|
Contains a stack of active (in motion) requests. You really shouldn't mess with this directly, but it can be useful to read its length value when debugging.
Example:
alert(domapi.ajax.active.length);
| doRetryOnTimeout | type : boolean | default value : true |
|---|
not currently implemented
| maxConcurrentRequests | type : integer | default value : 50 |
|---|
This is the maximum number of requests that can be in motion before the engine starts queuing them. You can use this to throttle back bandwidth usage, by setting it to a low value like 2.
| maxRetryOnTimeout | type : integer | default value : 1 |
|---|
not currently implemented
| queue | type : Array |
|---|
Contains a stack of queued requests that have not been sent yet. You really shouldn't mess with this directly, but it can be useful to read its length value when debugging.
Example:
alert(domapi.queue.length);
| singletonStrobe | type : integer | default value : 100 |
|---|
The engine uses a blocking mechanism for synchronizing threads. The singletonStrobe value is the time in milliseconds that the engine polls the locks. A lower value increases the perceived 'responsiveness' during heavy usage, but can also increase cpu usage.
