ContentBox itself is a ColdBox application, with 3 special modules that do all of the hard work. Below you will see the shell of the ColdBox app, with the key folders expanded and bolded.

Although ContentBox has a large number of folders and files, most customization activities will be done in a few key locations. This should make navigating the ContentBox source files easier.

We recommend using modules for extending ContentBox. Modules are easy to install, and can be managed through the ContentBox admin, activating and deactivating as needed. Modules can contain widgets, interceptors, admin or front end menu items, including handlers and views.

Themes are self contained folders, within ContentBox's themes folder. Themes themselves are module like, with a few added features, which means you can include modules in your themes for truly deep and powerful themes.

Traditional ColdBox Modules can be installed outside of ContentBox's control and life-cycle with ColdBox's normal conventions.

Initial ContentBox Website Install

• coldbox ( The ColdBox core, including system and ColdBox dependencies )

• config ( The ColdBox app config folder )

• handlers ( The ColdBox app handlers folder )

• layouts ( The ColdBox app layouts folder )

• models ( The ColdBox app layouts folder )

• modules ( The ColdBox app layouts folder )

  • contentbox

    • content ( default location for the media manager - customizable through Admin settings )

    • email_templates ( Email templates for adding authors, comments, pages, blog posts and many more )

    • i18n ( i18N properties files for DE, US, SV, IT, BR currently )

    • models ( Core ContentBox Models and Services )

    • modules ( Modules here are always loaded no matter what. These are core sub-modules of the ContentBox core module )

    • modules_user ( ContentBox life-cycle controlled modules. Manually installed or downloaded from Forgebox. These Modules can be activated and deactivated through the admin )

      • Hello ( Hello World Sample Module )

    • themes ( ContentBox Themes, manually installed or downloaded from Forgebox )

      • default ( Default ContentBox Theme )

    • tmp

    • updates ( Location for downloaded and manually installed patches )

    • widgets ( Default ContentBox Widgets - Override-able )

    • Application.cfc

    • ModuleConfig.cfc

  • contentbox-admin ( ContentBox Admin - removable for security reasons )

  • contentbox-ui ( Contentbox UI Module )

