Home | Symfony2Doc »リファレンスドキュメント »Form Type リファレンス »entity フィールドタイプ

コンテンツ上部に更新日の記載のないページは、翻訳の内容が2.0相当のものになっております。最新の内容は原文のページをご確認ください。

Note

  • 対象バージョン:2.4 (2.0以降)
  • 翻訳更新日:2013/12/30

entity フィールドタイプ

Doctrineentity から選択肢を読み込む様に設計された特別な choice フィールドです。例えば、 Category エンティティを持つ場合、 select フィールドにデータベースからの Category オブジェクト全て、または一部を表示するのにこのフィールドを使います。

対応するタグ さまざまなタグに対応 (参照 セレクトタグ、チェックボックス、ラジオボタン)
オプション
上書きされた オプション
継承された オプション
親タイプ choice
クラス EntityType

基本的な使い方

entity タイプは一つだけ必須のオプションを持ちます。選択フィールドの内側に一覧にされるべきエンティティです。:

$builder->add('users', 'entity', array(
    'class' => 'AcmeHelloBundle:User',
    'property' => 'username',
));

この場合、すべての User オブジェクトはデータベースから読み取られ、セレクトタグ、ラジオボタン、または、一連のチェックボックスとして表示されます(これは multipleexpanded の値によります)。 もし、エンティティオブジェクトが __toString() メソッドを持っていない場合、 property オプションを設定する必要があります。

エンティティにカスタムクエリを利用する

エンティティを取り出す際に、特別なカスタムクエリーを定義する必要がある場合(一部のエンティティのみ欲しい場合、または、並べ順を指定する必要がある場合など)、 query_builder オプションを利用します。以下のように使うのが最も簡便です。:

use Doctrine\ORM\EntityRepository;
// ...

$builder->add('users', 'entity', array(
    'class' => 'AcmeHelloBundle:User',
    'query_builder' => function(EntityRepository $er) {
        return $er->createQueryBuilder('u')
            ->orderBy('u.username', 'ASC');
    },
));

Choices の利用

すでに選択肢に含めるエンティティの正確な集合を持っている場合、簡潔に choices キーに渡すことが出来ます。 例えば、(フォームオプションとしてフォームにわたされた) $group 変数を持ち、 getUsersUser エンティティのコレクションをかえす場合、直接 choices オプションに提供できます。:

$builder->add('users', 'entity', array(
    'class' => 'AcmeHelloBundle:User',
    'choices' => $group->getUsers(),
));

セレクトタグ、チェックボックス、ラジオボタン

このフィールドは expandedmultiple オプションに応じて、いくつかの異なった HTML フィールドのうちの一つが表示されます。:

要素タイプ expanded multiple
セレクトタグ false false
セレクトタグ ( multiple 属性有) false true
ラジオボタン true false
チェックボックス true true

フィールドオプション

class

データ型: string 必須

エンティティのクラスです(例 AcmeStoreBundle:Category )。これは完全修飾クラス名(例 Acme\StoreBundle\Entity\Category )か、(上述のような)省略名です。

property

データ型: string

これはエンティティが HTML 要素にテキストとして表示されるために使用されるプロパティです。未設定のままの場合、エンティティオブジェクトは文字列変換されるので、 __toString() メソッドを持つ必要があります。

group_by

データ型: string

グループで選択できるよう整理する、プロパティパス(例 author.name )です。セレクトタグとして表示される場合のみ動作し、選択肢を囲むように optgroup タグを追加する動作をします。このプロパティパスの値を返さない選択肢は、直接セレクトタグの下に表示され、 optgroup で囲まれません。

query_builder

データ型: Doctrine\ORM\QueryBuilder または 単一の無名関数

指定した場合、フィールドに使用される選択肢の絞込み(とその順序)のクエリーに使用されます。このオプションの値は QueryBuilder オブジェクトか無名関数です。無名関数を使用する場合は、引数としてエンティティの EntityRepository を一つとります。

em

データ型: string デフォルト: デフォルトエンティティマネージャー

指定された場合、デフォルトのエンティティマネージャの代わりに指定されたエンティティマネージャが選択肢の読み込みに使われます。

上書きされたオプション

choices

データ型: array || \Traversable デフォルト: null

classquery_builder オプションでエンティティを読み込む代わりに、直接 choices オプションを渡すことが出来ます。 参照 Choices の利用

choice_list

デフォルト: EntityChoiceList

entity タイプの目的は、上述のすべてのオプションを利用して EntityChoiceList を作成し設定することです。このオプションを上書きする必要がある場合は、 choice フィールドタイプ を直接使用することも検討できるでしょう。

継承されたオプション

以下のオプションは choice タイプを継承しています:

multiple

データ型: Boolean デフォルト: false

true の場合、(一つの選択肢だけを選ぶのと対照的に)複数の選択肢が選択可能になります。 expanded オプションの値によって、 true の場合はセレクトタグかチェックボックスで表示されます。 false の場合はセレクトタグかラジオボタンとなります。戻り値は配列となります。

Note

Doctrine のエンティティのコレクションを使用している場合、 collection フィールドタイプ のドキュメントを読むとより参考になります。加えて、クックブックの記事に完全な例があります。 フォームのコレクションを埋め込む方法

