UDF ( User Defined Functions ) are a great way to add more power to your theme, and your theme settings.

Below are some common UDFs you might want to use in your themes, or templates on how you could create some of your own.

Example UDFs

LoadHelpFile()

This is a useful method for standardizing loads HTML for the fieldHelp Modal. The fieldHelp setting using this function would look like this

loadHelpFile( 'cbBootswatchTheme.html' );

Since the helpFilePath is not passed in this example, it defaults to the Theme's includes/help/ folder.

Note: One concern when using this is relative pathing of assets, since the modal is generated in one folder, and the includes are in another folder.

/**
* loadHelpFile - helper function for loading html help into a variable for modal
* @helpFileName - the name of the file to read and return
* @helpFilePath - the relative directory for the help files. Defaulting to ./includes/help/ inside the theme.
* @return the contents of the file or empty string if the file does not exist
*/
function loadHelpFile( required string helpFileName, string helpFilePath='./includes/help/' ){
    try {
        return fileRead( arguments.helpFilePath & arguments.helpFileName );
    } catch( any e ){
        return '';
    }
}

selectMediaManagerFolder()

This function gives you an array of Media Manager folders, so you could use in a optionsUDF setting, to allow the Theme Settings form to display a dropdown box with a list of folders. This would be great for a slide show, where the users select the folder, and all of the contents of the folder could be shown in the slideshow.

function selectMediaManagerFolder(){
    var event         = getRequestContext();
    var cbSettings     = event.getValue(name="cbSettings",private=true);
    var defaultDir = expandPath( cbSettings.cb_media_directoryRoot );
    var allDirectories = directoryList( path=defaultDir, recurse=true, listInfo="query" );
    var result = [];
    for( var directory in allDirectories ){
        if ( directory.type is 'dir' ){
            var theString = replaceNoCase( directory.directory, defaultDir, "", "all" ) & '/' & directory.name;
            theString = replaceNoCase( theString, "\", "/", "all");
            theString = replaceNoCase( theString, "//", "/", "all");
            result = result.append( theString );
        }
    }
    return result;
}

getBootstrapStyles()

Bootstrap has a set of pre-defined styles, used in alerts, buttons, and many other styles you can use in your website. Having a UDF like this, allows you to create a setting that the User can select the button style type.

array function getBootstrapStyles(){
    return [ 
        "default",
        "primary",
        "success",
        "info",
        "warning",
        "danger"
    ];
}

getBootstrapSwatches()

We use BootSwatch in several Themes, because it gives the user of the theme a lot of complete styles, in one theme. This UDF shows you how you can return a list as an array, so a user could select the BootSwatch they would like to use.

/**
* Build the swatches options
*/
array function getBootSwatches(){
    return listToArray( "cerulean,cosmo,cyborg,darkly,flatly,green,journal,lumen,paper,readable,sandstone,simplex,slate,spacelab,superhero,united,yeti" );
}

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.

Template Folder File Structure

• templates (The folder that contains optional templates for collection rendering that are used using the quick rendering methods in the CB Helper. See below for additional information)

  • category.cfm (The template used to display an iteration of entry categories using coldbox collection rendering)

  • comment.cfm (The template used to display an iteration of entry or page comments using coldbox collection rendering)

  • entry.cfm (The template used to display an iteration of entries in the home page using coldbox collection rendering)

Functionality

The individual files included in the templates directory are a single .cfm files used by ContentBox to iterate over a collection (usually entries or categories or comments) and render out all of them in uniformity.

Please refer to ColdBox Collection Rendering for more information.

Each template receives the following variables:

• _counter (A variable created for you that tells you in which record we are currently looping on)

• _items (A variable created for you that tells you how many records exist in the collection)

• {templateName} The name of the object you will use to display: entry, comment, category

Layout Local CallBack Functions:

• onActivation()

• onDelete()

• onDeactivation()

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

Layouts Folder File Structure

• 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)

ContentBox for some time has had a ContentBox site title, keywords and descriptions. Most themes also overrode those values with Blog Post and Page Titles, and if you use the SEO tab in the editor, you can override the Keywords and descriptions too.

New SEO CBHelper Functions for your Theme

In ContentBox 3.1, we added some additional logic into the default Theme ( as a reference ) to allow even more flexibility with Title, Keywords, Meta etc. In previous versions, logic checked to see if the content was a blog, or a page, and how to determine if overrides were used or not. Now the CBHelper contains all of that logic, and you can just request the Title, Description or Keywords from CBHelper.

<title>#cb.getContentTitle()#</title>
<meta name="description"     content="#cb.getContentDescription()#" />
<meta name="keywords"          content="#cb.getContentKeywords()#" />

This is in addition to already existing functions like:

<base href="#cb.siteBaseURL()#" />

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. As of ContentBox 3.1, since we have added the SEO and Meta functions to CBHelper, you can actually set and retrieve that data easily. To add Meta to your modules, you can now add this to your Module Handler Events.

function index(event,rc,prc){
    cbhelper.setMetaTitle( 'My cool module' );
    cbhelper.setMetaKeywords( 'ContentBox, Ortus, Themes, Modules' );
    cbhelper.setMetaDescription( 'My new module now has Meta Data to be used my the Theme.' );
    cbhelper.prepareUIRequest( "pages" );
    event.setView( "home/index" );
}

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.

Views Folder File Structure

• 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.)

  • maintenance.cfm (OPTIONAL: Used when in maintenance mode)

A theme is composed of the following pieces

ThemeDirectory

• 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.)

  • maintenance.cfm (OPTIONAL: Used when in maintenance mode)

• templates (The folder that contains optional templates for collection rendering that are used using the quick rendering methods in the CB Helper. See below for additional information)

  • category.cfm (The template used to display an iteration of entry categories using coldbox collection rendering)

  • comment.cfm (The template used to display an iteration of entry or page comments using coldbox collection rendering)

  • entry.cfm (The template used to display an iteration of entries in the home page using coldbox collection rendering)

• widgets (A folder that can contain layout specific widgets which override core ContentBox widgets)

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 Retreival

• • 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.

[2]: /content/using/managers/widgets.html

You can declare settings for your Themes that ContentBox will manage for you. The form itself is built from the Theme.cfc file itself.

The value is an array of structures with the following keys:

• name : The name of the setting (required), the setting is saved as cb_layoutname_settingName

• defaultValue : The default value of the setting (required)

• required : Whether the setting is required or not. Defaults to false

• type : The type of the HTMl control (text=default, textarea, boolean, select, color)

• label : The HTML label of the control (defaults to name)

• title : The HTML title of the control (defaults to empty string)

• options : The select box options. Can be a list or array of values or an array of name-value pair structures

• optionsUDF : The select box options. This points to a UDF that returns a list or array of values or an array of name-value pair structures. Example: getColors not getColors()

• group : lets you group inputs under a Group name - settings should be in order for groupings to work as expected

• groupIntro : Lets you add a description for a group of fields

• fieldDescription : Lets you add a description for an individual field

• fieldHelp : Lets you add a chunk of HTML for a Modal, openable by the User by clicking on question mark next to the field label. Recommended use is to readFiles from the ./includes/help directory, with a helper function, for example: loadHelpFile( 'cbBootswatchTheme.html' );

Example

this.settings = [
    { name="Title", defaultValue="My Awesome Title", required="true", type="text", label="Title:" },
    { name="Colors", defaultValue="blue", required="false", type="select", label="Color:", options="red,blue,orange,gray" }
];

Theme Settings Admin Form

Below is a annotated screenshot showing most of the visible elements generated in the Theme Settings Admin form from the Theme Settings configuration structure.