Twig テンプレート

テンプレート

このCMSではテンプレートエンジンとして Twig を採用しています。主にHTMLを出力するために利用しますが、メール本文のテンプレートとして利用する場合もあります。

利用している Twig のバージョンは 3系です。 Twigの拡張機能を利用してこのCMSで追加したフィルターや関数があります。それらの説明文には ME拡張という表示をしています。 Twigについて詳しく知りたい方はTwigの公式ドキュメントをご覧ください。
Twigの公式ドキュメント：https://twig.symfony.com/

ファイル

Twig テンプレートファイルの拡張子は .twig を推奨します。ファイル名は default.twig のようになります。
※ コンテンツタイプ名から自動的にテンプレート名が決定される場合の拡張子は .twig に固定されています。
ファイルの文字コードは UTF-8 です。

基本構文

Twig は {{ }} と {% %} という２種類の記号を使って Twig の変数や文を記述します。変数の内容を出力する場合は {{ }} を使います。if文や for文などの制御構造は {% %} を使います。

Twig テンプレートの例：

<!DOCTYPE html>
<html>
<head>
  <title>My Webpage</title>
</head>
<body>
<ul id="navigation">
  {% for item in navigation %}
  <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
  {% endfor %}
</ul>

<h1>My Webpage</h1>
{{ a_variable }}
</body>
</html>

変数

変数のプロパティには . （ドット）を使ってアクセスできます。

ページ名を出力する例：

{{ page.name }}

上記の例では page 変数の name プロパティを出力しています。 PHPでは $page->name や $page['name'] と記述しますが、Twigの場合はオブジェクトでも配列でも page.name と記述することができます。また、メソッドを呼び出す場合にもドットでアクセスできます。

下記のように記述しても、上記と同じ内容にアクセスできます。

{{ page['name'] }}

配列のキーにハイフン（マイナス記号）を含む場合には減算と解釈されてしまうため、次のように attribute() 関数を使用してアクセスします。

{{ attribute(foo, 'data-foo') }}

変数の確認

テンプレート作成中に、現在のコンテキストで利用できる変数名を確認したい場合は、一時的に次のような記述をテンプレートに追加することで確認することができます。

{% for key,var in _context %}
  {{ key }}<br>
{% endfor %}

変数の内容を詳細に確認したい場合は、基本設定ファイル（system/config/settings.php）の debug 項目を 1 にセットした上で次のように dump() 関数を使うことでその変数の内容を表示させることができます。

{{ dump(field) }}

グローバル変数

次の変数はテンプレートに常にセットされます。

変数名	説明
_site	テーブルコンテンツのサイト設定に登録した内容がセットされます。
_self	現在のテンプレート名。例：cms/views/outputs/text.twig
_context	コンテキスト変数。現在のコンテキストでセットされている変数が配列にまとめられています。
_charset	文字コード。例：UTF-8

変数を定義する

変数を定義するには set タグを使います。
例：

{% set foo = 'foo' %}
{% set foo = [1, 2] %}
{% set foo = {'foo': 'bar'} %}

この例では、文字列、配列、連想配列をセットしています。

テキストの塊をキャプチャーしたい場合は次のように set と endset タグを使います。

{% set foo %}
<div id="pagination">
  ...
</div>
{% endset %}

フィルター

変数はフィルター（モディファイア）を使って変更を加えることができます。Twigに組み込まれたフィルターとこのCMSで拡張されたフィルターがあります。フィルターは | (パイプ)で連結して連続的に指定することができます。
例：

{{ name|striptags|title }}

上記の例では、name 変数からHTMLタグを取り除いて、単語の先頭を大文字に変換しています。

フィルターは引数を指定できるものもあります。次のように () を使って引数を渡すことができます。
例：

{{ list|join(', ') }}

上記の例では、list 配列の要素を ', ' で結合しています。

filterタグを使うと、そのタグ内のコードにフィルターを適用することができます。

{% filter upper %}
This text becomes uppercase
{% endfilter %}

関数

Twigに組み込まれた関数とこのCMSで拡張された関数があります。関数は関数名の後に () をつけて実行します。
例：

{% for i in range(0, 3) %}
{{ i }},
{% endfor %}

この例では range 関数で「0, 1, 2, 3」という数値を生成しています。

名前付き引数

関数の引数は名前を付けて呼び出すこともできます。テンプレートを保守する際に読みやすくする目的で活用できます。
例：

{% for i in range(low=1, high=10, step=2) %}
{{ i }},
{% endfor %}

twigのinclude関数は5つの引数（template, variables, with_context, ignore_missing, sandboxed）を持っています。このような場合に、順番に引数を指定したくない場合にも名前付き引数を活用できます。次の例では3つ目の引数のみ名前付き引数で指定しています。
例：

