Skip to content

Commit

Permalink
feature #5642 Documented label_format option (WouterJ)
Browse files Browse the repository at this point in the history 
This PR was merged into the 2.7 branch.

Discussion
----------

Documented label_format option

| Q   | A
| --- | ---
| Doc fix? | no
| New docs? | yes (symfony/symfony#12050)
| Applies to | 2.6+
| Fixed tickets | #4286

@javiereguiluz abandoned #4412, so I continued #4489. I welcome any improvements, as I'm not 100% sure this is well documented now.

Commits
-------

ac0fdbc Documented label_format option
  • Loading branch information
@wouterj
wouterj committed Feb 6, 2016
2 parents 129d853 + ac0fdbc commit a31dcc0
Show file tree
Hide file tree
Showing 26 changed files with 120 additions and 0 deletions.
2 changes: 2 additions & 0 deletions components/translation/usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,8 @@ recommended format. These files are parsed by one of the loader classes.
'symfony.great' => 'J\'aime Symfony',
);
.. _translation-real-vs-keyword-messages:

.. sidebar:: Using Real or Keyword Messages

This example illustrates the two different philosophies when creating
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/checkbox.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ true, if the box is unchecked, the value will be set to false.
| | - `error_mapping`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -71,6 +72,8 @@ type:

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/choice.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op
| | - `inherit_data`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -339,6 +340,8 @@ type:

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/collection.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ photos).
| | - `error_mapping`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `required`_ |
+-------------+-----------------------------------------------------------------------------+
Expand Down Expand Up @@ -389,6 +390,8 @@ error_bubbling

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/required.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/country.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ you should just use the ``choice`` type directly.
| | - `empty_data`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -102,6 +103,8 @@ The actual default value of this option depends on other field options:

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/currency.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ you should just use the ``choice`` type directly.
| | - `empty_data`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -92,6 +93,8 @@ The actual default value of this option depends on other field options:

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/email.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ The ``email`` field is a text field that is rendered using the HTML5
| | - `error_mapping`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `max_length`_ (deprecated as of 2.5) |
| | - `read_only`_ |
Expand Down Expand Up @@ -54,6 +55,8 @@ The default value is ``''`` (the empty string).

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/max_length.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/entity.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ objects from the database.
| | - `error_mapping`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -246,6 +247,8 @@ The actual default value of this option depends on other field options:

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/file.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ The ``file`` type represents a file input in your form.
| | - `error_mapping`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -125,6 +126,8 @@ type:

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/form.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ on all types for which ``form`` is the parent type.
| | - `invalid_message`_ |
| | - `invalid_message_parameters`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `max_length`_ (deprecated as of 2.5) |
| | - `method`_ |
Expand Down Expand Up @@ -110,6 +111,8 @@ The actual default value of this option depends on other field options:

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

.. include:: /reference/forms/types/options/label_format.rst.inc

.. _reference-form-option-mapped:

.. include:: /reference/forms/types/options/mapped.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/integer.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ integers. By default, all non-integer values (e.g. 6.78) will round down
| | - `invalid_message_parameters`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -112,6 +113,8 @@ The default value is ``''`` (the empty string).

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/language.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ you should just use the ``choice`` type directly.
| | - `empty_data`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -103,6 +104,8 @@ The actual default value of this option depends on other field options:

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/locale.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ you should just use the ``choice`` type directly.
| | - `empty_data`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -105,6 +106,8 @@ The actual default value of this option depends on other field options:

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/money.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ how the input and output of the data is handled.
| | - `invalid_message_parameters`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -125,6 +126,8 @@ The default value is ``''`` (the empty string).

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/number.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ that you want to use for your number.
| | - `invalid_message_parameters`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -107,6 +108,8 @@ The default value is ``''`` (the empty string).

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
47 changes: 47 additions & 0 deletions reference/forms/types/options/label_format.rst.inc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
label_format
~~~~~~~~~~~~

.. versionadded:: 2.6
The ``label_format`` option was introduced in Symfony 2.6.

**type**: ``string`` **default**: ``null``

Configures the string used as the label of the field, in case the ``label``
option was not set. This is useful when using
:ref:`keyword translation messages <translation-real-vs-keyword-messages>`.

If you're using keyword translation messages as labels, you often end up having
multiple keyword messages for the same label (e.g. ``profile_address_street``,
``invoice_address_street``). This is because the label is build for each "path"
to a field. To avoid duplicated keyword messages, you can configure the label
format to a static value, like::
// ...
$profileFormBuilder->add('address', new AddressType(), array(
'label_format' => 'form.address.%name%',
));
$invoiceFormBuilder->add('invoice', new AddressType(), array(
'label_format' => 'form.address.%name%',
));
This option is inherited by the child types. With the code above, the label of
the ``street`` field of both forms will use the ``form.address.street`` keyword
message.
Two variables are available in the label format:
``%id%``
A unique identifier for the field, consisting of the complete path to the
field and the field name (e.g. ``profile_address_street``);
``%name%``
The field name (e.g. ``street``).
The default value (``null``) results in a
:ref:`"humanized" version <reference-twig-humanize-filter>` of the field name.
.. note::
The ``label_format`` option is evaluated in the form theme. Make sure to
update your templates in case you
:doc:`customized form theming </cookbook/form/form_customization>`.
3 changes: 3 additions & 0 deletions reference/forms/types/password.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ The ``password`` field renders an input password text box.
| | - `error_mapping`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `max_length`_ (deprecated as of 2.5) |
| | - `read_only`_ |
Expand Down Expand Up @@ -83,6 +84,8 @@ The default value is ``''`` (the empty string).

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/max_length.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/percent.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ This field adds a percentage sign "``%``" after the input box.
| | - `invalid_message_parameters`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -109,6 +110,8 @@ The default value is ``''`` (the empty string).

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/radio.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ If you want to have a boolean field, use :doc:`checkbox </reference/forms/types/
| | - `error_mapping`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `read_only`_ |
| | - `required`_ |
Expand Down Expand Up @@ -63,6 +64,8 @@ type:

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/read_only.rst.inc
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/search.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Read about the input search field at `DiveIntoHTML5.info`_
| | - `error_mapping`_ |
| | - `label`_ |
| | - `label_attr`_ |
| | - `label_format`_ |
| | - `mapped`_ |
| | - `max_length`_ (deprecated as of 2.5) |
| | - `read_only`_ |
Expand Down Expand Up @@ -53,6 +54,8 @@ The default value is ``''`` (the empty string).

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

.. include:: /reference/forms/types/options/label_format.rst.inc

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

.. include:: /reference/forms/types/options/max_length.rst.inc
Expand Down
Loading

0 comments on commit a31dcc0

Please sign in to comment.