If you are using per-environment control in your parent application via the ColdBox.cfc, you can also use that in your Module Configuration object. So the same conventions that are used in the parent configuration can be used in the module; having the name of the environment match a method name in your module config. So if the following environments are declared in your parent configuration file and the dev environment is detected, the dev() method is called in your configuration object:

But if you declare that dev() method in your Module Configuration object, it will be called as well after your configure() method is called:

Retrieving Module Settings

Modules configurations are stored in the host parent configuration structure under a modules key according to their name. To retrieve them you can do

• getModuleSettings( module ) : Returns the structure of module settings by the module name.

• getModuleConfig( module ) : Returns the module's configuration structure

Injecting Module Settings

You can also use our injection DSL to inject module settings and configurations:

// Inject all module settings
property name="settings" inject="coldbox:modulesettings:{module}";
// Inject the module configuration structure
property name="config" inject="coldbox:moduleConfig:{module}";
// Inject a single module setting
property name="customSetting" inject="coldbox:setting:customSetting@{module}";

The injection DSL pattern is the following:

• coldbox:setting:mySetting@module : You can now inject easily a module setting by using the @module directive.

• coldbox:moduleSettings:{module} : You can now inject the entire module settings structure

• coldbox:moduleConfig:{module} : You can now inject the entire module configuration structure

Overriding Module Settings

If you have parseParentSettings set to true in your ModuleConfig.cfc (which is the default), ColdBox will look for a struct inside the moduleSettings struct of your config/ColdBox.cfc with a key equal to your module's this.modelNamespace (default is the module name) and merge them with your modules settings struct (as defined in your module's configure() method) with the parent settings overwritting the module settings. This allows a user of your module to easily overwrite specific settings for their needs.

// myModule/ModuleConfig.cfc
component {
  function configure() {
    settings = {
      someSetting = "default",
      anotherSetting = "default"
    };
  }
}

// config/ColdBox.cfc
component {
  function configure() {
    moduleSettings = {
      myModule = {
        someSetting = "overridden" 
      }
    };
  }
}

// end result
{
  someSetting = "overridden",
  anotherSetting = "default"
}

If parseParentSettings is set to false, your module's settings will instead overwrite the settings set in the same moduleSettings struct.

Using Overridden Settings in your ModuleConfig.cfc

If you want to use the overridden settings in your ModuleConfig.cfc, you will need to use it in the postModuleLoad interceptor. Remember, all your modules register the ModuleConfig.cfc as an interceptor, so all you need to do is add the postModuleLoad function and you're off!

function postModuleLoad( event, interceptData, buffer, rc, prc ) {
  binder.map( "MyAlias@MyModule" )
    .to( "#moduleMapping#.models.#settings.moduleName#" );
}

The module configuration object: ModuleConfig.cfc is the boot code of your module and where you can tell the host application how this module will behave. This component is a simple CFC, no inheritance needed, because it is decorated with methods and variables by ColdBox at runtime.

The only requirement is that this object MUST exist in the root of the module folder and contain a configure() method. This is the way modules are discovered, so if there is no ModuleConfig.cfc in the root of that folder inside of the modules folder, the framework skips it. So let's investigate what we need or can do in this component.

component{

    function configure(){

    }

}

The module configuration object is also treated as an Interceptor once it is created and configured.

Life-cycle Events

There are two life-cycle callback events you can declare in your ModuleConfig.cfc:

• onLoad() : Called when the module is loaded and activated

• onUnLoad() : Called when the module is unloaded from memory

This gives you great hooks for you to do bootup and shutdown commands for this specific module. You can build a ContentBox or Wordpress like application very easily all built in to the developing platform.

function onLoad(){
  // Register some tables in my database and activate some features
  controller.getWireBox().getInstance('MyModuleService').activate();
    log.info( 'Module #this.title# loaded correctly' );
}