• modules_app ( Home for all of your custom ColdBox modules, outside of ContentBox's lifecycle )

• views ( The ColdBox app layouts folder )

• .htaccess

• Application.cfc ( The main ColdBox Application.cfc )

• box.json

• favicon.ico

• index.cfm

• license.txt

• readme.md

• robots.txt

• server.json

Working with Assets in the Admin

To make Asset management easier in the Admin, we have provided a few arrays, that you can append your assets to. We have JS and CSS arrays, as well as convention based, and full path arrays.

Javascript Assets

We 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' );

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>

CSS Assets

We 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' );

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>

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 [ContentBox Module Home]/themes directory.

With state-of-the art development tools like CommandBox to assist with scaffolding and dependency management and Coldbox Elixr, it's easy to build out your theme in a fraction of the time it might otherwise take.

Theme Directory Conventions

A typical theme directory structure might be:

MyAwesomeTheme

- includes

• css

• fonts

• js

- layouts

- templates

- views

- widgets

For more information on the theme directory structure and configuration options see ContentBox Theme Development.

Modularity

In addition, many front-end focused modules and libraries are available on Forgebox and can be installed from the CommandBox CLI and used immediately in your templates, widgets and views. For example, to install a Twitter feed widget for ContentBox, simply run box install ID=cbwidget-tweetfeed directory=widgets from your theme directory and it will automatically be available for use in the admin. You may browse the ever-growing list of Forgebox libraries and modules on the Forgebox site or run forgebox help from within CommandBox to begin exploring the available options.

By default the includes directory of your theme is used to store your static assets.

Because these assets are called from your customized theme, however, you may use any directory conventions you prefer. If you plan to use customized paths or CDN links in your template, it's best to create a setting in your Theme.cfc which will then be configured through the admin.

AddAsset() Method for CSS and JS

In the Front End of the Website, the Theme takes over the rendering. To ensure all Assets are added correctly from various modules, for every theme, we recommend using the htmlHelper's addAsset() method.

Since the SuperType ( which all ColdBox items inherit from ) implements addAsset() you can call it directly from almost any file in your application.

addAsset( "#prc.cbroot#/includes/css/#css#.css" );

You might have noticed, that even in the Admin Asset Management methods explained here, the actual implementation of the cssFullAppendList and cssAppendList use the addAsset to add the CSS to the head of the HTML page.

This applies to both CSS and JS. The main downside to this approach is that all assets added with addAsset are added to the head. The order of the assets is not strictly ( or easily ) controlled either.

Better Asset Management coming soon

We recommend using a similar approach to the admin, using an array, and outputting in the theme. We will be standardizing an approach soon, so all themes can easy implement these features, with a single line cbhelper method.

Global Variables and Functions

During the ContentBox request, common variables and super-type methods are made available to all templates and views used in that request. When developing themes and modules for ContentBox, the following methods and variables are available for use in customization:

#cb#

The cb object contains a variety of common methods for retrieving ContentBox content and settings. Below are some common methods used to retrieve and create HTML content:

Content and Settings Retrieval Methods

Settings Retreival

• cb.siteName(): retrieves the configured name of Contentbox installation

• cb.siteTagline(): retrieves the configured tagline for the ContentBox installation

• cb.siteDescription(): retrieves the configured description for the Contentbox installation

• cb.siteKeywords(): retrieves the configured global keywords

• cb.siteEmail(): retrieves the default site email

• cb.siteOutgoingEmail(): retreives the configured email used in outbound deliveries

Theme Views

• cb.quickView( viewTemplate ): Renders a view partial located in the [theme home]/views directory. A .cfm file extension is not required.

• cb.mainView( args ): Renders the main view for the handler action. A struct containing the args necessary for view rendering should be passed in. By default, this struct is available in your layout and is also named args.

Entry Retrieval

• cb.getCurrentEntries():

• cb.getCurrentEntriesCount():

• cb.getCurrentCategories():

• cb.getCurrentPage():

• cb.getCurrentComments(): Returns the published comments for the current entry

• cb.getCurrentCommentsCount(): Returns the count of published comments for the current entry

• cb.getCurrentRelatedContent(): Returns an array of content related to the active post or entry

• cb.getCurrentCustomFields(): Returns a structure of custom fields for the active post or entry

• cb.getCustomField( string fieldName, any defaultValue ): Returns the value of a custom field for the active post or entry

Content Store Retrieval

• • cb.contentStore( string slug ): retrieves the HTML output of a Content Store item by its slug

• cb.contentStoreObject( string slug ): retrieves the associated Content Store object

• cb.widget( string widgetName, struct args ): executes a named widget's renderit method and returns the HTML. A structure of arguments may be passed.

• cb.getWidget( string widgetName ): retreives the associated [widget][2] object

• cb.themeSetting( string settingName, any defaultValue ): retrieves a theme setting by name. A default value may be specified

• cb.isCommentsEnabled(): returns a true|false value of whether site comments are enabled and if the current entry accepts comments

• cb.quickSearchForm(): returns the HTML of a standard ContentBox Search Form according to the SearchForm widget

• cb.getSearchResults(): returns an array of results for an active search

Link Building Methods

• cb.linkAdmin(): creates a link to the ContentBox admin

• cb.linkAdminLogin(): creates a link to the ContentBox administration login form

• cb.linkAdminLogout(): creates a link to logout of ContentBox administration

• cb.linkBlog(): creates a link to the site's blog

• cb.linksSelf(): creates a link to the current page

• cb.linkPageRSS( any categoryFilter): creates a link to the RSS feed applicable to the active request

• cb.linkSiteRSS( any categoryFilter ): creates a link to the site's RSS feed

• cb.linkCategory( string categorySlug ): creates a link to a specific category page

• cb.quickCategoryLinks( string categorySlug ): creates an HTML unordered list of category links

Path and URL Utility Methods

• cb.themeRoot(): returns the location of your currently defined theme in the application, great for assets, cfincludes, etc

• cb.siteRoot(): returns the site root location using your configured module's entry point

• cb.siteBaseURL(): returns the site's SES base URL

• cb.adminRoot(): returns the root location of the admin using your configured module's entry point

• widgetRoot(): returns the location of your widgets, great for assets and includes

Interception Points

A number of built-in interception points are avaialble within the ContentBox request, which may be run using the cb.event() method. For examples of how these are used, see the default theme layout files. Examples include:

• cb.event( "cbui_beforeHeadEnd" )

• cb.event( "cbui_afterBodyStart" )

• cb.event( "cbui_afterContent" )

• cb.event( "cbui_beforeBodyEnd" )

Development and Debugging Helper Methods:

• cb.themeName(): returns the currently active theme name

• cb.layoutName(): returns the currently active layout name

• cb.isPrintFormat(): returns true if you are in printing or exporting format

UI Utility Functions

Easily Render Captcha Images - ContentBox supports native captcha support and now your themes can render out a nice captcha image by using the new ContentBox helper method:

• cb.renderCaptcha() method.