Learning ColdBox: I

So...my first step is going to the ColdBox site to download the framework: http://www.coldbox.org/download. I created a coldbox directory directly under wwwroot. For now, I'm going with my idea of a Philosopher Battle game (see yesterday's post). (BTW, as Phil Nacelli pointed out, ColdBox comes with several sample applications already! Why not just one of these? See below...) So, let's start with creating a "Philosophy Game" app.

I want to do about as little as possible to get the app working. (BTW, if you just browse to the coldbox/ApplicationTemplates/SuperSimple/index.cfm, you can test to see if your setup is working.) I begin by copying coldbox/ApplicationTemplates/Advanced and renaming it to philosophy. Why the Advanced directory? Just a guess that, as I make the app more complex, I may find some sample code in there that will be helpful. (Throughout this exploration, I expect to make a lot of mistakes. I'm counting on you helpful guides to set me -- and all of us -- straight.)

I read through the excellent tutorial Jason Dean has beginning at http://www.12robots.com/index.cfm/2008/9/21/Building-an-Application-with-ColdBox-and-ColdSpring--Part-1. As I understand it, the ApplicationTemplates is where my individual sites can be created. At least, this is one way of doing it, I believe?

Question: can I take the philosophy directory and move it to the web root? If so, what do I need to do to make that work?

UPDATE: See Luis' response: moving the app to the web root is really simple. Nicely done, ColdBox!

While I'm awaiting an answer on that, I'll open up philosophy/config/Coldbox.cfc. My understanding is that's where the configuration stuff goes. In the past, ColdBox used an XML file (and still supports that, I believe?), but the move from XML is, for me at least, most welcome.

There's a single configure method that we'll use to individualize the philosophy application.

// coldbox directives
coldbox = {
//Application Setup
appName 		= "philosophy",
eventName 		= "event",
...

Within the configure method, I've exchanged the default appName value for my own: philosophy.

The next section is for development settings:

//Development Settings
debugMode               = true,
debugPassword           = "",
reinitPassword          = "",
handlersIndexAutoReload = true,
configAutoReload        = true false, // see Luis' comment below

I've changed some of the defaults here: my understanding is that these are good for development?

The next section, Implicit Events, looks like this:

//Implicit Events
defaultEvent            = "philosophy.index",
requestStartHandler     = "Main.onRequestStart",
requestEndHandler       = "",
applicationStartHandler = "Main.onAppInit",
applicationEndHandler   = "",
sessionStartHandler     = "",
sessionEndHandler       = "",
missingTemplateHandler  = "",

What are these for? As I understand it, events in ColdBox are really requests. I mention this because in some other systems, events are not so much requests as they are notifications that something has just taken place. I won't get us sidetracked talking about different meanings of event, though.

The defaultEvent is used when no event is specified. How might an event be specified? One way would be through the use of a search-engine-safe (SES) URL parameter -- for example: localhost/coldbox/ApplicationTemplates/philosophy/index.cfm/user/add where user indicates the event handler and new specifies the event.

To put it another way, events map to a method in a CFC found in philosophy/handlers directory. In the case of the URL just show, Coldbox would look in the events directory for a file called User.cfc and for a method within that CFC called add. In addition to a specified event ( or the defaultEvent if none was specified), it looks like we can specify methods to run during the following phases of the application:

• when the application starts
• when the session starts
• when the request starts
• when the request ends
• when the session ends
• when the application ends
• when a template is requested that doesn't exist

It's certainly nice to be able to explicitly set these.

The next section, Extension Points, I'm going to skip for now. This is a little deeper than I want to get into for my first app -- limited cranial storage and processing and all that. In fact, I'm going to save my Coldbox.cfc file now. We'll come back to this later, I'm sure.

Luis Majano has a nicely done graphic explaining the ColdBox lifecycle here: http://wiki.coldbox.org/wiki/RequestLifecycles.cfm. ColdBox supports the Model-View-Controller design pattern, so normally, I would want a request to be handled by a controller that would use model and/or view resources to accomplish its responsibility. In ColdBox parlance, controllers are called event handlers, I believe?

For now, I just want to say "Hello, World" -- and to do this, I'm going to use a very nice, new feature of ColdBox 3 called implicit view rendering. From the docs:

My goal with this first step of my app is just to get the app to say hello. So, for now, I'll have no controllers and no actions -- just the template I wish the user to view. These are located, logically enough, in the views directory. I'll use this URL: localhost/coldbox/ApplicationTemplates/philosophy/index.cfm/hello/world. So, if I have it right, I should be able to create a subdirectory within views called hello and within that subdirectory, create a file called world.cfm.

Pointing a browser at that URL produces this:

Hey, that worked!

Ok, obviously, there's a lot more to be covered, but we did get ColdBox installed and running. Next, we'll go a little deeper, creating an event handler and specifying an event (rather than using implicit view rendering).

My code, so far: https://github.com/halhelms/ColdBox-Sample-App/tree/step1

Your corrections, comments, questions are much desired!

A Note About This Learning Style

While this trial-and-error style isn't the most efficient, for some of us, it's one of the best ways of incorporating new information. It allows us to build a mental model of how a system works, which is vital since we want to master a new subject. Of course, different people have different learning styles: one of my good friends likes to read RFCs to learn new technology!