Making ColdBox 2.6 Dance: Customizing ColdFusion Frameworks

Wed, 09 Nov 2011

This post covers customizing ColdBox 2.6 to use a custom directory structure. This post is part of a mini-series on Making Frameworks Dance: Customizing ColdFusion Frameworks.

I like how Rails 3 applications are setup. I wanted to keep the following directory structure when converting the application to ColdFusion.


Why ColdBox 2.6?

I use ColdBox 2.6 for several applications. I am also expecting to receive a project soon that was written in 2.6.

I am doing a post on ColdBox 3.x as well.

Moving ColdBox 2.6 to /lib

ColdBox 2.6 is pretty set on using /coldbox as it’s path. Luckily application mappings save the day.

Create /lib/coldbox/.

Move /config, /dashboard, and /system into /lib/coldbox/.

The only references you need to update are in /Application.cfc.

Mappings don’t apply until after Application.cfc is run, so updated the extends attribute in <cfcomponent to "lib.coldbox.system.coldbox".

extends= "lib.coldbox.system.coldbox"

Add a mapping for ColdBox’s new location:

this.mappings[ "/coldbox" ]=  ExpandPath( "/lib/coldbox" );

Update the location of your config file:

variables.coldbox_config_file= "/lib/coldbox/config/config.xml.cfm";

Moving ColdBox 2.6 Application Folders to /app

Application folders are all of the folders I listed under the /app directory, which includes: controllers, layouts, model, and views.

ColdBox 2.6 also has an includes folder that we’re going to add to the /app folder.

All of the changes we need to make are in the config.xml.cfm file. Try to ignore variables.coldbox_app_root_path in Application.cfc.

Firstly, find the <Conventions> section that let’s you customize the conventions used in ColdBox. Add custom conventions for handlers (controllers), layouts, views, and models.


I rename handlers to controllers. It’s probably a personal preference, but it makes more sense to me.

Next, find the ExternalLocation block and update the location of your handlers(controllers), models, and views (again).

<Setting name="ViewsExternalLocation" 		value="app/views"/>
<Setting name="HandlersExternalLocation"   	value="app.controllers" />
<Setting name="ModelsExternalLocation"   	value="app/model" />

If you moved /includes into /app, then update the UDFLibraryFile setting.

<Setting name="UDFLibraryFile"  value="/app/includes/helpers/ApplicationHelper.cfm" />

After all of the settings above have been changed, then ColdBox 2.6 will recognize the correct paths. For example, to reference /app/controllers/application_emulator.cfc as the RequestStartHandler you can do the following:

<Setting name="RequestStartHandler"  value="application_emulator.onRequestStart"/>


ColdBox 2.6 responded well enough once I figured out the right set of moves. It’s still a bit quirky, but it gets the job done.

I was frustrated by variables.coldbox_app_root_path in Application.cfc. It would’ve been nice to set this variable to “/app” and be done. I’m also unsure why setting both conventions and external locations in the config file are necessary.

Other Frameworks in Mini-series

I’ll be covering multiple frameworks and the issues in getting them to work in the directory structure above. Each framework will be it’s own post. This post will be updated with links to all posts in the mini-series so you can easily jump to your favorite.


  • Customize Frameworks
  • Frameworks
  • ColdFusion
  • ColdBox
  • fw/1
  • ColdBox 2.6
  • Dancing Frameworks
  • CFWheels
  • orangexception