last edited bylmajano on 31-Aug-2011

History 

<< Back to Dashboard

ColdBox Configuration CFC

Overview

The ColdBox configuration CFC is the heart of your ColdBox application. It contains the initialization variables for your application and extra information used by the ColdBox software aspects and ultimately how your application boots up. This programmatic approach is extremely flexible in comparison to its counterpart of using a ColdBox XML configuration file from pre 3.0.0 applications. The best practice approach to bootstrap a ColdBox application is via this configuration CFC. So say bye bye to XML!

Another huge advantage of using this programmatic approach is that it has already tier or environment detection built in. Not only that, but you can customize it at your will, much like play-doh :)

Introduction

The configuration CFC is a simple CFC that lives in your config folder by convention called Coldbox.cfc. This is a convention that is setup by default, but of course you can alter the location by tweaking some variables in the Application.cfc provided in the templates. So before we start digesting what we can do in our configuration object, let's explore these directives as they are extremely important.

+ Application.cfc
+ /config
  + Coldbox.cfc

Application.cfc Directives

The provided Application.cfc object in the application templates can come in two flavors:

1. Using inheritance
2. Using Composition (Our Preference)

The inheritance approach is the easiest way to start but it is bound to extending the Application.cfc object to the ColdBox bootstrapper. With the no-inheritance or composition approach it is much more flexible and we can use per-application mappings for choosing the location of the coldbox distribution package. Anyways, once you make this decision there are some directives or variables you can set that will alter some behavior.

Most of the time you will never alter these settings if your application is the root application and it will look like the following:

<---  COLDBOX STATIC PROPERTY, DO NOT CHANGE UNLESS THIS IS NOT THE ROOT OF YOUR COLDBOX APP --->
<cfset COLDBOX_APP_ROOT_PATH = getDirectoryFromPath(getCurrentTemplatePath())>
<---  The web server mapping to this application. Used for remote purposes or static purposes --->
<cfset COLDBOX_APP_MAPPING   = "">
<---  COLDBOX PROPERTIES --->
<cfset COLDBOX_CONFIG_FILE   = "">	
<---  COLDBOX APPLICATION KEY OVERRIDE --->
<cfset COLDBOX_APP_KEY       = "">

Or you can modify it, like the following example in order to load a custom configuration file and a custom application mapping.

<---  COLDBOX STATIC PROPERTY, DO NOT CHANGE UNLESS THIS IS NOT THE ROOT OF YOUR COLDBOX APP --->
<cfset COLDBOX_APP_ROOT_PATH = getDirectoryFromPath(getCurrentTemplatePath())>
<---  The web server mapping to this application. Used for remote purposes or static purposes --->
<cfset COLDBOX_APP_MAPPING   = "apps.myApp">
<---  COLDBOX PROPERTIES --->
<cfset COLDBOX_CONFIG_FILE   = "shared.myApp.coldbox">	
<---  COLDBOX APPLICATION KEY OVERRIDE --->
<cfset COLDBOX_APP_KEY       = "">

Creating the ColdBox.cfc

/**
* A simple CFC that configures a ColdBox application.  You can even extend, compose, strategize and do your OO goodness.
*/
component{
	
	void function configure(){
	  // Setup all the application settings here.
	  
	}
}

This component is a simple CFC, no inheritance needed, because it is decorated with methods and variables by ColdBox at runtime. Once created, we must create a mandatory configure() method that will be executed by ColdBox in order to configure your application. We will discover the optional methods later on, so don't worry. Another important facet of the configuration object is that it will be decorated at runtime with the following variables that will be placed in the component's variables scope:

The Decorated Variables

The Configure() Method

As discussed previously we must implement one mandatory method called configure(). In this method is where we can set all the necessary ColdBox directives, settings, tier control, etc. If you are already familiar with configuring ColdBox applications via XML the programmatic approach will be very similar in terms of the settings and names. We really wanted to maintain some balance, so you will not see any weird new names. Basically, you have to create several structures or arrays in the variables scopes that must match the following names:

// Sample showing all the possible structures/arrays to configure
function configure(){
	cacheBox = {};
	coldbox 	= {};
	conventions = {};
	datasources = {};
	debugger	= {};
	environments = {};
	i18n		= {};
	interceptorSettings = {};
	interceptors = [];
	ioc = {};
	layoutSettings = {};
	layouts = [];
	logBox = {};
	mailSettings = {};
	modules = {};
	settings = {};
	webservices = {};
	wirebox = {};
}

The Simplest Configuration

Before we start digesting each of these directive variables, let's look at the simplest of all configurations. Below is the simplest approach by only filling out the mandatory requirements:

