Blog

Gavin Pickin

July 27, 2016

Spread the word


Share your thoughts

In previous posts, we looked at how to extend ContentBox 3 with ColdBox Modules, installing from Forgebox with CommandBox, or creating your own. In this post, we're going to look at how you can create your own Admin Modules, add Menu Items into the Admin Interface, use ContentBox admin Users and Permissions instead of building your own security by extending ContentBox.

At it's core, ContentBox is an Application running on top of ColdBox as a framework, but with all of the great features ContentBox has, ORM, Pages, Blog Posts, Categories, Comments, Subscriptions, Admin User Interface, Permissions, Modules, and much more, you can treat ContentBox like an Application Framework, and just extend it, with Modules. With almost every real Application, you will need to add front end modules, and then admin modules.

We've looked at how to build and install front end modules, in the website root's module folder(s). When you are building admin modules, you need to build / install those modules into the 'modules/contentbox/modules_user' folder or 'modules/contentbox/modules' folder. Read appendix a below to know when to use what folder... depending if the module will be custom, vs a shared forgebox module, you should put them in different locations.

One of the reasons I love ContentBox, is how easy it is to use the base admin, and extend it to make it my own admin. Why build a normal website anymore, when ContentBox already has all the login, password reset, security roles and permissions, why not just use the admin, and add more buttons for my admin modules. So lets look at building a simple module in the ContentBox admin. We're going to make a custom module, that will only live with this application, and will not be shared with forgebox, so we want this to be included in our source code. So we will build this module in this folder:

/modules/contentbox/modules_user/

The full path of our module, which will be called mySecrets would be

/modules/contentbox/modules_user/mySecrets

Now, if we go to the Module Manager in the backend, and rescan for modules, you will see it doesn't show up yet.

First, we need to create a module config. This is similar to a normal ColdBox module, with a few extra splashes of flavor for ContentBox. 
Since it is a CFC, we can use the pseudo contructor to set the module properties. For mySecrets, it looks something like this.

// Module Properties
this.title                       = "MySecrets";
this.author                = "Ortus Solutions, Corp";
this.webURL                = "http://www.ortussolutions.com";
this.description           = "This is a secrets module";
this.version               = "1.0";

// If true, looks for views in the parent first, if not found, then in the module. Else vice-versa
this.viewParentLookup      = true;

// If true, looks for layouts in the parent first, if not found, then in module. Else vice-versa
this.layoutParentLookup = true;

// Module Entry Point
this.entryPoint                  = "mysecrets";

The only required function for the ModuleConfig.cfc is the configure() function. This is where you can set ( or inherit ) settings, parent settings, layout settings, datasources, webservices, routes, interceptorSettings, custom Interceptors and Interception Points, model bindings ( mappings ). A shell of your configure method might look like this.

       function configure(){
             // parent settings
             parentSettings = {
             };
             // module settings - stored in modules.name.settings
             settings = {
             };
             // Layout Settings
             layoutSettings = {
                    defaultLayout = ""
             };
             // datasources
             datasources = {
             };
             // web services
             webservices = {
             };
             // SES Routes
             routes = [
                    // Module Entry Point
                    {pattern="/", handler="home",action="index"},
                    // Convention Route
                    {pattern="/:handler/:action?"}
             ];
             // Custom Declared Points
             interceptorSettings = {
                    customInterceptionPoints = ""
             };
             // Custom Declared Interceptors
             interceptors = [
             ];
             // Binder Mappings
             // binder.map( "Alias" ).to( "#moduleMapping#.model.MyService" );
       }

This is the minimum you need for the module to show up in the Manage Modules screen. If we rescan now, you'll see it detects our Module.

When you click the Thumb Up icon to activate, it activates the module.

Since these modules are inside of ContentBox, Contentbox manages loading and unloading the module, as well as activating and deactivating the modules, so you need those functions to listen for those events. ModuleConfig.cfc is one big interceptor, so you can catch all sorts of interception points, but these are the four needed for a ContentBox Module to function to its fullest.

/**
* Fired when the module is registered and activated.
*/
function onLoad(){
}

/**
* Fired when the module is activated by ContentBox
*/
function onActivate(){
}

/**
* Fired when the module is unregistered and unloaded
*/
function onUnload(){
}

/**
* Fired when the module is deactivated by ContentBox
*/
function onDeactivate(){
}

This is a bare bones template for a module controlled by ContentBox, but right now it doesn't really do anything... in fact if you tried to hit the module, the default route for / would look for home hander with index action/view but we haven't created those yet. None of the functions above do anything, so all the activation and deactivation does, is make the module available or not. If you try and access /mysecrets ( the entry point ) with the module deactivated you see this

When the module is activated, and you hit the entry point, you will get the error that the event is not a valid registered event

Here is the gist of step 1.
ModuleConfig.CFC for Step 1 - https://gist.github.com/gpickin/545242a3da6c2805efb4e6cac82ce1ad

Next we'll look at making the event, so we wont get that error, and after that, we'll add admin menus so you can access it from inside the administrator.

Appendix - When to use modules folder vs modules_user folder.
When working with source control, the normal approach is to only add files to the repo that are unique to the repo. You exclude includes, or dependencies, to reduce bloat, and streamline deployments. Since CommandBox installs by convention to the modules folder, most dependencies are installed there, and you could exclude those from git with one line added to your .gitignore 'modules/*'. This is simple, and effective, until you start creating your own modules. Maybe you don't want to add it to forgebox, or manage it as a separate repo, you just want it in your project... but git is ignoring your modules folder. That is where ContentBox's convention for User modules comes in. Instead of using the modules folder, you create modules in the 'modules_user' folder inside of 'modules/contentbox/' folder. This means that git does not ignore it, and by default, the 'modules_user' folder is scanned for modules along with the 'modules' folder. 
 

Add Your Comment

Recent Entries

Into the Box 2024 Last Early Bird Days!

Into the Box 2024 Last Early Bird Days!

Time is ticking, with less than 60 days remaining until the excitement of Into the Box 2024 unfolds! Don't let this golden opportunity slip away; our exclusive Early Bird Pricing is here for a limited time only, available until March 31st. Why wait? Secure your seat now and take advantage of this steal!

Maria Jose Herrera
Maria Jose Herrera
March 20, 2024
Ortus February Newsletter 2024

Ortus February Newsletter 2024

Welcome to Ortus Solutions’ monthly roundup, where we're thrilled to showcase cutting-edge advancements, product updates, and exciting events! Join us as we delve into the latest innovations shaping the future of technology.

Maria Jose Herrera
Maria Jose Herrera
March 06, 2024
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