Installing Twitter Bootstrap with Drupal

This post covers installing Twitter Bootstrap with Drupal using Drush

Tested:Drupal 7.18

Bootstrap(below 2.2) Without CDN

Step-1 Install Drupal Twitter Bootstrap Module

drush dl bootstrap-7.x-2.2
drush en bootstrap-7.x-2.2

This will create the base bootstrap theme in sites/all/themes folder

Step-2 Update with 2.3.2 Twitter Bootstrap
Downloaded the version 2.3.2 from Twitter Bootstrap and extract into sites/all/themes/bootstrap/bootstrap folder(yes, it is not mistake folder ‘bootstrap’ within folder ‘bootstrap’). Afterwards, you can test it by going in ‘Appearance’ section and setting ‘bootstrap’ as default theme to see if it works

UPDATE April, 2015:
There is no more support for CDN Bootstrap 2.3.2, so to make it work, you have to configure Bootstrap locally as follows:

  1. Disable CDN by updating bootstrap.info
    settings[cdn_bootstrap] = 0

    Or desable from the UI in the Theme/Bootstrap/Settings

  2. Specify to read Bootstrap libraries locally by including the following in bootstrap.info
    scripts[] = 'bootstrap/js/bootstrap.min.js'
    stylesheets[all][] = bootstrap/css/bootstrap.min.css
    

    Here, we assumed you have downloaded bootstrap libraries into the /bootstrap directory as described Step-2 above

Step-3 Create Your Theme
Follow steps https://drupal.org/node/1844448 to create your theme. To summarize, create your theme folder. In this folder add file themeName.info and update accordingly. At last, copy UI artifacts in the theme/css and image folder

Step-4 Converting Theme
In this process, we suggest to do one page at the time by coping template files from sites/all/themes/bootstrap/templates into sites/all/themes/yourThema/templates. This will override the base bootstrap theme templates so you can modify per your needs and it doesn’t affect future Twitter Bootstrap upgrades.

Boostrap 2.3 With CDN

With module bootstrap 7.x-2.2, the structure is different for building Drupal themes that inherits from bootstrap. It also have a setup that retrieves the Twitter Bootstrap library dynamically and doesn’t physically store library files locally. While it provides convenient way to switch between versions of Bootstrap, it does require you to depend on third party.

Step-1 Install The New Drupal Twitter Bootstrap Module

drush dl bootstrap
drush en bootstrap

To test it, login as administrator and set the default theme(admin->Appearance and click ‘Set Default’ for Bootstrap theme) to the Bootstrap theme
Step-2 Create Your New Themes Codebase
All of the themes are inherited from the Bootstrap main theme and is referred as sub-themes
a)Create Sub Theme
Make a copy of the ‘bootstrap_subtheme’ folder, rename to your new theme name and place it in ‘sites/all/themes/’ folder. By keeping it outside the Bootstrap directory it makes easy to upgrade Drupal Bootstrap module in future
b) Setup Configuration of Your New Subtheme
Rename the file ‘sites/all/themes/NEWTHEME_NAME/bootstrap_subtheme.info.starterkit’ to ‘sites/all/themes/NEWTHEME_NAME/NEWTHEME_NAME.info’
c) Configure Your New Subtheme
Update the ‘sites/all/themes/NEWTHEME_NAME/NEWTHEME_NAME.info’ file with:

name = NEWTHEME_NAME
description = description of your new NEWTHEME.
core = 7.x
base theme = bootstrap

Step-3 Enable Theme
Clear cache and go to ‘Admin/appearance’ to switch to your new theme

Run Bootstrap 3.0.x Locally

At this time, the Drupal Bootstrap module for Drupal has Boostrap 3.0.x version as other release, so to download with drush you have to specify complete version as following:

sudo drush dl bootstrap-7.x-3.0-rc2
drush en bootstrap

Afterwards, make sure you have jQuery_update module with Jquery version 1.7 or above

