Setting up a ColdBox Application - ColdBox Series Part 2

I guess I am making this a series. Well, let's get started.

I am not going to start with the typical "What is a MVC Framework" or "ColdBox is..." kind of posts. For two reasons:

  1. No one wants that, we want to jump right into structure and code, right?
  2. You can already read those things:

In this series we are building a To-Do List application using ColdBox and ColdSpring.

Installing ColdBox

Download ColdBox and place the files inside of a /coldbox folder either in your web root or in a ColdFusion mapping called /coldbox.

Installing ColdSpring

Download ColdSpring and place the files inside of a /coldspring folder either in your web root or in a ColdFusion mapping called /coldspring.

UML Diagram

So the first thing we need is our UML diagram that shows our model. I have chosen to go with diagram number 1.2 from my first post. From this we can construct our database that we will use to persist the data in our application.

As a refresher, here is the model diagram:


So we have two domain objects, one representing our To-Do lists and one representing the items inside those lists. Each of these objects will need to be persisted in our relational database. Here is an Entity Relationship Diagram I have created to represent these objects in a relational database.

And here is the SQL to create these tables in MySQL

USE `todo`;

-- -----------------------------------------------------
-- Table `todo`.`lists`
-- -----------------------------------------------------
`name` VARCHAR(50) NOT NULL ,
`priority` INT NULL ,
PRIMARY KEY (`listid`) )

-- -----------------------------------------------------
-- Table `todo`.`items`
-- -----------------------------------------------------
`title` VARCHAR(45) NOT NULL ,
`listid_fk` INT NOT NULL ,
PRIMARY KEY (`itemid`, `listid_fk`) ,
INDEX fk_items_lists (`listid_fk` ASC) ,
CONSTRAINT `fk_items_lists`
FOREIGN KEY (`listid_fk` )
REFERENCES `todo`.`lists` (`listid` )

After you have created the database, go to your ColdFusion administrator and set up a DSN. I called mine "todos" and I will be using that DSN name going forward.

Folder Structure

The way I have my development environment set up, I give each of my projects a domain name on my local machine. So this project will be located at http://todos:81/ on my local machine. I set this up using my HOSTS file in windows and Apache Virtual Hosts. I am not going to go into detail about how to do this in this post, if you would like help setting this up, email me with my contact form. Maybe someday I will create a connect preso or post about how to do it.

So I will start by creating a project in Eclipse (I trust you know how to do this). Here is what my project looks like:

/Documentation is for my UML diagrams, SQL scripts, changelogs, etc.
/test is for my unit test (This part is new for me)
/web is my web root.

In this project we will be putting a lot of stuff in the web root that you may not want to, normally. I am doing this because it is easier to start with and because this is how we would do it in a shared hosting environment.

So now to add the structure of our ColdBox application. Inside of the "/web" folder (my webroot) I am going to add the folders from the ColdBox Application Template in the ColdBox download. I have zipped up the template and you can download it here or you can get it from your copy of ColdBox.

/config - For our Config files for ColdBox and ColdSpring
/handlers - For our event handlers (more on this later)
/includes - This is where our generic error template, CSS and JavaScript files go
/interceptors - This is for interceptors (duh), but we won't be using it (yet). /layouts - This is where our page templates go
/logs - ColdBox Log files
/model - For our service, gateway and beans
/plugins - Like interceptors, we are not going to use plugins just yet /views - Individual views will be placed here

To learn more about the directory structure, go here

Now we're also going to go through and delete several files from this template. In each of the new folders there is a text file telling you what goes in there (e.g. Place your Handlers here.txt), delete those. Also, delete build.xml, readme.txt and the .project file (unless you set up the template as a project of its own, but since mine is just a folder within my project, I do not want the .project file.

You'll notice there is an Application.cfc and an Application_noinheritance.cfc, if you we able to place the /coldbox directory in your webroot or you were able to create a mapping called /coldbox, then you should be fine using Application.cfc and you can delete the other. However, If you could not place /coldbox at the root and you cannot create a mapping, then you will need to use CF8 Application specific mappings to create a /coldbox mapping and then use the Application_noinheritance.cfc by renaming it to Application.cfc.


So this is how we set up our Application Structure. You should be able to browse to your web root for this project, in my case it would be http://todolists:81/, and get a Welcome to ColdBox Message.

In my next post we will modify our default event handlers.

mcaulay's Gravatar YAY...welcome to ColdBox!! achieved, gonna go and do some research on the directory structure and have a poke about with ColdSpring in the meantime.
# Posted By mcaulay | 9/29/08 4:17 AM
Luis Majano's Gravatar Great Stuff!!

I will be adding it as a resource to the Wiki!! Keep 'em coming!!
# Posted By Luis Majano | 9/29/08 8:08 PM
Josh Highland's Gravatar Thanks for posting this Jason. I am looking forward to more of your tutorials
# Posted By Josh Highland | 10/1/08 4:07 PM
Doug's Gravatar Thanks for this series! Write on.
# Posted By Doug | 10/2/08 9:18 PM
Jason Dean's Gravatar Thanks for the comments everyone. I appreciate you taking the time to read the posts. Going forward I would love to hear your thoughts on quality, or to try to answer any questions you have (except for Luis, I am not going to try to answer your questions) . ;)
# Posted By Jason Dean | 10/3/08 8:14 AM
Joey G's Gravatar I love these blog tutorials (blogtoots), I was especially happy to find the answer to one of my questions, and that was how to create a ColdBox project in CFEclipse.

# Posted By Joey G | 7/29/09 9:47 PM
BlogCFC was created by Raymond Camden. This blog is running version 5.9.1. Contact Blog Owner