function configure(){
	coldbox = {
	  appName      ="My Simple App",
	  defaultEvent = "general.index"
	};
}

There you go, that is the simplest that you can go with ColdBox, just the name of your application and the default event. Just remember that ColdBox can be as simple as you like, or as complex as you like. ColdBox has lots of tools and software concerns that can address most typical ColdFusion applications, but its core is plain old simple conventions MVC. So go ahead, and build your own recipe!

Configuration Storage

Once the application starts up, a reference to the instantiated configuration CFC will be stored in the ColdBox settings with the key coldboxConfig. You can then retrieve it like so:

config = getSetting('coldboxConfig');

Having access to the reference can be useful.

Configuration CFC As An Interceptor

Another cool concept for the Configuration CFC is that it is also registered as a ColdBox Interceptor once the application starts up automatically for you. This means that you can create interception points in this CFC that will be registered upon application startup. This can be a great way for you to define startup procedures, etc.

cacheBox

The cacheBox structure is based on the CacheBox declaration DSL, see CacheBox. Below are the main keys you can fill out:

Please note that there are certain flows for CacheBox configuration discovery if you do not use the inline CacheBox DSL. Please refer to the CacheBox Application Configuration section in order to learn it. Below is a snapshot of that documentation so you can get a feel of the inline CacheBox DSL. However, we recommend using an external portal file for configuring CacheBox, whether XML or programmatic (our choice!).

Scope Registration

CacheBox has a nifty little feature that enables itself to leech onto a specific scope in memory. It basically can auto-register itself in your environment with no further need for persistence or just to expand its location. By default CacheBox registers itself in server scope with a key of cacheBox, but you have complete control on how the scope registration should work.

Customizable Keys:

Example:

// The CacheBox configuration structure DSL
cacheBox = {
	// Scope registration, automatically register the cachebox factory instance on any CF scope
	// By default it registeres itself on server scope
	scopeRegistration = {
		enabled = true,
		scope   = "application",
		key		= "cacheBox"
	},
};

Default Cache

The defaultCache element is in itself a structure of configuration data for the default cache provider of type coldbox.system.cache.providers.CacheBoxProvider. This is a reserved cache name and it is MANDATORY to declare and its name or type cannot be changed. However, if you are using CacheBox within a ColdBox application, the provider will switch itself to coldbox.system.cache.providers.CacheBoxColdBoxProvider by using the coldboxEnabled key. So let's see the configuration keys for our default cache.

Default Cache Properties:

Example:

// The CacheBox configuration structure DSL
cacheBox = {
	// Please note that each object store could have more configuration properties
	defaultCache = {
		objectDefaultTimeout = 60,
		objectDefaultLastAccessTimeout = 30,
		useLastAccessTimeouts = true,
		reapFrequency = 2,
		freeMemoryPercentageThreshold = 0,
		evictionPolicy = "LRU",
		evictCount = 1,
		maxObjects = 200,
		// Our default store is the concurrent soft reference
		objectStore = "ConcurrentSoftReferenceStore",
		// This switches the internal provider from normal cacheBox to coldbox enabled cachebox
		coldboxEnabled = false
	},
};

Caches

The caches element is in itself a structure of configuration data for aggregating named cache providers of ANY type. The key is the unique name of the cache to aggregate under this CacheBox instance. The value should be a structure with the following keys:

Example:

