Skip to content

Commit 9bd5f8b

Browse files
javiereguiluzjaviereguiluz
committed
Moved PHP-related code from Forms to the PHP templating page
1 parent 24555f3 commit 9bd5f8b

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

305305
{% form_theme form.a_child_form 'form/fields_child.html.twig' %}
306306

307-
Form Theming in PHP
308-
-------------------
307+
.. _referencing-base-form-blocks-twig-specific:
309308

310-
When using PHP as a templating engine, the only method to customize a fragment
311-
is to create a new template file - this is similar to the second method used by
312-
Twig.
313-
314-
The template file must be named after the fragment. You must create a ``integer_widget.html.php``
315-
file in order to customize the ``integer_widget`` fragment.
316-
317-
.. code-block:: html+php
318-
319-
<!-- app/Resources/views/form/integer_widget.html.php -->
320-
<div class="integer_widget">
321-
<?php echo $view['form']->block(
322-
$form,
323-
'form_widget_simple',
324-
array('type' => isset($type) ? $type : "number")
325-
) ?>
326-
</div>
327-
328-
Now that you've created the customized form template, you need to tell Symfony
329-
to use it. Inside the template where you're actually rendering your form,
330-
tell Symfony to use the theme via the ``setTheme()`` helper method::
331-
332-
<?php $view['form']->setTheme($form, array(':form')); ?>
333-
334-
<?php $view['form']->widget($form['age']) ?>
335-
336-
When the ``form.age`` widget is rendered, Symfony will use the customized
337-
``integer_widget.html.php`` template and the ``input`` tag will be wrapped in
338-
the ``div`` element.
339-
340-
If you want to apply a theme to a specific child form, pass it to the ``setTheme()``
341-
method::
342-
343-
<?php $view['form']->setTheme($form['child'], ':form'); ?>
344-
345-
.. note::
346-
347-
The ``:form`` syntax is based on the functional names for templates:
348-
``Bundle:Directory``. As the form directory lives in the
349-
``app/Resources/views`` directory, the ``Bundle`` part is empty, resulting
350-
in ``:form``.
351-
352-
Referencing base Form Blocks (Twig specific)
353-
--------------------------------------------
309+
Referencing base Form Blocks
310+
----------------------------
354311

355312
So far, to override a particular form block, the best method is to copy
356313
the default block from `form_div_layout.html.twig`_, paste it into a different template,
@@ -406,16 +363,15 @@ the base block by using the ``parent()`` Twig function:
406363
templating engine. You have to manually copy the content from the base block
407364
to your new template file.
408365

366+
.. _twig:
367+
409368
Making Application-wide Customizations
410369
--------------------------------------
411370

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

416-
Twig
417-
~~~~
418-
419375
By using the following configuration, any customized form blocks inside the
420376
``form/fields.html.twig`` template will be used globally when a form is
421377
rendered.
@@ -512,125 +468,6 @@ your template file rather than adding the template as a resource:
512468
Note that the ``form`` variable in the above code is the form view variable
513469
that you passed to your template.
514470

515-
PHP
516-
~~~
517-
518-
By using the following configuration, any customized form fragments inside the
519-
``app/Resources/views/Form`` folder will be used globally when a
520-
form is rendered.
521-
522-
.. configuration-block::
523-
524-
.. code-block:: yaml
525-
526-
# app/config/config.yml
527-
framework:
528-
templating:
529-
form:
530-
resources:
531-
- 'AppBundle:Form'
532-
# ...
533-
534-
.. code-block:: xml
535-
536-
<!-- app/config/config.xml -->
537-
<?xml version="1.0" encoding="UTF-8" ?>
538-
<container xmlns="http://symfony.com/schema/dic/services"
539-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
540-
xmlns:framework="http://symfony.com/schema/dic/symfony"
541-
xsi:schemaLocation="http://symfony.com/schema/dic/services
542-
http://symfony.com/schema/dic/services/services-1.0.xsd
543-
http://symfony.com/schema/dic/symfony
544-
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
545-
546-
<framework:config>
547-
<framework:templating>
548-
<framework:form>
549-
<framework:resource>AppBundle:Form</framework:resource>
550-
</framework:form>
551-
</framework:templating>
552-
<!-- ... -->
553-
</framework:config>
554-
</container>
555-
556-
.. code-block:: php
557-
558-
// app/config/config.php
559-
// PHP
560-
$container->loadFromExtension('framework', array(
561-
'templating' => array(
562-
'form' => array(
563-
'resources' => array(
564-
'AppBundle:Form',
565-
),
566-
),
567-
),
568-
569-
// ...
570-
));
571-
572-
By default, the PHP engine uses a *div* layout when rendering forms. Some people,
573-
however, may prefer to render forms in a *table* layout. Use the ``FrameworkBundle:FormTable``
574-
resource to use such a layout:
575-
576-
.. configuration-block::
577-
578-
.. code-block:: yaml
579-
580-
# app/config/config.yml
581-
framework:
582-
templating:
583-
form:
584-
resources:
585-
- 'FrameworkBundle:FormTable'
586-
587-
.. code-block:: xml
588-
589-
<!-- app/config/config.xml -->
590-
<?xml version="1.0" encoding="UTF-8" ?>
591-
<container xmlns="http://symfony.com/schema/dic/services"
592-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
593-
xmlns:framework="http://symfony.com/schema/dic/symfony"
594-
xsi:schemaLocation="http://symfony.com/schema/dic/services
595-
http://symfony.com/schema/dic/services/services-1.0.xsd
596-
http://symfony.com/schema/dic/symfony
597-
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
598-
599-
<framework:config>
600-
<framework:templating>
601-
<framework:form>
602-
<resource>FrameworkBundle:FormTable</resource>
603-
</framework:form>
604-
</framework:templating>
605-
<!-- ... -->
606-
</framework:config>
607-
</container>
608-
609-
.. code-block:: php
610-
611-
// app/config/config.php
612-
$container->loadFromExtension('framework', array(
613-
'templating' => array(
614-
'form' => array(
615-
'resources' => array(
616-
'FrameworkBundle:FormTable',
617-
),
618-
),
619-
),
620-
621-
// ...
622-
));
623-
624-
If you only want to make the change in one template, add the following line to
625-
your template file rather than adding the template as a resource:
626-
627-
.. code-block:: html+php
628-
629-
<?php $view['form']->setTheme($form, array('FrameworkBundle:FormTable')); ?>
630-
631-
Note that the ``$form`` variable in the above code is the form view variable
632-
that you passed to your template.
633-
634471
How to Customize an individual Field
635472
------------------------------------
636473

