Editing Using Sass

[[Category:Sass]] [[Category:CSS]] [[Category:Web Development]]
== 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 [http://compass-style.org/install/ Compass Documentation]:

<syntaxhighlight lang="powershell">
m:\path\to\web_root\> gem update --system
m:\path\to\web_root\> gem install compass
</syntaxhighlight>

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:

<syntaxhighlight lang="bash">
$ compass create <project_name>
</syntaxhighlight>

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:

<syntaxhighlight lang="bash">
$ compass init
</syntaxhighlight>

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.<ref>[http://sass-lang.com/documentation/file.SASS_REFERENCE.html#output_style Output Style], Sass Reference</ref>
* `line_comments = false` to supress debugging information.

To include [[Using_Sass#Shared_resources|shared frameworks]] use `load`: 
<syntaxhighlight lang="ruby">
load "../../littledamien/common_lib"
</syntaxhighlight>

=== Directory structure ===

[http://thesassway.com/beginner/how-to-structure-a-sass-project The Sass Way: How to Structure a Sass Project]

<span style="color:red"><b>NB</b> I have started to settle on a slightly different model for naming the directories. The information below is outdated.</span>

<pre>
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
</pre>

* 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: 

<syntaxhighlight lang="bash">
$ compass compile
</syntaxhighlight>

To compile a specific .scss file : 

<syntaxhighlight lang="bash">
$ compass compile sass/myfile.scss
</syntaxhighlight>

Also, be aware of any toolkits (e.g. `gulp`) that might usurp the `compass compile` command.

==== In the background ====

===== Prerequisites =====

* [[:Category:Grunt|Grunt.js]]

===== Configuration =====

* Install the compass grunt module:
<syntaxhighlight lang="javascript">
$ npm install grunt-contrib-compass --save-dev
</syntaxhighlight>

* Configure `grunt`:
<syntaxhighlight lang="javascript">
/* 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');
};
</syntaxhighlight>

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:
<syntaxhighlight lang="powershell">
C:\> m:
M:\> cd littledamien\littledamien_web\
M:\littledamien\littledamien_web\> grunt watch
</syntaxhighlight>

* 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:
<syntaxhighlight lang="css">
@import "shared/modules/my_module";
</syntaxhighlight>

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

<syntaxhighlight lang="ruby">
load "../../littledamien/common_lib/"
</syntaxhighlight>

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).

<pre>
+- /              <-- 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
</pre>

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`:

<syntaxhighlight lang="javascript">
compass: {
    cms: {
        options: {
            config: "_cms/config.rb"
        }
    }
}
</syntaxhighlight>

Compile using `grunt`:

<syntaxhighlight lang="powershell">
path/to/web/root> grunt compass:cms  
</syntaxhighlight>

== Troubleshooting ==

=== Compile error: "ENOENT File not found..." ===

This occurred when attempting to compile 

== Notes ==
<references />