The unit of re-use in CommandBox is the module. A module is a folder containing some settings and code that follows a convention. Modules allow you you to develop your own additions and customizations to the tool without needing to modify the core code. If you have worked with the ColdBox MVC framework, CommandBox modules are very similar to ColdBox modules. If not, don't worry, they're very simple to learn.

Build Your First Module

A module is a folder that minimally contains a ModuleConfig.cfc file inside it. User modules are stored in the ~/.CommandBox/cfml/modules/ directory on your hard drive. Let's navigate to that folder and create a new sub directory called test. Now inside of our new folder, create a new file called ModuleConfig.cfc and place the following in it.

~/.CommandBox/cfml/modules/test/ModuleConfig.cfc

component {
    function configure(){}

    function onCLIStart() {
      shell.callCommand( 'upgrade' );
    }
}

This module runs the upgrade command every time the CLI starts up to check and see if you have the latest version. Pretty cool, huh?

Use Intercept Data

Let's take it a step further. Since this upgrade check could get annoying, let's only run it if we're starting the shell in interactive mode (with the blinking cursor awaiting input). That way, one-off commands from the OS shell that exit right away won't trigger the update check. Our onCLIStart() method gets an argument called intercept data that has a flag for this.

function onCLIStart( interceptData ) {
  if( interceptData.shellType == 'interactive' ) {
    shell.callCommand( 'upgrade' );
  }
}

Use A Config Setting

One final improvement. Create a module setting called checkForUpdates which defaults to true. Users can set it to false to disable the update check. Here is the final version of the ModuleConfig.cfc:

component {
    function configure(){
        settings = {
            checkForUpdates=true
        };
    }

    function onCLIStart( interceptData ) {
        if( interceptData.shellType == 'interactive' && settings.checkForUpdates ) {
            shell.callCommand( 'upgrade' );
        }
    }
}

Now run the following command to override our module's default setting and turn off the update check.

config set modules.test.checkforupdates=false

Reload the shell and you'll see the update check is gone.

Share The Love

Now that you've written your first module, you can share it with the world. The following commands run from the root folder of your module will turn it into a package:

package init name="Update Checker" version=1.0.0 slug="commandbox-update-checker"
package set type=commandbox-modules

Drop the contents of your test folder in a Github repo and now anyone can install it in their own CommandBox installation with the install command using the Git endpoint.

The configuration for a module is contained within in the ModuleConfig.cfc that lives in the root folder. Here's an overview of the options for configuring your module.

component{
    // Module Properties
    this.autoMapModels = true;
    this.modelNamespace = "test";
    this.cfmapping = "test";
    this.dependencies = [ "otherModule", "coolModule" ];

    function configure(){

        // Settings for my module
        settings = {
            mySetting = 'isCool',
            settingsCanBe = [
                'complex',
                'values'
            ]
        };

        // Declare some interceptors to listen
        interceptors = [
            {
                class='#moduleMapping#.interceptors.TestInterceptor'
            }
        ];

        // Ad-hoc interception events I will announce myself
        interceptorSettings = {
            customInterceptionPoints = ''
        };

        // Manually map some models
        binder.map( 'foo' ).to( '#moduleMapping#.com.foo.bar' );

    }

    // Runs when module is loaded
    function onLoad(){
        log.info('Module loaded successfully.' );
    }

    // Runs when module is unloaded
    function onUnLoad(){
        log.info('Module unloaded successfully.' );
    }

    // An interceptor that listens for every command that's run.
    function preCommand( interceptData ){
        // I just intercepted ALL Commands in the CLI
        log.info('The command executed is #interceptData.CommandInfo.commandString#');
    }    

}

You can control how CommandBox loads your module by setting optional settings in the this scope.

• this.autoMapModels - Will automatically map all model objects under the models folder in WireBox using @modulename as part of the alias.

• this.modelNamespace - The name of the namespace to use when registering models in WireBox. Defaults to name of the module.

• this.cfmapping - The CF mapping that will be registered for you that points to the root of the module. Defaults to name of the module.

• this.disabled - You can manually disable a module from loading and registering.

• this.dependencies - An array of dependent module names. All dependencies will be registered and activated FIRST before the module declaring them

Module Conventions

What makes modules so easy to use is the convention-over-configuration approach that lets you use expected file and folder names instead of manually configuring things. Here are some of the high-level conventions that modules use.

Configuration

/modules/ModuleName/ModuleConfig.cfc

The settings for a module is stored in the ModuleConfig.cfc file in the root of the module. This CFC is automatically created and its settings extracted when the module is loaded. It has lifecycle methods like onLoad() and onUnLoad() that will be called automatically if they exist. This CFC will also be loaded up as an interceptor, so any method names that match interception points will be registered. Read more about module configuration here.

Models

/modules/ModuleName/models/

CommandBox ships with WireBox, which is the glue that holds everything together. Your custom modules can contain as many models as they like. Place your CFCs (beans, services, etc) in the models folder and WireBox will automatically map them as modelName@moduleName so they can easily be injected into any other model, interceptor, or command CFC.

Commands

/modules/ModuleName/commands/

One of the primary purposes of modules is to serve as a delivery mechanism for custom commands. All command CFCs should be placed in the commands folder inside your module. Any CFCs there will automatically be registered when the module is loaded, and will be available in the help command, as well as tab-completion, etc. To create namespace commands, create extra sub folders inside the commands folder that match the name of the namespace. Read more about command configuration here

Interceptors

/modules/ModuleName/interceptors/

