From e99ebb706e8e6e830514c93cf316833918b0eb01 Mon Sep 17 00:00:00 2001
From: Zdeno Kuzmany <zdeno@kuzmany.biz>
Date: Fri, 30 May 2025 13:07:20 +0200
Subject: [PATCH] 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 29dbbe96..88df7f70 100644
--- a/docs/channels/emails.rst
+++ b/docs/channels/emails.rst
@@ -141,6 +141,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
 **************