You are here

Home » API reference » Zircon Profile 8 » FormElement.php

abstract class FormElement in Zircon Profile 8

Same name in this branch
  1. 8 core/lib/Drupal/Core/Render/Annotation/FormElement.php \Drupal\Core\Render\Annotation\FormElement
  2. 8 core/lib/Drupal/Core/Render/Element/FormElement.php \Drupal\Core\Render\Element\FormElement
Same name and namespace in other branches
  1. 8.0 core/lib/Drupal/Core/Render/Element/FormElement.php \Drupal\Core\Render\Element\FormElement

Provides a base class for form element plugins.

Form elements are a subset of render elements, representing elements for HTML forms, which can be referenced in form arrays. See the Render API topic for an overview of render arrays and render elements, and the Form API topic for an overview of forms and form arrays.

The elements of form arrays are divided up into properties (whose keys start with #) and children (whose keys do not start with #). The properties provide data or settings that are used in rendering and form processing. Some properties are specific to a particular type of form/render element, some are available for any render element, and some are available for any form input element. A list of the properties that are available for all form elements follows; see \Drupal\Core\Render\Element\RenderElement for some additional information, as well as a list of properties that are common to all render elements (including form elements). Properties specific to a particular element are documented on that element's class.

Here is a list of properties that are used during the rendering and form processing of form elements:

  • #after_build: (array) Array of callables or function names, which are called after the element is built. Arguments: $element, $form_state.
  • #ajax: (array) Array of elements to specify Ajax behavior. See the Ajax API topic for more information.
  • #array_parents: (string[], read-only) Array of names of all the element's parents (including itself) in the render array. See also #parents, #tree.
  • #default_value: Default value for the element. See also #value.
  • #description: (string) Help or description text for the element. In an ideal user interface, the #title should be enough to describe the element, so most elements should not have a description; if you do need one, make sure it is translated. If it is not already wrapped in a safe markup object, it will be filtered for XSS safety.
  • #disabled: (bool) If TRUE, the element is shown but does not accept user input.
  • #element_validate: (array) Array of callables or function names, which are called to validate the input. Arguments: $element, $form_state, $form.
  • #field_prefix: (string) Prefix to display before the HTML input element. Should be translated, normally. If it is not already wrapped in a safe markup object, will be filtered for XSS safety.
  • #field_suffix: (string) Suffix to display after the HTML input element. Should be translated, normally. If it is not already wrapped in a safe markup object, will be filtered for XSS safety.
  • #input: (bool, internal) Whether or not the element accepts input.
  • #parents: (string[], read-only) Array of names of the element's parents for purposes of getting values out of $form_state. See also #array_parents, #tree.
  • #process: (array) Array of callables or function names, which are called during form building. Arguments: $element, $form_state, $form.
  • #processed: (bool, internal) Set to TRUE when the element is processed.
  • #required: (bool) Whether or not input is required on the element.
  • #states: (array) Information about JavaScript states, such as when to hide or show the element based on input on other elements. See drupal_process_states() for documentation.
  • #title: (string) Title of the form element. Should be translated.
  • #title_display: (string) Where and how to display the #title. Possible values:

    • before: Label goes before the element (default for most elements).
    • after: Label goes after the element (default for radio elements).
    • invisible: Label is there but is made invisible using CSS.
    • attribute: Make it the title attribute (hover tooltip).
  • #tree: (bool) TRUE if the values of this element and its children should be hierarchical in $form_state; FALSE if the values should be flat. See also #parents, #array_parents.
  • #value_callback: (callable) Callable or function name, which is called to transform the raw user input to the element's value. Arguments: $element, $input, $form_state.

Hierarchy

Expanded class hierarchy of FormElement

See also

\Drupal\Core\Render\Annotation\FormElement

\Drupal\Core\Render\Element\FormElementInterface

\Drupal\Core\Render\ElementInfoManager

Plugin API

Related topics

Render API overview
Overview of the Theme system and Render API.
3 files declare their use of FormElement
DateElementBase.php in core/lib/Drupal/Core/Datetime/Element/DateElementBase.php
Contains \Drupal\Core\Datetime\Element\DateElementBase.
LanguageConfiguration.php in core/modules/language/src/Element/LanguageConfiguration.php
Contains \Drupal\language\Element\LanguageConfiguration.
ManagedFile.php in core/modules/file/src/Element/ManagedFile.php
Contains \Drupal\file\Element\ManagedFile.

File

core/lib/Drupal/Core/Render/Element/FormElement.php, line 90
Contains \Drupal\Core\Render\Element\FormElement.

Namespace

Drupal\Core\Render\Element
View source 
abstract class FormElement extends RenderElement implements FormElementInterface {

  /**
   * {@inheritdoc}
   */
  public static function valueCallback(&$element, $input, FormStateInterface $form_state) {
    return NULL;
  }

  /**
   * #process callback for #pattern form element property.
   *
   * @param array $element
   *   An associative array containing the properties and children of the
   *   generic input element.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form.
   * @param array $complete_form
   *   The complete form structure.
   *
   * @return array
   *   The processed element.
   */
  public static function processPattern(&$element, FormStateInterface $form_state, &$complete_form) {
    if (isset($element['#pattern']) && !isset($element['#attributes']['pattern'])) {
      $element['#attributes']['pattern'] = $element['#pattern'];
      $element['#element_validate'][] = array(
        get_called_class(),
        'validatePattern',
      );
    }
    return $element;
  }

  /**
   * #element_validate callback for #pattern form element property.
   *
   * @param $element
   *   An associative array containing the properties and children of the
   *   generic form element.
   * @param $form_state
   *   The current state of the form.
   * @param array $complete_form
   *   The complete form structure.
   */
  public static function validatePattern(&$element, FormStateInterface $form_state, &$complete_form) {
    if ($element['#value'] !== '') {

      // The pattern must match the entire string and should have the same
      // behavior as the RegExp object in ECMA 262.
      // - Use bracket-style delimiters to avoid introducing a special delimiter
      //   character like '/' that would have to be escaped.
      // - Put in brackets so that the pattern can't interfere with what's
      //   prepended and appended.
      $pattern = '{^(?:' . $element['#pattern'] . ')$}';
      if (!preg_match($pattern, $element['#value'])) {
        $form_state
          ->setError($element, t('%name field is not in the right format.', array(
          '%name' => $element['#title'],
        )));
      }
    }
  }

  /**
   * Adds autocomplete functionality to elements.
   *
   * This sets up autocomplete functionality for elements with an
   * #autocomplete_route_name property, using the #autocomplete_route_parameters
   * property if present.
   *
   * For example, suppose your autocomplete route name is
   * 'mymodule.autocomplete' and its path is
   * '/mymodule/autocomplete/{a}/{b}'. In a form array, you would create a text
   * field with properties:
   * @code
   * '#autocomplete_route_name' => 'mymodule.autocomplete',
   * '#autocomplete_route_parameters' => array('a' => $some_key, 'b' => $some_id),
   * @endcode
   * If the user types "keywords" in that field, the full path called would be:
   * 'mymodule_autocomplete/$some_key/$some_id?q=keywords'
   *
   * @param array $element
   *   The form element to process. Properties used:
   *   - #autocomplete_route_name: A route to be used as callback URL by the
   *     autocomplete JavaScript library.
   *   - #autocomplete_route_parameters: The parameters to be used in
   *     conjunction with the route name.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form.
   * @param array $complete_form
   *   The complete form structure.
   *
   * @return array
   *   The form element.
   */
  public static function processAutocomplete(&$element, FormStateInterface $form_state, &$complete_form) {
    $url = NULL;
    $access = FALSE;
    if (!empty($element['#autocomplete_route_name'])) {
      $parameters = isset($element['#autocomplete_route_parameters']) ? $element['#autocomplete_route_parameters'] : array();
      $url = Url::fromRoute($element['#autocomplete_route_name'], $parameters)
        ->toString(TRUE);

      /** @var \Drupal\Core\Access\AccessManagerInterface $access_manager */
      $access_manager = \Drupal::service('access_manager');
      $access = $access_manager
        ->checkNamedRoute($element['#autocomplete_route_name'], $parameters, \Drupal::currentUser(), TRUE);
    }
    if ($access) {
      $metadata = BubbleableMetadata::createFromRenderArray($element);
      if ($access
        ->isAllowed()) {
        $element['#attributes']['class'][] = 'form-autocomplete';
        $metadata
          ->addAttachments([
          'library' => [
            'core/drupal.autocomplete',
          ],
        ]);

        // Provide a data attribute for the JavaScript behavior to bind to.
        $element['#attributes']['data-autocomplete-path'] = $url
          ->getGeneratedUrl();
        $metadata = $metadata
          ->merge($url);
      }
      $metadata
        ->merge(BubbleableMetadata::createFromObject($access))
        ->applyTo($element);
    }
    return $element;
  }

}

Members

Namesort descending Modifiers Type Description Overrides
DependencySerializationTrait::$_serviceIds protected property An array of service IDs keyed by property name used for serialization.
DependencySerializationTrait::__sleep public function 1
DependencySerializationTrait::__wakeup public function 2
ElementInterface::getInfo public function Returns the element properties for this element. 52
FormElement::processAutocomplete public static function Adds autocomplete functionality to elements.
FormElement::processPattern public static function #process callback for #pattern form element property.
FormElement::validatePattern public static function #element_validate callback for #pattern form element property.
FormElement::valueCallback public static function Determines how user input is mapped to an element's #value property. Overrides FormElementInterface::valueCallback 15
PluginBase::$configuration protected property Configuration information passed into the plugin. 2
PluginBase::$pluginDefinition protected property The plugin implementation definition.
PluginBase::$pluginId protected property The plugin_id.
PluginBase::DERIVATIVE_SEPARATOR constant A string which is used to separate base plugin IDs from the derivative ID.
PluginBase::getBaseId public function Gets the base_plugin_id of the plugin instance. Overrides DerivativeInspectionInterface::getBaseId
PluginBase::getDerivativeId public function Gets the derivative_id of the plugin instance. Overrides DerivativeInspectionInterface::getDerivativeId
PluginBase::getPluginDefinition public function Gets the definition of the plugin implementation. Overrides PluginInspectionInterface::getPluginDefinition
PluginBase::getPluginId public function Gets the plugin_id of the plugin instance. Overrides PluginInspectionInterface::getPluginId
PluginBase::__construct public function Constructs a Drupal\Component\Plugin\PluginBase object. 69
RenderElement::preRenderAjaxForm public static function Adds Ajax information about an element to communicate with JavaScript.
RenderElement::preRenderGroup public static function Adds members of this group as actual elements for rendering.
RenderElement::processAjaxForm public static function Form element processing handler for the #ajax form property.
RenderElement::processGroup public static function Arranges elements into groups.
RenderElement::setAttributes public static function Sets a form element's class attribute. Overrides ElementInterface::setAttributes
StringTranslationTrait::$stringTranslation protected property The string translation service.
StringTranslationTrait::formatPlural protected function Formats a string containing a count of items.
StringTranslationTrait::getNumberOfPlurals protected function Returns the number of plurals supported by a given language.
StringTranslationTrait::getStringTranslation protected function Gets the string translation service.
StringTranslationTrait::setStringTranslation public function Sets the string translation service to use. 2
StringTranslationTrait::t protected function Translates a string to the current language or to a given language.