ColdBox Series Part IIa - The Website Plan

One of my unwritten goals (plenty was written) for 2009 was to master a new CFML framework. I've used Fusebox and Model-Glue 2 (Unity) over the years but wanted to see what else was out there. After researching a variety of CFML frameworks, I selected ColdBox over cfWheels, Model-Glue 3, and Mach-ii.

Why ColdBox?
Let me say, from the outset, that my selection is in no way a reflection on cfWheels, Model-Glue 3, and Mach-ii. All are excellent and I love the fact that I was struggling to select one amongst all the CFML framework options. It's great to have so many excellent choices in our little community!

ColdBox's selection came down to 4 key elements for me:

1. Convention over Configuration—ColdBox is not alone here but implementing this philosophy was central to my search. The more I work on team projects, the more I appreciate what this approach brings.
2. Standard Web or Remote Access—The same ColdBox application can be used with any type of front-end: HTML, Flex/Flash, AIR, or Ajax interfaces.
3. Toolkit over Framework—ColdBox bills itself as more than a framework, noting that it 'introduces several software application aspects that will help you build your applications faster, debug with ease and much much more.' (TransferORM, ColdSpring, etc.)
4. Documentation—The ColdBox team has done an awesome job building a beefy set of documentation for the framework.

ColdBox Series
I spent some time over the last month reading the ColdBox documentation, playing with some tutorials, and trying a few features of the framework. While that was incredibly helpful getting my head around ColdBox, I always prefer meaningful or realistic tutorials that show me not only the basics of a framework (or language) but also how I would actually use it on a site.

I decided to keep a running set of posts on ColdBox for this purpose; develop a detailed, hopefully, real-world applicable tutorial. How? Well, I'm actually using ColdBox (and recording it in this series) to rebuild my original company site (imageaid.net).

While ImageAid is still my official business entity, I'm transitioning to a new identity for my development work. My wife, however, is an editor and continues to use ImageAid for her business. So, it's really her site :). In part two of this series, I'll outline what features I want to implement on the site, how ColdBox will figure into the plans, etc.

For now, let's get started and install ColdBox!

Development Environment
I am developing on a Mac (10.5.7) with Apache 2.2.9, MySQL 5.0.67, and ColdFusion 8.0.1. I also test and develop against an Apache (2.2.9), Tomcat 6.0.18 and Railo 3.1 (beta) setup on the same machine. Okay, I really do it all on the Tomcat/Railo server and then test on CF8 to ensure it works. What can I say, I love open-source :)!

All that said, everything we're doing should work on Windows and other 'nix variants (system paths notwithstanding), so long as you have either CF8 or Railo 3.1 installed and running.

My IDE is Aptana Studio (Andretti Alpha version), which I love. Aptana is based on Eclipse for those unfamiliar with it (ala Adobe Flex Builder). Naturally, I have the CFEclipse plug-in installed for CFML editing.

Framework Installation
As with most CFML frameworks, installation is easy.

1. Download—I selected the 2.6.3 bundle, which is 5.2 MB.
2. Unpack—Once the bundle is downloaded, unpack it.
3. Rename—Once the bundle is unpacked, rename the resulting folder to 'coldbox'.
4. Move—Copy or move this folder to your web root folder.
5. Mapping—If desired, set a mapping in the CF Administrator, called 'coldbox' and point to your coldbox directory now in your web root folder (this step is optional, but advised).

Application Skeleton
Open the coldbox folder in your web root. You will see a subfolder called 'ApplicationTemplate'. This is important to note because it's the base application structure you need to run a ColdBox application.

You can create a new ColdBox application in one of two ways: (1) copy the contents of this folder to your site/app's directory or (2) run an Ant script to do it for you.

For now, we'll use option 1, copying it manually. I you're interested in the Ant approach, check out the ColdBox documentation on My First Application. Yes, part one of my series is very much akin to this tutorial but will deviate (original content) in the subsequent posts!

Create a ColdBox Application

