Add {% plugin %} template tag.

Author: fsbraun

djangocms_frontend/__init__.py

@@ -19,4 +19,4 @@
 13. Github actions will publish the new package to pypi
 """
 
-__version__ = "1.3.2"
+__version__ = "2.0.0a"

djangocms_frontend/apps.py

@@ -0,0 +1,11 @@
+from django import apps
+
+
+class DjangocmsFrontendConfig(apps.AppConfig):
+    name = "djangocms_frontend"
+    verbose_name = "DjangoCMS Frontend"
+
+    def ready(self):
+        from .pool import setup
+
+        setup()

djangocms_frontend/contrib/carousel/templates/djangocms_frontend/bootstrap5/carousel/default/image.html

@@ -1,8 +1,6 @@
 {% load cms_tags easy_thumbnails_tags %}
 {% if instance.rel_image %}
-    {% thumbnail instance.rel_image options.size crop=options.crop upscale=options.upscale subject_location=instance.rel_image.subject_location as thumbnail %}
-
-    <img class="d-block w-100" src="{{ thumbnail.url }}" alt="{{ instance.rel_image.default_alt_text|default:'' }}" />
+    <img class="d-block mx-auto" style="height: 40vh;" src="{{ instance.rel_image.url }}" alt="{{ instance.rel_image.default_alt_text|default:'' }}" />
 {% else %}
     <div class="d-block w-100"
         style="aspect-ratio: {{ aspect_ratio }}">

djangocms_frontend/contrib/component/__init__.py

@@ -60,12 +60,14 @@ def get_object_for_value(value):
 
 
 def unescape(text, nbsp):
-    return (text.replace(" ", nbsp)
-            .replace("&", "&")
-            .replace("&lt;", "<")
-            .replace("&gt;", ">")
-            .replace("&quot;", '"')
-            .replace("&#x27;", "'"))
+    return (
+        text.replace("&nbsp;", nbsp)
+        .replace("&amp;", "&")
+        .replace("&lt;", "<")
+        .replace("&gt;", ">")
+        .replace("&quot;", '"')
+        .replace("&#x27;", "'")
+    )
 
 
 def get_link_choices(request, term="", lang=None, nbsp=None):

djangocms_frontend/contrib/link/helpers.py

@@ -0,0 +1,101 @@
+import copy
+import importlib
+import warnings
+
+from cms.plugin_pool import plugin_pool
+from cms.templatetags.cms_tags import render_plugin
+from django.conf import settings
+from django.contrib.admin.sites import site as admin_site
+from django.template import engines
+from django.template.library import SimpleNode
+from django.template.loader import get_template
+
+django_engine = engines["django"]
+
+plugin_tag_pool = {}
+
+
+IGNORED_FIELDS = (
+    "id",
+    "cmsplugin_ptr",
+    "language",
+    "plugin_type",
+    "position",
+    "creation_date",
+    "ui_item",
+)
+
+allowed_plugin_types = tuple(
+    getattr(importlib.import_module(cls.rsplit(".", 1)[0]), cls.rsplit(".", 1)[-1]) if isinstance(cls, str) else cls
+    for cls in getattr(settings, "CMS_COMPONENT_PLUGINS", [])
+)
+
+
+def _get_plugindefaults(instance):
+    defaults = {
+        field.name: getattr(instance, field.name)
+        for field in instance._meta.fields
+        if field.name not in IGNORED_FIELDS and bool(getattr(instance, field.name))
+    }
+    defaults["plugin_type"] = instance.__class__.__name__
+    return defaults
+
+
+class _DummyUser:
+    is_superuser = True
+    is_staff = True
+
+    def has_perm(self, perm):
+        return True
+
+
+class _DummyRequest:
+    user = _DummyUser()
+
+
+def render_dummy_plugin(context, dummy_plugin):
+    return dummy_plugin.nodelist.render(context)
+
+
+def patch_template(template):
+    """Patches the template to use the dummy plugin renderer instead of the real one."""
+    copied_template = copy.deepcopy(template)
+    patch = False
+    for node in copied_template.template.nodelist.get_nodes_by_type(SimpleNode):
+        if node.func == render_plugin:
+            patch = True
+            node.func = render_dummy_plugin
+    return copied_template if patch else template
+
+
+def setup():
+    global plugin_tag_pool
+
+    for plugin in plugin_pool.get_all_plugins():
+        if not issubclass(plugin, allowed_plugin_types):
+            continue
+        tag_name = plugin.__name__.lower()
+        if tag_name.endswith("plugin"):
+            tag_name = tag_name[:-6]
+        try:
+            instance = plugin.model()
+            plugin_admin = plugin(admin_site=admin_site)
+            if hasattr(instance, "initialize_from_form"):
+                form_class = plugin_admin.get_form(_DummyRequest())
+                instance.initialize_from_form(form_class)
+            if tag_name not in plugin_tag_pool:
+                template = get_template(plugin_admin._get_render_template({}, instance, None))
+                plugin_tag_pool[tag_name] = {
+                    "defaults": {
+                        **_get_plugindefaults(instance),
+                        **dict(plugin_type=plugin.__name__),
+                    },
+                    "template": patch_template(template),
+                    "class": plugin,
+                }
+            else:
+                warnings.warn(
+                    f"Duplicate candidates for {{% plugin \"{tag_name}\" %}} found. "
+                    f"Only registered {plugin_tag_pool[tag_name]['class'].__name__}.", stacklevel=1)
+        except Exception as exc:
+            warnings.warn(str(exc), stacklevel=1)

djangocms_frontend/pool.py

@@ -1,6 +1,10 @@
 import json
 
+from classytags.arguments import Argument, MultiKeywordArgument
+from classytags.core import Options
+from classytags.helpers import AsTag
 from django import template
+from django.conf import settings as django_settings
 from django.contrib.contenttypes.models import ContentType
 from django.core.serializers.json import DjangoJSONEncoder
 from django.template.defaultfilters import safe
@@ -9,8 +13,10 @@
 from django.utils.html import conditional_escape, mark_safe
 
 from djangocms_frontend import settings
+from djangocms_frontend.cms_plugins import CMSUIPlugin
 from djangocms_frontend.fields import HTMLsanitized
 from djangocms_frontend.helpers import get_related_object as related_object
+from djangocms_frontend.pool import plugin_tag_pool
 
 register = template.Library()
 
@@ -95,3 +101,49 @@ def framework_info(context, item, as_json=True):
         if as_json
         else framework_info.get(item, "")
     )
+
+
+class DummyPlugin:
+    def __init__(self, nodelist):
+        self.nodelist = nodelist
+        super().__init__()
+
+
+class Plugin(AsTag):
+    name = "plugin"
+    options = Options(
+        Argument("name", required=True),
+        MultiKeywordArgument("kwargs", required=False),
+        "as",
+        Argument("varname", resolve=False, required=False),
+        blocks=[("endplugin", "nodelist")],
+    )
+
+    def message(self, message):
+        return f"<!-- {message} -->" if django_settings.DEBUG else ""
+
+    def get_value(self, context, name, kwargs, nodelist):
+        if name not in plugin_tag_pool:
+            return self.message(f"Plugin {name} not found in pool for plugins usable with {{% plugin %}}.")
+        context.push()
+        instance = (plugin_tag_pool[name]["defaults"])
+        plugin_class = plugin_tag_pool[name]["class"]
+        if issubclass(plugin_class, CMSUIPlugin):
+            #
+            instance["config"].update(kwargs)
+        else:
+            instance.update(kwargs)
+        # Create context
+        context["instance"] = plugin_class.model(**instance)
+        # Call render method of plugin
+        context = plugin_class().render(context, context["instance"], None)
+        # Replace inner plugins with the nodelist, i.e. the content within the plugin tag
+        context["instance"].child_plugin_instances = [DummyPlugin(nodelist)]
+        # ... and redner
+
+        result = plugin_tag_pool[name]["template"].render(context.flatten())
+        context.pop()
+        return result
+
+
+register.tag(Plugin.name, Plugin)

djangocms_frontend/templatetags/frontend.py

@@ -35,9 +35,29 @@ each collapsable section.
 Also see Bootstrap 5 `Accordion <https://getbootstrap.com/docs/5.3/components/accordion/>`_
 documentation.
 
+Re-usable component example
+===========================
+
+The accordion component is a good example of a re-usable component. It can be
+used in all your project's templates. Here is an example of how to create an
+accordion (if key word arguments are skipped they fall back to their defaults):
+
+.. code-block::
+
+    {% load frontend %}
+    {% plugin "accordion" accordion_header_type="h2" accordion_flush=False %}
+        {% plugin "accordionitem" accordion_item_header="Accordion item 1" accordion_item_open=True %}
+            Content of accordion item 1
+        {% endplugin %}
+        {% plugin "accordionitem" accordion_item_header="Accordion item 2" %}
+            Content of accordion item 1
+        {% endplugin %}
+    {% endplugin %}
+
 .. index::
     single: Alert
 
+
 ***************
 Alert component
 ***************
@@ -61,6 +81,21 @@ the right hand side.
 Also see Bootstrap 5 `Alerts <https://getbootstrap.com/docs/5.3/components/alerts/>`_
 documentation.
 
+Re-usable component example
+===========================
+
+**djangocms-frontend** plugins can be used as components. They can be
+used in all your project's templates. Example (if key word arguments are
+skipped they fall back to their defaults):
+
+.. code-block::
+
+    {% load frontend %}
+    {% plugin "alert" alert_context="primary" alert_dismissible=True %}
+        Alert text goes here!
+    {% endplugin %}
+
+
 .. index::
     single: Badge
 
@@ -79,6 +114,22 @@ plugin, badges are useful, e.g., to mark featured or new headers.
 Also see Bootstrap 5 `Badge <https://getbootstrap.com/docs/5.3/components/badge/>`_
 documentation.
 
+Re-usable component example
+===========================
+
+**djangocms-frontend** plugins can be used as components. They can be
+used in all your project's templates. Example (if key word arguments are
+skipped they fall back to their defaults):
+
+.. code-block::
+
+    {% load frontend %}
+    {% plugin "badge" badge_text="My badge" badge_context="info" badge_pills=False %}
+        This content is ignored.
+    {% endplugin %}
+
+
+
 .. index::
     single: Card
     single: CardInner
@@ -149,6 +200,31 @@ Here is an example of the new card **Image overlay** feature:
 Also see Bootstrap 5 `Card <https://getbootstrap.com/docs/5.3/components/card/>`_
 documentation.
 
+Re-usable component example
+===========================
+
+**djangocms-frontend** plugins can be used as components. They can be
+used in all your project's templates. Example (if key word arguments are
+skipped they fall back to their defaults):
+
+.. code-block::
+
+    {% load frontend %}
+    {% plugin "card" card_alignment="center" card_outline="info"
+                     card_text_color="primary" card_full_height=True %}
+        {% plugin "cardinner" inner_type="card-header" text_alignment="start" %}
+            <h4>Card title</h4>
+        {% endplugin %}
+        {% plugin "cardinner" inner_type="card-body" text_alignment="center" %}
+            Some quick example text to build on the card title and make up the
+            bulk of the card's content.
+        {% endplugin %}
+        {% plugin "listgroupitem" %}An item{% endplugin %}
+        {% plugin "listgroupitem" %}A second item{% endplugin %}
+        {% plugin "listgroupitem" %}A third item{% endplugin %}
+    {% endplugin %}
+
+
 .. index::
     single: Carousel
 
@@ -239,6 +315,23 @@ For more information, see
     is registered and the logged in user has view permissions: A user will only
     see a destination if they can view it in the admin site.
 
+Re-usable component example
+===========================
+
+**djangocms-frontend** plugins can be used as components. They can be
+used in all your project's templates. Example (if key word arguments are
+skipped they fall back to their defaults):
+
+.. code-block::
+
+    {% load frontend %}
+    {% url 'some_view' as some_view %}
+    {% plugin "textlink" external_link=some_view link_type="btn" link_context="primary" link_outline=False %}
+        Click me!
+    {% endplugin %}
+
+
+
 ********************
 List group component
 ********************

docs/source/components.rst

@@ -439,3 +439,44 @@ the upper right corner:
 .. image::  screenshots/tab-error-indicator.png
 
 
+.. _components:
+
+Using frontend plugins as components in templates
+=================================================
+
+The plugins of **djangocms-frontend** can be used as components in your
+templates - even in apps that do not use or integrate with djanog CMS
+otherwise. This is useful if you want use exactly the same markup for, say,
+buttons, links, the grid both in pages managed with django CMS and in
+other parts of your project.
+
+This allows you to keep one set of templates for your django CMS frontend
+plugins and any changes to those templates will be reflected in all parts
+of your project.
+
+To use a frontend plugin in a template you need to load the ``frontend`` tags
+and then use the ``plugin`` template tag to render a frontend plugin.
+
+.. code::
+
+    {% load frontend %}
+    {% plugin "alert" alert_context="secondary" alert_dismissable=True %}
+        Here goes the content of the alert.
+    {% endplugin %}
+
+The plugins will be rendered based on their standard attribute settings.
+You can override these settings by passing them as keyword arguments to the
+``plugin`` template tag.
+
+See the documentation of the djanog CMS plugins for examples of how to use
+the ``{% plugin %}`` template tag with each plugin.
+
+.. note::
+
+    While this is designed for **djangocms-frontend** plugins primarily, it
+    will work with most django CMS plugins.
+
+    Since no plugins are created in the database, plugins relying on their
+    instances being available in the database will potentially not work.
+    This especially is true for plugins that have a foreign key to
+    other models.