a)Disable CDN Loading
Go to Theme Settings(admin/appearance/settings/YOUR-THEME) and uncheck ‘use CDN load..’ under THEME CDN SETTINGS section.
Also update the ‘settings[cdn_bootstrap]’ to ‘0’ in the THEMENAME.info file to change the default setting for CDN to be disabled

b)Install Bootstrap 3.0.x Locally
From the Bootstrap site, grab the zip file and extract all artifacts(Css, Js, Font,etc) into the ‘bootstrap’ folder of your theme. This will keep Bootstrap separately easy for upgrade in future

c)Configure to load Bootstrap Library Manually
Next configure to load Bootstrap library from the local file system by adding the following in ThemeName.info file:

;Stylesheets
stylesheets[all][] = bootstrap/css/bootstrap.min.css

;JavaScript
scripts[] = 'bootstrap/js/bootstrap.min.js'

This approach gives a way to import a none minimal version by updating the name of bootstrap file ‘bootstrap.min.js’ to ‘boostrap.js’ and the same for css. Please, note that we don’t exclude bootstrap.css like boostrap.js because on Jan, 2014 the bootstrap.css is not always included like .js. It may change. Please see code ‘bootstrap/theme/alter.inc’

c)Auto load Bootstrap Library
Perhaps, you like to have so that once CDN disable it automatically grabs the local version, then you have to update ‘bootstrap/theme/alter.inc’ file as following:

function bootstrap_js_alter(&$js) {
...
// Add CDN.
  if (theme_get_setting('bootstrap_cdn')) {
    $cdn = '//netdna.bootstrapcdn.com/bootstrap/' . theme_get_setting('bootstrap_cdn')  . '/js/bootstrap.min.js';
    $js[$cdn] = drupal_js_defaults();
    $js[$cdn]['data'] = $cdn;
    $js[$cdn]['type'] = 'external';
    $js[$cdn]['every_page'] = TRUE;
    $js[$cdn]['weight'] = -100;
  }else{
      /***********ADD THESE LINES BELOW*********/
      $active_theme_path = drupal_get_path('theme', $GLOBALS['theme']);
      $cdn = '/' . $active_theme_path .'/bootstrap/js/bootstrap.min.js';
      $js[$cdn] = drupal_js_defaults();
      $js[$cdn]['data'] = $cdn;
      $js[$cdn]['type'] = 'external';
      $js[$cdn]['every_page'] = TRUE;
      $js[$cdn]['weight'] = -100;
  }
}

In line 4, it check if CDN is enable. If it is not then the local Js Bootstrap library is added. The similar change have to be made for CSS in the same file ‘bootstrap/theme/alter.inc’ as following:

function bootstrap_css_alter(&$css) {
...
if
 $bootstrap_cdn = theme_get_setting('bootstrap_cdn');
  if ($bootstrap_cdn) {
    // Add CDN.
    if (theme_get_setting('bootstrap_bootswatch')) {
      $cdn = '//netdna.bootstrapcdn.com/bootswatch/' . $bootstrap_cdn  . '/' . theme_get_setting('bootstrap_bootswatch') . '/bootstrap.min.css';
    }
    else {
      $cdn = '//netdna.bootstrapcdn.com/bootstrap/' . $bootstrap_cdn  . '/css/bootstrap.min.css';
    }
  }else{
      /********ADD THE FOLLOWING LINES***********/
      $active_theme_path = drupal_get_path('theme', $GLOBALS['theme']);
      if (theme_get_setting('bootstrap_bootswatch')) {
          $cdn =  $active_theme_path . '/bootswatch/' . theme_get_setting('bootstrap_bootswatch') . '/bootstrap.min.css';
      }
      else {
          $cdn =  '/' . $active_theme_path . '/bootstrap/css/bootstrap.min.css';
      }
  }
    $css[$cdn] = array(
      'data' => $cdn,
      'type' => 'external',
      'every_page' => TRUE,
      'media' => 'all',
      'preprocess' => FALSE,
      'group' => CSS_THEME,
      'browsers' => array('IE' => TRUE, '!IE' => TRUE),
      'weight' => -2,
    );
...
}

