Skip to content
This repository
Newer
Older
100644 149 lines (103 sloc) 5.216 kb
3c8b7ade »
2008-04-28 first version of the jinja2 docs
1 Introduction
2 ============
3
4 This is the documentation for the Jinja2 general purpose templating language.
5 Jinja2 is a library for Python 2.4 and onwards that is designed to be flexible,
6 fast and secure.
7
8 If you have any exposure to other text-based template languages, such as Smarty or
9 Django, you should feel right at home with Jinja2. It's both designer and
10 developer friendly by sticking to Python's principles and adding functionality
11 useful for templating environments.
12
13 Prerequisites
14 -------------
15
16 Jinja2 needs at least **Python 2.4** to run. Additionally a working C-compiler
10c34da7 »
2010-08-17 Documented switch to MarkupSafe
17 that can create python extensions should be installed for the debugger if you
18 are using Python 2.4.
3c8b7ade »
2008-04-28 first version of the jinja2 docs
19
656d5e7c »
2010-02-09 Some tiny documentation fixes (unicode -> Unicode)
20 If you don't have a working C-compiler and you are trying to install the source
10c34da7 »
2010-08-17 Documented switch to MarkupSafe
21 release with the debugsupport you will get a compiler error.
56d01078 »
2008-11-23 Updated documentation to reflect the new speedups installation behavior.
22
3c8b7ade »
2008-04-28 first version of the jinja2 docs
23 .. _ctypes: http://python.net/crew/theller/ctypes/
24
25
ed98cac7 »
2008-05-07 some documentation updates
26 Installation
27 ------------
28
29 You have multiple ways to install Jinja2. If you are unsure what to do, go
30 with the Python egg or tarball.
31
32 As a Python egg (via easy_install)
33 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34
56d01078 »
2008-11-23 Updated documentation to reflect the new speedups installation behavior.
35 You can install the most recent Jinja2 version using `easy_install`_ or `pip`_::
ed98cac7 »
2008-05-07 some documentation updates
36
86b5cb53 »
2009-09-13 (codename Kong, released on September 12th 2009)
37 easy_install Jinja2
38 pip install Jinja2
ed98cac7 »
2008-05-07 some documentation updates
39
40 This will install a Jinja2 egg in your Python installation's site-packages
41 directory.
42
56d01078 »
2008-11-23 Updated documentation to reflect the new speedups installation behavior.
43 (If you are installing from the windows command line omit the `sudo` and make
44 sure to run the command as user with administrator rights)
45
ed98cac7 »
2008-05-07 some documentation updates
46 From the tarball release
47 ~~~~~~~~~~~~~~~~~~~~~~~~~
48
49 1. Download the most recent tarball from the `download page`_
50 2. Unpack the tarball
51 3. ``sudo python setup.py install``
52
0045216c »
2010-02-10 Documentation recommends distribute now.
53 Note that you either have to have setuptools or `distribute`_ installed,
54 the latter is preferred.
ed98cac7 »
2008-05-07 some documentation updates
55
56 This will install Jinja2 into your Python installation's site-packages directory.
57
0045216c »
2010-02-10 Documentation recommends distribute now.
58 .. _distribute: http://pypi.python.org/pypi/distribute
59
ed98cac7 »
2008-05-07 some documentation updates
60 Installing the development version
61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
d811ab5d »
2010-10-17 Changed links to github
63 1. Install `git`_
64 2. ``git clone git://github.com/mitsuhiko/jinja2.git``
ed98cac7 »
2008-05-07 some documentation updates
65 3. ``cd jinja2``
66 4. ``ln -s jinja2 /usr/lib/python2.X/site-packages``
67
68 As an alternative to steps 4 you can also do ``python setup.py develop``
0045216c »
2010-02-10 Documentation recommends distribute now.
69 which will install the package via distribute in development mode. This also
ed98cac7 »
2008-05-07 some documentation updates
70 has the advantage that the C extensions are compiled.
71
0aa0f58a »
2009-03-18 Applied documentation patches by Clemens Hermann.
72 .. _download page: http://pypi.python.org/pypi/Jinja2
ed98cac7 »
2008-05-07 some documentation updates
73 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
74 .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
56d01078 »
2008-11-23 Updated documentation to reflect the new speedups installation behavior.
75 .. _pip: http://pypi.python.org/pypi/pip
54a13bce »
2010-10-17 Fixed link to git
76 .. _git: http://git-scm.org/
ed98cac7 »
2008-05-07 some documentation updates
77
56d01078 »
2008-11-23 Updated documentation to reflect the new speedups installation behavior.
78
10c34da7 »
2010-08-17 Documented switch to MarkupSafe
79 More Speed with MarkupSafe
79cc8d16 » birkenfeld
2009-10-19 Fix typo.
80 ~~~~~~~~~~~~~~~~~~~~~~~~~~
56d01078 »
2008-11-23 Updated documentation to reflect the new speedups installation behavior.
81
10c34da7 »
2010-08-17 Documented switch to MarkupSafe
82 As of version 2.5.1 Jinja2 will check for an installed `MarkupSafe`_
83 module. If it can find it, it will use the Markup class of that module
84 instead of the one that comes with Jinja2. `MarkupSafe` replaces the
85 older speedups module that came with Jinja2 and has the advantage that is
86 has a better setup script and will automatically attempt to install the C
87 version and nicely fall back to a pure Python implementation if that is
88 not possible.
89
90 The C implementation of MarkupSafe is much faster and recommended when
91 using Jinja2 with autoescaping.
92
93 .. _MarkupSafe: http://pypi.python.org/pypi/MarkupSafe
94
95
96 Enable the debug support Module
97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98
99 By default Jinja2 will not compile the debug support module. Enabling this
56d01078 »
2008-11-23 Updated documentation to reflect the new speedups installation behavior.
100 will fail if you don't have the Python headers or a working compiler. This
101 is often the case if you are installing Jinja2 from a windows machine.
102
10c34da7 »
2010-08-17 Documented switch to MarkupSafe
103 Because the debug support is only necessary for Python 2.4 you will not
104 have to do this unless you run 2.4::
56d01078 »
2008-11-23 Updated documentation to reflect the new speedups installation behavior.
105
10c34da7 »
2010-08-17 Documented switch to MarkupSafe
106 sudo python setup.py --with-debugsupport install
56d01078 »
2008-11-23 Updated documentation to reflect the new speedups installation behavior.
107
ed98cac7 »
2008-05-07 some documentation updates
108
3c8b7ade »
2008-04-28 first version of the jinja2 docs
109 Basic API Usage
110 ---------------
111
4dcc237b »
2008-05-26 fixed linking in jinja docs for the intro
112 This section gives you a brief introduction to the Python API for Jinja2
113 templates.
3c8b7ade »
2008-04-28 first version of the jinja2 docs
114
115 The most basic way to create a template and render it is through
4dcc237b »
2008-05-26 fixed linking in jinja docs for the intro
116 :class:`~jinja2.Template`. This however is not the recommended way to
117 work with it if your templates are not loaded from strings but the file
118 system or another data source:
3c8b7ade »
2008-04-28 first version of the jinja2 docs
119
120 >>> from jinja2 import Template
121 >>> template = Template('Hello {{ name }}!')
122 >>> template.render(name='John Doe')
123 u'Hello John Doe!'
124
4dcc237b »
2008-05-26 fixed linking in jinja docs for the intro
125 By creating an instance of :class:`~jinja2.Template` you get back a new template
126 object that provides a method called :meth:`~jinja2.Template.render` which when
3c8b7ade »
2008-04-28 first version of the jinja2 docs
127 called with a dict or keyword arguments expands the template. The dict
128 or keywords arguments passed to the template are the so-called "context"
129 of the template.
61a5a24a »
2008-05-26 fixed a bug in error reporting and some small documentation updates
130
131 What you can see here is that Jinja2 is using unicode internally and the
132 return value is an unicode string. So make sure that your application is
133 indeed using unicode internally.
eb43b12f »
2010-02-10 Added Python 3 section to the documentation.
134
135
136 Experimental Python 3 Support
137 -----------------------------
138
139 Jinja 2.3 brings experimental support for Python 3. It means that all
140 unittests pass on the new version, but there might still be small bugs in
141 there and behavior might be inconsistent. If you notice any bugs, please
142 provide feedback in the `Jinja bug tracker`_.
143
144 Also please keep in mind that the documentation is written with Python 2
145 in mind, you will have to adapt the shown code examples to Python 3 syntax
146 for yourself.
147
148
d811ab5d »
2010-10-17 Changed links to github
149 .. _Jinja bug tracker: http://github.com/mitsuhiko/jinja2/issues
Something went wrong with that request. Please try again.