Getting started Sass and Compass

Zen 7.x-5.0 was developed with the latest version of Sass and Compass (at the time!) Newer versions are not compatible with Zen's Sass files. To ensure you are using the correct version of Sass and Compass, you will need to use the "bundle" command which will read Zen's Gemfile to ensure the proper versions are used when compiling your CSS. To install the correction versions of Sass and Compass, go to the root directory of your sub-theme and type:

bundle install

You will also need to prefix any compass commands with "bundle exec". For example, type "bundle exec compass compile" instead of just "compass compile".

To automatically generate the CSS versions of the scss while you are doing theme development, you'll need to tell Compass to "watch" the sass directory so that any time a .scss file is changed it will automatically generate a CSS file in your sub-theme's css directory:

bundle exec compass watch

If you are already in the root of your sub-theme's directory, you can simply type: bundle exec compass watch

While using generated CSS with Firebug, the line numbers it reports will not match the .scss file, since it references the generated CSS file's lines, not the line numbers of the "source" sass files. How then do we debug? Sourcemaps to the rescue! To find the oringial, newer browsers have support for sourcemap files (*.map). These files are used by the built-in development tools of newer browsers to map the generated line to the SCSS source. When in development mode, Zen can be set to generate sourcemap files. Edit config.rb, and uncomment:

sourcemap=true

Enabling and using sourcemap files (*.map) in your browser

In short, Open Developer tools, go to settings, and enable an option to the
effect of: 'view original sources' or 'Enable CSS source maps'.

• Firefox
• Chrome
• IE

Developing with Sass & Compass

To automatically generate the CSS versions of the scss while you are doing theme development, you'll need to tell Compass to "watch" the sass directory so that any time a .scss file is changed it will automatically place a generated CSS file into your sub-theme's css directory:

compass watch <path to your sub-theme's directory>

If you are already in the root of your sub-theme's directory, you can simply type:

compass watch

If after using the compass watch command your theme stops behaving appropriately, it's possible this is a Compass version issue. You may need to install an older version of Compass (0.12.7) as follows:

gem install compass --version versionnumber

While using generated CSS with Firebug, the line numbers it reports will be wrong since it will be showing the generated CSS file's line numbers and not the line numbers of the source Sass files. To correct this problem, you can install the FireCompass plug-in into Firefox.

Developing with Zen Grids

Zen Grids is an independent project from the Zen theme. You can use Zen Grids on any website, no matter how its built (hand-written HTML, YAML, Jekyll, Joomla, WordPress, whatever). The Zen Theme includes Zen Grids because it makes building layouts really simple. (The comments below may be a bit confusing. So, just to be clear: you don't have to install Zen Grids separately when you want to create a Zen subtheme.)

On the Zen Grids website (http://zengrids.com), you can:

• Discover why building responsive layouts requires using a CSS preprocessor like Sass
• Learn how to use Zen Grids to build layouts
• Find a complete reference to all of Zen Grids’ variables, mixins and functions

Moving your CSS to production

Once you have finished your sub-theme development and are ready to move your CSS files to your production server, you'll need to tell sass to update all your CSS files and to compress them (to improve performance). Note: the Compass command will only generate CSS for .scss files that have recently changed; in order to force it to regenerate all the CSS files, you can use the Compass' clean command to delete all the generated CSS files.

• Edit the config.rb file in your theme's directory and uncomment this line by deleting the "#" from the beginnning: #environment = :production
• Delete all CSS files by running: compass clean
• Regenerate all the CSS files by running: compass compile

And don't forget to turn on Drupal's CSS aggregation. :-)

Check zen/STARTERKIT/sass/README.txt for updates.

More resources

• A short tutorial on introducing, installing and using sass/compass: http://thesassway.com/beginner/getting-started-with-sass-and-compass
• Slides about Drupal and Compass: http://www.slideshare.net/nathansmith/drupal-compass