fix: allow intuitive template paths in custom CMS apps

README.md

@@ -194,6 +194,7 @@ To contribute, first read [How to Contirbute][Contributing].
 | `python manage.py collectstatic` | [django](https://docs.djangoproject.com/en/3.2/howto/static-files/)
 | `python manage.py createsuperuser` | [django cms](https://docs.django-cms.org/en/release-3.8.x/how_to/install.html#admin-user), [django](https://docs.djangoproject.com/en/3.2/ref/django-admin/#createsuperuser)
 
+
 <!-- Link Aliases -->
 
 [Camino]: https://github.com/TACC/Camino

package.json

@@ -21,6 +21,6 @@
   },
   "homepage": "https://github.com/TACC/Core-CMS",
   "devDependencies": {
-    "@tacc/core-styles": "^2.45.0"
+    "@tacc/core-styles": "^2.46.2"
   }
 }

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "tacc-core-cms-backend"
-version = "4.35.0"
+version = "4.36.3"
 description = "DjangoCMS backend for the TACC ACI-WMA Core-CMS Codebase."
 authors = ["TACC-WMA <wma-portals@tacc.utexas.edu>"]
 
@@ -45,9 +45,7 @@ djangocms-admin-style = "~3.2.6"
 djangocms-apphook-setup = "0.4.1"
 djangocms-attributes-field = "2.1.0"
 djangocms-blog = "^1.2"
-# TO get a commit in main (since v3.0.1) to fix Container error
-# https://github.com/django-cms/djangocms-bootstrap4/pull/164
-djangocms-bootstrap4 = {git = "https://github.com/django-cms/djangocms-bootstrap4.git", rev = "49983f4"}
+djangocms-bootstrap4 = "^3.0"
 djangocms-column = "^2.0"
 djangocms-file = "3.0.0"
 djangocms-forms-maintained = { git = "https://github.com/TACC/djangocms-forms", rev = "6b59ff366495915f06f4d6fac01a2f0aa9efecaf" }

taccsite_cms/apps.py

@@ -1,7 +1,10 @@
 import logging
+
 from django.apps import AppConfig
 from django.db.models.signals import post_migrate
 
+from .djangocms_picture.extend import extendPicturePlugin
+
 logger = logging.getLogger(f"portal.{__name__}")
 
 class TaccsiteCmsConfig(AppConfig):
@@ -10,6 +13,7 @@ class TaccsiteCmsConfig(AppConfig):
 
     def ready(self):
         post_migrate.connect(self.create_groups, sender=self)
+        extendPicturePlugin()
 
     def create_groups(self, sender, **kwargs):
         from django.contrib.auth.models import Group

taccsite_cms/djangocms_picture/extend.py

