Rewrite examples of form options to be less culturally specific [#3265929]

Problem/Motivation

On #2779999: Document checkboxes and radios element can have individual descriptions it was pointed out that the sample code for checkboxes and radios form elements is culturally specific. @quietone wrote in the MR review:

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. I spoke to xjm and she thought 'high_school' was acceptable and then reminded me of the controversy about the 'SAT' test being biased, such as racially, economically, and gender. Therefor, let's use a different example.

The current example code is:

 * Usage example:
 * @code
 * $form['high_school']['tests_taken'] = array(
 *   '#type' => 'checkboxes',
 *   '#options' => array('SAT' => $this->t('SAT'), 'ACT' => $this->t('ACT')),
 *   '#title' => $this->t('What standardized tests did you take?'),
 *   ...
 * );
 * @endcode
 *
 * Element properties may be set on single option items as follows.
 *
 * @code
 * $form['high_school']['tests_taken']['SAT']['#description'] = $this->t('Description for the SAT option.');
 * @endcode
 *

Proposed resolution

The terms used in the example code should be changed.

Remaining tasks

- Decide on what to use for an example
- Make a MR with the changes.

Issue fork drupal-3265929

Show commands

Start within a Git clone of the project using the version control instructions.

Add & fetch this issue fork’s repository

Or, if you do not have SSH keys set up on git.drupalcode.org:

Add & fetch this issue fork’s repository

3265929-rewrite-examples-of changes, plain diff MR !2022
Check out this branch

About issue forks

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

22 February 2022 at 17:09

joachim created an issue. See original summary.

Comment #2

lauriii

he/him

Finnish

Finland

CreditAttribution: lauriii at Acquia commented 26 March 2022 at 17:10

Status:

Postponed

» Active

#2779999: Document checkboxes and radios element can have individual descriptions has been committed.

Comment #3

joachim CreditAttribution: joachim as a volunteer commented 26 March 2022 at 17:47

Issue summary:

View changes

Comment #4

joachim CreditAttribution: joachim as a volunteer commented 26 March 2022 at 17:48

Issue summary:

View changes

Let's start the bikeshed!

The obvious one seems to me to be 'What is your favourite colour?'

Comment #5

jonathanshaw

English

Stroud, UK

CreditAttribution: jonathanshaw commented 26 March 2022 at 21:48

How's this:

* Usage example:
 * @code
 * $form['favorites']['colors'] = array(
 *   '#type' => 'checkboxes',
 *   '#options' => array('blue' => $this->t('Blue'), 'red' => $this->t('Red')),
 *   '#title' => $this->t('Which colors do you like?'),
 *   ...
 * );
 * @endcode
 *
 * Element properties may be set on single option items as follows.
 *
 * @code
 * $form['favorites']['colors']['blue']['#description'] = $this->t('The color of the sky.');
 * @endcode

Comment #6

joachim CreditAttribution: joachim as a volunteer commented 26 March 2022 at 23:06

Looks good!

Comment #7

28 March 2022 at 12:24

jonathanshaw opened merge request !2022

Comment #8

jonathanshaw

English

Stroud, UK

CreditAttribution: jonathanshaw commented 28 March 2022 at 12:25

Status:

Active

» Needs review

Comment #9

28 March 2022 at 18:35

yogeshmpawar made their first commit to this issue’s fork.

Comment #10

joachim CreditAttribution: joachim as a volunteer commented 28 March 2022 at 20:34

Status:

Needs review

» Reviewed & tested by the community

LGTM!

Comment #11

6 April 2022 at 22:30

xjm credited quietone.

Comment #12

xjm

she/her

English

CreditAttribution: xjm at Acquia commented 6 April 2022 at 22:30

Adding credit for @quietone who brought this up with me originally.

Comment #13

6 April 2022 at 22:33

xjm committed 5d2d281 on 10.0.x

Issue #3265929 by jonathanshaw, yogeshmpawar, quietone, xjm: Rewrite...

Comment #14

6 April 2022 at 22:34

xjm committed 4e4d69c on 9.4.x

Issue #3265929 by jonathanshaw, yogeshmpawar, quietone, xjm: Rewrite...

Comment #15

6 April 2022 at 22:42

xjm committed 2f9239c on 9.3.x

Issue #3265929 by jonathanshaw, yogeshmpawar, quietone, xjm: Rewrite...

Comment #16

xjm

she/her

English

CreditAttribution: xjm at Acquia commented 6 April 2022 at 22:44

Version:	9.4.x-dev	» 9.3.x-dev
Status:	Reviewed & tested by the community	» Fixed
Issue tags:		+Needs followup

Tagging "Needs followup" for:

This also should be using short array syntax. ;) But that's out of scope for the issue as written, so someone can make a "Correct use of array() to [] in comments" issue to clean that up. (A CS rule already enforces it for code.)

Committed to 10.0.x and cherry-picked to 9.4.x. Thanks! I also backported it to 9.3.x as a patch-eligible documentation bugfix. (I had to backport #2779999: Document checkboxes and radios element can have individual descriptions first.)

Apologies to @joachim; I accidentally left off credit for your issue report in the commit message because I crossposted with myself when dealing with the backport blocker, but it's restored in the issue credit on the issue node here.