Templates

• 配置
  有关模板的配置位于settings.py中的TEMPLATES中

  # settings.py
  TEMPLATES = [
      {
          'BACKEND': 'django.template.backends.django.DjangoTemplates',
         # 'DIRS' 定义一个Django在查找模板时应该遍历的目录列表
          'DIRS': [],
          # 'APP_DIRS' 指明Django是否应该去各app应用目录下查找模板
          'APP_DIRS': True,
          'OPTIONS': {
              # ... some options here ...
          },
      },
  ]
  

---

• 使用模板（django.template.loader）
  • get_template(template_name, using=None)
    返回查找到的模板对象
  • select_template(template_name_list, using=None)
    同get_template()用法一致，只不过返回的是模板对象列表（因为参数也是列表）
  • exception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)
    当模板未能找到时，引发该异常
  • exception TemplateSyntaxError(msg)
    当被查找到的模板中存在语法错误时引发该异常
  • render(context=None, request=None)
    查找到并返回的Template对象必须实现上边的方法
  • render_to_string(template_name, context=None, request=None, using=None)
    get_template()函数和render()方法的结合

---

模板语言

• 模板变量（{{ variables }}）

  当模板系统遇到一个 '.' 时，将会按照以下顺序进行查询

  • 查询相应的字典
  • 查询属性或者方法
  • 查询序列索引

  如果查询的结果可以被调用，Django将会进行无参数调用，并返回调用结果
  若变量不存在，模板系统将会插入string_if_invalid中设置的值（该值在settings.TEMPLATES['OPTIONS']中设置）

• 过滤器

  • 一般形式：{{ name|lower }}
  • 链状形式：{{ text|escape|linebreaks }}
  • 包含参数：{{ bio|truncatewords:30 }}
  • 含有空格的参数必须使用引号：{{ list|join:", " }}

  Django中所有的过滤器

  • 一些常使用的过滤器
    • default（{{ value|default:"nothing" }}）：若变量不存在，则返回default中的参数值
    • length：返回变量的长度（适用于字符串和列表）
    • filesizeformat：将数字以文件大小的表示形式返回（即：13 KB，8.8 MB等等）

• 模板标签（{% tags %}）

  使用extends标签需要注意

  • {% extends %}标签必须是该模板中的第一个标签
  • {% block %}标签的使用多多益善
  • 当需要使用父模板中block里边的内容时，可以通过{{ block.super }}变量来获得（注意block.super是变量）
  • 在{% block %}外通过模板标签创造的变量无法在{% block %}内使用

    {% trans "Title" as title %}
    {% block content %}{{ title }}{% endblock %}
    # 上述标签将不会返回任何东西
    

  • 在{% endblock %}中可以选择性的添加块名，如{% endblock content %}

---

Automatic HTML escaping

用户可能会在变量中添加HTML标签，而使得模板展示出现错误（Cross Site Scripting(XSS)攻击）
有两种方法可以避免该问题：

• 使用escape过滤器将传入的变量转变为无害的变量，这种方法是Django默认使用的方法（但是这种方法会escape掉所有传入的变量）
• 利用Django的 automatic HTML escaping

关闭自动escape

有时候可能用户希望传入原生的HTML语句（即保留标签的使用等），有以下方法可以使得escape的使用关闭

• 对于单个变量
  使用save过滤器

  This will be escaped: {{ data }}
  This will not be escaped: {{ data|safe }}
  

• 对于模板中的块（blocks）
  使用autoescape标签

  Auto-escaping is on by default. Hello {{ name }}
  
  # 关闭autoescape（即对传入变量不做处理）
  {% autoescape off %}
      This will not be auto-escaped: {{ data }}.
  
      Nor this: {{ other_data }}
      {% autoescape on %}
          Auto-escaping applies again: {{ name }}
      {% endautoescape %}
  {% endautoescape %}
  

  autoescape标签之间中的所有内容（包括其他标签、子模板等等）都会遵循autoescape的状态
• default过滤器
  default过滤器中的内容默认为关闭escape

  # 应该使用这种形式
  {{ data|default:"3 < 2" }}
  # 而不应该使用这种形式
  {{ data|default:"3 < 2"}}
  

---

自定义标签和过滤器的使用

1. 需要确保包含自定义标签和过滤器的应用在INSTALLED_APPS中
2. 在模板中使用{% load %}标签
3. {% load %}标签可以加载多个库

   {{ load humanize i18n }}
   

另外需要注意的是，子模板不继承父模板的{% load %}标签，因此必要时，需要在子模板中使用{% load %}标签进行重新加载

---

Django中内建的标签和过滤器

---

自定义标签和过滤器

布局

• 在app的直接目录下创建templatetags文件夹，并将其声明为一个包（即在templatetags中创建__init__.py文件）
• 在temloatetags中创建定义标签和过滤器的python文件（如poll_extras.py），并在需要用到相应标签/过滤的模板中通过{% load poll_extras %}引入（注意该app已存在于INSTALLED_APPS）
• 将相关python文件注册为可以使用的标签库

  from django import template
  
  register = template.Library()
  

自定义过滤器

过滤器函数至少需要一个参数（传入被过滤对象），此外可以选择性地使用另一个参数

def cut(value, arg):
    return value.replace(arg, '')
# 使用：{{ somevariable|cut:"0" }}

• 注册自定义过滤器
  有两种方法注册过滤器
  • register.filter()

    # 第一个参数是过滤器使用的名称，第二个参数是过滤器使用的函数
    register.filter('cut', cut)
    

  • 装饰器

    # 若装饰器含有name参数，则该过滤器名称会被设置为name参数所指对象
    @register.filter(name='cut')
    def cut(value, arg):
        return value.replace(arg, '')
    
    # 若装饰器没有name参数，django会自动使用函数名作为过滤器名称
    @register.filter
    def lower(value):
        return value.lower()
    

• 强制转变第一个传入的参数为字符串类型

  from django import template
  from django.template.defaultfilters import stringfilter
  
  register = template.Library()
  
  @register.filter
  # 该过滤器会将被过滤对象首先转变为字符串类型
  @stringfilter
  def lower(value):
      return value.lower()
  

• register.filter()中的其它三个参数（全部默认为False）
  • is_safe
  • needs_autoescape
  • expects_localtime

自定义模板标签