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 Folders
*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.
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.
@anon: glad to hear your digging the MVC structure with Fusebox (great framework, too). When you get 'bored' checkout CakePHP, too. Pretty nice PHP framework.
Hope I have time to look over CB one of these days.
The optional (commented-out) <Conventions> tag around line 135 of coldbox.xml.cfm is where that occurs. So, while Coldbox enforces "convention over configuration", you can still tell Coldbox where all of these "conventional" places are, and name them whatever you want.
(note: I find out about your new blog posts via Twitter. Keep those tweets comin'!).