Config Guide (coldbox.xml & config.xml)

  1. Config Guide (coldbox.xml & config.xml)
    1. Overview
    2. Sample Config.xml
    3. Generated Schema Documentation
    4. Loading another configuration File
    5. Interacting With The Loaded Settings
      1. Methods
      2. Code Samples
    6. <Settings> Element
      1. Settings Chart
      2. AppName
      3. AppMapping
      4. AppDevMapping
      5. ApplicationStartHandler
      6. CustomErrorTemplate
      7. CustomEmailBugReport
      8. ColdboxLogsLocation
      9. ConfigAutoReload
      10. DebugMode
      11. DebugPassword
      12. DefaultEvent
      13. EventName
      14. ExceptionHandler
      15. EnableBugReports
      16. EnableColdfusionLogging
      17. EnableDumpVar
      18. EnableColdboxLogging
      19. EventCaching
      20. HandlersIndexAutoReload
      21. HandlersExternalLocation
      22. HandlerCaching
      23. IOCFramework
      24. IOCDefinitionFile
      25. IOCObjectCaching
      26. MessageboxStyleClass
      27. MessageboxStyleOverride
      28. MyPluginsLocation
      29. onInvalidEvent
      30. OwnerEmail
      31. ProxyReturnCollection
      32. RequestStartHandler
      33. RequestEndHandler
      34. RequestContextDecorator
      35. ReinitPassword
      36. SessionStartHandler
      37. SessionEndHandler
      38. UDFLibraryFile
    7. <YourSettings>
      1. Complex Variable Syntax
        1. Arrays
        2. Structures
      2. How Do I Use Them?
    8. <MailServerSettings>
    9. <BugTracerReports>
    10. <DevEnvironments>
    11. <WebServices>
    12. <Layouts>
    13. <i18N>
      1. i18N Resources
    14. <Datasources>
    15. <Cache>
      1. Object Default Timeout
      2. Object Default Last Access Timeout
      3. Use Last Access Timeouts
      4. Reap Frequency
      5. Max Objects
      6. JVM Free Memory Percentage Threshold
      7. EvictionPolicy
    16. <Interceptors>
      1. throwOnInvalidStates Attribute
      2. CustomInterceptionPoints
      3. Interceptor Element
        1. Class Attribute
        2. Property Elements
    17. Conclusion

Overview

The config file is the heart of your ColdBox application. It contains the initialization variables for your application and extra information used by the ColdBox software aspects. Below is an overview of every section of the file and how to configure an application. To provide code hinting and simple validation, I have included a config.xsd file for your usage. This file can be found at /coldbox/system/config/config.xsd. You can then use any of the tools below to help you get coding hints, color coding and validation.

XML & ColdFusion Tools


Note About Security: Your config.xml or coldbox.xml file is actually a cfm template. I did this in order to protect the download of the file with the use of an Application.cfm template (Thanks to Raymond Camden). However, for added security I also use an apache access file: .htaccess. You will find the .htaccess file on the distribution archive for the config directory. This is used by Apache for executing directory security.

Read more on .htaccess.

In IIS, you will have to configure the directory's security from the IIS Manager.

Good article on securing IIS

Sample Config.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<Config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="http://www.coldboxframework.com/schema/config_2.5.0.xsd">
<Settings>
        <!--The name of your application.-->
        <Setting name="AppName"                                         value="Your App Name here"/>
        <!--AppMapping is Optional now, if declared, it overrides an auto calculation-->
        <Setting name="AppMapping"        value="Your mapping" /><!--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=""/>
        <!--Default event name variable to use in URL/FORM etc. -->
        <Setting name="EventName"                                       value="event" />
        <!--This feature is enabled by default to permit the url dumpvar parameter-->
        <Setting name="EnableDumpVar"                           value="true" />
        <!--Log Errors and entries on the coldfusion server logs, disabled by default if not used-->
        <Setting name="EnableColdfusionLogging"         value="false" />
        <!--Log Errors and entries in ColdBox's own logging facilities. You choose the location, finally per application logging.-->
        <Setting name="EnableColdboxLogging"            value="true" />
        <!--The absolute or relative path to where you want to store your log files for this application-->
        <Setting name="ColdboxLogsLocation"                     value="logs" />
        <!--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.dspHome"/>
        <!--Event Handler to run on the start of a request, leave blank if not used. Emulates the Application.cfc onRequestStart method -->
        <Setting name="RequestStartHandler"             value="main.onRequestStart"/>
        <!--Event Handler to run at end of all requests, leave blank if not used. Emulates the Application.cfc onRequestEnd method-->
        <Setting name="RequestEndHandler"                       value="main.onRequestEnd"/>
        <!--Event Handler to run at the start of an application, leave blank if not used. Emulates the Application.cfc onApplicationStart method        -->
        <Setting name="ApplicationStartHandler"         value="main.onAppInit"/>
        <!--Event Handler to run at the start of a session, leave blank if not used.-->
        <Setting name="SessionStartHandler"             value="main.onSessionStart"/>
        <!--Event Handler to run at the end of a session, leave blank if not used.-->
        <Setting name="SessionEndHandler"                       value="main.onSessionEnd"/>
        <!--The event handler to execute on all framework exceptions. Event Handler syntax required.-->
        <Setting name="ExceptionHandler"                        value="" />
        <!--What event to fire when an invalid event is detected-->
        <Setting name="onInvalidEvent"                          value="" />
        <!--Full path from the application's root to your custom error page, else leave blank. -->
        <Setting name="CustomErrorTemplate"                     value="" />
        <!--The Email address from which all outgoing framework emails will be sent. -->
        <Setting name="OwnerEmail"                                      value="myemail@gmail.com" />
        <!-- Enable Bug Reports to be emailed out, set to true by default if left blank
                A sample template has been provided to you in includes/generic_error.cfm
         -->
        <Setting name="EnableBugReports"                        value="true"/>
        <!--UDF Library To Load on every request for your views and handlers -->
        <Setting name="UDFLibraryFile"                          value="" />
        <!--Messagebox Style Override. A boolean of wether to override the styles using your own css.-->
        <Setting name="MessageboxStyleOverride"         value="" />
        <!--Flag to Auto reload the internal handlers directory listing. False for production. -->
        <Setting name="HandlersIndexAutoReload"         value="true" />
        <!--Flag to auto reload the config.xml settings. False for production. -->
        <Setting name="ConfigAutoReload"                value="true" />
        <!-- Declare the custom plugins base invocation path, if used. You have to use dot notation.Example: mymapping.myplugins        -->
        <Setting name="MyPluginsLocation"               value="" />
        <!-- Declare the external handlers base invocation path, if used. You have to use dot notation.Example: mymapping.myhandlers    -->
        <Setting name="HandlersExternalLocation"        value="" />
        <!--Flag to cache handlers. Default if left blank is true. -->
        <Setting name="HandlerCaching"                          value="false"/>
        <!--Flag to cache events if metadata declared. Default is true -->
        <Setting name="EventCaching"                            value="false"/>
        <!--IOC Framework if Used, else leave blank-->
        <Setting name="IOCFramework"                            value="" />
        <!--IOC Definition File Path, relative or absolute -->
        <Setting name="IOCDefinitionFile"                       value="" />
        <!--IOC Object Caching, true/false. For ColdBox to cache your IoC beans-->
        <Setting name="IOCObjectCaching"                        value="false" />
        <!--Request Context Decorator, leave blank if not using. Full instantiation path -->
        <Setting name="RequestContextDecorator"         value=""/>
        <!--Flag if the proxy returns the entire request collection or what the event handlers return, default is false -->
        <Setting name="ProxyReturnCollection"           value="false"/>
