| {maketoc}
|
| !The Ajax object
|
|
|
| -The utility functions mentioned above are nice but, let's face it, they are not the most advanced type of thing, now are they? You could probably have done it yourself and you may even have similar functions in you own scripts. But those functions are just the tip of the iceberg.
|
| +The Ajax object is a pre-defined object, created by the library to wrap and simplify the tricky code that is involved when writing AJAX functionality. This object serves as the root for many other classes that provide AJAX functionality. This object contains a number of classes that provide encapsulated AJAX logic. |
|
|
| -I'm sure that your interest in prototype.js is driven mostly by its [http://en.wikipedia.org/wiki/Ajax_%28programming%29|AJAX] capabilities. So let's explain how the library makes your life easier when you need to perform AJAX logic.
|
| +||Method | Kind | Arguments | Description |
| +getTransport() | instance | (none) | Returns a new XMLHttpRequest object|| |
|
|
| -The Ajax object is a pre-defined object, created by the library to wrap and simplify the tricky code that is involved when writing AJAX functionality. This object contains a number of classes that provide encapsulated AJAX logic. Let's take a look at some of them.
|
| +!!The Ajax.Base class |
| + |
| +This class is used as the base class for the other classes defined in the Ajax object. |
| + |
| +||Method | Kind | Arguments | Description |
| +setOptions(options) | instance | options: [#Ajax.options | AJAX options] | Sets the desired [#Ajax.options | options] for the AJAX operation |
| +responseIsSuccess() | instance | (none) | Returns true if the AJAX operation succeeded, false otherwise |
| +responseIsFailure() | instance | (none) | The opposite of responseIsSuccess().|| |
| + |
| +!!The Ajax.Request class |
| + |
| +Inherits from [#Ajax.Base | Ajax.Base] |
| + |
| +Encapsulates AJAX operations |
| + |
| +||Property | Type | Kind | Description |
| +Events | Array | static | List of possible events/statuses reported during an AJAX operation. The list contains: 'Uninitialized', 'Loading', 'Loaded', 'Interactive', and 'Complete.' |
| +transport | XMLHttpRequest | instance | The XMLHttpRequest object that carries the AJAX operation|| |
| + |
| +||Method | Kind | Arguments | Description |
| +[ctor](url, options) | constructor | url: the url to be fetched, options: AJAX options | Creates one instance of this object that will call the given url using the given options. Important: It is worth noting that the chosen url is subject to the borwser's security settings. In many cases the browser will not fetch the url if it is not from the same host (domain) as the current page. You should ideally use only local urls to avoid having to configure or restrict the user's browser. (Thanks Clay). |
| +request(url) | instance | url: url for the AJAX call | This method is typically not called externally. It is already called during the constructor call. |
| +setRequestHeaders() | instance | (none) | This method is typically not called externally. It is called by the object itself to assemble the HTTP header that will be sent during the HTTP request. |
| +onStateChange() | instance | (none) | This method is typically not called externally. It is called by the object itself when the AJAX call status changes. |
| +respondToReadyState(readyState) | instance | readyState: state number (1 to 4) | This method is typically not called externally. It is called by the object itself when the AJAX call status changes.|| |
| + |
| +!!The options argument object |
| + |
| +An important part of the AJAX operations is the options argument. There's no options class per se. Any object can be passed, as long as it has the expected properties. It is common to create anonymous objects just for the AJAX calls. |
| + |
| +||Property | Type | Default | Description |
| +method | String | 'post' | Method of the HTTP request |
| +parameters | String | '' | The url-formatted list of values passed to the request |
| +asynchronous | Boolean | true | Indicates if the AJAX call will be made asynchronously |
| +postBody | String | undefined | Content passed to in the request's body in case of a HTTP POST |
| +requestHeaders | Array | undefined | List of HTTP headers to be passed with the request. This list must have an even number of items, any odd item is the name of a custom header, and the following even item is the string value of that header. Example:['my-header1', 'this is the value', 'my-other-header', 'another value'] |
| +onXXXXXXXX | Function(XMLHttpRequest) | undefined | Custom function to be called when the respective event/status is reached during the AJAX call. Example var myOpts = {onComplete: showResponse, onLoaded: registerLoaded};. The function used will receive one argument, containing the XMLHttpRequest object that is carrying the AJAX operation. |
| +onSuccess | Function(XMLHttpRequest) | undefined | Custom function to be called when the AJAX call completes successfully. The function used will receive one argument, containing the XMLHttpRequest object that is carrying the AJAX operation. |
| +onFailure | Function(XMLHttpRequest) | undefined | Custom function to be called when the AJAX call completes with error. The function used will receive one argument, containing the XMLHttpRequest object that is carrying the AJAX operation. |
| +insertion | Function(Object, String) | null | Function to be called to inject the returned text into an element. The function will be called with two arguments, the element object to be updated and the response text Applies only to [#Ajax.Updater | Ajax.Updater] objects. |
| +evalScripts | Boolean | undefined, false | Determines if script blocks will be evaluated when the response arrives. Applies only to [#Ajax.Updater | Ajax.Updater] objects. |
| +decay | Number | undefined, 1 | Determines the progressive slowdown in a [#Ajax.PeriodicalUpdater | Ajax.PeriodicalUpdater] object refresh rate when the received response is the same as the last one. For example, if you use 2, after one of the refreshes produces the same result as the previous one, the object will wait twice as much time for the next refresh. If it repeats again, the object will wait four times as much, and so on. Leave it undefined or use 1 to avoid the slowdown.|| |
| + |
| +!!The Ajax.Updater class |
| + |
| +Inherits from [#Ajax.Request | Ajax.Request] |
| + |
| +Used when the requested url returns HTML that you want to inject directly in a specific element of your page. You can also use this object when the url returns <script> blocks that will be evaluated upon arrival. Use the evalScripts option to work with scripts. |
| + |
| +||Property | Type | Kind | Description |
| +ScriptFragment | String | static | A regular expression to identify scripts |
| +containers | Object | instance | This object contains two properties: containers.success will be used when the AJAX call succeeds, and containers.failure will be used otherwise.|| |
| + |
| +||Method | Kind | Arguments | Description |
| +[ctor](container, url, options) | constructor | container:this can be the id of an element, the element object itself, or an object with two properties - object.success element (or id) that will be used when the AJAX call succeeds, and object.failure element (or id) that will be used otherwise. url: the url to be fetched, options: [#Ajax.options | AJAX options] | Creates one instance of this object that will call the given url using the given options. |
| +updateContent() | instance | (none) | This method is typically not called externally. It is called by the object itself when the response is received. It will update the appropriate element with the HTML or call the function passed in the insertion option. The function will be called with two arguments, the element to be updated and the response text.|| |
| + |
| +!!The Ajax.PeriodicalUpdater class |
| + |
| +Inherits from [#Ajax.Base | Ajax.Base] |
| + |
| +This class repeatedly instantiates and uses an Ajax.Updater object to refresh an element on the page, or to perform any of the other tasks the Ajax.Updater can perform. Check the [#Ajax.Updater | Ajax.Updater reference] for more information. |
| + |
| +||Property | Type | Kind | Description |
| +container | Object | instance | This value will be passed straight to the Ajax.Updater's constructor. |
| +url | String | instance | This value will be passed straight to the Ajax.Updater's constructor. |
| +frequency | Number | instance | Interval (not frequency) between refreshes, in seconds. Defaults to 2 seconds. This number will be multiplied by the current decay when invoking theAjax.Updater object |
| +decay | Number | instance | Keeps the current decay level applied when re-executing the task |
| +updater | [#Ajax.Updater | Ajax.Updater] | instance | The most recently used Ajax.Updater object |
| +timer | Object | instance | The JavaScript timer being used to notify the object when it is time for the next refresh.|| |
| + |
| +||Method | Kind | Arguments | Description |
| +[ctor](container, url, options) | constructor | container:this can be the id of an element, the element object itself, or an object with two properties - object.success element (or id) that will be used when the AJAX call succeeds, and object.failure element (or id) that will be used otherwise. url: the url to be fetched, options: [#Ajax.options | AJAX options] | Creates one instance of this object that will call the given url using the given options. |
| +start() | instance | (none) | This method is typically not called externally. It is called by the object itself to start performing its periodical tasks. |
| +stop() | instance | (none) | This method is typically not called externally. It is called by the object itself to stop performing its periodical tasks. |
| +updateComplete() | instance | (none) | This method is typically not called externally. It is called by the currently used Ajax.Updater after if completes the request. It is used to schedule the next refresh. |
| +onTimerEvent() | instance | (none) | This method is typically not called externally. It is called internally when it is time for the next update.|| |
| + |
| +!Use Examples |
|
|
| !!Using the Ajax.Request class
|
|
|