OpenMail - New Mail List Service: Part 2

On Tuesday we completed the heavy lifting required to query the OpenMail API for new mail listings, perform some minor data transformations, and create a minimized data feed. Today we'll write just a few lines of code to create a rich interface using Ext JS.

All development will be performed in our index page that was created on Tuesday. The shell was put in place to allow for OpenAuth integration, we now just need to hook in our Ext code to apply the user interface. Like any other Ext development instance, start off by linking in the styles and scripts which allow for maximum style coverage and script debugging ability. The following paths indicate a root relative path to the Ext resources:

<link rel="stylesheet" type="text/css" href="/ext-2.0/resources/css/ext-all.css" />
<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>

The next step is to define our script block for the Ext code. A common convention, although not always necessary is to wrap Ext code within Ext.onReady, a mechanism used for any activities that rely on a full DOM being present. Also since we need to utilize some ColdFusion variables, the script block is wrapped in <cfoutput /> tags as shown below:

<cfoutput>
<script type="text/javascript">

    Ext.onReady( function() {
        
        // code ...
        
    } );

</script>
</cfoutput>

The first of two major components to the OpenMail app is configuring the data store. As you can see in Listing 1, it's just a matter of entering some data relating to where to query for the data (url) and what the data looks like (root, totalField, and fields). After defining the store, the load() method is called to perform the actual request for data. Just as demonstrated before, three parameters are sent to the mail service including an AOL authentication token, developer id, and the referer url. The callback option is optional but quite useful while still in development. This function accepts three arguments (r = record, o = options, s = success) with the success option the simplest and most useful. This returns true if the request completed as expected and false otherwise. If it comes back false, I know I can interogate the service further but overall it serves as a quick and easy indication of any trouble that may have occurred. For a better idea of what the actual data looks like, see Listing 2.

Listing 1 - Configuring the data store

// define the data store to retrieve the new message data.
var ds_newMailList = new Ext.data.JsonStore(

    {
        url:        "http://localhost:8501/openmail/MailListRemoteFacade.cfc?method=getNewMailList",
        root:       "messages",
        totalField: "totalCount",
        fields: [
            "messageLink",
            "messageIconLink",
            "sender",
            "sentOn",
            "subject"
        ]
    }

);

// load the data, test the response
ds_newMailList.load( 

    {
        params: {
            authToken: "#url.token_a#",
            devId:     "#aolDevId#",
            referer:   "#succUrl#"
        },
        callback: function( r, o, s ) {
            //alert( s );
        }
    }

);

Listing 2 - JSON Data Feed

{

    "messages": [
    
        {
          messageLink:     "http://www.aol.com/link",
          messageIconLink: "<img src='icon.jpg' />",
          sender:          "lily@example.com",
          sentOn:          "01/22/2008 09:52:06 pm",
          subject:         "OpenMail rocks!"
        },
        
        // ... more messages ...
        
    ],
    
    totalCount: 52
}

Now that we have a good data feed coming in, we can populate a grid control as the final step. Use the code in Listing 2 to create the grid.

Listing 2 - Creating a Grid Control

var grid_newMailList = new Ext.grid.GridPanel(

    {
        store:    ds_newMailList,
        title:    "AOL OpenMail",
        width:    489,
        height:   300,
        renderTo: "grid-new-mail-list",
        footer:   true,
        columns: [
            { header: "",        width: 35,  dataIndex: "messageIconLink" },
            { header: "From",    width: 150, dataIndex: "sender"          },
            { header: "Subject", width: 150, dataIndex: "subject"         },
            { header: "Sent",    width: 150, dataIndex: "sentOn"          }
        ]
    }

);

grid_newMailList.on( "rowclick", function( g, r, e ) {
    
    window.open( g.getSelectionModel().getSelected().data.messageLink );

} );

Much of this code is self-explanatory. We use the store config option to bind the data store we just defined to the grid as well as define some standard options such as a title, dimensions, and the div id to render the control to (grid-new-mail-list). The columns option maps data fields in the store to their representation in the grid by using the dataIndex property. The final touch involves the listening for the rowclick event which when fired uses the messageLink data from the selected row to open a new window, presenting the mail message. See below for a peek at what we just created:

• AOL OpenMail
• Ext JS