Skip to content

Moved PHP-related code from Forms to the PHP templating page #10047

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 12, 2018
Merged

Moved PHP-related code from Forms to the PHP templating page #10047

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
218 changes: 9 additions & 209 deletions form/form_customization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -304,53 +304,10 @@ different than the one of your main form. Just specify both your themes:

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

Form Theming in PHP
-------------------
.. _referencing-base-form-blocks-twig-specific:

When using PHP as a templating engine, the only method to customize a fragment
is to create a new template file - this is similar to the second method used by
Twig.

The template file must be named after the fragment. You must create a ``integer_widget.html.php``
file in order to customize the ``integer_widget`` fragment.

.. code-block:: html+php

<!-- app/Resources/views/form/integer_widget.html.php -->
<div class="integer_widget">
<?php echo $view['form']->block(
$form,
'form_widget_simple',
array('type' => isset($type) ? $type : "number")
) ?>
</div>

Now that you've created the customized form template, you need to tell Symfony
to use it. Inside the template where you're actually rendering your form,
tell Symfony to use the theme via the ``setTheme()`` helper method::

<?php $view['form']->setTheme($form, array(':form')); ?>

<?php $view['form']->widget($form['age']) ?>

When the ``form.age`` widget is rendered, Symfony will use the customized
``integer_widget.html.php`` template and the ``input`` tag will be wrapped in
the ``div`` element.

If you want to apply a theme to a specific child form, pass it to the ``setTheme()``
method::

<?php $view['form']->setTheme($form['child'], ':form'); ?>

.. note::

The ``:form`` syntax is based on the functional names for templates:
``Bundle:Directory``. As the form directory lives in the
``app/Resources/views`` directory, the ``Bundle`` part is empty, resulting
in ``:form``.

Referencing base Form Blocks (Twig specific)
--------------------------------------------
Referencing base Form Blocks
----------------------------

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

.. _twig:

Making Application-wide Customizations
--------------------------------------

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

Twig
~~~~

By using the following configuration, any customized form blocks inside the
``form/fields.html.twig`` template will be used globally when a form is
rendered.
Expand Down Expand Up @@ -512,125 +468,6 @@ your template file rather than adding the template as a resource:
Note that the ``form`` variable in the above code is the form view variable
that you passed to your template.

PHP
~~~

By using the following configuration, any customized form fragments inside the
``app/Resources/views/Form`` folder will be used globally when a
form is rendered.

.. configuration-block::

.. code-block:: yaml

# app/config/config.yml
framework:
templating:
form:
resources:
- 'AppBundle:Form'
# ...

.. code-block:: xml

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

<framework:config>
<framework:templating>
<framework:form>
<framework:resource>AppBundle:Form</framework:resource>
</framework:form>
</framework:templating>
<!-- ... -->
</framework:config>
</container>

.. code-block:: php

// app/config/config.php
// PHP
$container->loadFromExtension('framework', array(
'templating' => array(
'form' => array(
'resources' => array(
'AppBundle:Form',
),
),
),

// ...
));

By default, the PHP engine uses a *div* layout when rendering forms. Some people,
however, may prefer to render forms in a *table* layout. Use the ``FrameworkBundle:FormTable``
resource to use such a layout:

.. configuration-block::

.. code-block:: yaml

# app/config/config.yml
framework:
templating:
form:
resources:
- 'FrameworkBundle:FormTable'

.. code-block:: xml

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

<framework:config>
<framework:templating>
<framework:form>
<resource>FrameworkBundle:FormTable</resource>
</framework:form>
</framework:templating>
<!-- ... -->
</framework:config>
</container>

.. code-block:: php

// app/config/config.php
$container->loadFromExtension('framework', array(
'templating' => array(
'form' => array(
'resources' => array(
'FrameworkBundle:FormTable',
),
),
),

// ...
));

If you only want to make the change in one template, add the following line to
your template file rather than adding the template as a resource:

.. code-block:: html+php

<?php $view['form']->setTheme($form, array('FrameworkBundle:FormTable')); ?>

Note that the ``$form`` variable in the above code is the form view variable
that you passed to your template.

How to Customize an individual Field
------------------------------------

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

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

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

In Twig, if you're making the form customization inside a separate template, use
If you're making the form customization inside a separate template, use
the following:

.. code-block:: html+twig
Expand All @@ -896,24 +733,6 @@ the following:
{% endif %}
{% endblock %}

When using PHP as a templating engine you have to copy the content from the
original template:

.. code-block:: html+php

<!-- form_label.html.php -->

<!-- original content -->
<?php if ($required) { $label_attr['class'] = trim((isset($label_attr['class']) ? $label_attr['class'] : '').' required'); } ?>
<?php if (!$compound) { $label_attr['for'] = $id; } ?>
<?php if (!$label) { $label = $view['form']->humanize($name); } ?>
<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>

<!-- customization -->
<?php if ($required) : ?>
<span class="required" title="This field is required">*</span>
<?php endif ?>

.. tip::

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

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

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

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

In Twig, if you're making the form customization inside a separate template, use
If you're making the form customization inside a separate template, use
the following:

.. code-block:: html+twig
Expand All @@ -964,25 +783,6 @@ the following:
{% endif %}
{% endblock %}

When using PHP as a templating engine you have to copy the content from the
original template:

.. code-block:: html+php

<!-- form_widget_simple.html.php -->

<!-- Original content -->
<input
type="<?php echo isset($type) ? $view->escape($type) : 'text' ?>"
<?php if (!empty($value)): ?>value="<?php echo $view->escape($value) ?>"<?php endif ?>
<?php echo $view['form']->block($form, 'widget_attributes') ?>
/>

<!-- Customization -->
<?php if (isset($help)) : ?>
<span class="help"><?php echo $view->escape($help) ?></span>
<?php endif ?>

To render a help message below a field, pass in a ``help`` variable:

.. code-block:: twig
Expand Down
Loading