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 Prerequisites
  14 -------------
  15
  16 Jinja2 needs at least **Python 2.4** to run.  Additionally a working C-compiler
  17 that can create python extensions should be installed for the debugger if you
  18 are using Python 2.4.
  19
  20 If you don't have a working C-compiler and you are trying to install the source
  21 release with the debugsupport you will get a compiler error.
  22
  23 .. _ctypes: http://python.net/crew/theller/ctypes/
  24
  25
  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
  35 You can install the most recent Jinja2 version using `easy_install`_ or `pip`_::
  36
  37     easy_install Jinja2
  38     pip install Jinja2
  39
  40 This will install a Jinja2 egg in your Python installation's site-packages
  41 directory.
  42
  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
  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
  53 Note that you either have to have setuptools or `distribute`_ installed,
  54 the latter is preferred.
  55
  56 This will install Jinja2 into your Python installation's site-packages directory.
  57
  58 .. _distribute: http://pypi.python.org/pypi/distribute
  59
  60 Installing the development version
  61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  62
  63 1.  Install `git`_
  64 2.  ``git clone git://github.com/mitsuhiko/jinja2.git``
  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``
  69 which will install the package via distribute in development mode.  This also
  70 has the advantage that the C extensions are compiled.
  71
  72 .. _download page: http://pypi.python.org/pypi/Jinja2
  73 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
  74 .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
  75 .. _pip: http://pypi.python.org/pypi/pip
  76 .. _git: http://git-scm.org/
  77
  78
  79 More Speed with MarkupSafe
  80 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  81
  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
 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
 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::
 105
 106     sudo python setup.py --with-debugsupport install
 107
 108
 109 Basic API Usage
 110 ---------------
 111
 112 This section gives you a brief introduction to the Python API for Jinja2
 113 templates.
 114
 115 The most basic way to create a template and render it is through
 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:
 119
 120 >>> from jinja2 import Template
 121 >>> template = Template('Hello {{ name }}!')
 122 >>> template.render(name='John Doe')
 123 u'Hello John Doe!'
 124
 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
 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.
 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.
 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
 149 .. _Jinja bug tracker: http://github.com/mitsuhiko/jinja2/issues