Buy

Adding Form Field Help Text

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

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.

Leave a comment!

  • 2016-12-09 Victor Bocharsky

    Hey eCosinus,

    This is a "whitespace control", i.e. to remove some extra whitespace before and after {{- xxxx -}}. Check more information about it with some nice examples in the Twig docs: http://twig.sensiolabs.org/...

    Cheers!

  • 2016-12-09 eCosinus

    I in the template what does in mean {{- xxxx -}} what is the - ? Thanks