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)

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" );
}

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" );
}

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)

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 an annotated screenshot showing most of the visible elements generated in the Theme Settings Admin form from the Theme Settings configuration structure.

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)

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