Skip to content

[Form] Document template variables for each form type #1039

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.

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

Closed
webmozart opened this issue Jan 30, 2012 · 8 comments
Closed

[Form] Document template variables for each form type #1039

webmozart opened this issue Jan 30, 2012 · 8 comments
Labels
actionable Clear and specific issues ready for anyone to take them.
Milestone

Comments

@webmozart
Copy link
Contributor

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

wouterj commented Jan 17, 2013

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

@weaverryan
Copy link
Member

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

wouterj commented Jan 18, 2013

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

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

fabpot commented Feb 15, 2013

👍 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
Copy link
Contributor

vicb commented Feb 15, 2013

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

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

@wouterj
Copy link
Member

wouterj commented Mar 21, 2013

Closing this as it #2251 is merged

@wouterj wouterj closed this as completed Mar 21, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
actionable Clear and specific issues ready for anyone to take them.
Projects
None yet
Development

No branches or pull requests

5 participants