Template--模板

模板引擎的支持

配置

模板引擎配置为TEMPLATES设置。这是一个配置列表，每个引擎一个，默认值为空。这是settings.py生成的，通过startproject命令定义了一个更有用的值：

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            # ... some options here ...
        },
    },
]

BACKEND是实现Django的模板后端API的模板引擎类的Python路径。内置后端是django.template.backends.django.DjangoTemplates和django.template.backends.jinja2.Jinja2.

由于大多数引擎从文件中加载模板，因此每个引擎的顶级配置包含两个公共设置：

• DIRS定义引擎应按搜索顺序查找模板源文件的目录列表。
• APP_DIRS告诉引擎是否应该在已安装的应用程序中查找模板。每个后端都为应用程序中的子目录定义了一个常规名称，其中应该存储其模板。

虽然不常见，但可以使用不同的选项配置相同后端的几个实例。在这种情况下，您应该定义一个唯一的NAME每个引擎。

OPTIONS包含特定于后端的设置。

使用

django.template.loader模块定义两个函数来加载模板。

get_template(template_name, using=None)

此函数用给定的名称加载模板，并返回Template对象。

返回值的确切类型取决于加载模板的后端。每个后端都有自己的Template类

get_template()按顺序尝试每个模板引擎，直到成功为止。如果找不到模板，则会引发TemplateDoesNotExist。如果找到模板但包含无效语法，则会引发TemplateSyntaxError.

模板的搜索和加载方式取决于每个引擎的后端和配置。

如果要将搜索限制在特定的模板引擎上，在using参数中传递该引擎的NAME.。

select_template(template_name_list, using=None)

select_template()就像get_template()，但它需要一个模板名称列表。它按顺序尝试每个名称，并返回存在的第一个模板。

如果加载模板失败，则可能引发在django.template中定义的两个异常：

 exception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)

当找不到模板时会引发此异常。它接受以下可选参数来填充 template postmortem 在调试页上：

backend

异常来源的模板后端实例

tried

在找到模板时尝试的源列表。它被格式化为包含以下内容的元组列表(origin, status)，其中origin是一个 origin-like 对象，status是一个字符串，其中的原因是没有找到模板。

chain

在尝试加载模板时，引发异常的中间 TemplateDoesNotExist 列表。这是 get_template()等函数所使用的，这些函数试图从多个引擎加载给定的模板。

 exception TemplateSyntaxError(msg)

当找到模板但包含错误时会引发此异常。

Template返回的对象get_template()和select_template()必须提供render()方法具有以下签名：

Template.render(context=None, request=None)

使用给定的context渲染此模板。

如果提供context，则必须是dict。如果没有提供，引擎将使用空的context渲染模板。

如果提供request，则必须是HttpRequest。然后引擎必须使它和CSRF令牌在模板中可用。如何实现这一点取决于每个后端。

这是一个搜索算法的例子。在本例中，TEMPLATES设置是：

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            '/home/html/example.com',
            '/home/html/default',
        ],
    },
    {
        'BACKEND': 'django.template.backends.jinja2.Jinja2',
        'DIRS': [
            '/home/html/jinja2',
        ],
    },
]

如果你调用get_template('story_detail.html')，以下是Django将查找的文件，顺序如下：

• /home/html/example.com/story_detail.html ('django'引擎)
• /home/html/default/story_detail.html ('django'引擎)
• /home/html/jinja2/story_detail.html ('jinja2'引擎)

如果你调用select_template(['story_253_detail.html', 'story_detail.html'])以下是Django将寻找的内容：

• /home/html/example.com/story_253_detail.html ('django'引擎)
• /home/html/default/story_253_detail.html ('django'引擎)
• /home/html/jinja2/story_253_detail.html ('jinja2'引擎)
• /home/html/example.com/story_detail.html ('django'引擎)
• /home/html/default/story_detail.html ('django'引擎)
• /home/html/jinja2/story_detail.html ('jinja2'引擎)

　　当Django找到一个存在的模板时，它将停止查找。

Tip

你可以用select_template()用于灵活的模板加载。例如，如果您已经编写了一个新闻故事，并且希望某些故事具有自定义模板，
请使用以下内容select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])。这将允许您对
单个故事使用自定义模板，对于没有自定义模板的故事使用回退模板。

在包含模板的每个目录内的子目录中整理模板是合理的，也是可取的。

这样做是为了你自己的头脑清晰。将所有模板存储在单个目录的根目录中会很混乱

要加载子目录中的模板，只需使用斜杠，如下所示:

get_template('news/story_detail.html')

使用相同的TEMPLATES选项，此选项将尝试加载以下模板：

• /home/html/example.com/news/story_detail.html ('django'发动机)
• /home/html/default/news/story_detail.html ('django'发动机)
• /home/html/jinja2/news/story_detail.html ('jinja2'发动机)

此外，为了减少加载和渲染模板的重复性，Django提供了一个自动处理的快捷函数.

render_to_string(template_name, context=None, request=None, using=None)

　　render_to_string() 加载一个模板 get_template() ，并立即调用它的 render() 方法。它需要下面的参数。

　　template_name

　　加载和渲染模板的名称。如果是模板名称列表，Django 使用 select_template() ，而不是 get_template() 找到模板。

　　context

　　 dict 用作模板的渲染上下文。

