模板

A template 是磁盘上的文件,可用于呈现由 view . Pyramid 提供了许多现成执行模板化任务的方法,并通过一组绑定包提供附加模板化支持。

在详细讨论如何使用内置模板之前,我们将讨论在 Pyramid 通常:直接和通过渲染器配置。

直接使用模板

使用模板的最简单方法 Pyramid 使其直接在 view callable . 您可以使用给定模板引擎提供的任何API来执行此操作。

Pyramid 提供各种API,允许您直接从可调用视图中呈现模板。例如,如果 Chameleon ZPT模板名为 foo.pt 在一个名为 templates 在应用程序中,可以从可调用视图的主体中呈现模板,如下所示:

1
2
3
4
5
6
from pyramid.renderers import render_to_response

def sample_view(request):
    return render_to_response('templates/foo.pt',
                              {'foo':1, 'bar':2},
                              request=request)

这个 sample_view view callable 上面的函数返回 response 对象,其中包含 templates/foo.pt 模板。在这种情况下, templates 目录应与包含 sample_view 功能。模板作者将具有这些名称 foobar 作为顶级名称提供,用于替换或比较。

在上面的示例中,路径 templates/foo.pt 相对于包含定义视图配置的文件的目录。在这种情况下,这是包含定义 sample_view 功能。虽然渲染器路径通常只是一个简单的相对路径名,但名为渲染器的路径可以是绝对路径,从UNIX上的斜线或Windows上的驱动器号前缀开始。路径也可以是 asset specification 形式上 some.dotted.package_name:relative/path . 这使得处理另一个包中的模板资产成为可能。例如:

1
2
3
4
5
6
from pyramid.renderers import render_to_response

def sample_view(request):
    return render_to_response('mypackage:templates/foo.pt',
                              {'foo':1, 'bar':2},
                              request=request)

资产规范指向Python中的文件 包裹 . 在本例中,它指向一个名为 foo.pttemplates 目录 mypackage 包裹。使用资产规范而不是相对模板名称通常是一个好主意,因为调用 render_to_response() 如果将包含资产规范的代码移动到其他位置,则使用资产规范将继续正常工作。

