Theming with Twitter Bootstrap version 3

Twitter Bootstrap 3 - MObile FirstTwitter Bootstrap version 3 (BS3) is becoming the user interface framework library of choice for Exponent CMS.  Though initially shipped with Exponent v2.3.0, that BS3 implementation was still lacking some refinement, and wasn't fully implemented across the entire user interface.  This has been somewhat remedied by the first three patches to v2.3.0, and will be even more-so in the upcoming patch #4 release.  In this article I'll attempt to share some of the basics of how to create a Twitter Bootstrap 3 custom theme.

First off, this is NOT an introduction to using Twitter Bootstrap 3 or it's grids, nor understanding what 'mobile first' or 'responsive' means.  There are several tutorials on the web including this one.  However, we won't avoid those topics as we focus on Exponent CMS theming specifics as they apply to using BS3.

We ship a BS3 sample theme with Exponent v2.3.0 appropriately named 'bootstrap3theme'.  Since the release of v2.3.0 we have tweaked this theme (as we said we would), therefore the one being included in v2.3.0 patch #4 has some changes from the one included in the initial release.  This article assumes you have access to those sample theme files and can use it as a starting point.  Eventually I may also publish a second part to this article to walk you through converting an existing open source BS3 theme template for use as an Exponent template (with the purpose of it being added to the help/doc site).

When you examine the /themes/bootstrap3theme/index.php default theme template, you'll note several Exponent specific things in the 'head' section with the expTheme::head() parameters: 

  • the 'framework' parameter is set to 'bootstrap3'.  This automatically ensures we are loading the BS3 stylesheets, jQuery script, and 'prefer' the '.bootstrap3' view template variation (which includes any form control or template engine plugin variations) if available.
    • BS3 scripts are never automatically loaded, but must be requested by the expJavascript::pushToFoot() call or the theme template {script} smarty function using the 'bootstrap=' parameter.  This parameter works just like the 'yui3mods' and 'jquery' parameters.
  • there are no 'reset' scripts being loaded.  The new standard css reset script, 'normalize.css' is automatically loaded by BS3.
  • we can optionally load the BS3 'theme' stylesheet which gives a BS2 appearance to BS3 styles, if that setting was saved within the theme configuration.
  • though the 'viewport' parameter is optional since we always set the minimum defaults, it is in this theme template as a point to deviate from.
  • we account for two (2) less stylesheet compiler variables (lessvars) we pull from the theme configuration settings which are mandatory for this theme's .less stylesheets.  Most (but not all) stylesheets used with a BS3 theme are in the .less format to allow custom configuration by the end user.  For example, the bootstrap3theme allows selecting from the entire set of 'BootSwatch' themes.  

Now a short sidebar on some BS3 basic concepts...there is a hierarchy of three (3) basic components for the BS3 grid system: 1) container, 2) row, and 3) column.  

  • The 'container' class element is mandatory as the highest level element for the grid system.  It may NOT be nested as this will create anomalies with display of the page.  The classname used for a container element is 'container'.
  • The 'row' class element MUST be placed within a 'container' class element, however unlike the container, they may be nested if the nesting occurs within a column.  In a basic sense, the row is a placeholder for up to 12 equal-width columns of data.  The classname used for a row element is 'row'.
  • The 'column' class element MUST be placed within a 'row' class element, and like the container may NOT be nested...except when found within a nested row.  The classname for a column element is more complex and composed of at least three (3) parts:
    • 'col-' to signify that this is a column
    • a designator for the device size the column setting applies to (more or this later).  But in our example we'll use the size for a small device or tablet with a max-width of 768 pixels which is 'sm-'.  Grid column classes are divided into device sized groupings:
      • 'lg' for large devices such as wide-screen monitors (max width 1200 pixels)
      • 'md' for medium sized devices such as desktop monitors (max width 992 pixels)
      • 'sm' for tablet sized devices
      • 'xs' for extra small devices such as phones (max width 640 pixels
      • These can be mixed within the same element to provide for a different layout on different devices.  E.g., a 4 column wide layout on a desktop would become a 2 column layout on a tablet (2 rows high) or a single column layout (4 rows high) on a smartphone.
    • and a digit to set the number of column units of width this column is to fill (from 1 to 12)
    • so the simplest column element would be 'col-sm-12' for a single column the entire width of the row.  A equal-width 2-column layout would be two elements each with a class of 'col-sm-6' (6 + 6 = 12).

<body>
    <div class="container">
        <div class="row">
            <div class="col-sm-12">
               This is a full width column, 12 units wide.
               A row with columns could also be placed within this element.
            </div>
        </div>
    </div>
</body>

Therefore, in Exponent, the template theme/subtheme template MUST hold any 'container' element(s).  There must NEVER be an element with the class of 'container' found within a view template.  A BS3 styled view template can ALWAYS assume it is being loaded within a 'container' and/or a 'column' element.  Therefore, the view template should be wrapped within a 'row' element if it will be subdividing its display using the grid system with 'column' elements.  The only exception to this is the navigation menu (navbar) which in most examples (including the main BS3 site) is simply wrapped within a 'container' element without rows nor columns.

So within the 'body' section of the /themes/bootstrap3theme/index.php default theme template, you'll note:

  • We have two (2) containers: one for the menu and one for the content
  • Within the menu container we have NO rows or columns, so the menu 'template' view can assume it's within a container
  • Within the content container we have two rows: one for the actual page content, and one for the page footer area
  • Within the actual page content row we have two columns: one for the main content, and one for the sidebar

For the Exponent theming system to work correctly with several UI frameworks, we allow for view templates to also have theme framework variations.  These system view templates are denoted by a framework type suffix before the file type.  So a system 'showall.tpl' view template with a BS3 variation would be named 'showall.bootstrap3.tpl'.  In the absence of a BS3 specific view template, the system would fallback and choose a BS2 template with that framework suffix...in this example if the BS3 variation template did not exist but a BS2 variation template existed named 'showall.bootstrap.tpl, it would be used instead of the base 'showall.tpl' file.  Since a custom theme can only use one UI framework, ALL custom template views use the root name without any framework variation.

A note about the /themes/bootstrap3theme/config.php theme configuration settings file.  You MUST include a variable named 'SWATCH' or the .less stylesheet compiler will crash when compiling the BS3 stylesheets. 

There MUST always be a file /theme/customthemename/less/variables.less, even if it's an empty flle. This file is ALWAYS compiled by the bootstrap.less file and overrides any bootstrap 3 and swatch variables as needed.  A failure to include this file (it may be empty) WILL result in a .less compiler crash.  This file should ONLY contain .less 'variables' as it will also always be compiled as a theme stylesheet and any 'styles' included within in it will also create a theme stylesheet named /css/variables.css.

In summary:

  • The theme/subtheme template MUST include the un-nested BS3 'container' element.  The theme/subtheme template is the only place the 'container' element will be found.  It may optionally contain 'row' elements' so long as it also contains 'column' elements within the 'row'.
  • The view template can always assume it's being displayed within a 'container' and/or also a 'column' element.
  • Any 'custom' view templates must only have the '.tpl' file type suffix and can NOT contain the '.bootstrap3.tpl' framework variation suffix.
  • Failure to follow these guidelines will cause horizontal margin anomalies and prevent theme custom views from loading

About the author

Dave Leffler
Exponent CMS Developer

Comments

No Comment yet

Leave a comment

Fill out the above security question to submit your form.