Setting Up Bootstrap in Drupal 7

Setting Up Bootstrap in Drupal 7
Microserve's picture
Jun 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.

Credit: This blog post was written by Martin White during his time at Microserve.

Drupal Bootstrap Theme

Download the latest version of the Bootstrap Drupal Theme and 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 of the folder to reflect the project you are working on i.e. '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 rename the included .info file to reflect you project. As default this file will be named something like 'bootstrap_subtheme.info.starterkit' or 'starterkit.info'. We want to rename it to something more useful, so in our case 'mytheme.info'.  
  5. Open the newly renamed file and on the first line change 'name =' value to match ('mytheme' in this instance) and edit the description to something more specific to our new theme. This will ensure that when admins visit the 'appearance' page our new theme is easily recognisable.
  6. 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, in addition to downloading the Preprocessor library (lessphp). Unzip the library to /sites/all/libraries/ 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, though it is important you turn this OFF before the 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 at least version 1.7. Make sure you have the JQuery Update module installed and set to 1.7 or above. For the record I've run Bootstrap on 1.10 without any 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 file 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.lessThis 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 your sub_theme's template folder. I recommend creating the folder if there isn't one already to keep the theme tidy.

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 be safely deleted if you don't intend to use them. If you do delete them, 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 Microserve have adopted as the 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.

We've also have another great post - Getting Bootstrap Grid Classes Into Drupal 7 CMS Markup - to provide further information on how to use Bootstraps native classes to make your site builder much more efficient. 

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

Kirsty Bewley's picture

You may also like...

We've gained two Acquia Drupal Site Builder certificates!

Kirsty Bewley, Jun 3rd 2015
Rick and I took the Acquia Drupal site builder exam yesterday, and we're proud to say we both passed with scores of 90% and higher!

Comments

nachobenavides

Jun 16th 2015 - 2:06amreply
nachobenavides's picture

Muy buen artículo

Martin White

Jun 17th 2015 - 4:06pmreply
Martin White's picture


Gracias!

Anonymous

Jun 16th 2015 - 4:06pmreply
Anonymous's picture

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

That's false, it definitely needs to be enabled.

Martin White

Jun 17th 2015 - 4:06pmreply
Martin White's picture

