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

585ca28b8a Add return type hint
859ee03785 Revert: remove comment line from twig templates
d723756331 Fix some mistakes
c74e0dc2da Use spaceless balises in Twig templates
8b937ff43f Try without try/catch
32bf1f68ad Test the renderHelp method in all Tests about help to skip them if necessary.
437b77e81a Skip renderHelp test as skipped if not override
d84be700b2 Update composer files
075fcfd07c [FrameworkBundle] Add widgetAtt to formTable/form_row
f1d13a860c Fix Fabpot.io
69ded67643 Added form_help on horizontal design and removed special variable
fd53bc579a Enable aria-described in row for all Templates
98065d38b5 fabpot.io fix
edb95f8e44 Use array long syntax
aada72c5d4 Set help option on nul as default
f948147e38 Rename help id (snake_case)
77fa3178bd Fix Test
30deaa9b28 PSR fix
bf4d08c5ae Add aria-describedBy on input
1f3a15e33b Rename id
058489d7df Add an id to the help
6ea7a2054b Remove vars option from form_help
ba798dfdf4 FrameworkBundle Tests
4f2581d7da Use array long syntax
f15bc79df1 Fix coding standards
c934e496d2 Add test without help set
8094804522 Add Tests
067c681580 Template for table, Foundation and Bootstrap 3
d3e3e492df Fix: check translation domain
2c2c04549f Adapt existant tests
831693ad45 Add trans filter
e311838aed Remove raw filter for help
8b97c1b516 Use a shortcut to acces help var in Twig template
1b89f9d9dd Add a template fot div_layout
c8914f591e Add a data_help method in Form

Author: fabpot

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; ?>

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>

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') : '' ?>

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>

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

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);

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);

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",