10. RENDERERS
10.6 Adding and Changing Renderers
New templating systems and serializers can be associated with Pyramid renderer names. To this end, configuration declarations can be made which change an existing renderer factory, and which add a new renderer factory.
Renderers can be registered imperatively using the pyramid.config.Configurator.add_renderer() API.
For example, to add a renderer which renders views which have a renderer attribute that is a path that ends in .jinja2:
1 config.add_renderer(’.jinja2’, ’mypackage.MyJinja2Renderer’)
The first argument is the renderer name. The second argument is a reference to an implementation of a renderer factory or a dotted Python name referring to such an object.
10.6.1 Adding a New Renderer
You may add a new renderer by creating and registering a renderer factory.
A renderer factory implementation is typically a class with the following interface:
1 class RendererFactory:
2def __init__(self, info):
3""" Constructor: info will be an object having the
4 following attributes: name (the renderer name), package
5(the package that was ’current’ at the time the
6renderer was registered), type (the renderer type
7 name), registry (the current application registry) and
8settings (the deployment settings dictionary). """
9
10def __call__(self, value, system):
11""" Call the renderer implementation with the value
12and the system value passed in as arguments and return
13the result (a string or unicode object). The value is
14the return value of a view. The system value is a
15dictionary containing available system values
16(e.g. view, context, and request). """
116
10.6. ADDING AND CHANGING RENDERERS
The formal interface definition of the info object passed to a renderer factory constructor is available as pyramid.interfaces.IRendererInfo.
There are essentially two different kinds of renderer factories:
•A renderer factory which expects to accept an asset specification, or an absolute path, as the name attribute of the info object fed to its constructor. These renderer factories are registered with a name value that begins with a dot (.). These types of renderer factories usually relate to a file on the filesystem, such as a template.
•A renderer factory which expects to accept a token that does not represent a filesystem path or an asset specification in the name attribute of the info object fed to its constructor. These renderer factories are registered with a name value that does not begin with a dot. These renderer factories are typically object serializers.
Asset Specifications
An asset specification is a colon-delimited identifier for an asset. The colon separates a Python package name from a package subpath. For example, the asset specification my.package:static/baz.css identifies the file named baz.css in the static subdirectory of the my.package Python package.
Here’s an example of the registration of a simple renderer factory via add_renderer():
1
2
3
# config is an instance of pyramid.config.Configurator
config.add_renderer(name=’amf’, factory=’my.package.MyAMFRenderer’)
Adding the above code to your application startup configuration will allow you to use the my.package.MyAMFRenderer renderer factory implementation in view configurations. Your application can use this renderer by specifying amf in the renderer attribute of a view configuration:
1
2
3
4
5
from pyramid.view import view_config
@view_config(renderer=’amf’) def myview(request):
return {’Hello’:’world’}
At startup time, when a view configuration is encountered, which has a name attribute that does not contain a dot, the full name value is used to construct a renderer from the associated renderer factory. In this case, the view configuration will create an instance of an MyAMFRenderer for each view configuration
117
10. RENDERERS
which includes amf as its renderer value. The name passed to the MyAMFRenderer constructor will always be amf.
Here’s an example of the registration of a more complicated renderer factory, which expects to be passed a filesystem path:
1 config.add_renderer(name=’.jinja2’,
2 |
factory=’my.package.MyJinja2Renderer’) |
Adding the above code to your application startup will allow you to use the my.package.MyJinja2Renderer renderer factory implementation in view configurations by referring to any renderer which ends in .jinja in the renderer attribute of a view configuration:
1
2
3
4
5
from pyramid.view import view_config
@view_config(renderer=’templates/mytemplate.jinja2’) def myview(request):
return {’Hello’:’world’}
When a view configuration is encountered at startup time, which has a name attribute that does contain a dot, the value of the name attribute is split on its final dot. The second element of the split is typically the filename extension. This extension is used to look up a renderer factory for the configured view. Then the value of renderer is passed to the factory to create a renderer for the view. In this case, the view configuration will create an instance of a MyJinja2Renderer for each view configuration which includes anything ending with .jinja2 in its renderer value. The name passed to the MyJinja2Renderer constructor will be the full value that was set as renderer= in the view configuration.
10.6.2 Changing an Existing Renderer
You can associate more than one filename extension with the same existing renderer implementation as necessary if you need to use a different file extension for the same kinds of templates. For example, to associate the .zpt extension with the Chameleon ZPT renderer factory, use the pyramid.config.Configurator.add_renderer() method:
1 config.add_renderer(’.zpt’, ’pyramid.chameleon_zpt.renderer_factory’)
After you do this, Pyramid will treat templates ending in both the .pt and .zpt filename extensions as Chameleon ZPT templates.
To change the default mapping in which files with a .pt extension are rendered via a Chameleon ZPT page template renderer, use a variation on the following in your application’s startup code:
118