How to Customize Form Rendering

Form Rendering Basics¶

Recall that the label, error and HTML widget of a form field can easily be rendered by using the form_row Twig function or the row PHP helper method:

You can also render each of the three parts of the field individually:

In both cases, the form label, errors and HTML widget are rendered by using a set of markup that ships standard with Symfony. For example, both of the above templates would render:

<div>
    <label for="form_age">Age</label>
    <ul>
        <li>This field is required</li>
    </ul>
    <input type="number" id="form_age" name="form[age]" />
</div>

To quickly prototype and test a form, you can render the entire form with just one line:

The remainder of this recipe will explain how every part of the form’s markup can be modified at several different levels. For more information about form rendering in general, see 在模板里生成表单.

What are Form Themes?¶

Symfony uses form fragments - a small piece of a template that renders just one part of a form - to render each part of a form - field labels, errors, input text fields, select tags, etc.

The fragments are defined as blocks in Twig and as template files in PHP.

A theme is nothing more than a set of fragments that you want to use when rendering a form. In other words, if you want to customize one portion of how a form is rendered, you’ll import a theme which contains a customization of the appropriate form fragments.

Symfony comes with four built-in form themes that define each and every fragment needed to render every part of a form:

• form_div_layout.html.twig, wraps each form field inside a <div> element.
• form_table_layout.html.twig, wraps the entire form inside a <table> element and each form field inside a <tr> element.
• bootstrap_3_layout.html.twig, wraps each form field inside a <div> element with the appropriate CSS classes to apply the default Bootstrap 3 CSS framework styles.
• bootstrap_3_horizontal_layout.html.twig, it’s similar to the previous theme, but the CSS classes applied are the ones used to display the forms horizontally (i.e. the label and the widget in the same row).

In the next section you will learn how to customize a theme by overriding some or all of its fragments.

For example, when the widget of an integer type field is rendered, an input number field is generated

renders:

<input type="number" id="form_age" name="form[age]" required="required" value="33" />

Internally, Symfony uses the integer_widget fragment to render the field. This is because the field type is integer and you’re rendering its widget (as opposed to its label or errors).

In Twig that would default to the block integer_widget from the form_div_layout.html.twig template.

In PHP it would rather be the integer_widget.html.php file located in the FrameworkBundle/Resources/views/Form folder.

The default implementation of the integer_widget fragment looks like this:

As you can see, this fragment itself renders another fragment - form_widget_simple:

The point is, the fragments dictate the HTML output of each part of a form. To customize the form output, you just need to identify and override the correct fragment. A set of these form fragment customizations is known as a form “theme”. When rendering a form, you can choose which form theme(s) you want to apply.

In Twig a theme is a single template file and the fragments are the blocks defined in this file.

In PHP a theme is a folder and the fragments are individual template files in this folder.

Form Theming¶

To see the power of form theming, suppose you want to wrap every input number field with a div tag. The key to doing this is to customize the integer_widget fragment.

Form Theming in Twig¶

When customizing the form field block in Twig, you have two options on where the customized form block can live:

Both methods have the same effect but are better in different situations.

{% extends '::base.html.twig' %}

{% form_theme form _self %}

{% block integer_widget %}
    <div class="integer_widget">
        {% set type = type|default('number') %}
        {{ block('form_widget_simple') }}
    </div>
{% endblock %}

{% block content %}
    {# ... render the form #}

    {{ form_row(form.age) }}
{% endblock %}

{# src/AppBundle/Resources/views/Form/fields.html.twig #}
{% block integer_widget %}
    <div class="integer_widget">
        {% set type = type|default('number') %}
        {{ block('form_widget_simple') }}
    </div>
{% endblock %}

{% form_theme form 'AppBundle:Form:fields.html.twig' %}

{{ form_widget(form.age) }}

{% form_theme form with ['::common.html.twig', ':Form:fields.html.twig',
                         'AppBundle:Form:fields.html.twig'] %}

{# ... #}

{% form_theme form.child 'AppBundle:Form:fields.html.twig' %}

{% form_theme form 'AppBundle:Form:fields.html.twig' %}

{% form_theme form.child 'AppBundle:Form:fields_child.html.twig' %}

Form Theming in PHP¶

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.

<!-- src/AppBundle/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('AppBundle: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'], 'AppBundle:Form/Child'); ?>

Referencing base Form Blocks (Twig specific)¶

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, and then customize it. In many cases, you can avoid doing this by referencing the base block when customizing it.

This is easy to do, but varies slightly depending on if your form block customizations are in the same template as the form or a separate template.

{% use 'form_div_layout.html.twig' with integer_widget as base_integer_widget %}

{% block integer_widget %}
    <div class="integer_widget">
        {{ block('base_integer_widget') }}
    </div>
{% endblock %}

{# src/AppBundle/Resources/views/Form/fields.html.twig #}
{% extends 'form_div_layout.html.twig' %}

{% block integer_widget %}
    <div class="integer_widget">
        {{ parent() }}
    </div>
{% endblock %}

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.

{% form_theme form 'form_table_layout.html.twig' %}

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

How to Customize an individual Field¶

So far, you’ve seen the different ways you can customize the widget output of all text field types. You can also customize individual fields. For example, suppose you have two text fields in a product form - name and description - but you only want to customize one of the fields. This can be accomplished by customizing a fragment whose name is a combination of the field’s id attribute and which part of the field is being customized. For example, to customize the name field only:

Here, the _product_name_widget fragment defines the template to use for the field whose id is product_name (and name is product[name]).

use SymfonyComponentFormFormBuilderInterface;

public function buildForm(FormBuilderInterface $builder, array $options)
{
    // ...

    $builder->add('name', 'text', array(
        'block_name' => 'custom_name',
    ));
}

You can also override the markup for an entire field row using the same method:

Other common Customizations¶

So far, this recipe has shown you several different ways to customize a single piece of how a form is rendered. The key is to customize a specific fragment that corresponds to the portion of the form you want to control (see naming form blocks).

In the next sections, you’ll see how you can make several common form customizations. To apply these customizations, use one of the methods described in the Form Theming section.

<ul>
    <li>This field is required</li>
</ul>

{% use 'form_div_layout.html.twig' with form_label as base_form_label %}

{% block form_label %}
    {{ block('base_form_label') }}

    {% if required %}
        <span class="required" title="This field is required">*</span>
    {% endif %}
{% endblock %}

{% extends 'form_div_layout.html.twig' %}

{% block form_label %}
    {{ parent() }}

    {% if required %}
        <span class="required" title="This field is required">*</span>
    {% endif %}
{% endblock %}

<!-- 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 ?>

label.required:before {
    content: "* ";
}

{% use 'form_div_layout.html.twig' with form_widget_simple as base_form_widget_simple %}

{% block form_widget_simple %}
    {{ block('base_form_widget_simple') }}

    {% if help is defined %}
        <span class="help">{{ help }}</span>
    {% endif %}
{% endblock %}

{% extends 'form_div_layout.html.twig' %}

{% block form_widget_simple %}
    {{ parent() }}

    {% if help is defined %}
        <span class="help">{{ help }}</span>
    {% endif %}
{% endblock %}

<!-- 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 ?>

Using Form Variables¶

Most of the functions available for rendering different parts of a form (e.g. the form widget, form label, form errors, etc.) also allow you to make certain customizations directly. Look at the following example:

The array passed as the second argument contains form “variables”. For more details about this concept in Twig, see More about Form Variables.