diff --git a/reference/forms/types/button.rst b/reference/forms/types/button.rst index 8ecd99a8a7a..4d0459b489c 100644 --- a/reference/forms/types/button.rst +++ b/reference/forms/types/button.rst @@ -13,6 +13,8 @@ A simple, non-responsive button. | options | - `disabled`_ | | | - `label`_ | | | - `translation_domain`_ | +| | - `label_translation_parameters`_ | +| | - `attr_translation_parameters`_ | +----------------------+----------------------------------------------------------------------+ | Parent type | none | +----------------------+----------------------------------------------------------------------+ @@ -51,3 +53,83 @@ as a key. This can be useful when you need to set a custom class for the button: .. include:: /reference/forms/types/options/button_label.rst.inc .. include:: /reference/forms/types/options/button_translation_domain.rst.inc + +label_translation_parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``[]`` + +Translated `label`_ can contain +:ref:`placeholders `. +This option allows you to pass an array of parameters in order to replace +placeholders with actual values. + +Given this translation message: + +.. code-block:: yaml + + # translations/messages.en.yml + form.order.submit_to_company: Send an order to %company% + +you can specify placeholder value: + +.. code-block:: php + + use Symfony\Component\Form\Extension\Core\Type\ButtonType; + // ... + + $builder->add('send', ButtonType::class, array( + 'label' => 'form.order.submit_to_company', + 'label_translation_parameters' => array( + '%company%' => 'ACME Inc.', + ), + )); + +Note that ``label_translation_parameters`` of buttons are merged with those of its +parent. In other words the parent's translation parameters are available for +children's buttons but can be overriden: + +.. code-block:: php + + // App/Controller/OrderController.php + use App\Form\OrderType; + // ... + + $form = $this->createForm(OrderType::class, $order, array( + // available to all children, grandchildren and so on. + 'label_translation_parameters' => array( + '%company%' => 'ACME', + ), + )); + +.. code-block:: php + + // App/Form/OrderType.php + use Symfony\Component\Form\Extension\Core\Type\ButtonType; + // ... + + $builder->add('send', ButtonType::class, array( + 'label' => 'form.order.submit_to_company', + // Value of parent's 'label_translation_parameters' will be merged with + // this field's empty 'label_translation_parameters'. + // array('%company%' => 'ACME') will be used to translate this label. + )); + +.. code-block:: php + + // App/Form/OrderType.php + use Symfony\Component\Form\Extension\Core\Type\ButtonType; + // ... + + $builder->add('send', ButtonType::class, array( + 'label' => 'form.order.submit_to_company', + 'label_translation_parameters' => array( + '%company%' => 'American Company Making Everything', + ), + // Value of parent's 'label_translation_parameters' will be merged with + // this button's 'label_translation_parameters'. + // array('%company%' => 'American Company Making Everything') + // will be used to translate this label. + )); + +.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst index 13f0c0bdcdb..8ef9984c8ca 100644 --- a/reference/forms/types/choice.rst +++ b/reference/forms/types/choice.rst @@ -45,6 +45,9 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op | | - `mapped`_ | | | - `required`_ | | | - `translation_domain`_ | +| | - `label_translation_parameters`_ | +| | - `attr_translation_parameters`_ | +| | - `help_translation_parameters`_ | +-------------+------------------------------------------------------------------------------+ | Parent type | :doc:`FormType ` | +-------------+------------------------------------------------------------------------------+ @@ -297,6 +300,12 @@ These options inherit from the :doc:`FormType `: .. include:: /reference/forms/types/options/choice_type_translation_domain.rst.inc +.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc + +.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc + +.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc + Field Variables --------------- diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst index 034e1cafb84..af1e934dd61 100644 --- a/reference/forms/types/entity.rst +++ b/reference/forms/types/entity.rst @@ -36,6 +36,7 @@ objects from the database. | | | | | from the :doc:`FormType `: | | | | +| | - `attr`_ | | | - `data`_ | | | - `disabled`_ | | | - `empty_data`_ | @@ -49,6 +50,9 @@ objects from the database. | | - `label_format`_ | | | - `mapped`_ | | | - `required`_ | +| | - `label_translation_parameters`_ | +| | - `attr_translation_parameters`_ | +| | - `help_translation_parameters`_ | +-------------+------------------------------------------------------------------+ | Parent type | :doc:`ChoiceType ` | +-------------+------------------------------------------------------------------+ @@ -312,6 +316,8 @@ when rendering the field: These options inherit from the :doc:`form ` type: +.. include:: /reference/forms/types/options/attr.rst.inc + .. include:: /reference/forms/types/options/data.rst.inc .. include:: /reference/forms/types/options/disabled.rst.inc @@ -347,3 +353,9 @@ The actual default value of this option depends on other field options: .. include:: /reference/forms/types/options/mapped.rst.inc .. include:: /reference/forms/types/options/required.rst.inc + +.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc + +.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc + +.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst index d31f75126ec..9d38ab840cc 100644 --- a/reference/forms/types/form.rst +++ b/reference/forms/types/form.rst @@ -22,6 +22,7 @@ on all types for which ``FormType`` is the parent. | | - `help`_ | | | - `help_attr`_ | | | - `help_html`_ | +| | - `help_translation_parameters`_ | | | - `inherit_data`_ | | | - `invalid_message`_ | | | - `invalid_message_parameters`_ | @@ -42,6 +43,8 @@ on all types for which ``FormType`` is the parent. | | - `disabled`_ | | | - `label`_ | | | - `translation_domain`_ | +| | - `label_translation_parameters`_ | +| | - `attr_translation_parameters`_ | +-----------+--------------------------------------------------------------------+ | Parent | none | +-----------+--------------------------------------------------------------------+ @@ -113,6 +116,8 @@ The actual default value of this option depends on other field options: .. include:: /reference/forms/types/options/help_html.rst.inc +.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc + .. include:: /reference/forms/types/options/inherit_data.rst.inc .. include:: /reference/forms/types/options/invalid_message.rst.inc @@ -167,3 +172,7 @@ of the form type tree (i.e. it cannot be used as a form type on its own). .. include:: /reference/forms/types/options/label.rst.inc .. include:: /reference/forms/types/options/translation_domain.rst.inc + +.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc + +.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc diff --git a/reference/forms/types/options/attr_translation_parameters.rst.inc b/reference/forms/types/options/attr_translation_parameters.rst.inc new file mode 100644 index 00000000000..f23aee36ee2 --- /dev/null +++ b/reference/forms/types/options/attr_translation_parameters.rst.inc @@ -0,0 +1,82 @@ +attr_translation_parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``[]`` + +Some translated `attr`_ (``title`` and ``placeholder``) can +contain :ref:`placeholders `. +This option allows you to pass an array of parameters in order to replace +placeholders with actual values. + +Given this translation message: + +.. code-block:: yaml + + # translations/messages.en.yml + form.order.id.placeholder: Enter unique identifier of the order to %company% + form.order.id.title: This will be the reference in communications with %company% + +you can specify placeholder value: + +.. code-block:: php + + $builder->add('id', null, array( + 'attr' => array( + 'placeholder' => 'form.order.id.placeholder', + 'title' => 'form.order.id.title', + ), + 'attr_translation_parameters' => [ + '%company%' => 'ACME Inc.' + ] + )); + +Note that ``attr_translation_parameters`` of children fields are merged with those +of its parent. In other words the parent's translation parameters are available +for children but can be overriden: + +.. code-block:: php + + // App/Controller/OrderController.php + use App\Form\OrderType; + // ... + + $form = $this->createForm(OrderType::class, $order, array( + // available to all children, grandchildren and so on. + 'attr_translation_parameters' => array( + '%company%' => 'ACME', + ), + )); + + .. code-block:: php + + // App/Form/OrderType.php + // ... + + $builder->add('id', null, array( + 'attr' => array( + 'placeholder' => 'form.order.id.placeholder', + 'title' => 'form.order.id.title', + ), + // Value of parent's 'attr_translation_parameters' will be merged with + // this field's empty 'attr_translation_parameters'. + // array('%company%' => 'ACME') will be used to translate 'placeholder' and 'title'. + )); + + .. code-block:: php + + // App/Form/OrderType.php + // ... + + $builder->add('id', null, array( + 'attr' => array( + 'placeholder' => 'form.order.id.placeholder', + 'title' => 'form.order.id.title', + ), + 'attr_translation_parameters' => array( + '%company%' => 'American Company Making Everything', + ), + // Value of parent's 'attr_translation_parameters' will be merged with + // this field's 'attr_translation_parameters'. + // array('%company%' => 'American Company Making Everything') + // will be used to translate 'placeholder' and 'title'. + )); diff --git a/reference/forms/types/options/choice_type_translation_domain.rst.inc b/reference/forms/types/options/choice_type_translation_domain.rst.inc index 87cd76cff9a..c22125ea844 100644 --- a/reference/forms/types/options/choice_type_translation_domain.rst.inc +++ b/reference/forms/types/options/choice_type_translation_domain.rst.inc @@ -5,4 +5,4 @@ translation_domain In case `choice_translation_domain`_ is set to ``true`` or ``null``, this configures the exact translation domain that will be used for any labels or -options that are rendered for this field +options that are rendered for this field. diff --git a/reference/forms/types/options/help_translation_parameters.rst.inc b/reference/forms/types/options/help_translation_parameters.rst.inc new file mode 100644 index 00000000000..3a1138e9f1d --- /dev/null +++ b/reference/forms/types/options/help_translation_parameters.rst.inc @@ -0,0 +1,72 @@ +help_translation_parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``[]`` + +Translated `help`_ can +contain :ref:`placeholders `. +This option allows you to pass an array of parameters in order to replace +placeholders with actual values. + +Given this translation message: + +.. code-block:: yaml + + # translations/messages.en.yml + form.order.id.help: This will be the reference in communications with %company% + +you can specify placeholder value: + +.. code-block:: php + + $builder->add('id', null, array( + 'help' => 'form.order.id.help', + 'help_translation_parameters' => [ + '%company%' => 'ACME Inc.' + ] + )); + +Note that ``help_translation_parameters`` of children fields are merged with those +of its parent. In other words the parent's translation parameters are available +for children but can be overriden: + +.. code-block:: php + + // App/Controller/OrderController.php + use App\Form\OrderType; + // ... + + $form = $this->createForm(OrderType::class, $order, array( + // available to all children, grandchildren and so on. + 'help_translation_parameters' => array( + '%company%' => 'ACME', + ), + )); + + .. code-block:: php + + // App/Form/OrderType.php + // ... + + $builder->add('id', null, array( + 'help' => 'form.order.id.help', + // Value of parent's 'help_translation_parameters' will be merged with + // this field's empty 'help_translation_parameters'. + // array('%company%' => 'ACME') will be used to translate 'help'. + )); + + .. code-block:: php + + // App/Form/OrderType.php + // ... + + $builder->add('id', null, array( + 'help' => 'form.order.id.help', + 'help_translation_parameters' => array( + '%company%' => 'American Company Making Everything', + ), + // Value of parent's 'help_translation_parameters' will be merged with + // this field's 'help_translation_parameters'. + // array('%company%' => 'American Company Making Everything') + // will be used to translate 'help'. + )); diff --git a/reference/forms/types/options/label_translation_parameters.rst.inc b/reference/forms/types/options/label_translation_parameters.rst.inc new file mode 100644 index 00000000000..269b52ff72f --- /dev/null +++ b/reference/forms/types/options/label_translation_parameters.rst.inc @@ -0,0 +1,72 @@ +label_translation_parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``[]`` + +Translated `label`_, can +contain :ref:`placeholders `. +This option allows you to pass an array of parameters in order to replace +placeholders with actual values. + +Given this translation message: + +.. code-block:: yaml + + # translations/messages.en.yml + form.order.id: Identifier of the order to %company% + +you can specify placeholder value: + +.. code-block:: php + + $builder->add('id', null, array( + 'label' => 'form.order.id', + 'label_translation_parameters' => [ + '%company%' => 'ACME Inc.' + ] + )); + +Note that ``label_translation_parameters`` of children fields are merged with those +of its parent. In other words the parent's translation parameters are available +for children but can be overriden: + +.. code-block:: php + + // App/Controller/OrderController.php + use App\Form\OrderType; + // ... + + $form = $this->createForm(OrderType::class, $order, array( + // available to all children, grandchildren and so on. + 'label_translation_parameters' => array( + '%company%' => 'ACME', + ), + )); + + .. code-block:: php + + // App/Form/OrderType.php + // ... + + $builder->add('id', null, array( + 'label' => 'form.order.id', + // Value of parent's 'label_translation_parameters' will be merged with + // this field's empty 'label_translation_parameters'. + // array('%company%' => 'ACME') will be used to translate this label. + )); + + .. code-block:: php + + // App/Form/OrderType.php + // ... + + $builder->add('id', null, array( + 'label' => 'form.order.id', + 'label_translation_parameters' => array( + '%company%' => 'American Company Making Everything', + ), + // Value of parent's 'label_translation_parameters' will be merged with + // this field's 'label_translation_parameters'. + // array('%company%' => 'American Company Making Everything') + // will be used to translate this label. + )); diff --git a/reference/forms/types/reset.rst b/reference/forms/types/reset.rst index f9363b0257b..b3d0e14db0a 100644 --- a/reference/forms/types/reset.rst +++ b/reference/forms/types/reset.rst @@ -13,6 +13,8 @@ A button that resets all fields to their original values. | options | - `disabled`_ | | | - `label`_ | | | - `translation_domain`_ | +| | - `label_translation_parameters`_ | +| | - `attr_translation_parameters`_ | +----------------------+---------------------------------------------------------------------+ | Parent type | :doc:`ButtonType ` | +----------------------+---------------------------------------------------------------------+ @@ -45,3 +47,83 @@ as a key. This can be useful when you need to set a custom class for the button: .. include:: /reference/forms/types/options/button_label.rst.inc .. include:: /reference/forms/types/options/button_translation_domain.rst.inc + +label_translation_parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``[]`` + +Translated `label`_ can contain +:ref:`placeholders `. +This option allows you to pass an array of parameters in order to replace +placeholders with actual values. + +Given this translation message: + +.. code-block:: yaml + + # translations/messages.en.yml + form.order.reset: Reset an order to %company% + +you can specify placeholder value: + +.. code-block:: php + + use Symfony\Component\Form\Extension\Core\Type\ResetType; + // ... + + $builder->add('send', ResetType::class, array( + 'label' => 'form.order.reset', + 'label_translation_parameters' => array( + '%company%' => 'ACME Inc.', + ), + )); + +Note that ``label_translation_parameters`` of resets are merged with those of its +parent. In other words the parent's translation parameters are available for +children's resets but can be overriden: + +.. code-block:: php + + // App/Controller/OrderController.php + use App\Form\OrderType; + // ... + + $form = $this->createForm(OrderType::class, $order, array( + // available to all children, grandchildren and so on. + 'label_translation_parameters' => array( + '%company%' => 'ACME', + ), + )); + +.. code-block:: php + + // App/Form/OrderType.php + use Symfony\Component\Form\Extension\Core\Type\ResetType; + // ... + + $builder->add('send', ResetType::class, array( + 'label' => 'form.order.reset', + // Value of parent's 'label_translation_parameters' will be merged with + // this field's empty 'label_translation_parameters'. + // array('%company%' => 'ACME') will be used to translate this label. + )); + +.. code-block:: php + + // App/Form/OrderType.php + use Symfony\Component\Form\Extension\Core\Type\ResetType; + // ... + + $builder->add('send', ResetType::class, array( + 'label' => 'form.order.reset', + 'label_translation_parameters' => array( + '%company%' => 'American Company Making Everything', + ), + // Value of parent's 'label_translation_parameters' will be merged with + // this reset's 'label_translation_parameters'. + // array('%company%' => 'American Company Making Everything') + // will be passed to translate this label. + )); + +.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc diff --git a/reference/forms/types/submit.rst b/reference/forms/types/submit.rst index bdb7a92d12a..541b2cbba77 100644 --- a/reference/forms/types/submit.rst +++ b/reference/forms/types/submit.rst @@ -14,6 +14,8 @@ A submit button. | | - `label`_ | | | - `label_format`_ | | | - `translation_domain`_ | +| | - `label_translation_parameters`_ | +| | - `attr_translation_parameters`_ | | | - `validation_groups`_ | +----------------------+----------------------------------------------------------------------+ | Parent type | :doc:`ButtonType` | @@ -59,6 +61,86 @@ as a key. This can be useful when you need to set a custom class for the button: .. include:: /reference/forms/types/options/button_translation_domain.rst.inc +label_translation_parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``[]`` + +Translated `label`_ can contain +:ref:`placeholders `. +This option allows you to pass an array of parameters in order to replace +placeholders with actual values. + +Given this translation message: + +.. code-block:: yaml + + # translations/messages.en.yml + form.order.submit_to_company: Send an order to %company% + +you can specify placeholder value: + +.. code-block:: php + + use Symfony\Component\Form\Extension\Core\Type\SubmitType; + // ... + + $builder->add('send', SubmitType::class, array( + 'label' => 'form.order.submit_to_company', + 'label_translation_parameters' => array( + '%company%' => 'ACME Inc.', + ), + )); + +Note that ``label_translation_parameters`` of submits are merged with those of its +parent. In other words the parent's translation parameters are available for +children's submits but can be overriden: + +.. code-block:: php + + // App/Controller/OrderController.php + use App\Form\OrderType; + // ... + + $form = $this->createForm(OrderType::class, $order, array( + // available to all children, grandchildren and so on. + 'label_translation_parameters' => array( + '%company%' => 'ACME', + ), + )); + +.. code-block:: php + + // App/Form/OrderType.php + use Symfony\Component\Form\Extension\Core\Type\SubmitType; + // ... + + $builder->add('send', SubmitType::class, array( + 'label' => 'form.order.submit_to_company', + // Value of parent's 'label_translation_parameters' will be merged with + // this field's empty 'label_translation_parameters'. + // array('%company%' => 'ACME') will be used to translate this label. + )); + +.. code-block:: php + + // App/Form/OrderType.php + use Symfony\Component\Form\Extension\Core\Type\SubmitType; + // ... + + $builder->add('send', SubmitType::class, array( + 'label' => 'form.order.submit_to_company', + 'label_translation_parameters' => array( + '%company%' => 'American Company Making Everything', + ), + // Value of parent's 'label_translation_parameters' will be merged with + // this submit's 'label_translation_parameters'. + // array('%company%' => 'American Company Making Everything') + // will be passed to translate this label. + )); + +.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc + validation_groups ~~~~~~~~~~~~~~~~~ diff --git a/templating/PHP.rst b/templating/PHP.rst index 6e89a46964b..743082806f7 100644 --- a/templating/PHP.rst +++ b/templating/PHP.rst @@ -532,7 +532,7 @@ original template: humanize($name); } ?> - +