レイアウト

レイアウト機能はテンプレート間で共有する, 個別ページを囲むための共通 HTML の使用を可能にします。PHP 開発経験のある開発者であればページ毎に, その上部と下部に "header" や "footer" への参照をもつ使い方をしたことがあるでしょう。 Ruby の世界と Middleman では逆のアプローチを取ります。 "layout" は "header" や "footer" 両方を含むことで個別ページのコンテンツを囲みます。

最も基本的なレイアウトは共有コンテンツとそのテンプレートの内容を配置する yield を含みます。

ERB を使ったレイアウトの例です:

<html>
<head>
  <title>私のサイト</title>
</head>
<body>
  <%= yield %>
</body>
</html>

ERB で書かれたページテンプレートが与えられます:

<h1>Hello World</h1>

組み合わされた最終的な HTML 出力は次のように:

<html>
<head>
  <title>私のサイト</title>
</head>
<body>
  <h1>Hello World</h1>
</body>
</html>

ファイル拡張子とパーサに関しては, レイアウト機能はビルドプロセスの中でテンプレートと異なる機能をもっているので, 正しい拡張子を与えるよう注意する必要があります。次がその理由です:

セクション毎に異なるテンプレートを集めるような場合, ファイル拡張子は重要です。例えば, レイアウトファイルを layout.html.erb と名付けることで, 言語パーサにこのファイルは erb として扱えと命じることになり, html に変換されます。

ある意味で, 拡張子を右から左に解釈することは, ファイルが左端の拡張子形式のファイルとしてパース処理されることを知らせます。例の場合, ファイルが与えられた時に erb から html に変換し, ファイルをビルドします。

テンプレートとは異なり, レイアウトは html にレンダリングされません。レイアウトのファイル名の左端の拡張子に .html を与えた場合, ビルド時のエラーの原因になります。したがって, 例えば layout.erb のような形式で拡張子をつける必要があります。

カスタムレイアウト

デフォルトでは, Middleman はそのサイトのすべてのページに同じレイアウトを適用します。複数のレイアウトを使い, どのページがどのレイアウトを使うのか指定したい場合があります。例えば, それぞれ独自のレイアウトをもつ "公開" サイトと "admin" サイトがあるような場合です。

デフォルトのレイアウトは source フォルダの中で "layout" と名付けられ, 使用するテンプレート言語の拡張子を持ちます。デフォルトでは layout.erb です。あなたが作るレイアウトは source/layouts フォルダに置かれます。

admin 用の新しいレイアウトを作るには, source/layouts フォルダに新たに "admin.erb" ファイルを追加します。次の内容だったとします:

<html>
<head>
  <title>Admin Area</title>
</head>
<body>
  <%= yield %>
</body>
</html>

次に, どのページがこのレイアウトを使用するのか指定する必要があります。次の 2 つの方法で指定することができます。ページの大きなグループにこのレイアウトを適用したい場合, config.rb で "page" コマンドを使うことができます。 source フォルダの中に "admin" フォルダがある状態で "admin" の中のテンプレートは admin レイアウトを使うとしましょう。config.rb は次のようになります:

page "/admin/*", :layout => "admin"

ページのパスにワイルドカードを使うことで admin フォルダ以下のすべてのページが admin レイアウトを使うように指定しています。

ページで直接指定することもできます。例えば, source フォルダに login.html.erb が置かれているが, admin レイアウトを適用したい場合です。ページテンプレートの例として次を使います。

<h1>Login</h1>
<form>
  <input type="email">
  <input type="password">
  <input type="submit">
</form>

この特別なページには次のようにカスタムレイアウトを指定できます:

page "/login.html", :layout => "admin"

これは login ページが admin レイアウトを使うように指定しています。 config.rb ですべて指定する代わりに, Frontmatter を使ってテンプレートのページ毎にレイアウトを指定することもできます。 login.html.erb ページ自身にレイアウトを指定する例です。

---
layout: admin
---

<h1>Login</h1>
<form>
  <input type="email">
  <input type="password">
  <input type="submit">
</form>

入れ子レイアウト

入れ子レイアウトはレイアウトの積み重ねを作成できます。この機能を理解する最も簡単なユースケースは middleman-blog 拡張です。ブログ記事はサイト全体のコンテンツの部分集合です。ブログ記事によって追加された内容と構造を含みますが, 最終的にサイト全体の構造によって囲まれる必要があります (header, footer など) 。

シンプルなデフォルトのレイアウトは次のようになります:

<html>
  <body>
    <header>ヘッダ</header>
    <%= yield %>
    <footer>フッタ</footer>
  </body>
</html>

blog 記事が blog/my-article.html.markdown に置かれているとします。すべての blog 記事がデフォルトの layout に代わり article_layout を使うように指定します。 config.rb を編集:

activate :blog do |blog|
  blog.layout = "article_layout"
end

# または:

page "blog/*", :layout => :article_layout

layouts/article_layout.erb は次のようになります:

<% wrap_layout :layout do %>
  <article>
    <%= yield %>
  </article>
<% end %>

Note: Haml や Slim では次のように等号を使う必要があります:

= wrap_layout :layout do

通常のレイアウトと同じように, yield はテンプレートの出力内容が配置される場所です。この例では次の出力になります:

<html>
  <body>
    <header>ヘッダ</header>
    <article>
      <!-- テンプレート/ブログ記事の内容 -->
    </article>
    <footer>フッタ</footer>
  </body>
</html>

完全なレイアウト無効化

いくつかの場合では, まったくレイアウトを使いたくない場合があります。 config.rb でデフォルトのレイアウトを無効化することで対応できます:

set :layout, false

# もしくは個別のファイルで:
page '/foo.html', :layout => false