Cairngorm for ColdFusion Developers (Part 1)

Welcome to the first edition in "Cairngorm for ColdFusion Developers," a series of blog entries focusing on helping ColdFusion developers learn to write well-architected Flex applications by using the Cairngorm framework.

Yep, it was originally "Cairngorm for Model-Glue Developers," but I figured it'd be better to target everyone. I'm still going to relate some pieces back to examples from Model-Glue, but they'll come with plenty of explanation.

Introduction

This edition of Cg4Cf is going to start from nothing: I'm assuming you may not even have Flex Builder installed. If you've already done some Flex work, this may not be the most exciting read, but I need to make sure we're all on the same page.

Our goals are as follows:

  1. Install Flex Builder 2.0
  2. Download and "Install" Cairngorm
  3. Create a Flex project that links to Cairngorm

Installing Flex Builder

There's no need to give an in-depth on this one. If you've got a PC, download and install the Flex Builder trial from http://www.adobe.com/products/flex/flexbuilder/. At the time that I'm writing this, if you have a Mac (and I just got mine, and it's awesome, and I'll be using it for the next entry in this series when my extra RAM arrives), you'll need to get the Beta of Flex Builder 2.0 from Adobe Labs at http://labs.adobe.com/technologies/flexbuilder2/.

Special note for Eclipse/CFEclipse Users

If you use Eclipse or CFEclipse, I highly recommend doing the "plug-in" download installation of Flex Builder 2 instead of the standalone. The standalone seems to be missing a few things from the jdt package (whatever that is) that some other plugins, like Subversive, need.

Once you installed Flex Builder 2, make sure it runs. I can't provide installation support any better than what the product comes with.

Downloading an "Installing" Cairngorm

Ok, I'm going to go "uninstall" Cairngorm to make sure I walk through the steps correctly.

*clicking*

That's better. Now, head over to http://labs.adobe.com/wiki/index.php/Cairngorm so that we can download Cairngorm. I'd link directly to the file, but 1) it could go 404, and 2) this is an important site to know about if you want to do Cairngorm development.

On the page, there should be a link on the page for downloading Cairngorm 2.1 for Flex 2. That's what we're after, so download it, but don't unzip it.

Instead of unzipping, start up Flex Builder 2.

Then, go to File -> Import. Choose "Existing Projects into Workspace." Check the radio button beside "Select archive file:", click "Browse...", and select the .zip file (probably cairngorm2_1.zip) that you downloaded. Click Finish.

Flex Builder will chug for a minute, then, presto: you've got a project named Cairngorm.

Create a Flex project that links to Cairngorm

For our final bit today, we'll make sure we can create and compile a project of our own that links to Cairngorm.

First, do File -> New -> Flex Project.

Choose a "Basic" project - we're not going to deal with Flash Remoting at this time. When we do, we'll add the appropriate compiler options by hand, because we're l33t.

For "Project Name," enter "CG4CF".

For "Project Location," enter a directory named "CG4CF" that's directly off of your web root. For my bastardized Apache-on-an-ex-IIS-box, that's c:\inetpub\wwwroot\CG4CF.

Go ahead and click finish. While we could link to Cairngorm from within the wizard, it's important to get to know the Project Properties dialog.

At this point, you should have a project named "CG4CF" in your Flex Builder's "Navigator" window, CG4CF.mxml should be highlighted, and CG4CF.mxml will be open.

Note: you may have a problem show up in the "Problems" pane of Flex Builder 2 stating "unable to open C:\dev\swat\projects\ac_emea\Cairngorm\buildlib". Ignore it. Learning why it's there and getting rid of it is extra credit.

To make sure we have Cairngorm up and running, we're going to screw up, make sure we get the right kind of error, and then fix the error by linking to Cairngorm.

In CG4CF.mxml, we're going to add an import statement importing a class from the Cairngorm framework. Copy/paste the following code into CG4CF.mxml, replacing all existing code:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">

<mx:Script>
    <![CDATA[
     // Import the ModelLocator class.
    
     // If Cairngorm isn't linked, compilation will fail.
        
     import com.adobe.cairngorm.model.ModelLocator;
    ]]>
</mx:Script>

</mx:Application>

Save the file. Flex Builder 2 should pause for a moment while it compiles. If it doesn't, make sure Project -> Build Automatically is checked.

After Flex Builder 2 tries to compile your project, you should have an error:

1172: Definition com.adobe.cairngorm.model:ModelLocator could not be found.

That's because we told our project to use a class from Cairngorm, but we didn't tell our project where to find the class.

Cairngorm ships as a precompiled package, sort of like a .JAR file in Java. Once we include that in our compilation path (sort of like class path), classes defined in that package become available.

To include Cairngorm in our compilation, do the following:

First, right-click the CF4CF project's name (the letters CG4CF, not CG4CF.mxml) in Flex Builder 2's Navigator pane and choose "properties."

Then, click "Flex Build Path" in the options listed on the left.

Third, click the "Library path" tab.

Click the "Add SWC..." button. Browse to the location of the Cairngorm.swc file in the Cairngorm project we created earlier, select Cairngorm.swc, and click open. For me, that's c:\Documents and Settings\Joe\My Documents\Flex Builder 2\Cairngorm\bin\Cairngorm.swc. You can find the exact location of your Cairngorm.swc file by opening the Cairngorm project, opening the "bin" folder, right-clicking Cairngorm.swc, choosing "Properties", and looking at the "Location:" information.

Once you click open, it's likely the "Add SWC" dialog will simply list "${DOCUMENTS}\Cairngorm\bin\Cairngorm.swc" - that's perfectly fine, go ahead and click Ok. Once you click Ok, go ahead and click Ok again on the Project Properties (Properties for CG4CF) dialog. Flex Builder will blink a dialog saying "Updating compiler settings..."

Once it's done, the "1172: Definition com.adobe.cairngorm.model:ModelLocator could not be found." problem should disappear from your Problems pane. Your project has just compiled.

To double check, click the green Play button at the top of Flex Builder 2 (or do Run -> Run CG4CF, or CTRL-F11). Firefox should appear, and you should get a blank grey window. If that's all you get, everything's good. If you get an error message, step back through this tutorial and make sure everything has been followed. If Internet Explorer opens...well...that's OK, but it means you're in the 20% of my readers still using IE, and you wouldn't want to not fit in, would you?

Conclusion

That's it for the first edition of Cg4Cf. We've installed Flex Builder (Well, you did. I already had it.). We've downloaded Cairngorm, and learned how to link to it from another projects, making sure it's included when we compile.

Next time will be more fun, I promise! We're going to learn about the Model Locator pattern, which lets us centralize storage of our application's data in a nice, decoupled, thoroughly good-OO manner.