Allow custom footnote reference rendering (torchbox#70)

* Allow custom footnote reference rendering

This change does two things to permit custom rendering of footnote references in the `RichTextBlockWithFootnotes` block:

1. Moves reference rendering from an inner function in the `replace_footnote_tags()` method to a separate `render_footnote_tag()` method on the `RichTextBlockWithFootnotes` block class. This provides an easy extension point for subclasses of `RichTextBlockWithFootnotes` to customize rendering that doesn't require duplication of a lot of other code.
2. The default implementation of `render_footnote_tag` renders using a Django template, optionally set with the `WAGTAIL_FOOTNOTES_REFERENCE_TEMPLATE` setting, allowing users to override rendering by providing a different template to that setting.

This is similar in spirit to @an-ant0ni0's proposal in torchbox#27, however we've chosen to move rendering out of Python f-strings altogether and into Django (or any other configured engine's) templates.

.github/workflows/ruff.yml

@@ -15,7 +15,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
-    - run: python -Im pip install --user ruff
+    - run: python -Im pip install --user ruff==0.5.0
 
     - name: Run ruff
-      run: ruff --output-format=github wagtail_footnotes
+      run: ruff check --output-format=github wagtail_footnotes

.pre-commit-config.yaml

@@ -18,7 +18,7 @@ repos:
     - id: end-of-file-fixer
     - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.3.7'
+    rev: 'v0.5.0'
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

README.md

@@ -124,6 +124,10 @@ WAGTAILADMIN_RICH_TEXT_EDITORS = {
   - Default: `["bold", "italic", "link"]`
   - Use this to update a list of Rich Text features allowed in the footnote text.
 
+- `WAGTAIL_FOOTNOTES_REFERENCE_TEMPLATE`
+  - Default: `"wagtail_footnotes/includes/footnote_reference.html"`
+  - Use this to set a template that renders footnote references. The template receives the footnote `index` in its context.
+
 ## 🌍 Internationalisation
 
 Wagtail Footnotes can be translated. Note that in a multi-lingual setup, the URL setup for footnotes

tests/templates/test/endnote_reference.html

@@ -0,0 +1 @@
+<a href="#endnote-{{ index }}" id="endnote-source-{{ index }}"><sup>{{ index }}</sup></a>

tests/test/test_blocks.py

@@ -1,6 +1,6 @@
 import json
 
-from django.test import TestCase
+from django.test import TestCase, override_settings
 from wagtail import blocks
 from wagtail.fields import StreamBlock
 from wagtail.models import Page
@@ -104,12 +104,29 @@ def test_block_replace_footnote_render_basic(self):
         context = self.test_page_with_footnote.get_context(self.client.get("/"))
         out = rtb.render_basic(value, context=context)
         result = '<p>This is a paragraph with a footnote. <a href="#footnote-1" id="footnote-source-1"><sup>[1]</sup></a></p>'
-        self.assertEqual(out, result)
+        self.assertHTMLEqual(out, result)
 
     def test_block_replace_footnote_render(self):
         rtb = self.test_page_with_footnote.body.stream_block.child_blocks["paragraph"]
         value = rtb.get_prep_value(self.test_page_with_footnote.body[0].value)
         context = self.test_page_with_footnote.get_context(self.client.get("/"))
         out = rtb.render(value, context=context)
         result = '<p>This is a paragraph with a footnote. <a href="#footnote-1" id="footnote-source-1"><sup>[1]</sup></a></p>'
-        self.assertEqual(out, result)
+        self.assertHTMLEqual(out, result)
+
+    def test_render_footnote_tag(self):
+        block = RichTextBlockWithFootnotes()
+        html = block.render_footnote_tag(2)
+        self.assertHTMLEqual(
+            html, '<a href="#footnote-2" id="footnote-source-2"><sup>[2]</sup></a>'
+        )
+
+    @override_settings(
+        WAGTAIL_FOOTNOTES_REFERENCE_TEMPLATE="test/endnote_reference.html"
+    )
+    def test_render_footnote_tag_new_template(self):
+        block = RichTextBlockWithFootnotes()
+        html = block.render_footnote_tag(2)
+        self.assertHTMLEqual(
+            html, '<a href="#endnote-2" id="endnote-source-2"><sup>2</sup></a>'
+        )

wagtail_footnotes/blocks.py

@@ -1,6 +1,8 @@
 import re
 
+from django.conf import settings
 from django.core.exceptions import ValidationError
+from django.template.loader import get_template
 from django.utils.safestring import mark_safe
 from wagtail.blocks import RichTextBlock
 from wagtail.models import Page
@@ -25,6 +27,15 @@ def __init__(self, **kwargs):
         if "footnotes" not in self.features:
             self.features.append("footnotes")
 
+    def render_footnote_tag(self, index):
+        template_name = getattr(
+            settings,
+            "WAGTAIL_FOOTNOTES_REFERENCE_TEMPLATE",
+            "wagtail_footnotes/includes/footnote_reference.html",
+        )
+        template = get_template(template_name)
+        return template.render({"index": index})
+
     def replace_footnote_tags(self, value, html, context=None):
         if context is None:
             new_context = self.get_context(value)
@@ -47,7 +58,7 @@ def replace_tag(match):
             except (KeyError, ValidationError):
                 return ""
             else:
-                return f'<a href="#footnote-{index}" id="footnote-source-{index}"><sup>[{index}]</sup></a>'
+                return self.render_footnote_tag(index)
 
         # note: we return safe html
         return mark_safe(FIND_FOOTNOTE_TAG.sub(replace_tag, html))  # noqa: S308

wagtail_footnotes/templates/wagtail_footnotes/includes/footnote_reference.html

@@ -0,0 +1 @@
+<a href="#footnote-{{ index }}" id="footnote-source-{{ index }}"><sup>[{{ index }}]</sup></a>