docs/src/devintro.txt

====================
Developer Quickstart
====================

This part of the documentation shows you how to embed Jinja into your
application.

Starting Up
===========

Here the quickest way to create a template from a string and render it:

.. sourcecode:: python

    from jinja import Environment
    env = Environment()
    tmpl = env.from_string('Hello {{ name }}!')
    print tmpl.render(name='John Doe')

This example should output the following string after execution::

    Hello John Doe!

If you receive an error, check if you have a typo in your code. If not, have
a look at the `installation`_ page for troubleshooting.

The Environment
===============

The core component of Jinja is the `Environment`. It contains important shared
variables like configuration, filters, tests, globals and other stuff.

Here the possible initialization parameters:

========================= ==================================================
`block_start_string` *    the string marking the begin of a block. this
                          defaults to ``'{%'``.
`block_end_string` *      the string marking the end of a block. defaults
                          to ``'%}'``.
`variable_start_string` * the string marking the begin of a print
                          statement. defaults to ``'{{'``.
`comment_start_string` *  the string marking the begin of a
                          comment. defaults to ``'{#'``.
`comment_end_string` *    the string marking the end of a comment.
                          defaults to ``'#}'``.
`trim_blocks` *           If this is set to ``True`` the first newline
                          after a block is removed (block, not
                          variable tag!). Defaults to ``False``.
`auto_escape`             If this is set to ``True`` Jinja will
                          automatically escape all variables using xml
                          escaping methods. If you don't want to escape a
                          string you have to wrap it in a ``Markup``
                          object from the ``jinja.datastructure`` module.
`template_charset`        The charset of the templates. Defaults
                          to ``'utf-8'``.
`charset`                 Charset of all string input data. Defaults
                          to ``'utf-8'``.
`namespace`               Global namespace for all templates.
`loader`                  Specify a template loader.
`filters`                 dict of filters or the default filters if not
                          defined.
`tests`                   dict of tests of the default tests if not defined.
`context_class`           the context class this template should use. See
                          the `context documentation`_ for more details.
========================= ==================================================

All of these variables except those marked with a star (*) are modifiable after
environment initialization.

The environment provides the following useful functions and properties in
addition to the initialization values:

=========================== ==================================================
``parse(source, filename)`` Parse the sourcecode and return the abstract
                            syntax tree. This tree of nodes is used by the
                            `translators`_ to convert the template into
                            executable source- or bytecode.
``from_string(source)``     Load and parse a template source and translate it
                            into eval-able Python code. This code is wrapped
                            within a `Template` class that allows you to
                            render it.
``get_template(name)``      Load a template from a loader. If the template
                            does not exist, you will get a `TemplateNotFound`
                            exception.
=========================== ==================================================

There are also some internal functions on the environment used by the template
evaluation code to keep it sandboxed.

Loading Templates From Files
============================

Loading templates from a string is always a bad idea. It doesn't allow template
inheritance and is also slow since it parses and compiles the template again
and again whereas loaders can cache the template code.

All you have to do is to define a loader and use the `get_template` function.

.. sourcecode:: python

    from jinja import Environment, FileSystemLoader
    env = Environment(loader=FileSystemLoader('templates'))
    tmpl = env.get_template('index.html')
    print tmpl.render(name='John Doe')

This tells jinja to look for templates in the ``templates`` folder. It's a
better idea to use an absolute path here though. For a list of supported
loaders or how to write your own, head over to the `loader`_ documentation.

Adding Filters
==============

If you want to add additional filters to the environment, the best way is to
modify the ``filters`` attribute and not to pass a dict to the environment.
If you pass it a dict it will not include the default filters!

.. sourcecode:: python

    from mylib import my_cool_filter
    env.filters['mycoolfilter'] = my_cool_filter

Writing filter functions is explained in the `filter development`_ section.

Adding Tests
============

Adding additional tests works analogous to filters:

.. sourcecode:: python

    from mylib import my_cool_test
    env.tests['mycooltest'] = my_cool_test

Writing tests is explained in the `test development`_ section.


.. _installation: installation.txt
.. _context documentation: contextenv.txt
.. _translators: translators.txt
.. _loader: loaders.txt
.. _filter development: filters.txt
.. _test development: tests.txt