Drupal Twig コーディングスタンダード 日本語訳

今回は Drupal コーディングスタンダード日本語訳シリーズの一環で Twig のコーディングスタンダードを翻訳してみたいと思います。

翻訳に入る前にまずは手短に Twig のご紹介をしてみたいと思います。

Twig とは

Twig は PHPTemplate に代わる形で Drupal 8 のデフォルトとなったテンプレートエンジンです。 特徴として、 1) 簡潔でわかりやすい文法、 2) テンプレート継承などの高度機能などがあげられます。

Python の Django フレームワークや Jinja2 テンプレートエンジンをもとにしているようで、文法はそれらとほぼ同じ形になっています。 汎用のテンプレートらしい感じになっており、 PHP らしさはまったくありません。

ちなみに twig とは英語で「小さな枝」「小枝」を表す単語だそうです。 名前の由来は・・・わかりません。

公式サイトはこちら。

• Twig - The flexible, fast, and secure PHP template engine
• Documentation - Twig

では、以下、 Drupal.org の Twig テンプレートコーディングスタンダードを日本語に翻訳してご紹介できればと思います。 最終更新日が 2014 年 03 月 26 日のバージョンをもとにしてます。

Twig コーディングスタンダード 日本語訳

Twig コーディングスタンダードの大部分はそのドキュメントとあわせて Twig ウェブサイト上で見ることができます。 このページの内容は Twig コードを Drupal 向けに書く方法を理解するときに役立ちます。

preprocess 関数のドキュメントスタンダードもあわせてご覧ください。

DocBlock

Twig テンプレートの先頭にある docblock は PHPTemplate ファイル（ http://drupal.org/coding-standards/docs#templates 参照）の先頭の dockblock と共通にすること。 ただし、 twig のコメントマーカ {# と #} で docblock 全体を囲うこと。

デフォルトの themeable な出力を提供するテンプレートの場合はテンプレートの dockblock には @ingroup themeable だけを含めるようにしましょう。 デフォルトの出力を上書きするテーマの場合は @ingroup themeable 行は含めないこと。

