11. TEMPLATES
Why Use A Renderer via View Configuration
Using a renderer in view configuration is usually a better way to render templates than using any rendering API directly from within a view callable because it makes the view callable more unit-testable. Views which use templating or rendering APIs directly must return a Response object. Making testing assertions about response objects is typically an indirect process, because it means that your test code often needs to somehow parse information out of the response body (often HTML). View callables configured with renderers externally via view configuration typically return a dictionary, as above. Making assertions about results returned in a dictionary is almost always more direct and straightforward than needing to parse HTML.
By default, views rendered via a template renderer return a Response object which has a status code of 200 OK, and a content-type of text/html. To vary attributes of the response of a view that uses a renderer, such as the content-type, headers, or status attributes, you must use the API of the pyramid.response.Response object exposed as request.response within the view before returning the dictionary. See Varying Attributes of Rendered Responses for more information.
The same set of system values are provided to templates rendered via a renderer view configuration as those provided to templates rendered imperatively. See System Values Used During Rendering.
11.4 Chameleon ZPT Templates
Like Zope, Pyramid uses ZPT (Zope Page Templates) as its default templating language. However, Pyramid uses a different implementation of the ZPT specification than Zope does: the Chameleon templating engine. The Chameleon engine complies largely with the Zope Page Template template specification. However, it is significantly faster.
The language definition documentation for Chameleon ZPT-style templates is available from the Chameleon website.
Given a Chameleon ZPT template named foo.pt in a directory in your application named templates, you can render the template as a renderer like so:
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}
See also Built-In Renderers for more general information about renderers, including Chameleon ZPT renderers.
128
11.4. CHAMELEON ZPT TEMPLATES
11.4.1 A Sample ZPT Template
Here’s what a simple Chameleon ZPT template used under Pyramid might look like:
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml"
4xmlns:tal="http://xml.zope.org/namespaces/tal">
5<head>
6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
7<title>${project} Application</title>
8</head>
9<body>
10<h1 class="title">Welcome to <code>${project}</code>, an
11application generated by the <a
12href="http://docs.pylonsproject.org/projects/pyramid/current/"
13>pyramid</a> web
14application framework.</h1>
15</body>
16</html>
Note the use of Genshi -style ${replacements} above. This is one of the ways that Chameleon ZPT differs from standard ZPT. The above template expects to find a project key in the set of keywords passed in to it via render() or render_to_response(). Typical ZPT attribute-based syntax (e.g. tal:content and tal:replace) also works in these templates.
11.4.2 Using ZPT Macros in Pyramid
When a renderer is used to render a template, Pyramid makes at least two top-level names available to the template by default: context and request. One of the common needs in ZPT-based templates is to use one template’s “macros” from within a different template. In Zope, this is typically handled by retrieving the template from the context. But the context in Pyramid is a resource object, and templates cannot usually be retrieved from resources. To use macros in Pyramid, you need to make the macro template itself available to the rendered template by passing the macro template, or even the macro itself, into the rendered template. To do this you can use the pyramid.renderers.get_renderer() API to retrieve the macro template, and pass it into the template being rendered via the dictionary returned by the view. For example, using a view configuration via a view_config decorator that uses a renderer:
1
2
3
4
from pyramid.renderers import get_renderer from pyramid.view import view_config
@view_config(renderer=’templates/mytemplate.pt’)
129