Any interceptor CFCs packaged inside a module should go in an interceptors folder. Interceptors are not loaded automatically though. You'll need to reference the component path in your ModuleConfig.cfc. The path that points to the interceptors folder can be resolved in your config file as #moduleMapping#.interceptors.MyInterceptorName. Read more about interceptor configuration here

Modules

/modules/ModuleName/modules/

Wait, what-- modules can have their own modules?? Yep, we call that "module inception" and it's one of the most powerful features of modular development. If your module depends on another CommandBox module, then specify that dependency in your module's box.json and it will automatically be installed for you inside your modules folder.

CommandBox allows you to link a module directly into the CommandBox core so that you can use the module as though it's installed but without having two copies of the code. To do this, cd to the root of the module you want to link into CommandBox.

This will create a symlink in the core CommandBox modules directory to your package and reload the shell for you so you can immediately test it out. Any further code changes you make can be tested by running the reload command again.

Unlinking

When you are done testing, you can remove the link by running the package unlink command from the root of the module you've been developing on.

This will remove the symlink for you.

Every module follows a sequence of steps when it is loaded and unloaded. Modules are automatically loaded for you when CommandBox starts up, but here are some ways for a module to affect how it loads.

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 procedures for this specific module.

function onLoad(){
    log.info('Module loaded successfully.' );
}

function onUnLoad(){
    log.info('Module unloaded successfully.' );
}

Custom Events

The ModuleConfig.cfc object itself is an interceptor so you can declare all of the CLI's interception points in the configuration object and they will be registered as interceptors.

function preCommand( interceptData ){
    // I just intercepted ALL Commands in the CLI
    log.info('The command executed is #interceptData.CommandInfo.commandString#');
}

The defaults for a module is stored in a settings struct in the ModuleConfig.cfc for that module. However, users can override those settings without needing to touch the core module code. This is made possible by special namespace in the CommandBox config settings called modules.

Consider the following module settings:

/modules/TestModule/ModuleConfig.cfc

component{
    function configure(){
        settings = {
            mySetting = 'isCool',
            somethingEnabled = true
        };
    }
}

The following config set commands will create config settings that override those. The pattern is modules.moduleName.settingName.

config set modules.TestModule.mySetting=overridden
config set modules.TestModule.somethingEnabled=false

When a module is loaded, the config settings (that exist) for that module are also loaded and overwrite the defaults from ModuleConfig.cfc. You can easily see what settings are set for our TestModule like so:

config show modules.TestModule

The configure() method will be run before a module is loaded.

Injected Variables

The following variables will be created for you in the variables scope of the ModuleConfig.cfc.

• shell - The shell object (kind of the core CommandBox controller)

• moduleMapping - The component mapping to the module

• modulePath - The physical path to the module

• logBox - The LogBox instance

• log - A named logger, ready to log!

• wirebox - Your friendly neighborhood DI engine

• binder - The WireBox binder, handy for mapping models manually

Data Structures

The configure() method does not accept or return any data. Instead, the config CFC itself represents the data for configuring the module with data structures in the variables scope. It's the job of the configure method to ensure that these data structures are created and populated.

There is no required data, but here is the list of optional data you can set:

• settings - A struct of custom module settings. These defaults can be overriden when the module is loaded with the CommandBox user config.

• interceptors - An array of declared interceptor structures that should be loaded in the entire application. Each interceptor structure contains class, and optional properties.

• interceptorSettings - A structure of settings for interceptor interactivity which includes the sub-key customInterceptionPoints, a list of custom interception points to add to the application wide interceptor service

Here is an example configure() method. Note these data structures are placed in the variables scope.

component{

  function configure(){

    // Settings for my module
    settings = {
        mySetting = 'isCool',
        settingsCanBe = [
            'complex',
            'values'
        ],
        andEven = {
            nested = {
                any = 'way'
            },
            you = 'like'
        }
    };

    // Declare some interceptors to listen
    interceptors = [
        {
            class='#moduleMapping#.interceptors.TestInterceptor'
        }, 
        {
            class='#moduleMapping#.interceptors.DoCoolThings',
            properties={
                coolnessFactor='max',
                crankItToEleven=true

            }
        }
    ];

    // Ad-hoc interception events I will announce myself
    interceptorSettings = {
        customInterceptionPoints = 'launchInitiated,velocityAcheived,singularityAcquired'
    };

    // Manually map some models
    binder.map( 'foo' ).to( '#moduleMapping#.com.foo.bar' );

  }
}

A module is nothing more than a folder that contains a ModuleConfig.cfc file. The only requirement for that CFC is that it contains a method called configure(). Modules can also contain models, interceptors, commands, and pretty much anything else you want to stick in them. As long as they contain a box.json in their root, they are also a package, which means they are self-describing, can install dependencies, and can be installed via the install command.

Locations

CommandBox has two default modules directories.

• ~/.CommandBox/cfml/system/modules

• ~/.CommandBox/cfml/modules

The first is for system modules so you shouldn't need to touch it. All the built-in commands are in those modules, so feel free to check out how they work. All user-installed modules are in the second folder. The cfml folder is the "root" of the CommandBox installation, so there will also be a box.json created in that folder once you start installing modules via the install command.

Installation

The first way to create a module is to manually create a folder in the ~/.CommandBox/cfml/modules directory and place your ModuleConfig.cfc inside of it. This is the process described in the guide on creating your first module.

If you have a package of type commandbox-modules locally, in a Git repo, or in Forgebox, you can install from any working directory. When CommandBox sees the package type, it will change the installation directory to be the user modules folder.

install /path/to/module
install githubuser/modulerepo
install forgebox-module-slug