function onUnLoad(){
  // Cleanup some stuff and logit
  controller.getWireBox().getInstance('MyModuleService').shutdown();

  // Log we unloaded
  log.info( 'My module unloaded successfully!' );
}

Custom Events

Also, remember that the configuration object itself is an interceptor so you can declare all of the framework's interception points in the configuration object and they will be registered as interceptors.

function preProcess(event, interceptData){
  // I just intercepted ALL incoming requests to the application
  log.info('The event executed is #arguments.event.getCurrentEvent()#');
}

This is a powerful feature, you can create an entire module based on a single CFC and just treat it as an interceptor. So get your brain into gear and let the gas run, you are going for a ride baby!

Once the public properties are set, we are now ready to configure our module. You will do this by creating a simple method called configure() and adding variables to the following configuration structures:

It is important to note that there is only ONE running application and the modules basically leach on to it. So the following structures will append their contents into the running application settings: parentSettings, datasources, webservices, customInterceptionPoints and interceptors.

All of the configuration settings that are declared in your configuration object will be added to a key in the host application settings called modules. Inside of this structure all module configurations will be stored according to their module name and remember that the module name comes from the name of the directory on disk. So if you have a module called helloworld then the settings will be stored in the following location: ConfigSettings.modules.helloworld

Below is an example of some settings:

function configure(){

  // parent settings
  parentSettings = {
    woot = "Module set it!"
  };

  // module settings - stored in the main configuration settings struct as modules.{moduleName}.settings
  settings = {
    display = "core"
  };

  // layout settings
  layoutSettings = {
    defaultLayout = "MyModuleLayout.cfm"
  };

  // Module Conventions
  conventions = {
    handlersLocation = "handlers",
    viewsLocation = "views",
    layoutsLocation = "layouts",
    pluginsLocation = "plugins",
    modelsLocation = "model"
  };

  // datasources
  datasources = {
    mysite   = {name="mySite", dbType="mysql", username="root", password="root"}
  };

  // SES Routes
  routes = [
    // load the routes.cfm in the config folder of the module
    "config/routes",
    // explicit route declared here
    {pattern="/api-docs", handler="api",action="index"}   
  ];    

  // Interceptor Config
  interceptorSettings = {
    customInterceptionPoints = "onModuleError"
  };
  interceptors = [
    {name="modulesecurity",class="#moduleMapping#.interceptors.ModuleSecurity",
     properties={
      URLMatch = '/api-docs',
      loginURL = '/api-docs/login'
     }
  ];  

  // binder mappings
  binder.map("MyModuleService").to("#moduleMapping#.model.ModuleService");
  // or easy map entire directory
  binder.mapDirectory("#moduleMapping#.model");
}

Here is a listing of all public properties that can be defined in a module.

Below you can see an example of declarations for the configuration object:

component{
    // Module Properties
    this.title      = "My Test Module";
    this.author       = "Luis Majano";
    this.webURL       = "http://www.coldbox.org";
    this.description    = "A funky test module";
    this.version      = "1.0.0";
    // If true, looks for views in the parent first, if not found, then in the module. Else vice-versa
    this.viewParentLookup   = true;
    // If true, looks for layouts in the parent first, if not found, then in module. Else vice-versa
    this.layoutParentLookup = true;
    // The module entry point using SES
    this.entryPoint     = "/testing";
    this.inheritEntryPoint = true;
    this.autoMapModels = true;
    this.autoProcessModels = false;
    this.modelNamespace = "store";
    this.aliases = [ "store", "ecommerce", "shop" ];
    this.cfmapping = "cbstore";
    this.parseParentSettings = true;
    this.dependencies = [ "JavaLoader", "CFCouchbase" ];
    this.applicationHelper = [ "includes/mixins.cfm" ]

    function configure(){
    }
}

At runtime, the configuration object will be created by ColdBox and decorated with the following private properties (available in the variables scope):

You can use any of these private variables to create module settings, load CFCs, add binder mappings, etc.