</Settings>

<YourSettings>
 <Setting name="MySetting" value="My Value"/>
</YourSettings>

<MailServerSettings>
 <MailServer></MailServer>
 <MailPort></MailPort>
 <MailUsername></MailUsername>
 <MailPassword></MailPassword>
</MailServerSettings>

<BugTracerReports>
 <BugEmail>myemail@gmail.com</BugEmail>
</BugTracerReports>

<DevEnvironments>
  <url>dev</url>
  <url>dev1</url>
</DevEnvironments>

<WebServices>
 <WebService name="TESTWS" URL="http://www.test.com/test.cfc?wsdl" DevURL="http://dev.test.com/test.cfc?wsdl" />
</WebServices>

<Layouts>
 <!--Declare the default layout, MANDATORY-->
 <DefaultLayout>Layout.Main.cfm</DefaultLayout>
 <DefaultView>home</DefaultView>
 <!--Declare other layouts, with view assignments if needed, else do not write them-->
 <Layout file="Layout.Popup.cfm" name="popup">
   <!--You can declare all the views that you want to appear with the above layout-->
   <View>vwTest</View>
   <View>vwMyView</View>
   <Folder>tags</Folder>
 </Layout>
</Layouts>

<!--Internationalization and resource Bundle setup:
    Leave blank if not used: <i18N />-->
<i18N>
 <DefaultResourceBundle>includes/main</DefaultResourceBundle>
 <DefaultLocale>en_US</DefaultLocale>
 <LocaleStorage>session</LocaleStorage>
</i18N>

<Datasources>
 <Datasource alias="mysite" name="MyDSN"   dbtype="mysql"  username="" password="" />
 <Datasource alias="blog"   name="MyBlog"  dbtype="oracle" username="" password="" />
</Datasources>

<!--ColdBox Object Caching Settings Overrides the Framework-wide settings-->
<Cache>
  <ObjectDefaultTimeout>45</ObjectDefaultTimeout>
  <ObjectDefaultLastAccessTimeout>15</ObjectDefaultLastAccessTimeout>
  <UseLastAccessTimeouts>true</UseLastAccessTimeouts>
  <ReapFrequency>3</ReapFrequency>
  <MaxObjects>100</MaxObjects>
  <FreeMemoryPercentageThreshold>5</FreeMemoryPercentageThreshold>
  <!-- LFU/LRU -->
  <EvictionPolicy>LFU</EvictionPolicy>
</Cache>

<!-- Interceptor Declarations 
<Interceptors throwOnInvalidStates="true">
<CustomInterceptionPoints>comma-delimited list</CustomInterceptionPoints>
<Interceptor class="full class name">
        <Property name="myProp">value</Property>
        <Property name="myArray">[1,2,3]</Property>
        <Property name="myStruct">{ key1:1, key2=2 }</Property>
</Inteceptor>
<Interceptor class="no property" />
</Interceptors>
-->

<Interceptors>
  <!-- config file is relative to app root -->
  <Interceptor class="coldbox.system.interceptors.ses">
        <Property name="configFile">config/routes.cfm</Property>
  </Interceptor>
</Interceptors>

</Config>

Generated Schema Documentation

Please use the link below to view the generated documentation about the schema file you will use to build your configuration file.

Loading another configuration File

The framework by default will look for a coldbox.xml or config.xml file in your config folder or as specified by your Naming Conventions. However, you can override the conventions and tell the framework which configuration file to load. This is important for multi-tiered environemnts, unit tests or for whatever reason you like. In order to do this, you will have to alter a processing variable in your application.cfc or index.cfm right before including the framework. Click here to read this guide and see how its done.

Interacting With The Loaded Settings

As you learned from the Setttings Guide this xml file is converted into a structure and stored in the ColdBox Application Controller alongside the Framework Settings. The framework provides you with a set of methods to interact with the structures and you can see all of them in the CFC API. However, below I layout the main methods you will call from your handlers, layouts, views and plugins.


