Form Fragment Naming

In Symfony, every part of a form that is rendered - HTML form elements, errors, labels, etc. - is defined in a base theme, which is a collection of blocks in Twig and a collection of template files in PHP.

In Twig, every block needed is defined in a single template file (e.g. form_div_layout.html.twig) that lives inside the Twig Bridge. Inside this file, you can see every block needed to render a form and every default field type.

In PHP, the fragments are individual template files. By default, they are located in the Resources/views/Form directory of the FrameworkBundle (view on GitHub).

Each fragment name follows the same basic pattern and is broken up into two pieces, separated by a single underscore character (_). A few examples are:

• form_row - used by form_row() to render most fields;
• textarea_widget - used by form_widget() to render a textarea field type;
• form_errors - used by form_errors() to render errors for a field;

Each fragment follows the same basic pattern: type_part. The type portion corresponds to the field type being rendered (e.g. textarea, checkbox, date, etc) whereas the part portion corresponds to what is being rendered (e.g. label, widget, errors, etc). By default, there are 4 possible parts of a form that can be rendered:

By knowing the field type (e.g. textarea) and which part you want to customize (e.g. widget), you can construct the fragment name that needs to be overridden (e.g. textarea_widget).

Template Fragment Inheritance

In some cases, the fragment you want to customize will appear to be missing. For example, there is no textarea_errors fragment in the default themes provided with Symfony. So how are the errors for a textarea field rendered?

The answer is: via the form_errors fragment. When Symfony renders the errors for a textarea type, it looks first for a textarea_errors fragment before falling back to the form_errors fragment. Each field type has a parent type (the parent type of textarea is text, its parent is form), and Symfony uses the fragment for the parent type if the base fragment doesn't exist.

So, to override the errors for only textarea fields, copy the form_errors fragment, rename it to textarea_errors and customize it. To override the default error rendering for all fields, copy and customize the form_errors fragment directly.

Global Form Theming

In the above example, you used the form_theme helper (in Twig) to "import" the custom form fragments into just that form. You can also tell Symfony to import form customizations across your entire project.

1
2
3
4
5
6

# app/config/config.yml
twig:
    form_themes:
        - '...'
        - 'form/fields.html.twig'
    # ...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- 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:twig="http://symfony.com/schema/dic/twig"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">

    <twig:config>
        <twig:theme>...</twig:theme>
        <twig:theme>form/fields.html.twig</twig:theme>
        <!-- ... -->
    </twig:config>
</container>

1
2
3
4
5
6
7
8

// app/config/config.php
$container->loadFromExtension('twig', [
    'form_themes' => [
        '...',
        'form/fields.html.twig',
    ],
    // ...
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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

{# import "_self" as the form theme #}
{% form_theme form _self %}

{# make the form fragment customization #}
{% block form_row %}
    {# custom field row output #}
{% endblock form_row %}

{% block content %}
    {# ... #}

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

1
2
3
4
5
6
7

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<!-- 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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

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

1
2
3
4
5
6
7
8
9
10
11

// app/config/config.php
$container->loadFromExtension('framework', [
    'templating' => [
        'form' => [
            'resources' => [
                'form',
            ],
        ],
    ],
    // ...
]);