Supported: Internet Explorer 6+ Supported: Mozilla Firefox 2+ Supported: Apple Safari 3+ Supported: Google Chrome Supported: Opera 9+ Supported: Konqueror
Leave Feedback

Ajax Classes

Contents

Ajax.Request

This is a base class for handling different AJAX-requests. Parent class - Ajax.Options

new Ajax.Request( String url [, Object options, Number type, String callback, Object scope])

Such call performs an AJAX request with the specified parameters:

  • url [required] - internet address to which request should be performed
  • options [optional] - request options. It’s a subject to pass an options to a parent constructor. See specification of available options below.
  • type [optional] - type of request transport object. Can be one of AJAX_TRANSPORT_TYPE_XHR = 0 or AJAX_TRANSPORT_TYPE_SCRIPT = 1. For more information about transport object - see Ajax.Transport class specification.
  • callback [optional] - callback function name parameter which should be passed to a server when transport type is AJAX_TRANSPORT_TYPE_SCRIPT
  • scope [optional] - an Object or DOM Element under which callback function should be crteated and executed by Ajax.Transport

Ajax.Options

This is a base class specified a set of properties for AJAX requests. Constructor takes only one argument Object options, where values for properties passed

Properties

Property Default Description
asynchronous true Determines whether Ajax.Transport is used asynchronously or not. Try to use asynchronous request whenever you can to avoid page interactivity to be blocked.
contentType 'application/x-www-form-urlencoded' This one property specifies Content-Type header for your request.
encoding 'UTF-8' The encoding used for your request contents.
method 'post' The HTTP method to use for the request. When is used with transport object type = AJAX_TRANSPORT_TYPE_SCRIPT the dafault value will be ‘get’ and it’s impossible to change it. If you will specify some methods differs with ‘get’ or ‘post’ on AJAX_TRANSPORT_TYPE_XHR, will be used ‘post’ method, so actually you able to swith only between 2 methods - ‘get’ or ‘post’.
parameters '' The parameters for the request, which will be encoded into the URL for a 'get' method, or into the request body when a ‘post’ method used. Parameters could be specified as a string with syntax similar to QUERY_STRING or as JavaScript object with a String pairs of name/value.
postBody ” This is parameter to store specific content for a request when is used ‘post’ method. If specified will be used this value insted of passed parameters.
requestHeaders {} Additional request header which should be sent with request. Them should be specified as an Object having String pairs name/value of header entry, e.g. { 'Accept-Charset' : 'iso-8859-5, unicode-1-1;q=0.8', ... }
login null User name parameter which can be passed as additional parameter to Ajax.Transport to handle request on page required HTTP-authentication. Applicable only with AJAX_TRANSPORT_TYPE_XHR.
password null User password parameter which can be passed as additional parameter to Ajax.Transport to handle request on page required HTTP-authentication. Applicable only with AJAX_TRANSPORT_TYPE_XHR.
callback ‘callback’ Name of a parameter for passing callback function name to a server. Actually usially used with AJAX_TRANSPORT_TYPE_SCRIPT. Here some more info about callbacks.
events null Set of event handlers, passed to Ajax.Events which assosiated with Ajax.Options. See possible set of callbacs below.

Also you can pass in option arguments a set of event handlers, which will be applied to Ajax.Events object associated with Ajax.Options.

Callback Events

Event Description
onCreate This event fires when request is just starts to be created.
onUnitialized Fires when transport object state is changed to 0 = Uninitialized. Actually this event applicable only with AJAX_TRANSPORT_TYPE_XHR and not guaranted even on it (this depends on browser and other specific settings).
onLoading Fires when transport object state is changed to 1 = Loading. Actually this event applicable only with AJAX_TRANSPORT_TYPE_XHR and not guaranted even on it (this depends on browser and other specific settings).
onLoaded Fires when transport object state is changed to 2 = Loaded. Actually this event applicable only with AJAX_TRANSPORT_TYPE_XHR and not guaranted even on it (this depends on browser and other specific settings).
onInteractive Fires when transport object state is changed to 3 = Interactive. Actually this event applicable only with AJAX_TRANSPORT_TYPE_XHR and not guaranted even on it (this depends on browser and other specific settings).
onComplete Fires when transport object state is changed to 4 = Complete and all other processors have been already executed. Actually this the last event in the events stack.
onSuccess Fires when response status is 2xx family and before Complete state event executed.
onFailure Fires when response status is not 2xx family and before Complete stste event executed. This event is not applicable with AJAX_TRANSPORT_TYPE_SCRIPT.
on[StatusCode] Fires on specified StatusCode, e.g. on404 or on200. This events if specified revokes call of onSuccess and onFailure events. Note, that only on200 event is applicable with AJAX_TRANSPORT_TYPE_SCRIPT.
onException Fires when some exception has been thrown while performing request. Exception object can be obtained from a second argument passed to this event.

Ajax.Transport

This class is a wrapper factory interface for XHR or other similar objects which provides with possibility to transfer asynchronous “hidden” requests between web browser and web-server over HTTP protocol.

Methods

constructor( [Number type])

