render(*args, **kwargs)

generate(*args, **kwargs)

stream(*args, **kwargs)

foo = Undefined(name='foo')
  >>> str(foo)
  ''
  >>> not foo
True
  >>> foo + 42
Traceback (most recent call last):
...
Jinja2.exceptions.UndefinedError: 'foo' is undefined

  >>> foo = DebugUndefined(name='foo')
  >>> str(foo)
'` foo `'
  >>> not foo
True
  >>> foo + 42
Traceback (most recent call last):
...
Jinja2.exceptions.UndefinedError: 'foo' is undefined

  >>> foo = StrictUndefined(name='foo')
  >>> str(foo)
Traceback (most recent call last):
...
Jinja2.exceptions.UndefinedError: 'foo' is undefined
  >>> not foo
Traceback (most recent call last):
...
Jinja2.exceptions.UndefinedError: 'foo' is undefined
  >>> foo + 42
Traceback (most recent call last):
...
Jinja2.exceptions.UndefinedError: 'foo' is undefined

模板设计文档

概述

一个模板其实就是一个普通的文本文件。它可以被设计为任何文本格式（HTML,XML,CSV等等）。它也不需要确定的扩展名，不过一般我们都会 用'.html'或'.xml'
模板中包含变量，表达式，标签，变量和表达式会在模板渲染时被用值来替换，标签控制模板的逻辑。Jinja的语法主要参考自Django和 python。

下面是一个简单的模板，它包含的了几个模板中的基本元素，在之后的文档中会对这些元素做详细说明。

  
  
  
      
  
  
      

      ` for item in navigation `
          
` item`.`caption `

      {% endfor %}
      

      
My Webpage

      ` a_variable `
  
  

  ` foo`.`bar `
  {{ foo['bar'] }}

  '{{ name|striptags|title }}'

 '{{ list|join(', ') }}'

    {% block head %}
    
    
    {% endblock %}


    
{% block content %}{% endblock %}

    

        {% block footer %}
        © Copyright 2008 by you.
        {% endblock %}
    

{% extends "base.html" %}
{% block title %}Index{% endblock %}
{% block head %}
    {{ super() }}
    
{% endblock %}
{% block content %}
    
Index

    

      Welcome on my awsome homepage.
    

{% endblock %}

{% extends "layout/default.html" %}

{{ self.title() }}

{% block body %}{% endblock %}

{% block sidebar %}
    
Table Of Contents

    ...
    {{ super() }}
{% endblock %}

HTML转义
:我们传递给模板的变量中可能会有一些html标记符，这些标记符也许会影响我们页面的正常显示，而且会给我们的站点带来跨站脚本***的隐患。
Jinja提供了两种方式-自动或者手工来对变量值进行html转义，即把'<'转换为'<'，'>'转换为 '>'，'&'转换为'&'
通过给Environment或Template的构建器传递autoescape参数，可以设置自动转义与否。
手动转义
这种方式需要我们使用过滤器转换我们需要转义的变量
'{{ user.username|e }}'. 这里'e'就是转义过滤器

自动转义
这种方式会在打印变量时自动进行转义。除非使用'safe'过滤器标明不需要转义：

'{{ user.username|safe }}'.

结构控制标记

Jinja中的控制标记包括：条件判断标记(if/elif/else)，循环控制(for-loop),另外还有macro（宏)和上文中提到 的block。

for
循环打印一个序列，例如：

Members


{% for user in users %}
  
{{ user.username|e }}

{% endfor %}


在循环内部，你可以访问一些特殊的变量
Variable
Description
loop.index
当 前迭代的索引，从1开始算
loop.index0
当前迭代的索引，从0开始算
loop.revindex
相 对于序列末尾的索引，从1开始算
loop.revindex0
相对于序列末尾的索引，从0开始算
loop.first
相 当于 loop.index == 1.
loop.last
相当于 loop.index == len(seq) - 1
loop.length
序列的长度.
loop.cycle
是 一个帮助性质的函数，可以接受两个字符串参数，如果当前循环索引是偶数，则显示第一个字符串，是奇数则显示第二个字符串。它常被在表格中用来用不同的背景 色区分相邻的行。


{% for row in rows %}
    
` row `

{% endfor %}

