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

Closed
webmozart opened this Issue May 21, 2012 · 7 comments

Comments

Projects
None yet
5 participants
@webmozart
Contributor

webmozart commented May 21, 2012

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

This comment has been minimized.

Show comment
Hide comment
@wouterj

wouterj Jan 22, 2013

Member

@weaverryan this should get a missing documentation label

Member

wouterj commented Jan 22, 2013

@weaverryan this should get a missing documentation label

@Sgoettschkes

This comment has been minimized.

Show comment
Hide comment
@Sgoettschkes

Sgoettschkes Mar 21, 2013

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?

Contributor

Sgoettschkes commented Mar 21, 2013

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

This comment has been minimized.

Show comment
Hide comment
@stof

stof Mar 26, 2013

Member

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

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

This comment has been minimized.

Show comment
Hide comment
@Sgoettschkes

Sgoettschkes Mar 26, 2013

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?

Contributor

Sgoettschkes commented Mar 26, 2013

@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

This comment has been minimized.

Show comment
Hide comment
@wouterj

wouterj Mar 26, 2013

Member

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

Member

wouterj commented Mar 26, 2013

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

@Sgoettschkes

This comment has been minimized.

Show comment
Hide comment
@Sgoettschkes

Sgoettschkes Mar 30, 2013

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?

Contributor

Sgoettschkes commented Mar 30, 2013

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

This comment has been minimized.

Show comment
Hide comment
@wouterj

wouterj Mar 30, 2013

Member

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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment