CfStatic and the MuraBootstrap Theme - Mura Docs v6

CfStatic and the MuraBootstrap Theme

The default theme that ships with Mura CMS, MuraBootstrap, utilizes some of the features of CfStatic.

There are some features of CfStatic you should be aware of:

  • Configuration of Dependencies
  • Configuration of Minify Modes

Configuration of Dependencies

In order for CfStatic to render files in the correct order and satisfy dependencies, it must know how the static files relate to each other. There are three ways to do this:

  1. JavaDoc style documentation in each file
  2. Plain text 'dependencies' file
  3. File and folder name ordering

All three methods may be used. Dependencies declared in JavaDoc style comments and in the dependencies file will be merged. When there is no dependency information, CfStatic will use the file and folder names for ordering of includes.

The JavaDoc style commenting system also allows you to specify other processing instructions for CfStatic, not available in the dependencies file.

JavaDoc Style Comments

JavaDoc comments look like this and must be present at the top of your files for CfStatic to process them:

/**
* Note the slash and double star to start the
* comments. The first paragraph of text
* within the comment block is a free-text
* description (i.e. this text). CfStatic will
* ignore this description but it can/should be
* used to document your code. Key value pair
* properties are then defined using the @
* symbol:
*
* @property property value
* @property another property value
* @anotherproperty yet another property value
*/

For example, the following code can be found in {SiteID}/includes/themes/merced/css/core/merced.css to indicate that CfStatic should load the typography.css file before merced.css:

/**
* @depends /core/typography.css
*/

Configuration of Minify Modes

CfStatic also offers a number of configuration options to control how it minifies your files. The options are:

  • None: no minification (e.g., only use CfStatic for the request inclusion and dependency)
  • File: files are minified but not concatenated in any way
  • Package (default): files are minified and concatenated in packages (all files in the same folder are considered a package)
  • All: files are minified and concatenated into a single JavaScript file and a single CSS file

Mura CMS uses the default setting of "Package" for the Minify mode. Hence, CSS and JavaScript files are separated into "packages" by creating a unique directory for each grouping (e.g., core, print, ie, etc.).

MuraBootstrap Theme Usage Examples

The file located at {SiteID}/includes/themes/MuraBootstrap/templates/inc/html_head.cfm contains the following configuration options for CfStatic:

<cf_CacheOMatic key="globalheadercss">
#$.static()
.include('/css/theme/')
.renderIncludes('css')#
</cf_CacheOMatic>

Referencing the code above, CfStatic will go through each "include" directory and create a minified and concatenated CSS file for each "package." For example, there are several .LESS files under the /css/theme/ directory, including a "responsive" sub-directory. CfStatic will first parse any .less files, resolve any configured dependencies and import statements, create a .css file (e.g., theme.less.css), minify the contents, then combine all files from the same directory (or package) into one file and place it inside of the /compiled directory. The compiled and concatenated file will then be stored as theme.min.{someTimeStamp}.css.

Finally, CfStatic outputs a link in the final HTML to the resulting file such as:

<link rel="stylesheet" href="/{SiteID}/includes/themes/MuraBootstrap/compiled/theme.min.20130129053619.css" media="all" charset="utf-8" />

Note: Do not modify files under the "compiled" directory since any changes are subject to being lost on the next compilation.

Because CfStatic will automatically detect when a file has changed and re-compile it, there is no need to edit anything other than your source files. 

Debug Mode

By default, you can force CfStatic to output includes for the source files rather than the minified files, by providing the URL parameter, debug=true.

Note: Debug mode is triggered on request only and is not part of your browsing session, so it will need to be appended to the URL every time you would like to use it.

For complete details on how to use CfStatic, please visit http://dominicwatson.github.com/cfstatic/full-guide.html#javadoc.