[Compass] 超訳 Configuration Reference

by

CSSのメタ言語、Sassベースで作られた便利なフレームワーク、それがCompass。

Compassの設定ファイルはRubyファイルです。
これはRubyを知っていれば色々なことが出来るということなんですが、逆にRubyを知らないと取っつきにくさがあると思います。
それで損をしてしまうのはあまりに勿体無いので、オレオレリファレンスを書いてみました！

※この記事は完全な和訳ではありません。

公式 Configuration Reference

基本的な書き方

文法はRubyと同じです。

Comapssの設定項目（プロパティ）はとてもたくさんありますが、
その殆どは項目に対して設定したい値を代入するという書き方をします。

css_dir = "stylesheets"

代入できる値には「型（タイプ）」があります。
プロパティによって設定できる型というのは決められているので、それと同じ型の値を代入しなければなりません。

  • 文字列（String）
    URLやディレクトリ名などのテキスト。必ずシングルクォートかダブルクォートで囲います。
    例：”stylesheets”
  • シンボル（Symbol）
    シンボル型はコロンが先頭についたテキストです。使えるシンボルはプロパティによって制限されています。
    例： :expanded
  • 真偽値（Boolean）
    trueまたはfalse。　はい＝true　いいえ=false　という感じです。

設定項目によっては以下２つのタイプも使えます。

  • 配列（Array）
    配列は値の１つずつをカンマで区切って角括弧の中に並べたものです。
    例：　[“one”, “two”, “three”]
  • ハッシュ（Hash）
    ハッシュは名前と値を結びつけたものです。中括弧の中にカンマ区切りで並べ、名前と値の間に=>を書きます。
    例：{:foo => “aaa”, :bar => “zzz”}

コメント

コメントを書く時は先頭に # をつけます。
先頭に#がある行はコメントとしてみなされますが、扱いは１行単位なので
複数行に渡って書く場合はすべての行頭に#を付ける必要があります。

公式の方には書いてないんですが、ブロックコメントの=begin～=endも使えます。

=begin
endまでの間になら
何行でも
書けます
マジ便利
=end

Windowsユーザー向けの注意

ダブルクォートで囲まれた文字列型の中に存在するバックスラッシュ記号 (\)は特殊文字になるので、
“some\\path”　のようにバックスラッシュをもう１つ増やしてエスケープするか、シングルクォートを使ってください。

設定項目

動作に影響するもの

設定用プロパティ 型（タイプ） 説明 コマンドライン 影響先
project_type Symbol :stand_aloneまたは:railsが設定できます。
デフォルトは:stand_alone。
この設定はRuby on Railsプロジェクトで使うときに設定するものなので、通常は必要ありません。		 プロジェクト
environment Symbol 環境設定。 デフォルトは:productionで、他に:developmentがあります。
これは、制作環境とリリース環境が違う場合に、各環境向けの設定をこのオプションを変えるだけで切り替えることができるようにするものです。		 -e
–environment		 設定
output_style Symbol コンパイルしたCSSのスタイル設定。Sassのそれと同じです。
:nested
:expanded
:compact
:compressed 		-s
–output-style		 コンパイラ
line_comments Boolean コンパイル後のCSSに、そのスタイルがどのsassファイルのどの行に書いてあるかを出力する。
デフォルトではproductionモードではfalse、development モードではtrueになっているが、output_styleがcompressedの場合は出力しません。		 –no-line-comments コンパイラ
disable_warnings Boolean trueにすると警告を表示しなくなります -q
–quiet		 ログ
sass_options Hash Sassコンパイラ向けのオプション。オプションについての詳しくはこちら。
例： {:cache => false} 		-s
–output-style		 コンパイラ
preferred_syntax Symbol Sassファイルで使用している記法。
:scssまたは:sass。
デフォルトは:scss		 コンパイラ
additional_import_paths Array of Strings プロジェクト外またはsass_dir外にあるSassファイルをimportして使いたい場合は、この設定に配列または文字列でディレクトリまでのパスを設定する。
先頭にディレクトリセパレータを付けなかった場合はproject_path + 設定したパス になります。
add_import_path 関数も使えます。		 -I コンパイラ

URL関連

URLに関する設定は優先順位があります。
imagesを例にすると
images_dir < http_images_dir < http_images_path となり、優先順位が高いものがある場合は低いものの設定が無視されます。

