Skip to content

Commit d0f189b

Browse files
ADmadADmad
authored
Merge pull request #8365 from cakephp/docs/6x-form-checkbox-radio-markup
Document checkbox and radio markup changes in 6.0
2 parents 49518c1 + 000bf3f commit d0f189b

2 files changed

Lines changed: 73 additions & 80 deletions

File tree

‎docs/en/appendices/6-0-migration-guide.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,17 @@ Some properties have also been renamed to better reflect their purpose. These ar
165165
`'item'`/`itemWithoutLink` breadcrumb templates.
166166
- `multicheckboxTitle` template of FormHelper is now `multicheckboxLabel`.
167167

168+
- `FormHelper` now defaults `nestedCheckboxAndRadio` to `false`, placing
169+
checkbox and radio inputs before their labels. Set it to `true` to retain
170+
nesting, or use `nestedInput` on individual controls. Review CSS selectors
171+
that depend on the old markup.
172+
- The default `radioWrapper` template is now
173+
`<div class="radio">{{input}}{{label}}</div>`. Custom wrappers must include
174+
`{{input}}` as well as `{{label}}` when inputs are not nested.
175+
- Multicheckbox option labels cannot be disabled. Use an array for label
176+
attributes when calling `multiCheckbox()`; direct `MultiCheckboxWidget`
177+
callers must also pass an array for `label`.
178+
168179
## New Features
169180

170181
### Event

‎docs/en/views/helpers/form.md‎

Lines changed: 62 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -691,20 +691,15 @@ as well as HTML attributes. This subsection will cover the options specific to
691691
]);
692692
```
693693

694-
- `$options['nestedInput']` - Used with checkboxes and radio buttons.
695-
Controls whether the input element is generated
696-
inside or outside the `label` element. When `control()` generates a
697-
checkbox or a radio button, you can set this to `false` to force the
698-
generation of the HTML `input` element outside of the `label` element.
694+
- `$options['nestedInput']` - Controls whether the input is generated inside
695+
the `label` element. Checkbox and radio inputs are outside their labels by
696+
default. Set this to `true` to nest an input inside its label for a single
697+
control, or set the `nestedCheckboxAndRadio` FormHelper configuration option
698+
to `true` to enable nesting for all checkbox and radio controls.
699699

700-
On the other hand you can set this to `true` for any control type to force the
701-
generated input element inside the label. If you change this for radio buttons
702-
then you might want to also modify the default [radioWrapper](#create-radio-button)
703-
template to add a wrapping `div`. Depending on the generated control type it
704-
defaults to `true` or `false`.
705-
706-
If you want to disable the nesting of checkbox and radio inputs globally you can
707-
set `nestedCheckboxAndRadio` option of `FormHelper` to `false`.
700+
Each radio option is wrapped in `<div class="radio">` by the default
701+
`radioWrapper` template. If you customize that template, include both
702+
`{{input}}` and `{{label}}` so non-nested inputs are rendered.
708703

709704
- `$options['templates']` - The templates you want to use for this input. Any
710705
specified templates will be merged on top of the already loaded templates.
@@ -1052,35 +1047,23 @@ methods are described in each method's own section.)
10521047
```html
10531048
<h2>Primary Colors</h2>
10541049
<input type="hidden" name="color" value="0">
1055-
<label for="color-red">
1056-
<input type="checkbox" name="color[]" value="5" id="color-red">
1057-
Red
1058-
</label>
1050+
<input type="checkbox" name="color[]" value="5" id="color-red">
1051+
<label for="color-red">Red</label>
10591052

1060-
<label for="color-blue">
1061-
<input type="checkbox" name="color[]" value="5" id="color-blue">
1062-
Blue
1063-
</label>
1053+
<input type="checkbox" name="color[]" value="5" id="color-blue">
1054+
<label for="color-blue">Blue</label>
10641055

1065-
<label for="color-yellow">
1066-
<input type="checkbox" name="color[]" value="5" id="color-yellow">
1067-
Yellow
1068-
</label>
1056+
<input type="checkbox" name="color[]" value="5" id="color-yellow">
1057+
<label for="color-yellow">Yellow</label>
10691058