Here, the same way in line 5 there is a check if CDN enabled. If not, then the Bootstrap Css library attached or the Bootswatch if enabled

d) Turn Bootswatch locally
Bootswatch may be the next thing where the layout is separated out from the styling for easy swap between the styles. To get Bootswatch run locally, first clone it in some folder separate from your projeced

sudo git clone https://github.com/thomaspark/bootswatch.git bootswatch

Then, create as symbolic link from your sub-theme as following:

ln -s {/path/to/bootswatch} bootswatch

By keeping bootswatch separate, it will be easy to upgrade in future for all of the subthemes that is linking to the bootswatch

e) Load Your Custom Bootstrap
It appears that the newest version of Drupal Bootstrap grabs the local JS from the base theme Bootstrap when the CDN is disabled. Perhaps, you like to load particular version from your subfolder then it will conflict unless you disable the default local bootstrap as following in template.tpl.php:

function THEME_js_alter(&$javascript) {
    unset($javascript[drupal_get_path('theme','bootstrap').'/js/bootstrap.js']);
}
function THEME_css_alter(&$css) {
    unset($css[drupal_get_path('theme','bootstrap').'/css/bootstrap.css']);
}

This removes the Boostrap JS/CSS lib to load from the base bootstrap theme so you can load it from you sub-theme as you wish

Afterwards, configure to load in THEME.info file as following:

;stylesheets[all][] = bootstrap/css/bootstrap.min.css
stylesheets[all][] = bootswatch/amelia/bootstrap.min.css

In first linke, uncomment the original bootstrap library, so it doesn’t load. And then specify which bootstwatch to load(i.e. amelia)

Issues

1. This version is not compatible with Drupal 7.x and should be replaced.
This error was due to the fact that the theme.info file didn’t specified the Drupal version, so by adding:

core = 7.x

This solved the issue

2. My New Bootstrap Subtheme Doesn’t Style
After creating the subtheme and enabling as the current theme, the styling is not being applied. This happens, if we haven’t specified the sub theme to inherit from Bootstrap main theme. Make sure your theme.info file contains the following:

base theme = bootstrap

This tells that your subtheme inherits the Bootstrap theme.

3. TypeError: a(…).on is not a function
The following JS error is because the current jQuery Lib is not compatible with the Bootstrap. Make sure you have installed Jquery update on your Drupal site and set the jQuery version to be 1.8 or 1.7

sudo drush dl jquery_update
sudo drush en jquery_update

Afterwards, go to the Modules->jQuery Update->Configurations to set the jQuery version

4. Unable To Use Admin Controls
Once logged in, you are unable to click on any of the admin controls in top horizontal menu. This is because the top sub themes navigation horizontal region is on top of the admin controls and you cannot see it because it is transparent background. To solve the problem add the following in css/style.css file

#navbar{
    z-index: 0;
}

This moves the top horizontal menu underneath the admin controls menu.
!Make sure you are importing the styles.css file by having following entry in the themeName.info file:

...
stylesheets[all][] = css/style.css

5. IE Support
To make your bootstrap themes to work for IE8 and lower version, you have to include the Respond.js in the html as described in Bootstrap Docs. In addition, you have to ensure that your stylesheets are imported via LINK tag instead of STYLE/import. Otherwise, the Respond.js script will not provide the IE support needed. In our case, we were using drupal_add_css() function to attach the CSS styles which by default imports CSS styles via STYLE/import style. As result, the themes were not displaying properly in IE. So, to make it import styles via LINK tag:

 drupal_add_css(drupal_get_path('theme',$GLOBALS['theme']) .'/custom-bootstrap/bootstrap.min.css', array('type' => 'file','preprocess' => FALSE, 'weight' => CSS_THEME));

Here, by specifying the ‘preprocess’ option to FALSE, makes the CSS import via LINK tag(the same if type=’external’). It may not be necessary if the aggregation is turned on,then by default it imports via LINK tag