Drupal Meets Sass: Getting Started With Aurora (Part 1)

Mike Crittenden, Software Architect
#Drupal | Posted

Drupal theming trends have slowly but surely kept up with the rest of the front end world, and leading that charge is our friend Sam Richard (aka Snugug) and his Aurora theme. Aurora is the grand introduction of Sass/Compass to Drupal, and it's a joy to use.

In this post I'll walk you through setting up and configuring both the theme itself and a Sass/Compass development environment. In follow up posts, I'll talk about how to make the best use out of this approach in your theming workflow.

Wait, what?

Before we jump into the steps, you (being the astute reader that you are) might find yourself wondering what these words mean. Worry not, it's actually pretty simple.

Sass

Sass stands for "Syntactically Awesome Stylesheets" and it can be an absolute godsend to anyone who writes a good bit of CSS. It's basically an extension of CSS which adds some great features on top of it and smartly compiles down to regular old CSS so that the browser doesn't know the difference. Some of the nicer parts include nested rules, variables, and mixins, but it brings a lot more than just that to the table. 

Compass

Compass takes things even further. It's a framework built on top of Sass that adds a metric ton of helpers and pre-build mixins and layout tools and lots of other cool stuff. It's also a command line tool (a Ruby gem specifically) which can watch your Sass files for changes and automatically compile raw CSS for the browser on the fly.

Aurora

The Aurora base theme for Drupal integrates Sass and Compass into a Drupal theming workflow, and is optimized for mobile first and responsive. Beyond that, it's fairly minimal as base themes go--it basically integrates Sass and Compass into Drupal, sets up a code structure for your Sass, and leaves the rest of the decisions up to you.

Step 1: Install Sass/Compass

So first you have to install Sass and Compass to your computer. This should be done wherever you develop--if you develop in a VM then you'll want to install them there. The steps required depend on your OS.

Windows users need to first install Ruby using Ruby Installer and can then open up a Ruby command prompt and run:

gem install compass

OSX

users already have Ruby installed so all you need to do is open up a terminal and run:

sudo gem install compass

Linux 

users, being naturally intelligent and good looking, know that installation depends on the distribution you're using. Here are Ubuntu instructions if that's your flavor. Otherwise, you'll likely want to Google "install compass <distroname>" to find distro-specific instructions.

Step 2: Install Aurora

Once you have Sass/Compass installed, you're ready to grab Aurora. First, you'll want to install the "compass-aurora" gem using:

gem install compass-aurora

Then, just download the Aurora theme from Drupal.org as you would any other theme. You'll also need to install the required Magic module for lots of helpers which Aurora integrates, and you might want to install the highly recommend HTML5 Tools module as well. If you're curious, you could also check out Aurora's list of recommended modules which you might find useful.

Step 3: Create your custom subtheme

Once everything is installed, you're ready to generate your custom subtheme. There are three different flavors of subthemes to choose from:

  • Corona is a subtheme which lacks a lot of structure to the Sass, including only a base folder, a global folder, and a design folder. To use Corona, run:
    compass create YOURTHEMENAME -r aurora --using aurora/corona
  • Polaris makes it easy to write code in accordance with SMACCS and includes folders/partials laid out according to the guidelines of SMACCS. To base your subtheme on Polaris, run:
    compass create YOURTHEMENAME -r aurora --using aurora/polaris
  • Aurora is the default and is based around the ideas that you that you start your theming with a style guide and as you theme you keep layout and design rules separate. As such, in addition to a global folder, it also includes a style guide folder along with a layout folder and a design folder. To use Aurora, run:
    compass create YOURTHEMENAME -r aurora --using aurora

Once you have your subtheme created, you'll want to install its dependencies. So "cd" into your subtheme's directory and then run:

bundle install

Note that if you get command not found errors for "bundle", you may have to install it using:

gem install bundler

Step 4: Configure and run Compass

At this point you have everything installed and a custom subtheme set up, so you're ready to roll.

First, you should open up your subtheme's config.rb file to take a glance at the default settings to get a feel for the options and see if you'd like to change anything. Particularly, you will likely want to uncomment the following line so that your browser's dev tools can map the generated CSS to the location in the source Sass files (more on this in Part 2):

  1. # In development, we can turn on the debug_info to use with FireSass or Chrome Web Inspector. Uncomment:
  2. # debug = true

Once you're happy with that, all you need to do is tell Compass to start watching your Sass files for changes, so that it knows when to recompile your CSS. So make sure you're still in your subtheme's directory, and then run:

bundle exec compass watch

Now, any time you make a change to any Sass files in your subtheme, Compass will see that and will instantly regenerate the CSS which the browser uses, so by the time you switch to your browser and refresh the page, you should see your newly generated CSS.

Note that you'll probably be running that 4 word command every time you start working on your theme and it can get kind of tiresome, so you might want to add something like this to your bash or zsh config so you can just type "becc" instead:

alias becc='bundle exec compass watch'

Step 5: Perform a sanity check

Just to make sure everything's working correctly, you'll want to open up one of your subtheme's Sass files such as "sass/partials/design/_design.scss" and make an obvious change such as:

  1. body {
  2. background: red;
  3. }

Then watch the command line output in the terminal where Compass is running. You should see it telling you that it detected a change and is rebuilding style.css, like this:

  1. Change detected at 10:34:47 to: partials/design/_design.scss
  2. overwrite stylesheets/style.css

Once that completes, switch to your browser and refresh your page. If your subtheme is set as the default theme and everything went according to plan, you should be presented with a horrible looking red background. Success!

Next steps

So now you have yourself a shiny new Sass/Compass based Drupal theme and you're ready to get to work. In Part 2 of this series, I'll walk through a nice and easy theming workflow using Aurora and give you some tips on making best use of Sass/Compass in Drupal.  Check out Part 2!

In the meantime, learn about the Omega theme in Josh Cooper's recent blog post.

Mike Crittenden

Software Architect