Python Django Library.inclusion_tag用法及代码示例

本文介绍 django.template.Library.inclusion_tag 的用法。

声明

django.template.Library.inclusion_tag()

另一种常见的模板标签类型是通过渲染another模板来显示一些数据的类型。例如，Django 的管理接口使用自定义模板标签来显示 “add/change” 表单页面底部的按钮。这些按钮看起来总是一样的，但链接目标会根据正在编辑的对象而变化——因此它们是使用填充了当前对象详细信息的小模板的完美案例。 (在管理员的情况下，这是submit_row 标签。)

这些类型的标签称为“inclusion tags”。

编写包含标签可能最好通过示例来演示。让我们编写一个标签，输出给定 Poll 对象的选项列表，例如在教程中创建的对象。我们将像这样使用标签：

{% show_results poll %}

…输出将是这样的：

<ul>
  <li>First choice</li>
  <li>Second choice</li>
  <li>Third choice</li>
</ul>

首先，定义接受参数并为结果生成数据字典的函数。这里重要的一点是我们只需要返回一个字典，而不是更复杂的东西。这将用作模板片段的模板上下文。例子：

def show_results(poll):
    choices = poll.choice_set.all()
    return {'choices': choices}

接下来，创建用于呈现标签输出的模板。这个模板是标签的一个固定特性：标签编写者指定它，而不是模板设计者。按照我们的示例，模板非常短：

<ul>
{% for choice in choices %}
    <li> {{ choice }} </li>
{% endfor %}
</ul>

现在，通过在Library 对象上调用inclusion_tag() 方法来创建和注册包含标记。按照我们的示例，如果上述模板位于模板加载器搜索的目录中名为 results.html 的文件中，我们将像这样注册标签：

# Here, register is a django.template.Library instance, as before
@register.inclusion_tag('results.html')
def show_results(poll):
    ...

或者，可以使用 django.template.Template 实例注册包含标签：

from django.template.loader import get_template
t = get_template('results.html')
register.inclusion_tag(t)(show_results)

…当第一次创建函数时。

有时，您的包含标签可能需要大量参数，这让模板作者很难传入所有参数并记住它们的顺序。为了解决这个问题，Django 为包含标签提供了一个takes_context 选项。如果您在创建模板标记时指定takes_context，则该标记将没有必需的参数，并且底层 Python 函数将有一个参数 - 调用标记时的模板上下文。

例如，假设您正在编写一个包含标记，该标记将始终在包含指向主页的 home_link 和 home_title 变量的上下文中使用。这是 Python 函数的样子：

@register.inclusion_tag('link.html', takes_context=True)
def jump_link(context):
    return {
        'link': context['home_link'],
        'title': context['home_title'],
    }

请注意，函数 must 的第一个参数称为 context 。

在register.inclusion_tag() 行中，我们指定了takes_context=True 和模板的名称。以下是模板link.html 的样子：

Jump directly to <a href="{{ link }}">{{ title }}</a>.

然后，任何时候您想使用该自定义标签，加载它的库并在没有任何参数的情况下调用它，如下所示：

{% jump_link %}

请注意，当您使用 takes_context=True 时，无需将参数传递给模板标签。它会自动访问上下文。

takes_context 参数默认为 False 。当它设置为 True 时，标签被传递给上下文对象，如本例所示。这是本案例与之前的 inclusion_tag 示例之间的唯一区别。

inclusion_tag 函数可以接受任意数量的位置或关键字参数。例如：

@register.inclusion_tag('my_template.html')
def my_tag(a, b, *args, **kwargs):
    warning = kwargs['warning']
    profile = kwargs['profile']
    ...
    return ...

然后在模板中，可以将任意数量的以空格分隔的参数传递给模板标签。与 Python 一样，关键字参数的值使用等号(“=”)设置，并且必须在位置参数之后提供。例如：

{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}