Editing Using Sass (section)

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