Pyramid푐ℎ푎푚푒푙푒표푛퐷표푐푢푚푒푛푡푎푡푖표푛 Release 0.4.Dev0
Total Page:16
File Type:pdf, Size:1020Kb
pyramidchameleonDocumentation Release 0.4.dev0 Pylons Project Contributors January 06, 2021 Contents 1 Overview 1 2 Installation 3 3 Setup 5 4 Using Chameleon templates 7 5 More information 17 6 Reporting bugs / development versions 19 Python Module Index 21 Index 23 i ii CHAPTER 1 Overview pyramid_chameleon is a set of bindings that make templates written for the Chameleon templating system work under the Pyramid web framework. 1 pyramidchameleonDocumentation; Release0:4:dev0 2 Chapter 1. Overview CHAPTER 2 Installation Install using setuptools, e.g. (within a virtualenv): $ $myvenv/bin/easy_install pyramid_chameleon 3 pyramidchameleonDocumentation; Release0:4:dev0 4 Chapter 2. Installation CHAPTER 3 Setup There are several ways to make sure that pyramid_chameleon is active. They are completely equivalent: 1) Add pyramid_chameleon to the pyramid.includes section of your applications main configuration section: [app:main] ... pyramid.includes= pyramid_chameleon 2) Use the includeme function via config.include: config.include('pyramid_chameleon') Once activated, files with the .pt extension are considered to be Chameleon templates. 5 pyramidchameleonDocumentation; Release0:4:dev0 6 Chapter 3. Setup CHAPTER 4 Using Chameleon templates Once pyramid_chameleon been activated .pt templates can be loaded either by looking up names that would be found on the Chameleon search path or by looking up an absolute asset specification (see Understanding Asset Specifications for more information). Quick example 1. Look up a template named foo.pt within the templates directory of a Python package named mypackage: 1 @view_config(renderer="mypackage:templates/foo.pt) 2 def sample_view(request): 3 return {'foo':1,'bar':2} Quick example 2. Look up a template named foo.pt within the templates directory of the "current" Python package (the package in which this Python code is defined): 1 @view_config(renderer="templates/foo.pt) 2 def sample_view(request): 3 return {'foo':1,'bar':2} Quick example 3: manufacturing a response object using the result of render() (a string) using a Chameleon template: 1 from pyramid.renderers import render 2 from pyramid.response import Response 3 4 def sample_view(request): 5 result= render('mypackage:templates/foo.pt', 6 {'foo':1,'bar':2}, 7 request=request) 8 response= Response(result) 9 response.content_type='text/plain' 10 return response Here’s an example view configuration which uses a Chameleon ZPT renderer registered imperatively: 7 pyramidchameleonDocumentation; Release0:4:dev0 1 # config is an instance of pyramid.config.Configurator 2 3 config.add_view('myproject.views.sample_view', 4 renderer='myproject:templates/foo.pt') Here’s an example view configuration which uses a Chameleon text renderer registered imperatively: 1 config.add_view('myproject.views.sample_view', 2 renderer='myproject:templates/foo.txt') 4.1 Chameleon ZPT templates Chameleon is an implementation of ZPT (Zope Page Templates) templating language. The Chameleon engine com- plies largely with the Zope Page Template template specification. However, it is significantly faster than the default implementation that is represented by zope.pagetemplates. 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 from pyramid.view import view_config 2 3 @view_config(renderer='templates/foo.pt') 4 def my_view(request): 5 return {'foo':1,'bar':2} Two built-in renderers exist for Chameleon templates. If the renderer parameter of a view configuration is an absolute path, a relative path or asset specification which has a final path element with a filename extension of .pt, the Chameleon ZPT renderer is used. If the extension is .txt, the Chameleon text renderer is used. The behavior of these renderers is the same, except for the engine used to render the template. When a Chameleon renderer is used in a view configuration, the view must return a Response object or a Python dictionary. If the view callable with an associated template returns a Python dictionary, the named template will be passed the dictionary as its keyword arguments, and the template renderer implementation will return the resulting rendered template in a response to the user. If the view callable returns anything but a Response object or a dictionary, an error will be raised. Before passing keywords to the template, the keyword arguments derived from the dictionary returned by the view are augmented. The callable object – whatever object was used to define the view – will be automatically inserted into the set of keyword arguments passed to the template as the view keyword. If the view callable was a class, the view key- word will be an instance of that class. Also inserted into the keywords passed to the template are renderer_name (the string used in the renderer attribute of the directive), renderer_info (an object containing renderer-related information), context (the context resource of the view used to render the template), and request (the request passed to the view used to render the template). request is also available as req in Pyramid 1.3+. 4.1.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" (continues on next page) 8 Chapter 4. Using Chameleon templates pyramidchameleonDocumentation; Release0:4:dev0 (continued from previous page) 4 xmlns: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 11 application generated by the <a 12 href="http://docs.pylonsproject.org/projects/pyramid/current/" 13 >pyramid</a> web 14 application framework.</h1> 15 </body> 16 </html> Note the use of Mako and/or 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. 4.1.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 from pyramid.renderers import get_renderer 2 from pyramid.view import view_config 3 4 @view_config(renderer='templates/mytemplate.pt') 5 def my_view(request): 6 main= get_renderer('templates/master.pt').implementation() 7 return {'main':main} Where templates/master.pt might look like so: 1 <html xmlns="http://www.w3.org/1999/xhtml" 2 xmlns:tal="http://xml.zope.org/namespaces/tal" 3 xmlns:metal="http://xml.zope.org/namespaces/metal"> 4 <head> 5 </head> 6 <body> 7 <div metal:define-macro="hello"> 8 <h1> 9 Hello <span metal:define-slot="name">Fred</span>! 10 </h1> 11 </div> 12 </body> 13 </html> 4.1. Chameleon ZPT templates 9 pyramidchameleonDocumentation; Release0:4:dev0 And templates/mytemplate.pt might look like so: 1 <html xmlns="http://www.w3.org/1999/xhtml" 2 xmlns:tal="http://xml.zope.org/namespaces/tal" 3 xmlns:metal="http://xml.zope.org/namespaces/metal"> 4 <head> 5 </head> 6 <body> 7 <span metal:use-macro="main.macros['hello']"> 8 <span metal:fill-slot="name">Chris</span> 9 </span> 10 </body> 11 </html> 4.1.3 Using a master page You can also use macros and slots to create a master page that can be used by all your templates. This is very similar to using a macro from another template but uses the IBeforeRender event subscriber to make the macros available to any template. 1 from pyramid.renderers import get_renderer 2 from pyramid.interfaces import IBeforeRender 3 from pyramid.events import subscriber 4 5 @subscriber(IBeforeRender) 6 def globals_factory(event): 7 master= get_renderer('templates/master.pt').implementation() 8 event['master']= master Where templates/master.pt provides a whole page with slots to be filled by views: 1 <!DOCTYPE html> 2 <html> 3 <head> 4 <title metal:define-slot="title" 5 tal:content="context/title | python:None"> Title goes here </title> 6 <meta tal:attributes="description context/description | python:None"> 7 8 <link rel="stylesheet" href="/site/css/screen.css" media="screen"> 9 <link rel="stylesheet" href="/site/css/print.css" media="print"> 10 11 <metal:slot metal:define-slot="script" /> 12 <metal:slot metal:define-slot="css" /> 13 14 </head> 15 <body> 16 <nav> 17 <ul> 18 <li><a href="/">Home</a></li> 19 </ul> 20 </nav> 21 <section id="content"> 22 <metal:slot metal:define-slot="body" /> 23 </section> 24 <footer>© Pylons Project</footer> 25 </body> 26 </html> 10 Chapter 4. Using Chameleon templates pyramidchameleonDocumentation; Release0:4:dev0 And templates/index.pt fills the relevant slots: 1 <metal:macro use-macro="master"> 2 <metal:slot fill-slot="title"> 3 <title>Welcome to Pyramid Chameleon</title> 4 </metal:slot> 5 6 <metal:slot fill-slot="body"> 7 <h1>Pyramid Chameleon</h1> 8 <p>Chameleon is an XML-based templating language</p> 9 </metal:slot> 10 </metal:macro> 4.2 Chameleon text templates pyramid_chameleon also allows for the use of templates which are composed entirely of non-XML text via Chameleon.