You are here

Home » API reference » Drupal 8 » Checkbox.php

class Checkbox in Drupal 8

Same name and namespace in other branches
  1. 9 core/lib/Drupal/Core/Render/Element/Checkbox.php \Drupal\Core\Render\Element\Checkbox

Provides a form element for a single checkbox.

Properties:

  • #return_value: The value to return when the checkbox is checked.

Usage example:

$form['copy'] = array(
  '#type' => 'checkbox',
  '#title' => $this
    ->t('Send me a copy'),
);

Plugin annotation

@FormElement("checkbox");

Hierarchy

Expanded class hierarchy of Checkbox

See also

\Drupal\Core\Render\Element\Checkboxes

1 string reference to 'Checkbox'
FormTestCheckboxTypeJugglingForm::buildForm in core/modules/system/tests/modules/form_test/src/Form/FormTestCheckboxTypeJugglingForm.php
Form constructor.
198 #type uses of Checkbox
AccountForm::form in core/modules/user/src/AccountForm.php
Gets the actual form array to be built.
AccountSettingsForm::buildForm in core/modules/user/src/AccountSettingsForm.php
Form constructor.
ActionAjaxTest::buildConfigurationForm in core/modules/action/tests/action_form_ajax_test/src/Plugin/Action/ActionAjaxTest.php
Form constructor.
AddFormBase::buildSelectedItemElement in core/modules/media_library/src/Form/AddFormBase.php
Returns a render array for a single pre-selected media item.
AdvancedSettingsForm::buildForm in core/modules/views_ui/src/Form/AdvancedSettingsForm.php
Form constructor.

... See full list

File

core/lib/Drupal/Core/Render/Element/Checkbox.php, line 26

Namespace

Drupal\Core\Render\Element
View source 
class Checkbox extends FormElement {

  /**
   * {@inheritdoc}
   */
  public function getInfo() {
    $class = get_class($this);
    return [
      '#input' => TRUE,
      '#return_value' => 1,
      '#process' => [
        [
          $class,
          'processCheckbox',
        ],
        [
          $class,
          'processAjaxForm',
        ],
        [
          $class,
          'processGroup',
        ],
      ],
      '#pre_render' => [
        [
          $class,
          'preRenderCheckbox',
        ],
        [
          $class,
          'preRenderGroup',
        ],
      ],
      '#theme' => 'input__checkbox',
      '#theme_wrappers' => [
        'form_element',
      ],
      '#title_display' => 'after',
    ];
  }

  /**
   * {@inheritdoc}
   */
  public static function valueCallback(&$element, $input, FormStateInterface $form_state) {
    if ($input === FALSE) {

      // Use #default_value as the default value of a checkbox, except change
      // NULL to 0, because FormBuilder::handleInputElement() would otherwise
      // replace NULL with empty string, but an empty string is a potentially
      // valid value for a checked checkbox.
      return isset($element['#default_value']) ? $element['#default_value'] : 0;
    }
    else {

      // Checked checkboxes are submitted with a value (possibly '0' or ''):
      // http://www.w3.org/TR/html401/interact/forms.html#successful-controls.
      // For checked checkboxes, browsers submit the string version of
      // #return_value, but we return the original #return_value. For unchecked
      // checkboxes, browsers submit nothing at all, but
      // FormBuilder::handleInputElement() detects this, and calls this
      // function with $input=NULL. Returning NULL from a value callback means
      // to use the default value, which is not what is wanted when an unchecked
      // checkbox is submitted, so we use integer 0 as the value indicating an
      // unchecked checkbox. Therefore, modules must not use integer 0 as a
      // #return_value, as doing so results in the checkbox always being treated
      // as unchecked. The string '0' is allowed for #return_value. The most
      // common use-case for setting #return_value to either 0 or '0' is for the
      // first option within a 0-indexed array of checkboxes, and for this,
      // \Drupal\Core\Render\Element\Checkboxes::processCheckboxes() uses the
      // string rather than the integer.
      return isset($input) ? $element['#return_value'] : 0;
    }
  }

  /**
   * Prepares a #type 'checkbox' render element for input.html.twig.
   *
   * @param array $element
   *   An associative array containing the properties of the element.
   *   Properties used: #title, #value, #return_value, #description, #required,
   *   #attributes, #checked.
   *
   * @return array
   *   The $element with prepared variables ready for input.html.twig.
   */
  public static function preRenderCheckbox($element) {
    $element['#attributes']['type'] = 'checkbox';
    Element::setAttributes($element, [
      'id',
      'name',
      '#return_value' => 'value',
    ]);

    // Unchecked checkbox has #value of integer 0.
    if (!empty($element['#checked'])) {
      $element['#attributes']['checked'] = 'checked';
    }
    static::setAttributes($element, [
      'form-checkbox',
    ]);
    return $element;
  }

  /**
   * Sets the #checked property of a checkbox element.
   */
  public static function processCheckbox(&$element, FormStateInterface $form_state, &$complete_form) {
    $value = $element['#value'];
    $return_value = $element['#return_value'];

    // On form submission, the #value of an available and enabled checked
    // checkbox is #return_value, and the #value of an available and enabled
    // unchecked checkbox is integer 0. On not submitted forms, and for
    // checkboxes with #access=FALSE or #disabled=TRUE, the #value is
    // #default_value (integer 0 if #default_value is NULL). Most of the time,
    // a string comparison of #value and #return_value is sufficient for
    // determining the "checked" state, but a value of TRUE always means checked
    // (even if #return_value is 'foo'), and a value of FALSE or integer 0
    // always means unchecked (even if #return_value is '' or '0').
    if ($value === TRUE || $value === FALSE || $value === 0) {
      $element['#checked'] = (bool) $value;
    }
    else {

      // Compare as strings, so that 15 is not considered equal to '15foo', but
      // 1 is considered equal to '1'. This cast does not imply that either
      // #value or #return_value is expected to be a string.
      $element['#checked'] = (string) $value === (string) $return_value;
    }
    return $element;
  }

}

Members

Namesort descending Modifiers Type Description Overrides
Checkbox::getInfo public function Returns the element properties for this element. Overrides ElementInterface::getInfo
Checkbox::preRenderCheckbox public static function Prepares a #type 'checkbox' render element for input.html.twig.
Checkbox::processCheckbox public static function Sets the #checked property of a checkbox element.
Checkbox::valueCallback public static function Determines how user input is mapped to an element's #value property. Overrides FormElement::valueCallback
DependencySerializationTrait::$_entityStorages protected property An array of entity type IDs keyed by the property name of their storages.
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
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.
MessengerTrait::$messenger protected property The messenger. 29
MessengerTrait::messenger public function Gets the messenger. 29
MessengerTrait::setMessenger public function Sets the messenger.
PluginBase::$configuration protected property Configuration information passed into the plugin. 1
PluginBase::$pluginDefinition protected property The plugin implementation definition. 1
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 3
PluginBase::getPluginId public function Gets the plugin_id of the plugin instance. Overrides PluginInspectionInterface::getPluginId
PluginBase::isConfigurable public function Determines if the plugin is configurable.
PluginBase::__construct public function Constructs a \Drupal\Component\Plugin\PluginBase object. 92
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. 1
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. 1
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.