Making ColdBox 3.1 Dance: Customizing ColdFusion Frameworks

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:

• FW/1
• ColdBox 2.6
• ColdBox 3.1
• CFWheels

Making ColdBox 2.6 Dance: Customizing ColdFusion Frameworks

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.

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

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.

<Conventions>
	<handlersLocation>app/controllers</handlersLocation>
	<layoutsLocation>app/layouts</layoutsLocation>
	<viewsLocation>app/views</viewsLocation>
	<modelsLocation>app/model</modelsLocation>
</Conventions>

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"/>

Conclusion

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.

Frameworks:

• FW/1
• ColdBox 2.6
• ColdBox 3.1
• CFWheels

Making FW/1 Dance: Customizing ColdFusion Frameworks

This post covers customizing FW/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 setup. 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 FW/1 to /lib

FW/1 is a single compenent that resides at /org/corfield/.

You can safely move /org inside of /lib.

The only reference you need to update is in /Application.cfc. In /Application.cfc, change extends="org.corfield.framework" to extends="lib.org.corfield.framework".

Moving FW/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.

FW/1 also has a services folder that we’re going to add to the /app folder.

FW/1 has a nice feature that easily allows you to move the application folders relative to the application root.

https://github.com/seancorfield/fw1/wiki/Developing-Applications-Manual

base – Provide this if the application itself is not in the same directory as Application.cfc and index.cfm. It should be the relative path to the application from the Application.cfc file.

In addition you can override the base directory for the application, which is necessary when the controllers, services, views and layouts are not in the same directory as the application’s index.cfm file. variables.framework.base should specify the path to the directory containing the layouts and views folders, either as a mapped path or a webroot-relative path (i.e., it must start with / and expand to a full file system path). If the controllers and services folders are in that same directory, FW/1 will find them automatically. If you decide to put your controllers and services folders somewhere else, you can also specify variables.framework.cfcbase as a dotted-path to those components, e.g., com.myapp.cfcs assuming that com.myapp.cfcs.controllers.Controller maps to your Controller.cfc and com.myapp.cfcs.services.Service maps to your Service.cfc.

The FW/1 wiki is refering to `variables.framework.base` within /Application.cfc. In order to move the application folders to /app we need to set this value.

Add the following to /Application.cfc:

variables.framework.base= "/app";

Conclusion

FW/1 is a pleasure to dance with. It is by far the easiest ColdFusion framework to customize. It was designed with motion in mind. The only customizing was in /Application.cfc, which is where I’d expect to find it.

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.

Frameworks:

• FW/1
• ColdBox 2.6
• ColdBox 3.1
• CFWheels

Making Frameworks Dance: Customizing ColdFusion Frameworks

This is a mini-series of posts on getting ColdFusion frameworks to dance. Most of them are stiffs who can’t count to three, much less do the Charleston.

This mini-series is part of an overall series of converting a Ruby on Rails app to ColdFusion.

I like how Rails 3 applications are setup. 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

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.

Frameworks:

• FW/1
• ColdBox 2.6
• ColdBox 3.1
• CFWheels