Bootstrap 4 template for CMSMS

This is my generic Bootstrap 4 template for use with CMSMS. It provides a central settings file to easily change the template, as well as a flexible template with 9 content sections. Sections can be styled through the Content Manager using the Bootstrap classes. It has the following dependencies:

Recommended CMSMS modules:

  • CGSmartImage
  • CGExtensions
  • CSSPreProcessor
  • SitemapMgr
  • Markdown1

Optional CMSMS Modules

  • FormBuilder
  • Captcha

Links to the template, stylesheets and required UDTs:

Template Files:
CSS Files:
Optional Module templates:
Smarty plugins:

Setting up CMSMS

We need to adjust some settings within CMSMS for the template to work correctly. Once you have installed the required modules listed above set them up as follows:

Installing the Smarty Plugins

This is ideally done via FTP.

  • Save the Smarty plugins linked above.
  • Upload them to /assets/plugins
  • Use the names specified in the link. The format of the name is important.

Adjusting Global Settings

We need to remove the default globallly applied meta tags to avoid duplication.

  • Head to Admin > Site Admin > Settings - Global Settings
  • Remove the following meta tags from the "Global Metadata" section:
    • <meta name="generator"...
    • <meta httpequiv="Content-Type"...
      Both of these tags are already included in the template and are now redundant.

Setting up Markdown

The default settings for the Markdown module are unsuitable for this template. Adjust them as follows:

  • Head to Admin > Extensions > Markdown
  • Set "Automatic Processing of Content Blocks" to "No"
  • Set "Active the security" to "Nope"
  • Set all three of the "patch me" values beneath to "Nope"
  • Save your changes
  • Ignore the warning stating "This javascript shouldn't be executed"

You also need to change your CMSMS profile settings to use the Markdown Editor.

  • Head to Admin > My Preferences > My Account > User Preferences
  • Set "Select WYSIWYG to use" to "Markdown"
  • Save your changes.

You may also wish uninstall the MicroTiny module if you no longer intend to use it.

Note: installing Markdown can break existing content. You may need to edit the pages and remove the excess HTML formatting. Here's a simple Markdown Cheatsheet.

Setting up CSSPreProcessor

CSSPreProcessor has no settings by default and must be configured. Note, this is highly dependent on your server configuration. This guide assumes you are using a box that you have control over, and as such we will be installing SCSS via gem.

Install either SCSS (instructions below) then do the following:

  • Head to Admin > Layout > CSS Preprocessor
  • Set your preprocessor to be Sass (from command line)
  • Leave the rest of the options blank.
  • You can tick minify if you like but it won't do anything.
Installing SCSS via gem:
  • Open an SSH window to your server
  • Type: sudo gem install sass
  • If it completes, we're done. If it fails chances are you need to also install gcc:
  • Type: sudo yum install gcc -y
Installing less via npm (optional, usually not needed):
  • Open an SSH window to your server
  • Type: sudo npm install -g less

Installing Bootstrap4, jQuery and lightbox2, Popper.js, FontAwesome

  • Open an SSH window to your server
  • Navigate to: /assets (not /assets/node_modules)
  • Type: npm install bootstrap jquery@3 lightbox2 popper.js font-awesome
  • Wait for it to finish. Warnings here are usually fine.
  • The installed files should now be at /assets/node_modules/..

FontAwesome will need some additional configuration, due to the way that CMSMS caches stylesheets. In the default settings the paths to the font files will be modified by the caching process and icons will fail to render.

Fix the font paths by doing the following:

  • Open assets/node_modules/font-awesome/scss/_variables.scss
  • Go to line #4 and change the value for the variable $fa-font-path to: ../../assets/node_modules/font-awesome/fonts
  • Save the file
  • Clear the cache

Configuring CGSmartImage

  • Head to Admin -> Extensions -> CG Smart Image Toolkit
  • Go to the "Embedded Images" tab
  • Change "Image embedding mode" to: "Smart mode but limit image size"
  • Set the "Embeddable image size limit" to 32, or smaller.

This is done so that the source code does not become overly bloated and unresponsive when viewed during development. This is due to the excessive source code length from having all images in the page embedded as base64 encoded strings. This setting enforces large images to be embedded as traditional links and only images smaller than the specified limit will be embedded in the page source.

Configuring Captcha module

  • Go to https://www.google.com/recaptcha/admin
  • Create or obtain the reCaptcha keys for your website
  • Go back to your CMSMS admin panel
  • Go to Admin > Extensions > Captcha
  • Set "Active library" to "reCaptcha"
  • Click Submit
  • Go to the "reCaptcha" tab
  • Enter your secret and site_key
  • Click Submit again

