Brad Wood

July 03, 2014

Spread the word

Share your thoughts

Fusebox is one of the oldest frameworks for ColdFusion.  My first real ColdFusion job was working on a large intranet site built upon Fusebox.  The framework has changed hands several times and though it has now gone cold in terms of new development but it is still used by 1 in 3 ColdFusion developers according to the State of the CF Union survey results from 2014.  

Party like it's 1999

There's a lot of legacy code out there still running on FuseBox, but that doesn't mean it has to stay that way.  The Internet has moved on to design patterns like MVC and more-object oriented approaches for code reuse and testing.   The thought of reworking your old codebase might seem scary, especially if you're not familiar with MVC and you aren't using any OO principles.  Don't despair though, it's often times better to make incremental improvements to code instead of trying to throw it out and rewrite it from scratch.  The old adage says, how do you eat an elephant? "One bite at a time!"

The Future

There are but a handful of active frameworks for CFML developers today.  The most productive and extensible of those is the ColdBox MVC Platform.  ColdBox introduces common conventions into the way you code just like Fusebox did, but it helps you separate out your controller code from your HTML markup and your database access and business logic.  ColdBox was one of the first convention-over-configuration frameworks which means it's simple to get up and running with little or no settings and there's no XML required.  As opposed to a very formal and verbose method of declaring the portions of your application, you just create files in the appropriate folder, and the framework will simply pick them up and use them.  This makes for very fast and easy prototyping of new functionality, and it's all done in good old CFML code just like you're used to programming in.  In fact, you can have a simple Hello World ColdBox site up and running with just a few files.  Here's an example you can run in your browser!

ColdBox isn't just simple MVC conventions though.  The beauty of the platform is that once it gets you out of the gate, it grows with your system by providing an array of useful tools and libraries.  Developers spend too much time inventing or re-inventing wheels that already exist.  Common needs like caching, logging, creating objects, and testing are integrated right with the platform and ready whenever you need them in a way that no other CFML framework provides.  ColdBox also makes it easier than ever to share libraries with other developers with innovations like modules for common tasks like compressing JavaScript files, AntiSamy HTML sanitization, and recordset paging-- all of which can be downloaded from ForgeBox.

Divide and conquer

Start by making a list on your whiteboard of the main chunks of your app or website.  Think about what makes logical sense as a standalone unit of your code from a conceptual standpoint as well as how the actual code is organized.  In a Fusebox site, these lines will probably fall naturally with your circuits. Pick one of the smaller areas and set it aside to convert first.  Remember, you'll probably look back and wish you had built your first version a little different; so do something simple and small so you can learn from it.  This is a natural process called the "pilot system".  


ColdBox can happily live along side your legacy code, or even other ColdBox apps while you're in the process of refactoring your legacy site.  This means you don't have to convert 100% of your code in one shot. The first method of doing this is to create a subdirectory in your site that contains the ColdBox site.  The ColdBox framework will detect that it's being run inside of a subfolder and will adjust accordingly.  You just need to make sure that the CFC mapping "coldbox" resolves to the ColdBox framework.  The easiest way to accomplish this is to drop the coldbox folder in the web root.  You can also create a ColdFusion mapping that points to it.  Using application-specific mappings can help shield your code from future changes later on.  By default, the ColdBox app will have it's own application scope.  You can work around this by using the same application name, or letting your ColdBox's Application.cfc inherit from the parent one. 

The second way to have your new ColdBox code live amongst your legacy code is to just put your new ColdBox code in the webroot right along side your old code.  You'll need to convert over to Application.cfc if you're not already using it.  Start with the template Application.cfc that comes with our sample apps, and add back in any needs for your legacy code.  this will ensure that the framework gets loaded.  The last remaining thing to do will be to differentiate between URLs that are meant to hit your legacy code and URLs that need to be processed by ColdBox.  The magic happens in the onRequestStart() method with the "if" statement looking for an "index.cfm" in the URL to conditionally call the processColdBoxRequest() method.  You can tweak that statement to look for whatever patterns you want. For instance, I recently installed ContentBox CMS (Built with ColdBox) on a personal site of mine with a bunch of old legacy page laying around that I wanted to keep.  I switched the code to look like this so it would ONLY run ColdBox for requests hitting my root index.cfm file.  All other requests continue normally as though ColdBox doesn't exist.

//Process a ColdBox request only
if( arguments.targetPage == '/index.cfm' ){


A slightly more subtle way to start working Box goodness into your site before you even touch the MVC portions is to start using the LogBox, CacheBox, WireBox, and TestBox libraries right inside your legacy code.  Even though these libraries are part of the ColdBox MVC stack, they are also usable in a standalone form.  Just create the libraries when your app starts up and persist them in the application scope to start using them today.  Later on, as your code moves to ColdBox, you'll already be using a lot its bits and pieces and all you'll have to do is switch your hard-coded references to the application scope over to the local references the framework provides you.  I was part of a presentation at our Into The Box conference this year where we showed integrating each of those Box libraries into a legacy app.  You can check out the code repo for it here.  The master branch is the original app, switch branches to see the progression of adding each library.  


There are also some tricks for converting code over bit at a time.  For instance, a proper MVC has all the logic in the controller (we call them handler and they're a CFC file) and HTML in a view which is just a CFM file.  ColdBox actually let's you call a view directly with no handler.  Let's say in your /views directory you create a home sub directory and put your aboutUs.cfm page in there.


Now, normally you'd create a /handlers/home.cfc with an aboutUs() method inside, but we'll let you skip that and if you're using SES URLs with web server rewrites, just hit this URL:

Since there's no home handler, ColdBox will just run your cfm page directly as a view!  This is great for getting legacy pages to run inside the framework with any security, logging, etc it provides with minimal rewrite.  You can then go back and refactor pieces out later.

Plug-in and go!

You're well on your way to bringing your aging CFML app into the current decade!  Many people are embarrassed to admit they still use ColdFusion, but you don't have to be.  Transform your apps into something you are proud of using the most innovative platform in CFML today.  To get plugged in right away, here's some final resources for you to consider:

In the next installment in this series, we'll take a look at the sample applications for Fusebox and actually convert them over to use ColdBox. You can read our FuseBox 3 conversion post here.

Add Your Comment

Recent Entries

BoxLang: Available for Chromebook!

BoxLang: Available for Chromebook!

Chromebooks are fantastic for developers because they can install a Debian Linux container alongside Chrome OS. This makes running and developing BoxLang applications on your Chromebook simple. Chromebooks have gained popularity among developers and students due to their unique blend of affordability, portability, and robust integration with Linux. By bringing BoxLang to Chromebooks, we are creating a powerful platform for learning and development. Here’s why BoxLang on Chromebooks is a perfect match for students:

Maria Jose Herrera
Maria Jose Herrera
June 13, 2024
ColdBox 7 Workshop 2023: Mission Accomplished!

ColdBox 7 Workshop 2023: Mission Accomplished!

Our two-day ColdBox 7 Workshop of 2023 has concluded, and it was an exciting journey of knowledge and skill-building. Our attendees came, saw, and conquered, learning a treasure trove of materials, techniques, tools, and resources to enhance their projects with ColdBox 7 mastery. It was a fantastic ride, indeed!

Maria Jose Herrera
Maria Jose Herrera
June 13, 2024
May Newsletter 2024!

May Newsletter 2024!

May 2024 Updates & News

Welcome to Ortus Solutions’ monthly roundup, where we're thrilled to showcase cutting-edge advancements, product updates, and exciting events! Join us as we delve into the latest innovations shaping the future of technology. Let’s get started!


Maria Jose Herrera
Maria Jose Herrera
June 06, 2024