class Checkboxes
Same name in other branches
- 9 core/lib/Drupal/Core/Render/Element/Checkboxes.php \Drupal\Core\Render\Element\Checkboxes
- 8.9.x core/lib/Drupal/Core/Render/Element/Checkboxes.php \Drupal\Core\Render\Element\Checkboxes
- 10 core/lib/Drupal/Core/Render/Element/Checkboxes.php \Drupal\Core\Render\Element\Checkboxes
Provides a form element for a set of checkboxes.
Properties:
- #options: An associative array whose keys are the values returned for each checkbox, and whose values are the labels next to each checkbox. The #options array cannot have a 0 key, as it would not be possible to discern checked and unchecked states.
Usage example:
$form['favorites']['colors'] = [
'#type' => 'checkboxes',
'#options' => ['blue' => $this->t('Blue'), 'red' => $this->t('Red')],
'#title' => $this->t('Which colors do you like?'),
...
];
Element properties may be set on single option items as follows.
$form['favorites']['colors']['blue']['#description'] = $this->t('The color of the sky.');
Hierarchy
- class \Drupal\Component\Plugin\PluginBase implements \Drupal\Component\Plugin\PluginInspectionInterface, \Drupal\Component\Plugin\DerivativeInspectionInterface
- class \Drupal\Core\Plugin\PluginBase extends \Drupal\Component\Plugin\PluginBase uses \Drupal\Core\StringTranslation\StringTranslationTrait, \Drupal\Core\DependencyInjection\DependencySerializationTrait, \Drupal\Core\Messenger\MessengerTrait
- class \Drupal\Core\Render\Element\RenderElementBase extends \Drupal\Core\Plugin\PluginBase implements \Drupal\Core\Render\Element\ElementInterface
- class \Drupal\Core\Render\Element\FormElementBase extends \Drupal\Core\Render\Element\RenderElementBase implements \Drupal\Core\Render\Element\FormElementInterface
- class \Drupal\Core\Render\Element\Checkboxes extends \Drupal\Core\Render\Element\FormElementBase uses \Drupal\Core\Render\Element\CompositeFormElementTrait
- class \Drupal\Core\Render\Element\FormElementBase extends \Drupal\Core\Render\Element\RenderElementBase implements \Drupal\Core\Render\Element\FormElementInterface
- class \Drupal\Core\Render\Element\RenderElementBase extends \Drupal\Core\Plugin\PluginBase implements \Drupal\Core\Render\Element\ElementInterface
- class \Drupal\Core\Plugin\PluginBase extends \Drupal\Component\Plugin\PluginBase uses \Drupal\Core\StringTranslation\StringTranslationTrait, \Drupal\Core\DependencyInjection\DependencySerializationTrait, \Drupal\Core\Messenger\MessengerTrait
Expanded class hierarchy of Checkboxes
See also
\Drupal\Core\Render\Element\Radios
\Drupal\Core\Render\Element\Checkbox
3 files declare their use of Checkboxes
- FilterPluginBase.php in core/
modules/ views/ src/ Plugin/ views/ filter/ FilterPluginBase.php - ViewsExposedForm.php in core/
modules/ views/ src/ Form/ ViewsExposedForm.php - views_ui.theme.inc in core/
modules/ views_ui/ views_ui.theme.inc - Preprocessors and theme functions for the Views UI.
18 string references to 'Checkboxes'
- Checkboxes::getInfo in core/
lib/ Drupal/ Core/ Render/ Element/ Checkboxes.php - Returns the element properties for this element.
- claro_preprocess_fieldset in core/
themes/ claro/ claro.theme - Implements template_preprocess_HOOK() for fieldset.
- ContentTranslationHandler::addTranslatabilityClue in core/
modules/ content_translation/ src/ ContentTranslationHandler.php - Adds a clue about the form element translatability.
- ElementTest::testOptions in core/
modules/ system/ tests/ src/ Functional/ Form/ ElementTest.php - Tests expansion of #options for #type checkboxes and radios.
- ElementTest::testWrapperIds in core/
modules/ system/ tests/ src/ Functional/ Form/ ElementTest.php - Tests wrapper ids for checkboxes and radios.
File
-
core/
lib/ Drupal/ Core/ Render/ Element/ Checkboxes.php, line 36
Namespace
Drupal\Core\Render\ElementView source
class Checkboxes extends FormElementBase {
use CompositeFormElementTrait;
/**
* {@inheritdoc}
*/
public function getInfo() {
$class = static::class;
return [
'#input' => TRUE,
'#process' => [
[
$class,
'processCheckboxes',
],
],
'#pre_render' => [
[
$class,
'preRenderCompositeFormElement',
],
],
'#theme_wrappers' => [
'checkboxes',
],
];
}
/**
* Processes a checkboxes form element.
*/
public static function processCheckboxes(&$element, FormStateInterface $form_state, &$complete_form) {
$value = is_array($element['#value']) ? $element['#value'] : [];
$element['#tree'] = TRUE;
if (count($element['#options']) > 0) {
if (!isset($element['#default_value']) || $element['#default_value'] == 0) {
$element['#default_value'] = [];
}
$weight = 0;
foreach ($element['#options'] as $key => $choice) {
// Integer 0 is not a valid #return_value, so use '0' instead.
// @see \Drupal\Core\Render\Element\Checkbox::valueCallback().
// @todo For Drupal 8, cast all integer keys to strings for consistency
// with \Drupal\Core\Render\Element\Radios::processRadios().
if ($key === 0) {
$key = '0';
}
// Maintain order of options as defined in #options, in case the element
// defines custom option sub-elements, but does not define all option
// sub-elements.
$weight += 0.001;
// Only enabled checkboxes receive their values from the form
// submission, the disabled checkboxes use their default value.
$default_value = NULL;
if (isset($value[$key]) || !empty($element[$key]['#disabled']) && in_array($key, $element['#default_value'], TRUE)) {
$default_value = $key;
}
$element += [
$key => [],
];
$element[$key] += [
'#type' => 'checkbox',
'#title' => $choice,
'#return_value' => $key,
'#default_value' => $default_value,
'#attributes' => $element['#attributes'],
'#ajax' => $element['#ajax'] ?? NULL,
// Errors should only be shown on the parent checkboxes element.
'#error_no_message' => TRUE,
'#weight' => $weight,
];
}
}
return $element;
}
/**
* {@inheritdoc}
*/
public static function valueCallback(&$element, $input, FormStateInterface $form_state) {
if ($input === FALSE) {
$value = [];
$element += [
'#default_value' => [],
];
foreach ($element['#default_value'] as $key) {
$value[$key] = $key;
}
return $value;
}
elseif (is_array($input)) {
// Programmatic form submissions use NULL to indicate that a checkbox
// should be unchecked. We therefore remove all NULL elements from the
// array before constructing the return value, to simulate the behavior
// of web browsers (which do not send unchecked checkboxes to the server
// at all). This will not affect non-programmatic form submissions, since
// all values in \Drupal::request()->request are strings.
// @see \Drupal\Core\Form\FormBuilderInterface::submitForm()
foreach ($input as $key => $value) {
if (!isset($value)) {
unset($input[$key]);
}
}
// Because the disabled checkboxes don't receive their input from the
// form submission, we use their default value.
if (!empty($element['#default_value'])) {
foreach ($element['#default_value'] as $key) {
if (!empty($element[$key]['#disabled'])) {
$input[$key] = $key;
}
}
}
return array_combine($input, $input);
}
else {
return [];
}
}
/**
* Determines which checkboxes were checked when a form is submitted.
*
* @param array $input
* An array returned by the FormAPI for a set of checkboxes.
*
* @return array
* An array of keys that were checked.
*/
public static function getCheckedCheckboxes(array $input) {
// Browsers do not include unchecked options in a form submission. The
// FormAPI tries to normalize this to keep checkboxes consistent with other
// form elements. Checkboxes show up as an array in the form of option_id =>
// option_id|0, where integer 0 is an unchecked option.
//
// @see \Drupal\Core\Render\Element\Checkboxes::valueCallback()
// @see https://www.w3.org/TR/html401/interact/forms.html#checkbox
$checked = array_filter($input, function ($value) {
return $value !== 0;
});
return array_keys($checked);
}
/**
* Determines if all checkboxes in a set are unchecked.
*
* @param array $input
* An array returned by the FormAPI for a set of checkboxes.
*
* @return bool
* TRUE if all options are unchecked. FALSE otherwise.
*/
public static function detectEmptyCheckboxes(array $input) {
return empty(static::getCheckedCheckboxes($input));
}
}
Members
Title Sort descending | Modifiers | Object type | Summary | Overriden Title | Overrides |
---|---|---|---|---|---|
Checkboxes::detectEmptyCheckboxes | public static | function | Determines if all checkboxes in a set are unchecked. | ||
Checkboxes::getCheckedCheckboxes | public static | function | Determines which checkboxes were checked when a form is submitted. | ||
Checkboxes::getInfo | public | function | Returns the element properties for this element. | Overrides ElementInterface::getInfo | |
Checkboxes::processCheckboxes | public static | function | Processes a checkboxes form element. | ||
Checkboxes::valueCallback | public static | function | Determines how user input is mapped to an element's #value property. | Overrides FormElementBase::valueCallback | |
CompositeFormElementTrait::preRenderCompositeFormElement | public static | function | Adds form element theming to an element if its title or description is set. | ||
FormElementBase::processAutocomplete | public static | function | Adds autocomplete functionality to elements. | 1 | |
FormElementBase::processPattern | public static | function | #process callback for #pattern form element property. | 1 | |
FormElementBase::validatePattern | public static | function | #element_validate callback for #pattern form element property. | 1 | |
PluginInspectionInterface::getPluginDefinition | public | function | Gets the definition of the plugin implementation. | 6 | |
PluginInspectionInterface::getPluginId | public | function | Gets the plugin ID of the plugin instance. | 2 | |
RenderElementBase::preRenderAjaxForm | public static | function | Adds Ajax information about an element to communicate with JavaScript. | 2 | |
RenderElementBase::preRenderGroup | public static | function | Adds members of this group as actual elements for rendering. | 2 | |
RenderElementBase::processAjaxForm | public static | function | Form element processing handler for the #ajax form property. | 3 | |
RenderElementBase::processGroup | public static | function | Arranges elements into groups. | 2 | |
RenderElementBase::setAttributes | public static | function | Overrides ElementInterface::setAttributes | 2 |
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.