Adding Form Field Help Text

Keep on Learning!

If you liked what you've learned so far, dive in!
Subscribe to get access to this tutorial plus
video, code and script downloads.

Start your All-Access Pass
Buy just this tutorial for $10.00

With a Subscription, click any sentence in the script to jump to that part of the video!

Login Subscribe

I think we should becomes legends by adding a totally new feature to Symfony!

I want to be able to add some help text under each field - ya know to give the user a little bit more info about that field.

Bootstrap already has markup and CSS for this:

<span class="help-block">
    A block of help text that breaks onto a new line and may extend beyond one line.
</span>

If we add a span and give it a help-block class, it should look great, for free.

Inventing a new help Variable

Tip

Since Symfony 4.1 there is help option you can use on every form field:

$builder->add('price', null, [
    'help' => 'In cents',
]);

For more information, check this doc: https://symfony.com/blog/new-in-symfony-4-1-form-field-help

This feature doesn't exist in Symfony... yet, but here's how I want it to work: I want to be able to pass a variable called help and just have it show up:

{{ form_start(genusForm) }}
... lines 2 - 16
{{ form_row(genusForm.isPublished, {
help: 'Should this genus be shown on the site?'
}) }}
... lines 20 - 22
{{ form_end(genusForm) }}

As promised, nothing happens yet. But! Now that we are passing in a new, invented variable called help, this variable is already available in our form theme templates. Head into the form_row block, render dump() with no arguments:

... lines 1 - 2
{% block form_row -%}
... line 4
<div class="form-group {% if (not compound or force_error|default(false)) and not valid %} has-error{% endif %}{{ showErrorIcon ? ' has-feedback' : '' }}">
... lines 6 - 7
{{ dump() }}
... line 9
</div>
{%- endblock form_row %}
... lines 12 - 24

And then refresh.

Search for help: it's alive! The isPublished field is rocking that variable.

So yea, you're free to pass in whatever variables you want. And that makes us, super dangerous. If the help message is set, then add the span, give it the help-block class and print help:

... lines 1 - 2
{% block form_row -%}
... line 4
<div class="form-group {% if (not compound or force_error|default(false)) and not valid %} has-error{% endif %}{{ showErrorIcon ? ' has-feedback' : '' }}">
... lines 6 - 7
{% if help %}
<span class="help-block">{{ help }}</span>
{% endif %}
... line 11
</div>
{%- endblock form_row %}
... lines 14 - 26

Using the default Filter Everywhere

Try that out. Oh... and it does not work. Of course: the form_row block is called for every field, but the help variable only exists for the isPublished field. We need to code defensively! How? Just pipe the help variable to the default filter:

... lines 1 - 2
{% block form_row -%}
... line 4
<div class="form-group {% if (not compound or force_error|default(false)) and not valid %} has-error{% endif %}{{ showErrorIcon ? ' has-feedback' : '' }}">
... lines 6 - 7
{% if help|default %}
<span class="help-block">{{ help }}</span>
{% endif %}
... line 11
</div>
{%- endblock form_row %}
... lines 14 - 26

Yep, that's it. This says:

If the help variable does not exist, don't throw a big error, just default the variable to null and, have a nice day.

When you use default, you can either pass it a default value - like we did above - or let it use null, which is cool for us.

Try this! Suhweet!

Next, we'll do a bit more work to make our forms friendly for screen readers. Pulling this off gets really interesting.

Leave a comment!

This tutorial is built on Symfony 3 but form theming hasn't changed much in Symfony 4 and Symfony 5. Other than some path differences - this tutorial should work fine.

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": ">=5.5.9",
        "symfony/symfony": "3.1.*", // v3.1.4
        "doctrine/orm": "^2.5", // v2.7.2
        "doctrine/doctrine-bundle": "^1.6", // 1.6.4
        "doctrine/doctrine-cache-bundle": "^1.2", // 1.3.0
        "symfony/swiftmailer-bundle": "^2.3", // v2.3.11
        "symfony/monolog-bundle": "^2.8", // 2.11.1
        "symfony/polyfill-apcu": "^1.0", // v1.2.0
        "sensio/distribution-bundle": "^5.0", // v5.0.22
        "sensio/framework-extra-bundle": "^3.0.2", // v3.0.16
        "incenteev/composer-parameter-handler": "^2.0", // v2.1.2
        "knplabs/knp-markdown-bundle": "^1.4", // 1.4.2
        "doctrine/doctrine-migrations-bundle": "^1.1", // 1.1.1
        "stof/doctrine-extensions-bundle": "^1.2" // v1.2.2
    },
    "require-dev": {
        "sensio/generator-bundle": "^3.0", // v3.0.7
        "symfony/phpunit-bridge": "^3.0", // v3.1.3
        "nelmio/alice": "^2.1", // 2.1.4
        "doctrine/doctrine-fixtures-bundle": "^2.3" // 2.3.0
    }
}