10701059
<h2>Tertiary Colors</h2>
10711060
<input type="hidden" name="color" value="0">
1072-
<label for="color-green">
1073-
<input type="checkbox" name="color[]" value="5" id="color-green">
1074-
Green
1075-
</label>
1076-
<label for="color-purple">
1077-
<input type="checkbox" name="color[]" value="5" id="color-purple">
1078-
Purple
1079-
</label>
1080-
<label for="color-orange">
1081-
<input type="checkbox" name="color[]" value="5" id="color-orange">
1082-
Orange
1083-
</label>
1061+
<input type="checkbox" name="color[]" value="5" id="color-green">
1062+
<label for="color-green">Green</label>
1063+
<input type="checkbox" name="color[]" value="5" id="color-purple">
1064+
<label for="color-purple">Purple</label>
1065+
<input type="checkbox" name="color[]" value="5" id="color-orange">
1066+
<label for="color-orange">Orange</label>
10841067
```
10851068

10861069
Disabling `'hiddenField'` on the second control group would
@@ -1210,7 +1193,7 @@ Creates a set of radio button inputs. The default widget templates used are:
12101193

12111194
```html
12121195
'radio' => '<input type="radio" name="{{name}}" value="{{value}}"{{attrs}}>'
1213-
'radioWrapper' => '{{label}}'
1196+
'radioWrapper' => '<div class="radio">{{input}}{{label}}</div>'
12141197
```
12151198

12161199
**Attributes for Radio Buttons**
@@ -1238,18 +1221,18 @@ Will output:
12381221

12391222
```html
12401223
<input name="gender" value="" type="hidden">
1241-
<label for="gender-0">
1224+
<div class="radio">
12421225
<input name="gender" value="0" id="gender-0" type="radio">
1243-
Masculine
1244-
</label>
1245-
<label for="gender-1">
1226+
<label for="gender-0">Masculine</label>
1227+
</div>
1228+
<div class="radio">
12461229
<input name="gender" value="1" id="gender-1" type="radio">
1247-
Feminine
1248-
</label>
1249-
<label for="gender-2">
1230+
<label for="gender-1">Feminine</label>
1231+
</div>
1232+
<div class="radio">
12501233
<input name="gender" value="2" id="gender-2" type="radio">
1251-
Neuter
1252-
</label>
1234+
<label for="gender-2">Neuter</label>
1235+
</div>
12531236
```
12541237

12551238
Generally `$options` contains simple `key => value` pairs. However, if you
@@ -1273,18 +1256,18 @@ Will output:
12731256

12741257
```html
12751258
<input type="hidden" name="favorite_color" value="">
1276-
<label for="favorite-color-r">
1259+
<div class="radio">
12771260
<input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite-color-r">
1278-
Red
1279-
</label>
1280-
<label for="favorite-color-u">
1261+
<label for="favorite-color-r">Red</label>
1262+
</div>
1263+
<div class="radio">
12811264
<input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite-color-u">
1282-
Blue
1283-
</label>
1284-
<label for="favorite-color-g">
1265+
<label for="favorite-color-u">Blue</label>
1266+
</div>
1267+
<div class="radio">
12851268
<input type="radio" name="favorite_color" value="g" style="color:green;" id="favorite-color-g">
1286-
Green
1287-
</label>
1269+
<label for="favorite-color-g">Green</label>
1270+
</div>
12881271
```
12891272

12901273
You can define additional attributes for an individual option's label as well:
@@ -1303,14 +1286,14 @@ Will output:
13031286

13041287
```html
13051288
<input type="hidden" name="favorite_color" value="">
1306-
<label for="favorite-color-r" class="red">
1307-
<input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite-color-r">
1308-
Red
1309-
</label>
1310-
<label for="favorite-color-u" class="blue">
1311-
<input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite-color-u">
1312-
Blue
1313-
</label>
1289+
<div class="radio">
1290+
<input type="radio" name="favorite_color" value="r" id="favorite-color-r">
1291+
<label for="favorite-color-r" class="red">Red</label>
1292+
</div>
1293+
<div class="radio">
1294+
<input type="radio" name="favorite_color" value="u" id="favorite-color-u">
1295+
<label for="favorite-color-u" class="blue">Blue</label>
1296+
</div>
13141297
```
13151298

13161299
If the `label` key is used on an option, the attributes in
@@ -1546,16 +1529,12 @@ certain behaviors of the `select()` method.
15461529
```html
15471530
<input name="field" value="" type="hidden">
15481531
<div class="checkbox">
1549-
<label for="field-1">
1550-
<input name="field[]" value="Value 1" id="field-1" type="checkbox">
1551-
Label 1
1552-
</label>
1532+
<input name="field[]" value="Value 1" id="field-1" type="checkbox">
1533+
<label for="field-1">Label 1</label>
15531534
</div>
15541535
<div class="checkbox">
1555-
<label for="field-2">
1556-
<input name="field[]" value="Value 2" id="field-2" type="checkbox">
1557-
Label 2
1558-
</label>
1536+
<input name="field[]" value="Value 2" id="field-2" type="checkbox">
1537+
<label for="field-2">Label 2</label>
15591538
</div>
15601539
```
15611540

@@ -1605,19 +1584,22 @@ certain behaviors of the `select()` method.
16051584
```html
16061585
<input name="field" value="" type="hidden">
16071586
<div class="checkbox">
1608-
<label for="field-1">
1609-
<input name="field[]" disabled="disabled" value="Value 1" type="checkbox">
1610-
Label 1
1611-
</label>
1587+
<input name="field[]" disabled="disabled" value="Value 1" type="checkbox">
1588+
<label for="field-1">Label 1</label>
16121589
</div>
16131590
<div class="checkbox">
1614-
<label for="field-2">
1615-
<input name="field[]" value="Value 2" id="field-2" type="checkbox">
1616-
Label 2
1617-
</label>
1591+
<input name="field[]" value="Value 2" id="field-2" type="checkbox">
1592+
<label for="field-2">Label 2</label>
16181593
</div>
16191594
```
16201595

1596+
When using `multiCheckbox()` or `select()` with `'multiple' => 'checkbox'`,
1597+
each option keeps its label. The `label` option accepts an array of label
1598+
attributes; passing `false` does not remove those option labels. The underlying
1599+
`MultiCheckboxWidget` requires an array and rejects other values. This differs
1600+
from `control(..., ['label' => false])`, which suppresses the group's label or
1601+
legend rather than the individual option labels.
1602+
16211603
### Creating File Inputs
16221604

16231605
`method` Cake\\View\\Helper\\FormHelper::**file**(string $fieldName, array $options): string

0 commit comments

Comments
 (0)