aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Render/Element/Checkbox.php

   1 <?php
   2
   3 namespace Drupal\Core\Render\Element;
   4
   5 use Drupal\Core\Form\FormStateInterface;
   6 use Drupal\Core\Render\Element;
   7
   8 /**
   9  * Provides a form element for a single checkbox.
  10  *
  11  * Properties:
  12  * - #return_value: The value to return when the checkbox is checked.
  13  *
  14  * Usage example:
  15  * @code
  16  * $form['copy'] = array(
  17  *   '#type' => 'checkbox',
  18  *   '#title' => $this->t('Send me a copy'),
  19  * );
  20  * @endcode
  21  *
  22  * @see \Drupal\Core\Render\Element\Checkboxes
  23  *
  24  * @FormElement("checkbox")
  25  */
  26 class Checkbox extends FormElement {
  27
  28   /**
  29    * {@inheritdoc}
  30    */
  31   public function getInfo() {
  32     $class = get_class($this);
  33     return [
  34       '#input' => TRUE,
  35       '#return_value' => 1,
  36       '#process' => [
  37         [$class, 'processCheckbox'],
  38         [$class, 'processAjaxForm'],
  39         [$class, 'processGroup'],
  40       ],
  41       '#pre_render' => [
  42         [$class, 'preRenderCheckbox'],
  43         [$class, 'preRenderGroup'],
  44       ],
  45       '#theme' => 'input__checkbox',
  46       '#theme_wrappers' => ['form_element'],
  47       '#title_display' => 'after',
  48     ];
  49   }
  50
  51   /**
  52    * {@inheritdoc}
  53    */
  54   public static function valueCallback(&$element, $input, FormStateInterface $form_state) {
  55     if ($input === FALSE) {
  56       // Use #default_value as the default value of a checkbox, except change
  57       // NULL to 0, because FormBuilder::handleInputElement() would otherwise
  58       // replace NULL with empty string, but an empty string is a potentially
  59       // valid value for a checked checkbox.
  60       return isset($element['#default_value']) ? $element['#default_value'] : 0;
  61     }
  62     else {
  63       // Checked checkboxes are submitted with a value (possibly '0' or ''):
  64       // http://www.w3.org/TR/html401/interact/forms.html#successful-controls.
  65       // For checked checkboxes, browsers submit the string version of
  66       // #return_value, but we return the original #return_value. For unchecked
  67       // checkboxes, browsers submit nothing at all, but
  68       // FormBuilder::handleInputElement() detects this, and calls this
  69       // function with $input=NULL. Returning NULL from a value callback means
  70       // to use the default value, which is not what is wanted when an unchecked
  71       // checkbox is submitted, so we use integer 0 as the value indicating an
  72       // unchecked checkbox. Therefore, modules must not use integer 0 as a
  73       // #return_value, as doing so results in the checkbox always being treated
  74       // as unchecked. The string '0' is allowed for #return_value. The most
  75       // common use-case for setting #return_value to either 0 or '0' is for the
  76       // first option within a 0-indexed array of checkboxes, and for this,
  77       // \Drupal\Core\Render\Element\Checkboxes::processCheckboxes() uses the
  78       // string rather than the integer.
  79       return isset($input) ? $element['#return_value'] : 0;
  80     }
  81   }
  82
  83   /**
  84    * Prepares a #type 'checkbox' render element for input.html.twig.
  85    *
  86    * @param array $element
  87    *   An associative array containing the properties of the element.
  88    *   Properties used: #title, #value, #return_value, #description, #required,
  89    *   #attributes, #checked.
  90    *
  91    * @return array
  92    *   The $element with prepared variables ready for input.html.twig.
  93    */
  94   public static function preRenderCheckbox($element) {
  95     $element['#attributes']['type'] = 'checkbox';
  96     Element::setAttributes($element, ['id', 'name', '#return_value' => 'value']);
  97
  98     // Unchecked checkbox has #value of integer 0.
  99     if (!empty($element['#checked'])) {
 100       $element['#attributes']['checked'] = 'checked';
 101     }
 102     static::setAttributes($element, ['form-checkbox']);
 103
 104     return $element;
 105   }
 106
 107   /**
 108    * Sets the #checked property of a checkbox element.
 109    */
 110   public static function processCheckbox(&$element, FormStateInterface $form_state, &$complete_form) {
 111     $value = $element['#value'];
 112     $return_value = $element['#return_value'];
 113     // On form submission, the #value of an available and enabled checked
 114     // checkbox is #return_value, and the #value of an available and enabled
 115     // unchecked checkbox is integer 0. On not submitted forms, and for
 116     // checkboxes with #access=FALSE or #disabled=TRUE, the #value is
 117     // #default_value (integer 0 if #default_value is NULL). Most of the time,
 118     // a string comparison of #value and #return_value is sufficient for
 119     // determining the "checked" state, but a value of TRUE always means checked
 120     // (even if #return_value is 'foo'), and a value of FALSE or integer 0
 121     // always means unchecked (even if #return_value is '' or '0').
 122     if ($value === TRUE || $value === FALSE || $value === 0) {
 123       $element['#checked'] = (bool) $value;
 124     }
 125     else {
 126       // Compare as strings, so that 15 is not considered equal to '15foo', but
 127       // 1 is considered equal to '1'. This cast does not imply that either
 128       // #value or #return_value is expected to be a string.
 129       $element['#checked'] = ((string) $value === (string) $return_value);
 130     }
 131     return $element;
 132   }
 133
 134 }