PT Commons

h1. Compass

Maintaining projects with compass-based themes requires the ability to edit SCSS files and to recompile them to CSS. Be aware that any changes to CSS files (compiled output) will be lost when the stylesheets are recompiled, so you should always make changes to the SCSS files.

Compass is a tool for managing Sass stylesheet projects. Sass is a language that compiles to CSS and also the name of the compiler. Compass makes working with Sass outside of a Ruby project much easier, however it is entirely possible to work with a Compass project using just the Sass compiler. But truly it's not worth the trouble! You likely won't encounter a situation where you have sass but not compass and no permission to install compass.

h1. Installing compass

<pre>

sudo apt-get install rubygems

sudo gem install compass --pre

</pre>

This installs all dependencies including Sass.

Our projects tend to use additional compass plugins, which are installed as Ruby gems. Here are the set I commonly rely on:

<pre>

sudo gem install compass-rgbapng survivalkit foundation

</pre>

If one of these things is missing, you will be told in a very straightforward way when you try to compile a project that something is missing:

<pre>

benjamin@dev1:/var/www/dev/nlg/sites/all/themes/prudence$ /var/lib/gems/1.8/bin/compass compile

LoadError on line 31 of /usr/lib/ruby/1.8/rubygems/custom_require.rb: no such file to load -- survivalkit

Run with --trace to see the full backtrace

</pre>

The proper response to that is:

<pre>

sudo gem install survivalkit

</pre>

h1. Compass projects

I'm referring to SCSS which is a syntax of Sass that closely resembles CSS. From "Wikipedia":http://en.wikipedia.org/w/index.php?title=Sass_(stylesheet_language)&oldid=550390589

> Sass consists of two syntaxes. The original syntax, called "the indented syntax" uses a syntax similar to Haml. It uses indentation to separate code blocks and newline characters to separate rules. The newer syntax, "SCSS" uses block formatting like that of CSS. It uses braces to denote code blocks and semicolons to separate lines within a block. The indented syntax and SCSS files are traditionally given the extensions .sass and .scss respectively.

None of our projects use the Sass syntax. Both variants are fully supported by Compass and Sass.

Compass-based themes are compass projects. You can identify them by the "config.rb" file in the theme directory. This config.rb specifies the location of SCSS source files and the destination of compiled output. In almost every case, "css" is the name of the output directory and "sass" is the name of the source directory.

These directories are relative to the theme directory itself. If there's any confusion, view the config.rb file to find the exact names of the directories.

<pre>

# Location of the theme's resources.

css_dir         = "css"

sass_dir        = "sass"

extensions_dir  = "sass-extensions"

images_dir      = "images"

javascripts_dir = "js"

fonts_dir       = "fonts"

</pre>

In the "sass" directory, you will see the source files that end with "scss." Some of these files are prefixed with "_" which identifies them as "partials." This is a Ruby concept that appears throughout the ruby ecosystem. "For sass, this simply means:":http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html

> If you have a SCSS or Sass file that you want to import but don’t want to compile to a CSS file, you can add an underscore to the beginning of the filename. This will tell Sass not to compile it to a normal CSS file. You can then import these files without using the underscore.

h1. Editing SCSS

Recompiling stylesheets in a project is simple