如何在Django/Wagtail中实现向base.html模板块追加内容？

问题背景 #

现有Django基础模板base.html定义了append_to_me块，需要在子模板、自定义模板标签、Wagtail块中，不受位置限制地向该块追加内容，同时避免覆盖原有内容。

现有模板与代码 #

• base.html：

<!DOCTYPE html>
<html>
    <head>
        <title>My Project</title>
        {% block append_to_me %}{% endblock %}
    </head>

    <body>
    {% block content %}{% endblock content %}
    </body>
</html>

• 子模板（继承自base.html）：

{% extends "base.html" %}

{% block content %}
    <h2>Content for My App</h2>
    <p>Stuff etc etc.</p>
    {# 希望不受使用位置限制 #}
    {% my_custom_tag %}
{% endblock content %}

• 自定义模板标签my_custom_tag：

@register.simple_tag(takes_context=True)
def my_custom_tag(context):
    objects = Preload.objects.all()
    for object in objects:
        append_to_header_block(object.html)

• Wagtail块及模板：

class MyBlock(blocks.StructBlock):
    title = blocks.CharBlock()
    content = blocks.RichTextBlock()

    class Meta:
        template = 'myapp/myblock.html'

{% add_to_header IMG "img/my-img.jpeg" %}
...

当前问题 #

1. 渲染顺序问题：base.html的append_to_me块可能先于子模板、标签、Wagtail块渲染，无法直接追加内容；
2. Wagtail块具有通用性，无法确定自身是否在继承base.html的模板中使用。

解决方案 #

1. 利用上下文存储待追加内容 #

核心思路是在模板渲染上下文里维护一个列表，临时存储所有需要追加到append_to_me块的内容，最后在base.html中统一渲染。

实现自定义的add_to_header模板标签，负责向上下文的列表中添加内容：

from django import template

register = template.Library()

@register.simple_tag(takes_context=True)
def add_to_header(context, *args):
    # 初始化上下文存储列表，避免不存在时报错
    if 'header_content' not in context:
        context['header_content'] = []
    # 根据传入参数生成对应HTML内容，可扩展其他类型
    if args[0] == 'IMG':
        img_html = f'<img src="{args[1]}" alt="" />'
        context['header_content'].append(img_html)
    return ''  # 标签无需输出内容

@register.simple_tag(takes_context=True)
def my_custom_tag(context):
    objects = Preload.objects.all()
    if 'header_content' not in context:
        context['header_content'] = []
    for obj in objects:
        context['header_content'].append(obj.html)
    return ''

2. 修改base.html渲染存储的内容 #

修改base.html中的append_to_me块，直接渲染上下文里存储的所有内容：

<!DOCTYPE html>
<html>
    <head>
        <title>My Project</title>
        {% block append_to_me %}
            {% if header_content %}
                {% for item in header_content %}
                    {{ item|safe }}
                {% endfor %}
            {% endif %}
        {% endblock %}
    </head>

    <body>
    {% block content %}{% endblock content %}
    </body>
</html>

使用|safe过滤器确保HTML内容能正确渲染，可根据实际需求调整是否保留该过滤器。

3. 处理Wagtail块的通用性问题 #

Wagtail块渲染时会自动继承父模板的上下文，因此无需修改Wagtail块的代码或模板。只要父模板（继承base.html的模板）渲染时上下文包含header_content列表，Wagtail块中的{% add_to_header %}标签就能正常向列表添加内容，最终在base.html中统一渲染。

若担心Wagtail块在非base.html模板中使用出错，add_to_header标签已做兼容处理——即使上下文没有header_content，也不会抛出异常，仅不添加内容，不影响块的通用性。

内容的提问来源于stack exchange，提问作者nigel239