Methods

  • getSetting([string name], [boolean FWSetting])
  • setSetting([string name], [any value])
  • settingExists([string name], [boolean FWSetting])
  • getConfigSettings()
  • getColdboxSettings()
  • getSettingStructure([boolean FWSetting], [boolean DeepCopyFlag])

Code Samples

//Get a setting
<cfset getController().getSetting("key")>
//or use facade method
<cfset getSetting("key")>

//Get the settings structure using controller getter method
<cfset getController().getConfigSettings()>
//or utility method
<cfset getSettingStructure(false)>

//Set a new setting
<cfset getController().setSetting("key", value)>
//or use facade method
<cfset setSetting("key",value)>

//Check if setting exists
<cfset getController().settingExists("key")>
//or use facade method
<cfset settingExists("key")>

If you would like to reload your settings, you will need to reinitialize the framework by using the fwreinit=1 URL action (See URL Actions Guide).

<Settings> Element

We will start off with the Settings Element. This element is used to define the framework settings, you can look at the schema to see which settings are required and which ones are optional (Here is the generated Configuration File Documentation). As a rule of thumb, I always define all of them and if I do not use the setting, the value is blank. Below is an overview table and then I will go into each setting.

Settings Chart

Setting Description Type Required Default
AppMapping: The path of your application either relative from the web root or cfmx mapping. String FALSE [Auto Calculated]
AppName: The unique name of your application. String TRUE n/a
ApplicationStartHandler The name of the onApplicationStart handler to run: ehGeneral.onAppStart, leave blank if not used. To trigger again this handler, you must reinitialize the framework: fwreinit=1 String FALSE blank
CustomErrorTemplate ColdBox comes with its own error template for exceptions and bug reports. However, if you wish to customize your errors and bug reports, which you should, then just place the location of your custom error template. For example: includes/errorpage.cfm or /mymapping/templates/error.cfm Then in order to retrieve the error, you will need to get the Exception Bean from the request collection: getValue("ExceptionBean"). You can then use this bean to render your error page. Please look at the API to get a better understanding of the bean. String FALSE blank
CustomEmailBugReport ColdBox comes with its own template for bug reporting. However, you can override it and use your own. For example: includes/bugreport.cfm or /mymapping/templates/bugreport.cfm Then in order to retrieve the error, you will need to get the Exception Bean from the request collection: getValue("ExceptionBean"). You can then use this bean to render your error page. Please look at the API to get a better understanding of the bean. String FALSE blank
ColdboxLogsLocation The logation of the ColdBox logs. Relative if using a directory within the application. Absolute location if outside of the application. String (Path) FALSE logs
ConfigAutoReload This is a flag mostly used during development. It will reload your config.xml settings on every request. Else you will have to manually reload the structures using fwreinit=1 Boolean FALSE FALSE
DebugMode Enable/Disable ColdBox debugging mode application wide. Boolean FALSE FALSE
DebugPassword The password you would like to use to go into debugmode. You will need to pass this string as a URL param combined with the DebugMode. String FALSE blank
DefaultEvent: The name of the event handler for the default event to run: ehGeneral.dspHome String TRUE n/a
EventName The name of the event variable to use in the URL/FORM, default is 'event'. String FALSE event (or framework wide setting)
ExceptionHandler The custom exception handler to run on all framework exceptions. You decide what to do, YOU HAVE THE POWER! String FALSE blank
EnableBugReports: Enable/Disable the emailing of bug reports to the emails in the BugReports element. Boolean FALSE TRUE
EnableColdfusionLogging Enable/Disable Coldfusion Error Logs. Boolean FALSE FALSE
EnableDumpVar Enable/Disable the use of the URL action to dump variables in debug mode. Boolean FALSE TRUE
EnableColdboxLogging Enable/Disable Coldbox Logging facilities. Boolean FALSE FALSE
EventCaching Enable/Disable Event Caching Boolean FALSE TRUE
HandlersIndexAutoReload This is a flag mostly used during development. ColdBox onApplication Start will read your handlers directory and store the names of the available handlers. When requests are made and handlers get instantiated, they are instantiated using the internal syntax. Thus, if you are developing and are adding handlers, with this flag set to TRUE, then ColdBox will reload the list. Else, you will have to manually reload the structures using the fwreinit=1 url action Boolean FALSE FALSE
HandlersExternalLocation This is the base instantiation path for an external location for event handlers. The framework will read all the handlers from that directory and register them as external events.  This should be a dot formatted path: myMapping.externalHandlers.blog String FALSE blank
HandlerCaching

This is useful to be set to false in development and true in production. This tells the framework to cache your event handlers. If you do not specify this setting or leave it blank, then the framework will use the default value of TRUE

 boolean FALSE TRUE
IOCFramework

This setting is used if you will be using an IoC framework like coldspring or lightwire. The only possible values are "coldspring" and "lightwire"

 String FALSE blank
IOCDefinitionFile

This is the path to the main configuration file for your IoC framework. This can either be relative to the root of your application or an absolute path.

 String (path) FALSE blank
IOCObjectCaching

This boolean variable tells the IoC plugin to cache objects created by the IoC framework in the !ColdBox Cache.

 boolean FALSE FALSE
MessageboxStyleClass Deprecated --- --- ---
MessageboxStyleOverride Whether you want to override the messagebox's css or not. boolean FALSE FALSE
MyPluginsLocation

Declare the custom plugins base invocation path, if used. You have to use dot notation. Example: mymapping.myplugins, myapplication.customplugins.
When custom plugins are called, this invocation location will be pre-pended.

 String FALSE blank
