minor #6050 Lots of minor fixes & applying best practices to form coo…

…kbook doc (ThomasLandauer, WouterJ)

This PR was merged into the 2.3 branch.

Discussion
----------

Lots of minor fixes & applying best practices to form cookbook doc

This finishes #5569

| Q | A
| --- | ---
| doc fix? | yes
| New docs? | no
| Applies to | 2.3+
| Fixed tickets | -

Commits
-------

99cdc00 Revert some changes and fix template names
2b00abe Minor clarification
3ce46f6 Fixed file path
d227ffb Fixed typo
44d19de Added example for 'required' => false
ebb1e74 Update templating.rst
d806300 Typo: Removed comma
6e41f57 Another typo
a4f0318 Fixed typo
275c079 Removed unnecessary(?) YAML hint
9cd391b Note about nesting blocks and {% endblock NAME %}
41f7e6f Changed <meta http-equiv> to HTML5's <meta charset>

book/doctrine.rst

@@ -953,8 +953,8 @@ To relate the ``Category`` and ``Product`` entities, start by creating a
                 products:
                     targetEntity: Product
                     mappedBy: category
-            # don't forget to init the collection in the __construct() method
-            # of the entity
+        # Don't forget to initialize the collection in
+        # the __construct() method of the entity
 
     .. code-block:: xml
 
@@ -1096,7 +1096,7 @@ table, and ``product.category_id`` column, and new foreign key:
 
 .. note::
 
-    This task should only be really used during development. For a more robust
+    This command should only be used during development. For a more robust
     method of systematically updating your production database, read about
     `migrations`_.
 
@@ -1187,7 +1187,7 @@ You can also query in the other direction::
         // ...
     }
 
-In this case, the same things occurs: you first query out for a single ``Category``
+In this case, the same things occur: you first query out for a single ``Category``
 object, and then Doctrine makes a second query to retrieve the related ``Product``
 objects, but only once/if you ask for them (i.e. when you call ``->getProducts()``).
 The ``$products`` variable is an array of all ``Product`` objects that relate

book/forms.rst

@@ -212,8 +212,8 @@ Handling Form Submissions
 
 The second job of a form is to translate user-submitted data back to the
 properties of an object. To make this happen, the submitted data from the
-user must be written into the form. Add the following functionality to your
-controller::
+user must be written into the Form object. Add the following functionality to
+your controller::
 
     // ...
     use Symfony\Component\HttpFoundation\Request;
@@ -679,9 +679,14 @@ the documentation for each type.
     The most common option is the ``required`` option, which can be applied to
     any field. By default, the ``required`` option is set to ``true``, meaning
     that HTML5-ready browsers will apply client-side validation if the field
-    is left blank. If you don't want this behavior, either set the ``required``
-    option on your field to ``false`` or
-    :ref:`disable HTML5 validation <book-forms-html5-validation-disable>`.
+    is left blank. If you don't want this behavior, either
+    :ref:`disable HTML5 validation <book-forms-html5-validation-disable>`
+    or set the ``required`` option on your field to ``false``::
+    
+        ->add('dueDate', 'date', array(
+            'widget' => 'single_text',
+            'required' => false
+        ))
 
     Also note that setting the ``required`` option to ``true`` will **not**
     result in server-side validation to be applied. In other words, if a
@@ -920,7 +925,7 @@ specify it:
 
 Some field types have additional rendering options that can be passed
 to the widget. These options are documented with each type, but one common
-options is ``attr``, which allows you to modify attributes on the form element.
+option is ``attr``, which allows you to modify attributes on the form element.
 The following would add the ``task_field`` class to the rendered input text
 field:
 

book/templating.rst

@@ -201,7 +201,7 @@ First, build a base layout file:
         <!DOCTYPE html>
         <html>
             <head>
-                <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+                <meta charset="UTF-8">
                 <title>{% block title %}Test Application{% endblock %}</title>
             </head>
             <body>
@@ -226,7 +226,7 @@ First, build a base layout file:
         <!DOCTYPE html>
         <html>
             <head>
-                <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+                <meta charset="UTF-8">
                 <title><?php $view['slots']->output('title', 'Test Application') ?></title>
             </head>
             <body>
@@ -311,7 +311,7 @@ output might look like this:
     <!DOCTYPE html>
     <html>
         <head>
-            <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+            <meta charset="UTF-8">
             <title>My cool blog posts</title>
         </head>
         <body>

cookbook/form/form_customization.rst

@@ -243,7 +243,7 @@ directly in the template that's actually rendering the form.
 
 .. code-block:: html+twig
 
-    {% extends '::base.html.twig' %}
+    {% extends 'base.html.twig' %}
 
     {% form_theme form _self %}
 
@@ -282,7 +282,7 @@ can now re-use the form customization across many templates:
 
 .. code-block:: html+twig
 
