SmallCage Manual (ja)
SmallCageは静的なサイトを高速に作成・更新するためのアプリケーションです。
前身となるプロジェクトを経て、2007年から現在のruby版の開発に着手しました。
SmallCageのディレクトリ構成は以下の通りです。
- /_smc/ …… テンプレートやヘルパを格納するディレクトリ。
- templates/ …… テンプレート用ディレクトリ。
- helpers/ …… ヘルパクラス用ディレクトリ。
- filters/ …… フィルタ用ディレクトリ。
- tmp/ …… 一時ファイル用ディレクトリ
必須なのはドキュメントルート直下の_smcディレクトリだけです。_smcディレクトリはドキュメントルートを探すための目印です。_smcディレクトリの中身は空でも動きます。
$ mkdir htdocs $ mkdir htdocs/_smc $ smc update htdocs -- 0 files. 0.003 sec. 0.000 sec/file. $ touch htdocs/index.html.smc $ smc update htdocs A /index.html -- 1 files. 0.005 sec. 0.005 sec/file.
テンプレートが無いので、生成されるファイルの中身は空になります。
SmallCageは、(filename).smc という名前のファイルから、(filename)を生成するアプリケーションです。例えば、
index.html.smc → index.htmlという生成を行います。smcファイルはYAML形式で記述します。
--- | <h2>SmallCageの使い方</h2> <p>SmallCageを使うとウェブサイトを簡単に構築できます。</p>
また、次のように構造化されている場合もあります。
template: gallery image: photo1.jpg date: 2010-12-31 title: my picture site: - http://www.example.com/abc - http://www.example.com/def - http://www.example.com/ghi --- | <p>私の撮った写真です。</p>
Mappingのキー(上の例のimage、date、title、site)は自由に設定できます。キーは、テンプレートからその名前で参照されます。
<h1><%= title %></h1> <ul> <%- site.each do |s| -%><li><%= s %></li><%- end -%> </ul> <%= body %>
ただし、以下の名前はSmallCageによって特別扱いされます。
- template …… テンプレート名
- dirs …… ディレクトリ情報
- uri / uri.smc …… 出力するファイル/smcファイルのURI
- file / file.smc …… 出力するファイル/smcファイルのパス
- strings …… smcファイルに書かれた文字列の配列
- arrays …… smcファイルに書かれた配列の配列
- body ……
strings[0]
のエイリアス
URIテンプレート(後述)を使う場合、更に以下の値を利用します。
- uris …… URIテンプレートのレンダリング結果(配列)
- cursor …… urisの中の現在位置
/_smc/templates/以下に置かれたテンプレートの名前を指定します。例。
template: free → /_smc/templates/free.rhtml
template指定を省略すると /_smc/templates/default.rhtml を使用します。
ディレクトリについての情報を格納した配列が設定されます。配列の要素は出力するファイルの親ディレクトリに対応します。dirs[0]
には、ドキュメントルートの情報が格納されています。dirs[-1]
には、smcファイルが置かれたディレクトリの情報が格納されます。
dir.smc という名前のファイルで、独自のディレクトリ情報を追加できます。例えばドキュメントルートのdir.smcは、サイト全体の設定を書くのに使うことができます。
出力するファイルのURIが設定されます。また、uri.smcという名前でsmcファイルのURIを取得できます。例。
smcファイル /abc/def/index.html.smc uri /abc/def/index.html uri.smc /abc/def/index.html.smc
出力するファイルのパスが、Pathnameオブジェクトで設定されます。uriと同様にfile.smc で smcファイルを指すPathnameオブジェクトを取得できます。例。
ドキュメントルート: /home/smc/project smcファイル: /abc/def/index.html.smc file: /home/smc/project/abc/def/index.html (Pathname) file.smc: /home/smc/project/abc/def/index.html.smc (Pathname)
文字列の配列。YAML文書の1つがスカラー値だった場合に、stringsに追加されます。
配列の配列。YAML文書の1つが配列だった場合に、arraysに追加されます。
strings[0]
のエイリアスです。最初の文字列は、bodyでアクセスできます。
SmallCageは、smcファイルを読み込んでsmcオブジェクトを作成します。smcオブジェクトはRubyのHashインスタンスです。
‘---
’で区切られたYAML文書のうち、Mapping型のものは全てHashに格納されます。キーが重複した場合は、後から定義されたもので上書きされます。
Scalar型の文書は、smcオブジェクトのstringsというキーに格納されます。これは文字列の配列です。
Sequence型の文書は、arraysというキーに格納されます。これは配列の配列です。
例。以下のsmcファイルがあった場合、
template: default title: This is the page! --- | <p>abc</p> --- - a - b - c --- | <p>something difference</p> --- - x - y - z --- site: http://example.com
以下のsmcオブジェクトに変換されます。
@obj = { "template" => "default", "title" => "This is the page!", "site" => "http://example.com", "strings" => [ "<p>abc</p>", "<p>something difference</p>" ], "arrays" => [ ["a", "b", "c"], ["x", "y", "z"] ], "body" => "<p>abc</p>" # bodyはstrings[0]のエイリアスです。 }
テンプレートから単純な名前でアクセスできるようにすることが、この変換の目的です。
_dir.smc
ファイルは、カレントディレクトリの情報を定義するファイルです。_dir.smc
から_dir
ファイルは生成されません。
_dirs.smc
は、パンくずリストを表示したい時に最もよく使います。また、ドキュメントルートの_dirs.smc
は、サイト全体の設定に使います。
テンプレートからは、dirs
という名前でディレクトリ情報の配列を取得できます。dirs[0]
はドキュメントルートのディレクトリ情報です。
_local.smc
ファイルの機能は、_dir.smc
ファイルと全く同じです。_dir.smc
ファイルの内容を_local.smc
が上書きします。_local.smc
は環境毎に異なる設定を行いたい場合に使います。
例えば本番環境の設定を_dir.smc
に書き、作業環境では_local.smc
を使って上書きする、といった具合に利用します。
_local.smc
はバージョン管理の共有リポジトリにコミットしてはいけません。
_smc
ディレクトリが置かれた場所がドキュメントルートになります。smc update
を実行した際、親ディレクトリをさかのぼって_smc
ディレクトリが置かれたディレクトリが見つからない場合は、エラーになります。
テンプレートは、/_smc/templates/に置かれたERB形式のファイルです。拡張子は.rhtmlとします。smcファイルから、templateという名前でテンプレートを指定できます。
template: sample
は/_smc/templates/sample.rhtml を使います。templateを省略するとdefault.rhtmlが使用されます。
smcオブジェクトは、テンプレートから@objという名前でアクセスできます。
<%= @obj["image"] %>
@objは省略できます。上の例は、
<%= image %>
と書くことができます。出力中のファイルのURIを表示したいなら、
<%= uri %>
です(uriは上で説明した特別扱いされる名前の1つです)。smcファイルが置かれたディレクトリのURIは、
<%= dirs.last["uri"] %>
で出力できます。
テンプレートも単純な名前でインクルードすることができます。例えば、
<%= header %> <%= body %> <%= footer %>
と書くことで、bodyの前後にheader.rhtmlとfooter.rhtmlをインクルードできます。
ヘルパーメソッドは、/smc/helpers/*_helper.rbで定義されたメソッドです。テンプレートからメソッド名でアクセスすることができます。例えば /_smc/helpers/sitehelper.rb に
module SmallCage module SiteHelper def current_date Time.now.strftime("%Y-%m-%d") end end end
とあった場合、テンプレートで
<%= current_date %>
とすると、現在日時を2010-12-31といった形式で出力します。
ヘルパーメソッドは、SmallCageモジュール内のファイル名をキャメルケースにしたモジュールに記述します。
テンプレートで使用する名前には、以下のような優先順位があります。
1. テンプレート内で定義されたローカル変数、メソッド等
名前がテンプレート内で定義されていればその名前を参照します。
2. ヘルパメソッド
その名前が未定義だった場合、ヘルパメソッドを探します。
3. smcオブジェクト
ヘルパメソッドが無ければ、smcオブジェクトのキーを探します。
4. テンプレート名
smcオブジェクトのキーが見つからなければ、最後にその名前のテンプレートを探します。
この優先順位により、テンプレートをsmcファイルから上書きできます。例えば、
<%= copyright %>
が通常はcopyright.rhtmlをインクルードしている場合に、特定のsmcファイルだけ
copyright: (c) 2001-2020 Special Page Inc.
のようにして別の内容を書き出すことができます。また、ヘルパメソッドでsmcオブジェクトの値を上書きできます。上の例でcopyrightという名前のヘルパーメソッドがあった場合は、テンプレートの有無やsmcファイルの内容に関わらず、ヘルパーメソッドが呼ばれます。
ヘルパメソッドの呼び出し部分を別のテンプレートに書くことで、ヘルパの優先順位をsmcオブジェクトよりも下げることができます。