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

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.

CommandBox is written in CFML, which puts any CFML developer in a position to easily build upon it for their own needs. CommandBox is not only a CLI tool and collection of pre-built commands, but also an extensible framework for building your own CFML-based automations. The core is modular such that anyone can extend it themselves or via the help of community modules hosted on ForgeBox, or any other installation endpoint.

Modularity

The unit of re-use in CommandBox is the module. A module is nothing more than a folder containing some settings and code that follows a convention. Modules mean that you can develop your own additions and customizations to the tool without needing to modify the core code.

Read about Developing Modules here.

Custom Commands

CommandBox's expressive CLI gets its power from commands. You can create your own commands by packaging simple CFCs inside of modules. This is a powerful way to create custom, reusable CFML scripts that interact with the user, automate hard tasks, and can be shared with other developers. Commands are better than stand alone CFML files because they have very well-defined parameters, validation, and WireBox DI.

Read about Developing Commands here.

Event Model

Customizing the internals of CommandBox is achieved via an event model known as interceptors. What this means is that at pre-defined points in the lifecylce of the shell, command execution, or web server starting, the CLI broadcasts events that you can listen to. This lets you provide custom error handling, special server handling, or modify command output. Interceptors are packaged up in modules and can be combined with custom commands and config settings for fully-configurable shell add-ons.

Read about Developing Interceptors here.

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 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 ){