-    {# app/Resources/views/Form/fields.html.twig #}
+    {# app/Resources/views/form/fields.html.twig #}
     {% block integer_widget %}
         <div class="integer_widget">
             {% set type = type|default('number') %}
@@ -298,7 +298,7 @@ tell Symfony to use the template via the ``form_theme`` tag:
 
 .. code-block:: html+twig
 
-    {% form_theme form 'AppBundle:Form:fields.html.twig' %}
+    {% form_theme form 'form/fields.html.twig' %}
 
     {{ form_widget(form.age) }}
 
@@ -314,13 +314,12 @@ name of all the templates as an array using the ``with`` keyword:
 
 .. code-block:: html+twig
 
-    {% form_theme form with ['::common.html.twig', ':Form:fields.html.twig',
-                             'AppBundle:Form:fields.html.twig'] %}
+    {% form_theme form with ['common.html.twig', 'form/fields.html.twig'] %}
 
     {# ... #}
 
-The templates can be located at different bundles and they can even be stored
-at the global ``app/Resources/views/`` directory.
+The templates can also be located in different bundles, use the functional name
+to reference these templates, e.g. ``AcmeFormExtraBundle:form:fields.html.twig``.
 
 Child Forms
 ...........
@@ -329,16 +328,16 @@ You can also apply a form theme to a specific child of your form:
 
 .. code-block:: html+twig
 
-    {% form_theme form.child 'AppBundle:Form:fields.html.twig' %}
+    {% form_theme form.child 'form/fields.html.twig' %}
 
 This is useful when you want to have a custom theme for a nested form that's
 different than the one of your main form. Just specify both your themes:
 
 .. code-block:: html+twig
 
-    {% form_theme form 'AppBundle:Form:fields.html.twig' %}
+    {% form_theme form 'form/fields.html.twig' %}
 
-    {% form_theme form.child 'AppBundle:Form:fields_child.html.twig' %}
+    {% form_theme form.child 'form/fields_child.html.twig' %}
 
 .. _cookbook-form-php-theming:
 
@@ -354,9 +353,13 @@ file in order to customize the ``integer_widget`` fragment.
 
 .. code-block:: html+php
 
-    <!-- app/Resources/views/Form/integer_widget.html.php -->
+    <!-- app/Resources/views/form/integer_widget.html.php -->
     <div class="integer_widget">
-        <?php echo $view['form']->block($form, 'form_widget_simple', array('type' => isset($type) ? $type : "number")) ?>
+        <?php echo $view['form']->block(
+            $form,
+            'form_widget_simple',
+            array('type' => isset($type) ? $type : "number")
+        ) ?>
     </div>
 
 Now that you've created the customized form template, you need to tell Symfony
@@ -367,7 +370,7 @@ tell Symfony to use the theme via the ``setTheme`` helper method:
 
 .. code-block:: php
 
-    <?php $view['form']->setTheme($form, array('AppBundle:Form')); ?>
+    <?php $view['form']->setTheme($form, array(':form')); ?>
 
     <?php $view['form']->widget($form['age']) ?>
 
@@ -380,7 +383,14 @@ method:
 
 .. code-block:: php
 
-    <?php $view['form']->setTheme($form['child'], 'AppBundle:Form/Child'); ?>
+    <?php $view['form']->setTheme($form['child'], ':form'); ?>
+
+.. note::
+
+    The ``:form`` syntax is based on the functional names for templates:
+    ``Bundle:Directory``. As the form directory lives in the
+    ``app/Resources/views`` directory, the ``Bundle`` part is empty, resulting
+    in ``:form``.
 
 .. _cookbook-form-twig-import-base-blocks:
 
@@ -454,8 +464,8 @@ Twig
 ~~~~
 
 By using the following configuration, any customized form blocks inside the
-``AppBundle:Form:fields.html.twig`` template will be used globally when a
-form is rendered.
+``form/fields.html.twig`` template will be used globally when a form is
+rendered.
 
 .. configuration-block::
 
@@ -465,15 +475,15 @@ form is rendered.
         twig:
             form:
                 resources:
-                    - 'AppBundle:Form:fields.html.twig'
+                    - 'form/fields.html.twig'
             # ...
 
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
         <twig:config>
             <twig:form>
-                <resource>AppBundle:Form:fields.html.twig</resource>
+                <resource>form/fields.html.twig</resource>
             </twig:form>
             <!-- ... -->
         </twig:config>
@@ -484,7 +494,7 @@ form is rendered.
         $container->loadFromExtension('twig', array(
             'form' => array(
                 'resources' => array(
-                    'AppBundle:Form:fields.html.twig',
+                    'form/fields.html.twig',
                 ),
             ),
 
@@ -666,7 +676,7 @@ customize the ``name`` field only:
     .. code-block:: html+php
 
         <!-- Main template -->
-        <?php echo $view['form']->setTheme($form, array('AppBundle:Form')); ?>
+        <?php echo $view['form']->setTheme($form, array(':form')); ?>
 
         <?php echo $view['form']->widget($form['name']); ?>
 
@@ -723,7 +733,7 @@ You can also override the markup for an entire field row using the same method:
     .. code-block:: html+php
 
         <!-- Main template -->
-        <?php echo $view['form']->setTheme($form, array('AppBundle:Form')); ?>
+        <?php echo $view['form']->setTheme($form, array(':form')); ?>
 
         <?php echo $view['form']->row($form['name']); ?>