Home | Symfony2Doc »リファレンスドキュメント »Twig テンプレートのフォーム関数と変数

ご注意

Symfony2日本語翻訳ドキュメントは内容が古くなっております。公式サイトの英語ドキュメントを参照してください。

Twig テンプレートのフォーム関数と変数

テンプレートでフォームを扱うとき、二つの強力な道具があります。

  • フォームの各部を出力する:ref:`関数 <reference-form-twig-functions>
  • フィールドについてのあらゆる情報が取得できる:ref:変数 <twig-reference-form-variables>

関数はフィールドを出力するのによく使われます。一方、変数は普通はそれほど使いませんが、フィールドのラベル・ID属性・エラー、その他フィールドに関するあらゆる情報を利用することができ、とても強力です。

Form 出力関数

このマニュアルではフォームを出力するためのありとあらゆる Twig 関数を掲載しています。様々な関数がありますが、それぞれが違うフォーム部品の出力に対応しています。(例えば、ラベル、エラーメッセージ、ウィジェットなど)

form(view, variables)

フォーム全体のHTMLを出力します。

{# フォームを出力し、submitメソッドを変更します #}
{{ form(form, {'method': 'GET'}) }}

主にアプリケーションのプロトタイプを作成するときや、カスタムフォームテーマを利用するときに使います。フォームを出力するときにもっと柔軟性がほしいなら、フォームの各部品を出力する他のヘルパーを利用した方が良いでしょう。

{{ form_start(form) }}
    {{ form_errors(form) }}

    {{ form_row(form.name) }}
    {{ form_row(form.dueDate) }}

    {{ form_row(form.submit, { 'label': '送信' }) }}
{{ form_end(form) }}

form_start(view, variables)

フォームの開始タグを出力します。設定されたメソッドとアクションを考慮します。 フォームがファイルアップロードを含んでいれば、適切な enctype も出力します。

{# 開始タグを出力し、送信メソッドを変更します #}
{{ form_start(form, {'method': 'GET'}) }}

form_end(view, variables)

フォームの終了タグを出力します。

{{ form_end(form) }}

render_rest をfalseにセットしない限り、 form_rest() も出力します。

{# 未出力のフィールドを出力しません #}
{{ form_end(form, {'render_rest': false}) }}

form_label(view, label, variables)

指定したフィールドのラベルを出力します。第二引数として、このフィールドに出力したいラベルを渡すこともできます。

{{ form_label(form.name) }}

{# 下記の二つの書き方は同じ意味になります #}
{{ form_label(form.name, 'お名前', {'label_attr': {'class': 'foo'}}) }}
{{ form_label(form.name, null, {'label': 'お名前', 'label_attr': {'class': 'foo'}}) }}

variables について詳しくは “フォーム変数の詳細” を参照してください。

form_errors(view)

指定したフィールドのエラーを出力します。

{{ form_errors(form.name) }}

{# グローバルなエラーを出力します #}
{{ form_errors(form) }}

form_widget(view, variables)

指定したフィールドの HTML ウィジェットを出力します。 フォーム全体やフォームの集合に対して使用すると、それに含まれている全フィールドの各行を出力します。

{# ウィジェットを出力し、 "foo" クラスを追加します #}
{{ form_widget(form.name, {'attr': {'class': 'foo'}}) }}

form_widget の第二引数は変数の配列です。 一番よく使われるのは attr で、HTMLウィジェットに追加する属性の配列です。フィールドのタイプによってはテンプレートに関係する他の変数も渡すことができます。 attributes は一度に多数のフィールドを出力するときでも(たとえば、 form_widget(form) としたとき)再帰しません。

variables についての詳細は “フォーム変数の詳細” を参照してください。

form_row(view, variables)

指定したフィールドの「行」、つまりラベル・エラーメッセージ・ウィジェットの組み合わさったものを出力します。

{# 行を出力しますが、ラベルはfooに変更します #}
{{ form_row(form.name, {'label': 'foo'}) }}

form_row の第二引数は変数の配列です。 上の例のように、 Symfony で提供されているテンプレートではラベルのみ上書きすることができます。

variables について詳細は “フォーム変数の詳細” を参照してください。

form_rest(view, variables)

指定したフォームについてまだ出力されていない全てのフィールドを出力します。 hidden フィールドや、出力し忘れたフィールドを出力してくれるので、いつもこのヘルパーを入れておくと便利です。

{{ form_rest(form) }}

form_enctype(view)

Note

このヘルパーは Symfony 2.3 で廃止され、 Symfony 3.0 で削除される予定です。代わりに form_start() を使用してください。

フォームに少なくとも一つのファイルアップロードフィールドがあるとき、このヘルパーは必要な enctype="multipart/form-data" フォーム属性を出力します。 form タグにいつでもこれを含めておくと便利です。

<form action="{{ path('form_submit') }}" method="post" {{ form_enctype(form) }}>

Form テストリファレンス

テストは、 is と一緒に使うことで条件を作ることができます。 詳しくは Twig ドキュメント を参照してください。

selectedchoice(selected_value)

このテストは、現在の選択肢が selected_value に等しいかどうかを調べます。 selected_value が配列のときには、現在の選択肢が selected_value の配列の中に含まれているかどうかを調べます。

<option {% if choice is selectedchoice(value) %} selected="selected"{% endif %} ...>

フォーム変数の詳細

Tip

全てのフォーム変数の一覧は Form 変数リファレンス にあります。

上に出てきたほとんど全ての Twig 関数では、最後の引数はフォームの一部分を出力する時に使われる変数の配列です。 例えば、次のコードはフィールドのウィジェットを出力しますが、特別なクラスを含めるように変更されています。

{# ウィジェットを出力し、 "foo" クラスを追加します #}
{{ form_widget(form.name, { 'attr': {'class': 'foo'} }) }}

この変数の配列の目的(どこから来て何をするのか)はわかりにくいかもしれませんが、信じられないぐらい強力です。 フォームのどの部分を出力するときでも、その部分を出力するブロックはたくさんの変数を使います。 デフォルトでは、ブロックは form_div_layout.html.twig の中に書かれています。

一例として form_label を見てみましょう。

{% block form_label %}
    {% if not compound %}
        {% set label_attr = label_attr|merge({'for': id}) %}
    {% endif %}
    {% if required %}
        {% set label_attr = label_attr|merge({'class': (label_attr.class|default('') ~ ' required')|trim}) %}
    {% endif %}
    {% if label is empty %}
        {% set label = name|humanize %}
    {% endif %}
    <label{% for attrname, attrvalue in label_attr %} {{ attrname }}="{{ attrvalue }}"{% endfor %}>{{ label|trans({}, translation_domain) }}</label>
{% endblock form_label %}

このブロックはいくつか変数を使っています。すなわち、 compound, label_attr, required, label, name そして translation_domain です。 変数はフォームレンダリング機構によって利用可能になっています。しかし、もっと重要なことは、この変数は開発者が form_label を呼び出すときに(上の例はラベルを出力する時のものなので)上書きすることができるということです。

上書きできる変数はフォームのどの部分を出力しようとしているか(例えば、ラベルかウィジェットか)、あるいはどのフィールドを出力しようとしているか(例えば、 choice ウィジェットには expanded という追加オプションがあります)によって異なります。 form_div_layout.html.twig には全てのオプションが網羅されています。

Tip

内部的には、変数は Form コンポーネントがフォームの各ノードについて buildViewfinishView を呼び出したときに FormView によって利用可能になります。 特定のフィールドについてどんなビュー変数が利用できるのか知りたいときは、そのフォームフィールド(および親のフィールド)のソースコードを調べ、上の二つのメソッドを見てください。

Note

フォーム全体(あるいは埋め込みフォーム全体)を一度に出力する場合は、 variables 引数はそのフォーム自身のみに適用され、フォームの子要素には適用されません。 つまり、下のサンプルコードでは、 “foo” クラス属性はフィールドには適用され ません

{# 機能しません。変数は再帰しないため。 #}
{{ form_widget(form, { 'attr': {'class': 'foo'} }) }}

Form 変数リファレンス

下の変数は全てのフィールドタイプに共通です。フィールドタイプの中にはもっと多くの変数があるものもあり、特定のフィールドのみに有効な変数もあります。

テンプレートに form 変数が含まれていて name フィールドの変数にアクセスしたいとき、 FormView オブジェクトの vars プロパティを使うことによりアクセスできます。

  • Twig
    <label for="{{ form.name.vars.id }}"
        class="{{ form.name.vars.required ? 'required' : '' }}">
        {{ form.name.vars.label }}
    </label>
    
  • PHP
    <label for="<?php echo $view['form']->get('name')->vars['id'] ?>"
        class="<?php echo $view['form']->get('name')->vars['required'] ? 'required' : '' ?>">
        <?php echo $view['form']->get('name')->vars['label'] ?>
    </label>
    

New in version 2.3: methodaction は Symfony2.3 で追加されました。

New in version 2.4: submitted 変数は Symfony2.4 で追加されました。

変数名 | 使い方
form 現在の FormView インスタンス
id 出力される id HTML属性
name フィールド名 (例えば title) ただし name HTML属性ではありません。 name HTML属性は full_name です。
full_name 出力される name HTML属性
errors 個別のフィールドについての全てのエラーの配列d (たとえば form.title.errors のように) form.errors はフォームが正しいかどうかを調べるのに利用することはできません。 グローバルなエラーしか返さないので、 個別のフィールドにはエラーがある可能性がある からです。代わりに valid を使ってください。
submitted フォームが送信されたかどうか true 又は false で返します。
valid フォーム全体にエラーが無いかどうか true 又は false で返します。
value 出力時に利用される値(大抵の場合は value HTML属性)
read_only true であれば readonly="readonly" がフィールドに追加されます。
disabled true であれば disabled="disabled" がフィールドに追加されます。
required true であれば required 属性がフィールドに追加され、HTML5のバリデーションを 有効にします。さらに、 required クラスがラベルに追加されます。
max_length エレメントに maxlength 属性を追加します。(2.5で廃止され、3.0で削除予定です。 代わりに attr[maxlength] を使ってください)
pattern エレメントに pattern 属性を追加します。(2.5で廃止され、3.0で削除予定です。 代わりに attr[pattern] を使ってください)
label 出力されるラベル文字列。
multipart もし true なら、 form_enctypeenctype="multipart/form-data" を出力 します。親のフォームだけに適用されます。
attr フィールドに HTML 属性として出力される key-value 配列。
compound フィールドが実際は子フィールドを保持しているかどうか。(例えば choice フィールド があるときに、それがチェックボックスの集合で成り立っているかどうか。
block_prefixes 親タイプ全ての名前の配列
translation_domain 現在のフォームの翻訳ドメイン
cache_key キャッシュで利用される一意なキー
data タイプの変換された(ノーマライズされた)データ
method 現在のフォームのメソッド(GET, POSTなど)
action 現在のフォームのアクション
blog comments powered by Disqus