feature #26332 Add a data_help method in Form (mpiot, Nyholm)

This PR was merged into the 4.1-dev branch. Discussion ---------- Add a data_help method in Form | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #26331 | License | MIT | Doc PR | symfony/symfony-docs#9361 Add a form_help method in twig to display a help message in form. A `help` keyword is added to all FormType to define the message. Commits ------- 585ca28 Add return type hint 859ee03 Revert: remove comment line from twig templates d723756 Fix some mistakes c74e0dc Use spaceless balises in Twig templates 8b937ff Try without try/catch 32bf1f6 Test the renderHelp method in all Tests about help to skip them if necessary. 437b77e Skip renderHelp test as skipped if not override d84be70 Update composer files 075fcfd [FrameworkBundle] Add widgetAtt to formTable/form_row f1d13a8 Fix Fabpot.io 69ded67 Added form_help on horizontal design and removed special variable fd53bc5 Enable aria-described in row for all Templates 98065d3 fabpot.io fix edb95f8 Use array long syntax aada72c Set help option on nul as default f948147 Rename help id (snake_case) 77fa317 Fix Test 30deaa9 PSR fix bf4d08c Add aria-describedBy on input 1f3a15e Rename id 058489d Add an id to the help 6ea7a20 Remove vars option from form_help ba798df FrameworkBundle Tests 4f2581d Use array long syntax f15bc79 Fix coding standards c934e49 Add test without help set 8094804 Add Tests 067c681 Template for table, Foundation and Bootstrap 3 d3e3e49 Fix: check translation domain 2c2c045 Adapt existant tests 831693a Add trans filter e311838 Remove raw filter for help 8b97c1b Use a shortcut to acces help var in Twig template 1b89f9d Add a template fot div_layout c8914f5 Add a data_help method in Form
symfony · Mar 27, 2018 · 9dd89e0 · 9dd89e0
2 parents d329a7a + 585ca28
commit 9dd89e0
Show file tree

Hide file tree

Showing 32 changed files with 273 additions and 23 deletions.
diff --git a/src/Symfony/Bridge/Twig/Extension/FormExtension.php b/src/Symfony/Bridge/Twig/Extension/FormExtension.php
@@ -47,6 +47,7 @@ public function getFunctions()
             new TwigFunction('form_widget', null, array('node_class' => 'Symfony\Bridge\Twig\Node\SearchAndRenderBlockNode', 'is_safe' => array('html'))),
             new TwigFunction('form_errors', null, array('node_class' => 'Symfony\Bridge\Twig\Node\SearchAndRenderBlockNode', 'is_safe' => array('html'))),
             new TwigFunction('form_label', null, array('node_class' => 'Symfony\Bridge\Twig\Node\SearchAndRenderBlockNode', 'is_safe' => array('html'))),
+            new TwigFunction('form_help', null, array('node_class' => 'Symfony\Bridge\Twig\Node\SearchAndRenderBlockNode', 'is_safe' => array('html'))),
             new TwigFunction('form_row', null, array('node_class' => 'Symfony\Bridge\Twig\Node\SearchAndRenderBlockNode', 'is_safe' => array('html'))),
             new TwigFunction('form_rest', null, array('node_class' => 'Symfony\Bridge\Twig\Node\SearchAndRenderBlockNode', 'is_safe' => array('html'))),
             new TwigFunction('form', null, array('node_class' => 'Symfony\Bridge\Twig\Node\RenderBlockNode', 'is_safe' => array('html'))),

diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_horizontal_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_horizontal_layout.html.twig
@@ -23,10 +23,15 @@ col-sm-2
 {# Rows #}
 
 {% block form_row -%}
+    {%- set widget_attr = {} -%}
+    {%- if help is not empty -%}
+        {%- set widget_attr = {attr: {'aria-describedby': id ~"_help"}} -%}
+    {%- endif -%}
     <div class="form-group{% if (not compound or force_error|default(false)) and not valid %} has-error{% endif %}">
         {{- form_label(form) -}}
         <div class="{{ block('form_group_class') }}">
-            {{- form_widget(form) -}}
+            {{- form_widget(form, widget_attr) -}}
+            {{- form_help(form) -}}
             {{- form_errors(form) -}}
         </div>
 {##}</div>

diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_layout.html.twig
@@ -89,9 +89,14 @@
 {# Rows #}
 
 {% block form_row -%}
+    {%- set widget_attr = {} -%}
+    {%- if help is not empty -%}
+        {%- set widget_attr = {attr: {'aria-describedby': id ~"_help"}} -%}
+    {%- endif -%}
     <div class="form-group{% if (not compound or force_error|default(false)) and not valid %} has-error{% endif %}">
         {{- form_label(form) -}}
-        {{- form_widget(form) -}}
+        {{- form_widget(form, widget_attr) -}}
+        {{- form_help(form) -}}
         {{- form_errors(form) -}}
     </div>
 {%- endblock form_row %}
@@ -149,3 +154,17 @@
     {% if form is not rootform %}</span>{% else %}</div>{% endif %}
     {%- endif %}
 {%- endblock form_errors %}
+
+{# Help #}
+
+{% block form_help -%}
+    {%- if help is not empty -%}
+        <span id="{{ id }}_help" class="help-block">
+            {%- if translation_domain is same as(false) -%}
+                {{- help -}}
+            {%- else -%}
+                {{- help|trans({}, translation_domain) -}}
+            {%- endif -%}
+        </span>
+    {%- endif -%}
+{%- endblock form_help %}
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_horizontal_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_horizontal_layout.html.twig
@@ -24,21 +24,31 @@ col-sm-2
     {%- if expanded is defined and expanded -%}
         {{ block('fieldset_form_row') }}
     {%- else -%}
+    {%- set widget_attr = {} -%}
+    {%- if help is not empty -%}
+        {%- set widget_attr = {attr: {'aria-describedby': id ~"_help"}} -%}
+    {%- endif -%}
         <div class="form-group row{% if (not compound or force_error|default(false)) and not valid %} is-invalid{% endif %}">
             {{- form_label(form) -}}
             <div class="{{ block('form_group_class') }}">
-                {{- form_widget(form) -}}
+                {{- form_widget(form, widget_attr) -}}
+                {{- form_help(form) -}}
             </div>
     {##}</div>
     {%- endif -%}
 {%- endblock form_row %}
 
 {% block fieldset_form_row -%}
+    {%- set widget_attr = {} -%}
+    {%- if help is not empty -%}
+        {%- set widget_attr = {attr: {'aria-describedby': id ~"_help"}} -%}
+    {%- endif -%}
     <fieldset class="form-group">
         <div class="row{% if (not compound or force_error|default(false)) and not valid %} is-invalid{% endif %}">
             {{- form_label(form) -}}
             <div class="{{ block('form_group_class') }}">
-                {{- form_widget(form) -}}
+                {{- form_widget(form, widget_attr) -}}
+                {{- form_help(form) -}}
             </div>
         </div>
 {##}</fieldset>

diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_layout.html.twig
@@ -259,9 +259,14 @@
     {%- if compound is defined and compound -%}
         {%- set element = 'fieldset' -%}
     {%- endif -%}
+    {%- set widget_attr = {} -%}
+    {%- if help is not empty -%}
+        {%- set widget_attr = {attr: {'aria-describedby': id ~"_help"}} -%}
+    {%- endif -%}
     <{{ element|default('div') }} class="form-group">
         {{- form_label(form) -}}
-        {{- form_widget(form) -}}
+        {{- form_widget(form, widget_attr) -}}
+        {{- form_help(form) -}}
     </{{ element|default('div') }}>
 {%- endblock form_row %}
 
@@ -287,3 +292,17 @@
         </span>
     {%- endif %}
 {%- endblock form_errors %}
+
+{# Help #}
+
+{% block form_help -%}
+    {%- if help is not empty -%}
+        <small id="{{ id }}_help" class="form-text text-muted">
+            {%- if translation_domain is same as(false) -%}
+                {{- help -}}
+            {%- else -%}
+                {{- help|trans({}, translation_domain) -}}
+            {%- endif -%}
+        </small>
+    {%- endif -%}
+{%- endblock form_help %}
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
@@ -287,6 +287,20 @@
 
 {%- block button_label -%}{%- endblock -%}
 
+{# Help #}
+
+{% block form_help -%}
+    {%- if help is not empty -%}
+        <p id="{{ id }}_help" class="help-text">
+            {%- if translation_domain is same as(false) -%}
+                {{- help -}}
+            {%- else -%}
+                {{- help|trans({}, translation_domain) -}}
+            {%- endif -%}
+        </p>
+    {%- endif -%}
+{%- endblock form_help %}
+
 {# Rows #}
 
 {%- block repeated_row -%}
@@ -298,10 +312,15 @@
 {%- endblock repeated_row -%}
 
 {%- block form_row -%}
+    {%- set widget_attr = {} -%}
+    {%- if help is not empty -%}
+        {%- set widget_attr = {attr: {'aria-describedby': id ~"_help"}} -%}
+    {%- endif -%}
     <div>
         {{- form_label(form) -}}
         {{- form_errors(form) -}}
-        {{- form_widget(form) -}}
+        {{- form_widget(form, widget_attr) -}}
+        {{- form_help(form) -}}
     </div>
 {%- endblock form_row -%}
 

diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/form_table_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/form_table_layout.html.twig
@@ -1,13 +1,18 @@
 {% use "form_div_layout.html.twig" %}
 
 {%- block form_row -%}
+    {%- set widget_attr = {} -%}
+    {%- if help is not empty -%}
+        {%- set widget_attr = {attr: {'aria-describedby': id ~"_help"}} -%}
+    {%- endif -%}
     <tr>
         <td>
             {{- form_label(form) -}}
         </td>
         <td>
             {{- form_errors(form) -}}
-            {{- form_widget(form) -}}
+            {{- form_widget(form, widget_attr) -}}
+            {{- form_help(form) -}}
         </td>
     </tr>
 {%- endblock form_row -%}

diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/foundation_5_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/foundation_5_layout.html.twig
@@ -267,11 +267,16 @@
 {# Rows #}
 
 {% block form_row -%}
+    {%- set widget_attr = {} -%}
+    {%- if help is not empty -%}
+        {%- set widget_attr = {attr: {'aria-describedby': id ~"_help"}} -%}
+    {%- endif -%}
     <div class="row">
         <div class="large-12 columns{% if (not compound or force_error|default(false)) and not valid %} error{% endif %}">
-            {{ form_label(form) }}
-            {{ form_widget(form) }}
-            {{ form_errors(form) }}
+            {{- form_label(form) -}}
+            {{- form_widget(form, widget_attr) -}}
+            {{- form_help(form) -}}
+            {{- form_errors(form) -}}
         </div>
     </div>
 {%- endblock form_row %}

diff --git a/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionBootstrap3HorizontalLayoutTest.php b/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionBootstrap3HorizontalLayoutTest.php
@@ -69,6 +69,11 @@ protected function renderLabel(FormView $view, $label = null, array $vars = arra
         return (string) $this->renderer->searchAndRenderBlock($view, 'label', $vars);
     }
 
+    protected function renderHelp(FormView $view)
+    {
+        return (string) $this->renderer->searchAndRenderBlock($view, 'help');
+    }
+
     protected function renderErrors(FormView $view)
     {
         return (string) $this->renderer->searchAndRenderBlock($view, 'errors');

diff --git a/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionBootstrap3LayoutTest.php b/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionBootstrap3LayoutTest.php
@@ -89,6 +89,11 @@ protected function renderLabel(FormView $view, $label = null, array $vars = arra
         return (string) $this->renderer->searchAndRenderBlock($view, 'label', $vars);
     }
 
+    protected function renderHelp(FormView $view)
+    {
+        return (string) $this->renderer->searchAndRenderBlock($view, 'help');
+    }
+
     protected function renderErrors(FormView $view)
     {
         return (string) $this->renderer->searchAndRenderBlock($view, 'errors');

diff --git a/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionBootstrap4HorizontalLayoutTest.php b/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionBootstrap4HorizontalLayoutTest.php
@@ -70,6 +70,11 @@ protected function renderLabel(FormView $view, $label = null, array $vars = arra
         return (string) $this->renderer->searchAndRenderBlock($view, 'label', $vars);
     }
 
+    protected function renderHelp(FormView $view)
+    {
+        return (string) $this->renderer->searchAndRenderBlock($view, 'help');
+    }
+
     protected function renderErrors(FormView $view)
     {
         return (string) $this->renderer->searchAndRenderBlock($view, 'errors');

diff --git a/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionBootstrap4LayoutTest.php b/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionBootstrap4LayoutTest.php
@@ -92,6 +92,11 @@ protected function renderLabel(FormView $view, $label = null, array $vars = arra
         return (string) $this->renderer->searchAndRenderBlock($view, 'label', $vars);
     }
 
+    protected function renderHelp(FormView $view)
+    {
+        return (string) $this->renderer->searchAndRenderBlock($view, 'help');
+    }
+
     protected function renderErrors(FormView $view)
     {
         return (string) $this->renderer->searchAndRenderBlock($view, 'errors');

diff --git a/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionDivLayoutTest.php b/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionDivLayoutTest.php
@@ -179,6 +179,11 @@ protected function renderLabel(FormView $view, $label = null, array $vars = arra
         return (string) $this->renderer->searchAndRenderBlock($view, 'label', $vars);
     }
 
+    protected function renderHelp(FormView $view)
+    {
+        return (string) $this->renderer->searchAndRenderBlock($view, 'help');
+    }
+
     protected function renderErrors(FormView $view)
     {
         return (string) $this->renderer->searchAndRenderBlock($view, 'errors');

diff --git a/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionTableLayoutTest.php b/src/Symfony/Bridge/Twig/Tests/Extension/FormExtensionTableLayoutTest.php
@@ -90,6 +90,11 @@ protected function renderLabel(FormView $view, $label = null, array $vars = arra
         return (string) $this->renderer->searchAndRenderBlock($view, 'label', $vars);
     }
 
+    protected function renderHelp(FormView $view)
+    {
+        return (string) $this->renderer->searchAndRenderBlock($view, 'help');
+    }
+
     protected function renderErrors(FormView $view)
     {
         return (string) $this->renderer->searchAndRenderBlock($view, 'errors');

diff --git a/src/Symfony/Bridge/Twig/UndefinedCallableHandler.php b/src/Symfony/Bridge/Twig/UndefinedCallableHandler.php
@@ -34,6 +34,7 @@ class UndefinedCallableHandler
         'form_widget' => 'form',
         'form_errors' => 'form',
         'form_label' => 'form',
+        'form_help' => 'form',
         'form_row' => 'form',
         'form_rest' => 'form',
         'form' => 'form',

diff --git a/src/Symfony/Bridge/Twig/composer.json b/src/Symfony/Bridge/Twig/composer.json
@@ -23,7 +23,7 @@
         "symfony/asset": "~3.4|~4.0",
         "symfony/dependency-injection": "~3.4|~4.0",
         "symfony/finder": "~3.4|~4.0",
-        "symfony/form": "^3.4.7|^4.0.7",
+        "symfony/form": "^4.1",
         "symfony/http-foundation": "~3.4|~4.0",
         "symfony/http-kernel": "~3.4|~4.0",
         "symfony/polyfill-intl-icu": "~1.0",
@@ -41,7 +41,7 @@
         "symfony/workflow": "~3.4|~4.0"
     },
     "conflict": {
-        "symfony/form": "<3.4.7|<4.0.7,>=4.0",
+        "symfony/form": "<4.1",
         "symfony/console": "<3.4"
     },
     "suggest": {

diff --git a/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form/form_help.html.php b/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form/form_help.html.php
@@ -0,0 +1,3 @@
+<?php if (!empty($help)): ?>
+    <p id="<?php echo $view->escape($id); ?>_help" class="help-text"><?php echo $view->escape(false !== $translation_domain ? $view['translator']->trans($help, array(), $translation_domain) : $help); ?></p>
+<?php endif; ?>
diff --git a/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form/form_row.html.php b/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form/form_row.html.php
@@ -1,5 +1,7 @@
 <div>
-    <?php echo $view['form']->label($form) ?>
-    <?php echo $view['form']->errors($form) ?>
-    <?php echo $view['form']->widget($form) ?>
+    <?php $widgetAttr = empty($help) ? array() : array('attr' => array('aria-describedby' => $id.'_help')); ?>
+    <?php echo $view['form']->label($form); ?>
+    <?php echo $view['form']->errors($form); ?>
+    <?php echo $view['form']->widget($form, $widgetAttr); ?>
+    <?php echo $view['form']->help($form); ?>
 </div>
diff --git a/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form/widget_attributes.html.php b/src/Symfony/Bundle/FrameworkBundle/Resources/views/Form/widget_attributes.html.php
@@ -1,3 +1,3 @@
 id="<?php echo $view->escape($id) ?>" name="<?php echo $view->escape($full_name) ?>"<?php if ($disabled): ?> disabled="disabled"<?php endif ?>
 <?php if ($required): ?> required="required"<?php endif ?>
-<?php echo $attr ? ' '.$view['form']->block($form, 'attributes') : '' ?>
+<?php echo $attr ? ' '.$view['form']->block($form, 'attributes') : '' ?>
diff --git a/src/Symfony/Bundle/FrameworkBundle/Resources/views/FormTable/form_row.html.php b/src/Symfony/Bundle/FrameworkBundle/Resources/views/FormTable/form_row.html.php
@@ -1,9 +1,11 @@
 <tr>
+    <?php $widgetAttr = empty($help) ? array() : array('attr' => array('aria-describedby' => $id.'_help')); ?>
     <td>
         <?php echo $view['form']->label($form); ?>
     </td>
     <td>
         <?php echo $view['form']->errors($form); ?>
-        <?php echo $view['form']->widget($form); ?>
+        <?php echo $view['form']->widget($form, $widgetAttr); ?>
+        <?php echo $view['form']->help($form); ?>
     </td>
 </tr>
diff --git a/src/Symfony/Bundle/FrameworkBundle/Templating/Helper/FormHelper.php b/src/Symfony/Bundle/FrameworkBundle/Templating/Helper/FormHelper.php
@@ -169,6 +169,18 @@ public function label(FormView $view, $label = null, array $variables = array())
         return $this->renderer->searchAndRenderBlock($view, 'label', $variables);
     }
 
+    /**
+     * Renders the help of the given view.
+     *
+     * @param FormView $view The parent view
+     *
+     * @return string The HTML markup
+     */
+    public function help(FormView $view): string
+    {
+        return $this->renderer->searchAndRenderBlock($view, 'help');
+    }
+
     /**
      * Renders the errors of the given view.
      *

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Templating/Helper/FormHelperDivLayoutTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Templating/Helper/FormHelperDivLayoutTest.php
@@ -91,6 +91,11 @@ protected function renderLabel(FormView $view, $label = null, array $vars = arra
         return (string) $this->engine->get('form')->label($view, $label, $vars);
     }
 
+    protected function renderHelp(FormView $view)
+    {
+        return (string) $this->engine->get('form')->help($view);
+    }
+
     protected function renderErrors(FormView $view)
     {
         return (string) $this->engine->get('form')->errors($view);

diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Templating/Helper/FormHelperTableLayoutTest.php b/src/Symfony/Bundle/FrameworkBundle/Tests/Templating/Helper/FormHelperTableLayoutTest.php
@@ -92,6 +92,11 @@ protected function renderLabel(FormView $view, $label = null, array $vars = arra
         return (string) $this->engine->get('form')->label($view, $label, $vars);
     }
 
+    protected function renderHelp(FormView $view)
+    {
+        return (string) $this->engine->get('form')->help($view);
+    }
+
     protected function renderErrors(FormView $view)
     {
         return (string) $this->engine->get('form')->errors($view);

diff --git a/src/Symfony/Bundle/FrameworkBundle/composer.json b/src/Symfony/Bundle/FrameworkBundle/composer.json
@@ -39,7 +39,7 @@
         "symfony/dom-crawler": "~3.4|~4.0",
         "symfony/polyfill-intl-icu": "~1.0",
         "symfony/security": "~3.4|~4.0",
-        "symfony/form": "~3.4|~4.0",
+        "symfony/form": "^4.1",
         "symfony/expression-language": "~3.4|~4.0",
         "symfony/process": "~3.4|~4.0",
         "symfony/security-core": "~3.4|~4.0",
@@ -65,7 +65,7 @@
         "phpunit/phpunit": "<4.8.35|<5.4.3,>=5.0",
         "symfony/asset": "<3.4",
         "symfony/console": "<3.4",
-        "symfony/form": "<3.4",
+        "symfony/form": "<4.1",
         "symfony/property-info": "<3.4",
         "symfony/serializer": "<4.1",
         "symfony/stopwatch": "<3.4",