From 449e532f9a5b75b2e5fd5a4ad8a8b05c4a017e57 Mon Sep 17 00:00:00 2001 From: Andrew Dupont Date: Sat, 7 Mar 2009 15:43:20 -0600 Subject: [PATCH] Add PDoc for most of Ajax section. --- src/ajax.js | 109 +++++++++++++++++++++++++++++++++++++++++ src/ajax/ajax.js | 10 ++++ src/ajax/base.js | 1 + src/ajax/request.js | 101 +++++++++++++++++++++++++++++++++++++- src/ajax/responders.js | 87 ++++++++++++++++++++++++++++++++ src/ajax/response.js | 97 ++++++++++++++++++++++++++++++++++++ src/ajax/updater.js | 28 +++++++++++ 7 files changed, 432 insertions(+), 1 deletion(-) diff --git a/src/ajax.js b/src/ajax.js index 98cf975..2771fd8 100644 --- a/src/ajax.js +++ b/src/ajax.js @@ -1,3 +1,112 @@ +/** + * == Ajax == + * + * Prototype's APIs around the `XmlHttpRequest` object. + * + * The Prototype framework enables you to deal with Ajax calls in a manner that is + * both easy and compatible with all modern browsers. + * + * Actual requests are made by creating instances of [[Ajax.Request]]. + * + *

Request headers

+ * + * The following headers are sent with all Ajax requests (and can be + * overridden with the `requestHeaders` option described below): + * + * * `X-Requested-With` is set to `XMLHttpRequest`. + * * `X-Prototype-Version` is set to Prototype's current version (e.g., + * `1.6.0.3`). + * * `Accept` is set to `text/javascript, text/html, application/xml, + * text/xml, * / *` + * * `Content-type` is automatically determined based on the `contentType` + * and `encoding` options. + * + *

Ajax options

+ * + * All Ajax classes share a common set of _options_ and _callbacks_. + * Callbacks are called at various points in the life-cycle of a request, and + * always feature the same list of arguments. + * + *
Common options
+ * + * * `asynchronous` ([[Boolean]]; default `true`): Determines whether + * `XMLHttpRequest` is used asynchronously or not. Synchronous usage is + * seriously discouraged — it halts all script execution for the duration of + * the request _and_ blocks the browser UI. + * * `contentType` ([[String]]; default `application/x-www-form-urlencoded`): + * The `Content-type` header for your request. Change this header if you + * want to send data in another format (like XML). + * * `encoding` ([[String]]; default `UTF-8`): The encoding for the contents + * of your request. It is best left as-is, but should weird encoding issues + * arise, you may have to tweak this. + * * `method` ([[String]]; default `post`): The HTTP method to use for the + * request. The other common possibility is `get`. Abiding by Rails + * conventions, Prototype also reacts to other HTTP verbs (such as `put` and + * `delete`) by submitting via `post` and adding a extra `_method` parameter + * with the originally-requested method. + * * `parameters` ([[String]]): The parameters for the request, which will be + * encoded into the URL for a `get` method, or into the request body for the + * other methods. This can be provided either as a URL-encoded string, a + * [[Hash]], or a plain [[Object]]. + * * `postBody` ([[String]]): Specific contents for the request body on a + * `post` method. If it is not provided, the contents of the `parameters` + * option will be used instead. + * * `requestHeaders` ([[Object]]): A set of key-value pairs, with properties + * representing header names. + * * `evalJS` ([[Boolean]] | [[String]]; default `true`): Automatically `eval`s + * the content of [[Ajax.Response#responseText]] and populates + * [[Ajax.Response#responseJSON]] with it if the `Content-type` returned by + * the server is set to `application/json`. If the request doesn't obey + * same-origin policy, the content is sanitized before evaluation. If you + * need to force evalutation, pass `'force'`. To prevent it altogether, pass + * `false`. + * * `sanitizeJSON` ([[Boolean]]; default is `false` for same-origin requests, + * `true` otherwise): Sanitizes the contents of + * [[Ajax.Response#responseText]] before evaluating it. + * + *

Common callbacks

+ * + * When used on individual instances, all callbacks (except `onException`) are + * invoked with two parameters: the `XMLHttpRequest` object and the result of + * evaluating the `X-JSON` response header, if any (can be `null`). + * + * For another way of describing their chronological order and which callbacks + * are mutually exclusive, see [[Ajax.Request]]. + * + * * `onCreate`: Triggered when the [[Ajax.Request]] object is initialized. + * This is _after_ the parameters and the URL have been processed, but + * _before_ opening the connection via the XHR object. + * * `onUninitialized` (*Not guaranteed*): Invoked just after the XHR object + * is created. + * * `onLoading` (*Not guaranteed*): Triggered when the underlying XHR object + * is being setup, and its connection opened. + * * `onLoaded` (*Not guaranteed*): Triggered once the underlying XHR object + * is setup, the connection is open, and it is ready to send its actual + * request. + * * `onInteractive` (*Not guaranteed*): Triggered whenever the requester + * receives a part of the response (but not the final part), should it + * be sent in several packets. + * * `onSuccess`: Invoked when a request completes and its status code is + * `undefined` or belongs in the `2xy` family. This is skipped if a + * code-specific callback is defined (e.g., `on200`), and happens _before_ + * `onComplete`. + * * `onFailure`: Invoked when a request completes and its status code exists + * but _is not_ in the `2xy` family. This is skipped if a code-specific + * callback is defined (e.g. `on403`), and happens _before_ `onComplete`. + * * `onXYZ` (_with `XYZ` representing any HTTP status code_): Invoked just + * after the response is complete _if_ the status code is the exact code + * used in the callback name. _Prevents_ execution of `onSuccess` and + * `onFailure`. Happens _before_ `onComplete`. + * * `onException`: Triggered whenever an XHR error arises. Has a custom + * signature: the first argument is the requester (i.e. an [[Ajax.Request]] + * instance), and the second is the exception object. + * * `onComplete`: Triggered at the _very end_ of a request's life-cycle, after + * the request completes, status-specific callbacks are called, and possible + * automatic behaviors are processed. Guaranteed to run regardless of what + * happened during the request. + * +**/ + //= require "ajax/ajax" //= require "ajax/responders" //= require "ajax/base" diff --git a/src/ajax/ajax.js b/src/ajax/ajax.js index 4895a10..d8174f2 100644 --- a/src/ajax/ajax.js +++ b/src/ajax/ajax.js @@ -1,3 +1,7 @@ +/** section: Ajax + * Ajax +**/ + var Ajax = { getTransport: function() { return Try.these( @@ -7,5 +11,11 @@ var Ajax = { ) || false; }, + /** + * Ajax.activeRequestCount -> Number + * + * Represents the number of active XHR requests triggered through + * [[Ajax.Request]], [[Ajax.Updater]], or [[Ajax.PeriodicalUpdater]]. + **/ activeRequestCount: 0 }; diff --git a/src/ajax/base.js b/src/ajax/base.js index b6413db..0be66bc 100644 --- a/src/ajax/base.js +++ b/src/ajax/base.js @@ -1,3 +1,4 @@ +// Abstract class; does not need documentation. Ajax.Base = Class.create({ initialize: function(options) { this.options = { diff --git a/src/ajax/request.js b/src/ajax/request.js index 6937b5d..d09d53d 100644 --- a/src/ajax/request.js +++ b/src/ajax/request.js @@ -1,6 +1,92 @@ +/** section: Ajax + * class Ajax.Request + * + * Initiates and processes an Ajax request. + * + * `Ajax.Request` is a general-purpose class for making HTTP requests. + * + *

