1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
Templates
=========
A :term:`template` is a usually file on disk which can be used to
render data provided by a :term:`view`, surrounded by more static
information.
Templating With :term:`Chameleon` (:term:`chameleon.zpt`) Page Templates
------------------------------------------------------------------------
Like Zope, :mod:`repoze.bfg` uses Zope Page Templates (:term:`ZPT`) as
its default and best-supported templating language. However,
:mod:`repoze.bfg` uses a different implementation of the :term:`ZPT`
specification than Zope does: the :term:`Chameleon`
:term:`chameleon.zpt` templating engine. This templating engine
complies with the `Zope Page Template
<http://wiki.zope.org/ZPT/FrontPage>`_ template specification and is
significantly faster.
.. note:: :mod:`repoze.bfg` can also allow for the use of Genshi-style
templates via the ``chameleon.genshi`` package, support for which
is built-in to :mod:`repoze.bfg`. The :mod:`repoze.bfg` API
functions for getting and rendering Chameleon Genshi-style
templates mirrors the Chameleon ZPT-style API completely; only the
template files themselves must differ. See :ref:`template_module`
for more information about using Genshi-style templates within
:mod:`repoze.bfg`.
Given that there is a :term:`chameleon.zpt` template named
``foo.html`` in a directory in your application named ``templates``,
you can render the template from a view like so:
.. code-block:: python
:linenos:
from repoze.bfg.chameleon_zpt import render_template_to_response
def sample_view(context, request):
return render_template_to_response('templates/foo.html', foo=1, bar=2)
The first argument to ``render_template_to_response`` shown above (and
its sister function ``render_template``, not shown, which just returns
a string body) is the template *path*. Above, the path
``templates/foo.html`` is *relative*. Relative to what, you ask?
Relative to the directory in which the ``views.py`` file which names
it lives, which is usually the :mod:`repoze.bfg` application's
:term:`package` directory.
``render_template_to_response`` always renders a :term:`chameleon.zpt`
template, and always returns a Response object which has a *status
code* of ``200 OK`` and a *content-type* of ``text-html``. If you
need more control over the status code and content-type, use the
``render_template`` function instead, which also renders a ZPT
template but returns a string instead of a Response. You can use the
string manually as a response body:
.. code-block:: python
:linenos:
from repoze.bfg.chameleon_zpt import render_template
from webob import Response
def sample_view(context, request):
result = render_template('templates/foo.html', foo=1, bar=2)
response = Response(result)
response.content_type = 'text/plain'
return response
:mod:`repoze.bfg` loads the template and keeps it in memory between
requests. This means that modifications to the ZPT require a restart
before you can see the changes.
Templating with XSLT
------------------------
:mod:`repoze.bfg` also supports XSLT as an optional templating
language. Like ZPT, an XSLT template is loaded once and re-used
between requests.
Given a template ``foo.xsl`` in the templates directory, you can render
an XSLT as follows:
.. code-block:: python
:linenos:
from repoze.bfg.xslt import render_transform_to_response
from lxml import etree
node = etree.Element("root")
return render_transform_to_response('templates/foo.xsl', node)
As shown, the second argument to ``render_transform_to_response`` is
the element (and children) that you want as the top of the data for
the XSLT.
You can also pass XSLT parameters in as keyword arguments:
.. code-block:: python
:linenos:
from repoze.bfg.xslt import render_transform_to_response
from lxml import etree
node = etree.Element("root")
value1 = "'app1'"
return render_transform_to_response('templates/foo.xsl', node, param1=value1)
This would then assign 'app1' as the value of an ``<xsl:param
name="param1"/>`` parameter in the XSLT template.
.. _reload_templates_section:
Automatically Reloading Templates
---------------------------------
It's often convenient to see changes you make to a template file
appear immediately without needing to restart the application process.
:mod:`repoze.bfg` allows you configure your application development
environment so that a change to a template will be automatically
detected, and the template will be reloaded on the next rendering.
.. warning:: auto-template-reload behavior is not recommended for
production sites as it slows rendering; it's usually only
desirable during development.
In order to turn on automatic reloading of templates, you can use an
environment variable setting or a configuration file setting.
To use an environment variable, start your application under a shell
using the ``BFG_RELOAD_TEMPLATES`` environment variable set to ``1``,
For example::
$ BFG_RELOAD_TEMPLATES=1 bin/paster serve myproject.ini
To use a setting in the the application ``.ini`` file for the same
purpose, set the ``reload_templates`` key to ``true`` within the
application's configuration section, e.g.::
[app:main]
use = egg:MyProject#app
reload_templates = true
Using Text Templates
--------------------
:mod:`repoze.bfg` also allows for the use of templates which are
composed entirely of non-XML text via :term:`Chameleon`. To do so,
you can create templates that are entirely composed of text except for
``${name}`` -style substitution points. The rendering API is a mirror
of the ZPT rendering facility, it's just imported from another place;
see :ref:`template_module` for more information.
Templating with other Templating Languages
------------------------------------------
Because :term:`view` functions are typically the only code in
:mod:`repoze.bfg` that need to know anything about templates, and
because view functions are very simple Python, you can use whatever
templating system you're most comfortable with within
:mod:`repoze.bfg`. Install the templating system, import its API
functions into your views module, use those APIs to generate a string,
then return that string as the body of a :term:`WebOb` ``Response``
object. Assuming you have `Mako <http://www.makotemplates.org/>`_
installed, here's an example of using Mako from within a
:mod:`repoze.bfg` :term:`view`:
.. code-block:: python
:linenos:
from mako.template import Template
from webob import Response
def make_view(context, request):
template = Template(filename='/templates/template.mak')
result = template.render(name=context.name)
response = Response(result)
return response
.. note:: It's reasonably easy to write custom templating system
binding packages for use under :mod:`repoze.bfg`. See
`repoze.bfg.jinja2
<http://svn.repoze.org/repoze.bfg.jinja2/trunk/>`_ for an example
of one such package. This particular one creates
:mod:`repoze.bfg`-style bindings for the `Jinja2
<http://jinja.pocoo.org/2/documentation>`_ templating system.
Note that if you use third-party templating languages, the
auto-template-reload strategy explained in
:ref:`reload_templates_section` will not be available.
|
