Developer Center Article

Pet Market is a blueprint application that shows you how to build a Rich Internet Application which uses Macromedia Flash MX for the front-end user experience and ColdFusion MX to manage back-end data interactions. Although much of Pet Market highlights the interactive technology inherent in Macromedia Flash MX and ColdFusion MX, there are several areas of the application that rely on Dreamweaver MX. This article introduces you to two ColdFusion Components (CFCs) that are in the application and explains how to create them in Dreamweaver MX.

I assume that you have installed Pet Market so that you can look at these files. If you have not yet downloaded the sample application and would like to look at some of the files in context, download them now.

Using ColdFusion components in Pet Market
CFCs encapsulate ColdFusion code into separate components that a web page can call via functions. There are include files already in CFML and custom tags. What distinguishes CFCs from include files and custom tags is that they can contain data as well as code, and they can be referenced by functions rather than as a whole unit. In short, CFCs allow you to separate important functionality into separate files so you can control the business logic of your application better or centralize the app's data or interfaces.

In the Pet Market application's petmarket folder, there's an api folder that includes several CFCs. Although ColdFusion MX can find CFCs throughout your web site to use in an application, it's considered a best practice to keep your CFCs in one of two places in your site: either a separate folder in the section of the site to which they belong or a folder in the root that's easy for everyone working on the site to access.

The two CFCs that I address in this article include stringresourcesservice.cfc, which concentrates user-interface strings into one file so they can be easily translated without giving the translator access to the logic portions of the application, and addressutilservice.cfc, which allows you to find U.S. cities and states based on entered ZIP codes and vice versa. The stringresourcesservice CFC centralizes the user interface information, while the addressutilservice CFC executes code when called.

Consolidating UI strings with stringresourcesservice.cfc
Localizing a web application requires sending files to a translator. As your application becomes more complex, this task becomes more difficult. If the user interface strings are distributed across multiple files, you have a real issue to contend with when you send out these files because the more people touch them, the greater the chances of introducing typographical errors. To be safe, you'll have to open and change many files or perform complex search and replace operations across multiple files. Furthermore, while these files are with the translator, you can't add or change the logic of the page because you won't have the active set of files. If you do make changes to the logic, you'll need to merge the code changes from the two sets of pages.

Therefore, if you abstract all the UI strings, you won't need to worry about any of this. The stringresourcesservice.cfc file does just that: It removes all strings that the user views in the application into a separate file.

If you open stringresourcesservice.cfc, you'll see that the file is broken into three sections:

• The header of the file with the comments that describe the legal details and a good description of what the file does. When you start to extract functions or strings into CFCs, it's critical to comment the code and provide a good description of what the files do.
• A function called getAppStrings, where all the user interface strings reside. In this CFC, the strings are in two languages, German and U.S. English, but you can have as many languages as you need in the file. This facilitates translation into languages not planned for in advance.
• A function called getAboutUsStrings, which contains all the legal information which is not translated, but which may be necessary to update over the life of the application.

Creating stringresourcesservice.cfc
Creating a new CFC in Dreamweaver MX is simple. You can either open a new blank CFC document with a dummy set of values included or create one using the Create CFC wizard from the Components panel. If you prefer hand-coding everything, then starting with a blank CFC is a great way to go; but creating CFCs from the wizard is the best way for most people.

The Create CFC wizard allows you to create a component, name it, provide tips for the Dreamweaver MX interface to display, and set all your properties, functions, and arguments for each function in one location. Here's how stringresourcesservice.cfc looks, as created by the wizard.

Once you create the framework for the CFC in Dreamweaver MX, you can add the code needed for each function directly in Code view. You will also need to specify what will be returned in the <cfreturn> tag.

In the getStrings function, an argument is defined that the function expects, a new structure is instantiated for the strings, and a set of cases is added that run based on the argument passed to the function. For detailed information on how to work with the CFML code in the examples, check the ColdFusion language references that were installed with ColdFusion.

In the Pet Market application, you can see all the strings in the stringresourcesservice.cfc. For this article, I abbreviate the number of strings that are set up. See the code.

The remaining functions—getAboutUsStrings, getAffiliateStrings, and getLegalStrings—are similar in construction and can be seen in their entirety in the Pet Market application's api folder.

Testing stringresourcesservice.cfc
Although the Pet Market CFCs were developed to be used with Macromedia Flash to build the user interface on the fly, they work just as well in Dreamweaver MX. This offers a tremendous advantage because you can mock up an application quickly to test a CFC's logic without first having to build it in Macromedia Flash, which would entail a number of other construction issues.

To test the string's return function, create a file with a form and one element called "locale" and then a ColdFusion file that calls the component and prints out the results in a <cfoutput> tag set, as shown below:

In the test file that it references, you can use the Components panel in Dreamweaver MX to simply drag out the function from the CFC that you want to invoke. You can specify in Code view what the argument is going to be called and what the CFC is going to return:

In the same file you can add a <cfoutput> tag set to display some of the returned information:

This is a quick way to ensure that you are returning the right strings. In the Pet Market example, you then could have coded your Macromedia Flash MX files knowing that the correct results were going to be returned.

Creating addressutilservice.cfc
You create addressutilservice.cfc the same way as stringresourcesservice.cfc, but there are a few things about it that make it interesting to look at. Addressutilservice.cfc contains two functions: findZip, which finds the U.S. ZIP code of any city and state combination, and getLocation, which determines the city and state based on any given ZIP code. Each function takes an argument passed to it from an interface—where the user enters either the ZIP code or the city and state—and then compares that argument to the ZIP table in the Pet Market database, which contains the names of all U.S. towns with post offices and their corresponding ZIP codes. When you create this CFC in the wizard in Dreamweaver MX, you can add prototypes for both functions and their arguments at one time and then modify them by hand once the CFC is created.

Abstracting the functions that find the ZIP code (or the city and state) makes it very easy for you to change the functionality of any application that uses the CFC, rather than changing each page and application individually. For example, if you ever switched to a database running on another database server that also contained geographical coordinates associated with ZIP codes, you could simply add a function to the CFC which returned the distance between ZIP codes or, by extension, the distance between cities. In an application where the functions are hard-coded into the page, that would be difficult to accomplish and would likely introduce errors.

The getZip function has two arguments that are required to be passed in: city and state. The query finds the ZIP code from the two arguments and returns a string, postalCode.zip, which you can reference on the page or in another query or construction by using a <cfoutput> tag set.See the code.

Resources

• Introduction to ColdFusion Components
• An easier way to create and consume ColdFusion Components and web services with Dreamweaver MX
• Creating ColdFusion web service pages with Dreamweaver MX

About the author
Matt Brown is a Community Manager for Macromedia and technical editor of more than a dozen software books. Matt has taught courses at Foothill College and San Francisco State's Multimedia Studies Program and is a regular speaker at conferences and User Groups.