Skip to content

[Form] Document how unmapped forms can be implemented #1387

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
webmozart opened this issue May 21, 2012 · 7 comments
Closed

[Form] Document how unmapped forms can be implemented #1387

webmozart opened this issue May 21, 2012 · 7 comments
Labels
actionable Clear and specific issues ready for anyone to take them. Form

Comments

@webmozart
Copy link
Contributor

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).
@webmozart webmozart mentioned this issue May 21, 2012
Closed
@wouterj
Copy link
Member

wouterj commented Jan 22, 2013

@weaverryan this should get a missing documentation label

@Sgoettschkes
Copy link
Contributor

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
Copy link
Member

stof commented Mar 26, 2013

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

@Sgoettschkes
Copy link
Contributor

@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
Copy link
Member

wouterj commented Mar 26, 2013

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

@Sgoettschkes
Copy link
Contributor

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
Copy link
Member

wouterj commented Mar 30, 2013

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

@Sgoettschkes Sgoettschkes mentioned this issue Mar 30, 2013
Merged
@Sgoettschkes Sgoettschkes mentioned this issue Apr 12, 2013
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
actionable Clear and specific issues ready for anyone to take them. Form
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@weaverryan @webmozart @stof @Sgoettschkes @wouterj