` としても利用されます。
ラベルやエラー、HTMLフォームウィジェットのレンダリングなど、大部分の処理は ``form_row`` ヘルパーによって行われます。
なお、デフォルトではフォームウィジェットは ``div`` タグで囲まれた状態でレンダリングされます。
:ref:`フォームテーマ` 節にて、``form_row`` の出力をカスタマイズする方法を解説しています。
.. tip::
HTML5では、ブラウザ側でフォームのバリデーションを行う仕組みが用意されています。
Symfonyを用いて生成したフォームはその仕組みを最大限活用するようになっています。
もしこの仕組みを無効にしたい場合、``form`` タグに ``novalidate`` 属性を指定するか、サブミットボタンに ``formnovalidate`` 属性を指定します。
それぞれのフィールドを手動でレンダリングする
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``form_row`` ヘルパーは、フィールドを手っ取り早くレンダリングするのにうってつけです(「行(row)」のマークアップはカスタマイズも可能です)。
複雑なフォームの場合はフィールドを好きなように配置することも可能です。
.. configuration-block::
.. code-block:: html+jinja
{{ form_errors(form) }}
{{ form_label(form.name) }}
{{ form_errors(form.name) }}
{{ form_widget(form.name) }}
{{ form_label(form.price) }}
{{ form_errors(form.price) }}
{{ form_widget(form.price) }}
{{ form_rest(form) }}
.. code-block:: html+php
errors($form) ?>
label($form['name']) ?>
errors($form['name']) ?>
widget($form['name']) ?>
label($form['price']) ?>
errors($form['price']) ?>
widget($form['price']) ?>
rest($form) ?>
もし自動生成されるラベルを変更したい場合は、次のようにして明示的に指定します。
.. configuration-block::
.. code-block:: html+jinja
{{ form_label(form.name, 'Product name') }}
.. code-block:: html+php
label($form['name'], 'Product name') ?>
これらに加え、フィールドタイプごとにレンダリングオプションが用意されています。
それぞれのオプションはドキュメントに記載してありますが、中でもよく使われるのがフォームの属性を指定するための ``attr`` オプションです。
次の例ではフィールドに ``name_field`` class属性を指定します。
.. configuration-block::
.. code-block:: html+jinja
{{ form_widget(form.name, { 'attr': {'class': 'name_field'} }) }}
.. code-block:: html+php
widget($form['name'], array(
'attr' => array('class' => 'name_field'),
)) ?>
Twigテンプレート 関数リファレンス
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Twigを利用している場合、フォームに関する関数のリファレンスはすべて :doc:`リファレンスマニュアル` に記載されています。
.. index::
single: フォーム; フォームクラスの作成
.. _book-form-creating-form-classes:
フォームクラスの作成
--------------------
フォームがコントローラ内で直接組み立てができることは既に解説しました。
しかしながら、フォームの組み立て処理をクラスとして独立させることで、再利用性の向上につながります。
次は商品フォームを組み立てる処理をクラス化したものです。
.. code-block:: php
// src/Acme/StoreBundle/Form/Type/ProductType.php
namespace Acme\StoreBundle\Form\Type;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilder;
class ProductType extends AbstractType
{
public function buildForm(FormBuilder $builder, array $options)
{
$builder->add('name');
$builder->add('price', 'money', array('currency' => 'USD'));
}
public function getName()
{
return 'product';
}
}
このクラスには商品フォームを作成するための処理がすべて記述されています(``getName()`` メソッドはタイプを識別するユニークな値を返す必要があります)。
あとはコントローラでこれを呼び出すだけで素早くフォームが組み立てられます。
.. code-block:: php
// src/Acme/StoreBundle/Controller/DefaultController.php
// クラスの先頭にuseステートメントを追加
use Acme\StoreBundle\Form\Type\ProductType;
public function indexAction()
{
$product = // ...
$form = $this->createForm(new ProductType(), $product);
// ...
}
.. note::
フォームのデータは ``setData()`` メソッドを通じてセットすることもできます。
.. code-block:: php
$form = $this->createForm(new ProductType());
$form->setData($product);
``setData`` メソッドを使う場合、フィールドタイプの推測機能を利用するには次のようにフォームクラスを指定する必要があります。
.. code-block:: php
public function getDefaultOptions(array $options)
{
return array(
'data_class' => 'Acme\StoreBundle\Entity\Product',
);
}
このようにするのは、 フォームが作成された時点でフォームタイプの推測が行われ、オブジェクトが渡されるのはそれより後になるためです。
フォームに関する処理をクラスとしてまとめることで、容易に再利用できるようになります。
これがもっともよいやり方ですが、最終的にどうやるかはあなた次第です。
.. index::
pair: フォーム; Doctrine
フォームと Doctrine
-------------------
フォームを目的はオブジェクト(``Product`` など)のデータを HTML のフォームに変換することと、フォームから送信されたデータを元のオブジェクトに反映することです。
ここでは ``Product`` オブジェクトをデータベースに保存するやり方について解説しますが、フォームとは直接関係のない内容になります。
``Product`` クラスを Doctrine を用いて保存できるように設定しているのであれば、次のようにして送信されたデータが妥当な場合に保存を行います。
.. code-block:: php
if ($form->isValid()) {
$em = $this->get('doctrine')->getEntityManager();
$em->persist($product);
$em->flush();
return $this->redirect($this->generateUrl('store_product_success'));
}
もし何らかの理由により、もともとデータが格納されていた ``$product`` オブジェクトにアクセスしたくない場合、次のようにしてフォームから取得できます。
.. code-block:: php
$product = $form->getData();
より詳しい情報は、 :doc:`Doctrine ORM の章` を参照してください。
重要なことは、フォームがにデータがバインドされたとき、そのデータは直ちに内部に持つオブジェクトに反映されるということです。
つまりそのデータを保存したいのであれば、単純にそのオブジェクトを保存すればよいわけです。
もしフォームの内部に持つオブジェクト(``Product`` など)がDoctrine ORMによってマッピングされている場合、フォームフレームワークはバリデーションのメタデータと同様に、その情報をもとにタイプの推測を行います。
.. index::
single: フォーム; フォームの埋め込み
フォームの埋め込み
------------------
1つのフォームで複数のオブジェクトを使いたいことがしばしばあると思います。
例えば、``User`` オブジェクトを登録するフォームで ``Address`` などの様々なオブジェクトも扱わなければならない場合などです。
フォームコンポーネントを用いると、簡単かつ自然にこれらの処理が行えます。
単一のオブジェクトの埋め込み
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``Product`` には ``Category`` オブジェクトが紐づいているとします。
.. code-block:: php
// src/Acme/StoreBundle/Entity/Category.php
namespace Acme\StoreBundle\Entity;
use Symfony\Component\Validator\Constraints as Assert;
class Category
{
/**
* @Assert\NotBlank()
*/
public $name;
}
``Product`` クラスは ``$category`` プロパティを持ち、そこに ``Category`` が紐づきます。
.. code-block:: php
use Symfony\Component\Validator\Constraints as Assert;
class Product
{
// ...
/**
* @Assert\Type(type="Acme\StoreBundle\Entity\Category")
*/
protected $category;
// ...
public function getCategory()
{
return $this->category;
}
public function setCategory(Category $category)
{
$this->category = $category;
}
}
これらをアプリケーションへ反映したら、 ``Category`` オブジェクトをユーザーが修正できるようにフォームクラスを作成します。
.. code-block:: php
// src/Acme/StoreBundle/Form/Type/CategoryType.php
namespace Acme\StoreBundle\Form\Type;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilder;
class CategoryType extends AbstractType
{
public function buildForm(FormBuilder $builder, array $options)
{
$builder->add('name');
}
public function getDefaultOptions(array $options)
{
return array(
'data_class' => 'Acme\StoreBundle\Entity\Category',
);
}
public function getName()
{
return 'category';
}
}
``name`` フィールドのフィールドタイプは ``Category`` クラスのバリデーションメタデータをもとに(``text`` と)推測されます。
ここでの最終目標は ``Product`` がもつ ``Category`` を ``Product`` のフォームから変更できるようにすることです。
それをするために ``ProductType`` に ``category`` プロパティを追加し、そこに ``CategoryType`` オブジェクトを設定します。
.. code-block:: php
public function buildForm(FormBuilder $builder, array $options)
{
// ...
$builder->add('category', new CategoryType());
}
これで ``CategoryType`` は ``ProductType`` と共にレンダリングできるようになりました。
``Category`` フィールドのレンダリングは ``Product`` のフィールドをレンダリングするのと同じように行えます。
.. configuration-block::
.. code-block:: html+jinja
{# ... #}
{{ form_row(form.price) }}
Category
{{ form_row(form.category.name) }}
{{ form_rest(form) }}
{# ... #}
.. code-block:: html+php
row($form['price']) ?>
Category
row($form['category']['name']) ?>
rest($form) ?>
フォームからデータが送信されると、``Category`` のフィールドに対応するデータが ``Category`` オブジェクトに反映されます。
これらはすべて、メインの ``Product`` オブジェクトを操作する一環として行われます。
``Category`` オブジェクトは ``$product->getCategory()`` のように取得でき、データベースへ保存など、任意に操作できます。
複数フォームの埋め込み
~~~~~~~~~~~~~~~~~~~~~~
``collection`` フィールドタイプを使うと、1つのフォームの中に複数フォームを埋め込むこともできます。
たとえば、``reviews`` プロパティと、そこに対応する ``ProductReviewType`` タイプがあるとして、``ProductType`` を次のように変更します。
.. code-block:: php
public function buildForm(FormBuilder $builder, array $options)
{
// ...
$builder->add('reviews', 'collection', array(
'type' => new ProductReviewType(),
));
}
.. index::
single: フォーム; テーマ
single: フォーム; フィールドのカスタマイズ
.. _form-theming:
フォームのテーマ
----------------
Every part of how a form renders can be customized. You're free to change
how each form "row" renders, change the markup used to render errors, or
even customize how a textarea tag should be rendered. Nothing is off-limits,
and different customizations can be used in different places.
Symfony uses templates to render each and every part of a form, such as
field ``label`` tags, ``input`` tags, error messages and everything else.
In Twig, each form "fragment" is represented by a Twig block. To customize
any part of how a form renders, you just need to override the appropriate block.
In PHP, each form "fragment" is rendered via an individual template file.
To customize any part of how a form renders, you just need to override the
existing template by creating a new one.
To understand how this works, let's customize the ``form_row`` fragment and
add a class attribute to the ``div`` element that surrounds each row. To
do this, create a new template file that will store the new markup:
.. configuration-block::
.. code-block:: html+jinja
{# src/Acme/StoreBundle/Resources/views/Form/fields.html.twig #}
{% block field_row %}
{% spaceless %}
{{ form_label(form) }}
{{ form_errors(form) }}
{{ form_widget(form) }}
{% endspaceless %}
{% endblock field_row %}
.. code-block:: html+php
label($form, $label) ?>
errors($form) ?>
widget($form, $parameters) ?>
The ``field_row`` form fragment is used when rendering most fields via the
``form_row`` function. To tell the component to use your new ``field_row``
fragment defined above, add the following to the top of the template that
renders the form:
.. configuration-block:: php
.. code-block:: html+jinja
{# src/Acme/StoreBundle/Resources/views/Default/index.html.twig #}
{% form_theme form 'AcmeStoreBundle:Form:fields.html.twig' %}