Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Modules are self contained bundles of code, that contain their own configuration, routes, handlers, views, widgets, interceptors, and can contain other modules. They are a vital part of ContentBox, and the ease in which you can use, and develop for ContentBox.
ContentBox itself is made up of 3 separate Modules ( and their submodules ), ContentBox, ContentBox-Admin and ContentBox-UI. One of the best security features of ContentBox is the fact that you can remove the Admin module from your production installs, removing the ability for the admin to get hacked, because it is not even present on your production server.
If you are planning to build a module, a great way to get started is Scaffolding a Module using CommandBox. CommandBox has a lot of commands and the one we will be using in this case is the ColdBox command. The ColdBox command inside of CommandBox allows you to do a lot of things, including coldbox create for all of these items:
view
app-wizard
orm-virtual-service
unit
integration-test
interceptor-test
orm-entity
orm-service
app
interceptor
orm-event-handler
model
layout
handler
bdd
module
orm-crud
model-test
controller
We are of course interested in creating a module. Lets look at that command
coldbox create module
The params for this command are the following:
There is also a flag for script: --script
Lets create a module with the command, and see what it produces. Note: Be in the root of your app so the command knows where to put the files. If you are in a subfolder, the command might get lost.
Looking at the arguments in more detail
name=customModule2
author="Gavin Pickin"
authorURL="http://www.gpickin.com"
description="Custom Module 2"
version="1.2.3"
cfmapping="customModule2Mapping"
modelNamespace="customModuleName"
directory="modules_app"
script=true
The command outputs this:
Here is a visual display of the directory structure
The command creates a Module Config file with all your information. It creates a default handler, called Home.cfc in the handlers folder. It creates a models folder, with just a placeholder file. It also creates a views folder, with the home folder to match the handler, and creates a default index.cfm view.
It is a great way to get started. You can use many of the other ColdBox commands to create additional handlers, views, and layouts. The next time you want to create a module, instead of remembering the conventions, and what files you need, scaffold it with CommandBox's ColdBox create command.
ColdBox modules all work with ContentBox, so what will you create?
Modules are one of the key components of ContentBox. One frequently asked question is: how do we theme our custom module output? Theming your custom module, so it uses the same theme/layout as the rest of your ContentBox site, is vital if you are going to be extending your site with your own modules. For consistency and flexibility, you do not want your module to be tightly coupled to the current theme, making it harder to change themes. We have a helper to assist you with that.
To use a theme, it requires a lot of different pieces behind the scenes. Usually in the process of displaying a ContentBox blog post, or page, the UI Module that handles the process, prepares the UI Request, setting up the settings, themes etc. This has been made available to you through the ContentBox CB Helper class. The first step is to get an injection or request the ContentBox helper object via its injection DSL: CBHelper@cb. You most likely will do this in your custom module handlers:
The helper sports the prepareUIRequest() method which you will use to tell ColdBox to leverage the ContentBox module theme instead of a traditional ColdBox layout. Here is the method signature:
This method accepts one argument called layout which by default is the pages layout from the chosen theme. If the ContentBox selected theme has more than one rendering layout, then you can even choose it here.
The string for the name of the layout allows you to pick and choose the layout inside the theme. Pages is a common one, but you could have specifically designed layouts for different parts of your modules, or prefer the blog layout for example. Here is a link to the documentation on PrepareUIRequest: http://apidocs.ortussolutions.com/contentbox/3.0.0-rc/contentbox/models/system/CBHelper.html#prepareUIRequest()
We tried hard to make this as simple as possible, so you can drop a module in and have it using the theme in seconds. Try it out and go build cool stuff!
To add Menu Items for your Admin Modules into the Admin Interface, you need to update the onLoad and onUnload functions of your ModuleConfig.cfc file.
In this example, you'll start by adding the Menu Item by updating onLoad:
Next, you'll update the onUnload function to remove the Menu Item when deactivating our Admin Module:
Now reload the app (?fwreinit=1). If you activate the mySecrets Admin Module, you should see mySecrets appear in the Modules sub menu items.
Now that your module menu button is working in the admin, you need to add some metadata to your module.
To view a Module, with routing and ColdBox modules entry points, you can simply hit a url/route on your site, and the module is ready to go.
For example: http://www.yoursite.com/businessLogicScanner
That is all you have to do. You don't need to build a special widget to display the module, the module can be accessed by the entry point in the module configuration, and its as easy as that.
Depending on the type of module, there are different methods and locations to install the module into.
/modules - ColdBox Modules - git ignored, controlled by CommandBox
/modules_app - ColdBox App Modules - Your application global modules - included in your git repo
/modules/contentbox/modules - ContentBox Always Load Modules
/modules/contentbox/modules_user - ContentBox Admin Managed Modules
There are four 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.
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 two ColdBox App locations, one 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 ).
This location is not ignored by git and 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 alternate location ( read below for when you should do this ). These 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.
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.
This one is pretty self explanatory, there 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
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 your module was not in this folder, your module would not be able to intercept these events, making simple tasks harder to do.
Another great aspect of having ContentBox manage modules, is that logged in users can activate, deactivate, or reload modules. This is the best way to extend ContentBox as you can tie the module into all the internal events of Contentbox. In a future page, we'll be showing you how 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.
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, you can get your hands dirty and write some code too. You can either build one, copy the source manually, install with CommandBox, or install via ContentBox itself.
Depending on the type of module, there are different methods and locations to install the module into.
/modules - ColdBox Modules - git ignored, controlled by CommandBox
/modules_app - ColdBox App Modules - Your application global modules - included in your git repo
/modules/contentbox/modules - ContentBox Always Load Modules
/modules/contentbox/modules_user - ContentBox Admin Managed Modules
You can manage ContentBox Modules through the ContentBox Administration. Click on the ForgeBox tab, you can search, locate and install modules directly.
If you are not using CommandBox yet, you should be. It is not only great for easily spinning up CFML Servers ( multiple server types ), but CommandBox's true strength is using it to manage your projects and packages, similar to 'npm' for node.
At Ortus Solutions, we use CommandBox to manage all of our CFML Projects. We track all of our dependencies and do not commit any CommandBox module to our Git repos. CommandBox will install dependencies from the CLI during our build process.
Let's walk through installing a ColdBox module, to scan our views for Business Logic, there is a module for that. If you look on Forgebox, you'll find Business Logic Scanner by Brad Wood. https://www.forgebox.io/view/Business-Logic-Scanner
To install, we cd into the site root, and type
box install Business-Logic-Scanner
Once CommandBox is done, you can log into ContentBox, and click 'Modules > Manage' and activate the module ( or reinit the app ).
Now, you have quickly installed a module, and activated it...time to use the module.
Absolutely, you can just copy a module into your modules folder, and sometimes, your modules will not be on Forgebox... a perfect example, Commercial Products, like DataBoss.
For a customer recently, who has a large custom database, we decided we wanted to use Databoss to help our customer view, add and edit data. DataBoss is a commercial product of Ortus Solutions and a complete Application in a Module. You can download a trial of Databoss, drop into your Modules folder, activate it, and now you have a full DataBoss application running on your /databoss route/url.
One common issue with using the theme for your module is the way Meta Tags are generated. Having your own module, its hard to set your Title, Keywords and Description.
You are able to do this inside your Module Handler Events
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.
As stated in our Module Conventions page, we showed you how there are four locations for modules in ContentBox. Depending on how your module will work, you should choose the appropriate location. In this example, we're going to build a custom ColdBox module, which is not managed by ContentBox Admin's Module Manager.
We'll be working in modules_app folder. These modules we create are for developer's eyes, and will not show up in the 'Manage Modules' administration menu. These are modules that you wouldn't want someone accidentally turning on / off, for example, a key part of the website.
When you install a module from the 'module manager' in the admin, ContentBox installs those modules into another location.
There are a few ways to build a module, including CommandBox scaffolding, 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.
In this example, we will start simple, and add more files as we build. 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.
Version
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.
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.
https://gist.github.com/gpickin/f7b0a53353230d326ef31d1d3d4996ef
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.
These routes are child routes of the entrypoint.
So /customModule/ is added to the apps main routing table, by setting the entry point above. These child 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 two 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.
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 ) /modules_app/customModule/views/
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.
ContentBox makes it easy to 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 frontend modules, and then admin modules.
When you are building admin modules, you need to build / install those modules into the modules_app/contentbox-custom/_modules folder. If you are building a ForgeBox module, that will be installed in modules/contentbox/modules_user. Read Module Conventions to know when to use what folder... depending if the module will be custom, vs a shared forgebox module, they will live in different locations.
One big benefit with ContentBox is how easy it is to use the base admin and to extend it to make it your own admin. Why build a normal website the hard way when ContentBox already has all the login, password reset, security roles and permissions build for you? You can simply use the admin and add more buttons for your admin modules.
This page walks through building a simple module in the ContentBox admin. We're going to make a custom module that will only live within this application and will not be shared with forgebox, so we want this to be included in our source code. We will build this module in this folder:
/modules_app/contentbox-custom/_modules/
The full path of our module, which will be called mySecrets, would be
/modules_app/contentbox-custom/_modules/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.
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, and model bindings ( mappings ). A shell of your configure method might look like this.
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.
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 handler 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
As you can see, we have our own routes setup for the module in the ModuleConfig.cfc. The default action is handler=home and action=index. We'll need to create this event, or update our module route to point to the new one. Let's keep it simple, and we'll make a home.index event.
ColdBox, and therefore ContentBox, calls the views folder 'views'. Since our action is home.index, we need a folder inside of 'views' called home, and an index.cfm file inside of that.
Inside the index.cfm, just put some simple html, like <h1>my Secrets</h1>
Lets reload our application with /?fwreinit=1 or Reload Application from the admin cog dropdown menu. Now lets try hitting our entrypoint /mysecrets and you'll see something like this.
Wait, why did that work? ColdBox uses conventions to find the view, even without the handler. For legacy conversion or simple views, you don't even need the handler. Wait, I wasn't logged into the admin, how did that not ask me to login?
If you look at the url, i was using /mysecrets which is actually the front end url... so that worked.
What is the admin entrypoint for this module?: /cbadmin/modules/mysecrets/ Now what happens when we hit that url
It bounces me to the login page, like it should. Ok, so when I login, then what happens?
In the admin, its throwing an error, telling me the handler doesn't exist. Strange that it worked in the front end right? The admin has a little more security, so it requires a handler. One of the pitfalls of not using handlers is that the ColdBox Lifecycle special actions like pre and post handlers etc cannot run, because it bypasses a lot of the lifecycle and just spits out the view. Keep that in mind when you are having issues with anything out of the ordinary and you don't have a handler, or have a handler without a handler event for the event you're executing.
We need to follow conventions ( unless you want to complicate things and override the conventions ) and make a folder called 'handlers' for our handler. We can just add the Home.cfc directly into the 'handlers' folder, and now your folder tree structure will look like this
We'll keep our handler very simple, just a shell, so we'll add this to our Home.cfc
Now we have added the handler, lets reinit the application and see what it looks like now.
Another note: If you hit http://127.0.0.1:61805/cbadmin/module/mysecrets/ you will get a strange handler error... because it thinks the module isn't a module, but its an action of a parent module... so make sure you use the full url, like below.
http://127.0.0.1:61805/cbadmin/module/mysecrets/home/index
Now, you will see the following
Now our module is working, in the admin, we need to add some menu buttons so users can access your module.
