Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Checkboxes and radios form elements can both have descriptions added to each item (or indeed other specific form properties). However, this is not documented and not widely known.
It is however covered by our tests, in FormTestCheckboxesRadiosForm:
// Expand #type checkboxes, setting custom element properties for some but not
// all options.
$form['checkboxes'] = array(
'#type' => 'checkboxes',
'#title' => 'Checkboxes',
'#options' => array(
0 => 'Zero',
'foo' => 'Foo',
1 => 'One',
'bar' => $this->t('<em>Bar - checkboxes</em>'),
'>' => "<em>Special Char</em><script>alert('checkboxes');</script>",
),
);
if ($customize) {
$form['checkboxes'] += array(
'foo' => array(
'#description' => 'Enable to foo.',
),
1 => array(
'#weight' => 10,
),
);
}
The slightly clearer way to do this is as follows:
$form['checkboxes'] = array(
'#type' => 'checkboxes',
'#title' => 'Checkboxes',
'#options' => array(
'foo' => 'Foo',
'bar' => 'Bar',
);
$form['checkboxes']['foo']['#description'] = 'description for the foo checkbox';
Documentation should be added to the Checkboxes and Radios element classes.
| Comment | File | Size | Author |
|---|---|---|---|
| #5 | interdiff-2779999-3-5.txt | 1.33 KB | shashikant_chauhan |
| #5 | 2779999-5.patch | 1.19 KB | shashikant_chauhan |
| #3 | 2779999-3.patch | 1.05 KB | shashikant_chauhan |
Issue fork drupal-2779999
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
- 2779999-document-checkboxes-and
changes, plain diff MR !1681
1 hidden branch
Comments
Comment #3
shashikant_chauhan CreditAttribution: shashikant_chauhan as a volunteer and at Iksula commentedadding patch.
Comment #4
joachim CreditAttribution: joachim commentedThanks for the patch!
Good start but needs a bit more work I think:
The descriptions should be sentences with a capital and a full stop.
I'd also add a code comment within the code example that explains it, eg:
Comment #5
shashikant_chauhan CreditAttribution: shashikant_chauhan as a volunteer and at Iksula commentedThanks for the suggestion, adding updated patch.
Comment #6
David_Rothstein CreditAttribution: David_Rothstein as a volunteer commentedThe patch looks good. As a small documentation improvement there is no reason this shouldn't be added to 8.2.x also, and the patch applies there as well.
Note that the corresponding issue for documenting this for the Drupal 7 form API reference is #1349432: Mention checkboxes/radios options pre-setting in forms_api_reference.html.
Comment #7
xjmRather than putting a comment within a comment in the same
@code/@endcodeblock, let's start a new one and put the comment above it. So:Looks good to me other than that. Thanks!
Comment #8
joachim CreditAttribution: joachim commentedRe #7: taking the comment out of a code comment is a good thing, but:
this code in isolation means nothing. It only works if it's following the full radios/checkboxes definition.
Comment #9
David_Rothstein CreditAttribution: David_Rothstein as a volunteer commentedI agree. It is not a new code example, but rather part of the previous one.
That said, I'd be willing to mark a patch that did it either way RTBC :)
Comment #16
dpiComment #20
guilhermevp CreditAttribution: guilhermevp at CI&T commentedComment #22
guilhermevp CreditAttribution: guilhermevp at CI&T commentedMade a MR based on feedback #7, but #5 still applies. Please review!
Comment #23
guilhermevp CreditAttribution: guilhermevp at CI&T commentedComment #24
jonathanshawRTBC per #9
Comment #25
quietone CreditAttribution: quietone at PreviousNext commentedSetting to NW for unresolved comment.
Comment #26
joachim CreditAttribution: joachim commented> I am concerned that both 'high_school' and 'SAT' are culturally specific and may not mean much to anyone outside of countries that have high schools and use the 'SAT' test
> Yep. In addition to all that, I checked and "SAT" is also a registered trademark, which is another reason we should probably avoid referencing it (or any similar tests).
That all seems fair enough, but isn't that all out of scope for this issue? The SAT and high school stuff is already in the example code.
I'd be happy to work on a follow-up, but I don't think the bikeshedding over what to put instead should hold up a simple docs issue which has been hanging around for 6 years.
Comment #27
lauriiiCan we open a follow-up to address the feedback from the MR?
Comment #28
joachim CreditAttribution: joachim commentedDone: #3265929: Rewrite examples of form options to be less culturally specific.
Comment #30
dwwThis needed a trivial rebase to be merge-able. Leaving RTBC, since I didn't change any code.
Comment #34
lauriiiCommitted 46cc0e0 and pushed to 10.0.x. Also cherry-picked to 9.4.x. Thanks!
Comment #36
xjmCherry-picked to 9.3.x as a patch-release-eligible documentation improvement. Thanks!