Classic AJAX and the OpenMail API

The last couple of posts, we've starting exploring classic AJAX development using Ext JS. Having already completed our OpenBlog reader application, we'll apply more AJAX techniques to interact with the OpenMail API.

A few days back I wrote about using the OpenMail API in a simple server-side implementation using ColdFusion. Today, we'll use a mix of server and client side development to update an HTML/CSS based control with the new mail count for an AOL account.

The Proxy

Due to its secure architecture, we'll be taking the approach of developing our own proxy service to interact with the AOL OpenMail service. It's a best practice, so we might as well get into the habit. Our proxy implementation is written in ColdFusion as follows:

<cfcomponent displayname="OpenMailRemoteFacade" output="false">

    <cfset variables.f = "json" />
    <cfset variables.devId = "someAOLDevId" />
    <cfset variables.referer = "http://localhost:8501/openmail.cfm" />

    <cffunction name="getNewMailCount" access="remote" output="true" returntype="void">
    	<cfargument name="a" type="string" required="yes" />
    	
        <cfhttp url="http://api.mail.aol.com/mail/newMailCount" method="get">
            <cfhttpparam type="url" name="f" value="json" />
            <cfhttpparam type="url" name="a" value="#arguments.a#" />
            <cfhttpparam type="url" name="devId" value="#variables.devId#" />
            <cfhttpparam type="url" name="referer" value="#variables.referer#" />
        </cfhttp>
        
        <cfoutput>#cfhttp.FileContent#</cfoutput>
    
    	<cfreturn />
    </cffunction>	
	
</cfcomponent>

This service defines a single method named getNewMailCount. It simply prepares a request to the OpenMail API's newMailCount method to retrieve the number of new messages in an AOL user's account. Our CFC method does not return a value explicitly, rather it will output JSON formatted data to be consumed by an AJAX call.

Preparing the UI

Now that we have a proxy to query, we need to define a spot for the data to reside. The minimum code required to accomplish this is shown below:

<cfparam name="url.token_a" type="string" default="" />

<--- set up OpenAuth configuration --->
<cfset devId = "someAOLDevId" />
<cfset succUrl = "http://localhost:8501/openMail.cfm" />
<cfset obj_openAuth = CreateObject( "component", "AOL.OpenAuth" ).init( devId, succUrl ) />

<cfif url.token_a eq "">

	<cfset obj_openAuth.login() />

<cfelse>
    
    <div id="new-mail-count">
    	<div id="folder-name">Inbox</div>
        <div id="mail-count"></div>
        <div id="count-label">new message(s)</div>
    </div>

</cfif>

Since we'll need an OpenAuth authentication token to use the OpenMail service, we're using the AOL.OpenAuth CFC to manage authentication. If authentication is successful, our div structure is available for the AJAX routines to query for OpenMail data and populate the divs.

The AJAX

The final piece of the puzzle involves making an AJAX call to our proxy service and updating the content of the mail-count div container. Using Ext JS, we can accomplish this as follows:

<--- Ext JS core files --->
<script type="text/javascript" src="ext-2.0/adapter/ext/ext-base.js"></script>
<script type="text/javascript" src="ext-2.0/ext-all-debug.js"></script>
<script type="text/javascript">
// capture the OpenAuth token
var authToken = "<cfoutput>#url.token_a#</cfoutput>";

Ext.onReady( function() {

    // update the content of the 'mail-count' div container
    // with data returned from AJAX call defined below.
    Ext.get( "mail-count" ).load(
    
        {
            url: "http://localhost:8501/OpenMailRemoteFacade.cfc",
            params: { 
                method: "getNewMailCount",
                a:      authToken
            },
            // e = element
            // s = success
            // r = response
            // o = options
            callback: function( e, s, r, o ) {
                
                if( s ) {
                    var jsonResponse = Ext.util.JSON.decode( r.responseText );
                    
                    // update the target element with the new mail count from the inbox.
                    e.update( jsonResponse.response.data.mailFolderCount.
                              mailFolderData.mailFolderType[0].count );
                }
                else {
                    alert( "A problem occurred with your request." );
                }
                
            }
        }
    
    );

} );
</script>

Using the load method of the Ext.Element class, we're able to issue an AJAX call to retrieve data used to update the target element. We've chosen the div element with the id mail-count. The callback defined as part of this request will support arguments including a reference to the target element, a success boolean value, a response object, and an options object. If the response was successful, all we have to do is decode the JSON data, and populate the container with the new mail count for the inbox. With a little bit of styling, I get a result as shown below: