Skip to content

Commit b2ffdbc

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '3.4' into 4.0
* 3.4: Remove redundant example configuration value Moved PHP-related code from Forms to the PHP templating page
2 parents 4ea2865 + c83113e commit b2ffdbc

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
@@ -343,53 +343,10 @@ different than the one of your main form. Just specify both your themes:
343343

344344
{% form_theme form.a_child_form 'form/fields_child.html.twig' %}
345345

346-
Form Theming in PHP
347-
-------------------
346+
.. _referencing-base-form-blocks-twig-specific:
348347

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

394351
So far, to override a particular form block, the best method is to copy
395352
the default block from `form_div_layout.html.twig`_, paste it into a different template,
@@ -445,16 +402,15 @@ the base block by using the ``parent()`` Twig function:
445402
templating engine. You have to manually copy the content from the base block
446403
to your new template file.
447404

405+
.. _twig:
406+
448407
Making Application-wide Customizations
449408
--------------------------------------
450409

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

455-
Twig
456-
~~~~
457-
458414
By using the following configuration, any customized form blocks inside the
459415
``form/fields.html.twig`` template will be used globally when a form is
460416
rendered.
@@ -551,125 +507,6 @@ your template file rather than adding the template as a resource:
551507
Note that the ``form`` variable in the above code is the form view variable
552508
that you passed to your template.
553509

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

@@ -905,7 +742,7 @@ Adding a "Required" Asterisk to Field Labels
905742
If you want to denote all of your required fields with a required asterisk (``*``),
906743
you can do this by customizing the ``form_label`` fragment.
907744

908-
In Twig, if you're making the form customization inside the same template as your
745+
If you're making the form customization inside the same template as your
909746
form, modify the ``use`` tag and add the following:
910747

911748
.. code-block:: html+twig
@@ -920,7 +757,7 @@ form, modify the ``use`` tag and add the following:
920757
{% endif %}
921758
{% endblock %}
922759

923-
In Twig, if you're making the form customization inside a separate template, use
760+
If you're making the form customization inside a separate template, use
924761
the following:
925762

926763
.. code-block:: html+twig
@@ -935,24 +772,6 @@ the following:
935772
{% endif %}
936773
{% endblock %}
937774

938-
When using PHP as a templating engine you have to copy the content from the
939-
original template:
940-
941-
.. code-block:: html+php
942-
943-
<!-- form_label.html.php -->
944-
945-
<!-- original content -->
946-
<?php if ($required) { $label_attr['class'] = trim((isset($label_attr['class']) ? $label_attr['class'] : '').' required'); } ?>
947-
<?php if (!$compound) { $label_attr['for'] = $id; } ?>
948-
<?php if (!$label) { $label = $view['form']->humanize($name); } ?>
949-
<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>
950-
951-
<!-- customization -->
952-
<?php if ($required) : ?>
953-
<span class="required" title="This field is required">*</span>
954-
<?php endif ?>
955-
956775
.. tip::
957776

958777
See :ref:`form-theming-methods` for how to apply this customization.
@@ -973,7 +792,7 @@ Adding "help" Messages
973792

974793
You can also customize your form widgets to have an optional "help" message.
975794

976-
In Twig, if you're making the form customization inside the same template as your
795+
If you're making the form customization inside the same template as your
977796
form, modify the ``use`` tag and add the following:
978797

979798
.. code-block:: html+twig
@@ -988,7 +807,7 @@ form, modify the ``use`` tag and add the following:
988807
{% endif %}
989808
{% endblock %}
990809

991-
In Twig, if you're making the form customization inside a separate template, use
810+
If you're making the form customization inside a separate template, use
992811
the following:
993812

994813
.. code-block:: html+twig
@@ -1003,25 +822,6 @@ the following:
1003822
{% endif %}
1004823
{% endblock %}
1005824

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

1027827
.. code-block:: twig

0 commit comments

Comments
 (0)