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

ご注意

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

Note

  • 対象バージョン:2.3+
  • 翻訳更新日:2014/06/20

form フィールドタイプ

form タイプを親タイプにもつすべてのタイプで利用可能なオプションを事前にいくつか定義しています。

オプション
継承された オプション
親クラス none
クラス FormType

フィールドオプション

data

データ型: mixed デフォルト: 対応するオブジェクトのフィールド(一つであれば)

フォームを作成したとき、各フィールドに表示する初期値は、フォームのドメインオブジェクトの対応するプロパティの値です(オブジェクトがフォームにバインドされている場合)。もしフォーム、または、単に個々のフィールドの初期値を上書きしたい場合は、data オプションで設定することが出来ます。:

$builder->add('token', 'hidden', array(
    'data' => 'abcdef',
));

Note

フォームのフィールドのデフォルト値は、直接データ構造(例えば、エンティティまたは配列)から取得されます。 data オプションはこのデフォルト値を上書きします。

data_class

データ型: string

このオプションは、フォームで使用する適切なデータ·マッパーを設定するために使われます。 オブジェクトを必要とする任意のフィールドタイプに使用することができます。

$builder->add('media', 'sonata_media_type', array(
    'data_class' => 'Acme\DemoBundle\Entity\Media',
));

empty_data

データ型: mixed デフォルト: multiple 又は expanded の場合 array() それ以外 ''

このオプションは empty_value の選択肢が選ばれた時に、どのような値を返すかを決定します。

このオプションのデフォルト値はフィールドオプションによって異なります。:

  • data_class が設定され requiredtrue の場合、 new $data_class();
  • data_class が設定され requiredfalse の場合、 null;
  • data_class が設定されず compoundtrue の場合、 array();
  • data_class が設定されず compoundfalse の場合、 null.

しかし、必要に応じてこれを変更することができます。例えば、値が選択されていないとき gender フィールドを明示的に null に設定したいとすると、このようにできます。:

$builder->add('gender', 'choice', array(
    'choices' => array(
        'm' => 'Male',
        'f' => 'Female'
    ),
    'required'    => false,
    'empty_value' => 'Choose your gender',
    'empty_data'  => null
));

Note

フォームクラス全体に empty_data オプションをセットしたい場合はクックブックの記事( /cookbook/form/use_empty_data )を参照してください。

compound

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

フォームが合成物である場合は、このオプションが指定されます。 これは、フォームが実際に子要素を持っているかどうかとは無関係です。 フォームが合成物である時は子要素をまったく持つことができません(例えば、空のコレクション型)。

required

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

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

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

label_attr

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

フィールドのラベルを表示する際、 <label> 要素に html 属性を設定します。それは HTML 属性をキーとした連想配列です。この属性は直接テンプレートの中に設定することも出来ます。:

  • Twig
    {{ form_label(form.name, 'あなたのお名前', {'label_attr': {'class': 'CUSTOM_LABEL_CLASS'}}) }}
    
  • PHP
    echo $view['form']->label(
        $form['name'],
        'あなたのお名前',
        array('label_attr' => array('class' => 'CUSTOM_LABEL_CLASS'))
    );
    

constraints

データ型: array または Constraint デフォルト: null

特定のフィールドに1つ以上の検証制約を設定することができます。 より詳しくはこちらを参照 Adding Validation 。 このオプションはフォーム拡張の FormTypeValidatorExtension に追加されます。

cascade_validation

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

埋め込んだフォームタイプの検証を強制するためにこのオプションを true にします。 例えば、 ProductTypeCategoryType を埋め込んで持つ場合、 ProductTypecascade_validationtrue にすることで、 検証されるべき CategoryType からもデータが発生します。

このオプションの代わりに、モデルの Valid 制約でプロパティに格納されている子オブジェクトの検証を強制することができます。

Tip

collection Field Type では親フォームへエラーを渡す error_bubbling オプションはデフォルトで有効になっています。 実際に発生した場所にエラーを添付したい場合は、 error_bubblingfalse に設定する必要があります。

