Gavin Pickin

May 18, 2016

Spread the word

Share your thoughts

In the last blog post, we talked about extending ContentBox with modules. With ContentBox being built on top of ColdBox, and integration with ForgeBox using CommandBox, there are a lot of modules ( and module locations), and how those modules interact isn't obvious at first. To be honest, with ContentBox 3, we only just decided to move the core contentbox modules, to provide clearer separation, and easier source control management... things are changing, so I thought this would be a great time to explain about the different type of module locations, and why you should use one over another.

Where are modules located in a ContentBox 3 application

  1. ColdBox Modules - /modules - git ignored, controlled by CommandBox
  2. ColdBox App Modules - /modules_app - Your application global modules - included in your git repo
  3. ContentBox Always Load Modules - /modules_app/contentbox/modules
  4. ContentBox Admin Managed Modules - /modules_app/contentbox/modules_user

Note: These module locations for the ContentBox modules, assume we have moved them already. In your installation, the contentbox module might be still in the /modules/contentbox location... but this will be changing, soon.

Why are there 4 locations? Which location should I use?

There are 4 locations because each location has a different set of conventions, and different behaviors. Depending on what your module is, and what it will do, helps you determine where you should install / create it. The other reason the location matters, is because of source control. If your module interacts with ContentBox's life cycle, ie adding admin menu items when the module is loaded, the module is considered a ContentBox module, and should be installed in one of the last 2 locations.

ColdBox Modules /modules

Applications can have many dependencies, and keeping them out of your repo, and managing them with package managers, like Node, Bower, CommandBox, can keep your apps clean and light. Your gitignore file can get out of hand if you are individually adding and removing modules. To make life easier, we have 2 ColdBox App locations, 1 is /modules, which is controlled by CommandBox, and should be set to ignored. 
This means you can install hundreds of ColdBox modules, and do not have to worry about them filling up your repo.
Note:Since these files in the /modules folder are not in source control, editing these files is pointless. Your changes will never get committed, and therefore deploy to any other developers, or staging / production servers. If a module requires you to edit files inside the module to work, you should install the module to the ColdBox Apps Modules location ( below ).

ColdBox App Modules - /modules_app

This location is not ignored by git, it is a part of your source control repo. These modules can be created by you, or manually installed, or installed by CommandBox by using an alternative location ( read below for when you should do this ). There modules behave just like modules installed into the modules folder, the main difference is source control. Do you want the module to be embedded in your repo, or linked, using commandbox to resolve the module as a dependency.

Installing CommandBox modules to modules_app folder instead of the modules folder

When installing modules with CommandBox, they are usually installed to the /modules folder, but sometimes you should install modules to the modules_app folder. The main reason, if the module requires configuration changes to the files, those files need to be in source control. So the best location for that module, is inside of the modules_app folder. Not all modules need file changes to get the module working, so install those normally, but if a module requires those types of changes, a simple change to the install command will change the installation path.

# box install Business-Logic-Scanner modules_app

The last parameter is the installation directory. This will install the module to that directory.
Note: If you are creating a module, and you know someone will need to modify the module to get it to work, you can set the directory in your modules box.json so when commandbox installs your module, it knows it should be in that folder by default.

ContentBox Always Load Modules - /modules_app/contentbox/modules

This one is pretty self explanatory, they are ContentBox modules that always load. This location is stored for core ContentBox submodules, that are not controllable by the admin. My advice is, do not develop modules in here. Since these modules always load, trying to use a normal module in here, can have loading order issues. For example, if you design a module to add menu items to the admin, this module will have issues loading the adminMenuService@cb since the contentbox-admin module hasn't been loaded when these modules are being loaded. Its best to put those modules in the next location - ContentBox Admin Managed Modules

ContentBox Admin Managed Modules - /modules_app/contentbox/modules_user

This is where you should create modules that require the contentbox lifecycle to function correctly. A perfect example of the contentbox lifecycle, is after the core admin module has been initialized, it then loads these modules. The lifecycle fires events, that your modules can listen to, for example, onLoad and onUnload which are perfect for adding and removing menu items from the main menu item for your customer admin modules. If you module was not in this folder, your modules would not be able to intercept these events, making simple tasks, harder to do.

Another great aspect of having ContentBox managed modules, is that logged in users can activate, deactivate, or reload modules. This is the best way to extend contentbox, you can tie the module into all the internal events of Contentbox. In a future post, we'll be showing you show to make your own Admin Module where you can add menu items like the screenshot below... the last main menu item is Mapigator, which has submenu items, added dynamically by using modules in this folder.


Now you have learned a little more about ContentBox Modules, and how you can install and create modules in different locations, to leverage the pros and cons of that type of module. Using contentbox's Module Manager can help you install modules from Forgebox, Commandbox can help you install modules from Forgebox into wherever you need them, and of course, get your hands dirty and write some code too.
In future posts, we'll show you how to make a simple module for the front end, and for the admin, including adding admin menus, with your own font awesome icons. 
Download Contentbox 3 today - we would love your feedback

PS: Note, this blog post assumed the contentbox core modules have been moved from /modules/ to /modules_app/
This decision has been made, but we are still implementing this change, so the core contentbox modules still may be in /modules/ in your current installation.


Add Your Comment

Recent Entries

BoxLang 1.0.0 Beta 5 Launched

BoxLang 1.0.0 Beta 5 Launched

We are pleased to announce the release of BoxLang 1.0.0-Beta 5! This latest beta version includes improvements and essential bug fixes.

What is BoxLang?

BoxLang is a modern dynamic JVM language that can be deployed on multiple runtimes: operating system (Windows/Mac/*nix/Embedded), web server, lambda, iOS, android, web assembly, and more. BoxLang combines many features from different progr

Luis Majano
Luis Majano
July 12, 2024
Explore Into the Box 2024 on CFCast!

Explore Into the Box 2024 on CFCast!

Did you miss our unique Into the Box 2024 event? This year's conference featured notable product updates, incredible new tools, and numerous tips and tricks from industry experts. If you attended Into the Box, you can review the series on demand for free. Those who missed it can purchase the entire series for just $299 and gain full access to video recordings and live sessions. The series will be available to CFCast Paid subscribers until October 30th, 2024.

Maria Jose Herrera
Maria Jose Herrera
July 11, 2024
Rest API Workshop before Adobe CFSummit 2024!

Rest API Workshop before Adobe CFSummit 2024!

Building a REST API for the Modern Developer!

Get ready to elevate your skills at our exclusive 2-day workshop in Las Vegas, Nevada, just before the Adobe CFSummit 2024! This hands-on workshop is your gateway to mastering modern REST API development using ColdBox and other modern tools.

Maria Jose Herrera
Maria Jose Herrera
July 08, 2024