{{ include('template.twig', {'field':childFieldConfig}, ignore_missing = true) }}

この例では、１つ目と２つ目の引数は順番どおりで、３つ目の引数をスキップして4つ目の引数を名前付き引数で指定しています。

Twigのコメントは {# #} を使います。コメントの内容は出力されません。
例：

{# これはコメントです #}

複数行コメントも可能です。
例：

{# note: disabled template because we no longer use this
{% for user in users %}
  ...
{% endfor %}
#}

他のテンプレートを呼び出す

テンプレートの中から他のテンプレートをインクルードすることができます。次のように指定するとテーマディレクトリの cms/views/partials/breadcrumbs.twig ファイルを呼び出すことができます。呼び出された breadcrumbs.twig テンプレート内では呼び出し元の変数が有効になります。
cmsテーマ内のファイルをインクルードする例：

{{ include('cms/views/partials/breadcrumbs.twig') }}

公開サイト用テーマ内のファイルをインクルードする例：

{{ include('@site/partials/footer.twig', ignore_missing = true) }}

パスを @site から指定すると、現在選択しているテーマの views ディレクトリからのパスとして指定することができます。実際のテーマディレクトリ名を指定すると、テーマディレクトリ名をリネームした場合に参照できなくなってしまいます。公開サイト用テーマ内のファイルを参照する場合は @site から始まるパスを指定するようにしてください。

テンプレート継承

Twigはテンプレートを継承することができます。HTML全体を記述したベーステンプレートを用意して、子テンプレートで上書きできる部分を block タグで定義することができます。継承した子テンプレートでは上書きしたい block 内だけ記述すれば良いので、効率的にテンプレートを扱うことができます。

ベーステンプレートの例（default.twig）：

<!DOCTYPE html>
<html>
<head>
  {% block head %}
  <link rel="stylesheet" href="style.css" />
  <title>{% block title %}{% endblock %} - My Webpage</title>
  {% endblock %}
</head>
<body>
<div id="content">{% block content %}{% endblock %}</div>
<div id="footer">
  {% block footer %}
  © Copyright 2011 by <a href="http://domain.invalid/">you</a>.
  {% endblock %}
</div>
</body>
</html>

block タグで head, title, content, footer を定義しています。

ベーステンプレートを継承する子テンプレートの例：

{% extends '@site/base/default.twig' %}

{% block title %}Index{% endblock %}
{% block head %}
{{ parent() }}
<style type="text/css">
  .important { color: #336699; }
</style>
{% endblock %}
{% block content %}
<h1>Index</h1>
<p class="important">
  Welcome to my awesome homepage.
</p>
{% endblock %}

extends タグで default.twig を継承することを宣言しています。この例では、title, head, content ブロック内のみを記述しています。子テンプレートで記述しなかった footer ブロックはベーステンプレートの内容が出力されます。

子テンプレートのブロック内で親テンプレートの内容を出力したい場合は次のように parent() 関数を使います。

{{ parent() }}

HTMLエスケープ

変数の内容を出力する場合はデフォルトでHTMLエスケープが実行されます。次のように特別な指定をしていない場合はHTML特殊文字はエスケープ処理されます。

{{ user.username }}

コンテキストに応じたエスケープが必要な場合は次のように指定できます。

{{ user.username|e('js') }}
{{ user.username|e('css') }}
{{ user.username|e('url') }}
{{ user.username|e('html_attr') }}

マクロ

マクロを使うと、HTML部品を出力する機能を一般的なプログラミング言語の関数のように定義することができます。

マクロを定義する例（common/macros.twig ※製品には含まれていません）：

{% macro error_box(msg = '') %}
<div class="alert alert-error">{{ msg }}</div>
{% endmacro %}

マクロを利用する例：

{% import "common/macros.twig" as macros %}

{{ macros.error_box(form.errors.MESSAGE) }}

importタグでマクロを読み込んで as で macros というエイリアスを指定しています。 macros.error_box() に引数を与えて呼び出すことで、引数に応じたHTML部品を出力できます。

このHTMLファイルについて

このHTMLファイルは Twig Team の著作物を複製・改変したドキュメントが含まれています。

著作物：https://twig.symfony.com/
著作権：Copyright (c) 2009-2020 by the Twig Team
ライセンス：https://twig.symfony.com/license

テンプレート

ファイル

基本構文

変数

変数の確認

グローバル変数

変数を定義する

フィルター

関数

名前付き引数

コメント

他のテンプレートを呼び出す

テンプレート継承

HTMLエスケープ

マクロ

このHTMLファイルについて

2.2 マニュアル

基本情報

インストール

コンテンツ

フィールド

テンプレート

アクション・クエリ