read_only

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

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

trim

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

trueの場合、サブミットされた文字列の値に含まれる空白は trim() で取り去られます。 余分な空白とともにサブミットされた値の場合、その値が下位のオブジェクトに取り込まれる前に取り除かれます。

mapped

データ型: boolean

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

property_path

データ型: any デフォルト: the field's name

フィールドには、デフォルトで、フォームのドメインオブジェクトのプロパティの値を表示します。フォームの送信時に、送信された値はオブジェクトに書き込まれます。

フィールドの読み取りと書き込みのプロパティを上書きしたい場合は、 property_path オプションを設定することでできます。そのデフォルト値は、フィールドの名前です。

オブジェクトの読み込み、書き込み時にそのフィールドを無視したい場合は、property_path オプションを false にすることで出来ます。しかし、その目的での property_path の使用は推奨されません。 mapped オプションを使用する必要があります。

max_length

データ型: integer

このオプションは maxlength 属性を追加する際に使用します。 いくつかのブラウザでは、フィールド内のテキストの長さを制限するために使用されています。

by_reference

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

下層にあるオブジェクトに name フィールドを持つとして、ほとんどの場合、setName が呼ばれることを期待します。 しかし、場合によっては setName が呼ばれ ない ことがあります。by_reference をセットすることですべての場合にセッターが呼ばれることを確実にします。

さらに説明するため、簡単な例がこちらです。:

$builder = $this->createFormBuilder($article);
$builder
    ->add('title', 'text')
    ->add(
        $builder->create('author', 'form', array('by_reference' => ?))
            ->add('name', 'text')
            ->add('email', 'email')
    )

by_referencetrue の場合、フォームの submit (または handleRequest )が呼ばれたとき、次のように裏側では処理されます。:

$article->setTitle('...');
$article->getAuthor()->setName('...');
$article->getAuthor()->setEmail('...');

setAuthor が呼び出されないことに注意して下さい。その author はリファレンスにより変更されます。

by_referencefalse の場合、送信時の処理はこのようになります。:

$article->setTitle('...');
$author = $article->getAuthor();
$author->setName('...');
$author->setEmail('...');
$article->setAuthor($author);

このように by_reference=false が実際にすることは、親オブジェクトでセッターを呼ぶことをフレームワークに強制することです。

同様に、下層にあるコレクションに collection フォームタイプを利用している場合、データは( Doctrine の ArrayCollection のように)オブジェクトです。そして、(例えば setAuthors のように)セッターが呼ばれる必要があるときは、by_referencefalse に設定されるべきです。

error_bubbling

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

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

inherit_data

New in version 2.3: このオプションは Symfony 2.3 より前は virtual として知られていました。

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

フォームが親フォームからデータを継承する場合は、このオプションで決定します。複数のフォーム間で重複しているフィールドのセットを持っている場合に役立ちます。参照 “inherit_data”オプションを使用してコードの重複を減らす

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 のように。
  • 左側のエラーマッピングは単一のドット . も認められます。それはフィールド自体をさしています。フィールドに追加されたエラーはネストされたフィールドの代わりに付与されたことを意味します。
  • 右側は単にフォームのフィールド名を有します。

invalid_message

データ型: string デフォルト: This value is not valid

フィールドに入力されたデータが意味を成さない(すなわち、バリデーション失敗の)場合に使われるバリデーションエラーのメッセージです。

たとえば、時間に変換される time フィールドに無意味な文字を入れたときに、または、 number フィールドに文字列(例、 apple )を入れたときにおきます。

通常の(最小の文字数をセットするような)(ビジネスロジック)バリデーションはバリデーションメッセージをバリデーションルール( reference )とあわせて設定すべきです。

invalid_message_parameters

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

invalid_message オプションをセットする場合、文字列にいくつかの変数を取り込む必要があるかもしれません。プレースホルダーをそのオプションに加え、変数をこのオプションに含めることで可能です:

