feat: Add support for choices in template components. (#282)

Author: fsbraun

djangocms_frontend/templatetags/cms_component.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+import re
 from django import forms, template
 
 register = template.Library()
@@ -49,10 +51,29 @@ def field(context: template.Context, field_name: str, field_type: forms.Field, *
     return ""
 
 
+def _to_tuple_if_needed(value: str) -> str | tuple[str, str]:
+    """
+    Helper function to convert a string into a tuple if it contains a delimiter.
+
+    Args:
+        value (str): The string to be converted.
+
+    Returns:
+        tuple[str, str]: A tuple containing the two parts of the string if it contains a delimiter,
+                         otherwise returns the original string as a single-element tuple.
+    """
+    match = re.match(r"^(.*?)\s*<([^>]+)>\s?$", value)
+    if match:
+        return (match.group(2).strip(), match.group(1).strip())
+    return value
+
+
 @register.filter
-def split(value: str, delimiter: str = "|") -> list[str]:
+def split(value: str, delimiter: str = "|") -> list[str] | list[tuple[str, str]]:
     """
     Helper that splits a given string into a list of substrings based on a specified delimiter.
+    If the substring is of the format "Verbose name <value>" it is turned into a 2-tuple
+    as used by a form field's choices argument.
 
     Args:
         value (str): The string to be split.
@@ -61,4 +82,5 @@ def split(value: str, delimiter: str = "|") -> list[str]:
     Returns:
         list[str]: A list of substrings obtained by splitting the input string using the delimiter.
     """
-    return value.split(delimiter)
+    split_list = value.split(delimiter)
+    return [_to_tuple_if_needed(item) for item in split_list]

docs/source/tutorial/custom_components.rst

@@ -5,7 +5,7 @@ Building Custom Frontend Components
 ####################################
 
 .. index::
-    single: custom frontend components
+    single: Custom frontend components
 
 .. versionadded:: 2.0
 

docs/source/tutorial/template_components.rst

@@ -250,6 +250,40 @@ Simply replace ``{{ title }}`` and/or ``{{ slogan }}`` with ``{% inline_field "t
     template files, you need to restart the server manually to see the changes.
 
 
+A little helper: the ``split`` filter
+-------------------------------------
+
+.. index::
+    single: split filter
+    single: choices in template components
+
+If you load the ``cms_component`` template tag library, you can use the ``split`` filter to convert a string into a list.
+Some component properties require a list of values, such as the ``parent_classes`` or ``child_classes``.
+You can use the ``split`` filter to convert a string into a list. For example, if you want to allow the
+**Hero component** to be a child of the **Container or Column component**, you can set the ``parent_classes``
+like this::
+
+    {% cms_component "Hero" name=_("My Hero Component") parent_classes="ContainerPlugin|ColumnPlugin"|split %}
+
+``split`` splits a string by the pipe character (``|``) and returns a list of strings. If you prefer to use a different
+separator, you can pass it as an argument to the filter, like this::
+
+    {% cms_component "Hero" name=_("My Hero Component") parent_classes="ContainerPlugin,ColumnPlugin"|split:"," %}
+
+Additionally, ``split`` can be used to create tuples as needed for the ``choices`` parameter of
+``forms.ChoiceField``. For example, if you want to create a choice field with two options, you can use the
+following code::
+
+    {% field "color" forms.ChoiceField choices=_("Red <red>|Green <green>|Default <blue>")|split name=_("Color") %}
+
+The verbose choice label is appended by the actual value of the field between angle brackets (``<...>``).
+
+.. note::
+
+    For translators it is important to know, that they **should not translate** the value in angle brackets.
+    The German translation of the above example string might be ``Rot <red>|Grün <green>|Standard <blue>``.
+
+
 Limitations of template components
 ----------------------------------
 

tests/test_autocomponent.py

@@ -69,7 +69,23 @@ def test_split_template_tag(self):
         self.assertEqual(split("hero.html"), ["hero.html"])
         self.assertEqual(split("Mixin1|Mixin2"), ["Mixin1", "Mixin2"])
         self.assertEqual(split("hero.html"), ["hero.html"])
+        # Common alternative:
         self.assertEqual(split("hero.html, Mixin1, Mixin2", ", "), ["hero.html", "Mixin1", "Mixin2"])
+        # Not nice but correct:
+        self.assertEqual(split("hero.html, Mixin1, Mixin2", ","), ["hero.html", " Mixin1", " Mixin2"])
+
+        self.assertEqual(
+            split("Dark mode <bg-dark>|Light mode <bg-light>"),
+            [("bg-dark", "Dark mode"), ("bg-light", "Light mode")],
+        )
+        self.assertEqual(
+            split("Dark mode<bg-dark>|Light mode<bg-light>"),  # No space before < needed
+            [("bg-dark", "Dark mode"), ("bg-light", "Light mode")],
+        )
+        self.assertEqual(
+            split("Dark mode <bg-dark|bg-light>"),
+            ["Dark mode <bg-dark", "bg-light>"],
+        )
 
     def test_invalid_cms_component_usage_missing_required_argument(self):
         # The {% cms_component %} tag requires a component name.