Adding Form Field Help Text

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

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:

            
            24 lines
            
            app/Resources/views/admin/genus/_form.html.twig
        
            {{ 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:

            
            24 lines
            
            app/Resources/views/_formTheme.html.twig
        
                                                    ... 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:

            
            26 lines
            
            app/Resources/views/_formTheme.html.twig
        
                                                    ... 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:

            
            26 lines
            
            app/Resources/views/_formTheme.html.twig
        
                                                    ... 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.

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": "^7.1.3",
        "symfony/symfony": "3.4.*", // v3.4.49
        "doctrine/orm": "^2.5", // 2.7.5
        "doctrine/doctrine-bundle": "^1.6", // 1.12.13
        "doctrine/doctrine-cache-bundle": "^1.2", // 1.4.0
        "symfony/swiftmailer-bundle": "^2.3", // v2.6.7
        "symfony/monolog-bundle": "^2.8", // v2.12.1
        "symfony/polyfill-apcu": "^1.0", // v1.23.0
        "sensio/distribution-bundle": "^5.0", // v5.0.25
        "sensio/framework-extra-bundle": "^3.0.2", // v3.0.29
        "incenteev/composer-parameter-handler": "^2.0", // v2.1.4
        "composer/package-versions-deprecated": "^1.11", // 1.11.99.4
        "knplabs/knp-markdown-bundle": "^1.4", // 1.9.0
        "doctrine/doctrine-migrations-bundle": "^1.1", // v1.3.2
        "stof/doctrine-extensions-bundle": "^1.2" // v1.3.0
    },
    "require-dev": {
        "sensio/generator-bundle": "^3.0", // v3.1.7
        "symfony/phpunit-bridge": "^3.0", // v3.4.47
        "nelmio/alice": "^2.1", // v2.3.6
        "doctrine/doctrine-fixtures-bundle": "^2.3" // v2.4.1
    }
}

Edit on GitHub

TRACK

Symfony 3 >

COURSE

Getting Crazy with Form Themes

Adding Form Field Help Text

Keep on Learning!

Inventing a new help Variable

Using the default Filter Everywhere

Leave a comment!

What PHP libraries does this tutorial use?

	{{ 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) }}

	... 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