@@ -0,0 +1,163 @@
+def extendPicturePlugin():
+    from django.utils.translation import gettext_lazy as _
+
+    from cms.plugin_pool import plugin_pool
+
+    ZOOM_TEMPLATE_NAME = 'zoom_effect'
+    ZOOM_TEMPLATE_LABEL = 'Zoom image on hover'
+    ZOOM_TEMPLATE_NOTE = _('The "%(zoom_template_label)s" templates only have effect if Image either has a Link or is within a Link.') % {"zoom_template_label": ZOOM_TEMPLATE_LABEL}
+    ZOOM_TEMPLATE_ERROR = _(' "%(zoom_template_label)s" templates require Image to either have a Link or be within a Link.') % {"zoom_template_label": ZOOM_TEMPLATE_LABEL}
+
+    LINK_TEMPLATE_NAME = 'no_link_to_ext_image'
+
+    def add_help_text(form_instance):
+        """Adds help text for: 'Template' field"""
+
+        if 'template' in form_instance.fields:
+            form_instance.fields['template'].help_text += _(' %(ZOOM_TEMPLATE_NOTE)s') % {"ZOOM_TEMPLATE_NOTE": ZOOM_TEMPLATE_NOTE}
+
+    def whether_to_render_link(instance):
+        has_explicit_link = bool(instance.link_url or instance.link_page_id)
+        # FAQ: The djangocms_picture has "feature" such that an image with
+        #      "External image" URL will automatically link to that resource
+        has_implicit_link = bool(instance.get_link()) and not has_explicit_link
+
+        allow_implicit_link = not LINK_TEMPLATE_NAME in instance.template
+
+        if has_explicit_link or (has_implicit_link and allow_implicit_link):
+            return True
+
+        return False
+
+    def validate_zoom_template(instance):
+        """Validates: 'Template' field choice 'Zoom image …'"""
+        from django.core.exceptions import ValidationError
+        from djangocms_link.cms_plugins import LinkPlugin
+
+        errors = {}
+
+        would_render_link = whether_to_render_link(instance)
+        should_add_zoom_effect = ZOOM_TEMPLATE_NAME in instance.template
+        parent_plugin = instance.parent.get_plugin_instance()[0] if instance.parent else None
+        is_in_link = instance.parent.plugin_type == 'LinkPlugin' if instance.parent else False
+
+        if (should_add_zoom_effect and not would_render_link and not is_in_link):
+            errors['template'] = ZOOM_TEMPLATE_ERROR
+
+        if errors:
+            raise ValidationError(errors)
+
+    def get_more_context_variables(instance):
+        """
+        Calculate boolean context variables to simplify template logic.
+        Returns a dictionary of context variables.
+        """
+        # Figure/Caption
+        has_caption_text = bool(instance.caption_text)
+        has_child_plugins = bool(instance.child_plugin_instances)
+        has_figure_content = has_caption_text or has_child_plugins
+
+        # Template
+        is_zoom_template = ZOOM_TEMPLATE_NAME in instance.template
+
+        # Link
+        should_render_link = whether_to_render_link(instance)
+
+        # Zoom Effect
+        should_add_zoom_effect = is_zoom_template
+        should_wrap_image_for_zoom = (
+            should_add_zoom_effect and
+            (has_figure_content or not should_render_link)
+        )
+        should_add_zoom_class_to_link = (
+            should_add_zoom_effect and
+            should_render_link and
+            not has_figure_content
+        )
+
+        # Attributes
+        should_add_attributes_to_image = (
+            not has_figure_content and
+            not should_render_link
+        )
+
+        return {
+            'should_render_link': should_render_link,
+            'has_figure_content': has_figure_content,
+            'should_wrap_image_for_zoom': should_wrap_image_for_zoom,
+            'should_add_zoom_class_to_link': should_add_zoom_class_to_link,
+            'should_add_attributes_to_image': should_add_attributes_to_image,
+        }
+
+
+    # djangocms_picture
+    from djangocms_picture.cms_plugins import PicturePlugin as OriginalPicturePlugin
+    from djangocms_picture.models import Picture as OriginalPicture
+
+    class PicturePluginForm(OriginalPicturePlugin.form):
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, **kwargs)
+            add_help_text(self)
+
+    class PicturePluginModel(OriginalPicture):
+        class Meta:
+            proxy = True
+
+        def clean(self):
+            super().clean()
+            validate_zoom_template(self)
+
+    class PicturePlugin(OriginalPicturePlugin):
+        model = PicturePluginModel
+        form = PicturePluginForm
+        name = 'Image'
+
+        def render(self, context, instance, placeholder):
+            context = super().render(context, instance, placeholder)
+
+            more_context = get_more_context_variables(instance)
+            context.update(more_context)
+
+            return context
+
+    # To support generic Image plugin without uninstalling Bootstrap's
+    # FAQ: Had been done cuz Image plugin had percieved use cases,
+    #      but is since not regularly used, but is used, thus maintained
+    # FAQ: No need to unregister cuz Bootstrap4PicturePlugin does that
+    # https://github.com/django-cms/djangocms-bootstrap4/blob/3.0.0/djangocms_bootstrap4/contrib/bootstrap4_picture/cms_plugins.py#L54
+    # plugin_pool.unregister_plugin(OriginalPicturePlugin)
+    plugin_pool.register_plugin(PicturePlugin)
+
+
+    # djangocms_bootstrap4: bootstrap4_picture
+    from djangocms_bootstrap4.contrib.bootstrap4_picture.cms_plugins import Bootstrap4PicturePlugin as OriginalBootstrap4PicturePlugin
+    from djangocms_bootstrap4.contrib.bootstrap4_picture.models import Bootstrap4Picture as OriginalBootstrap4Picture
+
+    class Bootstrap4PictureForm(OriginalBootstrap4PicturePlugin.form):
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, **kwargs)
+            add_help_text(self)
+
+    class Bootstrap4PictureModel(OriginalBootstrap4Picture):
+        class Meta:
+            proxy = True
+
+        def clean(self):
+            super().clean()
+            validate_zoom_template(self)
+
+    class Bootstrap4PicturePlugin(OriginalBootstrap4PicturePlugin):
+        model = Bootstrap4PictureModel
+        form = Bootstrap4PictureForm
+        name = 'Picture / Image (Responsive)'
+
+        def render(self, context, instance, placeholder):
+            context = super().render(context, instance, placeholder)
+
+            more_context = get_more_context_variables(instance)
+            context.update(more_context)
+
+            return context
+
+    plugin_pool.unregister_plugin(OriginalBootstrap4PicturePlugin)
+    plugin_pool.register_plugin(Bootstrap4PicturePlugin)

