From 15b55aa535060ea4ab710212b60a1ae04c45ad1c Mon Sep 17 00:00:00 2001 From: Will Barton Date: Tue, 13 Aug 2024 05:16:29 -0400 Subject: [PATCH] Allow custom footnote reference rendering (#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 #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 | 4 ++-- .pre-commit-config.yaml | 2 +- README.md | 4 ++++ tests/templates/test/endnote_reference.html | 1 + tests/test/test_blocks.py | 23 ++++++++++++++++--- wagtail_footnotes/blocks.py | 13 ++++++++++- .../includes/footnote_reference.html | 1 + 7 files changed, 41 insertions(+), 7 deletions(-) create mode 100644 tests/templates/test/endnote_reference.html create mode 100644 wagtail_footnotes/templates/wagtail_footnotes/includes/footnote_reference.html diff --git a/.github/workflows/ruff.yml b/.github/workflows/ruff.yml index 1f9008b..903e5f3 100644 --- a/.github/workflows/ruff.yml +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 3480c91..b624374 100644 --- a/.pre-commit-config.yaml +++ b/.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] diff --git a/README.md b/README.md index 37c57ba..ed73c83 100644 --- a/README.md +++ b/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 diff --git a/tests/templates/test/endnote_reference.html b/tests/templates/test/endnote_reference.html new file mode 100644 index 0000000..b4b31b9 --- /dev/null +++ b/tests/templates/test/endnote_reference.html @@ -0,0 +1 @@ +{{ index }} diff --git a/tests/test/test_blocks.py b/tests/test/test_blocks.py index ade57f0..85e4492 100644 --- a/tests/test/test_blocks.py +++ b/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,7 +104,7 @@ 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 = '

This is a paragraph with a footnote. [1]

' - 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"] @@ -112,4 +112,21 @@ def test_block_replace_footnote_render(self): context = self.test_page_with_footnote.get_context(self.client.get("/")) out = rtb.render(value, context=context) result = '

This is a paragraph with a footnote. [1]

' - 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, '[2]' + ) + + @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, '2' + ) diff --git a/wagtail_footnotes/blocks.py b/wagtail_footnotes/blocks.py index 1211b9e..315fbc6 100644 --- a/wagtail_footnotes/blocks.py +++ b/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'[{index}]' + return self.render_footnote_tag(index) # note: we return safe html return mark_safe(FIND_FOOTNOTE_TAG.sub(replace_tag, html)) # noqa: S308 diff --git a/wagtail_footnotes/templates/wagtail_footnotes/includes/footnote_reference.html b/wagtail_footnotes/templates/wagtail_footnotes/includes/footnote_reference.html new file mode 100644 index 0000000..86810ae --- /dev/null +++ b/wagtail_footnotes/templates/wagtail_footnotes/includes/footnote_reference.html @@ -0,0 +1 @@ +[{{ index }}]