Skip to content

Commit f9b8d1a

Browse files
committed
Merge branch 'issue5899' of github.com:bschussek/symfony-docs into bschussek-issue5899
Conflicts: cookbook/form/index.rst cookbook/map.rst.inc
2 parents 7b3e12c + dbfcaff commit f9b8d1a

File tree

3 files changed

+34
-40
lines changed

3 files changed

+34
-40
lines changed

cookbook/form/index.rst

+3-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,9 @@ Form
1010
form_collections
1111
create_custom_field_type
1212
create_form_type_extension
13-
use_virtuals_forms
13+
inherit_data_option
1414
unit_testing
1515
use_empty_data
1616
direct_bind
17+
18+

cookbook/form/use_virtuals_forms.rst renamed to cookbook/form/inherit_data_option.rst

+30-38
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
.. index::
2-
single: Form; Virtual forms
2+
single: Form; The "inherit_data" option
33

4-
How to use the Virtual Form Field Option
5-
========================================
4+
Reducing Code Duplication with "inherit_data"
5+
=============================================
66

7-
The ``virtual`` form field option can be very useful when you have some
8-
duplicated fields in different entities.
9-
10-
For example, imagine you have two entities, a ``Company`` and a ``Customer``::
7+
The ``inherit_data`` form field option can be very useful when you have some
8+
duplicated fields in different entities. For example, imagine you have two
9+
entities, a ``Company`` and a ``Customer``::
1110

1211
// src/Acme/HelloBundle/Entity/Company.php
1312
namespace Acme\HelloBundle\Entity;
@@ -39,13 +38,10 @@ For example, imagine you have two entities, a ``Company`` and a ``Customer``::
3938
private $country;
4039
}
4140
42-
Like you can see, each entity shares a few of the same fields: ``address``,
41+
As you can see, each entity shares a few of the same fields: ``address``,
4342
``zipcode``, ``city``, ``country``.
4443

45-
Now, you want to build two forms: one for a ``Company`` and the second for
46-
a ``Customer``.
47-
48-
Start by creating a very simple ``CompanyType`` and ``CustomerType``::
44+
Let's build two forms for these entities, ``CompanyType`` and ``CustomerType``::
4945

5046
// src/Acme/HelloBundle/Form/Type/CompanyType.php
5147
namespace Acme\HelloBundle\Form\Type;
@@ -84,8 +80,9 @@ Start by creating a very simple ``CompanyType`` and ``CustomerType``::
8480
}
8581
}
8682
87-
Now, to deal with the four duplicated fields. Here is a (simple)
88-
location form type::
83+
Instead of including the duplicated fields ``address``, ``zipcode``, ``city``
84+
and ``country``in both of these forms, we will create a third form for that.
85+
We will call this form simply ``LocationType``::
8986

9087
// src/Acme/HelloBundle/Form/Type/LocationType.php
9188
namespace Acme\HelloBundle\Form\Type;
@@ -108,7 +105,7 @@ location form type::
108105
public function setDefaultOptions(OptionsResolverInterface $resolver)
109106
{
110107
$resolver->setDefaults(array(
111-
'virtual' => true
108+
'inherit_data' => true
112109
));
113110
}
114111

@@ -118,46 +115,41 @@ location form type::
118115
}
119116
}
120117

121-
You don't *actually* have a location field in each of your entities, so you
122-
can't directly link ``LocationType`` to ``CompanyType`` or ``CustomerType``.
123-
But you absolutely want to have a dedicated form type to deal with location (remember, DRY!).
118+
The location form has an interesting option set, namely ``inherit_data``. This
119+
option lets the form inherit its data from its parent form. If embedded in
120+
the company form, the fields of the location form will access the properties of
121+
the ``Company`` instance. If embedded in the customer form, the fields will
122+
access the properties of the ``Customer`` instance instead. Easy, eh?
124123

125-
The ``virtual`` form field option is the solution.
124+
.. note::
126125

127-
You can set the option ``'virtual' => true`` in the ``setDefaultOptions()`` method
128-
of ``LocationType`` and directly start using it in the two original form types.
126+
Instead of setting the ``inherit_data`` option inside ``LocationType``, you
127+
can also (just like with any option) pass it in the third argument of
128+
``$builder->add()``.
129129

130-
Look at the result::
130+
Let's make this work by adding the location form to our two original forms::
131131

132-
// CompanyType
132+
// src/Acme/HelloBundle/Form/Type/CompanyType.php
133133
public function buildForm(FormBuilderInterface $builder, array $options)
134134
{
135+
// ...
136+
135137
$builder->add('foo', new LocationType(), array(
136138
'data_class' => 'Acme\HelloBundle\Entity\Company'
137139
));
138140
}
139141

140142
.. code-block:: php
141143
142-
// CustomerType
144+
// src/Acme/HelloBundle/Form/Type/CustomerType.php
143145
public function buildForm(FormBuilderInterface $builder, array $options)
144146
{
147+
// ...
148+
145149
$builder->add('bar', new LocationType(), array(
146150
'data_class' => 'Acme\HelloBundle\Entity\Customer'
147151
));
148152
}
149153
150-
With the virtual option set to false (default behavior), the Form Component
151-
expects each underlying object to have a ``foo`` (or ``bar``) property that
152-
is either some object or array which contains the four location fields.
153-
Of course, you don't have this object/array in your entities and you don't want it!
154-
155-
With the virtual option set to true, the Form component skips the ``foo`` (or ``bar``)
156-
property, and instead "gets" and "sets" the 4 location fields directly
157-
on the underlying object!
158-
159-
.. note::
160-
161-
Instead of setting the ``virtual`` option inside ``LocationType``, you
162-
can (just like with any options) also pass it in as an array option to
163-
the third argument of ``$builder->add()``.
154+
That's it! You have extracted duplicated field definitions to a separate
155+
location form that you can reuse wherever you need it.

cookbook/map.rst.inc

+1-1
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@
8484
* :doc:`/cookbook/form/form_collections`
8585
* :doc:`/cookbook/form/create_custom_field_type`
8686
* :doc:`/cookbook/form/create_form_type_extension`
87-
* :doc:`/cookbook/form/use_virtuals_forms`
87+
* :doc:`/cookbook/form/inherit_data_option`
8888
* :doc:`/cookbook/form/unit_testing`
8989
* :doc:`/cookbook/form/use_empty_data`
9090
* :doc:`/cookbook/form/direct_bind`

0 commit comments

Comments
 (0)