Interacting with Settings in ColdBox

ColdBox uses the following settings to configure and run applications:

  • ColdBox Settings – framework specific
  • Configuration Settings – application specific

These two settings reside in the controller and are created on the application’s initial request. The controller is the object that models your application and lives in the application scope. To re-initialize the application, append the fwreinit=1 URL parameter, i.e. /index.cfm?fwreinit=1.

Configuration Settings

ColdBox application settings reside inside config/ColdBox.cfc. This file is often refer to as the ConfigurationCFC. Here are some of the common available operations on the ConfigurationCFC:

  • getSetting([string name], [boolean FWSetting], [defaultValue])
  • getModuleSettings(module)
  • setSetting([string name], [any value])
  • settingExists([string name], [boolean FWSetting])
  • getSettingStructure([boolean FWSetting], [boolean DeepCopyFlag])
  • controller.getConfigSettings()
  • controller.getColdboxSettings()
  • getSettingsBean() : construct a coldbox.system.core.collections.ConfigBean with all the application settings.

Use the FWSetting boolean flag to use the framework settings structure instead of the application settings structure.

Here are code samples to illustrate courtesy of ColdBox wiki:

/* Get a setting */

/* Get the settings structure using controller getter method */

/* Set a new setting */

/* Check if setting exists */

/* get the framework structure settings */
frameworkSettings = controller.getColdboxSettings();

/* get the application settings */
appSettings = controller.getConfigSettings();

/* Construct a configuration bean with all of my configuration settings */
configBean = getSettingsBean();

Retrieving Configuration Settings

Use the getSetting method to retrieve configuration settings from within:

  • event handlers
  • plugins
  • interceptors
  • layouts, and
  • views

Let’s say we have the following in the configuration settings (config/ColdBox.cfc):

  // Configure ColdBox Application
  function configure(){
    // coldbox directives
    coldbox = {
      //Application Setup
      appName      = "My Cool Application",
      eventName   = "event"
    } // coldbox

    // custom settings
    settings = {
      emails = {
        sysAdmin = "",
        appAdmin = ""
    } //settings
  } //configure

Then in your views and layouts, you can retrieve them as follows:


And in your handler, retrieve the configurations as follows:


Retrieving Configuration Settings in Models

However when trying to retrieve the configuration settings from within models (including module models), you will need to use WireBox dependency injection. Here’s a code example to illustrate:

component accessors="true" singleton="true" {
  property name="configBean" inject="coldbox:configBean";
  public void function sendForgotPasswordNotification(required User user){
    var appName = configBean.getKey("appName");
    var appAdminEmail = configBean.getKey("emails").appAdmin;
    var sysAdminEmail = configBean.getKey("emails").sysAdmin;
} //component

The line property name=”configBean” inject=”coldbox:configBean” is the dependency injection. We then use the defined property configBean in the function as follows, i.e. var appName = configBean.getKey(“appName”).

Module Configurations

Module configurations are stored in modules\<module-name>\ModuleConfig.cfc. Let’s say we have the following in our module configurations (as an example, using the Solitary security module):

function configure(){
   // parent settings
   parentSettings = {
   // module settings - stored in
   settings = {
      // emails are sent from
      senderEmail = ""
} //configure

We know that the module settings are stored in, e.g. modules.solitary.settings for the Solitary security module. So here’s a code example to illustrate how we can retrieve the settings :

component accessors="true" singleton="true" {
   property name="configBean" inject="coldbox:configBean";
   public void function sendForgotPasswordNotification(required User user){
      var settings = configBean.getKey("modules").solitary.settings;
      var senderEmail = settings.senderEmail;

Further Information

Check out these links to learn further:



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s