Add django_hooks for template hooks (#4395)

frankduncan · frjo · web-flow · commit 6a76e6dc4565 · 2025-03-06T15:09:49.000+01:00
This is pulled from https://github.com/nitely/django-hooks with everything except the template hooks removed. This is the first of three PRs, adding the infrastructure needed to add django style hooks inside templates. The hooks in templates look like: ``` {% hook 'hook_name' %} ``` where `hook_name` is defined somewhere else via: ``` from django.template.loader import render_to_string # Code that loads a template def my_extension_for_hook_name(context, *args, **kwargs): return render_to_string( "my_extension_for_hook_name.html", context.flatten(), ) class MyApp(AppConfig): def ready(self): from extensions.django_hooks.templatehook import hook hook.register("hypha_extension_head", my_extension_for_hook_name) ``` --------- Co-authored-by: Fredrik Jonsson <frjo@xdeb.org>
diff --git a/docs/references/template-hooks.md b/docs/references/template-hooks.md
@@ -0,0 +1,93 @@
+# TemplateHook
+
+Adding a hook-point in `main_app`'s template:
+
+
+    # my_main_app/templates/_base.html
+
+    { % load hooks_tags %}
+
+    <!DOCTYPE html>
+    <html>
+      <head>
+        …
+
+        { % hook 'within_head' %}
+
+        …
+      </head>
+    </html>
+
+**Tip**
+
+Here we are adding a *hook-point* called `within_head` where
+*third-party* apps will be able to insert their code.
+
+Creating a hook listener in a `third_party_app`:
+
+    # third_party_app/template_hooks.py
+
+    from django.template.loader import render_to_string
+    from django.utils.html import mark_safe, format_html
+
+
+    # Example 1
+    def css_resources(context, *args, **kwargs):
+        return mark_safe(u'<link rel="stylesheet" href="%s/app_hook/styles.css">' % settings.STATIC_URL)
+
+
+    # Example 2
+    def user_about_info(context, *args, **kwargs):
+        user = context['request'].user
+        return format_html(
+            "<b>{name}</b> {last_name}: {about}",
+            name=user.first_name,
+            last_name=user.last_name,
+            about=mark_safe(user.profile.about_html_field)  # Some safe (sanitized) html data.
+        )
+
+
+    # Example 3
+    def a_more_complex_hook(context, *args, **kwargs):
+        # If you are doing this a lot, make sure to keep your templates in memory (google: django.template.loaders.cached.Loader)
+        return render_to_string(
+            template_name='templates/app_hook/head_resources.html',
+            context_instance=context
+        )
+
+
+    # Example 4
+    def an_even_more_complex_hook(context, *args, **kwargs):
+        articles = Article.objects.all()
+        return render_to_string(
+            template_name='templates/app_hook/my_articles.html',
+            dictionary={'articles': articles, },
+            context_instance=context
+        )
+
+Registering a hook listener in a `third_party_app`:
+
+    # third_party_app/apps.py
+
+    from django.apps import AppConfig
+
+
+    class MyAppConfig(AppConfig):
+
+        name = 'myapp'
+        verbose_name = 'My App'
+
+        def ready(self):
+            from hooks.templatehook import hook
+            from third_party_app.template_hooks import css_resources
+
+            hook.register("within_head", css_resources)
+
+**Tip**
+
+Where to register your hooks:
+
+Use `AppConfig.ready()`:
+[docs](https://docs.djangoproject.com/en/1.8/ref/applications/#django.apps.AppConfig.ready)
+and
+[example](http://chriskief.com/2014/02/28/django-1-7-signals-appconfig/)
diff --git a/hypha/core/templatehook.py b/hypha/core/templatehook.py
@@ -0,0 +1,150 @@
+# Adds the ability to have hooks injected into templates, via the `hooks_tags.hook` template tag.
+#
+# Originally from https://github.com/nitely/django-hooks but after culling everything except
+# the template hook.  See /docs/templatehook.rst for more information
+#
+# The reason this was forked, rather than used as a module, is that the last commit from the
+# other project was made in 2015, and can no longer be imported into a modern django project.
+# The template hook continues to work correctly, but the other hooks most likely do not, and
+# so were removed.
+
+
+class TemplateHook(object):
+    """
+    A hook for templates. This can be used directly or\
+    through the :py:class:`Hook` dispatcher
+
+    :param list providing_args: A list of the arguments\
+    this hook can pass along in a :py:func:`.__call__`
+    """
+
+    def __init__(self, providing_args=None):
+        self.providing_args = providing_args or []
+        self._registry = []
+
+    def __call__(self, *args, **kwargs):
+        """
+        Collect all callbacks responses for this template hook
+
+        :return: Responses by registered callbacks,\
+        this is usually a list of HTML strings
+        :rtype: list
+        """
+        return [func(*args, **kwargs) for func in self._registry]
+
+    def register(self, func):
+        """
+        Register a new callback
+
+        :param callable func: A function reference used as a callback
+        """
+        assert callable(func), "Callback func must be a callable"
+
+        self._registry.append(func)
+
+    def unregister(self, func):
+        """
+        Remove a previously registered callback
+
+        :param callable func: A function reference\
+        that was registered previously
+        """
+        try:
+            self._registry.remove(func)
+        except ValueError:
+            pass
+
+    def unregister_all(self):
+        """
+        Remove all callbacks
+        """
+        del self._registry[:]
+
+
+class Hook(object):
+    """
+    Dynamic dispatcher (proxy) for :py:class:`TemplateHook`
+    """
+
+    def __init__(self):
+        self._registry = {}
+
+    def __call__(self, name, *args, **kwargs):
+        """
+        Collect all callbacks responses for this template hook.\
+        The hook (name) does not need to be pre-created,\
+        it may not exist at call time
+
+        :param str name: Hook name, it must be unique,\
+        prefixing it with the app label is a good idea
+        :return: Responses by registered callbacks
+        :rtype: list
+        """
+        try:
+            templatehook = self._registry[name]
+        except KeyError:
+            return []
+
+        return templatehook(*args, **kwargs)
+
+    def _register(self, name):
+        """
+        @Api private
+        Add new :py:class:`TemplateHook` into the registry
+
+        :param str name: Hook name
+        :return: Instance of :py:class:`TemplateHook`
+        :rtype: :py:class:`TemplateHook`
+        """
+        templatehook = TemplateHook()
+        self._registry[name] = templatehook
+        return templatehook
+
+    def register(self, name, func):
+        """
+        Register a new callback.\
+        When the name/id is not found\
+        a new hook is created under its name,\
+        meaning the hook is usually created by\
+        the first registered callback
+
+        :param str name: Hook name
+        :param callable func: A func reference (callback)
+        """
+        try:
+            templatehook = self._registry[name]
+        except KeyError:
+            templatehook = self._register(name)
+
+        templatehook.register(func)
+
+    def unregister(self, name, func):
+        """
+        Remove a previously registered callback
+
+        :param str name: Hook name
+        :param callable func: A function reference\
+        that was registered previously
+        """
+        try:
+            templatehook = self._registry[name]
+        except KeyError:
+            return
+
+        templatehook.unregister(func)
+
+    def unregister_all(self, name):
+        """
+        Remove all callbacks
+
+        :param str name: Hook name
+        """
+        try:
+            templatehook = self._registry[name]
+        except KeyError:
+            return
+
+        templatehook.unregister_all()
+
+
+hook = Hook()
diff --git a/hypha/core/templatetags/hooks_tags.py b/hypha/core/templatetags/hooks_tags.py
@@ -0,0 +1,62 @@
+from django import template
+from django.utils.html import format_html_join
+
+from hypha.core.templatehook import hook
+
+register = template.Library()
+
+
+@register.simple_tag(name="hook", takes_context=True)
+def hook_tag(context, name, *args, **kwargs):
+    r"""
+    Hook tag to call within templates
+
+    :param dict context: This is automatically passed,\
+    contains the template state/variables
+    :param str name: The hook which will be dispatched
+    :param \*args: Positional arguments, will be passed to hook callbacks
+    :param \*\*kwargs: Keyword arguments, will be passed to hook callbacks
+    :return: A concatenation of all callbacks\
+    responses marked as safe (conditionally)
+    :rtype: str
+    """
+    return format_html_join(
+        sep="\n",
+        format_string="{}",
+        args_generator=(
+            (response,) for response in hook(name, context, *args, **kwargs)
+        ),
+    )
+
+
+def template_hook_collect(module, hook_name, *args, **kwargs):
+    r"""
+    Helper to include in your own templatetag, for static TemplateHooks
+
+    Example::
+
+        import myhooks
+        from hooks.templatetags import template_hook_collect
+
+        @register.simple_tag(takes_context=True)
+        def hook(context, name, *args, **kwargs):
+            return template_hook_collect(myhooks, name, context, *args, **kwargs)
+
+    :param module module: Module containing the template hook definitions
+    :param str hook_name: The hook name to be dispatched
+    :param \*args: Positional arguments, will be passed to hook callbacks
+    :param \*\*kwargs: Keyword arguments, will be passed to hook callbacks
+    :return: A concatenation of all callbacks\
+    responses marked as safe (conditionally)
+    :rtype: str
+    """
+    try:
+        templatehook = getattr(module, hook_name)
+    except AttributeError:
+        return ""
+
+    return format_html_join(
+        sep="\n",
+        format_string="{}",
+        args_generator=((response,) for response in templatehook(*args, **kwargs)),
+    )
