function template_preprocess_form_element in Drupal 9

Same name and namespace in other branches

1. 8 core/includes/form.inc \template_preprocess_form_element()
2. 10 core/includes/form.inc \template_preprocess_form_element()

Returns HTML for a form element. Prepares variables for form element templates.

Default template: form-element.html.twig.

In addition to the element itself, the DIV contains a label for the element based on the optional #title_display property, and an optional #description.

The optional #title_display property can have these values:

• before: The label is output before the element. This is the default. The label includes the #title and the required marker, if #required.
• after: The label is output after the element. For example, this is used for radio and checkbox #type elements. If the #title is empty but the field is #required, the label will contain only the required marker.
• invisible: Labels are critical for screen readers to enable them to properly navigate through forms but can be visually distracting. This property hides the label for everyone except screen readers.
• attribute: Set the title attribute on the element to create a tooltip but output no label element. This is supported only for checkboxes and radios in \Drupal\Core\Render\Element\CompositeFormElementTrait::preRenderCompositeFormElement(). It is used where a visual label is not needed, such as a table of checkboxes where the row and column provide the context. The tooltip will include the title and required marker.

If the #title property is not set, then the label and any required marker will not be output, regardless of the #title_display or #required values. This can be useful in cases such as the password_confirm element, which creates children elements that have their own labels and required markers, but the parent element should have neither. Use this carefully because a field without an associated label can cause accessibility challenges.

To associate the label with a different field, set the #label_for property to the ID of the desired field.

Parameters

array $variables: An associative array containing:

• element: An associative array containing the properties of the element. Properties used: #title, #title_display, #description, #id, #required, #children, #type, #name, #label_for.

File

core/includes/form.inc, line 440

Functions for form and batch generation and processing.

Code

function template_preprocess_form_element(&$variables) {
  $element =& $variables['element'];

  // This function is invoked as theme wrapper, but the rendered form element
  // may not necessarily have been processed by
  // \Drupal::formBuilder()->doBuildForm().
  $element += [
    '#title_display' => 'before',
    '#wrapper_attributes' => [],
    '#label_attributes' => [],
    '#label_for' => NULL,
  ];
  $variables['attributes'] = $element['#wrapper_attributes'];

  // Add element #id for #type 'item'.
  if (isset($element['#markup']) && !empty($element['#id'])) {
    $variables['attributes']['id'] = $element['#id'];
  }

  // Pass elements #type and #name to template.
  if (!empty($element['#type'])) {
    $variables['type'] = $element['#type'];
  }
  if (!empty($element['#name'])) {
    $variables['name'] = $element['#name'];
  }

  // Pass elements disabled status to template.
  $variables['disabled'] = !empty($element['#attributes']['disabled']) ? $element['#attributes']['disabled'] : NULL;

  // Suppress error messages.
  $variables['errors'] = NULL;

  // If #title is not set, we don't display any label.
  if (!isset($element['#title'])) {
    $element['#title_display'] = 'none';
  }
  $variables['title_display'] = $element['#title_display'];
  $variables['prefix'] = isset($element['#field_prefix']) ? $element['#field_prefix'] : NULL;
  $variables['suffix'] = isset($element['#field_suffix']) ? $element['#field_suffix'] : NULL;
  $variables['description'] = NULL;
  if (!empty($element['#description'])) {
    $variables['description_display'] = $element['#description_display'];
    $description_attributes = [];
    if (!empty($element['#id'])) {
      $description_attributes['id'] = $element['#id'] . '--description';
    }
    $variables['description']['attributes'] = new Attribute($description_attributes);
    $variables['description']['content'] = $element['#description'];
  }

  // Add label_display and label variables to template.
  $variables['label_display'] = $element['#title_display'];
  $variables['label'] = [
    '#theme' => 'form_element_label',
  ];
  $variables['label'] += array_intersect_key($element, array_flip([
    '#id',
    '#required',
    '#title',
    '#title_display',
  ]));
  $variables['label']['#attributes'] = $element['#label_attributes'];
  if (!empty($element['#label_for'])) {
    $variables['label']['#for'] = $element['#label_for'];
    if (!empty($element['#id'])) {
      $variables['label']['#id'] = $element['#id'] . '--label';
    }
  }
  $variables['children'] = $element['#children'];
}