Making ColdBox 3.1 Dance: Customizing ColdFusion Frameworks

Wed, 09 Nov 2011

This post covers customizing ColdBox 3.1 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 set up. I wanted to keep the following directory structure when converting the application to ColdFusion.

	+app
		+assets
			+documents
			+images
			+javascripts
			+stylesheets
		+controllers
		+layouts
		+model
		+views
	+assets
	+lib
		+{framework}
	Application.cfc
	index.cfm

Moving ColdBox 3.1 to /lib

ColdBox 3.1 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/Coldbox.cfc";

Moving ColdBox 3.1 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 3.1 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/Coldbox.cfc file. Try to ignore variables.coldbox_app_root_path in Application.cfc.

Depending on the template you’re using, you may need to add these variables to the coldbox struct.

function configure(){
	// coldbox directives
	coldbox = {
		...

		//ExternalLocations
		viewsExternalLocation=		"/app/views" ,
		handlersExternalLocation=	"/app/controllers" ,
		layoutsExternalLocation=	"/app/layouts"

	};

}

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

Next, we need to add custom conventions. This is not part of the coldbox struct.

function configure(){
	// coldbox directives
	coldbox = { .. };

	// other settings
	..

	//	Conventions
	conventions=	{
		handlersLocation=	"/app/handlers" ,
		viewsLocation=		"/app/views" ,
		layoutsLocation=	"/app/layouts" ,
		modelsLocation=		"/app/models"

	};

}

If you moved /includes into /app, then add/update the UDFLibraryFile setting. I added this to the external locations block in the coldbox struct.

function configure(){
	// coldbox directives
	coldbox = {
		...

		//ExternalLocations
		UDFLibraryFile=				"/app/includes/helpers/ApplicationHelper.cfm" ,
		viewsExternalLocation=		"/app/views" ,
		handlersExternalLocation=	"/app/controllers" ,
		layoutsExternalLocation=	"/app/layouts"

	};

}

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

function configure(){
	// coldbox directives
	coldbox = {
		...

		//Implicit Events
		defaultEvent			= "main.default" ,
		requestStartHandler		= "application_emulator.onRequestStart" ,
		...

	};

}

Conclusion

After dancing with ColdBox 2.6, I found ColdBox 3.1 was a smooth dancing partner. I found configuration component in 3.1 much easier to work with compared to the 2.6 xml file.

Some of the error messages in 3.1 were amusing. I enjoyed the one when you have no controllers.

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 its own post. This post will be updated with links to all posts in the mini-series so you can easily jump to your favorite.

Frameworks:

  • ColdFusion
  • Frameworks
  • FW/1
  • ColdBox
  • ColdBox 3.1
  • Dancing Frameworks
  • CFWheels
  • Customize Frameworks
  • orangexception