10000 Documented label_format option · symfony/symfony-docs@ac0fdbc · GitHub
[go: up one dir, main page]
Skip to content

Commit ac0fdbc

Browse files
wouterjwouterj
committed
Documented label_format option
1 parent 9fe5455 commit ac0fdbc

26 files changed

+120
-0
lines changed

‎components/translation/usage.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,8 @@ recommended format. These files are parsed by one of the loader classes.
139139
'symfony.great' => 'J\'aime Symfony',
140140
);
141141
142+
.. _translation-real-vs-keyword-messages:
143+
142144
.. sidebar:: Using Real or Keyword Messages
143145

144146
This example illustrates the two different philosophies when creating

‎reference/forms/types/checkbox.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ true, if the box is unchecked, the value will be set to false.
2222
| | - `error_mapping`_ |
2323
| | - `label`_ |
2424
| | - `label_attr`_ |
25+
| | - `label_format`_ |
2526
| | - `mapped`_ |
2627
| | - `read_only`_ |
2728
| | - `required`_ |
@@ -71,6 +72,8 @@ type:
7172

7273
.. include:: /reference/forms/types/options/label_attr.rst.inc
7374

75+
.. include:: /reference/forms/types/options/label_format.rst.inc
76+
7477
.. include:: /reference/forms/types/options/mapped.rst.inc
7578

7679
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/choice.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op
3737
| | - `inherit_data`_ |
3838
| | - `label`_ |
3939
| | - `label_attr`_ |
40+
| | - `label_format`_ |
4041
| | - `mapped`_ |
4142
| | - `read_only`_ |
4243
| | - `required`_ |
@@ -337,6 +338,8 @@ type:
337338

338339
.. include:: /reference/forms/types/options/label_attr.rst.inc
339340

341+
.. include:: /reference/forms/types/options/label_format.rst.inc
342+
340343
.. include:: /reference/forms/types/options/mapped.rst.inc
341344

342345
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/collection.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ photos).
2929
| | - `error_mapping`_ |
3030
| | - `label`_ |
3131
| | - `label_attr`_ |
32+
| | - `label_format`_ |
3233
| | - `mapped`_ |
3334
| | - `required`_ |
3435
+-------------+-----------------------------------------------------------------------------+
@@ -389,6 +390,8 @@ error_bubbling
389390

390391
.. include:: /reference/forms/types/options/label_attr.rst.inc
391392

393+
.. include:: /reference/forms/types/options/label_format.rst.inc
394+
392395
.. include:: /reference/forms/types/options/mapped.rst.inc
393396

394397
.. include:: /reference/forms/types/options/required.rst.inc

‎reference/forms/types/country.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ you should just use the ``choice`` type directly.
4141
| | - `empty_data`_ |
4242
| | - `label`_ |
4343
| | - `label_attr`_ |
44+
| | - `label_format`_ |
4445
| | - `mapped`_ |
4546
| | - `read_only`_ |
4647
| | - `required`_ |
@@ -102,6 +103,8 @@ The actual default value of this option depends on other field options:
102103

103104
.. include:: /reference/forms/types/options/label_attr.rst.inc
104105

106+
.. include:: /reference/forms/types/options/label_format.rst.inc
107+
105108
.. include:: /reference/forms/types/options/mapped.rst.inc
106109

107110
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/currency.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ you should just use the ``choice`` type directly.
3434
| | - `empty_data`_ |
3535
| | - `label`_ |
3636
| | - `label_attr`_ |
37+
| | - `label_format`_ |
3738
| | - `mapped`_ |
3839
| | - `read_only`_ |
3940
| | - `required`_ |
@@ -92,6 +93,8 @@ The actual default value of this option depends on other field options:
9293

9394
.. include:: /reference/forms/types/options/label_attr.rst.inc
9495

96+
.. include:: /reference/forms/types/options/label_format.rst.inc
97+
9598
.. include:: /reference/forms/types/options/mapped.rst.inc
9699

97100
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/email.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ The ``email`` field is a text field that is rendered using the HTML5
1717
| | - `error_mapping`_ |
1818
| | - `label`_ |
1919
| | - `label_attr`_ |
20+
| | - `label_format`_ |
2021
| | - `mapped`_ |
2122
| | - `max_length`_ (deprecated as of 2.5) |
2223
| | - `read_only`_ |
@@ -54,6 +55,8 @@ The default value is ``''`` (the empty string).
5455

5556
.. include:: /reference/forms/types/options/label_attr.rst.inc
5657

58+
.. include:: /reference/forms/types/options/label_format.rst.inc
59+
5760
.. include:: /reference/forms/types/options/mapped.rst.inc
5861

5962
.. include:: /reference/forms/types/options/max_length.rst.inc

‎reference/forms/types/entity.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ objects from the database.
3737
| | - `error_mapping`_ |
3838
| | - `label`_ |
3939
| | - `label_attr`_ |
40+
| | - `label_format`_ |
4041
| | - `mapped`_ |
4142
| | - `read_only`_ |
4243
| | - `required`_ |
@@ -243,6 +244,8 @@ The actual default value of this option depends on other field options:
243244

