Issue #314385 by penyaskito, Pancho, mgifford, jjcarrion, jlbellido, akalata,...

Issue #314385 by penyaskito, Pancho, mgifford, jjcarrion, jlbellido, akalata, alimac, jday, Risse, stBorchert | emmajane: Make position of #description configurable via the API.

core/includes/form.inc

@@ -2714,7 +2714,11 @@ function template_preprocess_form_element(&$variables) {
 
   $variables['description'] = NULL;
   if (!empty($element['#description'])) {
-    $description_attributes = array('class' => 'description');
+    $variables['description_display'] = $element['#description_display'];
+    $description_attributes = array('class' => array('description'));
+    if ($element['#description_display'] === 'invisible') {
+      $description_attributes['class'][] = 'visually-hidden';
+    }
     if (!empty($element['#id'])) {
       $description_attributes['id'] = $element['#id'] . '--description';
     }

core/lib/Drupal/Core/Form/FormBuilder.php

@@ -703,6 +703,7 @@ public function doBuildForm($form_id, &$element, FormStateInterface &$form_state
       '#required' => FALSE,
       '#attributes' => array(),
       '#title_display' => 'before',
+      '#description_display' => 'after',
       '#errors' => NULL,
     );
 

core/modules/system/src/Tests/Form/ElementsLabelsTest.php

@@ -94,4 +94,32 @@ function testFormLabels() {
     $elements = $this->xpath('//div[@id="edit-form-radios-title-attribute"]');
     $this->assertEqual($elements[0]['title'], 'Radios test' . ' (' . t('Required') . ')', 'Title attribute found.');
   }
+
+  /**
+   * Tests different display options for form element descriptions.
+   */
+  function testFormDescriptions() {
+    $this->drupalGet('form_test/form-descriptions');
+
+    // Check #description placement with #description_display='after'.
+    $field_id = 'edit-form-textfield-test-description-after';
+    $description_id = $field_id . '--description';
+    $elements = $this->xpath('//input[@id="' . $field_id . '" and @aria-describedby="' . $description_id . '"]/following-sibling::div[@id="' . $description_id . '"]');
+    $this->assertTrue(isset($elements[0]), t('Properly places the #description element after the form item.'));
+
+    // Check #description placement with #description_display='before'.
+    $field_id = 'edit-form-textfield-test-description-before';
+    $description_id = $field_id . '--description';
+    $elements = $this->xpath('//input[@id="' . $field_id . '" and @aria-describedby="' . $description_id . '"]/preceding-sibling::div[@id="' . $description_id . '"]');
+    $this->assertTrue(isset($elements[0]), t('Properly places the #description element before the form item.'));
+
+    // Check if the class is 'visually-hidden' on the form element description
+    // for the option with #description_display='invisible' and also check that
+    // the description is placed after the form element.
+    $field_id = 'edit-form-textfield-test-description-invisible';
+    $description_id = $field_id . '--description';
+    $elements = $this->xpath('//input[@id="' . $field_id . '" and @aria-describedby="' . $description_id . '"]/following-sibling::div[contains(@class, "visually-hidden")]');
+    $this->assertTrue(isset($elements[0]), t('Properly renders the #description element visually-hidden.'));
+  }
+
 }

core/modules/system/templates/form-element.html.twig

@@ -30,6 +30,12 @@
  *    - content: A description of the form element, may not be set.
  *    - attributes: (optional) A list of HTML attributes to apply to the
  *      description content wrapper. Will only be set when description is set.
+ * - description_display: Description display setting. It can have these values:
+ *   - before: The description is output before the element.
+ *   - after: The description is output after the element. This is the default
+ *     value.
+ *   - invisible: The description is output after the element, hidden visually
+ *     but available to screen readers.
  *
  * @see template_preprocess_form_element()
  *
@@ -43,6 +49,11 @@
   {% if prefix is not empty %}
     <span class="field-prefix">{{ prefix }}</span>
   {% endif %}
+  {% if description_display == 'before' and description.content %}
+    <div{{ description.attributes }}>
+      {{ description.content }}
+    </div>
+  {% endif %}
   {{ children }}
   {% if suffix is not empty %}
     <span class="field-suffix">{{ suffix }}</span>
@@ -50,7 +61,7 @@
   {% if label_display == 'after' %}
     {{ label }}
   {% endif %}
-  {% if description.content %}
+  {% if description_display in ['after', 'invisible'] and description.content %}
     <div{{ description.attributes }}>
       {{ description.content }}
     </div>

core/modules/system/tests/modules/form_test/form_test.routing.yml

@@ -378,6 +378,14 @@ form_test.button_class:
   requirements:
     _access: 'TRUE'
 
+form_test.description_display:
+  path: '/form_test/form-descriptions'
+  defaults:
+    _form: '\Drupal\form_test\Form\FormTestDescriptionForm'
+    _title: 'Form description test'
+  requirements:
+    _access: 'TRUE'
+
 form_test.group_details:
   path: '/form-test/group-details'
   defaults:

core/modules/system/tests/modules/form_test/src/Form/FormTestDescriptionForm.php

+<?php
+
+/**
+ * @file
+ * Contains \Drupal\form_test\Form\FormTestEmailForm.
+ */
+
+namespace Drupal\form_test\Form;
+
+use Drupal\Core\Form\FormBase;
+use Drupal\Core\Form\FormStateInterface;
+
+/**
+ * Defines a form for testing form element description display options.
+ *
+ * @see \Drupal\system\Tests\Form\ElementsLabelsTest::testFormDescriptions()
+ */
+class FormTestDescriptionForm extends FormBase {
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getFormId() {
+    return 'form_test_description_display';
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function buildForm(array $form, FormStateInterface $form_state) {
+    $form['form_textfield_test_description_before'] = array(
+      '#type' => 'textfield',
+      '#title' => 'Textfield test for description before element',
+      '#description' => 'Textfield test for description before element',
+      '#description_display' => 'before',
+    );
+
+    $form['form_textfield_test_description_after'] = array(
+      '#type' => 'textfield',
+      '#title' => 'Textfield test for description after element',
+      '#description' => 'Textfield test for description after element',
+      '#description_display' => 'after',
+    );
+
+    $form['form_textfield_test_description_invisible'] = array(
+      '#type' => 'textfield',
+      '#title' => 'Textfield test for visually-hidden description',
+      '#description' => 'Textfield test for visually-hidden description',
+      '#description_display' => 'invisible',
+    );
+
+    return $form;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function submitForm(array &$form, FormStateInterface $form_state) {
+    // The test that uses this form does not submit the form so this is empty.
+  }
+
+}