[[Dashboard | << Back to Dashboard ]] {|align="right" | __TOC__ |} = ColdBox Configuration File = == Overview == The ColdBox configuration 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 and how your application boots up. 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''' * [http://www.eclipse.org Eclipse] ** '''Plugins''' *** [http://www.cfeclipse.org CFEclipse] *** [http://www.eclipse.org/webtools/ Web Tools Project] *** [http://www.xmlbuddy.com/ XMLBuddy] *** [http://www.oxygenxml.com/ Oxygen XML] * [http://www.altova.com/products/xmlspy/xml_editor.html Altova's XML Spy] * [http://www.adobe.com Dreamweaver] * Good Old Notepad.
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 Coldbox.xml.cfm == true 10 50 Layout.Main.cfm 60 30 true 1 100 0 LRU config/environments.xml.cfm true config/routes.cfm == 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. This generated documentation will explain every single element and configuration you need in order to use this configuration file. * http://www.coldbox.org/documents/SchemaDocs/ == Loading another configuration File == The framework by default will look for a '''coldbox.xml.cfm''' or '''config.xml.cfm''' file in your '''config''' folder or as specified by your [[DirectoryStructure-Conventions | Naming Conventions]]. However, you can override the conventions and tell the framework which configuration file to load manually. 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 or processing a framework request. == Interacting With The Loaded Settings == As you learned from the [[ColdboxSettings | Framework 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 [http://www.coldbox.org/api CFC API]. However, below I layout the main methods you will call from your handlers, layouts, views, plugins, etc. === Methods === * '''getSetting'''([string name], [boolean FWSetting]) * '''setSetting'''([string name], [any value]) * '''settingExists'''([string name], [boolean FWSetting]) * '''getSettingStructure'''([boolean FWSetting], [boolean DeepCopyFlag]) * '''controller.getConfigSettings'''() * '''controller.getColdboxSettings'''() * '''getSettingsBean()''' : construct a ''coldbox.system.beans.ConfigBean'' with all the application settings.
'''FWSetting''' = Use the framework settings structure instead of the application settings structure
=== Code Samples === //Get a setting //Get the settings structure using controller getter method //Set a new setting //Check if setting exists //get the framework structure settings //get the application settings //Construct a configuration bean with all of my configuration settings If you would like to reload your settings, you will need to reinitialize the framework by using the '''fwreinit=1 URL action''' (See [[URLActions | URL Actions Guide]]). This is a very important url action, as most of the time your settings are cached and you need to reload them. So please read the guide. == ${setting} Replacement == This feature is available since version 2.6.2. You can use the '''${setting}''' notation, almost anywhere in the coldbox.xml file to retrieve and create dynamic settings, class paths or anything you like. You can use any setting that can be found in the coldbox.xml. The following are the locations within the coldbox.xml that you can use dynamic notation: * Within any '''' element (As long as the setting was declared before the target setting) * Within any '''' element (As long as the setting was declared before the target setting) * Interceptor Custom Interception Points * Interceptor class paths * Interceptor Properties As you can see from the samples, you can do multiple ${} notations in one value and you can even use nested values. == 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 ([http://www.coldbox.org/documents/SchemaDocs/#h-1530114522 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. Very Important to set this setting if using the coldbox proxy or remote operations, instead of letting the framework auto calculate it for you. 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 file settings, clear the cache, reset the app to first request state, on every request. Else you will have to manually reload the structures using fwreinit=1. Be careful when using this as performance decreases. 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: General.dspHome String TRUE n/a
DefaultLogLevel: The default log level to use when logging to log files.0-fatal,1-error,2-warning,3-information,4-debug numeric (0-4) false 4
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
FlashURLPersistScope The storage location of the flash RAM the framework uses. Available possibilities are session and client. String FALSE session (or framework wide settings)
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
IOCFrameworkReload

This setting is used to tell the framework to reload the entire IOC Framework on every request. Great for development.

 Boolean FALSE false
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
MessageboxStyleOverride Whether you want to override the messagebox's css or not. boolean FALSE FALSE
ModelsExternalLocation The instantiation base path of the location of external model objects string FALSE blank
ModelsObjectCaching Setting that tells the bean factory to persist model objects or not. Great for development. Boolean FALSE true
ModelsSetterInjection Use setter injection alongside metadata injection Boolean FALSE false
ModelsDebugMode Logs model creation and injections Boolean FALSE false
ModelsDICompleteUDF The global name of the UDF to call after injections (if found in cfc) string FALSE onCompleteDI
ModelsStopRecursion A comma-delimmitted list of class names where the factory should stop recursion. Ex: transfer.com.TransferDecorator string FALSE blank
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
ViewsExternalLocation The external location to use for view renderings. This location will be checked second for views to render by using the renderView() commands or setting a view. This is a great way to declare a repository of views for rendering. String FALSE blank
We will now go over each setting and describe what exactly they do, so you can get a better understanding of what switches to toggle on or off. In order to know if they are required or not or their default values, please refer to the chart above. === 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. === 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. This is the most important setting in your application, as this is how everything is calculated from.
Important Please make sure to use the AppMapping setting when using features such as the ColdBox Proxy
=== 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'''. === CustomErrorTemplate === The '''CustomErrorTemplate''' is a setting that simulates the cferror tag. However, you have the full Exception information stored in a bean (object) 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: Then you can use the bean's methods to display the exception information in any way you want. See [http://www.coldbox.org/api 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. === 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: Then you can use the bean's methods to display the exception information in any way you want. See [http://www.coldbox.org/api CFC API]. === 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 when choosing a path: * '''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 === 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. Be aware that the application will be reloaded in each request while this setting is turned on.
Note: Setting this setting to TRUE on production environments is not recommended. For performance issues.
=== 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 [[URLActions | ColdBox's URL Actions]]
The debug cookie expires when the user closes the browser, that is, the cookie is "session only"'''
=== DebugPassword === This setting is used to set the debug mode on or off via the [[URLActions | ColdBox's URL Actions]]. === 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 to the system 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 [[EventHandlers | 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. === DefaultLogLevel === This setting allows for user customization of what errors/entries to log by setting it to an integer between 0 and 4. The default log level the logger uses is '''4''', which means it will log EVERYTHING. Please see the severity log levels table below: {|cellpadding="5", class="tablelisting" ! '''severity''' !! '''log level''' |- || debug || 4 |- || information || 3 |- || warning || 2 |- || error || 1 |- || fatal || 0 |} === 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. === 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. === 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. === 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. 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. === 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''' === 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 found in the '''logger''' plugin, to log entries to this facility. You can also use the '''logError() and logErrorWithBean()''' methods, also found in the logger plugin. This is ColdBox's AOP Error Logging. See [http://www.coldbox.org/api 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 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)] ) === EventCaching === A simple boolean variable that tells the framework to activate event caching or not. === FlashURLPersistScope === This is a simple setting that tells the framework where to store the flash RAM data it uses. The only possible options right now are: * session * client If you do not have this setting defined, the framework will look for the default in its internal settings. === 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. This is done incredibly fast, so don't worry about performance hits on development.
Note: Setting this setting to TRUE on production environments is not recommended. For performance issues.
=== HandlersExternalLocation === This to me is the most interesting aspect of ColdBox, 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. === 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''' === IOCFramework === Here is where you can declare which IoC framework you would like to use in your application: '''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. [http://www.coldbox.org/api Please look at the API for more information.] === IOCFrameworkReload === Are you in development and have to be constantly hitting the reinit button because you made changes to your ioc services? Look no further. This setting will auto-reload the ioc factory on each development request so you know that you are getting the latest code changes produced for you. Of course, the default value is '''false'''. === 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 or a valid coldspring configuration file. For more information look at the Lightwire sample application and guide. === IOCObjectCaching === 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. By using the IoC plugin's '''getBean()''' method, you will be retrieving from the object cache and not creating an object again. Not only do you need to set this setting to true for the objects to get cached, but you need to add coldbox cache metadata to their cfcomponent tags in order for them to be cached. By default, the ioc plugin will NOT cache objects, unless their metadata specifies it. See an example below:
Important: This setting is for advanced users only. You will be potentially messing with object persistance.
//Cache the userService indefintely by setting a 0 //Cache my mail service for 20 minutes //Cache my bugservice for 5 minutes //Do not cache my cheapService === 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. === ModelsExternalLocation === This to me is the most interesting aspect of ColdBox, EXTENSIBILITY. In this element you define the base invocation path to your external models repository. You can package them as you want or just point to a specific package. The location will be registered and all found model objects can be used. This is a great setting for you to develop reusable model objects. Please note that model objects by convention take precedence over external model objects with the same name. We highly encourage you to use [[Models | Model Object Mappings]] to create distinctions. === ModelsObjectCaching === Tells the bean factory to cache model objects if cache metadata is found. This is great for development only as you are making every model object get recreated. === ModelsSetterInjection === This tells the bean factory to use setter injection alongside metadata injection. If you prefer not to use the metadata injections, then you can use the old method of setter injection. === ModelsDebugMode === If turned on, the bean factory will log all model creation and injections to the logging facilities. === ModelsDICompleteUDF === The global name of the UDF to call after injections (if found in cfc). Basically, after all dependency injection has been done on a target model object, the bean factory will look for a UDF with '''this''' name in the cfc. If found, it will call it. This is great for post dependency injection processing. === ModelsStopRecursion === A comma-delimmitted list of class names where the factory should stop recursion. Ex: transfer.com.TransferDecorator It stops recursion so no dependencies will be evaluated from that inheritance class. === MyPluginsLocation === Again, EXTENSIBILITY. You can create your own plugins according to the [[Recipes:My_First_Custom_Plugin | 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. or 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 instantiation path to your plugin. === onInvalidEvent === 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. If you do not set this setting, then the framework will throw an invalid event exception. === 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. === ProxyReturnCollection === The '''ProxyReturnCollection''' is a boolean setting used when calling the ColdBox proxy's process() method. 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. === 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. === 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. === RequestContextDecorator === The '''RequestContextDecorator''' is used to decorate the framework's event context object. This is an advanced setting and please read the [[RequestContextDecorator | 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. === 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 or FORM to reinitialize the framework. [[URLActions | ColdBox's URL Actions]]. 
fwreinit=mypass
=== 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. === 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''' === UDFLibraryFile === The '''UDFLibraryFile''' is a cool setting where you can declare the path to a UDF template to load for usage in 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. You can also do runtime mixins by using the '''includeUDF()''' method in your handlers/plugins/interceptors/views/layouts. === ViewsExternalLocation === This setting determines a location of where you want to have external views. So when you do a renderView() or setView() methods, the framework will search first your default convention for the view, if it cannot find it there, it will look in this external location and render it for you. This is a great way to create modules or extensible applications. == == 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. 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. === Complex Variable Syntax: JSON === All complex variable syntax is based on JSON notation. So you can go crazy and do all kinds of embedded structures, queries, etc. An important aspect in the configuration file is that instead of using double quotes (") for your JSON separators, you will have to use single quotes ('). The framework will then convert them to double quotes once it deserializes them. For an in-depth tutorial in JSON syntax, please visit this guide: http://www.json.org/ === 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. == == 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: _handlers _plugins _layouts _views go model * '''handlers location ''' : This element is to declare where your handlers are stored within the application root. In my sample its the directory '''_handlers''' * '''plugins location ''' : This element is to declare where your custom plugins are stored within the application root. In my sample it's the directory '''_plugins''' * '''layouts location ''' : This element is to declare where your layouts are stored within the application root. In my sample it's the directory '''_layouts''' * '''views location ''' : This element is to declare where your views are stored within the application root. In my sample it's the directory '''_views''' * '''event action''' : This element defines what is the default event action an event handler will use if an incoming event has no defined action. If there is no action then the framework will look for this action in the handler and execute it. * '''models location''' : This element is to declare where your model objects are stored within the application root. In my sample it's the directory '''model''' == == The debugger settings element is used to control how the ColdBox debugger works. Below are the main element that you will interact with. * '''PersistentRequestProfiler''' : This setting is a boolean setting that you use to tell the debugger to persist request profilers across requests. * '''maxPersistentRequestProfilers''' : This is the number of request profilers to keep stored in the debugger. * '''maxRCPanelQueryRows''' : This is how many rows to dump when dumping queries. The following are elements that have attributes that you can use to help you render the debugger. * '''TracerPanel''' : The panel that shows you all the code tracers ** @show : boolean (Actually render the panel) ** @expanded : boolean (Have the panel expanded or not by default) * '''InfoPanel''' : The panel that shows you all request information and request profiler ** @show : boolean (Actually render the panel) ** @expanded : boolean (Have the panel expanded or not by default) * '''CachePanel''' : The panel that shows you the cache statistics ** @show : boolean (Actually render the panel) ** @expanded : boolean (Have the panel expanded or not by default) * '''RCPanel''' : The panel that shows you the request collection at the end of the request. ** @show : boolean (Actually render the panel) ** @expanded : boolean (Have the panel expanded or not by default) == == 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. mail.server.com myusername mypassword 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! == == 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. cfcoldbox@coldbox.com joe@coldbox.com luis@gmail.com == == '''* This setting will be deprecated in 2.7 to favor the environment interceptor'''. 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. dev localhost mydev 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. == == 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. '''* The devURL will be deprecated by version 2.7 to favor the environment interceptor''' 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. == == 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. This is the core of the ColdBox layout manager capabilities. For an in-depth guide, please visit the [[Layouts-Views | layouts and views guide]]. Layout.Main.cfm home vwEmails vwPhones Tags vwContactBook blog 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 [http://www.adamfortuna.com/2007/06/10/automatically-include-your-views-with-coldbox/ 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. == == ColdBox has '''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: * [http://www.i18ngurus.com/docs/996478997.html i18Gurus] * [http://www.remotesynthesis.com/cfopensourcelist/ Open Source Listing of i18N by Brian Rinaldi] 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. includes/main en_US session UNKNOWN === Default Resource Bundle === 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. If used, this tells ColdBox that in the includes directory there will be a file that starts with ''main'' in the includes directory. === Default Locale === 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. Some examples are es_SV, es_DO This settings gets appended to the first element (default resource bundle) 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 are in the following format: 
{name}_{java standard locale}.properties
=== Locale Storage === The third element is '''!LocaleStorage''' and you have three possibilities: * session * client * cookie This tells ColdBox in what scope to store the locale of each user, not THE APPLICATION. This way, you can have a users running the application in different locales (languages) === Unknown Translation === The fourth element is '''!UnknownTranslation''' which is used by the resource bundle plugin whenever a translation cannot be found. Instead of returning the default bogus '''_UNKNOWN''', you can choose your own. 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=Close Me
relocate_button=Relocate Now!
intro_message=Welcome to my website.
search_button=Search It!
search_test=Search for postings now.
So how do I change from one locale to another? look at the sample below: === i18N Resources === * 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/ == == 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. == == The cache element is used to configure the ColdBox object cache system. These settings will override the framework-wide settings. See [[ColdboxCache | ColdBox Cache ]] 20 5 true 1 0 0 LFU === 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 * '''FIFO''' First In First Out 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. == == The interceptors element is where you declare the interceptors your application will use. Please see the [[Interceptors | 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: comma-delimited list value [1,2,3] { key1:1, key2=2 } === 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 [wiki:cbInterceptorsGuide 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. It contains one attribute: @name which is the name of the property. == Related Guides == * [[ConfigurationFile | The ColdBox Configuration File]] * [[EventHandlers | Event Handlers]] * [[RequestContext | The ColdBox Request Context]] * [[Layouts-Views | Layouts & Views]] * [[URLMappings | URL Mapping & Rewriting]] * [[Models | Model Integration]] * [[Plugins | ColdBox Plugins]] * [[Interceptors | ColdBox Interceptor ]] * [[RequestContextDecorator | Extending The Request Context]] * [[Testing | ColdBox Unit Testing & Integration Testing]] * [[ColdboxProxy | ColdBox Proxy: Powering Flex/AIR/Remote Applications]] * [[AjaxIntegration | ColdBox-Ajax Integration]]