　　request

 　　可选项 HttpRequest 在模板的渲染过程中可用。

　　using

　　可选的模板引擎 NAME。对模板的搜索将限于该引擎。

　　使用实例：

from django.template.loader import render_to_string
rendered = render_to_string('my_template.html', {'foo': 'bar'})

还可以参看 render() 快捷函数，它调用 render_to_string() ，并将结果提供给 HttpResponse ，适合从视图返回。

最后，您可以直接使用配置好的引擎：

engines

模板引擎可在 django.template.engines 中使用：

from django.template import engines

django_engine = engines['django']
template = django_engine.from_string("Hello {{ name }}!")

在这个例子中，查找关键字“django”是引擎的 NAME。

内置backend

class DjangoTemplates

设置 BACKEND 为 'django.template.backends.django.DjangoTemplates'，以配置 Django 模板引擎。

当 APP_DIRS是True, DjangoTemplates引擎会在已安装应用程序的 templates子目录中查找模板。这个通用名称是为了向后兼容而保留的。

DjangoTemplates引擎接受以下内容OPTIONS:

• 'autoescape'：控制是否启用HTML自动转义的布尔值。

  默认为True.(警告：如果您正在渲染非HTML模板，只设置为False！)

• 'context_processors'：一个布满Python路径的列表，在使用请求渲染模板时用于填充上下文的可调用项。这些调用以请求对象作为其参数，并返回dict要合并到上下文中的项。

  默认为空列表。

  参见RequestContext，了解更多信息。

• 'debug'：打开/关闭模板调试模式的布尔值。如果是的话True，特殊错误页面将显示模板渲染过程中引发的任何异常的详细报告。此报告包含模板的相关片段，并突出显示适当的行。

  它默认为DEBUG设置的值。

• 'loaders'指向模板加载器类的Python路径列表。每个Loader类知道如何从特定源导入模板。可以选择使用元组代替字符串。元组中的第一项应该是Loader类的名称，以及在初始化期间将后续项传递给加载程序。

  默认值取决于DIRS和APP_DIRS.

  参见Loader types 相关细节。

• 'string_if_invalid'模板系统应用于无效(例如拼错)变量的字符串输出。

  默认为空字符串。

  参见如何处理无效变量相关细节。

• 'file_charset'用于读取磁盘上的模板文件的字符集。

  值默认为FILE_CHARSET.

• 'libraries'template tag模块的标签和Python路径的字典，以便在模板引擎中注册。这可以用于添加新库或为现有库提供备用标签。例如：

OPTIONS={
    'libraries': {
        'myapp_tags': 'path.to.myapp.tags',
        'admin.urls': 'django.contrib.admin.templatetags.admin_urls',
    },
}

　　Libraries可以通过将对应的字典键传递给{% load %}标签来加载库。

• 'builtins'：要添加到内置的template tag模块的Python路径列表。例如：

OPTIONS={
    'builtins': ['myapp.builtins'],
}

　　不需要首先调用{% load %}标签，就可以使用内置库中的标签和过滤器。

Django模板语言

语法

关于这部分

这是Django模板语言语法的概述。有关详细信息，请参阅语言语法引用.

Django模板只是一个文本文档或使用Django模板语言标记的Python字符串。一些构造被模板引擎识别和解释。主要是变量和标签。

模板用 context 渲染。渲染用变量的值替换变量，这些值在 context 中查找，并执行标记。其他一切都如出一辙。

Django模板语言的语法涉及四个构造。

变量

变量从上下文中输出一个值，这是一个类似于字典对象，将键映射到值。

变量像{{add}}这样被围住：

My first name is {{ first_name }}. My last name is {{ last_name }}.

有一个由{'first_name': 'John', 'last_name': 'Doe'}组成的context，此模板渲染为：

My first name is John. My last name is Doe.

字典查找、属性查找和列表索引查找是用点表示法实现的：

{{ my_dict.key }}
{{ my_object.attribute }}
{{ my_list.0 }}

如果一个变量解析为一个可调用的，模板系统将不带参数地调用它，并使用它的结果而不是可调用的。

标签(Tags)

标签在渲染过程中提供任意的逻辑。

这一定义故意不明确的。例如，标签可以输出内容，充当控制结构，例如“if”语句或“for”循环，从数据库获取内容，甚至允许访问其他模板标记。

标签像 {% and %} 这样被围住：

{% csrf_token %}

大多数标记都接受参数：

{% cycle 'odd' 'even' %}

有些标签需要开始和结束标签：

{% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %}

标签详情： 内建标签的参考， 也可以编写自定义标记的说明.

过滤器(Filters)

过滤器转换变量和标签参数的值。

它们看起来是这样的：

{{ django|title }}

有一个有{'django': 'the web framework for perfectionists with deadlines'}组成的context.，此模板渲染为：

The Web Framework For Perfectionists With Deadlines

有些过滤器采用了一个参数：

{{ my_date|date:"Y-m-d" }}

过滤器详情： 内建滤波器参考，也可以编写自定义过滤器的说明.

注释(Comments)

注释方法如下：

{# this won't be rendered #}

{% comment %}标记提供多行注释。

学习自用，欢迎大神评论、指正

更多详情见Django文档之Template：

https://docs.djangoproject.com/zh-hans/2.1/topics/templates/