244245
.. include:: /reference/forms/types/options/label_attr.rst.inc
245246

247+
.. include:: /reference/forms/types/options/label_format.rst.inc
248+
246249
.. include:: /reference/forms/types/options/mapped.rst.inc
247250

248251
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/file.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ The ``file`` type represents a file input in your form.
2020
| | - `error_mapping`_ |
2121
| | - `label`_ |
2222
| | - `label_attr`_ |
23+
| | - `label_format`_ |
2324
| | - `mapped`_ |
2425
| | - `read_only`_ |
2526
| | - `required`_ |
@@ -125,6 +126,8 @@ type:
125126

126127
.. include:: /reference/forms/types/options/label_attr.rst.inc
127128

129+
.. include:: /reference/forms/types/options/label_format.rst.inc
130+
128131
.. include:: /reference/forms/types/options/mapped.rst.inc
129132

130133
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/form.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ on all types for which ``form`` is the parent type.
2424
| | - `invalid_message`_ |
2525
| | - `invalid_message_parameters`_ |
2626
| | - `label_attr`_ |
27+
| | - `label_format`_ |
2728
| | - `mapped`_ |
2829
| | - `max_length`_ (deprecated as of 2.5) |
2930
| | - `method`_ |
@@ -110,6 +111,8 @@ The actual default value of this option depends on other field options:
110111

111112
.. include:: /reference/forms/types/options/label_attr.rst.inc
112113

114+
.. include:: /reference/forms/types/options/label_format.rst.inc
115+
113116
.. _reference-form-option-mapped:
114117

115118
.. include:: /reference/forms/types/options/mapped.rst.inc

‎reference/forms/types/integer.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ integers. By default, all non-integer values (e.g. 6.78) will round down
3232
| | - `invalid_message_parameters`_ |
3333
| | - `label`_ |
3434
| | - `label_attr`_ |
35+
| | - `label_format`_ |
3536
| | - `mapped`_ |
3637
| | - `read_only`_ |
3738
| | - `required`_ |
@@ -112,6 +113,8 @@ The default value is ``''`` (the empty string).
112113

113114
.. include:: /reference/forms/types/options/label_attr.rst.inc
114115

116+
.. include:: /reference/forms/types/options/label_format.rst.inc
117+
115118
.. include:: /reference/forms/types/options/mapped.rst.inc
116119

117120
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/language.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ you should just use the ``choice`` type directly.
4242
| | - `empty_data`_ |
4343
| | - `label`_ |
4444
| | - `label_attr`_ |
45+
| | - `label_format`_ |
4546
| | - `mapped`_ |
4647
| | - `read_only`_ |
4748
| | - `required`_ |
@@ -103,6 +104,8 @@ The actual default value of this option depends on other field options:
103104

104105
.. include:: /reference/forms/types/options/label_attr.rst.inc
105106

107+
.. include:: /reference/forms/types/options/label_format.rst.inc
108+
106109
.. include:: /reference/forms/types/options/mapped.rst.inc
107110

108111
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/locale.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ you should just use the ``choice`` type directly.
4444
| | - `empty_data`_ |
4545
| | - `label`_ |
4646
| | - `label_attr`_ |
47+
| | - `label_format`_ |
4748
| | - `mapped`_ |
4849
| | - `read_only`_ |
4950
| | - `required`_ |
@@ -105,6 +106,8 @@ The actual default value of this option depends on other field options:
105106

106107
.. include:: /reference/forms/types/options/label_attr.rst.inc
107108

109+
.. include:: /reference/forms/types/options/label_format.rst.inc
110+
108111
.. include:: /reference/forms/types/options/mapped.rst.inc
109112

110113
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/money.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ how the input and output of the data is handled.
3131
| | - `invalid_message_parameters`_ |
3232
| | - `label`_ |
3333
| | - `label_attr`_ |
34+
| | - `label_format`_ |
3435
| | - `mapped`_ |
3536
| | - `read_only`_ |
3637
| | - `required`_ |
@@ -125,6 +126,8 @@ The default value is ``''`` (the empty string).
125126

126127
.. include:: /reference/forms/types/options/label_attr.rst.inc
127128

129+
.. include:: /reference/forms/types/options/label_format.rst.inc
130+
128131
.. include:: /reference/forms/types/options/mapped.rst.inc
129132

130133
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/number.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ that you want to use for your number.
2727
| | - `invalid_message_parameters`_ |
2828
| | - `label`_ |
2929
| | - `label_attr`_ |
30+
| | - `label_format`_ |
3031
| | - `mapped`_ |
3132
| | - `read_only`_ |
3233
| | - `required`_ |
@@ -107,6 +108,8 @@ The default value is ``''`` (the empty string).
107108

108109
.. include:: /reference/forms/types/options/label_attr.rst.inc
109110