Configuring FormBuilder

  • Go to Admin > Extensions > Form Builder
  • Click "Add New form"
  • Set "Form name" to "Contact Form with Captcha"
  • Set "Form alias" to "contact-captcha"
  • Leave "CSS Class for this form" as the default value
  • Do not enable inline mode.

Under the tab Form Submissions:

  • Ensure "After form is submitted" is set to "Display 'Submissions template'"
  • Ensure "Page to redirect to after form submission" is set to "None"

Under the tab Captcha Settings:

  • Check "Use Captcha to protect form submissions"
  • Set "Help text for Captcha:" to "" (blank)

Under the Form Template tab:

  • Insert the code linked above.

Add fields. Recommended fields follow in a name:type,property format.

  • "Your Name": Email "From Name" Field, populate "Reply-To" email address, required
  • "Email address": Email "From Address" Field, populate "Reply-To" email address, required
  • "Subject": Email "Subject" Field
  • "Message": Text area, non-wysiwyg, 5 rows, 60 cols, required
  • "Send To": Email Results to set Address(es), enter your email here. Enter valid sender info.

Note: When embedding this form on your page you must disable Markdown Parsing for the content block that it is part of. This may mean moving the form to it's own content block.

Setting up the template:

  • Create a new design in Design Manager called Bootstrap4
  • Create each of the templates linked above, using the same names (eg "Bootstrap4 Settings").
  • Templates should all be set to type Core::Page, except for the the navigation which should be of type Navigator::Navigation
  • The following should be set as the "default" for their types:
    • Bootstrap4 Nonuple Cols
    • Bootstrap4 Nav
  • The following templates should be set as unlisted:
    • Bootstrap4 Core
    • Bootstrap4 Settings

Creating required folders

  • Create a new folder under /assets/ called "themes"
  • Create a new folder under /assets/themes called "bootstrap4". This folder will act as a container for assets used by this theme.
  • Create a new folder under /assets/themes/bootstrap4 called "images". This folder is expected to contain the following images for your site:
    • og-image.png - the default image used for the OG meta tags
    • favicon.png - PNG format favicon, recommended at least 196x196 resolution.
    • favicon.ico - traditional ICO format favicon
    • favicon.svg (optional) - SVG format icon for favicon and splash screen.

If you have used different names for your files, or altered the folder structure, you will need to update the Core::Page template "Bootstrap4 Settings" to reflect these changes.

Setting up the CSS

  • Create two stylesheets, named "custom" and "bootstrap" containg the code linked above.
  • Assign them to the Design.
  • Ensure "custom" is listed after "bootstrap".

  • custom is where you will add your custom css classes.
  • bootstrap is used to import the various bootstrap, fontawesome and lightbox css/scss files. This file can be modified to include external stylesheets, such as GoogleFonts.

Setting up the app-manifest

  • Create a new page.
  • Name it app-manifest.json
  • Make sure the alias includes the extension
  • Insert a placeholder in the content area. This will not be shown.
  • Set it to use the Bootstrap4 AppManifest template type.
  • Hide it from the menu
  • Update the $manifest_alias variable found around line # in the Bootstrap4 Settings template.

All done!

Test a page

Either make a new page and give it some content, or re-assign an existing page to use the "Bootstrap4" Design and the "Nonuple Cols" template.

  • This template gives you nine areas to play with.
  • It requires content in the first section (Section 1) to function.
  • The "Main" tab allows you to specify classes for the body, container, and row. By default they are set to the following:
    • "" (Blank)
    • "container"
    • "row"
  • Each section has a "Content" and "Class" attribute.
  • "Content" is for your page content. Use valid Markdown formatting.
  • "Class" expects a valid Bootstrapv4 column class, such as "col" or "col-sm-6".
  • The "Logic" tab contains an area for page-spcific JavaScript. This will be inserted after the main content, just before the </body> tag.
  • You can disable Markdown parsing for indiviual content blocks by entering "true" in the corresponding "Disable Markdown" field under the "Logic" tab.

Problems? Template not working?

Common errors:

  • Clear the cache (Admin > Site Admin > System Maintenance > Cache and Content > Clear Cache > Clear)
  • Markdown has not been configured
  • CSSPreProcessor has not been configured
  • Navbar not styled? You need to set the Navigation template as the default
  • HTML code is appearing?
  • This appears to be a bug caused by enabling markdown. You'll need to edit the page and remove the HTML.