Understanding the coldbox.xml config file - ColdBox Series Part 4

In my previous posts we began building a To-Do list application with ColdBox. If you have not already reviewed the first three parts of these posts, you may want to consider doing so. They are linked at the bottom of the page in the "related posts" section.

In this post we are going to discuss the coldbox.xml file (sometimes named coldbox.xml.cfm for security reasons)

The coldbox.xml file "is the Heart of you ColdBox Application", according to the ColdBox website. The coldbox.xml is the file that the ColdBox framework looks for to learn how it is supposed to behave. If the file is not there, ColdBox cannot operate. If will give you an error about being unable to find the coldbox.xml or config.xml (an alternate name for the file) files in your /config directory.

What does the coldbox.xml file do?

The coldbox.xml file is where we keep all of the settings for our ColdBox application. We tell it everything from what the name of the application is, to where we have placed our ColdSpring config files, to where our views are stored, and much, much more.

In this post we are NOT going to discuss everything that the coldbox.xml file is used for, because that would make the post really long, and because I do not yet know everything there is to know about the config file and all of its setting.

The coldbox.xml file

So let's take a quick look at the beginning of the file.

<?xml version="1.0" encoding="ISO-8859-1"?>
<Config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        <!--The name of your application.-->
        <Setting name="AppName"                        value="Your App Name here"/>

As with the beginning of any well-formed XML file, we have and <?xml ?> declaration, we also have a namespace declaration, none of this needs to change.

The first setting in our file is for the AppName, this is an internal reference, it is not the same as the this.name setting you set in your Application.cfc. That is still set in Application.cfc since it happens before ColdBox even gets a chance to initialize.

Ok, that was easy enough, now let's look at the next piece of the config file.

<!--Default Debugmode boolean flag (Set to false in production environments)-->
<Setting name="DebugMode" value="true" />

<!--The Debug Password to use in order to activate/deactivate debugmode,activated by url actions -->
<Setting name="DebugPassword" value=""/>

<!--The fwreinit password to use in order to reinitialize the framework and application.Optional, else leave blank -->
<Setting name="ReinitPassword" value=""/>

DebugMode takes a boolean value that tells the framework whether or not to output debug information to the screen. Even if it is set to false, Debug mode can be turned on using a URL variable, so it is important to also set the DebugPassword value to a strong password. If a user knows the debug password they can use it to turn on debug settings.


We also have the ReinitPassword value. This is for the URL parameter fwreinit which is used to... can you guess? So to reinitialize the framework you would pass the password you set here on the URL string. Since applications can take a LONG time to reinitialize, and can use up a lot of CPU cycles and memory to do so, it is a good idea to set a password for reinitialization because if you don't it makes it easier for you to be DoS'd.


Next we have the EventName value:

<!--Default event name variable to use in URL/FORM etc. -->
<Setting name="EventName" value="event" />

This is the name of the parameter used to identify the event you are calling. You can call it anything you like. You could call it "event", you could call it "fuseaction", you could call it "go", you could even call it "monkey":


The next really important setting is DefaultEvent. I'm sure that some would tell you that ALL of the settings are important, but I don't have that kind of time.

<!--Default Event to run if no event is set or passed. Usually the event to be fired first (NOTE: use event handler syntax)-->
<Setting name="DefaultEvent" value="general.index"/>

Simply put, the default event is the event that gets called if no other event gets called. Notice it is calling our index() handler from the general.cfc located in our handlers directory. Coincidence? I think not.

Now we're going to skip all the way down to about Lines 175-191 where we'll see our <Layouts*gt; tags. Inside the Layouts tags we have a single child called <DefaultLayout>. This is where we declare the layout to use when no other is explicitly set in an event handler. You may remember in our first look at Event Handlers that it was not immediately clear how the code from Layout.Main.cfm was getting wrapped around our home.cfm view. This is how. Since we did not explicitly call a layout in our event handler ( Event.setLayout("Layout.Main") ) it used the layout that was set in this value as the default. In a future post we will look at setting up more layouts.


This has been a VERY superficial look at the coldbox.xml file. Obviously we skipped over A LOT, but we are not done yet:

  • Some of it is self explanatory and can be figured out by reading the comments.
  • We will be revisiting the coldbox.xml file several times in the future. We will need to make changes in it when we add ColdSpring, look at custom conventions, and create our own settings.
  • I also encourage you to go to the ColdBox docs Config Guide to see more detailed descriptions of all of the values in the coldbox.xml file.

BlogCFC was created by Raymond Camden. This blog is running version 5.9.1. Contact Blog Owner