{#
/**
 * @file
 * リージョンのためのデフォルトテーマ実装
 *
 * 利用可能な変数:
 * - content: このリージョンのコンテンツ 典型はブロック
 * - attributes: 残りの HTML アトリビュート 次のものを含む：
 *   - class: CSS を通して文脈に応じたスタイに使われる HTML クラス
 *
 * @see template_preprocess_region()
 *
 * @ingroup themeable
 */
#}

DocBlock 内の変数

twig テンプレートの docblock の変数は名前だけで参照すること。 Twig で出力を表す {{ や }} で囲ったりせず、 PHP で変数を表す $ を前につけたりもしないこと。 「その他の変数」という独立したセクションは設けないこと。

テンプレートの先頭のドキュメントを変換するための良いルールは次のとおりです：

• まず Drupal 7 用のドキュメントを用意しましょう。
• 「その他の変数」というタイトルの変数セクションがあれば、そのタイトルとその上の余分な行を削除しましょう。
• preprocess から削除された変数は Twig ドキュメントからも削除しましょう。
• 有益な変数が Twig ドキュメントに書かれていない場合はドキュメントに書き足しましょう。
• D7 のドキュメントにおいて改善できるポイントや冗長さを削減できる部分があれば、改善しましょう。

DocBlock 内の変数定義

テンプレートファイルに対して作業をする人が変数の型について気にしなくてもいいように、変数定義には型（配列、オブジェクト、文字列）に関する情報は含めないようにしましょう。 Twig テンプレートで出力されるものはすべて最終的には文字列となって出力されます。

DocBlock 内でインラインで参照される変数

変数が文章の中でインラインで参照されるときには、変数名はシングルクォートで囲いましょう。次のようにします：

    フィールド変数：ノードにアタッチされたフィールドインスタンスのそれぞれに対応する変数が定義されます。
    たとえば、 'node.body' は 'body' になります。
    フィールドの生の値にアクセスする必要があるときは、開発者やテーマ作成者はこれらの変数を使うことを強くおすすめします。
    その他の場合は、要求されたフィールドの言語を明示的に指定する必要があります。
    たとえば 'node.body.en' とします。
    こうすることで、それまでに適用されているあらゆる言語の交渉ルールをオーバーライドすることになります。

式

Twig の式は通常の PHP 式にとてもよく似ており、 Drupal では変数が表示できるかどうかのチェック、ループや新しい変数のセットなどに最もよく使われています。

式：変数が表示できるかどうかのチェック

表示すべき値があるときだけマークアップコンテナを表示したい、というケースがときどきあります。 Drupal でこれをする方法は次のとおりです：

{% if foo %}
  
{{ foo }}
{% endif %}

変数が利用可能かどうかを判断するために 'is defined' を変数の後につける必要はありません。

式：ループの利用　

Twig は for ループを使います。 Drupal では foreach ループを使う機会がよくあります。 配列のキーを使う必要がない場合、ループはこのようになるでしょう：

    {% for item in navigation %}
      
{{ item.caption }}
    {% endfor %}

場合によっては、ループの中でキーとバリューの両方を必要とすることがありますが、 Twig の for ループでそれを実現するためのループ構文はこのようになるでしょう：

{% for value, key in items %}
  
{{ value }}
{% endfor %}

式：変数の設定

式はテンプレートファイルの中で直接変数をセットするために使うこともできます。

{% text = '!person は Twig のファンです'|t('!person', user) %}

HTML アトリビュート

Drupal 8 の HTML アトリビュートは drillable なものです。 これは、 {{ attributes }} を書けばすべてをまとめて表示することもできるし、各アトリビュートを個別に表示することもできる、ということを意味します。 こんな感じです：

    

      {{ content }}
    

HTML タグの中でアトリビュートを個別に表示することにした場合でも、その 最後には完全な {{ attributes }} を含めるべきです。 こうすると、モジュールで追加されたアトリビュートもきちんと表示されるようになります。

Drupal のコアでは、 class アトリビュートだけを特別に表示し、その他のものはすべて {{ attributes }} の一部として表示することになるでしょう。 その理由は、フロントエンドの開発者が class をカンタンに追加できるべきだからです。 class="" アトリビュートをテンプレートファイルの中で直接書くことによって、ドキュメントを読んだり Drupal にはプリプロセスレイヤーがあることを理解したりせずとも HTML ・ CSS に馴染みのある人たちが class を追加する正しい方法を見て理解することができます。

    

      {{ content }}
    

より上級のテーマ開発者はプリプロセスの中で class を追加したり個別に表示された class をテンプレートから削除したりすることもできます。 class をテンプレートから削除すると、要素が class を持たないときに空の class="" アトリビュートが表示されてしまうのを防ぐことができます。

空白の制御

Twig には空白を制御する機能が 2 つあります。 {% spaceless %} タグとダッシュ文字（ - ）です。 {% spaceless %} タグは HTML タグと Twig タグの間の空白をすべて削除します。 一方ダッシュ文字 - は、 Twig タグの内側に置かれた場合にそのタグの外側の - がある方向の空白をすべて削除します。 spaceless タグはより一般的で「内向き」です。 ダッシュはより緻密でその効果は「外向き」です。

{% spaceless %}

{% splaceless %} タグはタグや文の間のテキストでない空白をすべて削除したいときに便利です。 これはコードブロックの中で空白を制御する際に Drupal コアにおいて好んで使われています。 しかしながら、 {% spaceless %} を使用する度に余分なインデント階層が生まれます。

「ダッシュ」（ - ）空白修正子

ダッシュ修正子 - はより緻密な（そしてときには混乱を招く）方法で、タグの片側あるいは両側の空白を選択的に削除します。 ダッシュ修正子 - を使わなくてはならないケースはそう多くはありません。 コードは {% spaceless %} タグを使ったときの方がたいていは読みやすくなります。 一般的にコアの中で、空白の制御機能はそう多くは使われません。

使い方の例：

{% if block.show %}

  {% spaceless %}
    {% if block.title %}
      {{ title_prefix }}
      
{{ block.title }}
      {{ title_suffix }}
    {% endif %}
  {% endspaceless %}
  {% if block.content %}
    
{{ block.content }}
  {% elseif block.description %}
    
{{ block.description }}
  {% endif %}

{% endif %}

インデントされたマークアップは次のようになるでしょう：

  
タイトル
  
コンテンツ

後ほど、すべてを twig に変換し、成果物である Twig コードとそこから生成されるマークアップを見てみた後に、空白の制御の使用については再度決断する必要があるかもしれません。 当面の私たちのゴールは、 Twig を新たに使いはじめた人、 Twig の組み込みツールを使う頻度の少ない人を混乱させないことです。

スペースと空白制御子、 spaceless タグを Twig テンプレートで使うときの決まりごと：

• 読みやすさのために空白を削除できるならそうしましょう。例：
  • <div{{ attributes }}> attributes の前の空白は削除する
  • class="no {{ attributes.class}} no" クラスに関しては、周りのスペースを削除したり空白制御子を置いたりするのは絶対にやめましょう
• 空白を見やすい形で削除できない場合は spaceless タグの使用を考慮しましょう。例：
  • コマンド（ {% if foo %} など）の周りでは spaceless タグを使いましょう
  • コメント（ {# これはコメントです #} ）の周りでは spaceless タグを使いましょう

ファイルの末尾の改行に関する警告

Git は twig ファイルの末尾に改行があることを要求します。 これがテストを壊す場合やテンプレート出力において望ましくない場合があるかもしれません。 これを変えるおすすめの方法はこちら：

• パスする必要があるテストは変更しましょう。
• もしくは twig テンプレートタグを末尾に追加してください。

Drupal コアコントリビュートの中でなければ、改行文字を削除してもよいでしょう。

フィルタ

t や url のような Drupal の最も一般的な関数のうちいくつかは twig テンプレートの中でフィルタとして使用することができます。 フィルタはパイプ文字 | で使うことができます。

twig テンプレートの中で t() 関数をフィルタとして使うにはこのようにします。

    {{ 'Original'|t }}

パイプの両隣には空白を置かないようにしてください。

コメント

すべてのコメントは twig コメントインジケータ {# と #} で囲います。

一行コメントの場合は同じ行にコメントインジケータを置きます。

  {# 後でレンダリングするのでここではコメントとリンクは隠しておきます。 #}
  {% hide(content.comments) %}
  {% hide(content.links) %}
  {{ content }}

2 行以上のコメントの場合は別の行にコメントインジケータを置きます。 コメントは行の文字数が 80 字未満となるように折り返します。

{#
  これは非常に長いコメントで、長さが 1 行を超えます。これは非常に長い
  コメントで、長さが 1 行を超えます。これは非常に長いコメントで、長さ
  が 1 行を超えます。
#}

  {{ content }}

以上です。 いかがだったでしょうか？

冒頭で述べられているように、 Twig の基本的なルールやスタンダードは Twig 公式ドキュメントの方に書かれているので、ここで紹介されているのは Twig の書き方ルールのごく一部、といった感じのようです。

Drupal 8 では twig がデフォルトになるとのことですので、テーマ開発者はもちろんバックエンド開発者もぜひ押さえておきたいところですね。 Twig の公式ドキュメントの方も見てみるとうまく使えば使うほどおいしいところがいろいろ出てきそうな感じですので、ぜひマスターしていきたいと思います。