Using Sass and Compass with Drupal

• Katie Graham's blog

If you haven't already, you'll also need to install Compass on your server. If you have Ruby installed, you can install Compass by running - as Sass is a dependency, it will install that for you too. Because we're running Debian, we had to add export PATH=${PATH}:/var/lib/gems/1.8/bin to our .bashrc files, where 1.8 is the version of Ruby we're using. Check that it's installed and working by running $ compass --version. If you don't see any error messages, you're ready to move to the next step.

Although it's not required, I'm using the Compass Drupal module. The main benefit of using this module is that you can configure it to watch your sass folder and automatically rebuild your stylesheets and generate new sprite maps on each page load. Yes, you can achieve this without the module, by using $ compass create or $ compass init and $ compass watch, however since other Webscopers jump in and make some CSS tweaks from time to time, I wanted to make it easy for those who don't use the command line.

I'm assuming that everyone uses the Devel module while a site is in development, but if not, install this now, along with the Compass module. Once they're both installed, you'll need to let the Compass module know the path to your Compass binary. The main settings page can be found at yoursite.tld/admin/config/compass - it should pick up the path to the binary automatically, but if you're running Debian and it doesn't pick up the path, try /var/lib/gems/1.8/bin/compass, again where 1.8 is the installed version of Ruby. You can also set further options on this page - choose the appropriate Output Styles for you're environment, and for a development environment, ensure you check the "Run compass during devel theme rebuild" box in the Compass settings and "Rebuild the theme registry on every page load" in the Devel settings page, as this will rebuild your stylesheets and generate compass sprites on each page load. I'm also using the Relative Assets option as we migrate sites between Aegir platforms and servers so I don't want absolute paths in stylesheets, etc. If you need to manually run Compass from the Drupal UI, you can do so at yoursite.tld/devel/compass

Now you need to make some changes to your theme. Open your theme's .info file and add the following lines:

compass[status] = 1
compass[sass_dir] = "sass"
compass[css_dir] = "css"
compass[images_dir] = "css/images"

Where the structure of your theme folder is as follows:

theme_folder/css
theme_folder/css/images
theme_folder/sass

However you can change the Sass configuration to match your existing theme's folder structure.

You'll need to leave reference to your stylesheets in your info folder, as the Compass module doesn't add your stylesheets for you, i.e.

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

At this point, if you're working with an existing theme, back up your .css files so they're not overwritten by Sass.

Now for the fun part! For each stylesheet you want included in your theme, create the equavalent .sass or .scss file in the sass folder. i.e. if my theme uses css/style.css, I'll need to create sass/style.scss. Now everytime you load a page, Sass will detect any changes and overwrite the .css files in the css folder.

To have Compass create image sprites and the corresponding css, create another folder inside your images folder and place your .png files in there. In your .sass or .scss file, add something like the following, where "icons" is the name of the folder you've placed your .png files in:

$icons: sprite-map("icons/*.png", $new-position: 0, $new-spacing: 15px, $new-repeat: no-repeat);

You can now use the generated sprite like so:

.myElement {
  background: sprite($icons, iconname);
  height: icons-sprite-height('iconname');
  width: icons-sprite-width('iconname');
}

Where "iconname" is the name of the original .png you're wanting to reference and Compass will take care of the rest for you. Magic!