SmallCage Manual (ja)

KOSEKI Kengo edited this page Feb 13, 2014 · 16 revisions

SmallCageとは

SmallCageは静的なサイトを高速に作成・更新するためのアプリケーションです。

前身となるプロジェクトを経て、2007年から現在のruby版の開発に着手しました。

ディレクトリ構成

SmallCageのディレクトリ構成は以下の通りです。

  • /_smc/ …… テンプレートやヘルパを格納するディレクトリ。
  • /_smc/templates/ …… テンプレート用ディレクトリ。
  • /_smc/helpers/ …… ヘルパクラス用ディレクトリ。
  • /_smc/filters/ …… フィルタ用ディレクトリ。
  • /_smc/ tmp/ …… 一時ファイル用ディレクトリ

_smcディレクトリの外では、以下のファイル名が特別扱いされます。

  • *.smc …… 生成するページのソースに当たるYAML形式のファイルです。
  • _dir.smc …… カレントディレクトリの情報を記述するYAML形式のファイルです。
  • _local.smc …… _dir.smcの値を上書きします。ローカル環境用の設定ファイルです。

この中で必須なのはドキュメントルート直下の_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.

この例では、テンプレートが無いので、生成されるファイルの中身は空になります。

smcファイル

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>
<p><%= date %></p>
<ul>
<%- site.each do |s| -%><li><%= s %></li><%- end -%>
</ul>
<%= body %>

ただし、以下の名前はSmallCageによって特別扱いされます。

  • template …… テンプレート名
  • dirs …… ディレクトリ情報
  • uri / uri.smc …… 出力するファイル/smcファイルのURI
  • path / path.smc …… 出力するファイル/smcファイルのパス
  • strings …… smcファイルに書かれた文字列の配列
  • arrays …… smcファイルに書かれた配列の配列
  • body …… strings[0]のエイリアス

URIテンプレート(後述)を使う場合、更に以下の値を利用します。

  • uris …… URIテンプレートのレンダリング結果(配列)
  • cursor …… urisの中の現在位置

template

/_smc/templates/以下に置かれたテンプレートの名前を指定します。例。

template: free
→ /_smc/templates/free.rhtml

template指定を省略すると /_smc/templates/default.rhtml を使用します。

dirs

ディレクトリについての情報を格納した配列が設定されます。配列の要素は出力するファイルの親ディレクトリに対応します。dirs[0]には、ドキュメントルートの情報が格納されています。dirs[-1]には、smcファイルが置かれたディレクトリの情報が格納されます。

_dir.smcという名前のファイルで、dirsの要素に値を足すことができます。

uri

出力するファイルのURIが設定されます。また、uri.smcという名前でsmcファイルのURIを取得できます。例。

smcファイル /abc/def/index.html.smc
uri /abc/def/index.html
uri.smc /abc/def/index.html.smc

path

出力するファイルのパスが、Pathnameオブジェクトで設定されます。uri と同様に path.smc で smc ファイルを指す Pathname オブジェクトを取得できます。例。

ドキュメントルート: /home/smc/project 
smcファイル: /abc/def/index.html.smc
path: /home/smc/project/abc/def/index.html (Pathname)
path.smc: /home/smc/project/abc/def/index.html.smc (Pathname)

strings

文字列の配列。YAML文書の1つがスカラー値だった場合に、stringsに追加されます。

arrays

配列の配列。YAML文書の1つが配列だった場合に、arraysに追加されます。

body

strings[0]のエイリアスです。最初の文字列は、bodyでアクセスできます。

smcオブジェクト

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.smcから_dirファイルは生成されません。

_dir.smcは、パンくずリストを表示したい時に最もよく使います。また、ドキュメントルートの_dir.smcは、サイト全体の設定に使います。

テンプレートからは、dirsという名前でディレクトリ情報の配列を取得できます。dirs[0]はドキュメントルートのディレクトリ情報です。

_local.smcファイル

_local.smcファイルの機能は、_dir.smcファイルと全く同じです。_dir.smcファイルの内容を_local.smcが上書きします。_local.smcは環境毎に異なる設定を行いたい場合に使います。

例えば本番環境の設定を_dir.smcに書き、作業環境では_local.smcを使って上書きする、といった具合に利用します。

_local.smcはバージョン管理の共有リポジトリにコミットしてはいけません。

_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をインクルードできます。

URIテンプレート

URIテンプレートを使うと、1つのsmcファイルから複数のファイルを出力したり、出力するファイル名を動的に変えたりすることができます。

URIテンプレートは /_smc/templates/(templatename).uri.rhtml のような名前で保存します。

詳しくは、Publish Multi Files (ja)を参照してください。

Helper methods

ヘルパーメソッドは、/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オブジェクトよりも下げることができます。

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.