Class constructor. Takes one optional argument type which can be one of predefined values: AJAX_TRANSPORT_TYPE_XHR = 0 or AJAX_TRANSPORT_TYPE_SCRIPT = 1. So you can use both ways to pass the type to a class constructor:

new Ajax.Transport( AJAX_TRANSPORT_TYPE_XHR);callback-events
// or
new Ajax.Transport( 0);
// AJAX_TRANSPORT_TYPE_XHR is default so the following call is similar to above:
new Ajax.Transport();
// or
new Ajax.Transport;

open( String method, String url[, Boolean asynchronous, String login,
String password, String callback, Object scope])

Specifies the method, URL, and other optional attributes of a request:

  • method : ‘get’ || ‘post’
  • url : request document address location
  • asynchronous : [optional] type of request = true (asynchronous) || false (synchronous). Default - true
  • login : [optional] login to access a page or null
  • password : [optional] password to access a page or null
  • callback : [optional] callback parameter name. This parameter is used with non-XHR objects when needed that server evaluate JavaScript function on document load. Name of parameter with function name can be defined with this value.
  • scope : [optional] object under which callback function should be defined and evaluated.

send( String postBody)

Sends the request. postBody argument can be a string or null - it specifies additional data which will be sent in request body. This argument has a sense only with type of transport object = AJAX_TRANSPORT_TYPE_XHR.

abort()

Aborts performed request. Works only with transport object type = AJAX_TRANSPORT_TYPE_XHR.

getAllResponseHeaders()

Returns the complete set of HTTP headers as a string. Headers can be obtained only when request transport object type = AJAX_TRANSPORT_TYPE_XHR.

getResponseHeader( String name)

Returns the value of the specified HTTP header. This works only with transport object type = AJAX_TRANSPORT_TYPE_XHR.

setRequestHeader( String name, String value)

Adds a name/value pair to the HTTP header to be sent. Works only with transport object type = AJAX_TRANSPORT_TYPE_XHR.

getType()

Returns type of transport object. Returned value can be one of the following: AJAX_TRANSPORT_TYPE_XHR or AJAX_TRANSPORT_TYPE_SCRIPT.

getAvailableTypes()

Returns string representations of available types as array.

allow( String param[, Mixed value])

Checks if current transport object allows parameter specified as param argument and/or when the param has specified value. Example:     [run]

var t = new Ajax.Transport( AJAX_TRANSPORT_TYPE_SCRIPT);
alert( t.allow( 'method', 'post'));

getCallbackName()

Returns a name of callback function used for current request. The callback functions usually used with transport object type = AJAX_TRANSPORT_TYPE_SCRIPT. In this case callback functions are wrappers to obtain JSON/XML/TEXT data from server and write them to responseText property of Ajax.Transport object. Each time the request is performed Ajax.Transport generates unique callback function and pass its name to a server. So it is available to get this name by using this method.

getTransport()

Returns curently used transport object. For transport type = AJAX_TRANSPORT_TYPE_XHR returns an instance of XmlHttpRequest (or similar - depends on browser), for transport type = AJAX_TRANSPORT_TYPE_SCRIPT returns used script tag DOM element.

Properties

readyState

Read only. Returns the state of the object as follows:

  • -1 = Uninstantiated - no XHR object instantiated or transport type is not AJAX_TRANSPORT_TYPE_XHR
  • 0 = Uninitialized – open() has not yet been called.
  • 1 = Loading – send() has not yet been called.
  • 2 = Loaded – send() has been called, headers and status are available.
  • 3 = Interactive – Downloading, responseText holds partial data (although this functionality is not available in IE
  • 4 = Complete – Finished.

responseText

Read only. Returns the response as a string.

responseXML

Read only. Returns the response as XML. This property returns an XML document object, which can be examined and parsed using W3C DOM node tree methods and properties. Applicable only with AJAX_TRANSPORT_TYPE_XHR.

status

Read only. Returns the HTTP status code as a number (e.g. 404 for “Not Found” and 200 for “OK”). Some network-related status codes (e.g. 408 for “Request Timeout”) cause errors to be thrown in Firefox if the status fields are accessed.[3] If the server does not respond (properly), IE returns a WinInet Error Code (e.g 12029 for “cannot connect”). Applicable only with AJAX_TRANSPORT_TYPE_XHR. on type AJAX_TRANSPORT_TYPE_SCRIPT it will always return 0.

statusText

Read only. Returns the status as a string (e.g. “Not Found” or “OK”). Applicable only with AJAX_TRANSPORT_TYPE_XHR. on type AJAX_TRANSPORT_TYPE_SCRIPT it will always return an empty string.

Ajax.Events

Methods

add( String name, Function handler)

Adds new event handler to an events list with the name specified only if event with such name does not exist.

remove( String name)

Removes event handler by a given name from events list.

registered( String name)

Returns true if event with given name already registered in the list, false otherwise.

fire( String name[, Mixed arguments...])

Fires an event from a list if event having given name is exists. Also applies a set of passed arguments after name parameter to an event handler.

Contents
Next >>
<< Previous