Ruby-based Configuration Reference

The compass configuration file is a ruby file, which means that we can do some clever things if we want to. But don’t let it frighten you; it’s really quite easy to set up your project.

Basic format

Most configuration properties are a simple assignment to a configuration property. For example:

css_dir = "stylesheets"

Most configuration properties have a value that is a “basic” type. There are three basic types that can be set to a property:

• String – Text is surrounded by either single or double quotes. E.g. "this is a string"
• Symbol – A symbol starts with a colon and has no spaces in it. Symbols are used to represent values where the set of possible values are limited. E.g. :foo or :foo_bar_baz
• Boolean – true or false

There are two kinds of composite values:

• Array – An Array is a comma delimited list of basic values surrounded by square brackets. E.g. ["one", "two", "three"].
• Hash – A Hash is an association or mapping of one value to another. It is a comma delimited list of associations surrounded by curly brackets. An association is two values separated by =>. E.g. {:foo => "aaa", :bar => "zzz"}

Comments

Use the hash sign # to comment out everything from the hash sign to the end of the line.

Import Note for Windows Users

The backslash character (\) is a special character in a string delimited by double quotes ("). If you are working with folders in your paths, you should either use single quotes to delimit your strings or escape your backslash by doubling it like "some\\path".

Loading Compass Plugins

Compass relies on the ruby require mechanism to load other libraries of code. To load a compass-compatible plugin, simply require it at the top of your configuration file. If you used the -r option to access another library at project creation time, this will already be set up for you.

Example:

require 'ninesixty'
require 'susy'

Overriding Configuration Settings

When using the compass command line, configuration options that you set on the command line will override the corresponding settings in your configuration file.

Inspecting Configuration Settings passed via the Command Line

When using the compass command line, configuration options that you set on the command line can be inspected within the configuration file. For instance, if you set the environment:

$ compass compile -e production --force

Then you can inspect the value like so:

output_style = (environment == :production) ? :compressed : :expanded

Values that are not set on the CLI will be nil even though they will have a default value later on.

Configuration Properties

Configuration Functions

add_import_path – Call this function to add a path to the list of sass import paths for your compass project. E.g.:

add_import_path "/Users/chris/work/shared_sass"

asset_host – Pass this function a block of code that will define the asset host url to be used. The block must return a string that starts with a protocol (E.g. http). The block will be passed the root-relative url of the asset. For example, this picks one of four asset hosts numbered 0-3, depending on the name of the asset:

asset_host do |asset|
  "http://assets%d.example.com" % (asset.hash % 4)
end

By default there is no asset host used. When relative_assets is true the asset host configuration is ignored.

asset_cache_buster – Pass this function a block of code that defines the cache buster strategy to be used. The block must return nil, a string or a hash. If the returned value is a hash the values of :path and/or :query is used to generate a cache busted path to the asset. If a string value is returned, it is added as a query string. The returned values for query strings must not include the starting ?.

The block will be passed the root-relative url of the asset. If the block accepts two arguments, it will also be passed a path that points to the asset on disk — which may or may not exist.

# Increment the deploy_version before every release to force cache busting.
deploy_version = 1
asset_cache_buster do |http_path, file|
  if file
    file.mtime.strftime("%s")
  else
    "v=#{deploy_version}"
  end
end

Busting the cache via path:

asset_cache_buster do |path, file|
  if file
    pathname = Pathname.new(path)
    modified_time = file.mtime.strftime("%s")
    new_path = "%s/%s-%s%s" % [pathname.dirname, pathname.basename(pathname.extname), modified_time, pathname.extname]

    {:path => new_path, :query => nil}
  end
end

To disable the asset cache buster:

asset_cache_buster :none

add_asset_collection - Each asset collection is a bundle of sass stylesheets, images, and fonts that potentially have their own URL location, cache busting, and host requirements. Unlike compass extensions, asset collections don't require the publisher to package their assets in any particular way and the image and fonts don't need to be bundled or delivered as part of your projects's assets. This makes asset collections ideal for integrating with drupal extensions, bower, and other front-end packagers.

To add an asset collection to your project, call add_asset_collection and pass the asset collection configuration options to describe where to find the assets and how the urls for them are constructed. The following options are allowed:

• :root_path - The absolute path to the asset collection.
• :root_dir - A relative path to the asset collection from the project path.
• :http_path - Web root location of assets in this collection. Starts with '/'.
• :http_dir - Web root location of assets in this collection. Relative to the project's http_path.
• :sass_dir - Sass directory to be added to the Sass import paths. Relative to the :root_path or :root_dir.
• :fonts_dir - Directory of fonts to be added to the font look up path. Relative to the :root_path or :root_dir.
• :http_fonts_dir - Where to find fonts on the webserver relative to the http_path or http_dir. Defaults to <http_path>/<fonts_dir>. Can be overridden by setting :http_fonts_path.
• :http_fonts_path - Where to find fonts on the webserver.
• :images_dir - Directory of images to be added to the image look up path. Relative to the :root_path or :root_dir.
• :http_images_dir - Where to find images on the webserver relative to the http_path or http_dir. Defaults to <http_path>/<images_dir>. Can be overridden by setting :http_images_path.
• :http_images_path - Where to find images on the webserver.
• :asset_host - A string starting with 'http://' for a single host, or a lambda or proc that will compute the asset host for assets in this collection. If :http_dir is set instead of http_path, this defaults to the project's asset_host.
• :asset_cache_buster - A string, :none, or or a lambda or proc that will compute the cache_buster for assets in this collection. If :http_dir is set instead of http_path, this defaults to the project's asset_cache_buster.

It is required to pass either :root_path or :root_dir and :http_path or :http_dir.

Example:

add_asset_collection(
  :root_dir => "other/asset_collection",
  :http_dir => "ext-assets",
  :images_dir => "img",
  :sass_dir => "scss"
  :asset_cache_buster => proc {|url_path, file|
    {:path => "/#{Digest::MD5.file(file)}#{File.extname(url_path)}"} },
  :asset_host => proc {|url_path|
    "http://assets#{url_path.hash % 4 + 1}.other-asset-server.com" }
)

watch -- React to changes to arbitrary files within your project. Can be invoked more than once. Example:

watch "images/**/*" do |project_dir, relative_path|
  if File.exists?(File.join(project_dir, relative_path))
    puts "File size of #{relative_path} is: #{File.size(File.join(project_dir, relative_path))}"
  end
end

This code will be called if the file is added, updated, or removed. Be sure to check for existence to avoid crashing the watcher in the case where the file has been removed.

Callbacks

on_sprite_saved -- Pass this function a block of code that gets executed after a sprite is saved to disk. The block will be passed the filename. Can be invoked more then once. Example:

on_sprite_saved do |filename|
  post_process(filename) if File.exists?(filename)
end

on_sprite_generated -- Pass this function a block of code that gets executed after a sprite is generated but before its saved to disk. The block will be passed an instance of ChunkyPNG::Image. Can be invoked more then once. Example:

on_sprite_generated do |sprite_data|
  sprite_data.metadata['Caption'] = "This Image is © My Company 2011"
end

on_stylesheet_saved -- Pass this function a block of code that gets executed after a stylesheet is processed. The block will be passed the filename. Can be invoked more then once. Example:

on_stylesheet_saved do |filename|
  Growl.notify {
     self.message = "#{File.basename(filename)} updated!"
     self.icon = '/path/to/success.jpg'
   }
end

on_stylesheet_error -- Pass this function a block of code that gets executed if a stylesheet has an error while processing. The block will be passed the filename and the error message. Can be invoked more then once. Example:

on_stylesheet_error do |filename, message|
  Growl.notify {
    self.message = "#{File.basename(filename)}: #{message}"
    self.icon = '/path/to/fail.jpg'
    sticky!
  }
end