1. Create a new folder in your web root and name it: cb_learning
2. Copy the contents of the ApplicationTemplate directory (above) to this folder.
3. From the cb_learning directory (or whatever you named it in step 1, above), open config/coldbox.xml.cfm in your editor and add a custom name for your application on line 6 (XML element = Setting name='AppName' value='custom_name_here')
4. Go to http://localhost/cb_learning/ to see the ColdBox skeleton.*

That's it. You should now be running a skeleton ColdBox application!

Next
The next post in the series involves getting comfortable moving around the framework and customizing the views/layouts. I'll also note the features I'll be adding to the real site (imageaid.net) I'm developing alongside this series.

*Your URL may vary depending on how CF is configured on your server.

This post, the second in an on-going ColdBox series, takes a look at the conventions used by ColdBox to bring an application to life. It's more a general overview of the file structure and the purpose of various files/folders than code and samples, which comes in the next post ... really!

ColdBox, like many web application frameworks, uses the Model-View-Controller (MVC) architecture pattern to separate application tasks into those three components types in its name. In brief, the Model is your business logic, the View is the presentation, and the Controller is, basically, a traffic cop, telling everyone where to go and what to do.

However, unlike a number of other web application frameworks, ColdBox enforces "convention over configuration". This convention-based approach is really just a fancy way of saying you have to put your files in certain places based on the file's specific type or function.

I've grown increasingly fond of these convention-based frameworks, having used them for projects built with Ruby on Rails and CakePHP. There's a decent amount of active debate over frameworks and how they set about accomplishing application tasks but there's something about the more rigid structure of convention-based systems that just works for me. Ultimately, I intrinsically know where everything is ... and I like that!

Prior to delving into the framework itself, I think its a good idea to step back a bit and get a sense of the lay of the land, as it were. It's especially helpful with conventions-based frameworks, like ColdBox. In that vein, following is a screen shot of the folder structure for ColdBox's default application skeleton. I'll note the purpose of each folder following the screen shot (below).

Mini-tangent: Before I get into the directory structure, I would highly recommend taking a few minutes to read, at least, two sections of the ColdBox docs:
General Overview
Request Lifecycle

Application Skeleton File Structure

Application Files (in root directory)

• Application_noinheritance.cfc—the main application file, it does not extend the system's coldbox object.
• Application.cfc—the main application file, extends the system's coldbox object
• build.properties—this is for using Ant scripts, you can most likely just dump these (unless you plan to run Ant scripts.
• build.xml—same as above, it's for Ant scripts.
• coldboxproxy.cfc—this file is called and used when your ColdBox application is used as a model framework (from an Ajax or Flex front-end, for example)
• favicon.ico
• index.cfm—a placeholder file, all action happens in the Application.cfc
• readme.txt
• robots.txt—a base robots file for search engine spiders, it keeps the search engines from indexing content we don't want it to see.

Application Folders

• config—this holds configuration files (settings, not logic) for your app. There's typically little work to do here (DSNs, etc.) ... unless you're using things like ColdSpring, Transfer, or Lightwire.
• handlers—this holds the controllers (CFCs) of our application. They receive instructions from the system and control the application (get data, show the data, etc.).
• includes—items you will include in your application, such as, images, css, etc.^
• interceptors—an interceptor does what it name implies: it intercepts the processing of a request and performs its action, adding functionality to the request (like enforcing security for part of your application). They also act as broadcasters/listeners, which can really extend your application ... but that's beyond our scope right now!*
• layout—your layout (page) templates, they show content generated in the views in the browser (phone, etc.).
• logs—a location for ColdBox to store log files.*
• model—business logic objects (beans, DAOs, gateways, and the like) are stored in this folder.
• plugins—custom plugin location.*
• test—test scripts.*
• views—all view files, these generate our content, which will appear, most often, in our layout files.

*optional
^optional but you really should have it.

Tomorrow or Wednesday, I am going to add the next post in the ColdBox series. That post will end with a custom layout file for the project's website. We'll start with the layout file generated by the application skeleton and turn it into our own. Along the way, we'll briefly touch on event handlers and models but, mostly, we'll work with layouts, views, and viewlets.