Ajax and the Yahoo! Connection Manager

The introduction of Ajax techniques to the web has spurred a series of JavaScript libraries designed to aid in cross-browser Ajax coding. A search for Ajax libraries on your favorite search engine will reveal a plethora of libraries claiming to be the best for such tasks. Recently, Yahoo! released some of its JavaScript utilities to the public; among them is the Connection Manager.

With Ajax making heavy use of XMLHttp, many developers are looking for ways to equalize the differences between browser implementations. The Yahoo! Connection Manager does this by handling all of the processing behind the scenes, exposing a simple API that frees developers from cross-browser concerns.

Before beginning, make sure you read the Yahoo! license agreement for JavaScript components at http://developer.yahoo.net/yui/license.txt. It’s a standard BSD-style license, but you should be sure to read it over anyway. You can download the Connect Managed code from http://developer.yahoo.net/yui/connection/index.html#download. The code download includes the source code as well as documentation, but no examples.

Setup

There are two JavaScript files necessary to use the Connection Manager: YAHOO.js, which sets up the YAHOO namespace (this file is used by all the Yahoo! JavaScript components), and connection.js, which contains the XMLHttp code. The files must be included in this order as well:

<script type="text/javascript" src="/js/YAHOO.js">
<script type="text/javascript" src="/js/connection.js">

With these files included in your page, you are now ready to begin using the Connection Manager.

Basic Requests

The Yahoo! Connection Manager uses a different methodology than you may be used to for sending XMLHttp requests. Instead of creating objects, the Connection Manager exposes several static methods to handle requests. The method you’ll use most often is asyncRequest(), which has the following signature:

YAHOO.util.Connect.asyncRequest(request_type, url, callback, postdata);

The first argument, request_type, is the type of HTTP request to make: “get” or “post”. The second argument is simply the URL of the request. The third argument is a callback object containing methods to handle the response from the request. This object has the following basic form:

var callback = {
    success: function (oResponse) {
        //handle a successful response
    },
    failure: function (oResponse) {
        //handle an unsuccessful request
    }
}

As you can see, this object has two methods: success() and failure(). The former gets called when a response is returned as expected; the latter is called when an error occurs during the request. Essentially, anytime the request doesn’t return a status of 200, the failure() method is called. The argument that is passed in to both methods is a response object containing all of the information about the response (including all XMLHttp properties such as status, statusText, responseText, responseXML, etc.).

The final argument of asyncRequest() is the data to post to the server. For POST requests, this value is a string of URL-encoded values to be sent; for GET requests, this value can either be omitted or set to null.