設定用プロパティ 型（タイプ） 説明 コマンドライン 影響先
project_path String プロジェクトのルートパス。
ディレクトリやパスの設定で、このproject_pathをルートとして使います。
デフォルトはドライブ名まで含んだフルパスで、config.rbが配置されている場所がプロジェクトのルートになります。
:stand_aloneモードの時は特に設定しなくてもいいですが、
ルートとしたい位置がconfig.rbと同じディレクトリではない時は設定する必要があります。 		  path設定全体
http_path String プロジェクトがWebサーバーで動く時のパス(URL)。
デフォルトは"/"		   http_path設定全体
relative_assets Boolean Compassのヘルパー関数がCSSから対象へのURLを生成する時に、相対パスと絶対パスどちらにするかの設定。
これをtrueにするとCompassがCSSファイルからの相対パスを計算します。		 –relative-assets image-url()
設定用プロパティ 型（タイプ） 説明 コマンドライン 影響先
sass_dir String Sassファイルがあるディレクトリ。
project_pathからの相対指定をする。
デフォルトは"sass" 		–sass-dir コンパイラ
sass_path String Sassファイルがあるディレクトリへのフルパス。
デフォルトは<project_path>/<sass_dir>		   コンパイラ
css_dir String コンパイルされたCSSファイルを配置するディレクトリ。
project_pathからの相対指定をする。
デフォルトは "stylesheets"		 –css-dir stylesheet-url()
css_path String コンパイルされたCSSファイルを配置するディレクトリのフルパス。
デフォルトは<project_path>/<css_dir>		   stylesheet-url()
http_stylesheets_dir String WebサーバーでのCSSファイルを置くディレクトリ。   stylesheet-url()
http_stylesheets_path String WebサーバーでのCSSファイルを置くディレクトリへのフルパス。
デフォルトはhttp_path + "/" + css_dir		   stylesheet-url()
images_dir String 画像を置いているディレクトリ。
project_pathからの相対指定をする。
デフォルトは"images"		 –images-dir image-url()
images_path String 画像を置いているディレクトリへのフルパス。
デフォルトは<project_path>/<images_dir>		   image-url()
http_images_dir String Webサーバーでの画像を置くディレクトリ。
デフォルトはhttp_path + "/" + images_dir		   image-url()
http_images_path String Webサーバーでの画像を置くディレクトリへのフルパス。
デフォルトはhttp_path + "/" + images_dir		   image-url()
generated_images_dir String 生成する画像の保存先ディレクトリ。
project_pathからの相対指定をする。
デフォルトはimages_dir		   generated-image-url()
generated_images_path String 生成する画像の保存先ディレクトリへのフルパス。
デフォルトは<project_path>/<generated_images_dir>		   generated-image-url()
http_generated_images_path String Webサーバー上の生成画像の保存先ディレクトリ。
デフォルトはhttp_path + "/" + generated_images_dir		   generated-image-url()
sprite-map()
javascripts_dir String JavaScriptファイルのディレクトリ。
project_pathからの相対指定をする。
デフォルトは"javascripts"		 –javascripts-dir  
javascripts_path String JavaScriptファイルディレクトリへのフルパス。
デフォルトは<project_path>/<javascripts_dir>		    
http_javascripts_dir String WebサーバーでのJavaScriptファイルディレクトリ。
デフォルトはhttp_path + "/" + javascripts_dir		    
http_javascripts_path String TWebサーバーでのJavaScriptファイルディレクトリのフルパス。
デフォルトはhttp_path + "/" + javascripts_dir		    
fonts_dir String フォントファイルのディレクトリ。
:stand_aloneでのデフォルトは<css_dir>/fonts
Railsプロジェクトでは"public/fonts" 		–fonts-dir font-url()
fonts_path String フォントファイルディレクトリへのフルパス。
デフォルトは<project_path>/<fonts_dir>		   font-url()
http_fonts_path String Webサーバーでのフォントファイルディレクトリへのフルパス。   font-url()
http_fonts_dir String Webサーバーでのフォントファイルディレクトリ。   font-url()

Sprite画像の自動生成用

この機能については別の記事で解説します。

設定用プロパティ 型（タイプ） 説明 コマンドライン
sprite_engine Symbol デフォルトは:chunky_png sprite
chunky_png_options Hash デフォルトは{:compression => Zlib::BEST_COMPRESSION}
より詳しい情報はchunky_pngのwiki を見てください。		  
sprite_load_path Array デフォルトは[images_path]  

コマンドラインでのオーバーライド

コマンドラインを使用してコンパイルするとき、対応するオプション（ハイフンつけたもの）がある設定についてはオーバーライドすることができます。


compass compile -s compressed --force

config.rbを上書きする訳ではなくて、その時だけ有効な値をコンパイラへ渡す感じです。

コマンドライン経由で渡される設定の検査

コマンドライン経由で渡された値もコンフィグファイル内で条件文などを使って検査することができます。

たとえば、environmentはコマンドオプションが用意されているので、
config.rbを編集することなく開発用と本番用を切り替えることができます。

output_styleなんかは特に、開発用では未圧縮の方がいいけど本番では圧縮したいものです。
そこで設定で三項演算を使って次のようにしておけば、

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

次のようなコマンドを叩くだけで出力スタイルを切り替えることができるようになります。


compass compile -e production --force

※–forceはキャッシュを無視して強制的に再出力するオプション

Compass 用プラグインの読み込み

