[Form] Document template variables for each form type

[webmozart]

The usage of forms in templates should be documented properly. People should understand that each form has attached variables which are accessible via {{ form.vars.<var-name> }} ($form->getVar('<var-name>') respectively) or, in a form theme, via {{ <var-name> }} directly ($<var-name> respectively).

Form children, in contrast, are accessed via {{ form.<child-name> }} (alternatively {{ form.children.<child-name>, which is necessary if the child name conflicts with one of the getters in FormView) and via $form['<child-name>'] in PHP templates.

For all form types, the available template variables should be documented (for example, in a "For designers" section) thouroughly.

[wouterj]

@weaverryan I think this should be documented soon, can you label it with 'Actionable' and 'Missing Documentation'?

[weaverryan]

We do cover this, though I don't think as intentionally as we should. In the form chapter, under the Rendering each Field by Hand header, we talk about how to do this (at the bottom of this section). But I think this area can be re-read and re-written with more realistic use-cases. This should also be under its own header to make it more findable.

[wouterj]

I think we should put this in the reference/forms/twig_reference article. The last section in that document already talks about the form variable, but not about the things mentioned here.

[weaverryan]

I think that's a great suggestion - the "form" chapter section should then just include a link over to the twig_reference doc. We should also look at the "form customizations" cookbook entry to make sure appropriate links are there to the new docs.

[fabpot]

👍 for adding all supported vars in a reference guide. Let me give you one very simple example that it not documented anywhere (except in an answer on SO by Bernhard): {{ form.vars.valid }} which allows you to easily check if a form has some errors or not. If you have a look at those that are always available, that's a lot: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Form/Extension/Core/Type/FormType.php#L123

This should probably be a high priority as this is really easy to document and highly interesting for developers.

[vicb]

which allows you to easily check if a form has some errors or not

You probably mean if a form "is valid", which is different - ie children included ?

[weaverryan]

I've got this going over in #2251 - thanks!

[wouterj]

Closing this as it #2251 is merged