Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 337 lines (218 sloc) 10.886 kB
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
1 API
2 ===
3
4 .. module:: jinja2
5 :synopsis: public Jinja2 API
6
7 This document describes the API to Jinja2 and not the template language. It
8 will be most useful as reference to those implementing the template interface
9 to the application and not those who are creating Jinja2 templates.
10
11 Basics
12 ------
13
14 Jinja2 uses a central object called the template :class:`Environment`.
15 Instances of this class are used to store the configuration, global objects
16 and are used to load templates from the file system or other locations.
17 Even if you are creating templates from string by using the constructor of
18 :class:`Template` class, an environment is created automatically for you.
19
20 Most applications will create one :class:`Environment` object on application
21 initialization and use that to load templates. In some cases it's however
22 useful to have multiple environments side by side, if different configurations
23 are in use.
24
25 The simplest way to configure Jinja2 to load templates for your application
26 looks roughly like this::
27
28 from jinja2 import Environment, PackageLoader
29 env = Environment(loader=PackageLoader('yourapplication', 'templates'))
30
31 This will create a template environment with the default settings and a
32 loader that looks up the templates in the `templates` folder inside the
33 `yourapplication` python package. Different loaders are available
34 and you can also write your own if you want to load templates from a
35 database or other resources.
36
37 To load a template from this environment you just have to call the
38 :meth:`get_template` method which then returns the loaded :class:`Template`::
39
40 template = env.get_template('mytemplate.html')
41
42 To render it with some variables, just call the :meth:`render` method::
43
44 print template.render(the='variables', go='here')
45
46
47 High Level API
48 --------------
49
50 .. autoclass:: jinja2.environment.Environment
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
51 :members: from_string, get_template, join_path, overlay
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
52
53 .. attribute:: shared
54
55 If a template was created by using the :class:`Template` constructor
56 an environment is created automatically. These environments are
57 created as shared environments which means that multiple templates
58 may have the same anonymous environment. For all shared environments
59 this attribute is `True`, else `False`.
60
61 .. attribute:: sandboxed
62
63 If the environment is sandboxed this attribute is `True`. For the
64 sandbox mode have a look at the documentation for the
65 :class:`~jinja2.sandbox.SandboxedEnvironment`.
66
67 .. attribute:: filters
68
69 A dict of filters for this environment. As long as no template was
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
70 loaded it's safe to add new filters or remove old. For custom filters
71 see :ref:`writing-filters`.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
72
73 .. attribute:: tests
74
75 A dict of test funcitons for this environment. As long as no
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
76 template way loaded it's safe to modify this dict. For custom tests
77 see :ref:`writing-tests`.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
78
79 .. attribute:: globals
80
81 A dict of global variables. These variables are always available
82 in a template and (if the optimizer is enabled) may not be
83 override by templates. As long as no template was loaded it's safe
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
84 to modify this dict. For more details see :ref:`global-namespace`.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
85
86
87 .. autoclass:: jinja2.Template
d84ec46 @mitsuhiko again documentation updates fixed another python 2.4 bug. Imports ar…
authored
88 :members: render, stream, generate, module
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
89
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
90 .. attribute:: globals
91
92 foo
93
94 .. attribute:: name
95
96 foo
97
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
98
99 .. autoclass:: jinja2.environment.TemplateStream
100 :members: disable_buffering, enable_buffering
101
102
103 Undefined Types
104 ---------------
105
106 These classes can be used as undefined types. The :class:`Environment`
107 constructor takes an `undefined` parameter that can be one of those classes
108 or a custom subclass of :class:`Undefined`. Whenever the template engine is
109 unable to look up a name or access an attribute one of those objects is
110 created and returned. Some operations on undefined values are then allowed,
111 others fail.
112
113 The closest to regular Python behavior is the `StrictUndefined` which
114 disallows all operations beside testing if it's an undefined object.
115
116 .. autoclass:: jinja2.runtime.Undefined
117
118 .. autoclass:: jinja2.runtime.DebugUndefined
119
120 .. autoclass:: jinja2.runtime.StrictUndefined
121
122
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
123 The Context
124 -----------
125
19cf9c2 @mitsuhiko small performance improvements
authored
126 .. autoclass:: jinja2.runtime.Context
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
127 :members: super, get, get_exported, get_all
128
129 .. attribute:: parent
130
131 A dict of read only, global variables the template looks up. These
19cf9c2 @mitsuhiko small performance improvements
authored
132 can either come from another :class:`Context`, from the
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
133 :attr:`Environment.globals` or :attr:`Template.globals`. It must not
134 be altered.
135
136 .. attribute:: vars
137
138 The template local variables. This list contains environment and
139 context functions from the :attr:`parent` scope as well as local
140 modifications and exported variables from the template. The template
141 will modify this dict during template evaluation but filters and
142 context functions are not allowed to modify it.
143
144 .. attribute:: environment
145
146 The environment that loaded the template.
147
148 .. attribute:: exported_vars
149
150 This set contains all the names the template exports. The values for
151 the names are in the :attr:`vars` dict. In order to get a copy of the
152 exported variables as dict, :meth:`get_exported` can be used.
153
154 .. attribute:: name
155
156 The load name of the template owning this context.
157
158 .. attribute:: blocks
159
160 A dict with the current mapping of blocks in the template. The keys
161 in this dict are the names of the blocks, and the values a list of
162 blocks registered. The last item in each list is the current active
163 block (latest in the inheritance chain).
164
165
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
166 Loaders
167 -------
168
169 Loaders are responsible for loading templates from a resource such as the
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
170 file system. The environment will keep the compiled modules in memory like
171 Python's `sys.modules`. Unlike `sys.modules` however this cache is limited in
172 size by default and templates are automatically reloaded.
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
173
174 .. autoclass:: jinja2.loaders.FileSystemLoader
175
176 .. autoclass:: jinja2.loaders.PackageLoader
177
178 .. autoclass:: jinja2.loaders.DictLoader
179
180 .. autoclass:: jinja2.loaders.FunctionLoader
181
182 .. autoclass:: jinja2.loaders.PrefixLoader
183
184 .. autoclass:: jinja2.loaders.ChoiceLoader
185
186 All loaders are subclasses of :class:`BaseLoader`. If you want to create your
187 own loader, subclass :class:`BaseLoader` and override `get_source`.
188
189 .. autoclass:: jinja2.loaders.BaseLoader
190 :members: get_source, load
191
192
193 Utilities
194 ---------
195
196 These helper functions and classes are useful if you add custom filters or
197 functions to a Jinja2 environment.
198
199 .. autofunction:: jinja2.filters.environmentfilter
200
201 .. autofunction:: jinja2.filters.contextfilter
202
203 .. autofunction:: jinja2.utils.environmentfunction
204
205 .. autofunction:: jinja2.utils.contextfunction
206
207 .. function:: escape(s)
208
209 Convert the characters &, <, >, and " in string s to HTML-safe sequences.
210 Use this if you need to display text that might contain such characters
211 in HTML. This function will not escaped objects that do have an HTML
212 representation such as already escaped data.
213
187bde1 @mitsuhiko added cache_clear function
authored
214 .. autofunction:: jinja2.utils.clear_caches
215
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
216 .. autoclass:: jinja2.utils.Markup
217
218
219 Exceptions
220 ----------
221
222 .. autoclass:: jinja2.exceptions.TemplateError
223
224 .. autoclass:: jinja2.exceptions.UndefinedError
225
226 .. autoclass:: jinja2.exceptions.TemplateNotFound
227
228 .. autoclass:: jinja2.exceptions.TemplateSyntaxError
229
230 .. autoclass:: jinja2.exceptions.TemplateAssertionError
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
231
232
233 .. _writing-filters:
234
235 Custom Filters
236 --------------
237
238 Custom filters are just regular Python functions that take the left side of
239 the filter as first argument and the the arguments passed to the filter as
240 extra arguments or keyword arguments.
241
242 For example in the filter ``{{ 42|myfilter(23) }}`` the function would be
243 called with ``myfilter(42, 23)``. Here for example a simple filter that can
244 be applied to datetime objects to format them::
245
246 def datetimeformat(value, format='%H:%M / %d-%m-%Y'):
247 return value.strftime(format)
248
249 You can register it on the template environment by updating the
250 :attr:`~Environment.filters` dict on the environment::
251
252 environment.filters['datetimeformat'] = datetimeformat
253
254 Inside the template it can then be used as follows:
255
256 .. sourcecode:: jinja
257
258 written on: {{ article.pub_date|datetimeformat }}
259 publication date: {{ article.pub_date|datetimeformat('%d-%m-%Y') }}
260
261 Filters can also be passed the current template context or environment. This
262 is useful if a filters wants to return an undefined value or check the current
263 :attr:`~Environment.autoescape` setting. For this purpose two decorators
264 exist: :func:`environmentfilter` and :func:`contextfilter`.
265
266 Here a small example filter that breaks a text into HTML line breaks and
267 paragraphs and marks the return value as safe HTML string if autoescaping is
268 enabled::
269
270 import re
271 from jinja2 import environmentfilter, Markup, escape
272
273 _paragraph_re = re.compile(r'(?:\r\n|\r|\n){2,}')
274
275 @environmentfilter
276 def nl2br(environment, value):
277 result = u'\n\n'.join(u'<p>%s</p>' % p.replace('\n', '<br>\n')
278 for p in _paragraph_re.split(escape(value)))
279 if environment.autoescape:
280 result = Markup(result)
281 return result
282
283 Context filters work the same just that the first argument is the current
19cf9c2 @mitsuhiko small performance improvements
authored
284 active :class:`Context` rather then the environment.
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
285
286
287 .. _writing-tests:
288
289 Custom Tests
290 ------------
291
292 Tests work like filters just that there is no way for a filter to get access
293 to the environment or context and that they can't be chained. The return
294 value of a filter should be `True` or `False`. The purpose of a filter is to
295 give the template designers the possibility to perform type and conformability
296 checks.
297
298 Here a simple filter that checks if a variable is a prime number::
299
300 import math
301
302 def is_prime(n):
303 if n == 2:
304 return True
305 for i in xrange(2, int(math.ceil(math.sqrt(n))) + 1):
306 if n % i == 0:
307 return False
308 return True
309
310
311 You can register it on the template environment by updating the
312 :attr:`~Environment.tests` dict on the environment::
313
314 environment.tests['prime'] = is_prime
315
316 A template designer can then use the test like this:
317
318 .. sourcecode:: jinja
319
320 {% if 42 is prime %}
321 42 is a prime number
322 {% else %}
323 42 is not a prime number
324 {% endif %}
325
326
327 .. _global-namespace:
328
329 The Global Namespace
330 --------------------
331
332 Variables stored in the :attr:`Environment.globals` or :attr:`Template.globals`
333 dicts are special as they are available for imported templates too and will be
334 used by the optimizer in future releases to evaluates parts of the template at
335 compile time. This is the place where you can put variables and functions
336 that should be available all the time.
Something went wrong with that request. Please try again.