Are you using the CDN method  to include Bootstrap files? If so , it might make sense that the Base theme  being enabled would be a requirement, but the instructions here are for using 'Method 1 - Including Bootstrap Source Files' (https://www.drupal.org/node/1978010), which definietly doesn't require it. 

In fact the site we're looking at right now has a Bootstrap subtheme and I can confirm the main Bootstrap base theme is  disabled. The only enabled themes currently are the custom Bootstrap subtheme and our admin theme, and as you can see everthing is working Bootstrap-wise ;)

Mangini

Jun 17th 2015 - 12:06amreply
Mangini's picture

Is the Project/Theme also working for Bootstrap with Sass, since I prefer this compiling language over LESS?

Martin White

Jun 17th 2015 - 4:06pmreply
Martin White's picture

Hi  there. 

I think i'm right in saying that at this time The Drupal Bootstrap theme only supports LESS.

I haven't personally tried setting up a SASS Bootstrap theme in Drupal, but i know there are people who have and do successfully.

The following links may be of help:

https://www.drupal.org/node/2358699

http://www.webfoobar.com/node/9

Todd

Jul 8th 2015 - 10:07pmreply
Todd's picture

Nice tutorial.

One question. You say "Copy the folder 'bootstrap_subtheme' and place the copy in the root of your regular sites/all/themes/ folder" I elected to Cut and Paste and it seems to be working fine.

I will go on to theme now. Any hints on how to get rid of some of the JS and CSS hits drupal seems to get on Google PageSpeed Insights. I get less than most but still like to clean up some of what seems to be D7 Core related. Thanks again for the nice and thoughtful and through tutorial.

Martin White

Jul 23rd 2015 - 12:07pmreply
Martin White's picture

Hi Todd,

Sorry for the late reply .

The reason I would suggest to copy rather than move the subtheme, is so you always have that original 'clean' copy to refer to, should anything go wrong/missing in your custom theme. Mainly a safety precaution.

As for the CSS/JS hits, that's quite a big and open ended topic, as every site is configured differently, with different modules and dependencies., running on different servers.

There are a few simple golden rules though. Like always makes sure CSS and JS Aggregation is switched ON on your live site (/admin/config/development/performance) , turn on caching for views/blocks/pages that are unlikely to change very often and disable and remove any contributed modules not needed by your site.

emmanuel

Aug 4th 2015 - 8:08amreply
emmanuel's picture

Hello martin ,
thank you for your tutorial, it's very useful.
i'm looking for build my own theme in drupal , but really want to do it with bootstrap.i use it with wordpress for multiple project but in my new job they only work in drupal and if you know good link to start from scratch a theme in drupal with the same quality of your tutoriel , i'll be very kind .best regards .emmanuel

Martin White

Oct 9th 2015 - 1:10pmreply
Martin White's picture

Hi Emmanuel, Sorry for the late reply.

I would still definetly recommend teh above method of using the Bootstrap Drupal theme.
https://www.drupal.org/project/bootstrap

The starter 'sub theme' that comes with it is very plain and unstyled, so perfect for customising to whatever you need to do.

Julian Taylor (macjules)

Aug 13th 2015 - 10:08amreply
Julian Taylor (macjules)'s picture

Really nice, well written tutorial. Thank you. I find it a help to download the documentation from Bootstrap as well and then use that to create a custom help system not just for a client but also for any future developers who may need to work on the project. Include the help system within the theme so that they can access it easily.

Martin White

Oct 9th 2015 - 1:10pmreply
Martin White's picture

That's areally nice idea Julian!

The thing with bootstrap is that it works brilliantly if everyone who works on the project has a basic knowledge of how it works and don't start trying to fight against it or re-inventing the wheel. Your idea would certainly help keep a consistant approach. 10+ Kudos!

Douglas Alencar

Aug 15th 2015 - 1:08amreply
Douglas Alencar's picture

Very good article. Helped a lot! Thanks!

Matt

Sep 11th 2015 - 6:09pmreply
Matt's picture

Martin, thanks for an excellent and thorough tutorial -- this definitely fills an unmet need for those of us trying to get started with CSS preprocessors. vis-a-vis Drupal.

One minor omission (but necessary for Drupal to recognize the theme) is to rename the starterkit.info file to mytheme.info

Thanks again!

Martin White

Oct 9th 2015 - 2:10pmreply
Martin White's picture

Good catch Matt!

I've updated the section you mean with slightly more indepth instructions.

Cheers!

Oliver

Oct 25th 2015 - 5:10amreply
Oliver's picture

Hi Martin,
i use bootsrap aswell on my projects but ran into the issue that the collapsible function collides with the collapsible function of the fieldset project (module). Do you have an idea to fix this? I was looking for either fixing the issue on bootstrap 3.0 with a patch or update from 3.0 to a higher version where it is said to be fixed. Until today i did not find a suitable solution.

Thanks

Edgar Rojas

Oct 25th 2015 - 9:10pmreply
Edgar Rojas's picture

Hi Martin!! I'm a newbie with drupal bootstrap theming. I've a bootstrap template and i interested in migrate it into drupal. Can you tell me about an override page.tpl.php tutorial for do this? Thanks a lot!!!!

Brent Kowalczyk

Jul 13th 2016 - 6:07pmreply
Brent Kowalczyk's picture

I have downloaded the latest version of Bootstrap and there is no folder "bootstrap_subtheme" is this correct?

Add new comment

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.

Related Blogs

Sophie Shanahan-Kluth's picture
Mark Pavlitski's picture
Rick Donohoe's picture