What’s this all about?

In the past few days, I’ve been taking on the task of setting up the Mach II framework and the ColdSpring framework for application development in Adobe ColdFusion. I’m evaluating these two offerings, hoping they can help speed up the development of new web apps by our team at work. Plain old ColdFusion development does a decent job, but this lament by Jacob Kaplan-Moss points out what’s wrong with it. The current state of affairs with CGI-style development, whether it’s using PERL, Python, ColdFusion, or shell scripts is just too clunky. There has to be something better. For example, in the content-management system world, Joomla offers all kinds of straightforward ways to mash up various kinds of content: rss, calendars, etc. Why not our so-called industrial strength app servers? I hate to think we’re stuck hacking away at glorified CGI scripts.

Maybe Mach II can make this next-generation capability available for the ColdFusion world. Combined with the ColdSpring framework (a CF version of the Spring Dependency Injection Framework.) It’s worth a try. And the Mach II Dashboard is a useful addition for getting real work done.

But getting all this stuff set up right is a little challenging for a newbie.  You need to figure out how to throw the axe at the dwarf  before you can really get into the cave (I guess I’m showing my age).

What do you need?

You’ll actually need six chunks of software stuff installed on your development machine to try out Mach II properly.

  1. A proper web server like IIS or Apache
  2. The ColdFusion distribution kit. I worked with Version 8. (Version 9 Beta also works, I believe, but you have to hotfix it to get Mach II to work.  That might not be worth your trouble at this point.)
  3. The Mach II distribution zip file.
  4. The Mach II skeleton application zip file.
  5. The Mach II Dashboard zip file.
  6. The ColdSpring framework zip file.

None of these cost extra money to evaluate; a ColdFusion developer license is free, IIS (or PWS = IIS lite) comes with your Windows OS, and the others are open-source.  (I did this on a Windows machine; it surely works on Max OSX and on Linux or BSD as well.)

What are the steps to getting set up?

Get your chosen web server working on your machine.  Follow the directions that come with the web server.  I used Apache 2.2, but you can use any version of Apache or the Microsoft-furnished server.  (You can also skip this web server step entirely if you want and use ColdFusion’s built in server configuration.  But that’s not how I did it.)

Figure out the location of your server’s document root directory.  The rest of these steps involve getting the contents of that directory set up right, so make sure you know where it is.  With IIS the root directory is called wwwroot.  In my Apache setup it’s called htdocs.

Install ColdFusion following the product’s directions, licensed as a developers’ package. If you do this right here’s what you will see in your web root directory:

+---htdocs
|   +---cfdocs
|   +---CFIDE

You may also see some web server related files like index.html or default.html.  But these are the two folders needed by ColdFusion.

Try accessing your ColdFusion administrator at http://localhost/CFIDE/administrator/index.cfm just to make sure all is well.

Next, you need to unzip the Mach II distribution zip file into your web server document root.

Once that’s done, unzip the skeleton zip file.  Be careful with this installation: the skeleton zip file has this directory structure inside it:

+---skeleton
    +---skeleton
        +---config
        +---filters
        +---img
        +---listeners
        +---model
        +---modules
        +---plugins
        +---properties
        +---views

Notice that there’s a second level skeleton directory inside the first.  You want to install the second level one in your web root.

Install the dashboard files too.  Your web root directory should look like this.

+---htdocs
|   +---cfdocs
|   +---CFIDE
|   +---MachII
|   +---MachIIDashboard
|   +---skeleton

Now you need to install the ColdSpring framework zip file.  This zip file has the opposite problem to the skeleton file; its contents are not in any subdirectory.  So first create the ColdSpring directory in your web root directory, then unzip the ColdSpring file into it.  Now you should have a web root that looks like this:

+---htdocs
|   +---cfdocs
|   +---CFIDE
|   +---ColdSpring
|   +---MachII
|   +---MachIIDashboard
|   +---skeleton

That takes care of installing your software.  What you have installed is this, just to recap.

  • A web server and ColdFusion application server.
  • The Mach II Framework.
  • The Mach II skeleton application.  This is the thing you can run by looking at it with a web browser.
  • The Mach II Dashboard Module.  This is a helper module.
  • The ColdSpring dependency injection framework.

Go ahead: try to run the skeleton program by pointing your web browser to http://localhost/skeleton/index.cfm .  At this point you should find that ColdFusion throws an error grumbling about some obscure file with the name CHANGEME someplace in its path.  It looks like we need to do a little configuration.

What configuration is needed?

Before you can actually run this all this stuff, you need to do a little bit of configuration.  Every Mach II application (the skeleton is our current example) has an XML configuration file controlling how it works.  The skeleton application’s file is located at

htdocs/skeleton/config/mach-ii.xml

We need to open that up in a programmer’s text editor and make a few simple edits.  First, let’s set up the skeleton’s applicationRoot path correctly.  Look for the line near the beginning of the file that says

<property name="applicationRoot" value="/CHANGEME" />

and change it to

<property name="applicationRoot" value="/skeleton" />

Now, try running the skeleton program again: http://localhost/skeleton/index.cfm .  You should see a web page announcing the skeleton app. It’s working at this point (at least, it should be).

But it’s grumbling about ColdSpring not being installed correctly.  So another edit to the configuration file is needed.  Find the line that says

<!-- <include file="./mach-ii_coldspringProperty.xml" /> -->

and strip off the comment tags so it says

<include file="./mach-ii_coldspringProperty.xml" />

Now you’ll find that the ColdSpring grumbling is gone.

Finally, we need to enable the Dashboard module.  This is done by including it in the <modules> section of the configuration file. (These instructions are simplified from the Dashboard documentation.)  Insert this stanza of XML right before the <properties> stanza.

<!-- MODULES -->    
  <modules>
    <module name="dashboard" file="/MachIIDashboard/config/mach-ii_dashboard.xml">
      <mach-ii>
        <properties>
          <property name="password" value="PASSWORD" />
        </properties>
      </mach-ii>
    </module>
  </modules>

Substitute the password you want to use to access the dashboard for the PASSWORD value.

Finally, you’ll be able to access the dashboard, which is installed as a module in your skeleton app.  To get to it, point your browser to http://localhost/skeleton/index.cfm?event=dashboard:info.index . You should get a page inviting you to log in to the dashboard.  Success!

Notice the way that URL is put together: the desired part of the application is included as an event parameter to the index.cfm page.  This gives a hint about how Mach II works.  But that’s for another day.

Do you want a shortcut?

If you want a shortcut to all this, you can try downloading this zip file and installing it in your web root.  But be careful — it is just a snapshot of the web root I set up, and I am no authority.

What’s next?

Watch Matt Woodward’s Head First presentation.

Copy the skeleton directory in your web root (and its contents) to the directory HelloMachII, then go work through The Mach II Application Skeleton presentation in the Quickstart Guide.

Permission is hereby granted to use this material for any purpose and without fee.

Advertisements