django-template-partials

为Django模板语言提供可重用的命名内联部分。

观看讲座

我在爱丁堡的DjangoCon Europe 2023演讲中介绍了 django-template-partials。

要快速了解，您可以在YouTube上观看视频。🍿

安装

使用pip安装

pip install django-template-partials

然后将其添加到 INSTALLED_APPS，您就可以开始了。

INSTALLED_APPS = [
    "template_partials",
    ...,
]

有关更多选项，请参阅 高级配置（见下文）。

如果您是从旧版本升级，请参阅 变更日志。

基本用法

安装后，加载 partials 标签，并在模板顶部定义一个可重用的部分

{% load partials %}

{% partialdef test-partial %}
TEST-PARTIAL-CONTENT
{% endpartialdef %}

为了提高可读性，您可以可选地将名称添加到您的 {% endblock %} 标签中。例如

{% load partials %}

{% partialdef test-partial %}
TEST-PARTIAL-CONTENT
{% endpartialdef test-partial %}

片段重用

定义部分后，您可以在稍后多次重用它

{% block main %}
BEGINNING
{% partial test-partial %}
MIDDLE
{% partial test-partial %}
END
{% endblock main %}

部分内容将在每次使用命名的部分时渲染。

通过模板加载器

django-template-partials 也与模板加载器集成，因此您可以将模板和部分名称传递给加载器以仅渲染该部分

# In view handler…
self.template_name = "example.html#test-partial"

您的视图逻辑的其他部分保持不变。

这意味着您也可以使用部分与 include 标签一起使用

{% include "example.html#test-partial" %}

内联输出

您可能想包裹页面上的现有部分，并在部分内继续渲染内容，在这种情况下，请使用 inline 参数

{% block main %}
{% partialdef inline-partial inline=True %}
CONTENT
{% endpartialdef %}
{% endblock main %}

控制上下文

使用当前上下文渲染模板部分。

这意味着它在循环中等预期的情况下工作

{% for object in object_list %}
    {% partial test-partial %}
{% endfor %}

如果您需要调整上下文，请像平常一样使用with标签

{% with name=value othername=othervalue %}
    {% partial test-partial %}
{% endwith %}

捕获输出

渲染部分——比如分页小部件——可能计算成本很高。

django-template-partials不捕获生成的HTML到上下文，但其他选项存在，例如Slipper的库片段标签，它允许这种行为。

将部分添加到模板内置

也许您不想在每个模板中加载部分标签...

{% load partials %}

Django模板语言的选项允许您为每个模板加载的内置内容添加。您可以在那里添加部分标签

OPTIONS = {
    "builtins": ["template_partials.templatetags.partials"],
}

这就是基础。祝您玩得开心！🚀

高级配置

默认情况下，将"template_partials"添加到您的INSTALLED_APPS将配置任何Django模板后端使用部分模板加载器。

如果您需要控制这种行为，您可以使用替代的SimpleAppConfig，它将不会调整您的TEMPLATES设置

INSTALLED_APPS = [
    "template_partials.apps.SimpleAppConfig",
    ...,
]

如果您使用SimpleAppConfig，您需要自己配置模板加载器。

有一个wrap_loaders()函数可用，并且可以用来配置任何特定的模板引擎实例与模板部分加载器。

您可以使用后端的NAME来调用wrap_loaders()以仅为此后端添加部分加载器

from template_partials.apps import wrap_loaders

TEMPLATES = [
    ...,
    {
        "BACKEND": "...",
        "NAME": "myname",
        "OPTIONS": {
           ...,
        },
    },
    ...,
]

wrap_loaders("myname")

如果没有提供NAME，则使用BACKEND值的倒数第二个元素——例如，"django.template.backends.django.DjangoTemplates"将相当于一个NAME为"django"。

在底层，wrap_loaders()相当于显式定义loaders。假设默认值...

from django.conf import settings

default_loaders = [
    "django.template.loaders.filesystem.Loader",
    "django.template.loaders.app_directories.Loader",
]
cached_loaders = [("django.template.loaders.cached.Loader", default_loaders)]
partial_loaders = [("template_partials.loader.Loader", cached_loaders)]

settings.TEMPLATES[...]['OPTIONS']['loaders'] = partial_loaders

…其中TEMPLATES[...]是TEMPLATES中与传递给wrap_loaders()的NAME匹配的条目。

运行测试

分支，然后克隆存储库

git clone git@github.com:your-username/django-template-partials.git

设置venv

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .[tests]

然后您可以使用just命令运行程序来运行测试

just test

或者使用覆盖率

just coverage

如果您没有安装just，您可以在justfile中查看要运行的命令。