在上面的示例中,我们传递一个名为 request 代表当前 Pyramid 请求。传递请求关键字参数将导致 render_to_response 函数为渲染器提供更正确的系统值(请参见 渲染期间使用的系统值 ,因为组成适当系统值所需的大部分信息都存在于请求中。如果模板依赖于名称 requestcontext 或者如果您已经配置了特殊的 renderer globals ,确保通过 request 在每次调用 pyramid.renderers.render_* 功能。

每个视图都必须返回 response 对象,但使用 renderer 通过视图配置命名(稍后我们将看到)。这个 pyramid.renderers.render_to_response() 函数是实际返回响应对象的快捷函数。这允许上面的示例视图简单地返回其调用的结果 render_to_response() 直接。

显然,并非所有可能调用以获取响应数据的API都将返回响应对象。例如,可以将一个或多个模板呈现为要用作响应数据的字符串。这个 pyramid.renderers.render() API将模板呈现为字符串。我们可以制造 response 对象,并将该字符串用作响应的主体:

1
2
3
4
5
6
7
8
9
from pyramid.renderers import render
from pyramid.response import Response

def sample_view(request):
    result = render('mypackage:templates/foo.pt',
                    {'foo':1, 'bar':2},
                    request=request)
    response = Response(result)
    return response

因为 view callable 函数通常是 Pyramid 这需要知道关于模板的任何信息,并且由于视图函数是非常简单的python,所以您可以使用您最熟悉的任何模板系统。 Pyramid . 安装模板系统,将其API函数导入视图模块,使用这些API生成字符串,然后将该字符串作为 Pyramid Response 对象。

例如,这里有一个使用“raw”的示例 Mako 从内部 Pyramid view

1
2
3
4
5
6
7
8
from mako.template import Template
from pyramid.response import Response

def make_view(request):
    template = Template(filename='/templates/template.mak')
    result = template.render(name=request.params['name'])
    response = Response(result)
    return response

您可能不会在项目中使用这个特定的片段,因为使用支持的 Mako bindings . 但是,如果不支持将您最喜爱的模板系统作为的渲染器扩展 Pyramid ,您可以创建自己的简单组合,如上图所示。

注解

如果在不合作的情况下使用第三方模板语言 Pyramid 直接在视图可调用文件中绑定,自动模板重新加载策略在 自动重新加载模板 将不可用,模板资产覆盖功能也将不可用 压倒一切的资产 可用,也不可能使用任何使用该语言的模板作为 renderer . 但是,编写自定义模板系统绑定包以便在 Pyramid 这样用语言编写的模板就可以用作渲染器。见 添加和更改渲染器 有关如何创建自己的模板渲染器和 可用的附加模板系统绑定 例如,软件包。

如果您需要对状态代码和内容类型或使用直接模板化的视图中的其他响应属性进行更多的控制,则可以对影响这些值的响应设置属性。

下面是更改由返回的响应对象的内容类型和状态的示例 render_to_response()

1
2
3
4
5
6
7
8
9
from pyramid.renderers import render_to_response

def sample_view(request):
    response = render_to_response('templates/foo.pt',
                                  {'foo':1, 'bar':2},
                                  request=request)
    response.content_type = 'text/plain'
    response.status_int = 204
    return response

下面是一个使用 render() (字符串):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from pyramid.renderers import render
from pyramid.response import Response

def sample_view(request):
    result = render('mypackage:templates/foo.pt',
                    {'foo':1, 'bar':2},
                    request=request)
    response = Response(result)
    response.content_type = 'text/plain'
    return response

渲染期间使用的系统值

当使用 render_to_response()render() ,或者 renderer= 视图配置的参数(请参见 通过配置用作呈现器的模板 )表示模板的渲染器将提供 系统 价值观。这些值提供给模板:

request
作为 request 关键字参数 render_to_responserender orrenderer= 视图配置的参数正用于呈现模板。
req
的别名 request .
context
Pyramid context 如果 request 作为关键字参数提供给 render_to_responserenderNone 如果 request 未提供关键字参数。如果模板是由 renderer= 正在使用的视图配置的参数。
get_csrf_token()
访问当前CSRF令牌的便利功能。见 使用 get_csrf_token 模板中的全局 更多信息。
renderer_name
用于执行渲染的渲染器名称,例如, mypackage:templates/foo.pt .
renderer_info
实现 pyramid.interfaces.IRendererInfo 接口。基本上,具有以下属性的对象: namepackagetype .
view
用于呈现此模板的视图可调用对象。如果视图可调用是基于类的视图的方法,则这将是定义该方法的类的实例。如果视图可调用是一个函数或实例,那么它就是该函数或实例。请注意,只有当模板作为 renderer= 争论;它将是 Nonerender_to_responserender 使用API。

通过定义 renderer globals .

任何特定的渲染器对这些系统值的操作都取决于渲染器本身,但大多数模板渲染器都将这些名称作为顶级模板变量提供。

通过配置用作呈现器的模板

替代使用 render_to_response() 要在视图中手动呈现模板,可调用代码是将模板指定为 renderer 在你 查看配置 . 这可以通过以下支持的任何模板语言来完成: Pyramid .

要通过视图配置使用渲染器,请指定模板 asset specification 作为 renderer 参数或属性 view configuration A的 view callable . 然后返回 词典 从那个角度来看,可以调用。视图可调用返回的字典项将作为顶级名称提供给渲染器模板。

模板作为渲染器的关联 view configuration 使在 view callable 它处理模板的呈现。

下面是一个使用 view_config 修饰器指定 view configuration 命名模板渲染器:

1
2
3
4
5
from pyramid.view import view_config

@view_config(renderer='templates/foo.pt')
def my_view(request):
    return {'foo':1, 'bar':2}

注解

你不需要提供 request 值作为字典结果中的键从渲染器配置的可调用视图返回。 Pyramid 自动为您提供该值,以便向渲染器提供“最正确”的系统值。

警告

这个 renderer 论据 @view_config 上面显示的配置装饰器是模板 path . 在上面的示例中,路径 templates/foo.pt相对的 . 相对于什么,你问?因为我们使用的是变色龙渲染器,它的意思是“相对于定义视图配置的文件所在的目录”。在这种情况下,这是包含定义 my_view 功能。

类似的渲染器配置可以强制执行。见 正在写入使用渲染器的视图可调用文件 .

参见

也见 内置渲染器 .

虽然渲染器路径通常只是一个简单的相对路径名,但名为渲染器的路径可以是绝对路径,从UNIX上的斜线或Windows上的驱动器号前缀开始。路径也可以是 asset specification 形式上 some.dotted.package_name:relative/path ,从而可以处理另一个包中的模板资产。

任何任意模板系统中的任何模板都不能用作渲染器。绑定必须专门存在于 Pyramid 使用模板语言模板作为渲染器。

默认情况下,通过模板渲染器渲染的视图返回 Response 对象具有 状态码 属于 200 OK 和A content-type 属于 text/html . 要改变使用渲染器的视图响应的属性,例如内容类型、标题或状态属性,必须使用 pyramid.response.Response 对象暴露为 request.response 在返回字典之前在视图中。见 呈现响应的不同属性 更多信息。

通过渲染器视图配置提供给模板的系统值集与强制提供给模板的系统值集相同。见 渲染期间使用的系统值 .

调试模板

A NameError 呈现带有未定义变量(例如 ${{wrong}} )可能最终看起来像这样:

RuntimeError: Caught exception rendering template.
 - Expression: ``wrong``
 - Filename:   /home/fred/env/proj/proj/templates/mytemplate.pt
 - Arguments:  renderer_name: proj:templates/mytemplate.pt
               template: <PageTemplateFile - at 0x1d2ecf0>
               xincludes: <XIncludes - at 0x1d3a130>
               request: <Request - at 0x1d2ecd0>
               project: proj
               macros: <Macros - at 0x1d3aed0>
               context: <MyResource None at 0x1d39130>
               view: <function my_view at 0x1d23570>

NameError: wrong

输出告诉您发生错误的模板,以及显示传递给模板本身的参数。

自动重新加载模板

通常可以方便地看到对模板文件所做的更改立即出现,而无需重新启动应用程序进程。 Pyramid 允许您配置应用程序开发环境,以便自动检测对模板的更改,并在下次呈现时重新加载模板。

警告

对于生产站点,不建议使用自动模板重新加载行为,因为它会稍微减慢渲染速度;通常只在开发期间才需要这样做。

为了启用模板的自动重新加载,可以使用环境变量或配置文件设置。

要使用环境变量,请使用 PYRAMID_RELOAD_TEMPLATES 操作系统环境变量设置为 1 例如:

PYRAMID_RELOAD_TEMPLATES=1 $VENV/bin/pserve myproject.ini

在应用程序中使用设置 .ini 文件用于相同的目的,设置 pyramid.reload_templates 关键 true 在应用程序的配置部分中,例如:

1
2
3
[app:main]
use = egg:MyProject
pyramid.reload_templates = true

可用的附加模板系统绑定

pylons项目维护了几个包,为不同的模板语言提供绑定,包括:

模板语言 金字塔绑定 默认扩展名
Chameleon pyramid_chameleon Pt,TXT
Jinja2 pyramid_jinja2 金沙2号
Mako pyramid_mako 麦克,马可