111+
.. include:: /reference/forms/types/options/label_format.rst.inc
112+
110113
.. include:: /reference/forms/types/options/mapped.rst.inc
111114

112115
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/options/label_format.rst.inc

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
label_format
2+
~~~~~~~~~~~~
3+
4+
.. versionadded:: 2.6
5+
The ``label_format`` option was introduced in Symfony 2.6.
6+
7+
**type**: ``string`` **default**: ``null``
8+
9+
Configures the string used as the label of the field, in case the ``label``
10+
option was not set. This is useful when using
11+
:ref:`keyword translation messages <translation-real-vs-keyword-messages>`.
12+
13+
If you're using keyword translation messages as labels, you often end up having
14+
multiple keyword messages for the same label (e.g. ``profile_address_street``,
15+
``invoice_address_street``). This is because the label is build for each "path"
16+
to a field. To avoid duplicated keyword messages, you can configure the label
17+
format to a static value, like::
18+
19+
// ...
20+
$profileFormBuilder->add('address', new AddressType(), array(
21+
'label_format' => 'form.address.%name%',
22+
));
23+
24+
$invoiceFormBuilder->add('invoice', new AddressType(), array(
25+
'label_format' => 'form.address.%name%',
26+
));
27+
28+
This option is inherited by the child types. With the code above, the label of
29+
the ``street`` field of both forms will use the ``form.address.street`` keyword
30+
message.
31+
32+
Two variables are available in the label format:
33+
34+
``%id%``
35+
A unique identifier for the field, consisting of the complete path to the
36+
field and the field name (e.g. ``profile_address_street``);
37+
``%name%``
38+
The field name (e.g. ``street``).
39+
40+
The default value (``null``) results in a
41+
:ref:`"humanized" version <reference-twig-humanize-filter>` of the field name.
42+
43+
.. note::
44+
45+
The ``label_format`` option is evaluated in the form theme. Make sure to
46+
update your templates in case you
47+
:doc:`customized form theming </cookbook/form/form_customization>`.

‎reference/forms/types/password.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ The ``password`` field renders an input password text box.
2020
| | - `error_mapping`_ |
2121
| | - `label`_ |
2222
| | - `label_attr`_ |
23+
| | - `label_format`_ |
2324
| | - `mapped`_ |
2425
| | - `max_length`_ (deprecated as of 2.5) |
2526
| | - `read_only`_ |
@@ -83,6 +84,8 @@ The default value is ``''`` (the empty string).
8384

8485
.. include:: /reference/forms/types/options/label_attr.rst.inc
8586

87+
.. include:: /reference/forms/types/options/label_format.rst.inc
88+
8689
.. include:: /reference/forms/types/options/mapped.rst.inc
8790

8891
.. include:: /reference/forms/types/options/max_length.rst.inc

‎reference/forms/types/percent.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ This field adds a percentage sign "``%``" after the input box.
3030
| | - `invalid_message_parameters`_ |
3131
| | - `label`_ |
3232
| | - `label_attr`_ |
33+
| | - `label_format`_ |
3334
| | - `mapped`_ |
3435
| | - `read_only`_ |
3536
| | - `required`_ |
@@ -109,6 +110,8 @@ The default value is ``''`` (the empty string).
109110

110111
.. include:: /reference/forms/types/options/label_attr.rst.inc
111112

113+
.. include:: /reference/forms/types/options/label_format.rst.inc
114+
112115
.. include:: /reference/forms/types/options/mapped.rst.inc
113116

114117
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/radio.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ If you want to have a boolean field, use :doc:`checkbox </reference/forms/types/
2929
| | - `error_mapping`_ |
3030
| | - `label`_ |
3131
| | - `label_attr`_ |
32+
| | - `label_format`_ |
3233
| | - `mapped`_ |
3334
| | - `read_only`_ |
3435
| | - `required`_ |
@@ -63,6 +64,8 @@ type:
6364

6465
.. include:: /reference/forms/types/options/label_attr.rst.inc
6566

67+
.. include:: /reference/forms/types/options/label_format.rst.inc
68+
6669
.. include:: /reference/forms/types/options/mapped.rst.inc
6770

6871
.. include:: /reference/forms/types/options/read_only.rst.inc

‎reference/forms/types/search.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Read about the input search field at `DiveIntoHTML5.info`_
1818
| | - `error_mapping`_ |
1919
| | - `label`_ |
2020
| | - `label_attr`_ |
21+
| | - `label_format`_ |
2122
| | - `mapped`_ |
2223
| | - `max_length`_ (deprecated as of 2.5) |
2324
| | - `read_only`_ |
@@ -53,6 +54,8 @@ The default value is ``''`` (the empty string).
5354

5455
.. include:: /reference/forms/types/options/label_attr.rst.inc
5556

57+
.. include:: /reference/forms/types/options/label_format.rst.inc
58+
5659
.. include:: /reference/forms/types/options/mapped.rst.inc
5760

5861
.. include:: /reference/forms/types/options/max_length.rst.inc

0 commit comments

Comments
 (0)
0