Setting Up Drupal Bootstrap

Setting Up Drupal BootstrapJun 15th 2015

For those looking for a reliable, responsive front-end framework to base their website/drupal theme upon, Twitter Bootstrap can be hard to beat. Luckily there is an existing, contributed theme available to take out the hard work of integrating Bootstrap and Drupal... Well nearly all the hard work.

This step by step tutorial hopes to serve as an extension to existing documentation for Drupal Bootstrap and strives to fill in a few blanks and signpost the odd 'gotcha' that can potentially leave the novice banging their head against their monitor. It assumes you already have a decent grasp of the drupal folder structure and a knowledge of LESS CSS preprocessor.

Drupal Bootstrap Theme

Download the latest version of the Bootstrap Drupal Theme.https://www.drupal.org/project/bootstrap

Unzip the contents into the sites/all/themes/ folder of your drupal site.

Copy the folder 'bootstrap_subtheme' and place the copy in the root of your regular sites/all/themes/ folder (You should now have two separate theme folders 'Bootstrap' and 'bootstrap_subtheme' at the same level in your theme folder structure).

Before anything else, rename the 'subtheme' copy to reflect the project you are working on. (for the purposes of this tutorial we'll name ours 'mytheme')

Bootstrap Editable Source Files

Bootstrap Drupal Theme provides the core framework to use bootstrap within Drupal, but we still need to include the latest working distribution of the editable bootstrap source files themselves.

In the future this should be possible using drush, but for now there are two methods for including these files. Either via link to the CDN, which is convenient, but does not give us full editability of LESS files, or by downloading the files to our theme to be used locally. Further info: https://www.drupal.org/node/1978010

We want to choose the second method...

  1. Download the latest distribution of bootstrap from: http://getbootstrap.com/getting-started/#download (Choose the second, 'SOURCE CODE' version.)
  2. Download to the root of your new sub_theme (mytheme).
  3. Unzip and rename the unzipped folder 'bootstrap'. (Yep this is where it can seem confusing, you will now have a new folder called 'bootstrap' inside your new bootstrap sub_theme)
  4. Inside your new subtheme edit the .info file. On the first line change 'name =' value to match your new theme name ('mytheme' in this instance).
  5. Now we need to tell the theme which method to use for including the Bootstrap distribution. Towards the bottom of the  .info file, uncomment all lines under the heading 'METHOD 1: Bootstrap Source Files'  (yes, all those JS files.)

LESS Preprocessor Method

Although you can run a (very restrictive) installation of Bootstrap using standard CSS, it's unlikely you'll want to pass up access to the wealth of in-built variables and mixins available in the core LESS files, so now we need to choose which method of LESS compilation we want to use.

If you wish to install and use a local LESS compiler, you can leave the .info file set to use /css/style.css and then set your preprocessor to compile all LESS files to this file.

*I recommend however using the Drupal LESS module, to let Drupal do the compiling for you in browser. For this method, change the 'Stylesheets' entry in .info to point directly to /less/style.less

For this method to work, you will need to download and install the drupal Less module here:https://www.drupal.org/project/less

Secondly download the Preprocessor library (lessphp) from:http://lessphp.gpeasy.com/#integration-with-other-projects

to > /sites/all/libraries/ unzip and rename the folder to 'lessphp'

Enable the LESS module (if you haven't already) and go to /admin/config/development/less in the Drupal admin menu.

Choose 'less.php' as your LESS engine and turn on 'Developer Mode'. (This will ensure LESS files are recompiled on each page load.) - *Make sure this is turned OFF before site goes live.

Turn On The Theme

If you haven't already, enable your sub_theme and make it the default theme.

Disable the main Bootstrap theme (it doesn't need to be enabled for the subtheme to work.)

Clear your drupal cache and you should be good to go.

JQuery Update

For boostrap to run properly, you will have to have JQuery installed and running at atleast version 1.7. Make sure you have the JQuery Update module installed and set to 1.7 or above. (I've run bootstrap on 1.10 without problems.) 

You can change the version on the JQuery Update config page, or specifically for the theme, you can switch the version on your bootstrap sub_theme's theme settings page. 

*If you have selected a version of JQuery 1.7 or above and you're still getting drupal errors complaining that Bootstrap requires this version, you can choose to 'Suppress jQuery version error message' under Advanced on the sub_theme settings page. 

Missing Variable Errors?

Sometimes the Drupal Bootstrap theme can fall out of sync with the latest Bootstrap version.

If after enabling the subtheme you get lots of red errors about missing variables, do the following:

Inside your subtheme:

Make a COPY of the latest variables.less from the distribution files (mytheme/bootstrap/less/variables.less) and use it to REPLACE the version in your theme's custom files (mytheme/less/variables.less)

This should stop bootstrap looking for out of date variables.

Page Templates

While you 'could' copy the page.tpl.php and html.tpl.php templates from the Drupal core and set about adding all the necessary bootstrap classes and regions to them, It makes much more sense to start off by making copies of the versions supplied inside the main Bootstrap parent theme, where most of the ground work has been done for you.

You can find templates at: bootstrap/theme/ (where 'bootstrap' is the main parent theme installed from drupal.org.) the page and html templates are inside the 'system' sub folder.

Copy the templates you need, to you sub_theme's template folder. (Create one if there isn't one already.)

Bootstrap LESS Files

In your sub_theme, you will initially have the following LESS files:

  • bootstrap.less 
    Never edit this. It's only purpose is to import all of bootstrap's core less files - the integral part of the framework.
  • overrides.less
    You will sometimes want edit some values in this file. It mainly contains drupal specific resets and 'overrides'.
  • variables.less
    This is where you can change the values of default bootstrap variables to set site wide typography, form styles, grid styles, branding etc. VERY USEFUL
  • styles.less
    This is initially empty other than a few import declarations. This like a normal style.css or .less file, is where you will put the bulk of your project specific custom LESS code.
  • header.less, content.less, footer.less
    I don't personally tend to find any use for these region specific files. These can safely be deleted if you don't intend to use them. If you do delete them, also make sure to delete their import declarations from the top of 'style.less'.

Custom Variables

You could create a new LESS file for your own custom variables, but I find a lot of my custom variables can be additions to existing bootstrap variable structures (for instance there is already a @brand-primary color value in variables.less and I nearly always add a @brand-secondary color), so it makes sense to include them in the same file and flow. So I add my variables to the existing file, making one consolidated, semantic file.

Custom Mixins

Mixins are a little different. You can just include them in style.less. You can also include them in the bottom of the existing overrides.less file. (You can include them anywhere really, but as you will often want to use variables within your mixins, it's advisable to call them after all variables have been imported from bootstrap and your own custom files.) I think the neatest way is to create new custom LESS file and keep all the custom mixins separate. For instance, on my current project, i've created a ‘custom-mixins.less’ file and imported it into style.less straight AFTER the existing imports like so:

// Bootstrap library.
@import 'bootstrap.less';
// Base-theme overrides.
@import 'overrides.less';
// Theme specific.
@import 'custom-mixins.less';

Wait!? Where was variables.less in those import declarations? 

Well, one thing to be careful of is that you don't want to import the same file into more than one other less file directly. This would in essence mean the entire file would be imported twice. So because variables.less has already been imported into overrides.less, it's content will be inherited through importing override.less into the above file.

Here's a diagram to try and better explain the bootstrap .less inheritance flow, mentioned above: 

In Conclusion

Hopefully these tips will be of use and help navigate the initially daunting landscape of getting Drupal and Bootstrap to play nice together.

This guide is based on the worflow I have personally found most logical and efficient, but if you have other methods or further tips to 'share with the class', feel free to leave a comment below.

My closing 'top tip' to developing with Bootstrap, Drupal or otherwise is to always have the Bootstrap site open in a tab, for easy reference of it's existng grid structure, variables, mixins, js plugins and info.

For anybody wanting to dig deeper into Bootstrap, the team over at Udemy have a great piece for anybody looking for a more comprehensive tutorial on all things Bootstrap.

Struggling with anything? Leave a comment and we'll do our best to help!

Written by: Martin White, Drupal Themer

Microserve is a Drupal Agency based in Bristol, UK. We specialise in Drupal Development, Drupal Site Audits and Health Checks, and Drupal Support and Maintenance. Contact us for for further information.

Original Article: