Skip to content

Commit 94c28d2

Browse files
wouterjwouterj
committed
Documented label_format option
1 parent ad4c1f0 commit 94c28d2

26 files changed

+112
-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 @@ 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`_ |
@@ -70,6 +71,8 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
7071

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

74+
.. include:: /reference/forms/types/options/label_format.rst.inc
75+
7376
.. include:: /reference/forms/types/options/mapped.rst.inc
7477

7578
.. 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
@@ -31,6 +31,7 @@ option.
3131
| | - `inherit_data`_ |
3232
| | - `label`_ |
3333
| | - `label_attr`_ |
34+
| | - `label_format`_ |
3435
| | - `mapped`_ |
3536
| | - `read_only`_ |
3637
| | - `required`_ |
@@ -180,6 +181,8 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
180181

181182
.. include:: /reference/forms/types/options/label_attr.rst.inc
182183

184+
.. include:: /reference/forms/types/options/label_format.rst.inc
185+
183186
.. include:: /reference/forms/types/options/mapped.rst.inc
184187

185188
.. 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
@@ -28,6 +28,7 @@ forms, which is useful when creating forms that expose one-to-many relationships
2828
| | - `error_mapping`_ |
2929
| | - `label`_ |
3030
| | - `label_attr`_ |
31+
| | - `label_format`_ |
3132
| | - `mapped`_ |
3233
| | - `required`_ |
3334
+-------------+-----------------------------------------------------------------------------+
@@ -383,6 +384,8 @@ error_bubbling
383384

384385
.. include:: /reference/forms/types/options/label_attr.rst.inc
385386

387+
.. include:: /reference/forms/types/options/label_format.rst.inc
388+
386389
.. include:: /reference/forms/types/options/mapped.rst.inc
387390

388391
.. 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`_ |
@@ -100,6 +101,8 @@ The actual default value of this option depends on other field options:
100101

101102
.. include:: /reference/forms/types/options/label_attr.rst.inc
102103

104+
.. include:: /reference/forms/types/options/label_format.rst.inc
105+
103106
.. include:: /reference/forms/types/options/mapped.rst.inc
104107

105108
.. 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 @@ 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`_ |
@@ -90,6 +91,8 @@ The actual default value of this option depends on other field options:
9091

9192
.. include:: /reference/forms/types/options/label_attr.rst.inc
9293

94+
.. include:: /reference/forms/types/options/label_format.rst.inc
95+
9396
.. include:: /reference/forms/types/options/mapped.rst.inc
9497

9598
.. 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`_ |
@@ -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

‎reference/forms/types/entity.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ objects from the database.
3838
| | - `error_mapping`_ |
3939
| | - `label`_ |
4040
| | - `label_attr`_ |
41+
| | - `label_format`_ |
4142
| | - `mapped`_ |
4243
| | - `read_only`_ |
4344
| | - `required`_ |
@@ -240,6 +241,8 @@ The actual default value of this option depends on other field options:
240241

241242
.. include:: /reference/forms/types/options/label_attr.rst.inc
242243

244+
.. include:: /reference/forms/types/options/label_format.rst.inc
245+
243246
.. include:: /reference/forms/types/options/mapped.rst.inc
244247

245248
.. 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
@@ -17,6 +17,7 @@ The ``file`` type represents a file input in your form.
1717
| | - `error_mapping`_ |
1818
| | - `label`_ |
1919
| | - `label_attr`_ |
20+
| | - `label_format`_ |
2021
| | - `mapped`_ |
2122
| | - `read_only`_ |
2223
| | - `required`_ |
@@ -116,6 +117,8 @@ The default value is ``null``.
116117

117118
.. include:: /reference/forms/types/options/label_attr.rst.inc
118119

120+
.. include:: /reference/forms/types/options/label_format.rst.inc
121+
119122
.. include:: /reference/forms/types/options/mapped.rst.inc
120123

121124
.. 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
@@ -23,6 +23,7 @@ on all types for which ``form`` is the parent type.
2323
| | - `invalid_message`_ |
2424
| | - `invalid_message_parameters`_ |
2525
| | - `label_attr`_ |
26+
| | - `label_format`_ |
2627
| | - `mapped`_ |
2728
| | - `max_length`_ (deprecated as of 2.5) |
2829
| | - `method`_ |
@@ -94,6 +95,8 @@ The actual default value of this option depends on other field options:
9495

9596
.. include:: /reference/forms/types/options/label_attr.rst.inc
9697

98+
.. include:: /reference/forms/types/options/label_format.rst.inc
99+
97100
.. include:: /reference/forms/types/options/mapped.rst.inc
98101

99102
.. _reference-form-option-max_length:

