I-Am-Bot Code, technology and life

Symfony2 form theme for Bootstrap

Symfony2 is a flexible, fast and secure PHP 5 framework for developing modern applications. This post assumes you already know the basics of working with Symfony.

Symfony2 has a very powerful templating engine in the form of Twig, a simple templating engine much like the popular Mustache. Twig allows non programmers to quickly design HTML layouts without the need to write PHP code. It also makes working with forms a breeze, and all that is needed to output a form on a template is

form_widget(form)

However, styling the form to suit your need takes a bit more effort. Symfony does allow your application to have different form themes which can be then be applied to various forms. It involves overriding various blocks to render different parts of the form. The problem is in finding which blocks to edit, and which to leave alone. This post can serve as a theme to render forms styled like the ones in Bootstrap.

When drawing a form using the form_widget(form) or form_row(form.field), Symfony uses the default theme that is defined in the file form_div_layout.html.twig. This file contains the various block definitions that are called when you use the appropriate twig function. For example, when you simply call form_widget(form), you can see how it in turn calls field_rows(form), which then renders the form errors, and for every field in the form, calls the corresponding widget block.

For Bootstrap's theme, we will override 3 blocks, and define one macro to display errors from the form.

We first define the macro hasErrors to check if the current field has an error, in which case the string "error" is returned which is appended to the class of the input div for the field to be rendered as an error field

/src/Acme/DemoBundle/Resources/views/Form/macro.html.twig

{% macro hasErrors(field) %}
    {% if form_errors(field)|length > 1 %}
        {{ 'error' }}
    {% endif %}
{% endmacro %}

Then, we redefine the field_rows block and do not display the error messages at the beginning of the form

/src/Acme/DemoBundle/Resources/views/Form/theme.html.twig

{% block field_rows %}
{% spaceless %}
    {% for child in form %}
        {{ form_row(child) }}
    {% endfor %}
{% endspaceless %}
{% endblock field_rows %}

Next, we define the custom field_row block that actually renders the HTML for each field. We define the container div for each input field, and call the hasErrors macro to check if Symfony has returned an error for that field. If yes, the class "error" will be added to the class attribute, and the entire field will be highlighted in red to indicate an error. We then echo the error after the field, just like in Bootstrap. Notice how we are passing the global _context object to the form_widget block. By default, you can pass custom attributes to the form_widget block and not to the field_row block. This is done so that we can add custom attributes to each input field, as shown in the example at the end.

/src/Acme/DemoBundle/Resources/views/Form/theme.html.twig

{% block field_row %}
{% spaceless %}
    {% if macro is not defined %}
        {% import 'AcmeDemoBundle:Form:macro.html.twig' as macro %}
    {% endif %}
    <div class="clearfix {{macro.hasErrors(form)}}">
        {{ form_label(form) }}
        <div class="input">
            {{ form_widget(form, _context) }}
            {{ form_errors(form) }}
        </div>
    </div>
{% endspaceless %}
{% endblock field_row %}

We have defined the actual macro, but we now have to customize the error display. That is done in the field_errors block

/src/Acme/DemoBundle/Resources/views/Form/theme.html.twig

{% block field_errors %}
{% spaceless %}
    {% if errors is defined and errors|length > 0 %}
        {% for error in errors %}
        <span class="help-inline error" style="float:right;width:170px;margin-top:5px;">{{ error.messageTemplate|trans(error.messageParameters, 'validators') }}</span>
        {% endfor %}
    {% endif %}
{% endspaceless %}
{% endblock field_errors %}

That's it! We have now created a custom form theme! To use this, just include the following twig block before drawing the theme

{% form_theme form 'AcmeDemoBundle:Form:theme.html.twig' %}
{{ form_row(form.name, { 'attr': {'class':'xlarge','placeholder':'Please enter your name'} }) }}
{{ form_row(form.description, {'attr': {'class':'xlarge'} }) }}
{{ form_rest(form) }}

We are using the form_row block to render each field, so that we can also pass along custom attributes to each field, just like the form_widget block {{ form_widget(form.task, { 'attr': {'class': 'task_field'} }) }}. However, if we use form_widget(form), then custom attributes cannot be passed to individual fields, but the theme will be rendered nevertheless. Passing custom attributes is particularly useful to adjust the width, height, placeholder, etc of the fields.

That's it! You can define various themes for different parts of your application in a similar fashion, and simply set the appropriate theme with the form_theme directive before rendering a form. Have fun theming forms in Symfony2!