@@ -866,7 +703,7 @@ Adding a "Required" Asterisk to Field Labels
866703
If you want to denote all of your required fields with a required asterisk (``*``),
867704
you can do this by customizing the ``form_label`` fragment.
868705

869-
In Twig, if you're making the form customization inside the same template as your
706+
If you're making the form customization inside the same template as your
870707
form, modify the ``use`` tag and add the following:
871708

872709
.. code-block:: html+twig
@@ -881,7 +718,7 @@ form, modify the ``use`` tag and add the following:
881718
{% endif %}
882719
{% endblock %}
883720

884-
In Twig, if you're making the form customization inside a separate template, use
721+
If you're making the form customization inside a separate template, use
885722
the following:
886723

887724
.. code-block:: html+twig
@@ -896,24 +733,6 @@ the following:
896733
{% endif %}
897734
{% endblock %}
898735

899-
When using PHP as a templating engine you have to copy the content from the
900-
original template:
901-
902-
.. code-block:: html+php
903-
904-
<!-- form_label.html.php -->
905-
906-
<!-- original content -->
907-
<?php if ($required) { $label_attr['class'] = trim((isset($label_attr['class']) ? $label_attr['class'] : '').' required'); } ?>
908-
<?php if (!$compound) { $label_attr['for'] = $id; } ?>
909-
<?php if (!$label) { $label = $view['form']->humanize($name); } ?>
910-
<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>
911-
912-
<!-- customization -->
913-
<?php if ($required) : ?>
914-
<span class="required" title="This field is required">*</span>
915-
<?php endif ?>
916-
917736
.. tip::
918737

919738
See :ref:`form-theming-methods` for how to apply this customization.
@@ -934,7 +753,7 @@ Adding "help" Messages
934753

935754
You can also customize your form widgets to have an optional "help" message.
936755

937-
In Twig, if you're making the form customization inside the same template as your
756+
If you're making the form customization inside the same template as your
938757
form, modify the ``use`` tag and add the following:
939758

940759
.. code-block:: html+twig
@@ -949,7 +768,7 @@ form, modify the ``use`` tag and add the following:
949768
{% endif %}
950769
{% endblock %}
951770

952-
In Twig, if you're making the form customization inside a separate template, use
771+
If you're making the form customization inside a separate template, use
953772
the following:
954773

955774
.. code-block:: html+twig
@@ -964,25 +783,6 @@ the following:
964783
{% endif %}
965784
{% endblock %}
966785

967-
When using PHP as a templating engine you have to copy the content from the
968-
original template:
969-
970-
.. code-block:: html+php
971-
972-
<!-- form_widget_simple.html.php -->
973-
974-
<!-- Original content -->
975-
<input
976-
type="<?php echo isset($type) ? $view->escape($type) : 'text' ?>"
977-
<?php if (!empty($value)): ?>value="<?php echo $view->escape($value) ?>"<?php endif ?>
978-
<?php echo $view['form']->block($form, 'widget_attributes') ?>
979-
/>
980-
981-
<!-- Customization -->
982-
<?php if (isset($help)) : ?>
983-
<span class="help"><?php echo $view->escape($help) ?></span>
984-
<?php endif ?>
985-
986786
To render a help message below a field, pass in a ``help`` variable:
987787

988788
.. code-block:: twig

0 commit comments

Comments
 (0)