需要注意的是，Jinja的循环不支持break和continue标记。你可以对需要迭代的sequence使用过滤器来达到与break和 continue相同的目的。
下面的例子中，如果user.hidden属性为true的则continue

{% for user in users if not user.hidden %}
    
{{ user.username|e }}

{% endfor %}

Jinja的for语句有一个和python相同的用法，那就是“else'：当无循环时显示else中的内容，如下例：


{% for user in users %}
    
{{ user.username|e }}

{% else %}
    
no users found

{% endif %}


if

if语句用来在Jinja中做比较判断，比较常见的用法是判断一个变量是否已定义，是否非空，是否为true

{% if users %}

{% for user in users %}
    
{{ user.username|e }}

{% endfor %}

{% endif %}

和python一样，也可以使用elif和else

{% if kenny.sick %}
    Kenny is sick.
{% elif kenny.dead %}
    You killed Kenny!  You bastard!!!
{% else %}
    Kenny looks okay --- so far
{% endif %}

if语句也可以被用来做内联表达式或者for语句过滤器。

宏（Macro）
宏的作用和函数比较类似。用来把一部分常用的代码封装起来，避免重复性的工作。
宏可以定义在一个帮助性质的模板中，用imported的方式被其它模板引用；也可以在模板中定义并直接使用。这两种方式有个显著的不同：在模板 中定义的宏可以访问传给模板的上下文变量；在其它模板中定义的宏则只能访问到传递给它的变量，或者全局变量。

这里有个打印表单元素的简单的宏

{% macro input(name, value='', type='text', size=20) -%}
    
{%- endmacro %}

这个宏可以在命名空间中被直接调用

{{ input('username') }}

{{ input('password', type='password') }}


如果这个宏在其它模板中，你必须先用import引入。
在一个模板中你可以访问三种特殊变量：

*'''varargs''' 等同于python语法中的"*args"
*'''kwargs''' 等同于python语法中的"**kwargs"
*'''caller''' 被call标签调用的宏，调用者会被存储在一个叫做caller的变量中。

宏其实也是一个对象，它有一些属性可以在模板中使用：
*'''name''' 宏的名称。{{ 'input.name':string }}
*'''arguments''' 宏可以接受的参数，这个属性是一个元组
*'''defaults''' 缺省值的元组
*'''catch_kwargs''' 这个宏是否可以接受关键字参数
*'''catch_varargs''' 这个宏是否可以接受索引位置参数
*'''caller''' 是否有caller变量，可以被call标签调用

Call

在某些情况下，你可能需要将一个宏对象传递到另外一个宏中使用。为了实现此目的，你可以使用call block。

{% macro render_dialog(title, class='dialog') -%}
    

        
` title `

        

            {{ caller() }}
        

    

{%- endmacro %}

{% call render_dialog('Hello World') %}
    This is a simple dialog rendered by using a macro and
    a call block.
{% endcall %}

在这里例子里，我们用"call render_dialog"调用了宏render_dialog，其中，'hello world作为render_dialog的title参数。在render_dialog中用{{ caller() }}将 call block中的内容显示出来。

在使用 {{ caller() }} 时，也可以传入参数，如下例:

{% macro dump_users(users) -%}
    

    {%- for user in users %}
        
{{ user.username|e }}
{{ caller(user) }}

    {%- endfor %}
    

{%- endmacro %}

{% call(user) dump_users(list_of_user) %}
    

        
Realname

        
{{ user.realname|e }}

        
Description

        
` user`.`description `

    

{% endcall %}


赋值
在一个代码块内部你可以为一个变量赋值。在块（block, macro, loop)外部赋值的变量可以被从模板中导出，提供给其它模板使用。
一个赋值语句的用法如下例：

{% navigation = [('index.html', 'Index'), ('about.html', 'About')] %}

include
用include可以导入另外一个模板到当前模板中

{% include 'header.html' %}
Body
{% include 'footer.html' %}

import

Jinja2支持将常用的代码放到宏中。这些宏可以放到不同的模板中，然后用import语句导入来使用，这有点类似python的import 功能。需要注意的是，import导入的模板会被缓存，而且导入到模板不能访问当前模板的本地变量，它只能访问全局变量。

