ColdBox Series Part I - Getting Started with ColdBox

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:

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.
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.
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.)
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.

Download—I selected the 2.6.3 bundle, which is 5.2 MB.
Unpack—Once the bundle is downloaded, unpack it.
Rename—Once the bundle is unpacked, rename the resulting folder to 'coldbox'.
Move—Copy or move this folder to your web root folder.
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

Create a new folder in your web root and name it: cb_learning
Copy the contents of the ApplicationTemplate directory (above) to this folder.
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')
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.

Comments

Craig Kaminsky

@Anonymous - I'm afraid I cannot help here. ColdBox has changed significantly since this was posted and I am no longer writing ColdFusion apps. Apologies for the inconvenience.

Anonymous

config/coldbox.xml.cfm i am not getting this file under config folder?

Craig Kaminsky

Thanks Jose. I'll be getting back on the blogging horse next week. I broke my wrist on May 18 and it was a bit too much to keep coding/working with one hand and blogging! But the cast comes off next week and I should be back to real typing then :).

In the meantime, I'd be happy to help you with your Mac setup. I played around with mine for 2 years before I was happy but now I love it!

Send me an email (craig.kaminsky at gmail dot com) and I'd be happy to help. You'll love having CF integrated into your Apache install!!

Oh, I do have a couple of posts on this (check the labels for Apache and Tomcat).

Jose Galdamez

I'm definitely going to have to follow your progress as you move along in learning ColdBox. I watched an introductory presentation on it at last year's CF United. I lost track of what was going on about halfway through cause I kept running into terms I had no clue about. I've made some progress since then, but I haven't made the time to pick up ColdBox and start from the basics. I think reading your posts will help me when I make the initial transition fairly soon.

I am currently intrigued by how you've got your set up going. I too run on a Mac at home. My current speed bump will be setting up the dev environment correctly. Sure, I could take the easy way out, install CF8 and use its built-in web server, which is how I've always done it in the past. What I really need to do, though, is get on the ball, learn how to set up Apache and make it flexible enough so that if I wanted to set up other servers such as Railo or PHP I could do it all from the same code base (like you've managed to do).

A lot of this stuff is still new to me (I had to google "Tomcat" to remind myself what it was *bows head down*). It'll take some time, but I'm definitely looking forward to what I'll be learning in the coming months.

Thanks!

Craig Kaminsky

Wow! That may be the first and last time I am at the top of Google!! Working on integrating BlazeDS into my Tomcat install...then, connect to Railo/Flex apps. Ugh, my head hurts from all this :)

gfranklin

Haha, I just found your article just before I saw your response to my comment. Incidentally, if you google "railo tomcat mac", your article comes up first in the results! I'm gonna check it out now! Thanks!

Craig Kaminsky

Thanks, Greg! I've got an entry from a bit back on Railo/Tomcat/Apache:
http://craigkaminsky.blogspot.com/2009/04/full-integration-apache-2-tomcat-6-and.html

It has links to better-written articles on Tomcat/Railo where necessary but let me know if it doesn't help or get you enough details.

The 'best' part right now is that I can run and test CF8 and Railo 3.1 side-by-side, from the same code base. Apache Virtual Hosts, with custom domains (dev.site.local for Railo and dev.site.com for CF were the key :).

gfranklin

Great article. I'd be interested to know how you set up tomcat/railo on the mac. Especially since you are able to boil things down into an easy-to-digest step-by-step process.

ColdFusion Zipper - Utility to Zip and Deliver a Collection of Files and/or Directories

Lately, I have come across an increasing number of posts on the Adobe ColdFusion Forums, whose subject I think would result in a nice utility or great learning exercise. Typically, when I get inspired to write a little utility, it's ColdFusion stuff I know but rarely use. A forum post earlier this month spawned another, mostly useless :), utility for zipping and delivering a set of files and/or directories.

