Skip to content

Commit df2bdb3

Browse files
javiereguiluzGuikingone
javiereguiluz
authored and
Guikingone
committed
Moved PHP-related code from Forms to the PHP templating page
1 parent 8a31539 commit df2bdb3

File tree

1 file changed

+216
-0
lines changed

1 file changed

+216
-0
lines changed

‎templating/PHP.rst

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -347,4 +347,220 @@ instance, to output something in a JavaScript script, use the ``js`` context::
347347

348348
<?php echo $view->escape($var, 'js') ?>
349349

350+
Form Theming in PHP
351+
-------------------
352+
353+
When using PHP as a templating engine, the only method to customize a fragment
354+
is to create a new template file - this is similar to the second method used by
355+
Twig.
356+
357+
The template file must be named after the fragment. You must create a ``integer_widget.html.php``
358+
file in order to customize the ``integer_widget`` fragment.
359+
360+
.. code-block:: html+php
361+
362+
<!-- app/Resources/views/form/integer_widget.html.php -->
363+
<div class="integer_widget">
364+
<?php echo $view['form']->block(
365+
$form,
366+
'form_widget_simple',
367+
array('type' => isset($type) ? $type : "number")
368+
) ?>
369+
</div>
370+
371+
Now that you've created the customized form template, you need to tell Symfony
372+
to use it. Inside the template where you're actually rendering your form,
373+
tell Symfony to use the theme via the ``setTheme()`` helper method::
374+
375+
<?php $view['form']->setTheme($form, array(':form')); ?>
376+
377+
<?php $view['form']->widget($form['age']) ?>
378+
379+
When the ``form.age`` widget is rendered, Symfony will use the customized
380+
``integer_widget.html.php`` template and the ``input`` tag will be wrapped in
381+
the ``div`` element.
382+
383+
If you want to apply a theme to a specific child form, pass it to the ``setTheme()``
384+
method::
385+
386+
<?php $view['form']->setTheme($form['child'], ':form'); ?>
387+
388+
.. note::
389+
390+
The ``:form`` syntax is based on the functional names for templates:
391+
``Bundle:Directory``. As the form directory lives in the
392+
``app/Resources/views`` directory, the ``Bundle`` part is empty, resulting
393+
in ``:form``.
394+
395+
Making Application-wide Customizations
396+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
397+
398+
If you'd like a certain form customization to be global to your application,
399+
you can accomplish this by making the form customizations in an external
400+
template and then importing it inside your application configuration.
401+
402+
By using the following configuration, any customized form fragments inside the
403+
``app/Resources/views/Form`` folder will be used globally when a
404+
form is rendered.
405+
406+
.. configuration-block::
407+
408+
.. code-block:: yaml
409+
410+
# app/config/config.yml
411+
framework:
412+
templating:
413+
form:
414+
resources:
415+
- 'AppBundle:Form'
416+
# ...
417+
418+
.. code-block:: xml
419+
420+
<!-- app/config/config.xml -->
421+
<?xml version="1.0" encoding="UTF-8" ?>
422+
<container xmlns="http://symfony.com/schema/dic/services"
423+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
424+
xmlns:framework="http://symfony.com/schema/dic/symfony"
425+
xsi:schemaLocation="http://symfony.com/schema/dic/services
426+
http://symfony.com/schema/dic/services/services-1.0.xsd
427+
http://symfony.com/schema/dic/symfony
428+
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
429+
430+
<framework:config>
431+
<framework:templating>
432+
<framework:form>
433+
<framework:resource>AppBundle:Form</framework:resource>
434+
</framework:form>
435+
</framework:templating>
436+
<!-- ... -->
437+
</framework:config>
438+
</container>
439+
440+
.. code-block:: php
441+
442+
// app/config/config.php
443+
// PHP
444+
$container->loadFromExtension('framework', array(
445+
'templating' => array(
446+
'form' => array(
447+
'resources' => array(
448+
'AppBundle:Form',
449+
),
450+
),
451+
),
452+
453+
// ...
454+
));
455+
456+
By default, the PHP engine uses a *div* layout when rendering forms. Some people,
457+
however, may prefer to render forms in a *table* layout. Use the ``FrameworkBundle:FormTable``
458+
resource to use such a layout:
459+
460+
.. configuration-block::
461+
462+
.. code-block:: yaml
463+
464+
# app/config/config.yml
465+
framework:
466+
templating:
467+
form:
468+
resources:
469+
- 'FrameworkBundle:FormTable'
470+
471+
.. code-block:: xml
472+
473+
<!-- app/config/config.xml -->
474+
<?xml version="1.0" encoding="UTF-8" ?>
475+
<container xmlns="http://symfony.com/schema/dic/services"
476+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
477+
xmlns:framework="http://symfony.com/schema/dic/symfony"
478+
xsi:schemaLocation="http://symfony.com/schema/dic/services
479+
http://symfony.com/schema/dic/services/services-1.0.xsd
480+
http://symfony.com/schema/dic/symfony
481+
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
482+
483+
<framework:config>
484+
<framework:templating>
485+
<framework:form>
486+
<resource>FrameworkBundle:FormTable</resource>
487+
</framework:form>
488+
</framework:templating>
489+
<!-- ... -->
490+
</framework:config>
491+
</container>
492+
493+
.. code-block:: php
494+
495+
// app/config/config.php
496+
$container->loadFromExtension('framework', array(
497+
'templating' => array(
498+
'form' => array(
499+
'resources' => array(
500+
'FrameworkBundle:FormTable',
501+
),
502+
),
503+
),
504+
505+
// ...
506+
));
507+
508+
If you only want to make the change in one template, add the following line to
509+
your template file rather than adding the template as a resource:
510+
511+
.. code-block:: html+php
512+
513+
<?php $view['form']->setTheme($form, array('FrameworkBundle:FormTable')); ?>
514+
515+
Note that the ``$form`` variable in the above code is the form view variable
516+
that you passed to your template.
517+
518+
Adding a "Required" Asterisk to Field Labels
519+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
520+
521+
If you want to denote all of your required fields with a required asterisk
522+
(``*``), you can do this by customizing the ``form_label`` fragment.
523+
524+
When using PHP as a templating engine you have to copy the content from the
525+
original template:
526+
527+
.. code-block:: html+php
528+
529+
<!-- form_label.html.php -->
530+
531+
<!-- original content -->
532+
<?php if ($required) { $label_attr['class'] = trim((isset($label_attr['class']) ? $label_attr['class'] : '').' required'); } ?>
533+
<?php if (!$compound) { $label_attr['for'] = $id; } ?>
534+
<?php if (!$label) { $label = $view['form']->humanize($name); } ?>
535+
<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>
536+
537+
<!-- customization -->
538+
<?php if ($required) : ?>
539+
<span class="required" title="This field is required">*</span>
540+
<?php endif ?>
541+
542+
Adding "help" Messages
543+
~~~~~~~~~~~~~~~~~~~~~~
544+
545+
You can also customize your form widgets to have an optional "help" message.
546+
547+
When using PHP as a templating engine you have to copy the content from the
548+
original template:
549+
550+
.. code-block:: html+php
551+
552+
<!-- form_widget_simple.html.php -->
553+
554+
<!-- Original content -->
555+
<input
556+
type="<?php echo isset($type) ? $view->escape($type) : 'text' ?>"
557+
<?php if (!empty($value)): ?>value="<?php echo $view->escape($value) ?>"<?php endif ?>
558+
<?php echo $view['form']->block($form, 'widget_attributes') ?>
559+
/>
560+
561+
<!-- Customization -->
562+
<?php if (isset($help)) : ?>
563+
<span class="help"><?php echo $view->escape($help) ?></span>
564+
<?php endif ?>
565+
350566
.. _`@Template`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/view

0 commit comments

Comments
 (0)