From 54533a8668e2644bcbfa77f5d324dcaa7a14d4a9 Mon Sep 17 00:00:00 2001 From: Zdeno Kuzmany Date: Fri, 30 May 2025 13:07:20 +0200 Subject: [PATCH 1/3] docs: add documentation for contact field label modifier Add documentation for the new < /dev/null | label modifier that displays human-readable labels for select and boolean contact fields instead of stored values. Related to https://github.com/mautic/mautic/pull/12620 --- docs/channels/emails.rst | 22 +++++++++++++++++++++ docs/configuration/variables.rst | 34 ++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/docs/channels/emails.rst b/docs/channels/emails.rst index 61005612..a771dba4 100644 --- a/docs/channels/emails.rst +++ b/docs/channels/emails.rst @@ -187,6 +187,28 @@ To use custom date fields in tokens, use the following format: The date outputs in a human-readable format, configured in the settings in your Global Configuration > System Settings under 'Default format for date only' and 'Default time only format'. +Label modifier for select and boolean fields +--------------------------------------------- + +For select and boolean field types, you can display the human-readable label instead of the stored value by using the ``|label`` modifier: + +.. code-block:: php + + {contactfield=select_alias|label} + {contactfield=bool_alias|label} + +This is useful when your select fields store technical values but you want to display user-friendly labels in your Emails. For example: + +- A country select field storing ``us`` can display ``United States`` +- A boolean field storing ``1`` can display ``Yes`` + +The modifier also works with company fields: + +.. code-block:: php + + {contactfield=company_select_alias|label} + {contactfield=company_bool_alias|label} + Contact replies =============== diff --git a/docs/configuration/variables.rst b/docs/configuration/variables.rst index 9be629ee..6161c574 100644 --- a/docs/configuration/variables.rst +++ b/docs/configuration/variables.rst @@ -8,6 +8,40 @@ Variables ``Hi {contactfield=firstname|there},`` +Token modifiers +*************** + +Label modifier for select and boolean fields +============================================= + +For select and boolean type fields, you can use the ``|label`` modifier to display the human-readable label instead of the stored value. This is particularly useful when your select fields store values like codes or IDs but you want to display friendly labels to your Contacts. + +**Syntax:** + +.. code-block:: text + + {contactfield=field_alias|label} + +**Examples:** + +For a select field with alias ``country_select`` that has options like ``us`` (United States), ``uk`` (United Kingdom): + +- ``{contactfield=country_select}`` - displays the value: ``us`` +- ``{contactfield=country_select|label}`` - displays the label: ``United States`` + +For a boolean field with alias ``is_subscriber``: + +- ``{contactfield=is_subscriber}`` - displays the value: ``1`` or ``0`` +- ``{contactfield=is_subscriber|label}`` - displays the label: ``Yes`` or ``No`` + +This modifier works for both Contact fields and Company fields: + +- ``{contactfield=company_type|label}`` - displays the label of a company select field +- ``{contactfield=company_active|label}`` - displays the label of a company boolean field + +.. note:: + The ``|label`` modifier only works with select and boolean field types. For other field types, it will display the regular value. + Contact fields ************** From 9f58105e03e9c15006ae5ed69a0497009cde7f04 Mon Sep 17 00:00:00 2001 From: Ayu Adiati <45172775+adiati98@users.noreply.github.com> Date: Thu, 22 Jan 2026 09:59:35 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Ruth Cheesley --- docs/channels/emails.rst | 2 +- docs/configuration/variables.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/channels/emails.rst b/docs/channels/emails.rst index a771dba4..c0ed78e5 100644 --- a/docs/channels/emails.rst +++ b/docs/channels/emails.rst @@ -202,7 +202,7 @@ This is useful when your select fields store technical values but you want to di - A country select field storing ``us`` can display ``United States`` - A boolean field storing ``1`` can display ``Yes`` -The modifier also works with company fields: +The modifier also works with Company fields: .. code-block:: php diff --git a/docs/configuration/variables.rst b/docs/configuration/variables.rst index 6161c574..dfe72804 100644 --- a/docs/configuration/variables.rst +++ b/docs/configuration/variables.rst @@ -36,8 +36,8 @@ For a boolean field with alias ``is_subscriber``: This modifier works for both Contact fields and Company fields: -- ``{contactfield=company_type|label}`` - displays the label of a company select field -- ``{contactfield=company_active|label}`` - displays the label of a company boolean field +- ``{contactfield=company_type|label}`` - displays the label of a Company select field +- ``{contactfield=company_active|label}`` - displays the label of a Company boolean field .. note:: The ``|label`` modifier only works with select and boolean field types. For other field types, it will display the regular value. From dbd1a338da6eb4ac4121191678e6c15aba14e5fa Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 22 Jan 2026 10:49:05 +0100 Subject: [PATCH 3/3] fix: format and adjust wordings --- docs/channels/emails.rst | 16 ++++++++-------- docs/configuration/variables.rst | 27 ++++++++++++++------------- 2 files changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/channels/emails.rst b/docs/channels/emails.rst index c0ed78e5..9b6057cb 100644 --- a/docs/channels/emails.rst +++ b/docs/channels/emails.rst @@ -188,26 +188,26 @@ To use custom date fields in tokens, use the following format: The date outputs in a human-readable format, configured in the settings in your Global Configuration > System Settings under 'Default format for date only' and 'Default time only format'. Label modifier for select and boolean fields ---------------------------------------------- +-------------------------------------------- For select and boolean field types, you can display the human-readable label instead of the stored value by using the ``|label`` modifier: .. code-block:: php - {contactfield=select_alias|label} - {contactfield=bool_alias|label} + {contactfield=select_alias|label} + {contactfield=bool_alias|label} -This is useful when your select fields store technical values but you want to display user-friendly labels in your Emails. For example: +This is particularly useful when these fields contain technical values, but you want to show user-friendly labels in your Emails. For instance: -- A country select field storing ``us`` can display ``United States`` -- A boolean field storing ``1`` can display ``Yes`` +* A country selection field storing ``us`` can display ``United States`` +* A boolean field storing ``1`` can display ``Yes`` The modifier also works with Company fields: .. code-block:: php - {contactfield=company_select_alias|label} - {contactfield=company_bool_alias|label} + {contactfield=company_select_alias|label} + {contactfield=company_bool_alias|label} Contact replies =============== diff --git a/docs/configuration/variables.rst b/docs/configuration/variables.rst index dfe72804..8cd35c3d 100644 --- a/docs/configuration/variables.rst +++ b/docs/configuration/variables.rst @@ -12,35 +12,36 @@ Token modifiers *************** Label modifier for select and boolean fields -============================================= +============================================ -For select and boolean type fields, you can use the ``|label`` modifier to display the human-readable label instead of the stored value. This is particularly useful when your select fields store values like codes or IDs but you want to display friendly labels to your Contacts. +For select and boolean type fields, you can use the ``|label`` modifier to display the human-readable label instead of the stored value. It's beneficial when your select fields store values like codes or IDs, but you want to display friendly labels to your Contacts. **Syntax:** .. code-block:: text - {contactfield=field_alias|label} + {contactfield=field_alias|label} **Examples:** -For a select field with alias ``country_select`` that has options like ``us`` (United States), ``uk`` (United Kingdom): +* For a select field with alias ``country_select`` that has options, such as ``us`` for ``United States`` or ``uk`` for ``United Kingdom``: -- ``{contactfield=country_select}`` - displays the value: ``us`` -- ``{contactfield=country_select|label}`` - displays the label: ``United States`` + * ``{contactfield=country_select}`` displays the value ``us`` + * ``{contactfield=country_select|label}`` displays the label ``United States`` -For a boolean field with alias ``is_subscriber``: +* For a boolean field with alias ``is_subscriber``: -- ``{contactfield=is_subscriber}`` - displays the value: ``1`` or ``0`` -- ``{contactfield=is_subscriber|label}`` - displays the label: ``Yes`` or ``No`` + * ``{contactfield=is_subscriber}`` displays the value ``1`` or ``0`` + * ``{contactfield=is_subscriber|label}`` displays the label ``Yes`` or ``No`` -This modifier works for both Contact fields and Company fields: +* For both Contact fields and Company fields: -- ``{contactfield=company_type|label}`` - displays the label of a Company select field -- ``{contactfield=company_active|label}`` - displays the label of a Company boolean field + * ``{contactfield=company_type|label}`` displays the label of a Company select field + * ``{contactfield=company_active|label}`` displays the label of a Company boolean field .. note:: - The ``|label`` modifier only works with select and boolean field types. For other field types, it will display the regular value. + + The ``|label`` modifier only works with select and boolean field types. For other field types, it displays the regular value. Contact fields **************