Using Sass

Prerequisites

Ruby

• Download the Windows Ruby Installer.
• Make sure to add the path to the Ruby bin directory to the global Windows Path variable.

Compass

From the Compass Documentation:

m:\path\to\web_root\> gem update --system
m:\path\to\web_root\> gem install compass

Installing Compass will also install Sass, since it is a dependency for Compass.

The gem command works in ms powershell.

Creating a Compass project

It's actually not that practical to follow the examples which assume that a project directory doesn't exist prior to starting out with Compass:

$ compass create <project_name>

What that command does is create a root directory for the website and place a configuration file (/config.rb), a directory for Sass files (/sass), and a destination directory for compiles CSS files (/stylesheets).

The locations of the Sass directory and CSS directory can be changed within the config.rb configuration file.

In most cases the web root directory already exists. In that case navigate to it, and:

$ compass init

Like compass create this creates a configuration file, a Sass directory, and a CSS directory. But it doesn't create the project directory.

Working with the project

Configuration

Configuration is defined in contrib.rb. The settings that have been used in past projects:

• css_dir: Destination path for compiled CSS files. Relative to project root. No leading slash on the path.
• sass_dir: Location of the Sass source files. Relative to project root. No leading slash on the path.
• output_style: Controls how compact or compressed the compiled CSS files will be: expanded, nested, compressed, or compact.
• line_comments = false to supress debugging information.

To include shared frameworks use load:

load "../../littledamien/common_lib"

Directory structure

The Sass Way: How to Structure a Sass Project

NB I have started to settle on a slightly different model for naming the directories. The information below is outdated.

sass/
|
|-- modules/
|   |
|   |-- _all.scss        # common includes
|   |-- _utility.scss    # module name
|   |-- _colors.scss     # Etc.
|   ...
|
|-- partials/
|   |
|   |-- _base.scss       # imports for all mixins + global project variables
|   |-- _buttons.scss    # buttons
|   |-- _framework.scss  # framework
|   |-- _grid.scss       # grid
|   |-- _text.scss       # text
|   ...
|
|-- vendors/             # CSS or Sass from other projects
|   |
|   |-- _colorpicker.scss
|   |-- _jquery.ui.core.scss
|   ...
|
|-- main.scss

• The modules directory is reserved for Sass code that doesn't cause Sass to actually output CSS. Things like mixin declarations, functions, and variables.
• The partials directory is where the meat of my CSS is constructed.
• The vendors directory is for third-party CSS.

Compiling

Manually

To compile all .scss files in the sass directory:

$ compass compile

To compile a specific .scss file :

$ compass compile sass/myfile.scss

In the background

Prerequisites

• Grunt.js

Configuration

• Install the compass grunt module:

$ npm install grunt-contrib-compass --save-dev

• Configure grunt:

/* gruntfile.js */

module.exports = function (grunt) {

	grunt.initConfig({

		pkg: grunt.file.readJSON('package.json'),

		watch: {
			files: 'sass/**/*.scss',
			tasks: ['compass']
		},
		compass: {
			dist: {
				options: {
					config: "config.rb"
				}
			}
		}
	});

	/* loading npm tasks */
	grunt.loadNpmTasks('grunt-contrib-compass');
	grunt.loadNpmTasks('grunt-contrib-watch');
};

The watch task watches the files specified with watch.files while it is running.

When any of those files are modified, it runs the task(s) specified with watch.tasks

Compass options can be set in compass.dist.options, or as in the example above, share them with a config.rb file with compass.dist.options.config.

Running the task

In PowerShell:

C:\> m:
M:\> cd littledamien\littledamien_web\
M:\littledamien\littledamien_web\> grunt watch

• This will start the "watch" task as defined in gruntfile.js, which will in turn invoke the "compass" task if any of the watched files are modified.

• This task doesn't seem like it's compatible with the "browser_sync" task. Until a better solution is found, run the two tasks in different powershells if they need to run concurrently.

The grunt task need to be started manually in a PowerShell at the beginning of each development session.

Grunt can be run from any local machine. (I.e. it doesn't require a remote desktop connection to the web server.)

Grunt is run from PowerShell on Windows. There is no support for either npm in cygwin, so no support for grunt either.

Shared resources

Setting up the framework:

• Outside of any specific web projects create a directory that will hold the Sass files.
  • E.g. [COMMON_LIB]stylesheets/shared/
• Put any files in there that can be used as a framework for all sites.
• The directory under [COMMON_LIB] must be named "stylesheets", I believe. When the framework is loaded, Compass always looks in a subdirectory named "stylesheets".

Using the framework in a project

• Framework files are included in the .scss files via:

@import "shared/modules/my_module";

In order to allow Compass to find the directory named shared, add the path to the shared Sass files to config.rb.

At the top of config.rb add

load "../../littledamien/common_lib/"

Again, the shared .scss files need to be placed in a subdirectory under that path named "stylesheets".

So, given the paths above, the .scss file _my_module.scss would be located in ../../littledamien/common_lib/stylesheets/shared/cms/_my_module.scss.

Multiple config files

This covers a situation where a section of a site (e.g. the CMS) has its own independent stylesheet(s).

+- /              <-- site root
|
+- config.rb      <-- compass config file for main site
|
+- css/           <-- main site compiled stylesheets location 
|
+- sass/          <-- main site sass/compass files
|
+- _cms/          <-- sub-site
   |
   +- config.rb   <-- compass config for sub-site
   |
   +- css/        <-- sub-site compiled stylesheets
   | 
   +- sass/       <-- sub-site sass/compass files

I haven't had any luck compiling the cms stylesheets from the command line.

Compass gets installed for the site in the web root directory. If you try to compile from within the _cms directory, it seems like the paths get confused.

The only way I have been able to compile the sub-site is with grunt, which gets run from the web root directory.

In gruntfile.js:

compass: {
    cms: {
        options: {
            config: "_cms/config.rb"
        }
    }
}

Compile using grunt:

path/to/web/root> grunt compass:cms