[Form] Document how unmapped forms can be implemented

[webmozart]

See symfony/symfony#3995

A form that does not map to the data of its parent should either be

• unmapped ("mapped" => false)
• virtual ("virtual" => true)

Unmapped forms are completely independent of their data. They have their own data, and children will be accessed to this data.

<?php
// Unmapped forms need to be filled with data explicitely
$form->add('address', 'form', array('mapped' => false));
$form->get('address')->setData($address);
// Maps to $address->getStreet()
$form->get('address')->add('street', 'text');

Virtual forms are not mapped to their parents data, but their children are.

<?php
// Virtual forms will not be mapped with data
$form->add('address', 'form', array('virtual' => true));
// Maps to $form->getData()->getStreet()
$form->get('address')->add('street', 'text');

Unmapped forms are useful if you want to embed forms that don't have a connection with the data of their parent form.

Virtual forms are useful if you use a form only in order to structure your view (see symfony/symfony#3995) or if you want to collect a set of field definitions that can be inserted ("copied") into the parent form (think traits).

[wouterj]

@weaverryan this should get a missing documentation label

[Sgoettschkes]

I found the virtual option in the 2.0 branch and the mapped option in 2.1. Correct?

If this is correct, I would start adding the virtual description to 2.0, waiting till it's merged in 2.1/2.2 and then add the mapped to 2.1. Is this the way to go?

[stof]

@Sgoettschkes virtual still exist in 2.1, 2.2 and 2.3. It is not the same meaning than mapped

[Sgoettschkes]

@stof I know. Maybe I described it the wrong way:

• virtual exists since 2.0
• mapped exists since 2.1

To make merging the document easier, I was thinking about adding the virtual option and making a PR against 2.0. If this one is merged into all branches, I would make a PR against 2.1 with the mapped option changes.

It's a workflow we use at work very often when many changes are expected against one document, to prevent merge conflicts.

If you don't think this is neccessary I don't mind doing both PR at the same time, but I still think they have to be split up as mapped was introduced in 2.1, right?

[wouterj]

You're workflow is the way I recommend to use (it's the most GITish solution)

[Sgoettschkes]

I just realized there is a whole cookbook explaining the virtual option: http://symfony.com/doc/2.1/cookbook/form/use_virtuals_forms.html

Does this mean only tthe unmapped option needs to be documented or should the documentation be extended somewhere to also mention the virtual option?

[wouterj]

Both of the options aren't documented yet on the form reference, that's something that needs to be done. See also #2362