Drupal 7 – Setup Bootstrap 3 Theme with Gulp for LESS compilation

Got a new responsive site freelance and i would like to try Bootstrap 3 theme in Drupal 7. A little bit confused at the very beginning because the theme has a lot of features and bug fixes ongoing. So the documentation is a bit lacking and i have to make some trials and errors before knowing what to do.

Some Drupal developers may also have problem on compiling LESS. So here i include a gulp script and some NodeJS packages to help.

Assume you have setup the Drupal 7.

1. Download the Bootstrap 3 Drupal theme. The current stable version is 7.x-3.0 which is a bit old and only works with Bootstrap 3.0.x. I am going to use 7.x-3.1 which supports the latest Bootstrap version (v3.3.2 at the moment i write this post). The 7.x-3.1 is still in beta (7.x-3.1-beta2). You could download it from the releases listing page.

2. Extract the Bootstrap 3 base theme to the sites/all/themes folder. You would found the starterkits folder containing the subthemes. as follow.

 

3. There are 3 different ways start the subtheme.

• cdn – Use the bootstrap framework provide by the CDN
• less – You have to download the bootstrap 3 source to the subtheme folder.
• sass – Didn’t try it, guess it is for the SASS version of Bootstrap.

4. Since i would like to use LESS for styling the website, i pick the less starterkit. So copy the starterkits/less folder to sites/all/themes. Rename to folder to whatever you want. In this example, i name it street. I also need to rename the less.starterkit to street.info and update the content accordingly.

5. Let’s take a look in the subtheme less folder.

• bootstrap.less
• variables.less
• overrides.less
• header.less
• content.less
• footer.less
• style.less

There are 3 different types of .less files.

• The bootstrap.less and variables.less are from Bootstrap 3 source, we will replace this 2 files from the newly downloaded Bootstrap 3 source. You can edit the variables.less for the Bootstrap basic configuration.
• I guess overrides.less is for Drupal to adapt the Bootstrap 3 theme. Only edit it when you know what you are doing.
• The header.less, content.less, footer.less and style.less are for your custom styling.

6. Download the Bootstrap 3 source and put it in your subtheme as shown in the following picture.

 

7. Replace the bootstrap.less and variables.less from the Bootstrap 3 source to /sites/all/themes/street/less folder.

8. Edit the bootstrap.less and update all @import as follow.

// Core variables and mixins
@import "variables.less"; // Use the one in the same folder, so leave this one untouch
@import "../bootstrap/less/mixins.less";

// Reset and dependencies
@import "../bootstrap/less/normalize.less";
@import "../bootstrap/less/print.less";
@import "../bootstrap/less/glyphicons.less";

// THE REST OF THE FILE...

9. The .less files are ready but we need to compile them into CSS files. Let’s handle them by gulp. Assume you have installed npm, create the package.json in your subtheme folder.

{
  "name": "street", // Whatever your want
  "version": "0.0.0",
  "description": "Build utility for working with the bootstrap subtheme",
  "author": "<your name>",
  "contributors": [
    {
      "name": "<your name>",
      "email": "<your email>"
    }
  ],
  "dependencies": {},
  "devDependencies": {},
  "license": "Private" // Or MIT if you want, haha~~
}

10. Install gulp globally.

npm install -g gulp

11. Move to the sites/all/themes/street folder and install the following project packages and save them as devDependencies in package.json.

npm install gulp gulp-less gulp-livereload gulp-sourcemaps gulp-watch --save-dev

12. Create the gulpfile.js.

var gulp       = require('gulp');
var less       = require('gulp-less');
var watch      = require('gulp-watch');
var livereload = require('gulp-livereload');
var sourcemaps = require('gulp-sourcemaps'); 

gulp.task('less', function () {
  gulp.src('less/style.less')
    .pipe(sourcemaps.init())
    .pipe(less())
    .pipe(sourcemaps.write())
    .pipe(gulp.dest('css'))
    .pipe(livereload());
});

gulp.task('watch', function() {
  livereload.listen();
  gulp.watch('less/*.less', ['less']);
});

13. If you want to compile the less/style.less into css/style.css, simply execute:

gulp less

14. If you want to watch all the .less files and auto compile the less/style.less, run:

gulp watch

15. If you can run the above commands without errors, your Bootstrap 3 subtheme is ready. Enable it and see if it works!

 

16. Note that in the gulpfile.js i have a livereload package so the page will autoreload if the .css files are recompiled. It works with a chrome plugin called LiveReload. For more information, please visit GitHub – vohof/gulp-livereload.

Done =)