Armin Ronacher | 3c8b7ad | 2008-04-28 13:52:21 +0200 | [diff] [blame] | 1 | Introduction |
| 2 | ============ |
| 3 | |
| 4 | This is the documentation for the Jinja2 general purpose templating language. |
Thomas Waldmann | 50f6965 | 2013-05-18 01:07:52 +0200 | [diff] [blame] | 5 | Jinja2 is a library for Python that is designed to be flexible, fast and secure. |
Armin Ronacher | 3c8b7ad | 2008-04-28 13:52:21 +0200 | [diff] [blame] | 6 | |
| 7 | If you have any exposure to other text-based template languages, such as Smarty or |
| 8 | Django, you should feel right at home with Jinja2. It's both designer and |
| 9 | developer friendly by sticking to Python's principles and adding functionality |
| 10 | useful for templating environments. |
| 11 | |
Armin Ronacher | 3c8b7ad | 2008-04-28 13:52:21 +0200 | [diff] [blame] | 12 | Prerequisites |
| 13 | ------------- |
| 14 | |
Armin Ronacher | fe63b44 | 2013-05-19 12:29:55 +0100 | [diff] [blame] | 15 | Jinja2 works with Python 2.6.x, 2.7.x and >= 3.3. If you are using Python |
Armin Ronacher | d76b8da | 2013-05-20 12:15:50 +0100 | [diff] [blame] | 16 | 3.2 you can use an older release of Jinja2 (2.6) as support for Python 3.2 |
| 17 | was dropped in Jinja2 version 2.7. |
Armin Ronacher | 3c8b7ad | 2008-04-28 13:52:21 +0200 | [diff] [blame] | 18 | |
Armin Ronacher | fe63b44 | 2013-05-19 12:29:55 +0100 | [diff] [blame] | 19 | If you wish to use the :class:`~jinja2.PackageLoader` class, you will also |
Carl A Dunham | d546358 | 2014-01-18 15:26:10 -0600 | [diff] [blame] | 20 | need `setuptools`_ or `distribute`_ installed at runtime. |
Thomas Waldmann | 50f6965 | 2013-05-18 01:07:52 +0200 | [diff] [blame] | 21 | |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 22 | Installation |
| 23 | ------------ |
| 24 | |
| 25 | You have multiple ways to install Jinja2. If you are unsure what to do, go |
| 26 | with the Python egg or tarball. |
| 27 | |
Carl A Dunham | d546358 | 2014-01-18 15:26:10 -0600 | [diff] [blame] | 28 | As a Python egg (via `easy_install`) |
| 29 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 30 | |
Armin Ronacher | 56d0107 | 2008-11-23 13:25:51 +0100 | [diff] [blame] | 31 | You can install the most recent Jinja2 version using `easy_install`_ or `pip`_:: |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 32 | |
Armin Ronacher | 86b5cb5 | 2009-09-13 00:23:27 -0700 | [diff] [blame] | 33 | easy_install Jinja2 |
| 34 | pip install Jinja2 |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 35 | |
| 36 | This will install a Jinja2 egg in your Python installation's site-packages |
| 37 | directory. |
| 38 | |
Mike Chesnut | d329a3e | 2012-12-18 13:52:07 -0800 | [diff] [blame] | 39 | (If you are installing from the Windows command line omit the `sudo` and make |
Armin Ronacher | 56d0107 | 2008-11-23 13:25:51 +0100 | [diff] [blame] | 40 | sure to run the command as user with administrator rights) |
| 41 | |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 42 | From the tarball release |
| 43 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 44 | |
| 45 | 1. Download the most recent tarball from the `download page`_ |
| 46 | 2. Unpack the tarball |
| 47 | 3. ``sudo python setup.py install`` |
| 48 | |
Carl A Dunham | d546358 | 2014-01-18 15:26:10 -0600 | [diff] [blame] | 49 | Note that you either have to have `setuptools` or `distribute` installed; |
Armin Ronacher | 0045216 | 2010-02-10 02:06:06 +0100 | [diff] [blame] | 50 | the latter is preferred. |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 51 | |
| 52 | This will install Jinja2 into your Python installation's site-packages directory. |
| 53 | |
| 54 | Installing the development version |
| 55 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 56 | |
Armin Ronacher | d811ab5 | 2010-10-17 16:07:08 +0200 | [diff] [blame] | 57 | 1. Install `git`_ |
José Carlos García | c5a860c | 2016-04-04 01:21:39 +0200 | [diff] [blame] | 58 | 2. ``git clone git://github.com/pallets/jinja.git`` |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 59 | 3. ``cd jinja2`` |
| 60 | 4. ``ln -s jinja2 /usr/lib/python2.X/site-packages`` |
| 61 | |
| 62 | As an alternative to steps 4 you can also do ``python setup.py develop`` |
Carl A Dunham | d546358 | 2014-01-18 15:26:10 -0600 | [diff] [blame] | 63 | which will install the package via `distribute` in development mode. This also |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 64 | has the advantage that the C extensions are compiled. |
| 65 | |
Armin Ronacher | 0aa0f58 | 2009-03-18 01:01:36 +0100 | [diff] [blame] | 66 | .. _download page: http://pypi.python.org/pypi/Jinja2 |
Carl A Dunham | d546358 | 2014-01-18 15:26:10 -0600 | [diff] [blame] | 67 | .. _distribute: http://pypi.python.org/pypi/distribute |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 68 | .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools |
| 69 | .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall |
Armin Ronacher | 56d0107 | 2008-11-23 13:25:51 +0100 | [diff] [blame] | 70 | .. _pip: http://pypi.python.org/pypi/pip |
Armin Ronacher | 54a13bc | 2010-10-17 16:07:38 +0200 | [diff] [blame] | 71 | .. _git: http://git-scm.org/ |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 72 | |
Armin Ronacher | 56d0107 | 2008-11-23 13:25:51 +0100 | [diff] [blame] | 73 | |
Armin Ronacher | cd7bf5b | 2013-05-19 13:51:47 +0100 | [diff] [blame] | 74 | MarkupSafe Dependency |
| 75 | ~~~~~~~~~~~~~~~~~~~~~ |
Armin Ronacher | 56d0107 | 2008-11-23 13:25:51 +0100 | [diff] [blame] | 76 | |
Armin Ronacher | cd7bf5b | 2013-05-19 13:51:47 +0100 | [diff] [blame] | 77 | As of version 2.7 Jinja2 depends on the `MarkupSafe`_ module. If you |
| 78 | install Jinja2 via `pip` or `easy_install` it will be installed |
| 79 | automatically for you. |
Armin Ronacher | 10c34da | 2010-08-17 12:10:27 +0200 | [diff] [blame] | 80 | |
| 81 | .. _MarkupSafe: http://pypi.python.org/pypi/MarkupSafe |
| 82 | |
Armin Ronacher | 3c8b7ad | 2008-04-28 13:52:21 +0200 | [diff] [blame] | 83 | Basic API Usage |
| 84 | --------------- |
| 85 | |
Armin Ronacher | 4dcc237 | 2008-05-26 13:59:26 +0200 | [diff] [blame] | 86 | This section gives you a brief introduction to the Python API for Jinja2 |
| 87 | templates. |
Armin Ronacher | 3c8b7ad | 2008-04-28 13:52:21 +0200 | [diff] [blame] | 88 | |
| 89 | The most basic way to create a template and render it is through |
Armin Ronacher | 4dcc237 | 2008-05-26 13:59:26 +0200 | [diff] [blame] | 90 | :class:`~jinja2.Template`. This however is not the recommended way to |
| 91 | work with it if your templates are not loaded from strings but the file |
| 92 | system or another data source: |
Armin Ronacher | 3c8b7ad | 2008-04-28 13:52:21 +0200 | [diff] [blame] | 93 | |
| 94 | >>> from jinja2 import Template |
| 95 | >>> template = Template('Hello {{ name }}!') |
| 96 | >>> template.render(name='John Doe') |
| 97 | u'Hello John Doe!' |
| 98 | |
Armin Ronacher | 4dcc237 | 2008-05-26 13:59:26 +0200 | [diff] [blame] | 99 | By creating an instance of :class:`~jinja2.Template` you get back a new template |
| 100 | object that provides a method called :meth:`~jinja2.Template.render` which when |
Armin Ronacher | 3c8b7ad | 2008-04-28 13:52:21 +0200 | [diff] [blame] | 101 | called with a dict or keyword arguments expands the template. The dict |
| 102 | or keywords arguments passed to the template are the so-called "context" |
| 103 | of the template. |
Armin Ronacher | 61a5a24 | 2008-05-26 12:07:44 +0200 | [diff] [blame] | 104 | |
| 105 | What you can see here is that Jinja2 is using unicode internally and the |
| 106 | return value is an unicode string. So make sure that your application is |
| 107 | indeed using unicode internally. |
Armin Ronacher | eb43b12 | 2010-02-10 02:10:48 +0100 | [diff] [blame] | 108 | |
| 109 | |
| 110 | Experimental Python 3 Support |
| 111 | ----------------------------- |
| 112 | |
Thomas Waldmann | 50f6965 | 2013-05-18 01:07:52 +0200 | [diff] [blame] | 113 | Jinja 2.7 brings experimental support for Python >=3.3. It means that all |
Armin Ronacher | eb43b12 | 2010-02-10 02:10:48 +0100 | [diff] [blame] | 114 | unittests pass on the new version, but there might still be small bugs in |
| 115 | there and behavior might be inconsistent. If you notice any bugs, please |
| 116 | provide feedback in the `Jinja bug tracker`_. |
| 117 | |
| 118 | Also please keep in mind that the documentation is written with Python 2 |
Carl A Dunham | d546358 | 2014-01-18 15:26:10 -0600 | [diff] [blame] | 119 | in mind, so you will have to adapt the shown code examples to Python 3 syntax |
Armin Ronacher | eb43b12 | 2010-02-10 02:10:48 +0100 | [diff] [blame] | 120 | for yourself. |
| 121 | |
| 122 | |
José Carlos García | c5a860c | 2016-04-04 01:21:39 +0200 | [diff] [blame] | 123 | .. _Jinja bug tracker: http://github.com/pallets/jinja/issues |