expanded

データ型: Boolean デフォルト: false

もし true の場合、( multiple の値により)ラジオボタンかチェックボックスが表示されます。 false の場合、 select 要素が表示されます。

preferred_choices

データ型: array デフォルト: array()

このオプションが指定されていた場合、すべての選択肢の一部がセレクトメニューの最上部に移動します。以下は “Baz” オプションが最上部に移動し、それと残りの選択肢の間にセパレーターがつきます。:

$builder->add('foo_choices', 'choice', array(
    'choices' => array('foo' => 'Foo', 'bar' => 'Bar', 'baz' => 'Baz'),
    'preferred_choices' => array('baz'),
));

ここで注意すべきは好みの選択肢は select 要素で表示されたときにのみ意味を持つことです(すなわち expandedfalse )。この好みの選択肢と通常の選択肢は点線(すなわち ------------------- )によって明示的に分離されます。これは表示する際に編集することが出来ます。:

  • Twig
    {{ form_widget(form.foo_choices, { 'separator': '=====' }) }}
    
  • PHP
    <?php echo $view['form']->widget($form['foo_choices'], array('separator' => '=====')) ?>
    

empty_value

データ型: string or Boolean

New in version 2.3: Symfony 2.3 から、 expanded オプションが true の場合でも空の値がサポートされました。

このオプションは特別な「空の」選択肢(例 “選択肢を選んで下さい” )がセレクトウィジェットの一番上に表示されるかどうかを決定します。このオプションは multiple オプションが false の場合にのみ適用されます。

  • テキストとして”選択肢を選んで下さい”との空の値を追加します。:

    $builder->add('states', 'choice', array(
        'empty_value' => '選択肢を選んで下さい',
    ));
    
  • 「空の」値の選択肢が表示されないことを保証します。:

    $builder->add('states', 'choice', array(
        'empty_value' => false,
    ));
    

empty_value を設定しないままで、 required オプションが false の場合にのみ空の選択肢(テキスト無し)が自動的に追加されます。:

// 空の選択肢(テキスト無し)が追加されます
$builder->add('states', 'choice', array(
    'required' => false,
));

以下のオプションは form タイプを継承しています:

required

データ型: Boolean デフォルト: true

trueの場合は HTML5 の required 属性 がレンダリングされます。 対応する label もまた required クラスをレンダリングします。

これらは表面的でバリデーションからは独立しています。Symfonyに フィールドタイプを推測することを許可する場合は、 このオプションの値はバリデーションの情報から推測されるのが理想的でしょう。

label

データ型: string デフォルト: フィールド名から推測されたものです。

フィールドがレンダリングされる際にラベルが設定されます。false が設定されるとラベルは表示されません。 ラベルはテンプレート内部で設定することもできます。

{{ render_label(form.name, 'Your name') }}

read_only

データ型: Boolean デフォルト: false

このオプションが true の場合、そのフィールドは readonly 属性付きでレンダリングされるため、編集する事が出来ません。

disabled

データ型: boolean デフォルト: false

ユーザにフィールドの値を変更させたくない場合は、 disabled オプションを true にします。どんなサブミットされた値も無視されます。

error_bubbling

データ型: Boolean デフォルト: false フォームに限り compound

true の場合、このフィールドのエラーは親フィールドまたはフォームに渡されます。 たとえば、通常のフィールドを true に設定した場合、フィールドに対するエラーは 特定のフィールドではなくメインのフォームに付加されます。

error_mapping

データ型: array デフォルト: empty

このオプションはバリデーションエラーの対象を編集することができます。

matchingCityAndZipCode という名前のメソッドを持っているとして、それが city および zip code が一致するかの検証をするとします。しかし残念なことに、 “matchingCityAndZipCode” フィールドがフォームに無いため、 Symfony ができるのはフォームの上部にエラーを表示することです。

カスタマイズされたエラーマッピングを使うと、city フィールドの上にエラーを表示するように、より上手にエラーをマップできます。:

public function setDefaultOptions(OptionsResolverInterface $resolver)
{
    $resolver->setDefaults(array(
        'error_mapping' => array(
            'matchingCityAndZipCode' => 'city',
        ),
    ));
}

こちらが左側、右側のマッピングするルールです:

  • 左側はプロパティパスを有します。
  • クラスのプロパティまたはメソッドで違反が生成された場合、そのパスは単に “propertyName” です。
  • array または ArrayAccess オブジェクトで違反が生成された場合、プロパティパスは [indexName] です。
  • ドットでプロパティを分離し、それらを連結して、ネストされたプロパティパスを作成することができます。たとえば addresses[work].matchingCityAndZipCode のように。
  • 左側のエラーマッピングは単一のドット . も認められます。それはフィールド自体をさしています。フィールドに追加されたエラーはネストされたフィールドの代わりに付与されたことを意味します。
  • 右側は単にフォームのフィールド名を有します。

mapped

データ型: boolean

オブジェクトを読み込んでいるまたは書き込んでいる間、フィールドが無視されるようにしたい場合は、 mapped オプションを false にしてください。

blog comments powered by Disqus