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 .. _ctypes: http://python.net/crew/theller/ctypes/
  41
  42
  43 Installation
  44 ------------
  45
  46 You have multiple ways to install Jinja2.  If you are unsure what to do, go
  47 with the Python egg or tarball.
  48
  49 As a Python egg (via easy_install)
  50 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  51
  52 You can install the most recent Jinja2 version using `easy_install`_::
  53
  54     sudo easy_install Jinja2
  55
  56 This will install a Jinja2 egg in your Python installation's site-packages
  57 directory.
  58
  59 From the tarball release
  60 ~~~~~~~~~~~~~~~~~~~~~~~~~
  61
  62 1.  Download the most recent tarball from the `download page`_
  63 2.  Unpack the tarball
  64 3.  ``sudo python setup.py install``
  65
  66 Note that the last command will automatically download and install
  67 `setuptools`_ if you don't already have it installed. This requires a working
  68 internet connection.
  69
  70 This will install Jinja2 into your Python installation's site-packages directory.
  71
  72 Installing the development version
  73 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  74
  75 1.  Install `mercurial`_
  76 2.  ``hg clone http://dev.pocoo.org/hg/jinja2-main jinja2``
  77 3.  ``cd jinja2``
  78 4.  ``ln -s jinja2 /usr/lib/python2.X/site-packages``
  79
  80 As an alternative to steps 4 you can also do ``python setup.py develop``
  81 which will install the package via setuptools in development mode.  This also
  82 has the advantage that the C extensions are compiled.
  83
  84 Alternative you can use `easy_install`_ to install the current development
  85 snapshot::
  86
  87     sudo easy_install Jinja2==dev
  88
  89 .. _download page: http://jinja.pocoo.org/2/download
  90 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
  91 .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
  92 .. _mercurial: http://www.selenic.com/mercurial/
  93
  94
  95 Basic API Usage
  96 ---------------
  97
  98 This section gives you a brief introduction to the Python API for Jinja2
  99 templates.
 100
 101 The most basic way to create a template and render it is through
 102 :class:`~jinja2.Template`.  This however is not the recommended way to
 103 work with it if your templates are not loaded from strings but the file
 104 system or another data source:
 105
 106 >>> from jinja2 import Template
 107 >>> template = Template('Hello {{ name }}!')
 108 >>> template.render(name='John Doe')
 109 u'Hello John Doe!'
 110
 111 By creating an instance of :class:`~jinja2.Template` you get back a new template
 112 object that provides a method called :meth:`~jinja2.Template.render` which when
 113 called with a dict or keyword arguments expands the template.  The dict
 114 or keywords arguments passed to the template are the so-called "context"
 115 of the template.
 116
 117 What you can see here is that Jinja2 is using unicode internally and the
 118 return value is an unicode string.  So make sure that your application is
 119 indeed using unicode internally.