reference/forms/twig_reference 翻訳

77web · 77web · commit 4ee55601064b · 2014-04-19T21:45:52.000+09:00
diff --git a/reference/forms/twig_reference.rst b/reference/forms/twig_reference.rst
@@ -1,5 +1,341 @@
-このページの翻訳はまだ行われていません。
-========================================
+.. index::
+   single: Forms; Twig form function reference
+
+Twig テンプレートのフォーム関数と変数
+==================================================
+
+テンプレートでフォームを扱うとき、二つの強力な道具があります。
+
+* フォームの各部を出力する:ref:`関数 <reference-form-twig-functions>
+* フィールドについてのあらゆる情報が取得できる:ref:`変数 <twig-reference-form-variables>`
+
+関数はフィールドを出力するのによく使われます。一方、変数は普通はそれほど使いませんが、フィールドのラベル・ID属性・エラー、その他フィールドに関するあらゆる情報を利用することができ、とても強力です。
+
+.. _reference-form-twig-functions:
+
+Form 出力関数
+------------------------
+
+このマニュアルではフォームを出力するためのありとあらゆる Twig 関数を掲載しています。様々な関数がありますが、それぞれが違うフォーム部品の出力に対応しています。（例えば、ラベル、エラーメッセージ、ウィジェットなど）
+
+.. _reference-forms-twig-form:
+
+form(view, variables)
+---------------------
+
+フォーム全体のHTMLを出力します。
+
+.. code-block:: jinja
+
+    {# フォームを出力し、submitメソッドを変更します #}
+    {{ form(form, {'method': 'GET'}) }}
+
+主にアプリケーションのプロトタイプを作成するときや、カスタムフォームテーマを利用するときに使います。フォームを出力するときにもっと柔軟性がほしいなら、フォームの各部品を出力する他のヘルパーを利用した方が良いでしょう。
+
+.. code-block:: jinja
+
+    {{ form_start(form) }}
+        {{ form_errors(form) }}
+
+        {{ form_row(form.name) }}
+        {{ form_row(form.dueDate) }}
+
+        {{ form_row(form.submit, { 'label': '送信' }) }}
+    {{ form_end(form) }}
+
+.. _reference-forms-twig-start:
+
+form_start(view, variables)
+---------------------------
+
+フォームの開始タグを出力します。設定されたメソッドとアクションを考慮します。
+フォームがファイルアップロードを含んでいれば、適切な ``enctype`` も出力します。
+
+.. code-block:: jinja
+
+    {# 開始タグを出力し、送信メソッドを変更します #}
+    {{ form_start(form, {'method': 'GET'}) }}
+
+.. _reference-forms-twig-end:
+
+form_end(view, variables)
+-------------------------
+
+フォームの終了タグを出力します。
+
+.. code-block:: jinja
+
+    {{ form_end(form) }}
+
+``render_rest`` をfalseにセットしない限り、 ``form_rest()`` も出力します。
+
+.. code-block:: jinja
+
+    {# 未出力のフィールドを出力しません #}
+    {{ form_end(form, {'render_rest': false}) }}
+
+.. _reference-forms-twig-label:
+
+form_label(view, label, variables)
+----------------------------------
+
+指定したフィールドのラベルを出力します。第二引数として、このフィールドに出力したいラベルを渡すこともできます。
+
+.. code-block:: jinja
+
+    {{ form_label(form.name) }}
+
+    {# 下記の二つの書き方は同じ意味になります #}
+    {{ form_label(form.name, 'お名前', {'label_attr': {'class': 'foo'}}) }}
+    {{ form_label(form.name, null, {'label': 'お名前', 'label_attr': {'class': 'foo'}}) }}
+
+``variables`` について詳しくは ":ref:`twig-reference-form-variables`" を参照してください。
+
+.. _reference-forms-twig-errors:
+
+form_errors(view)
+-----------------
+
+指定したフィールドのエラーを出力します。
+
+.. code-block:: jinja
+
+    {{ form_errors(form.name) }}
+
+    {# グローバルなエラーを出力します #}
+    {{ form_errors(form) }}
+
+.. _reference-forms-twig-widget:
+
+form_widget(view, variables)
+----------------------------
+
+指定したフィールドの HTML ウィジェットを出力します。
+フォーム全体やフォームの集合に対して使用すると、それに含まれている全フィールドの各行を出力します。
+
+.. code-block:: jinja
+
+    {# ウィジェットを出力し、 "foo" クラスを追加します #}
+    {{ form_widget(form.name, {'attr': {'class': 'foo'}}) }}
+
+``form_widget`` の第二引数は変数の配列です。
+一番よく使われるのは ``attr`` で、HTMLウィジェットに追加する属性の配列です。フィールドのタイプによってはテンプレートに関係する他の変数も渡すことができます。
+``attributes`` は一度に多数のフィールドを出力するときでも（たとえば、 ``form_widget(form)`` としたとき）再帰しません。
+
+``variables`` についての詳細は ":ref:`twig-reference-form-variables`" を参照してください。
+
+.. _reference-forms-twig-row:
+
+form_row(view, variables)
+-------------------------
+
+指定したフィールドの「行」、つまりラベル・エラーメッセージ・ウィジェットの組み合わさったものを出力します。
+
+.. code-block:: jinja
+
+    {# 行を出力しますが、ラベルはfooに変更します #}
+    {{ form_row(form.name, {'label': 'foo'}) }}
+
+``form_row`` の第二引数は変数の配列です。
+上の例のように、 Symfony で提供されているテンプレートではラベルのみ上書きすることができます。
+
+``variables`` について詳細は ":ref:`twig-reference-form-variables`" を参照してください。
+
+.. _reference-forms-twig-rest:
+
+form_rest(view, variables)
+--------------------------
+
+指定したフォームについてまだ出力されていない全てのフィールドを出力します。
+hidden フィールドや、出力し忘れたフィールドを出力してくれるので、いつもこのヘルパーを入れておくと便利です。
+
+.. code-block:: jinja
+
+    {{ form_rest(form) }}
+
+.. _reference-forms-twig-enctype:
+
+form_enctype(view)
+------------------
+
+.. note::
+
+    このヘルパーは Symfony 2.3 で廃止され、 Symfony 3.0 で削除される予定です。代わりに ``form_start()`` を使用してください。
+
+フォームに少なくとも一つのファイルアップロードフィールドがあるとき、このヘルパーは必要な ``enctype="multipart/form-data"`` フォーム属性を出力します。 form タグにいつでもこれを含めておくと便利です。
+
+.. code-block:: html+jinja
+
+    <form action="{{ path('form_submit') }}" method="post" {{ form_enctype(form) }}>
+
+Form テストリファレンス
+--------------------------
+
+テストは、 ``is`` と一緒に使うことで条件を作ることができます。
+詳しくは `Twig ドキュメント`_ を参照してください。
+
+.. _form-twig-selectedchoice:
+
+selectedchoice(selected_value)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+このテストは、現在の選択肢が ``selected_value`` に等しいかどうかを調べます。 ``selected_value`` が配列のときには、現在の選択肢が ``selected_value`` の配列の中に含まれているかどうかを調べます。
+
+.. code-block:: jinja
+
+    <option {% if choice is selectedchoice(value) %} selected="selected"{% endif %} ...>
+
+.. _`twig-reference-form-variables`:
+
+フォーム変数の詳細
+-------------------------
+
+.. tip::
+
+    全てのフォーム変数の一覧は :ref:`reference-form-twig-variables` にあります。
+
+上に出てきたほとんど全ての Twig 関数では、最後の引数はフォームの一部分を出力する時に使われる変数の配列です。
+例えば、次のコードはフィールドのウィジェットを出力しますが、特別なクラスを含めるように変更されています。
+
+.. code-block:: jinja
+
+    {# ウィジェットを出力し、 "foo" クラスを追加します #}
+    {{ form_widget(form.name, { 'attr': {'class': 'foo'} }) }}
+
+この変数の配列の目的（どこから来て何をするのか）はわかりにくいかもしれませんが、信じられないぐらい強力です。
+フォームのどの部分を出力するときでも、その部分を出力するブロックはたくさんの変数を使います。
+デフォルトでは、ブロックは `form_div_layout.html.twig`_ の中に書かれています。
+
+一例として ``form_label`` を見てみましょう。
+
+.. code-block:: jinja
+
+    {% 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 コンポーネントがフォームの各ノードについて ``buildView`` や ``finishView``  を呼び出したときに ``FormView`` によって利用可能になります。
+    特定のフィールドについてどんなビュー変数が利用できるのか知りたいときは、そのフォームフィールド（および親のフィールド）のソースコードを調べ、上の二つのメソッドを見てください。
+
+.. note::
+
+    フォーム全体（あるいは埋め込みフォーム全体）を一度に出力する場合は、 ``variables`` 引数はそのフォーム自身のみに適用され、フォームの子要素には適用されません。
+    つまり、下のサンプルコードでは、 "foo" クラス属性はフィールドには適用され **ません** 。
+
+    .. code-block:: jinja
+
+        {# 機能しません。変数は再帰しないため。 #}
+        {{ form_widget(form, { 'attr': {'class': 'foo'} }) }}
+
+.. _reference-form-twig-variables:
+
+Form 変数リファレンス
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+下の変数は全てのフィールドタイプに共通です。フィールドタイプの中にはもっと多くの変数があるものもあり、特定のフィールドのみに有効な変数もあります。
+
+テンプレートに ``form`` 変数が含まれていて ``name`` フィールドの変数にアクセスしたいとき、 :class:`Symfony\\Component\\Form\\FormView` オブジェクトの ``vars`` プロパティを使うことによりアクセスできます。
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        <label for="{{ form.name.vars.id }}"
+            class="{{ form.name.vars.required ? 'required' : '' }}">
+            {{ form.name.vars.label }}
+        </label>
+
+    .. code-block:: html+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>
+
+.. versionadded:: 2.3
+    The ``method`` and ``action`` variables were introduced in Symfony 2.3.
+
+.. versionadded:: 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_enctype`` は ``enctype="multipart/form-data"`` を出力します。        |
+|                        | 親のフォームだけに適用されます。                                         |
++------------------------+-------------------------------------------------------------------------------------+
+| ``attr``               | フィールドに HTML 属性として出力される key-value 配列。            |
++------------------------+-------------------------------------------------------------------------------------+
+| ``compound``           | フィールドが実際は子フィールドを保持しているかどうか。| 
+|                        | (例えば ``choice`` フィールドがあるときに、それがチェックボックスの集合で成り立っているかどうか。         |
++------------------------+-------------------------------------------------------------------------------------+
+| ``block_prefixes``     | 親タイプ全ての名前の配列 | 
++------------------------+-------------------------------------------------------------------------------------+
+| ``translation_domain`` | 現在のフォームの翻訳ドメイン                                       |
++------------------------+-------------------------------------------------------------------------------------+
+| ``cache_key``          | キャッシュで利用される一意なキー                                            |
++------------------------+-------------------------------------------------------------------------------------+
+| ``data``               | タイプの変換された（ノーマライズされた）データ                                                    |
++------------------------+-------------------------------------------------------------------------------------+
+| ``method``             | 現在のフォームのメソッド(GET, POSTなど)                                   |
++------------------------+-------------------------------------------------------------------------------------+
+| ``action``             | 現在のフォームのアクション |
++------------------------+-------------------------------------------------------------------------------------+
+
+.. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
+.. _`Twig ドキュメント`: http://twig.sensiolabs.org/doc/templates.html#test-operator
+
+.. 2014/04/19 77web b4a0fb09a2e8a30345d8f4c86c7cd8f8662d6ce3
 
-翻訳にご協力くださる方は
-`github/symfony-japan <https://github.com/symfony-japan/symfony-docs-ja/wiki>`_ まで！
