Creating Our First Event

Now that our application is setup, we want to make sure that it works. We'll start out by removing extra files we won't need. Once that's done we'll setup our default event and make sure everything's working.

Pruning the install

ColdBox includes a couple of extra files in it's application template. These files generally serve to display the default "welcome" event. Since we'll be replacing this event by our own, we can strip out a couple of files from the template:

/
	includes/
		helpers/
			ApplicationHelper.cfm
		images/
			coldbox.png
	logs/
		YourAppNamehere.log (a new one will be generated with our actual app name)
	build.properties
	build.xml
	readme.txt

All that should be left now is all that we need for our ColdBox-based application to work.

An event

An event is basically an action. When you request a page in ColdBox, you call an event. ColdBox then wires that event to a method in one of it's handlers, which then handles the request.

It's important to understand the idea behind event handling before proceeding. When you call a page, traditionally, your url would look something like this:

/squash/some_folder/file.cfm

In a ColdBox-based app (and many other MVC style frameworks), your url would look more like so:

/squash/index.cfm?event=some_handler.some_action

We're passing in a URL variable to ColdBox: event. This variable contains two very important parts delimited by the period. The first part, some_handler, is the handler. The handler is basically a .cfc file with loads of methods in it. The second part, some_action, is the name of the action. The action represents a method in the handler. By convention, when ColdBox receives an event call, it will look for a .cfc file with the name of handler in the handlers folder. It will then call the method within it that has the same name as the action. In our case, it will look for a some_handler.cfc file in the handlers folder, and call it's some_action method.

Now that the groundwork is done, let's override the default event left by ColdBox and create our own. In the coldbox.xml.cfm file, in the config folder, there's a setting named "DefaultEvent". This represents the event called in the case that none is provided; when someone hits index.cfm without providing an "event" variable, this is what will be called. Right now it's set to general.index which is just fine. Knowing what we now know, we can open up general.cfc in the handlers folder and search for the index method within it to see what it actually does:

Not much happening here. All actions receive an event variable, which contains all the functions/methods pertaining to the current request. One of those methods is setValue(). This adds/sets a variable within the request collection, which is then available through all methods/views for that particular request. We provide the variable name and then it's value.

A view is a ColdFusion template for displaying, well, stuff. In a MVC style framework, data is parsed/mashed in the model (M) and controller (C), while the view (V) should only bother with displaying stuff. In a ColdBox application, the model layer (M) is consisted of your beans (more on that later) and the controller (C) is made of your handlers and events.

We won't need the welcomeMessage where we're going, so we can remove it. Once we're done, we tell ColdBox which view to use to display our data. By convention, the views are located in the views folder. Tricky, huh? Let's open up home.cfm in the views folder and clear it out. We'll start by a simple hello world message:

When outputting that in the browser (by calling index.cfm or by providing the event parameter with index.cfm?event=general.index) we get the expected result... or do we? We can see our hello world message just fine, however some things are off. Why is there a title to our page? Also, some styles seem to be applied by default. The answer to these questions is rather simple: ColdBox uses a layout system to "wrap" around your views. You can create any amount of layouts you want and assign them to specific views or events. For now, we'll settle with using just the default layout. To modify it, we first have to figure out where it is. In the coldbox.xml.cfm file, there's a Layouts node. Within this node there's another one named DefaultLayout. This is currently set to Layout.Main.cfm, which is fine. By convention, layouts are in the layouts folder. Now that we know which file is causing our problems let's open it. For the time being we'll just clean out everything we don't need and leave it as a simple shell:

A quick refresh to confirm everything is working well... great!

I took a little longer than expected to go over these basics because I think it's important that at least this is covered before going into the nitty-gritty of the application coming up ahead. I won't go into as much detail for the basics in the next posts, however. One more post about the basics of ColdBox and ColdSpring and we actually get to work on SQUASH.

edit: removed ColdSpring from the title, that's for the next post ;).