Skip to content

Update forms.rst #4782

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

Closed
wants to merge 2 commits into from
Closed

Update forms.rst #4782

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
88cf8f7
Update forms.rst
ifdattic Jan 6, 2015
f94b3b2
Update forms.rst
ifdattic Jan 17, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 41 additions & 32 deletions book/forms.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,8 @@ from inside a controller::
// src/AppBundle/Controller/DefaultController.php
namespace AppBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use AppBundle\Entity\Task;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what is the convention, but I personally try to sort alphabetically (groups included if needed) when possible.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't have a convention I think (the code doesn't have one either, does it? /cc @stof )

I always sort on length of the seperate namespace items, but I don't care much :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC PHP-CS-Fixer sorts them alphabetically.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From that I saw in others code I think most/all the time it's sorted alphabetically, just sometimes they are grouped adding the empty line between namespaces, but the groups are still sorted.

And when I use sublime editor it's not a lot of problems to do that, just add use statement anywhere, select a block and press F5, no need to process anything.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't separate use statements in several blocks in the code.

And we usually keep them sorted in new code, but we don't sort them in existing code when refactoring if there are not sorted properly to avoid useless conflicts when merging branches

use Symfony\Component\HttpFoundation\Request;

class DefaultController extends Controller
Expand Down Expand Up @@ -197,7 +197,7 @@ it into a format that's suitable for being rendered in an HTML form.
The form system is smart enough to access the value of the protected
``task`` property via the ``getTask()`` and ``setTask()`` methods on the
``Task`` class. Unless a property is public, it *must* have a "getter" and
"setter" method so that the Form component can get and put data onto the
"setter" methods so that the Form component can get and put data onto the
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think plural makes more sense in here

property. For a Boolean property, you can use an "isser" or "hasser" method
(e.g. ``isPublished()`` or ``hasReminder()``) instead of a getter (e.g.
``getPublished()`` or ``getReminder()``).
Expand Down Expand Up @@ -344,17 +344,6 @@ object.

.. configuration-block::

.. code-block:: yaml

# AppBundle/Resources/config/validation.yml
AppBundle\Entity\Task:
properties:
task:
- NotBlank: ~
dueDate:
- NotBlank: ~
- Type: \DateTime

.. code-block:: php-annotations
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From what I noticed annotations are used much more often for validation (and you probably already use ORM/ODM annotations for your entities) so I think it makes more sense to display them first

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The best practices now prefer annotations over any other config format. With that, the order changed to Annotation, Yaml, Xml and PHP. So 👍 to do it now


// AppBundle/Entity/Task.php
Expand All @@ -374,6 +363,18 @@ object.
protected $dueDate;
}

.. code-block:: yaml

# AppBundle/Resources/config/validation.yml
AppBundle\Entity\Task:
properties:
task:
- NotBlank: ~
dueDate:
- NotBlank: ~
- Type: \DateTime


.. code-block:: xml

<!-- AppBundle/Resources/config/validation.xml -->
Expand Down Expand Up @@ -542,16 +543,17 @@ This will call the static method ``determineValidationGroups()`` on the
The Form object is passed as an argument to that method (see next example).
You can also define whole logic inline by using a ``Closure``::

use Acme\AcmeBundle\Entity\Client;
use AppBundle\Entity\Client;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;