// Register all the custom named caches you like here
caches = {
    // Named cache for all coldbox event and view template caching
	template = {
		provider = "coldbox.system.cache.providers.CacheBoxColdBoxProvider",
		properties = {
			objectDefaultTimeout = 120,
			objectDefaultLastAccessTimeout = 30,
			useLastAccessTimeouts = true,
			freeMemoryPercentageThreshold = 0,
			reapFrequency = 2,
			evictionPolicy = "LRU",
			evictCount = 2,
			maxObjects = 300,
			objectStore = "ConcurrentSoftReferenceStore" //memory sensitive
	},
	sampleCache1 = {
		provider="coldbox.system.cache.providers.CacheBoxProvider",
		properties = {
			objectDefaultTimeout="20",
			useLastAccessTimeouts="false",
			reapFrequency="1",
			evictionPolicy="LFU",
			evictCount="1",
			maxObjects="100",
			objectStore="ConcurrentSoftReferenceStore"
		}
	},
	sampleCache2 = {
		provider = "coldbox.system.cache.providers.CFProvider"
	}
},

coldbox

The coldbox structure must be declared with the two mandatory settings we saw in the previous section. Let's explore now the rest of the directives in our nice little charts below that are grouped by functionality:

Application Setup

coldbox = {
	appName   = "My App",
	eventName = "event"
};

Development Settings

coldbox = {
	debugMode = false,
	debugPassword = "whatUpDude",
	reinitPassword = "h1cker",
	handlersIndexAutoReload = true,
	configAutoReload = false
};

Implicit Event Settings

coldbox={
	//Implicit Events
	defaultEvent = "General.index",
	requestStartHandler	= "Main.onRequestStart",
	requestEndHandler = "Main.onRequestEnd",
	applicationStartHandler = "Main.onAppInit",
	applicationEndHandler = "Main.onAppEnd",
	sessionStartHandler = "Main.onSessionEnd",
	sessionEndHandler = "Main.onSessionStart",
	missingTemplateHandler = "Main.onMissingTemplate"
}

Extension Points Settings

coldbox={
	//Extension Points
	UDFLibraryFile 			= "includes/helpers/ApplicationHelper.cfm",
	coldboxExtensionsLocation = "sharedstuff.coldbox.extensions",
	modulesExternalLocation = ["/customer1/appmodules", "/shared/app/modules"],
	pluginsExternalLocation = "sharedstuff.coldbox.plugins",
	viewsExternalLocation	= "/sharedstuff/appViews",
	layoutsExternalLocation = "/sharedstuff/appLayouts",
	handlersExternalLocation  = "sharedstuff.appHandlers",
	requestContextDecorator = "#appMapping#.model.coldbox.MyRequestContext"
}

Exception Handling

coldbox={
	//Exception Handling
	exceptionHandler = "main.onException",
	onInvalidEvent = "main.pageNotFound",
	customErrorTemplate = "includes/templates/generic_error.cfm"
}

Application Aspects

coldbox={
	// Application Aspects
	handlerCaching 			= false,
	eventCaching			= true,
	proxyReturnCollection 	= false,
	flashURLPersistScope	= "session"	
}

// Custom Flash CFC Path
flashURLPersistScope	= "sharedStuff.flash.MyAwesomeFlashScope"

conventions

This element defines custom conventions for your application. By default, the framework has a default set of conventions that you need to adhere too. However, if you would like to implement your own conventions for a specific application, you can use this setting, otherwise do not declare it:

//Conventions
conventions = {
	handlersLocation = "controllers",
	pluginsLocation  = "plugins",
	viewsLocation 	 = "views",
	layoutsLocation  = "views",
	modelsLocation 	 = "model",
	modulesLocation  = "modules",
	eventAction 	 = "index"
};

datasources

This element is used to define metadata about datasources used in your application. This in no way means that whatever datasource you define here, ColdBox will register in the ColdFusion engine. No, this setting is for documentation and easy usage of datasources in your application. ColdBox even enables you to create datasource bean objects that represent these defined datasources and use them pretty much anywhere.

To get started you need to create internal structures that represent a datasource and the key that you use in the datasources structure is the alias of the datasource that you can use later on to autowire datasources or request datasource beans.

//Datasources
datasources = {
	alias1 = { name="", dbType="", username="", password=""},
	alias2 = { name="", dbType="", username="", password=""}
};

As you can see from the previous example, each internal key of the main datasources structure has another structure defined with the following elements:

//Datasources
datasources = {
	blog = { name="blog2009", dbType="MSSQL", username="", password=""},
	customers = { name="customers2010", dbType="MySQL", username="cn44", password="root"}
};

debugger

This element defines how the ColdBox debugger behaves and looks. If you do not need to alter this behavior then do not declare this structure.

// ColdBox Debugger Settings
debugger = {
	enableDumpVar = false,
	persistentRequestProfilers = true,
	maxPersistentRequestProfilers = 20,
	maxRCPanelQueryRows = 10,
	//Panels
	showTracerPanel = true,
	expandedTracerPanel = true,
	showInfoPanel = true,
	expandedInfoPanel = true,
	showCachePanel = true,
	expandedCachePanel = true,
	showRCPanel = true,
	expandedRCPanel = true,
	showModulesPanel = true,
	expandedModulesPanel = false
};

environments

The configuration CFC has embedded environment control and detection built in and it is much more extensive than using the Environment Interceptor and the XML approach. In this structure you will setup the environments and their associated regular expressions for its cgi host names to match. If the framework matches the regex with the associated cgi.http_host of the startup request then it will set a setting called Environment in your configuration settings and will then go ahead and look for that environment setting name in your CFC as a method. That's right, it will check if your CFC has a method with the same name as the environment and if it exists it will call it for you. Here is where you basically override, remove or add any settings according to your environment.

environments = {
	development = "^cf9.,^railo."
};

In the above example, I declare a development key with a value list of a regular expressions. So if I am in a host that starts with cf9 this will match and set the environment setting equal to development and then look for a development method in this CFC and execute it:

/**
* Executed whenever the development environment is detected
*/
function development(){
	// Override coldbox directives
	coldbox.handlerCaching = false;
	coldbox.eventCaching = false;
	coldbox.debugPassword = "";
	coldbox.reinitPassword = "";
	
	// Add dev only interceptors
	arrayAppend(interceptors, {class="coldbox.system.interceptors.ColdboxSidebar} );
}

Isn't this cool? Just create a method with the same name of the environment and go for it, sure makes life simpler! But what if I have my own strategy on detecting my environment that doe not involve the cgi.http_host?

Custom Environment Detection

You then will do your own custom environment detection. You will NOT fill out an environments structure but actually create a method with the following signature:

string public detectEnvironment(){
}

Create a public method called detectEnvironment() that returns a string. If the framework detects that you have created this method, it will call it for you. You will then do your own custom environment detection and return the name of the environment you are on as a string. The framework will then save that string as the current environment setting and look for a method with that same name and execute it if it exists. So there you go, if you don't like our basic approach, then override it and extend it.

i18n

The i18n structure is used to activate the localization and internationalization features of ColdBox. All you have to do is fill out the following keys:

{name}_{java standard locale}.properties

//i18n & Localization
i18n = {
	defaultResourceBundle = "includes/i18n/main",
	defaultLocale = "en_US",
	localeStorage = "session",
	unknownTranslation = "**NOT FOUND**"		
};

Good i18n Resources

• ColdBox i18n Guide
• Paul Hastings cfc: http://www.sustainablegis.com/unicode/resourceBundle/rb.cfm
• For ISO Language Code information look at: http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
• For ISO Country Code information look at: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
• For locale information look at http://java.sun.com/j2se/1.4.2/docs/guide/intl/locale.doc.html
• A free open source java translation editor http://attesoro.org/

Sample resource bundle

help_button=Help
closeLink=<a href='javascript:window.close()'>Close</a>
relocate_button=Relocate Now!
intro_message=Welcome to my website.
search_button=Search It!
search_test=<i>Search for postings now.</i>

interceptorSettings

This structures configures the interceptor service in your application. Below are the main configuration keys:

//Interceptor Settings
interceptorSettings = {
	throwOnInvalidStates = false,
	customInterceptionPoints = "onLogin,onWikiTranslation,onAppClose"
};

interceptors

This is an array of interceptor definitions that you will use to register them in your application. The key about this array is that ORDER matters. The interceptors will fire in the order that you register them whenever their interception points are announce, so please watch out for this caveat. Each array element is a structure that describes what interceptor to register. Below are the keys needed to register an interceptor:

//Register interceptors as an array, we need order
interceptors = [
	//Autowire
	{class="coldbox.system.interceptors.Autowire",
	 properties={useSetterInjection=false}
	},
	//SES
	{class="coldbox.system.interceptors.SES", name="MySES"}
];

ioc

This structure is used to declare the integration of third party dependency injection - inversion of control frameworks such as WireBox or ColdSpring or LightWire or your own. Below are the configuration keys for this structure:

//IOC Integration
ioc = {
	framework 		= "coldspring",
	reload 	  	  	= true,
	objectCaching 	= false,
	definitionFile  = "config/coldspring.xml.cfm"
};

layoutSettings

This structure is used in order to control de directives of the ColdBox layout manager. Below are the keys you can configure:

//Layout Settings
layoutSettings = {
	defaultLayout = "Main.cfm",
	defaultView   = "youForgot.cfm"
};

You will get more in depth information about the layout manager in the Layouts & Views Guide.

layouts

The layouts array element is used to define implicit associations between layouts and views/folders, this does not mean that you need to register ALL your layouts. This is a convenience for pairing them, we are in a conventions framework remember. Before any renderings occur or lookups, the framework will check this array of associations to try and match in what layout a view should be rendered in. It is also used to create aliases for layouts so you can use aliases in your code instead of the real file name and locations. Each array element is a structure that contains the following keys:

//Register Layouts
layouts = [
	{ name="tester",file="Layout.tester.cfm",views="vwLogin,test",folders="tags,pdf/single"	},
	{ name="login",file="Login.cfm",folders="^admin/security"}
];

logBox

The logBox structure is based on the LogBox declaration DSL, see LogBox. Below are the main keys you can fill out:

Appender Definition

So to define an appender you must define a key value which is the internal name of the appender with the following keys:

//LogBox DSL
logBox = {
	// Define Appenders
	appenders = {
		coldboxTracer = { 
		  class="coldbox.system.logging.appenders.ColdboxTracerAppender",
		  layout="coldbox.testing.cases.logging.MockLayout", 
		  properties = {
		    name = "awesome"
		  },
		  rollingFile = {
		    class="coldbox.system.logging.appenders.AsyncRollingFileAppender",
			levelMax="WARN",
			levelMin="FATAL",
			properties={
			  filePath="/#appMapping#/logs",
			  autoExpand="true",
			  fileMaxSize="3000",
			  fileMaxArchives="5"
			}
		  }
		}
	}
};

Root Logger

To define the root logger you can use the following keys:

//LogBox DSL
logBox = {
	root = { levelMin="FATAL", levelMax="INFO", appenders="*" }
};

Categories

Categories are defined by creating a set of structures within it with the key name being the name of the category you would like to declare and the following internal structure keys:

As you might notice the name of the keys on all the structures match 100% to the programmatic methods you can also use to configure logBox. So when in doubt, refer back to the argument names.

logBox = {
	// Categories
	categories = {
		"coldbox.system" = { levelMax="INFO" },
		"coldbox.system.interceptors" = { levelMin=0, levelMax="DEBUG", appenders="*" },
		"hello.model" = {levelMax=4, appenders="*" }
	}
};

Implicit Categories

You can then define the implicit logging categories by using the severity name and assigning an array of categories to them:

logBox = {
	debug  = [ "coldbox.system", "model.system" ],
	info = [ "hello.model", "yes.wow.wow" ],
	warn = [ "hello.model", "yes.wow.wow" ],
	error = [ "hello.model", "yes.wow1.wow" ],
	fatal = [ "hello.model", "yes.wow.wow" ],
	OFF = [ "hello.model", "yes.wow.wo2w" ] 
};

mailSettings

This element is a purely metadata element that you use to register mailing metadata. The framework can then also help you create a metadata object called MailSettingsBean with this information:

//Mailsettings
mailSettings = {
	server = "mail.mydomain.com",
	username = "lui@mydomain.com",
	password = "YouRock",
	port = 25
};

modules

The modules structure is used to configure the behavior of the ColdBox Modules.

Let's explore these settings:

modules = {
	autoReload = true,
	include = [],
	exclude = ["paidModule1","paidModule2"]
};

settings

This element is used by the developer to set any values he/she would like to use in the application. This can be configuration settings, etc. Remember that you can use any of the already created variables in this CFC or the injected variables to concatenate or append your own settings. Also, since you are in a programmatic CFC you can pretty much do whatever you like here.

// Custom Settings
settings = {
	useSkins = true,
	myCoolArray = [1,2,3,4],
	skinsPath = "views/skins",
	myUtil = createObject("component","#appmapping#.model.util.MyUtility")
};

We will cover all the methods to interact with settings later on, but the simplest way to get settings is well, to use:

getSetting(name,[FWSetting=false])

webservices

Since we are now in a service oriented web architecture, this was a great way to declare all the web services my application that will be used. ColdBox reads these elements and places them in the configuration structure. You can then use the webservices plugin to get the webservice's URL, get a webservice object already instantiated or refresh the web services's stubs or use WireBox to autowire webservice objects according to their registered names. So the key is the alias you want to use in your application and the value is the WSDL URL.

//webservices
webservices = {
	testWS = "http://www.test.com/test.cfc?wsdl",
	AnotherTestWS = "http://www.coldbox.org/distribution/updatews.cfc?wsdl"	
};

wirebox

This configuration structure is used to configure the WireBox dependency injection framework embedded in ColdBox. For version 3.0.0 you must enable it in order to be used as the primary engine. If not, we will fall back to a compatibility mode engine until ColdBox 3.1 is released. Why do we do this? Well, ColdBox 3 is still valid for ColdFusion 7 and WireBox is for ColdFusion 8 and above. Therefore, you must explicitly enable it for 3.0.0. However, please note that the enabled key will be droped by the next release:

// wirebox integration
wirebox = {
	enabled = true,
	singletonReload = true,
	binder = 'config.WireBox'
};

Interacting With The Loaded Settings

Now that you know how to configure your application, you can now check out how to interact with those loaded settings.

Download in other Formats:
Markup | PDF | HTML | Word

Comments (1)

Add Comment

Brett said

at 05:22:07 PM 04-Dec-2010

I think you should highlight in the interceptor settings that if you are registering two interceptors with the same name (same cfc name or setting name) only one will be registered. Right now it just says "unique name" but nothing about if the name is not unique. It took me a while to figure this out. In my case I had two interceptors in two separate modules named the same but only one would execute...