Skip to content

SmallCage Manual (ja)

Jump to bottom Edit New page
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オブジェクトよりも下げることができます。

Add a custom footer
Add a custom sidebar
Clone this wiki locally