onInvalidEvent The event to execute if an invalid event is detected by the framework. For example, if garbage is sent in the event variable, then the event registered here will fire instead. String FALSE blank
OwnerEmail: The email that will be used to send all email communications by the framework. String TRUE n/a
ProxyReturnCollection A boolean flag that tells the ColdBox proxy to return the entire request collection structure or what the event handlers return boolean FALSE FALSE
RequestStartHandler: The name of the onRequestStart handler to run: ehGeneral.onRequestStart, leave blank if not used. String FALSE blank
RequestEndHandler: The name of the onRequestEnd handler to run: ehGeneral.onRequestEnd, leave blank if not used String FALSE blank
RequestContextDecorator The instantiation path to the request context decorator you would like to use. String FALSE blank
ReinitPassword The password you would like to use to reinitialize the framework using the fwreinit URL Action. String FALSE blank
SessionStartHandler: The name of the onSessionStart handler to run: ehGeneral.onSessionStart, leave blank if not used. String FALSE blank
SessionEndHandler: The name of the onRequestEnd handler to run: ehGeneral.onSessionEnd, leave blank if not used String FALSE blank
UDFLibraryFile The location of your UDF library if in use, else leave blank.ColdBox will first look in your includes directory, so you can just place the name of the UDF here, or the full path you write including CFMX Mappings. Ex: /ColdBoxSamples/includes/udf.cfm String FALSE blank

AppName

The first setting is AppName, this is just used for internal references and you can use it throughout your code using the getSetting("AppName") method.

  • This setting is required.
  • No default value

AppMapping

This is an optional setting of the complete path to your application from either the web root or from a coldfusion mapping. If you do not use this setting, then ColdBox will try to auto-calculate the path to your application from the web root. Therefore, you should fill out the setting with your path to make sure that ColdBox can find and register your application for usage.

Important Please make sure to use the AppMapping setting when using features such as the ColdBox Proxy
  • This setting is not required
  • The default value is the auto-calculated value.

AppDevMapping

  • Deprecated since version 2.0.0

ApplicationStartHandler

The ApplicationStartHandler simulates the onApplicationStart method. You can use this to setup your application variables, initial configurations, etc. The cool thing is that in order to fire it again, you can just call it from any event handler method or you can fire it by using the framework reinit action parameter. fwreinit=true

This tells the framework, to reinitialize the framework and the application to first request status. It will reload the config.xml, resource bundles, etc, and start the application fresh. This is a great way to test and debug your apps.

  • This setting is not required
  • The default value is blank

CustomErrorTemplate

The CustomErrorTemplate is a setting that simulates the cferror tag, however, you have the full Exception information stored in a bean in the request collection that the framework places for you. In this setting you place the template to display on all errors. However, the template must be inside of the application root. Once inside the template, you can access the ExceptionBean by retrieving it from the request collection: 

<cfset myException = Event.getValue("ExceptionBean")>

Then you can use the bean's methods to display the exception information in any way you want. See CFC API. I truly recommend using this feature, since it enables you to present well formatted error displays to users, without showing all the stacktrace, etc.

  • This setting is not required
  • The default value is blank

CustomEmailBugReport

The CustomEmailBugReport is a setting to declare which template to use as the bug report for emailing it out, if using the bug report feature. The template must be withing the application or using cf mappings. Once inside the template, you can access the ExceptionBean by retrieving it from the request collection: 

<cfset myException = Event.getValue("ExceptionBean")>

Then you can use the bean's methods to display the exception information in any way you want. See CFC API.

  • This setting is not required
  • The default value is blank

ColdboxLogsLocation

The ColdboxLogsLocation is where you define the path to where you want to store the ColdBox generated log files. If you leave this setting blank and the EnableColdboxLogging setting is set to true, then ColdBox will create a directory called logs for you in the root of your application or whatever default you have placed in the framework's settings.xml file. You have two options here:

  • Relative Path: Set the folder where you will store the log files relative to your application root. So for example I have a directory under my application root called logs my value for this setting will be plain and simply logs
  • Absolute Path: Let's say you want to store your log files in another location outside of your application root. Well you can!!! Just enter the full path in this value.
    • Unix Sample: /data/work/mywebsitelogs/myblog
    • Windows Sample: c:\applicationlogfiles\myblog
  • This setting is not required, but it is FUNKY
  • The default value is Logs or whatever is on the settings.xml

ConfigAutoReload

The ConfigAutoReload setting tells the framework to reload the handlers index but also all of the configuration settings, resource bundles, cleans the cache and it fires the Application Start Handler. Again, if you have errors due to your config, then reload it by using the fwreinit=1 or set this flag to true for development.

Note: Setting this setting to TRUE on production environments is not recommended. For performance issues.
  • This setting is not required
  • The default value is FALSE

DebugMode

The DebugMode setting is used to declare wether your entire application will show the ColdBox debugging information or not. This is a boolean setting. You can also activate the ColdBox debug mode for a single session by using the url parameters. See ColdBox's URL Actions

