Skip to content

Commit c83113e

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '2.8' into 3.4
* 2.8: Moved PHP-related code from Forms to the PHP templating page
2 parents 07b3a28 + b16522c commit c83113e

File tree

2 files changed

+225
-209
lines changed

2 files changed

+225
-209
lines changed

‎form/form_customization.rst

Lines changed: 9 additions & 209 deletions
Original file line numberDiff line numberDiff line change
@@ -346,53 +346,10 @@ different than the one of your main form. Just specify both your themes:
346346

347347
{% form_theme form.a_child_form 'form/fields_child.html.twig' %}
348348

349-
Form Theming in PHP
350-
-------------------
349+
.. _referencing-base-form-blocks-twig-specific:
351350

352-
When using PHP as a templating engine, the only method to customize a fragment
353-
is to create a new template file - this is similar to the second method used by
354-
Twig.
355-
356-
The template file must be named after the fragment. You must create a ``integer_widget.html.php``
357-
file in order to customize the ``integer_widget`` fragment.
358-
359-
.. code-block:: html+php
360-
361-
<!-- app/Resources/views/form/integer_widget.html.php -->
362-
<div class="integer_widget">
363-
<?php echo $view['form']->block(
364-
$form,
365-
'form_widget_simple',
366-
array('type' => isset($type) ? $type : "number")
367-
) ?>
368-
</div>
369-
370-
Now that you've created the customized form template, you need to tell Symfony
371-
to use it. Inside the template where you're actually rendering your form,
372-
tell Symfony to use the theme via the ``setTheme()`` helper method::
373-
374-
<?php $view['form']->setTheme($form, array(':form')); ?>
375-
376-
<?php $view['form']->widget($form['age']) ?>
377-
378-
When the ``form.age`` widget is rendered, Symfony will use the customized
379-
``integer_widget.html.php`` template and the ``input`` tag will be wrapped in
380-
the ``div`` element.
381-
382-
If you want to apply a theme to a specific child form, pass it to the ``setTheme()``
383-
method::
384-
385-
<?php $view['form']->setTheme($form['child'], ':form'); ?>
386-
387-
.. note::
388-
389-
The ``:form`` syntax is based on the functional names for templates:
390-
``Bundle:Directory``. As the form directory lives in the
391-
``app/Resources/views`` directory, the ``Bundle`` part is empty, resulting
392-
in ``:form``.
393-
394-
Referencing base Form Blocks (Twig specific)
395-
--------------------------------------------
351+
Referencing base Form Blocks
352+
----------------------------
396353

397354
So far, to override a particular form block, the best method is to copy
398355
the default block from `form_div_layout.html.twig`_, paste it into a different template,
@@ -448,16 +405,15 @@ the base block by using the ``parent()`` Twig function:
448405
templating engine. You have to manually copy the content from the base block
449406
to your new template file.
450407

408+
.. _twig:
409+
451410
Making Application-wide Customizations
452411
--------------------------------------
453412

454413
If you'd like a certain form customization to be global to your application,
455414
you can accomplish this by making the form customizations in an external
456415
template and then importing it inside your application configuration.
457416

458-
Twig
459-
~~~~
460-
461417
By using the following configuration, any customized form blocks inside the
462418
``form/fields.html.twig`` template will be used globally when a form is
463419
rendered.
@@ -554,125 +510,6 @@ your template file rather than adding the template as a resource:
554510
Note that the ``form`` variable in the above code is the form view variable
555511
that you passed to your template.
556512

557-
PHP
558-
~~~
559-
560-
By using the following configuration, any customized form fragments inside the
561-
``app/Resources/views/Form`` folder will be used globally when a
562-
form is rendered.
563-
564-
.. configuration-block::
565-
566-
.. code-block:: yaml
567-
568-
# app/config/config.yml
569-
framework:
570-
templating:
571-
form:
572-
resources:
573-
- 'AppBundle:Form'
574-
# ...
575-
576-
.. code-block:: xml
577-
578-
<!-- app/config/config.xml -->
579-
<?xml version="1.0" encoding="UTF-8" ?>
580-
<container xmlns="http://symfony.com/schema/dic/services"
581-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
582-
xmlns:framework="http://symfony.com/schema/dic/symfony"
583-
xsi:schemaLocation="http://symfony.com/schema/dic/services
584-
http://symfony.com/schema/dic/services/services-1.0.xsd
585-
http://symfony.com/schema/dic/symfony
586-
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
587-
588-
<framework:config>
589-
<framework:templating>
590-
<framework:form>
591-
<framework:resource>AppBundle:Form</framework:resource>
592-
</framework:form>
593-
</framework:templating>
594-
<!-- ... -->
595-
</framework:config>
596-
</container>
597-
598-
.. code-block:: php
599-
600-
// app/config/config.php
601-
// PHP
602-
$container->loadFromExtension('framework', array(
603-
'templating' => array(
604-
'form' => array(
605-
'resources' => array(
606-
'AppBundle:Form',
607-
),
608-
),
609-
),
610-
611-
// ...
612-
));
613-
614-
By default, the PHP engine uses a *div* layout when rendering forms. Some people,
615-
however, may prefer to render forms in a *table* layout. Use the ``FrameworkBundle:FormTable``
616-
resource to use such a layout:
617-
618-
.. configuration-block::
619-
620-
.. code-block:: yaml
621-
622-
# app/config/config.yml
623-
framework:
624-
templating:
625-
form:
626-
resources:
627-
- 'FrameworkBundle:FormTable'
628-
629-
.. code-block:: xml
630-
631-
<!-- app/config/config.xml -->
632-
<?xml version="1.0" encoding="UTF-8" ?>
633-
<container xmlns="http://symfony.com/schema/dic/services"
634-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
635-
xmlns:framework="http://symfony.com/schema/dic/symfony"
636-
xsi:schemaLocation="http://symfony.com/schema/dic/services
637-
http://symfony.com/schema/dic/services/services-1.0.xsd
638-
http://symfony.com/schema/dic/symfony
639-
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
640-
641-
<framework:config>
642-
<framework:templating>
643-
<framework:form>
644-
<resource>FrameworkBundle:FormTable</resource>
645-
</framework:form>
646-
</framework:templating>
647-
<!-- ... -->
648-
</framework:config>
649-
</container>
650-
651-
.. code-block:: php
652-
653-
// app/config/config.php
654-
$container->loadFromExtension('framework', array(
655-
'templating' => array(
656-
'form' => array(
657-
'resources' => array(
658-
'FrameworkBundle:FormTable',
659-
),
660-
),
661-
),
662-
663-
// ...
664-
));
665-
666-
If you only want to make the change in one template, add the following line to
667-
your template file rather than adding the template as a resource:
668-
669-
.. code-block:: html+php
670-
671-
<?php $view['form']->setTheme($form, array('FrameworkBundle:FormTable')); ?>
672-
673-
Note that the ``$form`` variable in the above code is the form view variable
674-
that you passed to your template.
675-
676513
How to Customize an individual Field
677514
------------------------------------
678515

