8000 Merge pull request #382 from vicb/form-theme · lmcd/symfony-docs@ec5b4a4 · GitHub
[go: up one dir, main page]

Skip to content

Commit ec5b4a4

Browse files
committed
Merge pull request symfony#382 from vicb/form-theme
Form theme
2 parents 3c1723b + 06b48ed commit ec5b4a4

File tree

2 files changed

+84
-83
lines changed

2 files changed

+84
-83
lines changed

book/forms.rst

Lines changed: 47 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,13 @@ going to need to build a form. But before you begin, let's focus on the generic
3030
3131
// src/Acme/StoreBundle/Entity/Product.php
3232
namespace Acme\StoreBundle\Entity;
33-
33+
3434
class Product
3535
{
3636
public $name;
37-
37+
3838
protected $price;
39-
39+
4040
public function getPrice()
4141
{
4242
return $this->price;
@@ -53,9 +53,9 @@ going to need to build a form. But before you begin, let's focus on the generic
5353
If you're coding along with this example, be sure to create and enable
5454
the ``AcmeStoreBundle``. Run the following command and follow the on-screen
5555
directions:
56-
56+
5757
.. code-block:: text
58-
58+
5959
php app/console init:bundle Acme/StoreBundle src/
6060
6161
This type of class is commonly called a "plain-old-PHP-object" because, so far,
@@ -134,17 +134,17 @@ helper functions:
134134
.. code-block:: html+jinja
135135

136136
{# src/Acme/StoreBundle/Resources/views/Default/index.html.twig #}
137-
137+
138138
<form action="{{ path('store_product') }}" method="post" {{ form_enctype(form) }}>
139139
{{ form_widget(form) }}
140-
140+
141141
<input type="submit" />
142142
</form>
143143

144144
.. code-block:: html+php
145- 10000
145+
146146
<?php // src/Acme/StoreBundle/Resources/views/Default/index.html.php ?>
147-
147+
148148
<form action="<?php echo $view['router']->generate('store_product') ?>" method="post" <?php echo $view['form']->enctype($form) ?> >
149149
<?php echo $view['form']->widget($form) ?>
150150

@@ -187,7 +187,7 @@ controller:
187187
{
188188
// just setup a fresh $product object (no dummy data)
189189
$product = new Product();
190-
190+
191191
$form = $this->createFormBuilder($product)
192192
->add('name', 'text')
193193
->add('price', 'money', array('currency' => 'USD'))
@@ -203,7 +203,7 @@ controller:
203203
return $this->redirect($this->generateUrl('store_product_success'));
204204
}
205205
}
206-
206+
207207
// ...
208208
}
209209
@@ -221,7 +221,7 @@ of the ``$product`` object. This all happens via the ``bindRequest()`` method.
221221
222222
$product = new Product();
223223
$product->name = 'Test product';
224-
224+
225225
$form->bindRequest($this->get('request'));
226226
echo $product->name;
227227
@@ -328,7 +328,7 @@ number:
328328
public static function loadValidatorMetadata(ClassMetadata $metadata)
329329
{
330330
$metadata->addPropertyConstraint('name', new NotBlank());
331-
331+
332332
$metadata->addPropertyConstraint('price', new NotBlank());
333333
$metadata->addPropertyConstraint('price', new Min(0));
334334
}
@@ -423,10 +423,10 @@ guess (``text``).
423423

424424
The ``createFormBuilder()`` method takes up to two arguments neither
425425
of which are required):
426-
426+
427427
* The default data to initialize the form fields. This argument can be an
428428
associative array or a plain old PHP object like in this example;
429-
429+
430430
* an array of options for the form.
431431

432432
This example is pretty trivial, but field guessing can be a major time saver.
@@ -449,7 +449,7 @@ of code. Of course, you'll usually need much more flexibility when rendering:
449449
.. code-block:: html+jinja
450450

451451
{# src/Acme/StoreBundle/Resources/views/Default/index.html.twig #}
452-
452+
453453
<form action="{{ path('store_product') }}" method="post" {{ form_enctype(form) }}>
454454
{{ form_errors(form) }}
455455

@@ -462,9 +462,9 @@ of code. Of course, you'll usually need much more flexibility when rendering:
462462
</form>
463463

464464
.. code-block:: html+php
465-
465+
466466
<?php // src/Acme/StoreBundle/Resources/views/Default/index.html.php ?>
467-
467+
468468
<form action="<?php echo $view['router']->generate('store_product') ?>" method="post" <?php echo $view['form']->enctype($form) ?>>
469469
<?php echo $view['form']->errors($form) ?>
470470

@@ -631,30 +631,30 @@ It can be used to quickly build a form object in the controller:
631631
{
632632
$product = // ...
633633
$form = $this->createForm(new ProductType(), $product);
634-
634+
635635
// ...
636636
}
637637
638638
.. note::
639639
You can also set the data on the form via the ``setData()`` method:
640-
640+
641641
.. code-block:: php
642-
642+
643643
$form = $this->createForm(new ProductType());
644644
F438 $form->setData($product);
645645
646646
If you use the ``setData`` method - and want to take advantage of field
647647
type guessing, be sure to add the following to your form class:
648-
648+
649649
.. code-block:: php
650-
650+
651651
public function getDefaultOptions(array $options)
652652
{
653653
return array(
654654
'data_class' => 'Acme\StoreBundle\Entity\Product',
655655
);
656656
}
657-
657+
658658
This is necessary because the object is passed to the form after field
659659
type guessing.
660660

@@ -859,7 +859,7 @@ the following inside ``ProductType``:
859859
// ...
860860
861861
$builder->add('reviews', 'collection', array(
862-
'type' => new ProductReviewType(),
862+
'type' => new ProductReviewType(),
863863
));
864864
}
865865
@@ -885,10 +885,10 @@ do this, create a new template file that will store the new markup:
885885
.. configuration-block::
886886