The debug cookie expires when the user closes the browser, that is, the cookie is "session only"'''
  • This setting is not required
  • The default value is FALSE

DebugPassword

This setting is used to set the debug mode on or off via the ColdBox's URL Actions.

  • This setting is not required.
  • The default value is blank

DefaultEvent

In this setting, we go a foot deeper into implicit invocations and arrive at the DefaultEvent Setting. This is where you declare your event handler and method combination that will be invoked as the first request when no event is defined in the request collection. This follows the ColdBox lifecycle, in which the first request to the application, where no event has been defined by either url or form post, the framework will execute this event. That is why you can go to index.cfm and the default event will be fired. Remember that the value must be in event handler syntax.

For a more in depth look at event handlers, look at the Event Handlers Guide. So basically you are declaring what event to fire when no event has been defined or its the user's first request.

  • This setting is required

EventName

The event name is the variable used to fire events in the framework. The default variable is event, but you can choose your own such as do,fa,e. If you do not set a variable in your config, the framework will fall back to the default value set in the settings.xml file, which is the configuration file for the framework. The default shipped variable name is event but you can also change the framework wide one.

  • This setting is not required
  • The default value is event or whatever exists in the settings.xml

ExceptionHandler

The ExceptionHandler setting is used to define the event handler method combination that will take care of your exceptions. You can use this to filter out certain exceptions, relocate to certain events, log the errors, etc. Please note that if this setting is defined, then ColdBox will not automatically log the errors for you, you will have to do it yourself. How? Well, an ExceptionBean is placed in the request collection for you to determine what to do with the exception and the CustomErrorTemplate is for you to determine how to display the exception. Look at Custom Exception Handlers

  • This setting is not required
  • The default value is blank

EnableBugReports

The EnableBugReports setting is a boolean flag that tells ColdBox whether to email bug reports to the emails declared in the BugTracerReports sections, or not. So if you do not want to send bug reports on every exception, then you MUST set this flag to false.

  • This setting is not required
  • The default value is TRUE

EnableColdfusionLogging

The EnableColdfusionLogging setting is a boolean setting that tells the framework to log all types of errors and exceptions in the ColdFusion logging facilities using cflog. ColdBox will create a new log file named after the AppName setting value. You can then use the logEntry() method to log entries to this facility (Discussed more below). You can also use the logError() and logErrorWithBean() methods.

However, as you all know, we do not always have access to the coldfusion log locations and we cannot change their locations. Thus, the introduction of ColdBox's own logging facility.

  • This setting is not required
  • The default value is FALSE

EnableDumpVar

The EnableDumpVar is a pretty cool feature that you can enable or disable. You can use the DumpVar parameter in your url in order to well, dump variables at the end of the request. However, you can only use this feature if you are in the ColdBox debug mode. You can send a variable name, scope, etc. or even a comma delimited list of variables to dump. Example: 

http://myapp.com/index.cfm?dumpvar=myvariable,session

ColdBox will dump the the myvariable variable, and the session scope. It is recommended to have this setting set to FALSE in production

  • This setting is not required
  • The default value is TRUE

EnableColdboxLogging

The EnableColdboxLogging setting is a boolean setting that tells the framework to log all types of errors and exceptions in the location specified by the ColdboxLogsLocation element (Discussed below). You can then use the logEntry() method to log entries to this facility. You can also use the logError() and logErrorWithBean() methods. This is ColdBox's AOP Error Logging. See CFC API

So now you have full control of your logging per application. Not only that, using the settings.xml of the framework, you can control the maximum size in kbytes for each log file. Once this limit is reached, ColdBox auto-archives your log files and creates a new archive. You can choose the file encoding of the log files and the maximum number of archives to keep in rotation. Well ladies and gentlemen, isn't that easy. Two values to fill out and you have logging supported in your application. You can then use the following methods to interact with the logs. However, I encourage you to view the full API of the logger.cfc plugin to understand the full power you have.

  • logErrorWithBean( exceptionBean )
  • logError( Message, [ExceptionStruct (Coldfusion cfcatch structure)], [ExtraInfo (Anthing you like to log extra)])
  • logEntry( Severity=['error','information','warning','fatal'], Message, [ExtraInfo (Simple Value extra to log)] )

This is an indispensable tool when working with AJAX.

  • This setting is not required, but it is FUNKY
  • The default value is FALSE

EventCaching

A simple boolean variable that tells the framework to activate event caching or not.

  • This setting is not required
  • The default value is TRUE

HandlersIndexAutoReload

The HandlersIndexAutoReload is a developer tool to facilitate the developer from constantly using the fwreinit=1 action flag. When ColdBox initialized the application, it introspects your handlers for metadata. It then creates an internal registry of each handler. This way, only registered handlers can be called, and with the correct syntax for any operating system. However, when you are developing, you are constantly adding/removing/editing methods inside of these handlers or even adding new handlers. That is why you can get the Event Handler Not registered exceptions. So set this flag to true, to reload the index on every request.

Note: Setting this setting to TRUE on production environments is not recommended. For performance issues.
  • This setting is not required
  • The default value is FALSE

HandlersExternalLocation

This to me is the most interesting aspect of this framework, EXTENSIBILITY. In this element you define the base invocation path to your external handlers repository. You can package them as you want or just point to a specific package. The location will be registered and all found event handlers will be parsed and registered as external events. This means that if an event is already registerd in the local location, that one will take precedence over the external location. This is a great setting for you to develop reusable handlers where one update affects all events throughout.

  • This setting is not required
  • The default value is blank

HandlerCaching

This is useful to be set to false in development and true in production. This tells the framework to cache your event handlers. If you do not specify this setting or leave it blank, then the framework will use the default value of TRUE

  • This setting is not required
  • The default value is TRUE

IOCFramework

This is a new setting as of version 2.0.0. Here is where you can declare which IoC framework you would like to use: coldspring or lightwire. Those are the only two options as of now. If you are not using an IoC framework, then ommit this setting or leave it blank. You can then use the framework via the ioc plugin. Please look at the API for more information.

  • This setting is not required
  • The default value is blank

IOCDefinitionFile

This is the location of your IoC configuration file. You can use either a relative or absoulte path. However, if the path is invalid, the framework will throw an exception. If you set this value, but not the IOCFramework setting, then this setting is ommitted. If you use Lightwire then this setting is the instantiation path to your config bean. For more information look at the Lightwire sample application. Please look at the API for more information.

  • This setting is not required
  • The default value is blank

IOCObjectCaching

This is a new setting as of version 2.0.0. This setting tells the IoC plugin to actually cache the objects created by the IoC framework in the ColdBox cache. This is a great way for ColdBox to do the created object's persistance for you in a dynamic way. In order to do this, you will have to change your IoC Definition file to say that the service or object created to NOT be a singleton and do yes for lazy loading. This tells the IoC Framework that the object is created every single time. However, the IoC plugin decorates the IoC framework. Thus, by using the IoC plugin's getBean() method, you will be retrieving from the object cache and not creating an object again. Important to note is that you will need to set the caching metadata in your objects else they inherit the framework's default timeout. See an example below:

IMPORTANT: This setting is for advanced users only. You will be messing with object persistance. 
//Cache the userService indefintely by setting a 0
<cfcomponent name="UserService" output="false" cache="true" cachetimeout="0">

//Cache my mail service for 20 minutes
<cfcomponent name="MailService" output="false" cache="true" cachetimeout="20">

//Cache my bugservice for 5 minutes
<cfcomponent name="bugService" output="false" cache="true" cachetimeout="5">

//Do not cache my cheapService
<cfcomponent name="cheapService" output="false" cache="false">
  • This setting is not required
  • The default value is FALSE

MessageboxStyleClass

  • Deprecated since version 2.5.0

MessageboxStyleOverride

The MessageboxStyleOverride setting is used in conjunction with the messagebox plugin. This is a plugin that actually builds a visual representation of a message box for errors, warnings, and informational purposes. Since it is a visual component, you can skin it using this setting. By setting this boolean setting to true, you are saying to the plugin that the css will be available already. Please look at Messagebox CSS Guide.

  • This setting is not required
  • The default value is FALSE

MyPluginsLocation

This to me is the most interesting aspect of this framework, EXTENSIBILITY. You can create your own plugins according to the !ColdBox Plugin Specification and reuse them in your applications. In this element you define the base invocation path to your custom plugins. So for example you have all your custom plugins under a coldfusion mapping called coldboxcustomplugins and inside that mapping you have organized all your plugins into packages and so forth. On this element you would just define coldboxcustomplugins as the value. Then you would use ON-DEMAND these plugins by using the getMyPlugin('plugin_path') method. 

<cfset myFeed = getMyPlugin("utilities.rss.aggregator").parseFeed(rc.feedURL)>

You can also define the base path without using coldfusion mappings. However, you must make sure that the path is correct. Remember, this is the base path to your plugin.

  • This setting is not required
  • The default value is blank

onInvalidEvent

This is a new setting of version 2.0.0 and a very useful one. This is a quick way to declare what to do if an invalid event is detected. What is an invalid event? An invalid event is an event that does not exist in your application. So here is where you declare what event to fire instead of the garbage event. I usually set this to my default event.

  • This setting is not required
  • The default value is blank

OwnerEmail

The OwnerEmail setting is used to declare the email address that will be used to send email notifications from the framework to the outside world.

  • This setting is not required
  • The default value is blank

ProxyReturnCollection

The ProxyReturnCollection is a boolean setting used when calling the ColdBox proxy. If this setting is set to true, the proxy will return back to the remote call the entire request collection structure. If set to false, it will return, whatever the event handler returned.

  • This setting is not required
  • The default value is FALSE

RequestStartHandler

The RequestStartHandler is where you declare the event handler and method combination that will be invoked at the start of every user request. This simulates the Application.cfc onRequestStart method, but enclosed within the framework. You can use this for security, variable settings, etc. From within a request start handler method, you can call other events, override incoming events, filter events, etc.

  • This setting is not required
  • The default value is blank

RequestEndHandler

The RequestEndHandler is where you declare the event handler and method combination that will be invoked at the end of every user request. This simulates the onRequestEnd method, but enclosed within the framework.

  • This setting is not required
  • The default value is blank

RequestContextDecorator

The RequestContextDecorator is used to decorate the framework's event context object. This is an advanced setting and please read the Request Context Decorators Guide for an in depth view of this setting. The value for this setting, should be the instantiating path to your decorator. 

<Setting name="RequestContextDecorator" value="myApp.model.myRequestContext" />
  • This setting is not required
  • The default value is blank

ReinitPassword

The reinit password is a new setting since version 2.0 and it helps you set a reinitialization password that works in conjunction with the fwreinit=1 URL Action. This means that if you set this setting, you need to pass it via the URL to reinitialize the framework. ColdBox's URL Actions. 

fwreinit=mypass
  • This setting is not required
  • The default value is blank

SessionStartHandler

The SessionStartHandler is where you declare the event handler and method combination that will be invoked at the start of every user session. This simulates the Application.cfc onSessionStart method, but enclosed within the framework. You can use this for security, variable settings, etc.

  • This setting is not required
  • The default value is blank

SessionEndHandler

The SessionEndHandler is where you declare the event handler and method combination that will be invoked at the end of every user session. This simulates the onSessionEnd method, but enclosed within the framework. You will receive a copy of the session structure in the request collection called: sessionReference

  • This setting is not required
  • The default value is blank

UDFLibraryFile

The UDFLibraryFile is a cool setting where you can declare the path to a UDF template to load for usage in the views, layouts and event handlers. You can use relative path's to your applications root or ColdFusion mappings. So for example if I have my udf template called udf.cfm in my includes directory under my application root, I would use: value="includes/udf.cfm" , if I have them in a mapping called: myudfs, then I would use: value="/myudfs/udf.cfm". Your very own runtime method injection mechanism.

  • This setting is not required
  • The default value is blank

<YourSettings>

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. 

<YourSettings>
   <Setting name="BlogDSN" value="my_blog" />
   <Setting name="Maintenance_mode" value="true" />
   <Setting name="Publish_emails" value="lmajano@gmail.com" />
   <Setting name="MyArray" value="[1,2,3,4,5]" />
   <Setting name="MyStructure" value="{owner:Luis Majano, smart:false, funny:maybe}" />
</YourSettings>

As you can see above, I use it to declare a datasource, a flag for maintenance, a variable to hold my publish_emails, a custom number array and a structure.

WOW!! I can create complex variables from here. Yes you can.

Complex Variable Syntax

Arrays

You can declare arrays in your setting values by just using the [] in your value attribute. It must have a comma-delimmited list inside. Examples below: 

<Setting name="GeekArray" value="[luis, Aaron, sana, oscar, rob]" />
<Setting name="EmailArary" value="[info@coldboxframework.com, bugs@coldboxframework.com]" />

Structures

You can declare structures in your setting values by just using the {} in your value attribute in combination with : or = to separate name-key pairs. Examples below: 

<Setting name="LuisProfile" value="{name:Luis, dob:09/19/1977, country:El Salvador, geek:for sure}" />
<Setting name="TransferSettings" value="{ds:/config/datasource.xml,transfer=/config/transfer.xml,def:/config/definitions}" />

How Do I Use Them?

You can then use all these settings in your applications by simply calling the getSetting("setting").{key} Method. You can even change the settings that are loaded in memory using the setSetting("key", {value}). This element is a great way to securely store your applications configurations.

<MailServerSettings>

This element is used to declare the mail server, username and password to use for the application. This is an optional element, due to the fact that if it is not declared, then ColdBox will send emails out using the values in the ColdFusion administrator. 

<MailServerSettings>
   <MailServer>mail.server.com</MailServer>
   <MailPort></MailPort>
   <MailUsername>myusername<MailUsername>
   <MailPassword>mypassword<MailPassword>
</MailServerSettings>

In the MailServer element you declare the dns or ip address of the mail server. The default MailPort is 25, but you can override it here. MailUsername is the username to use to log in to the mail server defined. MailPassword is the Mail Password, duh!

<BugTracerReports>

This element works in conjunction with the EnableBugReports setting in the first tutorial. You must have this setting flag enabled in order for ColdBox to send you any bug report. In this element you are going to declare all the email addresses that will receive bug reports by using the BugEmail element. 

<BugTracerReports>
   <BugEmail>cfcoldbox@coldbox.com</BugEmail>
   <BugEmail>joe@coldbox.com</BugEmail>
   <BugEmail>luis@gmail.com</BugEmail>
</BugTracerReports>

<DevEnvironments>

Since we all work in development environments, a common setting in development might be different in production. Thus, the nature of this element. In this element you will declare url snippets that the framework will test at initialization. Once a match is produced, the frameworks : Environment setting is set to DEVELOPMENT or PRODUCTION if none are found. This is a great way for you to declare your development urls, not the full url just parts of it, and ColdBox sets the correct internal environment. 

<DevEnvironments>
   <url>dev</url>
   <url>localhost</url>
   <url>mydev</url>
</DevEnvironments>

In the example above, I set three url fragments that the framework will test for: dev, localhost, mydev If at least one of them is found in the cgi.http_host, then ColdBox will set the Environment setting to DEVELOPMENT, else to PRODUCTION. I also recommend you use an environment interceptor for your environment settings: Environment Control Interceptor

<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. Not only that, I can declare two url's for each webservice, one for development and one for production. 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. So for example if I call getWS("luis"), ColdBox will retrieve the correct web service URL according to the environment I am on, DEVELOPMENT or PRODUCTION. I no longer have to create tons of if's statements. ColdBox does it for me by sensing its environment. 

<WebServices>
   <WebService name="newsWS" DevURL="http://devurl.com/newsws.cfc?wsdl" URL="http://prourl.com/newsws.cfc?wsdl" />
   <WebService name="emailValidator" URL="http://someip.com/validator.cfc?wsdl" />
</WebServices>

In the second web service declaration you see that their is no DevURL attribute defined. Well, that is an optional attribute. If not used, then ColdBox will use the url in the URL attribute for both DEVELOPMENT and PRODUCTION.

<Layouts>

The layouts element is used to delare the Default Layout that all views will be rendered in and to declare other Layouts and their view/folder combinations 

<Layouts>
   <DefaultLayout>Layout.Main.cfm</DefaultLayout>
   <DefaultView>home</DefaultView>
   <Layout name="popup_black" file="Layout.popup_black.cfm">
      <View>vwEmails</View>
      <View>vwPhones</View>
      <Folder>Tags</Folder>
   </Layout>
   <Layout name="print" file="Layout.print.cfm">
      <View>vwContactBook</View>
   </Layout>
   <Layout name="blog" file="Layout.blog.cfm">
      <Folder>blog</Folder>
   </Layout>
</Layouts>

As you can see from the code above, the DefaultLayout element is mandatory and you define the name of the file. This file will need to be in the layouts directory under your application root. You can then continue to declare multiple Layout elements to declare how other views will be rendered by the framework. You can see the first Layout declaration has a name of "popup_black" and a file of "Layout.popup_black.cfm". It then defines two child View elements: vwEmails, vwPhones and a Folder Element called Tags. This tells the framework that the views: vwEmails, vwPhones and all the views inside of the folder tags will be rendered in this specific layout.

The Folder element is used to declared that all views inside that folder and within will be tied to a specific layout. Please note that a Folder can only exist within one layout only.

The DefaultView element is optional and can be used to tell the framework to always render this view (located in the views directory or your convention) when the event handler does not set a view via the event.setView(view) method. This is a great way to prototype websites. See Adam Fortuna's Include Views with ColdBox as a sample of why to use this setting.

Important Note: All view declarations must NOT include the extension. ColdBox automatically appends the .cfm extension.

This information gets loaded in the configuration structure of ColdBox, so when an event handler sets any of these views, it will automatically render them in the declared layout and not in the default layouts. So if I have in an event handler: setView("vwEmails") ColdBox will render the vwEmails view in the Layout.popup_black.cfm template. You can have as many layouts as you want. And also remember that you can override a view's layout by programmatically setting it in your event handlers. A perfect example of this feature is if you want to provide a cfdocument capability throughout your entire site, for any view, you simply can override the DefaultLayout of the view by using the setLayout("template") function. This tells ColdBox to render the view in the layout that was just set and not in the one in the configuration structure. The possibilties are endless.

<i18N>

ColdBox has now since 1.1.0 FULL INTERNATIONALIZATION SUPPORT built in thanks to Paul Hastings. It makes use of java resource bundles and java locales. If you need more information about internationalization, please visit the following sites:

Now, some people might not be that familiar with this concept, I am no expert, so I tried to make ColdBox give applications i18N support without a big headache or a lot of configuration. So basically the way to add i18N support for a ColdBox application is to fill out the following configuration (3 LINES ONLY!!!) and create your resource bundles with your key-value pairs using UTF-8 encoding if you are using translations. At the end of the post is a resources section that can help you out even more. 

<i18N>
   <DefaultResourceBundle>includes/main</DefaultResourceBundle>
   <DefaultLocale>en_US</DefaultLocale>
   <LocaleStorage>session</LocaleStorage>
</i18N>

In the first element: DefaultResourceBundle you declare the location of your resource bundles without the locale part: includes/main This is not mandatory and can be left blank if your application will only use the i18n locales and methods, no translations.

This tells ColdBox that in the includes directory there will be a file that starts with main in the includes directory.

The second element DefaultLocale is used to define the default locale to use: en_US. Please remember that this is using standard java locale syntax. Look here for more details some examples are es_SV, es_DO

This gets appended to the first element to define the default file to load: includes/main_en_US.properties The text in italics is what is defined in the xml, the rest is appended by ColdBox. So make sure your files look like the following format:

{name}_{java standard locale}.properties

The third element is LocaleStorage and you have two possibilities: session or client. This tells ColdBox in what scope to store the locale of each user. This way, you can have a users running the application in different locales (languaages)

There is no big deal about resource bundles, they are files that have key-value pairs, look at the example below: 

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

So how do I change from one locale to another? look at the sample below: 

<!--- This can exist in your onAppStart --->
<cffunction name="onAppStart" access="public" returntype="void" output="false">
  <cfset getPlugin("i18n").setfwLocale(getSetting("DefaultLocale"))>
</cffunction>

<!--- Then use the following in any of your event handlers --->
<!--- rc.thisLocale is a form variable holding the locale --->
<cfset getPlugin("i18n").setfwLocale(rc.thisLocale)>

<cfset getPlugin("i18n").setfwLocale(getvalue("newlocale"))>

<cfset getPlugin("i18n").setfwLocale("en_US")>

i18N Resources

<Datasources>

The datasources element is very useful when defining datasources for your application. You can then retrieve the settings via the getDatasource("alias") method. This method will create a datasource bean with the appropriate information. 

<Datasources>
 <Datasource alias="mysite" name="MyDSN"   dbtype="mysql"  username="" password="" />
 <Datasource alias="blog"   name="MyBlog"  dbtype="oracle" username="" password="" />
</Datasources>

<Cache>

The cache element is used to configure the ColdBox object cache system. These settings will override the framework-wide settings. 

<Cache>
  <ObjectDefaultTimeout>20</ObjectDefaultTimeout>
  <ObjectDefaultLastAccessTimeout>5</ObjectDefaultLastAccessTimeout>
  <UseLastAccessTimeouts>true</UseLastAccessTimeouts>
  <ReapFrequency>1</ReapFrequency>
  <MaxObjects>0</MaxObjects>
  <FreeMemoryPercentageThreshold>0</FreeMemoryPercentageThreshold>
  <EvictionPolicy>LFU</EvictionPolicy>
</Cache>

Object Default Timeout

The timeout in minutes in which the objects will live. After object goes beyond the timeout, they will be removed from the cache.

Object Default Last Access Timeout

The timeout in minutes in which the objects have not been accessed then they will be removed from the cache.

Use Last Access Timeouts

This setting is a boolean setting that tells the cache to use the expiration algorithms that use a default last access timeout. The default setting is true.

Reap Frequency

The frequency in minutes, in which the cache manager will reap the cache for expired objects. For example, if I set this to 5 (minutes). Then whenever a request comes in and the 5 minutes have passed, the cache manager will reap the cache. So reaping occurs at a frequency of at least 5 minutes.

Max Objects

The number of maximum objects for the cache manager to cache.

JVM Free Memory Percentage Threshold

This tells the cache manager the percentage amount needed of free memory in order to cache objects. If the JVM's free memory goes below this threshold, then the cache manager stops caching objects.

EvictionPolicy

The only possible eviction policies as of now are:

  • LFU Least Frequently Used
  • LRU Least Recently Used

The default policy is LFU. This means that the object with the least usage will be purged from the cache if space is needed. However, if LRU is used, then the object that was last used will be purged.

<Interceptors>

The interceptors element is where you declare the interceptors your application will use. Please see the Interceptor's Guide for an in-depth view of interceptors.

Important: The order of declaration is very important, since if they contain the same execution points, they will be chained in the order they are declared

So let's look at a sample: 

<Interceptors throwOnInvalidStates="true">
        <CustomInterceptionPoints>comma-delimited list</CustomInterceptionPoints>
        <Interceptor class="full class name">
                <Property name="myProp">value</Property>
                <Property name="myArray">[1,2,3]</Property>
                <Property name="myStruct">{ key1:1, key2=2 }</Property>
        </Inteceptor>
        <Interceptor class="no property" />
</Interceptors>

throwOnInvalidStates Attribute

The main Interceptors element has one boolean attribute called throwOnInvalidStates.

  • The default is true
  • This tells the interceptor service to throw an exception if the state announced for interception is not valid or does not exist.

CustomInterceptionPoints

The CustomInterceptionPoints element is a comma delimmited list of custom interception points you will be registering for execution. This is the way to provide an observer-observable pattern to your applications. Again, please see the Interceptor's Guide for more information. Just note that here is where you declare the custom interception points separated by a comma if more than one.

Interceptor Element

This is the element used to declare an interceptor for execution.

Class Attribute

The class attribute is the instantiation path for this interceptor, example: coldbox.system.interceptors.ses

Property Elements

Each interceptor can have zero, one or more property elements and they can be simple or complex value, using the complex syntax used for the settings shown above.

Conclusion

As you can see from this configuration guide. ColdBox alleviates a lot of reusable and software aspects of most applications. It is the heart of your application and it is IMPRESSSIVE!! Hold your applause please. Ahh, who cares, let it rip, applaud it!!