ColdBox Settings & Configurations Guide
Introduction
In this guide you will learn how ColdBox works internally, how you can configure it for certain environments, its internal methods and its data structures. This is a more in depth guide and it should shed light on the internals of the framework and how to use the internal data structures to your advantage. There are a lot of variables and settings that the framework exposes for your usage and you should know about them in order to not do several tasks over and over again.
Overview
In order to create a ColdBox application you must adhere to some naming conventions and a directory structure. This is required in order for ColdBox to find what it needs and to help you find modules easier. It is up to you to organize your code. Another great place to start is the Event Handlers Guide and the Config Guide. Below are links to the guides and the best places to start creating your applications. This guide mostly involves the internals of the framework and how to use them.
- Config Guide
- Event handlers Guide
- Plugins Guide
- Internationalization (i18N) Guide
- My First Application
The Internal Structures
ColdBox uses two internal structures in order to configure and run your applications. One is the ColdBox Settings and the other is the Configuration Settings , which are created on the application's initial request. The ColdBox Settings and the Configuration Settings reside inside the ColdBox application controller and can be reinitialized by using the fwreinit=1 url param. See URL Actions.
- ColdBox Settings : Framework specific settings.
- Configuration Settings : Your application settings.
Configuration Settings (Your Application)
The Configuration Settings Structure is the structure that gets created according to your coldbox.xml.cfm file. All your application settings are here. You can retrieve any setting (key) from this structure by using the getSetting() method call, which you can do from your event handlers, plugins, interceptors, layouts and views. You can also create new settings programmatically by using the setSetting() method. You can also verify that a setting value exits by using the settingExists() method. There are also several methods available to you that interact with this structure like retrieving webservice's urls or creating web service objects from the urls, getting datasource beans, getting resource bundle keys, etc. The best place to start for all this methods, is for you to study the Framework CFC API.
Extra Configuration Keys Created For You
Apart from converting your coldbox.xml into the Configuration Structure, ColdBox will also add a few keys to the structure to help you out in your application development.
| Key | Description |
| AppMapping | The path to your application relative to the webroot. This is calculated by ColdBox |
| ApplicationPath | This is the absolute path to your running application |
| ConfigTimeStamp | The datetimestamp on the coldbox.xml. This is used if you would like to do date/time checking on it and run an auto reload |
| Environment | This key is created for you according to where your application is running. The possible values are DEVELOPMENT or PRODUCTION. This is calculated with the <DevEnvironments> element in your config. |
| ExpandedColdboxLogsLocation | If using ColdBox logging, this is the expanded location of the log file |
| HandlerInvocationPath | This path is calculated by ColdBox in order to instantiate your handlers |
| HandlersPath | This is the absolute path to your handlers directory. This is the directory that ColdBox will traverse and auto-register |
| HandlersExternalLocation | This is the instantiation path of external handlers |
| HandlersExternalLocationPath | This is the full path of external handlers |
| MyPluginsInvocationPath | The instantiation path of the plugins conventions |
| MyPluginsPath | The full path of the plugins conventions |
| MyPluginsLocation | The instantiation path of the external plugins |
| RegisteredExternalHandlers | A comma-delimited list of all the external registered handlers in your application. |
| RegisteredHandlers | A comma-delimited list of all the registered handlers in your application. |
| RBundles | A structure for keeping resource bundles |
| using_i18N | The flag that i18N is used else false |
| htmlBaseURL | the html base url as per the Base URL set in your routes.cfm configuration (no index.cfm) |
| sesBaseURL | The exact base url you placed in your routes.cfm configuration |
As with any other configuration structure key, you retrieve them via the getSetting("key") method. For an up to date key set, please dump the configuration settings in your application:
<cfdump var="#getController().getConfigSettings()#">
How do I use settings in my model?
As you can see, you get all these settings and configuration keys available to you via the API. So please use them. Another useful feature about the API is that it can give you a copy of the structure for you to send to model components if necessary. This is necessary if you are not using a dependency injection framework like ColdSpring or LightWire. You can also request a new Configuration Bean.
getSettingStructure([boolean FWSetting="false"], [boolean DeepCopyFlag="false"])
//Sample injection of the application's configuration & framework structure to a service locator //fired on the application start handler. <cfset var oServiceLocator = CreateObject("component","model.serviceLocator").init( getSettingStructure(false), getSettingStructure(true) )> //persist the service locator in cash, indefinetly <cfset getColdBoxOCM().set("oServiceLocator", oServiceLocator,0)>
You can also use the new ColdBox Factory cfc that can be called via ColdSpring to create plugins, config beans, cache manager, etc. So there are several ways that you will see in the guides to help you get the configuration settings into your model.
Configuration Structure and IoC frameworks like Coldspring?
ColdBox implements an IoC proxy via a plugin and when Coldspring gets created by the proxy, the Configuration Structure gets passed to the Coldspring factory. This is a great feature, because you do not have to write configuration files twice. So you can use the following in your coldspring xml file if ColdSpring supports multi-nested values (Datasources.coldboxreader):
<!--ColdBox Datasource Bean, created by the config structure's dsn alias--> <bean id="datasourceBean" class="coldbox.system.beans.datasourceBean"> <property name="name"><value>${Datasources.coldboxreader.name}</value></property> <property name="DBType"><value>${Datasources.coldboxreader.DBTYPE}</value></property> <property name="Username"><value>${Datasources.coldboxreader.Username}</value></property> <property name="Password"><value>${Datasources.coldboxreader.Password}</value></property> </bean>
From this bean declaration, coldspring will create a coldbox datasource bean using the <Datasource> information that you declared in the coldbox.xml. This is why knowing the configuration structure is so important, you have control and knowledge of how to use them. You can then see how to retrieve a key from the configuration structure for specifying a property such as name : <value>${Datasources.coldboxreader.name}</value>
Framework Settings Structure (Framework Settings)
The Framework Settings is the internal structure that ColdBox uses in order to run and execute your requests. It is also used to configure certain aspects of the framework that you can change if needed. You can also use the keys for anything you might need in your application. There are several useful entries in this structure that contain information you don't need to retrieve again. You can get these settings by using the getSetting() method call. However, you need to pass a boolean true as a second parameter in order to retrieve settings from the Framework Settings
<cfset coldboxversion = getSetting( 'Version' ,true)> <cfset ConfigFileSchemaLocation= getSetting( ConfigFileSchemaLocation,1)>
You can also modify some of these global settings by using the ColdBox Dashboard application or just manually modifying the settings.xml file located in the config folder of the coldbox installation package: coldbox/system/config/settings.xml. In order for the settings to take place on a running application, you will have to manually reinitialize the framework using the fwreinit url action.
Below is a table of the keys in this structure as of ColdBox latest version:
| Key | Description |
| ApplicationPath | The absolute path to the running application |
| Author | The ColdBox author, me!! |
| AuthorEmail | The ColdBox author's email address. |
| AuthorWebsite | The ColdBox official website address. |
| !AvailableCFCharacterSets | A comma delimited list of the available character sets that you can use for file operations via the fileUtilities plugin. |
| AvailableLogFileEncodings | A comma delimited list of the available character encodings that you can use for log files. |
| CFMLEngine | Either ADOBE, RAILO or BLUEDRAGON |
| CFMLVersion | First integer only: 7,8 |
| CacheEvictionPolicy | The default cache eviction policy |
| CacheFreeMemoryPercentageThreshold | The framework default memory percentage threshold. |
| CacheMaxObjects | The maximum number of objects to cache in the ColdBox cache. |
| CacheObjectDefaultTimeout | The default timeout of objects in the ColdBox cache. This setting is in minutes |
| CacheObjectDefaultLastAccessTimeout | The default last access timeout of objects in the ColdBox cache. This means that if an object has not been accessed in (X) minutes, then remove it from cache. This setting is in minutes |
| CacheReapFrequency | The frequency in which the cache should be garbage collected. This setting is in minutes |
| CacheUseLastAccessTimeouts | The boolean flag telling if last access timeouts should be used |
| Codename | The codename of your current ColdBox installation. |
| ColdspringBeanFactory | The invocation path to the coldspring bean factory: coldspring.beans.DefaultXMLBeanFactory |
| ConfigFileLocation | The physical path to the current running's application config.xml.cfm file |
| ConfigFileSchemaLocation | The physical path to the ColdBox's Config File Schema, config.xsd |
| DefaultFileCharacterSet | The default character set used for file operations |
| DefaultLogDirectory | The default log directory to use if one is not set in the application. This is relative to the App Mapping setting. |
| Description | The description of the framework. |
| EventName | The default event name variable to use. |
| FrameworkAPI | The link to the live API of ColdBox |
| FrameworkBlog | The link to the ColdBox live blog |
| FrameworkForums | The link to the ColdBox live forums |
| FrameworkPath | The physical path to the current running ColdBox installation. |
| FrameworkPluginsPath | The physical path to the current running ColdBox plugins folder. |
| FrameworkTrac | The link to the ColdBox Trac Site |
| HandlersConvention | The default handlers convention to use |
| LayoutsConvention | The default layout conventions to use |
| LightWireBeanFactory | The LightWire factory instantiation path. |
| LogFileMaxArchives | The number of archives to keep in rotation. |
| LogFileEncoding | The file encoding for the log files. |
| LogFileMaxSize | The maximum size in kbytes. Once the log file reaches this size it will be zipped and archived. |
| MessageBoxStorage | The storage scope for the messagebox plugin. By default is session. |
| ModifyLogLocation | The physical path to the ColdBox readme.txt file. |
| OSFileSeparator | The File System Separator of your current running operating system. |
| Suffix | A codename key for the version of ColdBox. |
| Version | The current version of your ColdBox installation. |
| ViewsConvention | The default convention to look for the views in your application |
| chartingActive | Whether charting is active for your specific CF engine |
| pluginsConvention | The default plugins convention to use |
| xmlParseActive | Whether xml parsing is active in this CF engine |
| xmlValidate | Whether xml validation is active in this CF engine |
Conclusion
This concludes the Framework & Configuration settings guide. I hope you can now get a better understanding of how ColdBox works and the settings and configuration settings it can give you at application runtime. Please note that you can change these settings in the settings.xml and your local application's configuration file. However, please understand that you can seriously alter the framework if you have not yet an understanding of the settings. So please read about them again and again.
