Getting started with Drupal Omega 4.4, Node.js and Gulp

I’ve been an active and thankful user of the Omega base theme for Drupal 7 since version 3. 

Version 3 was easy to set-up, by setting up regions and zones in the config (Drupal admin)  area, but rather limited in what could be accomplished. It mostly came down to setting up websites with 12 column grids and sidebars of 4 or 3 columns. Designing around these 12 columns was rather hard. 

Version 4 was a shock for me at first but I also discovered endless possibilities. I could manage layouts with .tpl files and add regions and wrappers wherever I wanted, I could use the power of Singularity Grids, Sass and Compass. With Omega 4 I have full control over the front-end code. 

• I can add grids, change the gutters, add breakpoints at will. Mostly I set up breakpoints for tablet and desktop but I add breakpoints wherever necessary. 
• In the Sass and Compass toolbox there are tools to create sprites or base encoded image right within the final stylesheet.  
• Text is managed with percentages so paragraphs and headings are really nice. 

But setting up the dependencies was really hard. I had to watch the tutorial of LevelUpTuts twice (and it takes a day to watch the series). You need Drush, GCC (a GNU compiler), Homebrew, RVM (Ruby Version Manager) and Bundler. Except for Drush and Homebrew, which are really useful on the local machine, I don’t care about the other technologies. Especially RVM was really hard to setup: it takes a long time to install and then you get errors you have to Google, possibly messing up the local system. It’s frustrating. Finally, Ruby based compilation of Sass files is slow, especially with bigger projects. 

But there’s good news! Version 4.4 of the Omega base theme replaces the Ruby based compilation by a more lean and simpler LibSass compiler. Now the dependencies are easier to manage and Sass compilation is much faster. 

Follow along: 

Installing the dependencies

We need Drush, XCode and Homebrew. 

You can work without Drush but Drush will make your live easier, check my tutorial. 

Install XCode: 

xcode-select --install

Install Homebrew, a package manager for OS X: 

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

To check if everything is correctly up and running, run: 

brew doctor

(For those with an existing Homebrew installation, run brew update and brew upgrade first). 

Finally, we need to install Node: 

brew install node

Check the version with: 

node -v

Installing a subtheme

Now cd to your Drupal (7) installation and download Omega:

drush dl omega

Install Omega: 

drush en omega -y

Clear the cache:

drush cc all

And install a barebone subtheme: 

drush omega-wizard

Choose Omega (not Ohm) with the default starterkit (don’t choose dusty, which is the Ruby based variant), give it a proper name,…  

Now, if you run drush omega-guard from within the subtheme folder (/sites/all/themes/THEMEMACHINENAME, you’ll receive the error “There was no Gemfile at /sites/all/themes/THEMEMACHINENAME”

In fact, drush omega-guard isn’t needed anymore. We should use the ‘gulp’ command (more on that later). 

Installing the node modules

Check this post by Vagelis on Drupal.org: https://www.drupal.org/node/2537364#comment-10287771. He gives an example of a custom gulpfile. I used this method and it’s working well. 

Install gulp globally: 

sudo npm install -g gulp

Edit the package.json file within the newly created subtheme folder (and change starterkit with the machine name of the subtheme): 

{
  "name": "starterkit",
  "version": "1.0.0",
  "description": "",
  "main": "gulpfile.js",
  "scripts": {
    "sass:dev": "./node_modules/.bin/gulp",
    "sass:prod": "./node_modules/.bin/gulp sass:prod"
  },
  "dependencies": {
  },
  "devDependencies": {
    "gulp": "^3.9.0",
    "gulp-sass": "^2.0.4",
    "gulp-sourcemaps": "^1.5.2",
    "gulp-autoprefixer": "^2.3.1",
    "node-sass-globbing": "0.0.23",
    "gulp-plumber": "^1.0.1",
    "gulp-cssmin": "^0.1.7",
    "browser-sync": "^2.9.8",
    "singularitygs": "^1.6.2",
    "compass-mixins": "^0.12.7",
    "breakpoint-sass": "^2.6.1"
  },
   "scripts": {
    "postinstall": "find node_modules -type f -name '*.info' | xargs rm"
  }
}

The last line of this script removes all the .info files in the node_modules folder. Drupal scans for those files and if it encounters one that shouldn't be there, your site can crash.   

And, within the same folder, also edit the gulpfile.js, this is mine (credits to Vagelis): 

'use strict';

var gulp = require('gulp');
var sass = require('gulp-sass');
var sourcemaps = require('gulp-sourcemaps');
var autoprefixer = require('gulp-autoprefixer');
var importer = require('node-sass-globbing');
var plumber = require('gulp-plumber');
var cssmin = require('gulp-cssmin');
var browserSync = require('browser-sync').create();

var sass_config = {
  importer: importer,
  includePaths: [
    'node_modules/breakpoint-sass/stylesheets/',
    'node_modules/singularitygs/stylesheets/',
    'node_modules/compass-mixins/lib/'
  ]
};

gulp.task('browser-sync', function() {
    browserSync.init({
        //injectChanges: true,
        proxy: "mywebproject.local:8888"
    });
    gulp.watch("./sass/**/*.scss", ['sass']).on('change', browserSync.reload);
});

gulp.task('sass', function () {
  gulp.src('./sass/**/*.scss')
    .pipe(plumber())
    //.pipe(sourcemaps.init())
    .pipe(sass(sass_config).on('error', sass.logError))
    .pipe(autoprefixer({
      browsers: ['last 2 version']
    }))
    //.pipe(sourcemaps.write('.'))
    .pipe(cssmin())
    .pipe(gulp.dest('./css'));
});

gulp.task('default', [ 'browser-sync']);

Important! Don't forget to edit the proxy to the actual local path of your website! 

Now cd to the subtheme folder and install the plugins: 

npm install

The npm install command will create a folder /node_modules in the theme folder and install all the dependencies listed in the package.json file. 

If there are dependencies missing, please check the nmpjs.com website (for example, install gulp via the command 'npm install --save-dev gulp'). The --save-dev installs it for this project only. 

Next, import Singularity, Compass and Breakpoint in the main scss file and import the scss files from within the subfolders (by using globbing). Add these lines on top of the yourtheme.styles.scss: 

@import "singularitygs";
@import "compass";
@import "breakpoint";

@import "sass/variables/**/*.scss";
@import "sass/abstractions/**/*.scss";
@import "sass/base/**/*.scss";
@import "sass/components/**/*.scss";

When using layouts (mylayout.layout.scss) (tutorial), you can use globbing but you need to add a point in order to start from the theme root: 

@import "./sass/variables/**/*.scss";
@import "./sass/abstractions/**/*.scss";
@import "./sass/base/**/*.scss";
@import "./sass/components/**/*.scss";

Finally, we can run gulp and start coding! Simply run: 

gulp

In case it's not working, try with sudo gulp. 

Related info: http://www.chenhuijing.com/blog/drupal-101-theming-with-gulp/.