Automatic JavaScript response evaluation

+ * + * If an Ajax request follows the _same-origin policy_ **and** its response + * has a JavaScript-related `Content-type`, the content of the `responseText` + * property will automatically be passed to `eval`. + * + * In other words: you don't even need to provide a callback to leverage + * pure-JavaScript AJAX responses. This is the convention that drives Rails's + * RJS. + * + * The list of JavaScript-related MIME-types handled by Prototype is: + * + * * `application/ecmascript` + * * `application/javascript` + * * `application/x-ecmascript` + * * `application/x-javascript` + * * `text/ecmascript` + * * `text/javascript` + * * `text/x-ecmascript` + * * `text/x-javascript` + * + * The MIME-type string is examined in a case-insensitive manner. + * + *

Methods you may find useful

+ * + * Instances of the `Request` object provide several methods that can come in + * handy in your callback functions, especially once the request is complete. + * + *
Is the response a successful one?
+ * + * The [[Ajax.Request#success]] method examines the XHR object's `status` + * property and follows general HTTP guidelines: unknown status is deemed + * successful, as is the whole `2xy` status code family. It's a generally + * better way of testing your response than the usual + * `200 == transport.status`. + * + *
Getting HTTP response headers
+ * + * While you can obtain response headers from the XHR object using its + * `getResponseHeader` method, this makes for verbose code, and several + * implementations raise an exception when the header is not found. To make + * this easier, you can use the [[Ajax.Response#getHeader]] method, which + * delegates to the longer version and returns `null` if an exception occurs: + * + * new Ajax.Request('/your/url', { + * onSuccess: function(response) { + * // Note how we brace against null values + * if ((response.getHeader('Server') || '').match(/Apache/)) + * ++gApacheCount; + * // Remainder of the code + * } + * }); + * + *
Evaluating JSON headers
+ * + * Some backends will return JSON not as response text, but in the `X-JSON` + * header. In this case, you don't even need to evaluate the returned JSON + * yourself, as Prototype automatically does so. It passes the result as the + * `headerJSON` property of the [[Ajax.Response]] object. Note that if there + * is no such header — or its contents are invalid — `headerJSON` will be set + * to `null`. + * + * new Ajax.Request('/your/url', { + * onSuccess: function(transport) { + * transport.headerJSON + * } + * }); +**/ Ajax.Request = Class.create(Ajax.Base, { _complete: false, + /** + * new Ajax.Request(url[, options]) + * - url (String): The URL to fetch. When the _same-origin_ policy is in + * effect (as it is in most cases), `url` **must** be a relative URL or an + * absolute URL that starts with a slash (i.e., it must not begin with + * `http`). + * - options (Object): Configuration for the request. See the + * [[Ajax section]] for more information. + * + * Creates a new `Ajax.Request`. + **/ initialize: function($super, url, options) { $super(options); this.transport = Ajax.getTransport(); @@ -95,6 +181,11 @@ Ajax.Request = Class.create(Ajax.Base, { this.transport.setRequestHeader(name, headers[name]); }, + /** + * Ajax.Request.success() -> Boolean + * + * Tests whether the request was successful. + **/ success: function() { var status = this.getStatus(); return !status || (status >= 200 && status < 300); @@ -148,10 +239,18 @@ Ajax.Request = Class.create(Ajax.Base, { })); }, + /** + * Ajax.Request.getHeader(name) -> String | null + * - name (String): The name of an HTTP header that may have been part of + * the response. + * + * Returns the value of the given response header, or `null` if that header + * was not found. + **/ getHeader: function(name) { try { return this.transport.getResponseHeader(name) || null; - } catch (e) { return null } + } catch (e) { return null; } }, evalResponse: function() { diff --git a/src/ajax/responders.js b/src/ajax/responders.js index a317a90..80a8e37 100644 --- a/src/ajax/responders.js +++ b/src/ajax/responders.js @@ -1,3 +1,71 @@ +/** section: Ajax + * Ajax.Responders + * + * A repository of global listeners notified about every step of + * Prototype-based Ajax requests. + * + * Sometimes, you need to provide generic behaviors over all Ajax operations + * happening on the page (through [[Ajax.Request]], [[Ajax.Updater]] or + * [[Ajax.PeriodicalUpdater]]). + * + * For instance, you might want to automatically show an indicator when an + * Ajax request is ongoing, and hide it when none are. You may well want to + * factor out exception handling as well, logging those somewhere on the page + * in a custom fashion. The possibilities are myriad. + * + * To achieve this, Prototype provides `Ajax.Responders`, which lets you + * register (and, if you wish, unregister later) _responders_, which are + * objects with specially-named methods. These names come from a set of + * general callbacks corresponding to different points in time (or outcomes) + * of an Ajax request's life cycle. + * + * For instance, Prototype automatically registers a responder that maintains + * a nifty variable: [[Ajax.activeRequestCount]]. This represents, at a given + * time, the number of currently active Ajax requests — by monitoring their + * `onCreate` and `onComplete` events. The code for this is fairly simple: + * + * Ajax.Responders.register({ + * onCreate: function() { + * Ajax.activeRequestCount++; + * }, + * onComplete: function() { + * Ajax.activeRequestCount--; + * } + * }); + * + *

Responder callbacks

+ * + * The callbacks for responders are similar to the callbacks described in + * the [[Ajax section]], but take a different signature. They're invoked with + * three parameters: the requester object (i.e., the corresponding "instance" + * of [[Ajax.Request]]), the `XMLHttpRequest` object, and the result of + * evaluating the `X-JSON` response header, if any (can be `null`). They also + * execute in the context of the responder, bound to the `this` reference. + * + * * `onCreate`: Triggered whenever a requester object from the `Ajax` + * namespace is created, after its parameters are adjusted and before its + * XHR connection is opened. This takes *two* arguments: the requester + * object and the underlying XHR object. + * * `onUninitialized` (*Not guaranteed*): Invoked just after the XHR object + * is created. + * * `onLoading` (*Not guaranteed*): Triggered when the underlying XHR object + * is being setup, and its connection opened. + * * `onLoaded` (*Not guaranteed*): Triggered once the underlying XHR object + * is setup, the connection is open, and it is ready to send its actual + * request. + * * `onInteractive` (*Not guaranteed*): Triggered whenever the requester + * receives a part of the response (but not the final part), should it + * be sent in several packets. + * * `onException`: Triggered whenever an XHR error arises. Has a custom + * signature: the first argument is the requester (i.e. an [[Ajax.Request]] + * instance), and the second is the exception object. + * * `onComplete`: Triggered at the _very end_ of a request's life-cycle, after + * the request completes, status-specific callbacks are called, and possible + * automatic behaviors are processed. Guaranteed to run regardless of what + * happened during the request. + * +**/ + Ajax.Responders = { responders: [], @@ -5,11 +73,30 @@ Ajax.Responders = { this.responders._each(iterator); }, + /** + * Ajax.Responders.register(responder) -> undefined + * - responder (Object): A list of functions with keys corresponding to the + * names of possible callbacks. + * + * Add a group of responders to all Ajax requests. + **/ register: function(responder) { if (!this.include(responder)) this.responders.push(responder); }, + /** + * Ajax.Responders.unregister(responder) -> undefined + * - responder (Object): A list of functions with keys corresponding to the + * names of possible callbacks. + * + * Remove a previously-added group of responders. + * + * As always, unregistering something requires you to use the very same + * object you used at registration. If you plan to use `unregister`, be sure + * to assign your responder to a _variable_ before passing it into + * [[Ajax.Responders#register]] — don't pass it an object literal. + **/ unregister: function(responder) { this.responders = this.responders.without(responder); }, diff --git a/src/ajax/response.js b/src/ajax/response.js index c8bc2f8..6224426 100644 --- a/src/ajax/response.js +++ b/src/ajax/response.js @@ -1,4 +1,64 @@ +/** section: Ajax + * class Ajax.Response + * + * A wrapper class around `XmlHttpRequest` for dealing with HTTP responses + * of Ajax requests. + * + * An instance of `Ajax.Response` is passed as the first argument of all Ajax + * requests' callbacks. You _will not_ need to create instances of + * `Ajax.Response` yourself. +**/ + +/** + * Ajax.Response#readyState -> Number + * + * The request’s current state. + * + * `0` corresponds to `"Uninitialized"`, `1` to `"Loading"`, `2` to + * `"Loaded"`, `3` to `"Interactive"`, and `4` to `"Complete"`. +**/ + +/** + * Ajax.Response#responseText -> String + * + * The text body of the response. +**/ + +/** + * Ajax.Response#responseXML -> document | null + * + * The XML body of the response if the `Content-type` of the request is set + * to `application/xml`; `null` otherwise. +**/ + +/** + * Ajax.Response#responseJSON -> Object | Array | null + * + * The JSON body of the response if the `Content-type` of the request is set + * to `application/json`; `null` otherwise. +**/ + +/** + * Ajax.Response#headerJSON -> Object | Array | null + * + * Auto-evaluated content of the `X-JSON` header if present; `null` otherwise. +**/ + +/** + * Ajax.Response#request -> Ajax.Request | Ajax.Updater + * + * The request object itself (an instance of [[Ajax.Request]] or + * [[Ajax.Updater]]). +**/ + +/** + * Ajax.Response#transport -> XmlHttpRequest + * + * The native `XmlHttpRequest` object itself. +**/ + Ajax.Response = Class.create({ + // Don't document the constructor; should never be manually instantiated. initialize: function(request){ this.request = request; var transport = this.transport = request.transport, @@ -18,7 +78,18 @@ Ajax.Response = Class.create({ } }, + /** + * Ajax.Response#status -> Number + * + * The HTTP status code sent by the server. + **/ status: 0, + + /** + * Ajax.Response#statusText -> String + * + * The HTTP status text sent by the server. + **/ statusText: '', getStatus: Ajax.Request.prototype.getStatus, @@ -29,18 +100,44 @@ Ajax.Response = Class.create({ } catch (e) { return '' } }, + /** + * Ajax.Response#getHeader(name) -> String | null + * + * See [[Ajax.Request#getHeader]]. + **/ getHeader: Ajax.Request.prototype.getHeader, + /** + * Ajax.Response#getAllHeaders() -> String | null + * + * Returns a string containing all headers separated by line breaks. _Does + * not__ throw errors if no headers are present the way its native + * counterpart does. + **/ getAllHeaders: function() { try { return this.getAllResponseHeaders(); } catch (e) { return null } }, + /** + * Ajax.Response.getResponseHeader(name) -> String + * + * Returns the value of the requested header if present; throws an error + * otherwise. This is just a wrapper around the `XmlHttpRequest` method of + * the same name. + **/ getResponseHeader: function(name) { return this.transport.getResponseHeader(name); }, + /** + * Ajax.Response.getAllResponseHeaders() -> String + * + * Returns a string containing all headers separated by line breaks; throws + * an error if no headers exist. This is just a wrapper around the + * `XmlHttpRequest` method of the same name. + **/ getAllResponseHeaders: function() { return this.transport.getAllResponseHeaders(); }, diff --git a/src/ajax/updater.js b/src/ajax/updater.js index 262c7f6..e1efa98 100644 --- a/src/ajax/updater.js +++ b/src/ajax/updater.js @@ -1,3 +1,31 @@ +/** section: Ajax + * class Ajax.Updater < Ajax.Request + * + * A class that performs an Ajax request and updates a container’s contents + * with the contents of the response. + * + * `Ajax.Updater` is a subclass of [[Ajax.Request]] built for a common + * use-case. + * + *

Example

+ * + * new Ajax.Updater('items', '/items', { + * parameters: { text: $F('text') } + * }); + * + * This example will make a request to the URL `/items` (with the given + * parameters); it will then replace the contents of the element with the ID + * of `items` with whatever response it receives. + * + * + * +**/ + + + + + + Ajax.Updater = Class.create(Ajax.Request, { initialize: function($super, container, url, options) { this.container = {