导入模板有两种方式，一是导入整个的模板作为一个变量，另一个方法是从一个模板中导入指定的宏或者可导出的变量
下面我们写一个名为"form.html"的模板， 这个模板作为一个公共模板提供给其它模板使用

{% macro input(name, value='', type='text') -%}
    
{%- endmacro %}

{%- macro textarea(name, value='', rows=10, cols=40) -%}
    {{ value|e }}
{%- endmacro %}

最简单和灵活的方式是把form.html整个导入到一个模板中

{% import 'forms.html' as forms %}

    
Username

    
{{ forms.input('username') }}

    
Password

    
{{ forms.input('password', type='password') }}


{{ forms.textarea('comment') }}


或者导入指定的内容（宏或者变量）到当前模板中

{% from 'forms.html' import input as input_field, textarea %}

    
Username

    
{{ input_field('username') }}

    
Password

    
{{ input_field('password', type='password') }}


{{ textarea('comment') }}


表达式

Jinja的表达式在模板中到处都是，它的语法很类似python，而且它很简单，即使不会python也可以很容易学会它。

字面值

字面值是最简单的表达式，它其实就是一个python的对象，在Jinja中有下面几种字面值：
字符串，数字，序列，元组，字典，bool类型。

它们的用法很python的很接近，如下面的例子：


{% for href, caption in [('index.html', 'Index'), ('about.html', 'About'),
                         ('downloads.html', 'Downloads')] %}
    
` caption `

{% endfor %}


数字计算

Jinja支持一下几种操作符：
+,-,/,//(整除），%求余，*乘，**次方

逻辑操作
Jinja支持一下几种逻辑操作符，它们可以放在if块中使用：
and, or, not, ()

其它操作符
'''in '''
判断一个对象是否存在于另一个序列或者元组中

{{ 1 in [1, 2, 3] }}

'''is'''
执行一个检查器
'''|'''
执行一个过滤器
'''~'''
连接字符串 '{{ "Hello " ~ name ~ "!" }}'，如果name的值是'world， 显示的内容将是 "Hello world"
'''( )''' 调用函数
'''. / []''' 访问一个对象的属性

if表达式
Jinja支持内联表达式，在某些情况下非常有用，例如：

{% extends layout_template if layout_template is defined else 'master.html' %}

这个例子的意思是：如果变量layout_template已定义则导入，否则导入master.html
通用的语法规则是''' if  else '''

内建过滤器

*'''abs(number)''' 返回数字的绝对值

*'''batch(value, linecount, fill_with=None)'''
:将一个序列以给定值分成若干片，如果给定了fill_with，则会将fill_with补充到未分配的部分。比如一个序列 ['a','b','c','d','e'], 用数值3分片将会得到[['a','b','c'], ['d','e']], 如果分片时指定fill_with=' '，结果将会是[['a','b','c'], ['d','e',' ']]
:这个过滤器的用处在于，如果你要在表格中显示一个很长的序列，每行显示5个，则可以用下面的方式打印：

{% for row in seq|batch(3, ' ') %}
{% for item in row %}

*'''capitalize(s)'''
首字符大写
*'''center(value, width=80)'''
生成一个长度为width的空字符串，将value放在中间
*'''default(value, default_value=u”, boolean=False)'''
如果value未定义，则显示default_value，如果value是一个bool型，需要将boolean置为true，这样当value为 false是将会打印缺省值
这个过滤器的别名是d
*'''dictsort(value, case_sensitive=False, by='key')'''
字典排序，case_sensitive决定是否大小写敏感，by决定是按照key排序还是按value排序
*'''escape(s)'''
html字符转义，别名是e
*'''filesizeformat(value)'''
将一个大数字转换成KMG形式，如：1.3k，34g，25.3m等等

*'''first(seq)'''
返回序列的第一个值
*'''float(value, default=0.0)'''
将一个值转换成浮点数，如果转换失败则返回default
*'''forceescape(value)'''
不管value是否被转义过，一律进行html转义。比如value="<", 如果用“value|e|e”则会得到“<",而不是"&lt;",如果用forceescape则会得 到"&lt;"

*'''format(value, *args, **kwargs)'''
等同于python的"%s,%s" % (str1, str2)
*'''groupby(value, attribute)'''
类似SQL的group by,可以将一个序列里的对象/字典，按照attribute分组。如下例：


{% for group in persons|groupby('gender') %}
    
` group`.`grouper `

    {% for person in group.list %}
        
` person`.`first_name ` ` person`.`last_name `

    {% endfor %}

{% endfor %}


也可以用下面的方式使用：


{% for grouper, list in persons|groupby('gender') %}
    ...
{% endfor %}


"grouper"是分组的值，在上面的例子中分别是“male”和“female”
*'''indent(s, width=4, indentfirst=False)'''
将文本s中每行的首字符缩进width个字符。indentfirst表示是否缩进第一行。
*'''int(value, default=0)'''
将value转换成整数，如果转换失败则返回default
*'''join(seq, d=u”)'''
将序列seq中的各个值用d字符连接起来形成一个字符串。
*'''last(seq)'''
序列的最后一个值。
*'''length(object)'''
序列或者字典的长度
别名：count
*'''list(value)'''
将value转换为序列，如果value是字符串，则将字符串转换为字符数组。
*'''lower(s)'''
将字符串转换为小写
*'''pprint(value, verbose=False)'''
debug时使用，可以打印变量的详细信息。
*'''random(seq)'''
随机从序列中取得一个值。

*'''replace(s, old, new, count=None)'''
将字符s中的old字符串替换为new字符串，如果给定了count，则最多替换count次。
*'''reverse(value)'''
将一个序列反转。
*'''round(value, precision=0, method='common')'''
浮点数求精。precision是小数点位数，method有common,ceil,floor三种。common是四舍五入，ceil和floor与 python的同名函数功能相同。
*'''safe(value)'''
如果当前模板设置了html自动转义，用此过滤器可以使value不转义
*'''slice(value, slices, fill_with=None)'''
将序列分片，用fill_with字符填充最后一组子序列长度不足的部分。
*'''sort(value, reverse=False)'''
将序列按从小到大排序，reverse为true则按从大到小排序
*'''string(object)'''
将一个对象转换为unicode字符串
*'''striptags(value)'''
去掉字符串value中的html，xml标签
*'''sum(sequence, start=0)'''
统计数值序列的和。start表示从第几项开始计算
*'''title(s)'''
将字符串s中每个单词首字符大写

*'''trim(value)'''
去掉字符串value中首尾的空格

*'''truncate(s, length=255, killwords=False, end='...')'''
截断一个字符串为length长度，末尾补end字符。killword为false则将最后一个单词完整保留，为True则将严格按照给定的长度截断。
*'''upper(s)'''
将字符串转换为大写
*'''urlize(value, trim_url_limit=None, nofollow=False)'''

*'''wordcount(s)'''
统计字符串中单词的个数
*'''wordwrap(s, pos=79, hard=False)'''
将字符串s按照pos长度换行。如果hard为True，则强制截断单词。
*'''xmlattr(d, autospace=True)'''
创建一个sgml/xml的属性字符串，例如：


...


结果会是这个样子:


...


值会自动进行html转义，如果为未定义或者None则忽略。
*'''autospace''': 自动在首部添加空格.

内建检查器
*'''callable(object)'''
对象是否可调用
*'''defined(value)'''
对象是否已定义
*'''divisibleby(value, num)'''
value是否可以被num整除
*'''escaped(value)'''
是否已转义
*'''even(value)'''
是否为奇数
*'''iterable(value)'''
是否可以循环
*'''lower(value)'''
是否为小写
*'''none(value)'''
是否为None
*'''number(value)'''
是否为数字
*'''odd(value)'''
是否为偶数
*'''sameas(value, other)'''
value是否与other为同一个对象实例
*'''sequence(value)'''
是否为序列
*'''string(value)'''
是否是字符串
*'''undefined(value)'''
是否未定义
*'''upper(value)'''
是否为大写
创新互联www.cdcxhl.cn，专业提供香港、美国云服务器，动态BGP最优骨干路由自动选择，持续稳定高效的网络助力业务部署。公司持有工信部办法的idc、isp许可证， 机房独有T级流量清洗系统配攻击溯源，准确进行流量调度，确保服务器高可用性。佳节活动现已开启，新人活动云服务器买多久送多久。
                    

                    当前文章：Jinja2简明使用手册-创新互联                    

                    URL网址：http://chengdu.cdxwcx.cn/article/eojih.html