// ...
public function setDefaultOptions(OptionsResolverInterface $resolver)
{
$resolver->setDefaults(array(
'validation_groups' => function(FormInterface $form) {
'validation_groups' => function (FormInterface $form) {
$data = $form->getData();

if (Client::TYPE_PERSON == $data->getType()) {
return array('person');
}
Expand All @@ -565,16 +567,17 @@ Using the ``validation_groups`` option overrides the default validation
group which is being used. If you want to validate the default constraints
of the entity as well you have to adjust the option as follows::

use Acme\AcmeBundle\Entity\Client;
use AppBundle\Entity\Client;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;

// ...
public function setDefaultOptions(OptionsResolverInterface $resolver)
{
$resolver->setDefaults(array(
'validation_groups' => function(FormInterface $form) {
'validation_groups' => function (FormInterface $form) {
$data = $form->getData();

if (Client::TYPE_PERSON == $data->getType()) {
return array('Default', 'person');
}
Expand Down Expand Up @@ -1048,7 +1051,8 @@ that will house the logic for building the task form::
$builder
->add('task')
->add('dueDate', null, array('widget' => 'single_text'))
->add('save', 'submit');
->add('save', 'submit')
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Jumped semicolon to a next line as in this case it might not be the last call.
Also it might be useful to remove submit methods as by best practices they should be included in the template

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC, that best practice was about to be removed (or removed already). However, I'm still +1 on this change.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm just not sure it would be a good idea just remove all of them out of the blue. Because even thought it's a best practice this topic on forms is kind of a special one. So I'm not sure it would be a good idea to remove the submit button in the beginning of the topic. But later especially when you start to move forms to classes I think they could be safely removed. Still at some point it might be a good idea to mention that best practice is not to add buttons.

I would guess the best choice would be for docs team to give a quick glance to a topic and decide on the most user friendly solution.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I meant the practice itself was removed.

;
}

public function getName()
Expand Down Expand Up @@ -1116,7 +1120,8 @@ the choice is ultimately up to you.
$builder
->add('task')
->add('dueDate', null, array('mapped' => false))
->add('save', 'submit');
->add('save', 'submit')
;
}

Additionally, if there are any fields on the form that aren't included in
Expand Down Expand Up @@ -1148,7 +1153,7 @@ easy to use in your application.

# src/AppBundle/Resources/config/services.yml
services:
acme_demo.form.type.task:
app.form.type.task:
class: AppBundle\Form\Type\TaskType
tags:
- { name: form.type, alias: task }
Expand All @@ -1159,11 +1164,11 @@ easy to use in your application.
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd">

<services>
<service
id="acme_demo.form.type.task"
<service id="app.form.type.task"
class="AppBundle\Form\Type\TaskType">

<tag name="form.type" alias="task" />
Expand All @@ -1176,7 +1181,7 @@ easy to use in your application.
// src/AppBundle/Resources/config/services.php
$container
->register(
'acme_demo.form.type.task',
'app.form.type.task',
'AppBundle\Form\Type\TaskType'
)
->addTag('form.type', array(
Expand Down Expand Up @@ -1468,7 +1473,7 @@ renders the form:

{# app/Resources/views/Default/new.html.twig #}
{% form_theme form 'Form/fields.html.twig' %}

{# or if you want to use multiple themes #}
{% form_theme form 'Form/fields.html.twig' 'Form/fields2.html.twig' %}

{# ... render the form #}
Expand All @@ -1477,7 +1482,7 @@ renders the form:

<!-- app/Resources/views/Default/new.html.php -->
<?php $view['form']->setTheme($form, array('Form')) ?>

<!-- or if providing multiple themes -->
<?php $view['form']->setTheme($form, array('Form', 'Form2')) ?>

<!-- ... render the form -->
Expand Down Expand Up @@ -1519,7 +1524,7 @@ file, you can see every block needed to render a form and every default field
type.

In PHP, the fragments are individual template files. By default they are located in
the `Resources/views/Form` directory of the framework bundle (`view on GitHub`_).
the ``Resources/views/Form`` directory of the framework bundle (`view on GitHub`_).

Each fragment name follows the same basic pattern and is broken up into two pieces,
separated by a single underscore character (``_``). A few examples are:
Expand Down Expand Up @@ -1616,8 +1621,10 @@ file:
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:twig="http://symfony.com/schema/dic/twig"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/twig
http://symfony.com/schema/dic/twig/twig-1.0.xsd">

<twig:config>
<twig:form>
Expand Down Expand Up @@ -1702,8 +1709,10 @@ file:
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

<framework:config>
<framework:templating>
Expand All @@ -1725,7 +1734,7 @@ file:
'Form',
),
),
)
),
// ...
));

Expand Down