ColdBox - Refactoring the Application Template

Posted on June 28, 2010 in ColdBox

In my time of developing web applications, one of my preferences is that the only files under the web root should be web accessible files. With the addition of application specific mappings in ColdFusion, this has become even easier as you can use standard mappings for frameworks without running into collisions between applications. Over the years, I have come up with a fairly standardized application folder structure for Fusebox, Mach-II, and Model-Glue based applications. I recently decided to give ColdBox a spin and one of the first things I had to do was refactor the default template application to move everything that does not need to be directly web accessible out of the web root.

The default "advanced" application template that comes with the ColdBox download looks like this.

From my initial reading and testing, it appears that almost all of the folders here contain files which do not need to be directly accessible. Like most MVC frameworks, ColdBox uses the front-controller design pattern. By following this pattern, we should be able to refactor the application template such that only the Application.cfc and index.cfm files remain in the web root, along with any necessary css, images, and scripts.

After some trial and error, the refactored application template looks like this.

Some of the obvious changes here include:

The ColdBox framework itself is now located in a folder called frameworks. This folder would also include other frameworks like ColdSpring, MXUnit, and others as necessary by the application. This way, the application has all of the frameworks necessary for it to run and it will not be impacted if a shared framework was updated for another application. To handle this change, a mapping called /coldbox is necessary and will be shown later.
The core ColdBox folders are now located above the web root including folders for config, handlers, and more.
A new folder called www was added. This folder will be the web root of the application, within which will be the Application.cfc and index.cfm along with any css, images, and scripts.

So far, all of the changes have only been a reorganization of the folder structure. No files have been altered. The only file changes necessary to make this all function as expected are in the Application.cfc file. The index.cfm file under the web root remains unchanged from the ColdBox application template.

In the Application.cfc file, the mapping to the ColdBox framework files is added and the ColdBox configuration settings are updated as follows.

<!---// Application mappings //--->
<cfset this.applicationRoot = left( getCurrentTemplatePath(), find( "www", getCurrentTemplatePath() ) - 1 ) />

<cfset this.mappings = structNew() />
<cfset this.mappings[ "/appRoot" ] = this.applicationRoot />
<cfset this.mappings[ "/coldbox" ] = this.applicationRoot & "frameworks/coldbox" />

<!--- ------------------------------------------------------------ --->

<!---// ColdBox Framework Configuration Properties  //--->
<cfset this.cbConfig = structNew() />
<cfset this.cbConfig.COLDBOX_APP_ROOT_PATH = this.applicationRoot />
<cfset this.cbConfig.COLDBOX_APP_MAPPING = "appRoot" />
<cfset this.cbConfig.COLDBOX_CONFIG_FILE = "" />
<cfset this.cbConfig.COLDBOX_APP_KEY = "" />

In the application mappings section, the system file path to the web root (www) folder is determined. This provides the system file path to the base folder for the application, upon which the necessary mappings can be built. Two mappings are needed to get the ColdBox template running - one of the application root and one for the ColdBox framework.

In the ColdBox framework configuration properties, two settings are configured. The COLDBOX_APP_ROOT_PATH is set to the applicationRoot variable that was determined earlier and corresponds with the base system file path for the application. Second, the COLDBOX_APP_MAPPING variable is set to the name of the /appRoot mapping which again represents the base system file path for the application in a mapping form.

The remainder of the Application.cfc file is the same as the stock Application.cfc file that comes with the ColdBox application template.

If you point your web server to the /www folder, you should get the default ColdBox home screen below.

Thus far, I have only tested this on Adobe ColdFusion 9, but I see no reason this should not work on any version of ColdFusion that supports application specific mappings and it should work on any version of ColdFusion supported by ColdBox if the mappings are set in the ColdFusion administrator.