5.4.0
ForgeBox Enterprise
Modules
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
1
component {
2
function configure(){}
3
​
4
function onCLIStart() {
5
shell.callCommand( 'upgrade' );
6
}
7
}
Copied!
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.1
function onCLIStart( interceptData ) {
2
if( interceptData.shellType == 'interactive' ) {
3
shell.callCommand( 'upgrade' );
4
}
5
}
Copied!
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:1
component {
2
function configure(){
3
settings = {
4
checkForUpdates=true
5
};
6
}
7
​
8
function onCLIStart( interceptData ) {
9
if( interceptData.shellType == 'interactive' && settings.checkForUpdates ) {
10
shell.callCommand( 'upgrade' );
11
}
12
}
13
}
Copied!
Now run the following command to override our module's default setting and turn off the update check.
1
config set modules.test.checkforupdates=false
Copied!
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:
1
package init name="Update Checker" version=1.0.0 slug="commandbox-update-checker"
2
package set type=commandbox-modules
Copied!
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.Copy link
Edit on GitHub