taccsite_cms/management/commands/README.md

@@ -2,6 +2,7 @@
 
 - [How to Use](#how-to-use)
 - [List Pages Using Each Template](#list-pages-using-each-template)
+- [List Pages Using Plugins](#list-pages-using-plugins)
 - [Set Groups & Permissions](#set-groups--permissions)
 - [Reference](#reference)
 
@@ -25,6 +26,21 @@ Usage:
 python manage.py list_page_templates
 ```
 
+## List Pages Using Plugins
+
+This command lists all pages that use a specific plugin instance (given a plugin instance ID), along with the page's path.
+
+Usage:
+```sh
+python manage.py list_plugin_pages <plugin_instance_id> [<plugin_instance_id> ...]
+```
+
+Example:
+```sh
+python manage.py list_plugin_pages 42 99
+```
+
+
 ## Set Groups & Permissions
 
 Every file in [`group_perms/`](./group_perms) represents a group. Each group's intended usage is described at the top of its file. Permissions are set via function calls in each file.[^1]

taccsite_cms/management/commands/list_plugin_pages.py

@@ -0,0 +1,25 @@
+from django.core.management import BaseCommand
+from django.apps import apps
+
+class Command(BaseCommand):
+    help = 'Finds the page that uses a specific plugin instance by its ID'
+
+    def add_arguments(self, parser):
+        parser.add_argument('plugin_instance_ids', nargs='+', type=str)
+
+    def handle(self, *args, **options):
+        for plugin_instance_id in options['plugin_instance_ids']:
+            page = self.find_page_using_plugin_instance(plugin_instance_id)
+            if page:
+                self.stdout.write(f'Plugin instance ID {plugin_instance_id} is used on page: {page.get_path()}')
+            else:
+                self.stdout.write(f'No page found using plugin instance ID {plugin_instance_id}')
+
+    def find_page_using_plugin_instance(self, plugin_instance_id):
+        try:
+            CMSPlugin = apps.get_model('cms', 'CMSPlugin')
+            plugin_instance = CMSPlugin.objects.get(id=plugin_instance_id)
+            page = plugin_instance.placeholder.page if plugin_instance.placeholder else None
+            return page
+        except CMSPlugin.DoesNotExist:
+            return None