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

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