[I would have posted this much sooner but broke a wrist on May 18. Since I'm typing one-handed, things are moving slower and my post and examples might not be as detailed as they should...sorry!]

Zipper:
Zipper is a collection of four CFCs and a log file, which, creates a Zip archive from a specified collection of files and/or directories. Once the archive is created, Zipper will deliver it to the requester in one of three ways: (1) downloading to the user's system (prompting the user to save the file, of course); (2) saving it to disk (the server) and returning a download link to the archive, and (3) saving the file to disk (server) and emailing it to a specified recipient.

In instances (1) and (3), the zip archive is deleted from the file system (server) upon completion.

NOTE: I used CFTHREAD to delete the archive from the file system/disk when it's being delivered to the browser for download. CFTHREAD was the best approach for deleting a file served by the browser because, without it, the archive would not delete. As a result, ColdFusion 8 or Railo 3.1 is required (earlier versions of Railo might work -- tested on 3.1).

Files:
ZipperBean.cfc -- The properties and getters/setters for Zipper
Zipper.cfc -- Extends ZipperBean, which was done to keep file size down and make development/coding easier
EmailVerifier.cfc -- My Email Verification utility, used to verify an email address when sending an archive by email
Logger.cfc -- A simple logger CFC for recording errors
zipper.log -- A default log file

Installation:
Installation is pretty simple, drop the above four files into the same directory in your site. I use a directory called 'zipper'. You can, if it's easier or better for your development and/or production environments, place in a directory that is globally accessible in all applications via a CF Administrator mapping.

Configuration/Usage:
Technically, Zipper doesn't require any configuration, it only requires an array of file/directory paths (must be absolute paths) sent as a parameter to the zip method.

Zipper will try to help you by setting default storage locations and URL paths based on the calling template's directory but that doesn't always work as expected or desired. As such, you should probably set a few properties (path to save archives, for example) to be sure it runs as expected.

Following is a sample usage of Zipper on a form processing script:


// this script assumes a form has been submitted to it. 
// That form contains a series of checkboxes with same id (filesToDownload) whose individual values are full paths to directories or files)
// store files & directories for zipping in an array
if( StructKeyExists( form, "filesToDownload" ) )
{
        files_to_zip = ListToArray( form.filesToDownload ); 
}
else
{
 files_to_zip = ArrayNew(1);
}

// set up local path variables based on OS and directory of calling template. 
// Not required but I like such variables b/c I can move b/w environments with ease (read: no recoding!)
slash = IIf( server.os.name contains "windows", De( '\' ), De( '/' ));
thisDir = ExpandPath( '.' ) & slash; // current directory but has no trailing slash, so we add it

// instantiate the zipper object -- the path is based on the zipper folder being either at the web root level or a CF Admin mapping. 
zipper = createObject( 'component', 'zipper.Zipper' ).init();// this returns an instance of the Zipper object

/* 
* configure zipper: all props are optional & are accessed with getter/setter methods (i.e., getProperty_name())
*
* props (defaults) // description
* files_to_zip (ArrayNew(1)) // the full-path refs to files and/or directories to be zipped
* zip_archive (CreateUUID() & ".zip") // a default archive name, which you may want to set yourself!
* delivery_mechanism ("disk"); // browser, email, or disk
* save_location (ExpandPath( '.' ) & slash) // where to save an archive on the disk, which you may want to set yourself!
* slash ("\") // OS-specific path separator
* log_file (ExpandPath( '.' ) & slash & "zipper.log") // default log file
* save_url ("/archvies/") // url for retrieving archive on disk, assumes a folder called archives exists at the web root (or CF mapping), which you may want to set yourself!
* recursive (true) // include subdirectories when passing in directory paths
*
* ALL EMAIL PROPS SHOULD BE SET WHEN DELIVERING ARCHIVE VIA EMAIL (else fail!)
*
* email_sentby ("address@email.com") // email from
* email_subject ("Requested Files") // email subject
* email_message ("The files you requested are attached in the .zip format.") // email message
* email_recipient ("address@email.com") // email recipient
*
*/

// configure instance of Zipper
zipper.setSave_url( '/archives/' );
zipper.setSave_location( thisDir & 'archives/' );
zipper.setLog_file( thisDir & 'zipper/zipper.log' );
zipper.setDelivery_mechanism( 'disk' ); // default is 'disk' but here for example
// zip the files
result = zipper.zipFiles( files_to_zip );

// output result - delivery_mechanism is disk, so it's either a URL or 'failure'
if(result is not "failure"){
response = "Download the Archive";
}else{
response = "WTF?!? No file to download.";
}

#response#</cfouput></pre>
zip() Result:
Because Zipper does one of three things with the created archive (delivers by email, delivers to the browser, or creates a link), it wasn't possible to use a simple boolean value to indicate failure or success.

A string is returned and contains one of several values based on the delivery mechanism. In all cases, the string 'failure' is returned if the execution, well, fails!

Save Archive to Disk
Returns a URL-formatted string to the archive (to download).

Send Archive in Email
Returns the string 'email' to indicate it was delivered via email.

Send Archive to Browser for Download
Returns the string 'browser' to indicate it was delivered to the browser.

Where Da Code At?
I'm actively (no, really, I am) rebuilding my two business sites. For now, I have a project page at my ImageAid site (running Railo 3.1 on Tomcat 6.0.18). It's very dull (no design yet) but has a list of my open-source projects which you can select and download. This section is under current development as well, meaning examples and documentation are still to come.

Of course, the form processing uses Zipper to create the archives on the fly :)!
Get the Code</div>
Comments


Craig Kaminsky

I finally got a second to properly setup my S3 bucket. The files are located here:
http://s3.amazonaws.com/oss-projects/cfzipper.zip

Thanks!
Craig


mitchell

I would also like a copy of these files. Are they posted somewhere?


Craig

Did this ever get made live?


Craig Kaminsky

Ugh! I had to move my site. Sorry about that. If you subscribed to the comments, I'll try to get this online today or tomorrow so you can use it, should you like.

Again, sorry about that!


Anonymous

The  'Get the code' link to www.imageaid/projects doesn't work for me. It won't allow me access.... Tant pis!

ColdBox Series Part IIa - The Website Plan

This post is more for me than anything else. If you're following my ColdBox series, it's probably worth a perusal but otherwise, ignore this post.

Following is a brief overview of what features I plan to put on the ImageAid site that I am building alongside this tutorial. My intent is to be able to refer back to this post so that I don't forget something. Not that such a thing would ever happen in the development world!

I have a template of the site's UI and will break down the features based on this template. A screen shot follows but you can also view it online at staging-imageaid.aptanacloud.com/.

Features
The site will consist, essentially, of the following features:

Pages—Home, Services, Projects (this will be renamed to Clients), and Contact (from the top navigation) are all pages, as are Terms of Use, Privacy Policy, and Sitemap (from the footer)
Plugins—pages can have plugins; basically additional resources to show on a page (outside of content). The services page is a good example of a plugin (so is the client page). The page will have a write up of the services but we want each service in its own DB table to output a list of them on both the services page and the featured services call out on the homepage.
Grammatics—currently called 'News', this will be a grammar blog. Recent posts will show where you see the Recent News sidebar.*
Grammatics subscription—ability to sign up for RSS feeds from the blog.*
Grammar tips—little tips will appear on interior pages ala the 'Our Featured Services' box on the homepage*
Clients sidebar—provides quick access to the client details page, which will show recent projects completed for that client.
Contact forms/processing&mdashwhat good is a website without the ability to have a visitor contact you!?
Two layouts—we'll use two layouts on our site. The homepage (below) and a modified one for interior pages

* The Grammatics blog will be powered by Mango Blog but I won't be using their interface; rather, I'm going to attempt to use the Mango admin system and the blog's API to output on the site. This may well be an awful idea, so I'll see how it goes when I get there.

Design Screen Shot

The DDL
What website would be complete without a DB? Exactly! I'll be posting the DDL in Part III or Part IV of the series when we go to install it.

I think that's a decent overview of where I'm headed with this series. Again, apologies for the very dull post but I thought it important to lay this out so that I stay on track!!

Part IIb (getting comfortable with ColdBox Conventions and Customizing Layouts) is coming over the weekend. I'm trying to get these up quickly but broke my wrist just about 2 weeks back (stupid beer league softball)! I have to code and type with one hand, and it's not even my dominant hand, so it sometimes frustrates me and slows me down.

I finally got a second to properly setup my S3 bucket. The files are located here:
http://s3.amazonaws.com/oss-projects/cfzipper.zip

Thanks!
Craig

mitchell

I would also like a copy of these files. Are they posted somewhere?

Craig

Did this ever get made live?

Ugh! I had to move my site. Sorry about that. If you subscribed to the comments, I'll try to get this online today or tomorrow so you can use it, should you like.

Again, sorry about that!

The 'Get the code' link to www.imageaid/projects doesn't work for me. It won't allow me access.... Tant pis!

ColdBox Series Part I - Getting Started with ColdBox

Comments

Disclaimer

Author

Craig Kaminsky

ColdBox Series Part I - Getting Started with ColdBox

Comments

Disclaimer

Older · View Archive (109)

ColdFusion Zipper - Utility to Zip and Deliver a Collection of Files and/or Directories

Comments

Newer

ColdBox Series Part IIa - The Website Plan

Comments

Author

Craig Kaminsky