Into The Box Notes: Making Modules, Eric Peterson

April 27, 2017

Why use modules?

We can reuse modules, improve each other’s work

versioning
can pin to 1 version if you’re worried about a future version breaking something in your app

smaller testing footprint
can pull a module out of your app and test it in isolation
can switch to unit tests (which are faster than integration testing usually).
integration - hard to know WHAT you’re testing (the app? the module? something else?)
easier to test the right thing w/ unit tests

dependency management
can have dependencies inside your own module, and incorporate that into the work you then share.

ColdBox itself is a module.
TestBox
JavaLoader
application templates
semver
ses-on-request
and more
…are all modules

Why use modules?
don’t repeat yourself
someone else may have solved that problem already
don’t reinvent the wheel
you get automatic configuration w/ modules
you get benefit from and can give back to the community.

“If you’re feeling stuck in CMFL, I have a feeling it’s because you’re not leveraging the community.”

what do you get in non-coldbox applications
-versioning
-dependency management
-installation location by convention (or setting)

what do you need to make a module?
1 thing: box.json file
describes your project
-version
-dependencies
-dev dependencies
-module type
-package scripts
- a few other things

Package Scripts
can run arbitrary code from CommandBox
“scripts”: { “generatesAPIDocs” : “docbox generate \
    mapping=qb \
exclude=test|ModuleConfig |
strategy-outputDir=docs/apidocs \
strategy-projectTitle=“qb”
}

Package Scripts can hook into CommandBox interception points
“key” : “script”
example:
“postVersion” : “package set location=‘elpeteqb#b`packag version `’”,
“onRelease” : “run script …”

publish with “bump”
package gets auto updated on ForgeBox.io


Do Modules require ColdBox?
No, but when you use ColdBox w/ Modules you get super powers.
- modules
- interceptors
- layouts and views
- handlers
- settings (and automatic ways to override them)
- full MVC sub-application (ContentBox is a great example of this.)
- automatic WireBox mapping
    every module you map in your module gets auto-wired up
- automatic interceptors
- overridable settings

ModuleConfig.cfc properties needed
name - unique name of the module
entryPoint - default route for this module (i.e. api/v1)
autoMapModels = true (have WireBox auto map your models folder)
dependencies - if your mod depends on another, can put an array of dependencies here, they’ll load before your modules loads
parseParentSetting - allows overrides in your ColdBox Config.cfc file to override your module settings (default is “true”).

3 methods in ModuleConfig
configure() - where you do most of the work, where you put intercepters and routes, etc.
onLoad() - when you need the framework loaded first
onUnload() - undo what you did in onLoad()

an actual module that adds cors headers

“box install cors”
.poof, that’s it. removes lots of mental work in building your application.

Example Module: redirectBack

key parts to box.json
name
version
location
slug
shortDescription
type=modules (this tells it to install in the /modules folder of your app)
scripts
ignore

configure() method in ModuleConfig.cfc
{
settings = { key = “last_url”; }

interceptors = [{

}]
}

Leveraging WireBox
configure()
{
    builder.map( “DefaultGrammer” ).to (“modulemap.models.someModelFile” );
}

ForgeBox
CFML’s npm
forgebox.io

Testing
Modules make testing easier
smaller footprint to test
“how do i test what’s happening in this module” is easier than “how do i test something in the middle of a bunch of integration”

Unit Testing
component extends=“testbox.system.baseSpec”
{
    function run()
    {
        tests go here.
    }

}

For public projects, can run all your tests on all CF engines at once for free on Travis CI

travis.yaml file

to make a module —
create box.json
create moduleconfig.cfc
scaffold tests folder
-specs folder
runner.cfm
tests/Application.cfc
…of which you can probably find in a different project or a gist
copy over travis.yml file
create git repo and github repo
then get coding in your module…

that could be a lot of work, that’s one reason people don’t share things often

is there an easier way? there should be

For ColdBox apps, this is easy:
box coldbox create app

for modules it’s easy too:
box install cb-module-template
box module scaffold my-awesome-module “description of module”

creates a repo on git hub
turns on the build in Travis for you
sync and turns that on
pushes up an initial build for you
all you have to do is “bump”

what this module does for you:
create box.json
create moduleconfig.cfc
scaffolds the test for you
travis yml
git and github repo
creates a github token if it doesn’t exist
travis setup to accept builds
creates a Travis CI token if it doesn’t exist
so you can start coding right away

Bonus:
integration testing your module w/ ColdBox
as part of the template you get integration testing

/tests/resources folder
entire CB app
can use this as a “fake ColdBox app” to test integration w/ your module