Developer Quickstart
====================
-This part of the documentation shows you how to embedd Jinja into your
+This part of the documentation shows you how to embed Jinja into your
application.
Starting Up
Hello John Doe!
-If you receive an error check if you have a typo in your code. If not have
+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 helds important shared
+The core component of Jinja is the `Environment`. It contains important shared
variables like configuration, filters, tests, globals and other stuff.
-Here the possible initialisation 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.
-=========================== ==================================================
-
-All of this variables except those marked with a star(*) are modifyable after
-environment initialisation.
-
-The environment provides the following useful functions and properties
-additional to the initialisation values:
+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.
+========================= ==================================================
+
+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
`translators`_ to convert the template into
executable source- or bytecode.
``from_string(source)`` Load and parse a template source and translate it
- into evaluable python code. This code is wrapped
- with in a `Template` class that allows you to
+ 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`
+``get_template(name)`` Load a template from a loader. If the template
+ does not exist, you will get a `TemplateNotFound`
exception.
=========================== ==================================================
Adding Filters
==============
-If you want to add additional filters to the environment the best way is to
+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!
Adding Tests
============
-Adding additional tests works analog to filters:
+Adding additional tests works analogous to filters:
.. sourcecode:: python
Writing Filters
===============
-A filter basically is a factory function. Thus a function that returns another
-function. We do this because filters can get an unlimited amount of position
+A filter basically is a factory function, a function that returns another
+function. We do this because filters can get an unlimited amount of positional
arguments and aditionally should gain access to the environment, context and
piped value. A simple filter looks like this:
env.filters['join'] = do_join
-In fact this filter is already bundled so you won't see any effect. But its
+In fact this filter is already bundled so you won't see any effect. But it
should explain how such a filter looks like. The template designer can just
-trigger the outer code (eg: call do_join with or without arguments). The
+trigger the outer code (i.e. call `join` with or without arguments). The
returned function is then processed by the jinja template engine once all
filters are created.
-If you want to create filters that just operate on string (in fact unicode
+If you want to create filters that just operate on a string (in fact unicode
objects) you can use the `stringfilter` decorator:
.. sourcecode:: python
Differences To Django Templates
===============================
-If you have previously worked with Django templates you should feel very
-familiar. In fact most of the syntax elements look and work the same.
+If you have previously worked with Django templates, you should find Jinja very
+familiar. In fact, most of the syntax elements look and work the same.
-However Jinja provides some more syntax elements covered in the documentation
+However, Jinja provides some more syntax elements covered in the documentation
and some work a bit different.
Method Calls
============
-In Django method calls work implicit. With Jinja you have to tell it that you
-want to call it. Thus this Django code:
+In Django method calls work implicitly. With Jinja you have to specify that you
+want to call an object. Thus this Django code:
.. sourcecode:: django
Filter Arguments
================
-Jinja provides more than one argument for a filter. Also the syntax for argument
+Jinja provides more than one argument for filters. Also the syntax for argument
passing is different. A template that looks like this in Django:
.. sourcecode:: django
{{ items|join(', ') }}
-In fact it's a bit more to write but it allows different type of arguments including
-variables and more then one of them.
+In fact it's a bit more verbose but it allows different types of arguments - including
+variables - and more than one of them.
Tests
=====
-Additionally to filters there also exists tests you can perform using the `is`
-operator. Here some examples:
+In addition to filters there also are tests you can perform using the `is` operator.
+Here are some examples:
.. sourcecode:: jinja
Developing Loaders
==================
-Template loaders are just normal python classes that have to provide some
-functions used to load and translate templates. Here a simple loader implementation
-you can use as base for your own loader:
+Template loaders are just normal Python classes that have to provide some
+functions used to load and translate templates. Here is a simple loader implementation
+you can use as the base for your own loader:
.. sourcecode:: python
def get_source(self, environment, name, parent):
"""
- The get_source function is unused at the moment. However future
+ The get_source function is unused at the moment. However, future
versions of jinja will use this function for the debugging
system. It also works as helper functions for `parse` and
`load`.
def load(self, environment, name, translator):
"""
Parse and translate a template. Currently only translation to
- python code is possible, later jinja versions however will
+ python code is possible, later Jinja versions however will
support translating templates to javascript too.
"""
return translator.process(environment, self.parse(environment, name, None))
.. admonition:: Note
- Once a loader is bound to an environment you have to omit the environment
+ Once a loader is bound to an environment, you have to omit the environment
argument for the public functions `get_source`, `parse` and `load`.
projects / jinja2.git / commitdiff