Home > Article > Backend Development > Tutorial on the use of Jinja2, the standard template engine of Python's Flask framework
Tutorial on the use of Jinja2, the standard template engine of Python's Flask framework
- WBOYOriginal
- 2016-08-04 08:55:461524browse
Jinja2 requires Python 2.4 or above.
Installation
There are many ways to follow Jinja, you can choose different following methods according to your needs.
Use easy_install or pip:
#sudo easy_install Jinja2 #sudo pip install Jinja2
Install from tarball:
# 下载Jinja的安装包 # 解压缩 # sudo python setup.py install
Basic API usage
The easiest way to create templates with Jinja is through Template. However, this usage is not recommended in actual applications:
<pre class="brush:php;toolbar:false">
>>> from Jinja2 import Template
>>> template = Template('Hello {{ name }}!')
>>> template.render(name='World')
u'Hello World!'
This example creates a Template instance using a string as the template content, and then calls the "render method" with "name='World'" as a parameter, replacing the 'name' in the content with "World", and finally returns the rendered characters. String--"u'Hello World!'"
There are two types of separators. {% raw %}{% ... %}{% endraw %} and {% raw %}{{ ... }}{% endraw %}. The first is used to perform statements like for loops or assignments, and the latter is used to output the result of the expression to the template.
How to organize templates
So how do templates fit into our applications? If you have been paying attention to Flask, you may have noticed that Flask is very flexible and does not impose any special restrictions on its content. Templates are no exception. You may also notice that there is usually a recommended place to put things (for example, templates). For templates, that place is in the package directory.
myapp/
__init__.py
models.py
views/
templates/
static/
run.py
requirements.txt
templates/
layout.html
index.html
about.html
profile/
layout.html
index.html
photos.html
admin/
layout.html
index.html
analytics.html
The structure of the templates directory is parallel to our routing structure. For the route myapp.com/admin/analytics the template is templates/admin/analytics.html. There are some additional templates in the directory that are not rendered directly. The layout.html file is for other templates to inherit.
Inheritance
Much like Batman’s backstory, a well-organized template directory relies heavily on inheritance. Parent templates usually define a common structure that all child templates can inherit from. In our example, layout.html is a parent template and the other .html files are child templates.
You typically have a top-level layout.html that defines the general layout of your application and every part of your website. If you look at the directory above, you'll see a top-level myapp/templates/layout.html, as well as myapp/templates/profile/layout.html and myapp/templates/admin/layout.html. The last two files inherit and modify the first file.
{# _myapp/templates/layout.html_ #}
<!DOCTYPE html>
<html lang="en">
<head>
<title>{% raw %}{% block title %}{% endblock %}{% endraw %}</title>
</head>
<body>
{% block body %}
<h1>This heading is defined in the parent.</h1>
{% endblock %}
</body>
</html>
In child templates, we can extend the parent template and define the content of these blocks.
{# _myapp/templates/index.html_ #}
{% extends "layout.html" %}
{% block title %}Hello world!{% endblock %}
{% block body %}
{{ super() }}
<h2>This heading is defined in the child.</h2>
{% endblock %}
The super() function lets us render the content of the parent block.
Create macros
We can adhere to the DRY (Don’t Repeat Yourself) principle in our templates by abstracting out recurring code snippets into macros. If we are working on the HTML for navigation in our application, we need to give an "active" link a class (class="active"). Without macros, we would have to write a bunch of if...else statements that check each link to find the active one.
Macros provide a way to modularize code; they work like functions. Let's see how to mark an active link using macros.
{# myapp/templates/layout.html #}
{% from "macros.html" import nav_link with context %}
<!DOCTYPE html>
<html lang="en">
<head>
{% block head %}
<title>My application</title>
{% endblock %}
</head>
<body>
<ul class="nav-list">
{{ nav_link('home', 'Home') }}
{{ nav_link('about', 'About') }}
{{ nav_link('contact', 'Get in touch') }}
</ul>
{% block body %}
{% endblock %}
</body>
</html>
All we have to do now in this template is call an undefined macro - nav_link - and pass it two parameters: the target endpoint (for example, the function name of the target view) and the text we want to display.
You may notice that in the import statement we specified with context. Jinja's context is composed of the parameters passed to the render_template() function and the Jinja environment context from our Python code. For templates, these variables are available when the template is rendered.
Some variables are obviously passed in by us, for example, render_template("index.html", color="red"), but there are also some variables and functions that are automatically included in the context by Flask, for example, request, g and session. When we say {% raw %}{% from ... import ... with context %}{% endraw %}, we tell Jinja that these variables are also available to macros.
Now it's time to define the nav_link macro used in our template.
{# myapp/templates/macros.html #}
{% macro nav_link(endpoint, text) %}
{% if request.endpoint.endswith(endpoint) %}
<li class="active"><a href="{{ url_for(endpoint) }}">{{text}}</a></li>
{% else %}
<li><a href="{{ url_for(endpoint) }}">{{text}}</a></li>
{% endif %}
{% endmacro %}
Now we have the macro defined in myapp/templates/macros.html. In this macro we use Flask's request object — available by default in the Jinja context — to check if the endpoint of the route passed in nav_link is the current request. If it is, we are on the current page, then we mark it as active.
The import y from x statement takes a relative path to x. If our template is myapp/templates/user/blog.html, we can use from "../macros.html" to import nav_link.
自定义过滤器
Jinja 过滤器是一个函数，它能够在 {% raw %}{{ ... }}{% endraw %} 中用于处理一个表达式的结果。在表达式结果输出到模板之前它就被调用。
<h2>{{ article.title|title }}</h2>
在这段代码中，title 过滤器接收 article.title 作为参数并且返回一个过滤后的标题，接着过滤后的标题将会输出到模板中。这就像 UNIX 的“管道化”一个程序到另一个程序的输出。
有很多像 title 一样的内置过滤器。请参阅 Jinja 文档中的 完整列表。
我们可以在我们的 Jinja 模板中定义自己的过滤器供使用。举例来说，我们将会实现一个简单 caps 过滤器用来大写一个字符串中所有的字母。
Jinja 已经有一个 upper 过滤器来做这样的事情，并且还有一个 capitalize 过滤器，它能用来大写第一个字母，小写其余的字母。这些也能处理 unicode 转换，但是我们会继续我们的示例，让大家目前能够知道如何自定义过滤器。
我们要在 myapp/util/filters.py 中定义我们的过滤器。这里给出一个 util 包，它里面有各种各样的模块。
# myapp/util/filters.py from .. import app @app.template_filter() def caps(text): """Convert a string to all caps.""" return text.uppercase()
在这段代码中我们使用 @app.template_filter() 装饰器注册我们的函数成一个 Jinja 过滤器。默认的过滤器名称就是函数的名称，但是你可以传入一个参数到装饰器中来改变它。
@app.template_filter('make_caps')
def caps(text):
"""Convert a string to all caps."""
return text.uppercase()
现在我们可以在模板中调用 make_caps 而不是 {% raw %}caps：{{ "hello world!"|make_caps }}{% endraw %}。
为了要让我们的过滤器在模板中可用的话，我们只需要在我们的顶层 \\_init.py\\_ 的中导入它。
# myapp/__init__.py # Make sure app has been initialized first to prevent circular imports. from .util import filters