The Grade Schooler's Guide to Mach-II Version 1.5 - Part 1 Naked Mach-II

Introduction

Mach-II is a ColdFusion framework that can help you build complex web applications. Recently, the Mach-II developers (see reference 1) released version 1.5. I had previously used the older version of Mach-II and also recently took over a very large web application that uses Mach-II so I want to learn how to use the new features in Mach-II version 1.5. But after visiting the Mach-II website and looking over the documentation, I think it might be helpful to myself and others if I start a "grade schooler's" series of how to install, configure, and use Mach-II version 1.5. Please note, I'm far, far, far from being any kind of Mach-II expert. I've used the older version and I understand most of the basics, but I'm kind of like the junior high school kid who tutors 4th graders on math. If you need expert help, consult reference 6.

This blog entry will just focus on getting and setting up Mach-II version 1.5. In my sample configuration I won't be integrating ColdSpring (see reference 2). Mach-II and ColdSpring work very well together and provide a powerful framework for building complex web applications. But let's start simple, after all this is grade school!

Before I go too far, I do want to thank Dan Wilson and others (see reference 3) for putting together a Mach-II version 1.5 skeleton application and making it available publicly. I used their work to create the Mach-II sample application detailed in this blog entry. Also if you need a really good introduction to Mach-II, read references 5 and 7. Matt Woodward wrote a very good quick start guide to Mach-II and though it's a few years old and doesn't cover version 1.5, his guide can be very useful in understanding the basics of Mach-II. Adrian Moreno blogged an excellent introduction to Mach-II.

Get Mach-II Version 1.5

At reference 1 is a nice big beautiful button that you can click on and download a zip file containing all the wonderful Mach-II version 1.5 files. Included in the files is a readme.txt with instructions on how to install Mach-II. To keep this tutorial simple, I downloaded the zip file and unzipped everything directly into my web root (c:\coldfusion8\wwwroot\). After all the files are extracted I had a new directory in my web root named MACHII.

My Sample Application

I created a new web application, named M2beginner, in a folder named M2beginner. Reference 4 below is a zip file containing all the files in this sample application. Just download this zip file and again to keep everything simple extract all the files to your web root (in my case that is c:\coldfusion8\wwwroot). After doing this you should have a folder named M2beginner directly under your web root.

In the M2beginner folder is an Application.cfc. Per the Mach-II documentation, you should use Application.cfc instead of Application.cfm in your application's root folder to setup your application to use Mach-II. Note that this Application.cfc extends a CFC provided by the Mach-II framework. In addition to the Application.cfc file, you need a file named index.cfm. The index.cfm should not have any code inside it (my index.cfm in this example just contains a comment.

One of the key pieces of the Application.cfc is this line:

This tells Mach-II where to find the configuration XML file that specifies what events Mach-II will handle. There is much more that can go into the configuration file but we'll start simple. Our Mach-II configuration file is named mach-ii.xml and is in the config folder (c:\coldfusion8\wwwroot\M2beginner\config\). I'll write more about the configuration file and events later.

In my sample application is a views folder ( c:\coldfusion8\wwwroot\M2beginner\views\). In the views folder are two .cfm files, home.cfm and exception.cfm. If you've downloaded and unzipped Mach-II version 1.5 and my sample application per the above instructions you can run the following in your web browser and your browser should display the code contained in the home.cfm file.

http://localhost:8501/m2beginner/index.cfm

(of course replace localhost:8501 with whatever you normally use to display a web page in your development environment)

Mach-II Magic

So though my URL specified index.cfm above, my browser loaded the contents of views\home.cfm. That's the magic of Mach-II. If you examine the mach-ii.xml file (c:\coldfusion8\wwwroot\M2beginner\config\) you'll see this line:

The above line specifies that if no event is provided in the URL to execute the home event. You specify an event in the URL by adding ?event=some_event. If you don't specify an event, then Mach-II will execute whatever event you set as the defaultEvent.

Further down in the mach-ii.xml file is this code:

and this code

The event handler code tells Mach-II what to do in response to the home event. In this case it executes the view-page tag. The value of the name attribute tells Mach-II which page view to render (in this case the page view named home). The page-view tag specifies where the page with the name of "home" is physically located (in the views folder) and what it is called exactly on our web server (home.cfm).

So because we did not specify a specific event in our URL, MACH-II executed the home event and in response to the home event Mach-II told ColdFusion to load the home.cfm page.

Summary

We covered how to get Mach-II version 1.5 and set up a very simple sample application. Since it's nap time, that's enough for now. Please remember my caveat above - I'm only at the junior high school level in my Mach-II knowledge so if I've gotten something wrong let me know (gently please I'm young and sensitive).

References

1. Mach-II, http://www.mach-ii.org
2. Bruce Phillips Blog, The Grade Schooler's Guide To ColdSpring - Part 1 Naked ColdSpring
3. Mach-II Version 1.5 Skeleton Application (read down through all the posts on this topic)
4. M2beginner code download
5. Mach-II Quick Start Guide, Matt Woodward
6. Mach-II For ColdFusion Google Group
7. Mach-II Primer by Adrian Moreno