[Form] Documentation about "compound" is insufficient / missing

[Narretz]

Currently, when your search for something like "Symfony form compound" this is the only thing this is showing up: http://symfony.com/doc/current/reference/forms/types/form.html#compound

For a beginner, this explains basically nothing. Would be nice if there was a more detailed documentation or a section in the cookbook.

[wouterj]

I agree with you. I believe updating the description of this option to be more detailed is the best thing we can do (until we improve the custom form type cookbook recipe, as this option is pretty important in that topic).

[javiereguiluz]

I'd like to help documenting this option, but I don't understand it.

@webmozart if you have some time, could you please explain the purpose of this option so I can document it? Thanks!

[wouterj]

@javiereguiluz this option determines whether the form contains child forms or not. E.g. TextType doesn't contain any childs, so compound is false. A custom SomeEntityType contains sub types, so compound is true (default value iirc). The DateType for instance can be both compound and not compound. When widget is single_text, compound is false (one field), otherwise compound is true (multiple input boxes).

Afaik, this option is only used internally and should not be configured/changed when using ->add(...).

[xabbuh]

Afaik, this option is only used internally and should not be configured/changed when using ->add(...).

I am sure you are right. Afaik this is used, for example, to render forms properly (you need to iterate child views). However, this is already taken into account when the FormView instances are created.

[javiereguiluz]

@wouterj in the current description of the compound option, you can read:

This (option) is independent of whether the form actually has children.
A form can be compound but not have any children at all (e.g. an empty
collection form).

Does this description contradicts what you said? ("This option determines whether the form contains child forms or not")

[wouterj]

The options tells if it has children or not. However, the description you quoted says: A collection form is compound, as it has children (each collection entry). However, if the property this field is bound to has no items in the collection, the form element will not display any children. This doesn't make the field a non-compound form (as it sure is).

[javiereguiluz]

@wouterj OK thanks. I've updated the related description in the other PR.

[stof]

@javiereguiluz the wording proposed previously might indeed be confusing relating to collections (which are the reason why the option has been introduced btw, to allow supporting the case of compound forms without children and still considering them as compound when rendering).
A solution might be to say that a compound form can have children, while a non-compound form is a simple field (and so will always be a leaf in the Form tree btw).

[caillioux]

Hi, here is a try to make it more clear:
Current:
This option specifies if a form is compound. This is independent of whether the form actually has children. A form can be compound but not have any children at all (e.g. an empty collection form).

Proposal:
This option specifies if a field is compound. When set to true, the field may have children (think about DateType with option widget set to choice).
When set to false, the field will act a leaf form type, with no children field (example : TextType, or DateType with option widget set to single_text).