In this session, you will learn how to extend and customize a ContentBox application. Get a deep understanding of leveraging custom modules and dynamic pages to create highly customized and engaging ContentBox apps. Sometimes there are things that we need to customize to fill our business needs, and ContentBox allows you to create custom modules to take care of those special needs.

1. Extend your ContentBox Apps with custom
modules and build dynamic pages
LED BY
Javier Quintero
SESSION

2. JAVIER QUINTERO
SPEAKER AT ITB2023
• Systems Engineer
• Colombian => Living in Houston, Texas
• Java and CFML Developer
• Currently working for Ortus Solutions
• DJ and tennis instructor when not coding

3. AGENDA
• Introduction
• ContentBox Look & Feel
• Themes
• Global HTML
• Widgets
• Modules
• Front end Development
• File structure
• JS and CSS Assets
• Theme Development
• Back end Development
• How to build a custom module
• DEMO

4. Introduction
ContentBox is a professional open source hybrid modular CMS (Content
Management System) that allows you to easily build websites, blogs,
wikis, complex web applications and even power mobile or cloud
applications.
Built with a secure and flexible modular core, designed to scale, and
combined with world-class support, ContentBox will get your projects out
the door in no time.Built with a secure and flexible modular core,
designed to scale, and combined with world-class support, ContentBox
will get your projects out the door in no time.

5. Active Theme
• Header
• Footer
• Contact
• Blog Options
On this section, you will be able to customize your current theme and your theme settings
ContentBox Look & Feel

6. Global HTML
• Global Layout
• Before Head End
• After Body Start
• Before Body End
• Before Any
Content
• After Any Content
• Before SideBar
• After SideBar
• After Footer
The Global HTML allows you to render HTML/CSS/JavaScript in many different locations within the life-
cycle of the rendered content in the UI.
ContentBox Look & Feel
• Blog Entries
• Before A Blog Entry
• After A Blog Entry
• Before Blog Index
• After Blog Index
• Before Blog Archives
• After Blog Archives
• Comments
• Before The
Comment Form
• After The
Comment Form
• Pages
• Before Any Page
• After Any Page

7. Themes
By default ContentBox provides a default theme, but there are more themes available for you to use
ContentBox Look & Feel
• Ortus themes
• Developed and maintained by the Ortus team
• Community themes
• Built by the community and shared on ForgeBox
• Custom themes
• Built by yourself to fulfill your own taste and needs
• Publish it on ForgeBox so others can use it :)

8. Widgets
Widgets are small pieces of software that you can add to your ContentBox website to perform a specific
function. There are several Widgets built into ContentBox that are used for various parts of your website,
and you can insert widgets into blog posts and pages to make your website even more dynamic.
ContentBox Look & Feel
• Ortus widgets
• Developed and maintained by the Ortus team
• Community widgets
• Built by the community and shared on ForgeBox
• Custom widgets
• Built by yourself to fulfill your own needs
• Publish it on ForgeBox so others can use it :)

9. ContentBox Modules
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.
• Ortus Modules
• Developed and maintained by the Ortus team
• Community Modules
• Built by the community and shared on ForgeBox.io
• Custom Modules
• Built by yourself to fulfill your own needs
• Publish it on ForgeBox so others can use it :)

10. Built on Modules
ContentBox itself is made up of 4 separate Modules ( and their submodules ), ContentBox, ContentBox-
Admin, ContentBox-UI and ContentBox-API. 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.
• File Structure
ContentBox Modules

11. Installing Modules
Modules on ContentBox can easily be installed via CommandBox. Just look for the module you want to
install on ForgeBox and install it.
box install cbSocialite
ContentBox Modules

12. Managing Modules
Modules can be activated/deactivated at any time which gives you the ability to restrict access to a specific
module if desired.
When working on custom modules, you will be able to scan the modules_app directory for the new
modules to show up and activate them whenever you want
ContentBox Modules

13. Developing For ContentBox
ContentBox's modular architecture, combined with the awesome power of the ColdBox MVC development
framework, allows for a familiar, yet unrestricted, platform from which to develop great web applications.
ContentBox is comprised of four modules
• contentbox - Includes the the underlying libraries for content organization and
presentation
• contentbox-admin - Provides the administrative interface for managing your
CMS
• contentbox-ui - Provides shared libraries for the user interface which are used
for presentation and which may be extended to your application requirements.
• contentbox-api - Provides a fully documented API to power any external app
easily and consume content anywhere

14. Front End Development
In developing your user interface, the majority of your time will be spent creating content in the admin and
modifying files from within your custom theme, located in the modules_app/contentbox-custom/_themes
directory.
With state-of-the art development tools like CommandBox to assist with scaffolding and dependency
management and Coldbox Elixir, it's easy to build out your theme in a fraction of the time it might
otherwise take.

15. File Structure
All the custom frontend work will be done within the modules_app/contentbox-custom folder
Front End Development
• _content ( Location for the custom media )
• _modules ( All the custom modules will go here )
• _themes ( Custom Themes, built by the developer and not
installed via ForgeBox )
• _widgets ( custom widgets - built by the developer and not
installed via ForgeBox )

16. Javascript
You have two options for working with Javascript in the admin.
jsAppendList
This expects the name of the js file ( without the .js extension ) which is located in the ContentBox includes/
js folder. This is a simple convention based approach, so you can easily just append a file, for example
arrayAppend( jsAppendList, 'dragula' ) to load /includes/js/dragula.js
jsFullAppendList
This expects the full path of the js file ( including the .js extension ), including the location. This is useful,
because you may be using grunt or gulp to compile files, store them in different locations, or actually link
out to a CDN for some of your scripts.
For example:
arrayAppend( jsFullAppendList, '/includes/js/dragula.js' );
arrayAppend( jsFullAppendList, 'https://code.jquery.com/jquery-3.1.1.min.js' );
Front End Development

17. Javascript
How the JS is output
Inside of /modules/contentbox-admin/layouts/inc/HTMLBodyEnd.cfm you will see the following code.
<cfloop list="#event.getValue( "jsAppendList", "", true )#" index="js">
<script src="#prc.cbroot#/includes/js/#js#.js"></script>
</cfloop>
<cfloop list="#event.getValue( "jsFullAppendList", "", true )#" index="js">
<script src="#js#"></script>
</cfloop>
Front End Development

18. CSS Assets
You have two options for working with CSS in the admin.
cssAppendList
This expects the name of the CSS file ( without the .css extension ) which is located in the ContentBox
includes/css folder. This is a simple convention based approach, so you can easily just append a file, for
example
arrayAppend( cssAppendList, 'dragula' ) to load /includes/css/dragula.css
cssFullAppendList
This expects the full path of the css file ( including the .css extension ), including the location. This is
useful, because you may be using grunt or gulp to compile files, store them in different locations, or
actually link out to a CDN for some of your scripts.
For example
arrayAppend( cssFullAppendList, '/includes/css/dragula.css' );
arrayAppend( cssFullAppendList, 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/
bootstrap.min.css' );
Front End Development

19. CSS Assets
How the CSS is output
Inside of /modules/contentbox-admin/layouts/inc/HTMLHead.cfm you will see the following code.
<cfloop list="#event.getValue( "cssAppendList", "", true )#" index="css">
<cfset addAsset( "#prc.cbroot#/includes/css/#css#.css" )>
</cfloop>
<cfloop list="#event.getValue( "cssFullAppendList", "", true )#" index="css">
<cfset addAsset( "#css#" )>
</cfloop>
Front End Development

20. Theme Development
A theme plays an important role when when customizing a site.These are the pieces that make part of a
theme, you can always follow the default theme as reference when building yours.
• Theme.cfc (The CFC that models and configures your theme implementation)
• layouts (The folder that contains layouts in your theme)
• blog.cfm (Mandatory layout used for all blog views by convention)
• pages.cfm (Mandatory layout used for all pages by convention)
• maintenance.cfm (Optional used when in maintenance mode, else defaults to pages)
• search.cfm (Optional used when doing searches, else defaults to pages)
• views (The folder that contains views for rendering)
• archives.cfm (MANDATORY: The view used to render out blog archives.)
• entry.cfm (MANDATORY: The view used to render out a single blog entry with comments, etc.)
• error.cfm (MANDATORY: The view used to display errors when they ocurr in your blog or pages)
• index.cfm (MANDATORY: The view used to render out the home page where all blog entries are
rendered)
• notfound.cfm (The view used to display messages to users when a blog entry requested was not found in
our system.)
• page.cfm (MANDATORY: The view used to render out individual pages.)
Front End Development

21. Theme Development
For more details on how to build a custom theme check out the official ContentBox docs
https://contentbox.ortusbooks.com/font-end-development/theme-development
Front End Development

22. Back End Development
ContentBox allows to to extend the core to take care of those special needs and custom business logic you
need to take care of.
You can override some the ContentBox settings in two ways:
1. via ColdBox.cfc
This will allow developers to override any runtime setting for any site.
All you need to do is create a contentbox structure in your configure() or any tier method, with the name of
the site (default is the default site) and then any setting name-value pair.

23. ContentBox Settings
2. Override ContentBox Settings via Java Environment Variables
You can also override any runtime ContentBox setting by passing them via Docker/Java Runtime variables.
Since these are string keys we can now use our fancy structures like the settings above, so you must
adhere to our recognition pattern:
contentbox_{site}_{setting}=value
Here is an example on adding a custom media root:
-Dcontentbox_default_cb_media_directoryRoot=./build/docker/contentbox/content
This will allow especially Docker environments to override settings as environments or even provide
secrets. More is coming, so stay tuned to our updates.
Back End Development

24. Module Locations and Conventions
Modules with ContentBox and ColdBox is fairly straightforward. You work with conventions, but you have
control.
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
Back End Development

25. Build a Module
If you are planning to build a module, a great way to get started is Scaffolding a Module using
CommandBox.
> coldbox create module
The params for this command are the following:
required name (Name of the module to create.)
author = "" (Whoever wrote this module)
authorURL = "" (The author's URL)
description = "" (The description for this module)
version = "1.0.0" (The semantic version number: major.minior.patch)
cfmapping (A CF app mapping to create that points to the root of this module)
modelNamespace (The namespace to use when mapping the models in this module)
dependencies = "" (The list of dependencies for this module)
directory = "modules_app" (The base directory to create your model in and creates the directory if it does
not exist.)
boolean views = "true" (Create the views folder on creatin or remove it. Defaults to true)
Back End Development

26. Module File Structure
The command creates a ModuleConfig 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.
Back End Development

27. 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.
Back End Development

28. Build an Admin Module
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.
When you are building admin modules, you need to build / install those modules into the modules_app/
contentbox-custom/_modules folder.
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.
Back End Development

29. Admin Menus
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.
Back End Development

30. Adding Meta to your Modules
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
Back End Development

31. DEMO

32. THANK YOU
Thanks to our sponsors

33. Thanks to our sponsors