Gavin Pickin

May 20, 2016

Spread the word

Share your thoughts

In a previous Post, we talked about extending ContentBox easily with modules, and showed you how you could just download a module, activate it and use it in minutes. In this post, we'll look at how to add Modules into your website, by building your own, and how to leverage Module Layouts.

Whether you have used ColdBox before or not, using Modules with ContentBox and ColdBox is fairly straightforward, in fact, I think its a great way to dip your toes into using both technologies. Working with Modules is like everything else in ColdBox, you work with conventions, but you have control. In this previous post, 'Modules Modules everywhere, Extending ContentBox', we show you how there are 4 locations for modules in ContentBox, and depending on how your module will work, you should choose the appropriate location. In this post, we're going to build a custom ColdBox module, which it not managed by ContentBox Admin's Module Manager.

By default, CommandBox will install pacakges into the 'Modules' folder. The Modules folder should be setup to be ignored from your repo, to ensure you do not add those to your git repo, use .gitignore to ignore 'modules/*'.  
We'll be working in 'modules_app' folder. This is where you will be coding modules for this application, in addition to the 'modules' installed in the 'modules' folder, from external forces, like forgebox. These modules we create are for developers eyes, and will not show up in the 'Manage Modules' administration menu. These are modules that you wouldn't want someone accidentally turning off, for example, we recently built an insurance policy payment tool... a key part of the website, which users should not be able to turn on and off, like other smaller simpler modules.
When you install a module from the 'module manager' in the admin, ContentBox installs those modules into another location. We'll talk more about those modules another time.

Lets start building a module

There are a few ways to build a module, including CommandBox scaffholding, where you are asked a few questions, and then it generates a module, with all of the folders you need and some you might want.
I think the best way to understand things, is to start simple, and add as you go, so lets take that approach. We'll treat it like TDD, do something, test it, fix it, keep moving. We can compare to the scaffholding in a future post.

First, we need to know a few things about the module to get started... your folder name, and then some details to add into your Module Config file.

Folder Name for the Module

This is the folder you put the module in. It does not have to match anything else with the module, so you can use something meaningful... you can set the entry point / link / route manually in the Module Config file.

Entry point - What link / route would you hit to pull up this module?

In my example, I want to be able to go to /customModule and be able to pull up this module. I have created modules for /profile and /pay and /help in the past.

Namespace for the Module

This is a namespace for any models initialized in this module. Say you have a UserService.cfc in your module, you would ask for this service from wirebox with userService@customModule if that is the namespace you would like to use. I usually make the entry point and namespace and the folder all match, unless the entry point should be shorter or different, for whatever reasons.

CFMapping for the Module

This is an automated mapping for the module. I usually have this match the folder, and namespace.


Start at 1.0.0, you can bump it up as you go, but this is usually not vital unless you're planning to publish on Forgebox or something. We can look at that in a future post.

Our new Module - CustomModule

For my example, lets keep it super simple, and call the app customModule, and we'll keep everything the same, folder, entrypoint, namespace, mapping.

Create Folder
Lets create a folder /modules_app/customModule/

Create ModuleConfig.cfc
Next, lets create a file called ModuleConfig.cfc - this is the config file that ColdBox loads to setup the module, and get it ready to use. It can setup a lot of things, including the mapping, entry point, and a lot more. We'll start simple, here is a gist for my bare bones moduleConfig file.

Once you have your folder, and your moduleConfig file, you can reinit your app, and then try hitting your entrypoint.

Error - so lets see what we need next to be able to get this Module Working.

If you read the error message, you'll see that the event customModule:home.index is not a valid registered event.

What does this mean? This means the entry point worked, and found your module, but its looking for an event to run. If you look in your routes in your config, you'll see some basic routes setup for you.

Module Routing

// SES Routes
routes = [
// Module Entry Point
    { pattern= "/", handler="home" , action="index" },
    // Convention Route
    { pattern= "/:handler/:action?" }

These routes are children routes of the entrypoint.

So /customModule/ is added to the apps main routing table, by setting the entry point above. These children routes build on top of that.
So if someone hits the child route / then its the same as /customModule/ - and if that pattern is matched, that route says we want to use the 'Home" handler, and the "index" action. That is why you see the error looking for that, its because this is the default event for this module.
You will also see there is another route pattern below, /:handler/:action - this includes placeholders. So this will match anything with 2 or more values, and then it will use the first value as the handler name, and the second piece as the action.

  • /customModule/profile/view/ would be the customModule with the profile handler and the view action.
  • /customModule/product/add/ would be the customModule with the product handler and the add action.

We could change our default to be something else, but for now, lets keep it simple. Home Handler and Index action.

So how can we create this event?

This is where ColdBox conventions really shine. You might think you have to create a Handler folder, and create the handler named Home.cfc and then put a function inside of it called index... which is correct but you don't HAVE to. ColdBox's conventions requires less than that to create an event. In fact, the lowest point of entry for creating an event, is just to create a view.

Lets make a folder called views ( the convention for where your views live )

To create the view for home.index, we need to create an index.cfm. Conventions tell us, to make a folder inside views to match the handler, and then place the action's view in that folder. 
So lets create /modules_app/customModule/views/home/index.cfm
We'll put in an <h1>My Custom Module</h1> and see what happens when we hit the entry point now.

Amazing, just 2 files, and we have a working module. You could paste in your legacy spaghetti code right in here, and it would work. Of course, we probably want to dress it up a little more, and add some more functionality, so lets look at the layout first.
If we view the source, you'll see there is more than just the h1 tag we added.

Where is all of that coming from? Layouts

Check out our next blog post where we'll learn more about layouts.
Hope this helped demystify ColdBox modules and some of the conventions.

Add Your Comment

Recent Entries

Unveiling the Future of CFML Development - 3rd Round of Sessions

Unveiling the Future of CFML Development - 3rd Round of Sessions

Welcome back to our journey into the future of CFML development! As excitement continues to build for Into the Box 2024, we're thrilled to bring you the latest updates on what promises to be a transformative event. Continuing our blog post series, let's delve deeper into the third wave of session releases and discover the key surprises awaiting attendees. Learn More

Maria Jose Herrera
Maria Jose Herrera
March 01, 2024
Elevate Your ColdBox Experience and Skills

Elevate Your ColdBox Experience and Skills

We're thrilled to announce a significant overhaul of our ColdBox training experience to ensure it's nothing short of extraordinary! We've listened closely to your feedback and made significant improvements geared towards transforming you into a ColdBox superhero. Learn What's New!

Maria Jose Herrera
Maria Jose Herrera
February 20, 2024
Ortus Redis Extension v3.3.0 Released!

Ortus Redis Extension v3.3.0 Released!

We are very excited to bring you another release for our Redis Lucee Extension. The most significant feature in this release is the addition of the `` and `redisLock{}` tag, which allows you perform a lock across all instances in a cluster.

Ortus Redis Extension v3.3.0 gives you greater control over concurrent modifications in a distributed environment, utilizing your distributed cache to prevent overlaps!

Jon Clausen
Jon Clausen
February 16, 2024