$builder->add('some_field', 'some_type', array(
    // ...
    'invalid_message'            => 'You entered an invalid value - it should include %num% letters',
    'invalid_message_parameters' => array('%num%' => 6),
));

extra_fields_message

データ型: string デフォルト: This form should not contain extra fields.

これは検証エラーメッセージです。送信されたフォームデータに、フォーム定義の一部ではないフィールドが1つ以上含まれている場合に使われます。 プレースホルダ {{extra_fields}} は、送信された余分なフィールド名を、カンマ区切りのリストで表示することができます。

post_max_size_message

データ型: string デフォルト: The uploaded file was too large. Please try to upload a smaller file.

これは送信されたPOSTデータが php.inipost_max_size ディレクティブを超えた場合に使われる検証エラーメッセージです。 {{ max }} プレースホルダは、許可されたサイズを表示するために使用することができます。

Caution

pattern オプションは非推奨となり、3.0で削除されます。 その代わりに、attr オプションに pattern キーを持つ配列を設定し使用して下さい。

pattern

データ型: string デフォルト: null

これは HTML5 pattern 属性に指定した正規表現によるフィールド入力の制限を追加します。

action

New in version 2.3: action オプションは Symfony 2.3 から追加されました。

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

このオプションは、どこにフォームのデータを送信するかを指定します(通常はURI)。 その値は form 要素の action 属性としてレンダリングされます。 空の値は、同じドキュメント参照と見なされます。つまり、フォームは、レンダリングしたフォームと同じURIに送信されます。

method

New in version 2.3: method オプションは Symfony 2.3 から追加されました。

データ型: string デフォルト: POST

このオプションでは、フォームのデータを送信するために使用されるHTTPメソッドを指定します。 その値は form 要素の method 属性として表示されます。 また、送信後の handleRequest() メソッドの中で、フォームの送信をどう処理するかを決定するために使用されています。 可能な値は次のとおりです。

  • POST
  • GET
  • PUT
  • DELETE
  • PATCH

Note

メソッドが PUT 、PATCH 、または DELETE の時、 Symfony は自動的にフォームに hidden フィールド _method をレンダリングします。 これらは、”偽” のHTTPメソッドとして使用され、標準的なブラウザではサポートされていません。 詳細については、以下を参照してください。 /cookbook/routing/method_parameters

Note

PATCH メソッドは部分データを送信することができます。 言い換えれば、送信されたフォームデータの特定フィールドが欠落している場合、それらは無視され、デフォルト値が(もしあれば)使用されます。 他のすべてのHTTPメソッドは、いくつかのフィールドが欠落している場合、それらのフィールドには null が設定されます。

継承されたオプション

以下のオプションは BaseType クラスで定義されています。 BaseType クラスは form タイプと button type の両方の親クラスですが、フォームタイプツリーの一部ではありません(すなわち、それ自身はフォームタイプとして利用できません)。

block_name

データ型: string デフォルト: そのフォームの名前 (参照 Knowing which block to customize)

フォームタイプをレンダリングするために使用されるブロック名を上書きすることができます。 同じフォームの複数のインスタンスがあり、レンダリングを個別にパーソナライズする必要がある場合に便利です。

disabled

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

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

label

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

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

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

attr

データ型: array デフォルト値: Empty array

HTML フィールドの表現に追加属性を加えたい場合、attr オプションを使うことが出来ます。これは HTML 属性をキーとした連想配列です。ウィジェットにカスタムクラスを設定する必要があるときに便利です。:

$builder->add('body', 'textarea', array(
    'attr' => array('class' => 'tinymce'),
));

translation_domain

データ型: string デフォルト: messages

このフィールドのラベルまたはオプションの表示に使用されるに翻訳ドメインです。

auto_initialize

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

内部オプション:フォームを自動的に初期化されるべきかどうかを設定します。 このオプションはすべてのフィールドでルートフォームに対しては true のみであるべきです。 このオプションを変更する必要はありませんし、おそらくそれを心配する必要もありません。

blog comments powered by Disqus