‎reference/forms/types/integer.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ integers. By default, all non-integer values (e.g. 6.78) will round down (e.g. 6
2828
| | - `invalid_message_parameters`_ |
2929
| | - `label`_ |
3030
| | - `label_attr`_ |
31+
| | - `label_format`_ |
3132
| | - `mapped`_ |
3233
| | - `read_only`_ |
3334
| | - `required`_ |
@@ -102,6 +103,8 @@ The default value is ``''`` (the empty string).
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/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`_ |
@@ -101,6 +102,8 @@ The actual default value of this option depends on other field options:
101102

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

105+
.. include:: /reference/forms/types/options/label_format.rst.inc
106+
104107
.. include:: /reference/forms/types/options/mapped.rst.inc
105108

106109
.. 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`_ |
@@ -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/money.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ how the input and output of the data is handled.
2828
| | - `invalid_message_parameters`_ |
2929
| | - `label`_ |
3030
| | - `label_attr`_ |
31+
| | - `label_format`_ |
3132
| | - `mapped`_ |
3233
| | - `read_only`_ |
3334
| | - `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/number.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ you want to use for your number.
2424
| | - `invalid_message_parameters`_ |
2525
| | - `label`_ |
2626
| | - `label_attr`_ |
27+
| | - `label_format`_ |
2728
| | - `mapped`_ |
2829
| | - `read_only`_ |
2930
| | - `required`_ |
@@ -98,6 +99,8 @@ The default value is ``''`` (the empty string).
9899

99100
.. include:: /reference/forms/types/options/label_attr.rst.inc
100101

102+
.. include:: /reference/forms/types/options/label_format.rst.inc
103+
101104
.. include:: /reference/forms/types/options/mapped.rst.inc
102105

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

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
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 label of the field. This is useful when using
10+
:ref:`keyword translation messages <translation-real-vs-keyword-messages>`.
11+
12+
When using keyword translation messages as labels, you often end up having
13+
several keyword messages translating to the same label (e.g.
14+
``profile_address_street`` and ``invoice_address_street``). To avoid this,
15+
you can use the label format::
16+
17+
// ...
18+
$profileFormBuilder->add('address', new AddressType(), array(
19+
'label_format' => 'form.address.%name%',
20+
));
21+
22+
$invoiceFormBuilder->add('invoice', new AddressType(), array(
23+
'label_format' => 'form.address.%name%',
24+
));
25+
26+
The option is inherited to the child types. With the code above, the ``street``
27+
field of both forms will use the ``form.address.street`` keyword message as the
28+
label.
29+
30+
Two variables are available in the label format:
31+
32+
``%id%``
33+
A unique identifier for the field, consisting of the complete path to the
34+
field and the field name (e.g. ``profile_address_street``);
35+
``%name%``
36+
The field name (e.g. ``street``).
37+
38+
The default value (``null``) results in a
39+
:ref:`"humanized" version <reference-twig-humanize-filter>` of the field name.

‎reference/forms/types/password.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ The ``password`` field renders an input password text box.
1717
| | - `error_mapping`_ |
1818
| | - `label`_ |
1919
| | - `label_attr`_ |
20+
| | - `label_format`_ |
2021
| | - `mapped`_ |
2122
| | - `max_length`_ (deprecated as of 2.5) |
2223
| | - `read_only`_ |
@@ -68,6 +69,8 @@ The default value is ``''`` (the empty string).
6869

6970
.. include:: /reference/forms/types/options/label_attr.rst.inc
7071

72+
.. include:: /reference/forms/types/options/label_format.rst.inc
73+
7174
.. include:: /reference/forms/types/options/mapped.rst.inc
7275

7376
.. 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
@@ -27,6 +27,7 @@ This field adds a percentage sign "``%``" after the input box.
2727
| | - `invalid_message_parameters`_ |
2828
| | - `label`_ |
2929
| | - `label_attr`_ |
30+
| | - `label_format`_ |
3031
| | - `mapped`_ |
3132
| | - `read_only`_ |
3233
| | - `required`_ |
@@ -95,6 +96,8 @@ The default value is ``''`` (the empty string).
9596

9697
.. include:: /reference/forms/types/options/label_attr.rst.inc
9798

99+
.. include:: /reference/forms/types/options/label_format.rst.inc
100+
98101
.. include:: /reference/forms/types/options/mapped.rst.inc
99102

100103
.. 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
@@ -28,6 +28,7 @@ If you want to have a Boolean field, use :doc:`checkbox </reference/forms/types/
2828
| | - `error_mapping`_ |
2929
| | - `label`_ |
3030
| | - `label_attr`_ |
31+
| | - `label_format`_ |
3132
| | - `mapped`_ |
3233
| | - `read_only`_ |
3334
| | - `required`_ |
@@ -61,6 +62,8 @@ These options inherit from the :doc:`form </reference/forms/types/form>` type:
6162

6263
.. include:: /reference/forms/types/options/label_attr.rst.inc
6364

65+
.. include:: /reference/forms/types/options/label_format.rst.inc
66+
6467
.. include:: /reference/forms/types/options/mapped.rst.inc
6568

6669
.. 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`_ |
@@ -52,6 +53,8 @@ The default value is ``''`` (the empty string).
5253

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

56+
.. include:: /reference/forms/types/options/label_format.rst.inc
57+
5558
.. include:: /reference/forms/types/options/mapped.rst.inc
5659

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

0 commit comments

Comments
 (0)