config.rbファイルではRubyの require が使用できます。
requireを使ってCompass用のプラグインや、独自に作成した設定用rbファイルを読み込むことができます。
-r オプションを使ってプロジェクトを作成した場合は、これが自動的に設定されます。

#common.rb
STAGING= 'http://stg.example.com'
PRODUCT = 'http://example.com'

#config.rb
require 'common'
http_path = (environment == :production) ? PRODUCT : STAGING

コンフィグ関数

add_import_path

この関数を使うとSassのimportに任意のパスを追加することができます。

たとえば、次のように引数を渡して実行すると

add_import_path "/Users/chris/work/shared_sass"

設定したディレクトリにあるSassファイルを@importで使えるようになります。

@import "_myreset";

カンマ区切りで複数渡せます。

add_import_path "/foo", "bar", "/hoge"

asset_host

ブロックコードをこの関数に渡すと、引数にimage-urlを使用している画像のパスが代入されます。
ブロックは必ずhttpなどのプロトコルで始まる文字列を返さなければいけません。
返された文字列は画像のルートURLになります。
http_pathを設定している場合でも無視してさらにその前へ追加されます。

config.rb:

http_path = "http://example.com"
images_dir = "images"

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

SCSS:


background:image-url('bg.jpg');

コンパイル結果：

background: url('http://assets2.example.com/http://example.com/images/bg.jpg?1348940923');

なお、この関数は relative_assets がtrueの場合は実行されません。

asset_cache_buster

画像のキャッシュを消すために、image-urlの第三引数をfalseにしているか、
relative_assets が false になっている場合に有効。

asset_cache_buster do |http_path, real_path|
#ここに処理を書く
end

この関数にブロックコードを渡すと引数で画像のパスが２種類渡されます。
http_path → http_path + images_dir + image-url($path)
real_path →　#<File:*>

戻り値として返した文字列が対象のURL末尾に追加されます。

asset_cache_buster do |http_path, real_path|
 "hoge"
end

#=>background: url('http://example.com/images/bg.jpg?hoge');

Rubyの関数を使ってファイルのタイムスタンプをつける例

asset_cache_buster do |http_path, real_path|
  if File.exists?(real_path)
    File.mtime(real_path).strftime("%s")
  end
end
#=>background: url('http://example.com/images/bg.jpg?1348940923');

タイムスタンプをファイル名に含める例

asset_cache_buster do |http_path, real_path|
  if File.exists?(real_path)
    pathname = Pathname.new(http_path)
    modified_time = File.mtime(real_path).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
#=>background: url('http://example.com/images/bg-1348940923.jpg');

noneシンボルを渡すと relative_assets = false にしたのと同じように無効となります。

asset_cache_buster :none

watch

プロジェクト内の任意のファイルへの変更に反応します。
変更に応じて複数回呼び出すことができます。

watch "stylesheets/*" do |project_dir, relative_path|
  puts "project_dir  -> " + project_dir
  puts "relative_path  -> " + relative_path
  end
end

プロジェクト内のディレクトリであればなんでもおｋ。
以下は画像ディレクトリ内のファイルの変更があった時に、ファイルパスとファイルサイズをログに表示するサンプルです。
関数で何か操作をする場合は、ファイルが削除された時のクラッシュを避ける為にファイルの存在を確認するようにしてください。

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

コールバック

コールバックに設定したブロックはコンパイラの処理に応じて実行されます。

on_sprite_saved

スプライト画像が保存されたときに１度だけ実行されます。
引数にはファイルパスが渡されます。

on_sprite_saved do |filename|
  size = File.size(filename) / 1000
  puts "filesize:#{size}kb"
end

on_sprite_generated

スプライト画像が生成されるとき、保存前に１度だけ実行されます。
引数にはChunkyPNG::Imageのインスタンスが渡されます。

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

on_stylesheet_saved

スタイルシートが保存されたときに１度だけ実行されます。
引数にはスタイルシートのパスが渡されます。

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

on_stylesheet_error

スタイルシートの保存中、エラーが発生したときに実行されます。
引数にはSassファイル名とエラーメッセージが渡されます。

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

おまけ：Compass Configurable Variables

設定用変数まとめたscssファイルをgistに置いときました。

「[Compass] 超訳 Configuration Reference」への6件のフィードバック

  1. ピンバック: Sublime Text 2 で Sass/compass のコンパイルができるパッケージ 『Compass』 « shilog
  2. ピンバック: Sass + Compass の基本導入と設定ファイル config.rb について | WP-D
  3. ピンバック: [Sass + Compass] config.rbを、制作環境でないところに置く時のポイント
  4. ピンバック: Compass: config.rb を詳しくみる | deadwood
  5. ピンバック: Windows環境でSass開発環境を構築する（応用編） | Web Kid Blog
  6. ピンバック: SCSSとCompassをSublime Text2で使ってみる | cly7796.net

コメントを残す

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。