887887
.. code-block:: html+jinja
888-
888+
889889
{# src/Acme/StoreBundle/Resources/views/Form/fields.html.twig #}
890-
{% extends 'TwigBundle:Form:div_layout.html.twig' %}
891-
890+
{% extends 'div_layout.html.twig' %}
891+
892892
{% block field_row %}
893893
{% spaceless %}
894894
<div class="form_row">
@@ -919,7 +919,7 @@ the form:
919919

920920
{# src/Acme/StoreBundle/Resources/views/Default/index.html.twig #}
921921
{% form_theme form 'AcmeStoreBundle:Form:fields.html.twig' %}
922-
922+
923923
<form ...>
924924

925925
The ``form_theme`` tag "imports" the template and uses all of its form-related
@@ -942,7 +942,7 @@ Form Template Blocks
942942
Every part of a form that is rendered - HTML form elements, errors, labels, etc
943943
- is defined in a base template as individual Twig blocks. By default, every
944944
block needed is defined in the `div_layout.html.twig`_ file that lives inside
945-
the core ``TwigBundle``. Inside this file, you can see every block needed
945+
the `Twig Bridge`_. Inside this file, you can see every block needed
946946
to render a form and every default field type.
947947

948948
Each block follows the same basic pattern and is broken up into two pieces,
@@ -978,14 +978,14 @@ a form that can be rendered:
978978
By knowing the field type (e.g. ``textarea``) and which part you want to
979979
customize (e.g. ``widget``), you can construct the block name that needs
980980
to be overridden (e.g. ``textarea_widget``). The best way to customize the
981-
block is to copy it from ``div_layout.html.twig`` to a new template, customize
981+
block is to copy it from `div_layout.html.twig`_ to a new template, customize
982982
it, and then use the ``form_theme`` tag as shown in the earlier example.
983983

984984
Form Type Block Inheritance
985985
~~~~~~~~~~~~~~~~~~~~~~~~~~~
986986

987987
In some cases, the block you want to customize will appear to be missing.
988-
For example, if you look in the ``div_layout.html.twig`` file, you'll find
988+
For example, if you look in the `div_layout.html.twig`_ file, you'll find
989989
no ``textarea_errors`` block. So how are the errors for a textarea field
990990
rendered?
991991

@@ -1010,18 +1010,18 @@ templates in your application. To automatically include the customized blocks
10101010
from the ``fields.html.twig`` template created earlier, modify your application
10111011
configuration file:
10121012

1013-
.. configuration-block::
1013+
.. configuration-block::
10141014

10151015
.. code-block:: yaml
1016-
1016+
10171017
# app/config/config.yml
10181018
twig:
10191019
form:
10201020
resources: ['AcmeStoreBundle:Form:fields.html.twig']
10211021
# ...
1022-
1022+
10231023
.. code-block:: xml
1024-
1024+
10251025
<!-- app/config/config.xml -->
10261026
<twig:config ...>
10271027
<twig:form>
@@ -1039,40 +1039,40 @@ configuration file:
10391039
));
10401040
10411041
Any blocks inside the ``fields.html.twig`` template are now used globally
1042-
to define form output.
1042+
to define form output.
10431043

10441044
.. sidebar:: Customizing Form Output all in a Single File
10451045

10461046
You can also customize a form block right inside the template where that
10471047
customization is needed. Note that this method will only work if the
10481048
template used extends some base template via the ``{% extends %}``:
1049-
1049+
10501050
.. code-block:: html+jinja
1051-
1051+
10521052
{% extends '::base.html.twig' %}
1053-
1053+
10541054
{% form_theme form _self %}
1055-
{% use 'TwigBundle:Form:div_layout.html.twig' %}
1055+
{% use 'div_layout.html.twig' %}
10561056

10571057
{% block field_row %}
10581058
{# custom field row output #}
10591059
{% endblock field_row %}
10601060

10611061
{% block content %}
10621062
{# ... #}
1063-
1063+
10641064
{{ form_row(form.name) }}
10651065
{% endblock %}
10661066

10671067
The ``{% form_theme form _self %}`` tag allows form blocks to be customized
10681068
directly inside the template that will use those customizations. Use
10691069
this method to quickly make form output customizations that will only
10701070
ever be needed in a single template.
1071-
1071+
10721072
The ``use`` tag is also helpful as it gives you access to all of the
1073-
blocks defined inside ``div_layout.html.twig``. For example, this ``use``
1073+
blocks defined inside `div_layout.html.twig`_. For example, this ``use``
10741074
statement is necessary to make the following form customization, as it
1075-
gives you access to the ``attributes`` block defined in ``div_layout.html.twig``:
1075+
gives you access to the ``attributes`` block defined in `div_layout.html.twig`_:
10761076

10771077
.. code-block:: html+jinja
10781078

@@ -1158,5 +1158,6 @@ Learn more from the Cookbook
11581158
* :doc:`/cookbook/form/twig_form_customization`
11591159

11601160
.. _`Symfony2 Form Component`: https://github.com/symfony/Form
1161-
.. _`div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/TwigBundle/Resources/views/Form/div_layout.html.twig
1161+
.. _`Twig Bridge`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bridge/Twig
1162+
.. _`div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/div_layout.html.twig
11621163
.. _`Cross-site request forgery`: http://en.wikipedia.org/wiki/Cross-site_request_forgery

0 commit comments

Comments
 (0)
0