Template--模板

 

模板引擎的支持

配置

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

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

 

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

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

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

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

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

 

使用 

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

 get_template(template_nameusing=None)

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

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

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

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

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

 

select_template(template_name_listusing=None)

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

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

 exception TemplateDoesNotExist(msgtried=Nonebackend=Nonechain=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=Nonerequest=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',
        ],
    },
]
View Code

如果你调用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_namecontext=Nonerequest=Noneusing=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_DIRSTrueDjangoTemplates引擎会在已安装应用程序的 templates子目录中查找模板。这个通用名称是为了向后兼容而保留的。

 DjangoTemplates引擎接受以下内容OPTIONS:

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

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

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

    默认为空列表。

    参见RequestContext了解更多信息。

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

    它默认为DEBUG设置的值。

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

    默认值取决于DIRSAPP_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',
    },
}
View Code

  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/

 

posted @ 2019-01-25 15:47  Crazy丶土豆  阅读(254)  评论(0编辑  收藏  举报