@@ -908,7 +745,7 @@ Adding a "Required" Asterisk to Field Labels
908745
If you want to denote all of your required fields with a required asterisk (``*``),
909746
you can do this by customizing the ``form_label`` fragment.
910747

911-
In Twig, if you're making the form customization inside the same template as your
748+
If you're making the form customization inside the same template as your
912749
form, modify the ``use`` tag and add the following:
913750

914751
.. code-block:: html+twig
@@ -923,7 +760,7 @@ form, modify the ``use`` tag and add the following:
923760
{% endif %}
924761
{% endblock %}
925762

926-
In Twig, if you're making the form customization inside a separate template, use
763+
If you're making the form customization inside a separate template, use
927764
the following:
928765

929766
.. code-block:: html+twig
@@ -938,24 +775,6 @@ the following:
938775
{% endif %}
939776
{% endblock %}
940777

941-
When using PHP as a templating engine you have to copy the content from the
942-
original template:
943-
944-
.. code-block:: html+php
945-
946-
<!-- form_label.html.php -->
947-
948-
<!-- original content -->
949-
<?php if ($required) { $label_attr['class'] = trim((isset($label_attr['class']) ? $label_attr['class'] : '').' required'); } ?>
950-
<?php if (!$compound) { $label_attr['for'] = $id; } ?>
951-
<?php if (!$label) { $label = $view['form']->humanize($name); } ?>
952-
<label <?php foreach ($label_attr as $k => $v) { printf('%s="%s" ', $view->escape($k), $view->escape($v)); } ?>><?php echo $view->escape($view['translator']->trans($label, array(), $translation_domain)) ?></label>
953-
954-
<!-- customization -->
955-
<?php if ($required) : ?>
956-
<span class="required" title="This field is required">*</span>
957-
<?php endif ?>
958-
959778
.. tip::
960779

961780
See :ref:`form-theming-methods` for how to apply this customization.
@@ -976,7 +795,7 @@ Adding "help" Messages
976795

977796
You can also customize your form widgets to have an optional "help" message.
978797

979-
In Twig, if you're making the form customization inside the same template as your
798+
If you're making the form customization inside the same template as your
980799
form, modify the ``use`` tag and add the following:
981800

982801
.. code-block:: html+twig
@@ -991,7 +810,7 @@ form, modify the ``use`` tag and add the following:
991810
{% endif %}
992811
{% endblock %}
993812

994-
In Twig, if you're making the form customization inside a separate template, use
813+
If you're making the form customization inside a separate template, use
995814
the following:
996815

997816
.. code-block:: html+twig
@@ -1006,25 +825,6 @@ the following:
1006825
{% endif %}
1007826
{% endblock %}
1008827

1009-
When using PHP as a templating engine you have to copy the content from the
1010-
original template:
1011-
1012-
.. code-block:: html+php
1013-
1014-
<!-- form_widget_simple.html.php -->
1015-
1016-
<!-- Original content -->
1017-
<input
1018-
type="<?php echo isset($type) ? $view->escape($type) : 'text' ?>"
1019-
<?php if (!empty($value)): ?>value="<?php echo $view->escape($value) ?>"<?php endif ?>
1020-
<?php echo $view['form']->block($form, 'widget_attributes') ?>
1021-
/>
1022-
1023-
<!-- Customization -->
1024-
<?php if (isset($help)) : ?>
1025-
<span class="help"><?php echo $view->escape($help) ?></span>
1026-
<?php endif ?>
1027-
1028828
To render a help message below a field, pass in a ``help`` variable:
1029829

1030830
.. code-block:: twig

0 commit comments

Comments
 (0)