Add a helper for rendering sections to the region renderer

Author: matthiask

CHANGELOG.rst

@@ -6,10 +6,17 @@ Change log
 Next version
 ~~~~~~~~~~~~
 
-- Added Django 5.2a1 to the CI.
+- Added Django 5.2 to the CI.
 - Undeprecated the :mod:`~feincms3.mixins.TemplateMixin`, it's useful even
   though using :mod:`~feincms3.applications.PageTypeMixin` is obviously
   preferred.
+- Added tests for using ``reverse_app`` with the new ``query`` and ``fragment``
+  parameters from Django 5.2 to ensure everything works as it should.
+- Converted the testsuite to pytest and organized tests a bit.
+- Added experimental support for section rendering to the ``RegionRenderer``.
+  Sections are a more powerful alternative or addition to subregions already
+  supported by django-content-editor. The main upside of sections is that they
+  can be nested.
 
 
 5.3 (2024-11-18)

feincms3/renderer.py

@@ -83,6 +83,7 @@ def template_renderer(template_name, local_context=default_context, /):
 _subregion = 2
 _marks = 3
 _fetch = 4
+CLOSE_SECTION = "__close_section__"
 
 
 class RegionRenderer:
@@ -294,6 +295,13 @@ def handle_default(self, plugins, context):
         for plugin in self.takewhile_subregion(plugins, "default"):
             yield self.render_plugin(plugin, context)
 
+    def handle___close_section__(self, plugins, context):
+        # Internal helper which discards superfluous CLOSE_SECTION plugins
+        # This method assumes that we're working in a string/HTML context and
+        # therefore yields an empty string.
+        plugins.popleft()
+        yield ""
+
     def render_region(self, *, region, contents, context):
         """
         Render one region.
@@ -313,6 +321,23 @@ def render_regions(self, *, regions, contents, context):
             for region in regions
         }
 
+    # Sections support
+
+    def render_section_plugins(self, section, plugins, context):
+        out = []
+        while plugins:
+            subregion = self.subregion(plugins[0])
+            if subregion == CLOSE_SECTION:
+                plugins.popleft()
+                break
+            elif subregion is not None:
+                out.extend(self._handlers[subregion](plugins, context))
+            else:
+                out.append(self.render_plugin(plugins.popleft(), context))
+        return out
+
+    # Main external rendering API
+
     def regions_from_contents(self, contents, **kwargs):
         """
         Return an opaque object encapsulating

tests/testapp/test_region_renderer.py

@@ -2,12 +2,14 @@
 
 import pytest
 from content_editor.contents import contents_for_item
+from content_editor.models import Region
 from django.core.exceptions import ImproperlyConfigured
 from django.template import Context
 from django.utils.html import format_html, mark_safe
 from pytest_django.asserts import assertHTMLEqual
 
 from feincms3.renderer import (
+    CLOSE_SECTION,
     PluginNotRegisteredError,
     RegionRenderer,
     template_renderer,
@@ -194,3 +196,70 @@ def test_register_unregister():
         renderer.unregister(HTML, keep=[RichText])
     with pytest.raises(ImproperlyConfigured):
         renderer.unregister()
+
+
+def test_sections():
+    class SectionRenderer(RegionRenderer):
+        def handle_images(self, plugins, context):
+            content = "".join(
+                self.render_plugin(p, context)
+                for p in self.takewhile_subregion(plugins, "images")
+            )
+            yield f"<gallery>{content}</gallery>"
+
+        def handle_section(self, plugins, context):
+            section = plugins.popleft()
+            content = self.render_section_plugins(section, plugins, context)
+            return f"<section>{''.join(content)}</section>"
+
+    class Text:
+        pass
+
+    class Image:
+        pass
+
+    class Section:
+        pass
+
+    class CloseSection:
+        pass
+
+    renderer = SectionRenderer()
+    renderer.register(Text, "Text")
+    renderer.register(Image, "Image", subregion="images")
+    renderer.register(Section, "", subregion="section")
+    renderer.register(CloseSection, "", subregion=CLOSE_SECTION)
+
+    def render(plugins):
+        return renderer.render_region(
+            region=Region(key="content", title="Content"),
+            contents={"content": plugins},
+            context=None,
+        )
+
+    t = Text()
+    i = Image()
+    s = Section()
+    c = CloseSection()
+
+    # Basic tests
+    assert render([t, t]) == "TextText"
+    assert render([t, t, i, i, t]) == "TextText<gallery>ImageImage</gallery>Text"
+
+    # Automatic closing of sections
+    assert render([s, t]) == "<section>Text</section>"
+
+    # Superfluous CloseSection objects are ignored
+    assert render([s, t, c, c]) == "<section>Text</section>"
+
+    # Nested sections, the images subregion is also rendered within the outer section
+    assert (
+        render([t, s, t, s, t, c, i])
+        == "Text<section>Text<section>Text</section><gallery>Image</gallery></section>"
+    )
+
+    # The images subregion doesn't support nested sections and is automatically closed
+    assert (
+        render([t, i, i, s, t])
+        == "Text<gallery>ImageImage</gallery><section>Text</section>"
+    )

tox.ini

@@ -19,7 +19,7 @@ deps =
     dj42: Django>=4.2,<5.0
     dj50: Django>=5.0,<5.1
     dj51: Django>=5.1,<5.2
-    dj52: Django>=5.2a1,<6.0
+    dj52: Django>=5.2,<6.0
     djmain: https://github.com/django/django/archive/main.tar.gz
 
 [testenv:docs]