AOL Pictures CFC

Last week I showed you how simple is it to work up some plain vanilla code to interact with the AOL Pictures API using ColdFusion 8. This week, I'll demonstrate the coldfusion component (CFC) I wrote which manages the entire life cycle of using the AOL Pictures API and then some. If you just want to get the code and explore, you can download it here. The download includes complete documentation on the CFC.

Since ColdFusion 8 is still very new, I decided to incorporate an additional component which supports the encoding/decoding of JSON data for pre-CF8 MX installations, json.cfc, currently maintained by Thomas Messier. This allows the ColdFusion developer to not even have to worry about the translation between JSON formatted data and native ColdFusion structures. It's all taken care of in the AOL Pictures CFC, no matter what version of ColdFusion MX you're running. Let's run through an example of using the CFC.

The AOL Pictures CFC is actually a collection of components within the AOL component namespace. The examples in this post have installed the components at the same directory level as the test page. We'll begin by creating a new Pictures object and setting some configuration options like so:

<!--- create a new AOL Pictures object --->
<cfset obj_aolPictures = CreateObject( "component", "AOL.Pictures" ).init() />

<!--- set the dev id --->
<cfset obj_aolPictures.setDevId( "someAOLDevId" ) />

<!--- we want to restrict all queries to return 5 results for now. --->
<cfset obj_aolPictures.setMaxResults( 5 ) />

Although the code sample above demonstrates just two of the properties you can manage in the Pictures CFC, it does support virtually all of the options of the native AOL Pictures API such as host, category, and album id.

Now that we have a Pictures object, we can query for an album list as follows:

<h1>AOL Pictures</h1>

<!--- get an album list --->
<cfset variables.st_albumList = obj_aolPictures.getAlbumList( "winterWooHoo" ) />
    
<!--- print out links to the albums returned. --->
<cfloop from="1" to="#ArrayLen( variables.st_albumList.albums )#" index="i">
   <cfoutput>
      <a href="#cgi.script_name#?id=#urlEncodedFormat( variables.st_albumList.albums[i].id)#">
         #variables.st_albumList.albums[i].title#
      </a><br/>
   </cfoutput>   
</cfloop>

Basically we query the component for the album list of the winterWooHoo owner, then loop over the result to produce a group of links to the current page. The link includes a query string parameter to pass the album id which we'll use shortly. The output of the above code will look similar to Figure 1 below.

Figure 1 - Output from the getAlbumList method

If you were to dump the data structure returned from the getAlbumList method from above, it should look similar to Figure 2 below.

Figure 2 - Dump of the data structure returned from the getAlbumList method

To access the pictures in a given album, we can run the following code:

<cfif isDefined( "url.id" ) and url.id neq "">
   <cfset variables.st_pictures = obj_aolPictures.getPicturesByAlbumId( url.id ) />
    
   <!--- dump out the pictures --->
   <cfloop from="1" to="#ArrayLen( variables.st_pictures.response.data.pictures )#" index="i">
      <cfoutput>
         <img src="#variables.st_pictures.response.data.pictures[i].sizes[1].url#" />
      </cfoutput>
   </cfloop>
</cfif>

Here we just test to see if we have the id query string parameter available and if it's not empty. Once fed through to the getPicturesByAlbumId method, it's as simple as printing out what we want. The output generated from this code can be seen in Figure 3 below.

Figure 3 - Output from the getPicturesByAlbumId method

And for a scarier picture, a portion of the data structure returned from the getPicturesByAlbumId method may be seen in Figure 4 below.
Figure 4 - Dump of data structure returned from getPicturesByAlbumId

If you'd like to run the full example, I have posted the code on my website here. This example demonstrates just the bare introduction of using this component. I encourage you to download the code and documentation and explore. It offers a very familiar interface to the ColdFusion developer and may be used in any number of implementations. Next week, I'll show you how to feed picture data to an Adobe Flex application using the Pictures CFC.

Links

Topic Centers