Load A Custom ColdBox Config File

Introduction

This guide shows you how since version 2.0.1 you can decide which ColdBox config file to load when your application starts. Basically you can override the Conventions of the config file location and place your own location. This is a great tool if you place your configuration files outside of the web root or you are on a multi-tiered environment where you can create a config file for each tier. This sample deals with a basic sample of an alternate location for your config file. Please see the Directory Structure & Naming Conventions Guide.

Note: Please note that since version 2.0.1 you can also create your own conventions for your application layout and file locations.

Example 1: Absolute Path

Lets assume that for this example you will create your config.xml.cfm file in an alternate location, rather than on your {AppRoot}/config/config.xml.cfm. Let's say that you place your file in the following location:

c:\webConfigurations\MySampleApp\config.xml.cfm

Then in order for your application to use this file you will need to modify the Application.cfc or the index.cfm file, whichever bootstrap method you are using.

Application.cfc Method

Open the Application.cfc and look for the following:

<!--- COLDBOX PROPERTIES --->
<cfset COLDBOX_CONFIG_FILE = "">

Then just add your full path to that variable and that is it.

<!--- COLDBOX PROPERTIES --->
<cfset COLDBOX_CONFIG_FILE = "c:\webConfigurations\MySampleApp\config.xml.cfm">

index.cfm Method:

<cfsetting enablecfoutputonly="yes">

<cfinclude template="/coldbox/system/coldbox.cfm">

<cfsetting enablecfoutputonly="no">

Now, in order to include the file, you will need to add the following line of code before the include:

<cfset COLDBOX_CONFIG_FILE="c:\webConfigurations\MySampleApp\config.xml.cfm">

This is what the index.cfm file should look like:

<cfsetting enablecfoutputonly="yes">

<cfset COLDBOX_CONFIG_FILE="c:\webConfigurations\MySampleApp\config.xml.cfm">
<cfinclude template="/coldbox/system/coldbox.cfm">

<cfsetting enablecfoutputonly="no">

That is it folks!!

Example 2: Relative Path

You can also use a relative path to declare your configuration file. Lets say that this time the config file is located in a folder off the webroot called configfiles like so:

<cfset COLDBOX_CONFIG_FILE="/configfiles/myapp.xml.cfm">

Example 3: Coldfusion Mapping

You can also use a coldfusion mapping to declare the location of your configuration file. Lets say that the name of the mapping is coldboxapps and there is a directory there called sampleApp that contains your config file. You would then use the following code:

<cfset COLDBOX_CONFIG_FILE="/coldboxapps/sampleApp/coldbox.xml.cfm">

Conclusion

As you can see, it is relatively easy to declare a config file other than the convention standard. This is really useful in multi-tiered environments, unit testing and development environments. Remember that all you need to do is set the COLDBOX_CONFIG_FILE variable before the inclusion of the framework. Enjoy...