Dan Card

July 20, 2022

Spread the word

Share your thoughts

Recently I did a webinar on Refactoring Legacy Code and the question came up about whether or not it was possible to use Coldbox with existing code without converting everything to a Coldbox module or making changes to the existing codebase. In the first installation in this series, we took a tour of the various elements which make up ColdBox. In this second installation, we are looking at creating layouts, views, and routes in the main site.

In the first installation of this post, we took a quick tour of ColdBox and defined the eight parts of ColdBox:

  • Routes
  • Layouts
  • Views
  • Handlers
  • Models
  • Interceptors
  • Modules
  • Tasks
  • Scheduled Tasks

In this installation, we’re going to start looking at how a ColdBox site is constructed. Please see the first installment details about the forgebox project located at

After installing the myco module and starting the server in the /coldboxsite folder, visit http://myco.local/myco to see some configuration items and links to the examples here.

Creating / Adapting our layout

A layout is the template for your page. It might consist of the <html>, <head> and <body> tags as well as any styling which was universal to the site. By convention, ColdBox uses /layouts/main.cfm as the layout but you can change this.

Step 1: Duplicate /layouts/main.cfm and call it mycomain.cfm. Make some changes to mycomain.cfm so you can see that it a different file (Change something that says Ortus to myco or something.)

Step 2: Open the /config/coldbox.cfc and find the entry for configure() method. In that method, there will be the line:

layoutSettings = { defaultLayout : "", defaultView : "" };

If it isn’t changed already, change that to

layoutSettings = { defaultLayout : "mycomain", defaultView : "" };

Since this changes the ColdBox configuration, you will need to reinit the framework by using ?fwreinit=1.

Open the browser to http://myco.local/ (?fwreinit=1 if needed) and you should see your changes to the layout.

Creating our First View

If you look in /layouts/mycomain.cfm you will find the code renderView(). This will take the assigned view and display it inside the layout. By convention, ColdBox will use “/views/main/index.cfm” as the default view but you can change this several ways. The first is to change the layoutSettings.defaultView setting in /config/coldbox.cfc like we did for the layout above.

Step 1: Create the file mycotest.cfm in the /views folder. It can say anything you want (such as “This is mycotest!”).

Step 2: Assuming you’ve already started the server in the /coldboxsite folder, open your browser to http://myco.local/mycotest. If you get an error, add ?fwreinit=1 to the end of the URL and reload. This forces the ColdBox framework to re-initialize so new or edited routes, modules, handlers etc can be loaded. Even though there is no route defined for /mycotest, ColdBox can associate that URL with a view of the same name. However, we don’t want to always leave our sites up to simple conventions so next we are going to explicitly define a route for a view.

Creating our first Route

Open the Router.cfc file in the /config folder at the root of the ColdBox site. Even though this is a router, it is just a CFC which has a function called configure. The framework looks for this Router.cfc and runs configure() as part of its initialization when it starts up. If the file isn’t there, it’s skipped.

In configure() you’ll see several calls to route() which is where you, probably obviously, define and configure your routes.

Step 1: Create another view called mycotest2.cfm and put some text in there so you can identify it.

Step 2: Add route(“/mycotest2”,”mycotest2”) to the /config/Router.cfc in config(). Place it above this code, around line 29.


// Conventions based routing
route( ":handler/:action?" ).end();

Open the browser to http://myco.local/mycotest2. You should see your view inside of your layout.

Creating Our First handler

We don’t always want to have our URLs, views etc simply follow convention and sometimes they will need some pre-work before they can effectively display anything. The next step in our complexity ladder is to create a handler.

Step 1: Add route(“/mycoHandler”,”Myco.firstHandler”) to /config/Router.cfc in config()

Step 2: Create a CFC in the /handlers/ folder called Myco.cfc.

Step 3: Create the following method in /handlers/Myco.cfc:

function firsthandler(){

Step 4: Create the file /views/main/steve.cfm and put some text in there to identify it.

Open the browser to http://myco.local/mycoHandler. You should see your layout with the view, steve.cfm inside of it. Notice how in this case, steve.cfm is in a subfolder of /views called /views/main/ and that is reflected in the handler.


We’ve looked at several aspects of ColdBox and how they work. However, we haven’t tied it into our existing code yet. That is happening in installation 3. Promise!!!

Did you miss the June Webinar - Getting started with the Legacy Migration with Dan Card

We will look at the process of converting legacy .cfm based sites into a more modern coding design which has less overall code, is easier to maintain and manage, mistakes and errors can more readily and speedily identified and fixed, and is easier to read.


Legacy Migration Follow Up: Using Coldbox with an Existing Code Base with Dan Card

July 29th 2022: Time 11:00 AM Central Time ( US and Canada )

Dan Card will be presenting a follow up to his June webinar: Getting started with the Legacy Migration. Dan received some good questions, so July's Webinar: Legacy Migration Follow Up: Using Coldbox with an Existing Code Base with Dan Card. If you have a more traditional / legacy codebase, and are wanting to modernize with ColdBox, but don't know where to start, this webinar is just for you!

Register now:

Find out more about Dan Card's workshop at Into the Box - Legacy Code Conversion to the Modern World

This one-day workshop will focus on converting legacy .cfm based sites into a more modern coding design that has less overall code, is easier to maintain and manage, mistakes and errors can be more readily and speedily identified and fixed, and is easier to read.

Add Your Comment


Jul 23, 2022 01:58:57 UTC

by Derek

Thanks for this Dan!

Recent Entries

CBSecurity 3.1 Released

CBSecurity 3.1 Released

We are happy to announce our first minor release for CBSecurity v3.1.0, with some nice updates and a new password generator.

Luis Majano
Luis Majano
February 20, 2023
ColdFusion Summit East 2023 MVC Training Workshop

ColdFusion Summit East 2023 MVC Training Workshop

We are excited to announce a training workshop before the ColdFusion Summit East in Washington, D.C., on April 4th, 2023. Luis Majano, the creator of The ColdBox Platform, will be leading this workshop, bringing you a deep dive 1-day workshop: ColdFusion MVC for Dummies.

The workshop will combine a variety of theories, hands-on coding, and best practices to give you all the tools needed to leave the workshop ready to build MVC-powered apps when you return to your office.

Luis Majano
Luis Majano
February 16, 2023