docs/intro.rst

   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 The key-features are...
  14
  15 -   ... **configurable syntax**.  If you are generating LaTeX or other formats
  16     with Jinja2 you can change the delimiters to something that integrates better
  17     into the LaTeX markup.
  18
  19 -   ... **fast**.  While performance is not the primarily target of Jinja2 it's
  20     surprisingly fast.  The overhead compared to regular Python code was reduced
  21     to the very minimum.
  22
  23 -   ... **easy to debug**.  Jinja2 integrates directly into the python traceback
  24     system which allows you to debug Jinja2 templates with regular python
  25     debugging helpers.
  26
  27 -   ... **secure**.  It's possible to evaluate untrusted template code if the
  28     optional sandbox is enabled.  This allows Jinja2 to be used as templating
  29     language for applications where users may modify the template design.
  30
  31
  32 Prerequisites
  33 -------------
  34
  35 Jinja2 needs at least **Python 2.4** to run.  Additionally a working C-compiler
  36 that can create python extensions should be installed for the debugger.  If no
  37 C-compiler is available and you are using Python 2.4 the `ctypes`_ module
  38 should be installed.
  39
  40 If you don't have a working C-compiler and you are trying to install the source
  41 release with the speedups you will get a compiler error.  This however can be
  42 circumvented by passing the ``--without-speedups`` command line argument to the
  43 setup script::
  44
  45     $ python setup.py --with-speedups install
  46
  47 (As of Jinja 2.2, the speedups are disabled by default and can be enabled
  48 with ``--with-speedups``.  See :ref:`enable-speedups`)
  49
  50 .. _ctypes: http://python.net/crew/theller/ctypes/
  51
  52
  53 Installation
  54 ------------
  55
  56 You have multiple ways to install Jinja2.  If you are unsure what to do, go
  57 with the Python egg or tarball.
  58
  59 As a Python egg (via easy_install)
  60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  61
  62 You can install the most recent Jinja2 version using `easy_install`_ or `pip`_::
  63
  64     easy_install Jinja2
  65     pip install Jinja2
  66
  67 This will install a Jinja2 egg in your Python installation's site-packages
  68 directory.
  69
  70 (If you are installing from the windows command line omit the `sudo` and make
  71 sure to run the command as user with administrator rights)
  72
  73 From the tarball release
  74 ~~~~~~~~~~~~~~~~~~~~~~~~~
  75
  76 1.  Download the most recent tarball from the `download page`_
  77 2.  Unpack the tarball
  78 3.  ``sudo python setup.py install``
  79
  80 Note that you either have to have setuptools or `distribute`_ installed,
  81 the latter is preferred.
  82
  83 This will install Jinja2 into your Python installation's site-packages directory.
  84
  85 .. _distribute: http://pypi.python.org/pypi/distribute
  86
  87 Installing the development version
  88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  89
  90 1.  Install `mercurial`_
  91 2.  ``hg clone http://dev.pocoo.org/hg/jinja2-main jinja2``
  92 3.  ``cd jinja2``
  93 4.  ``ln -s jinja2 /usr/lib/python2.X/site-packages``
  94
  95 As an alternative to steps 4 you can also do ``python setup.py develop``
  96 which will install the package via distribute in development mode.  This also
  97 has the advantage that the C extensions are compiled.
  98
  99 Alternative you can use `pip`_ to install the current development
 100 snapshot::
 101
 102     sudo pip install Jinja2==dev
 103
 104 Or the `easy_install`_ command::
 105
 106     sudo easy_install Jinja2==dev
 107
 108 .. _download page: http://pypi.python.org/pypi/Jinja2
 109 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
 110 .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
 111 .. _pip: http://pypi.python.org/pypi/pip
 112 .. _mercurial: http://www.selenic.com/mercurial/
 113
 114 .. _enable-speedups:
 115
 116 Enable the speedups Module
 117 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 118
 119 By default Jinja2 will not compile the speedups module.  Enabling this
 120 will fail if you don't have the Python headers or a working compiler.  This
 121 is often the case if you are installing Jinja2 from a windows machine.
 122
 123 You can enable the speedups extension when installing using the
 124 ``--with-speedups`` flag::
 125
 126     sudo python setup.py --with-speedups install
 127
 128
 129
 130 Basic API Usage
 131 ---------------
 132
 133 This section gives you a brief introduction to the Python API for Jinja2
 134 templates.
 135
 136 The most basic way to create a template and render it is through
 137 :class:`~jinja2.Template`.  This however is not the recommended way to
 138 work with it if your templates are not loaded from strings but the file
 139 system or another data source:
 140
 141 >>> from jinja2 import Template
 142 >>> template = Template('Hello {{ name }}!')
 143 >>> template.render(name='John Doe')
 144 u'Hello John Doe!'
 145
 146 By creating an instance of :class:`~jinja2.Template` you get back a new template
 147 object that provides a method called :meth:`~jinja2.Template.render` which when
 148 called with a dict or keyword arguments expands the template.  The dict
 149 or keywords arguments passed to the template are the so-called "context"
 150 of the template.
 151
 152 What you can see here is that Jinja2 is using unicode internally and the
 153 return value is an unicode string.  So make sure that your application is
 154 indeed using unicode internally.
 155
 156
 157 Experimental Python 3 Support
 158 -----------------------------
 159
 160 Jinja 2.3 brings experimental support for Python 3.  It means that all
 161 unittests pass on the new version, but there might still be small bugs in
 162 there and behavior might be inconsistent.  If you notice any bugs, please
 163 provide feedback in the `Jinja bug tracker`_.
 164
 165 Also please keep in mind that the documentation is written with Python 2
 166 in mind, you will have to adapt the shown code examples to Python 3 syntax
 167 for yourself.
 168
 169
 170 .. _Jinja bug tracker: http://dev.pocoo.org/projects/jinja/