-
{%- for item in [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] if item % 2 == 0 %}
- {{ loop.index }} / {{ loop.length }}: {{ item }} {%- endfor %}
{{ article.title }}
{{ article.body|safe }}
- Name
- {% input_field 'name' %}
- {% input_field 'email' %}
- URL
- {% input_field 'url' %}
- Comment
- {% textarea 'comment' %}
- Captcha
- {% input_field 'captcha' %}
RealWorld Benchmark
A less stupid benchmark for Mako and Jinja2 to get an impression how code changes affect runtime performance.
{% block body %}{% endblock %}
${article.title}
${Markup(article.body)}
RealWorld Benchmark
A less stupid benchmark for Mako and Jinja2 to get an impression how code changes affect runtime performance.
${select('*|text()')}
{{ article.title|e }}
{{ article.body }}
- Name
- {{ input_field('name') }}
- {{ input_field('email') }}
- URL
- {{ input_field('url') }}
- Comment
- {{ textarea('comment') }}
- Captcha
- {{ input_field('captcha') }}
RealWorld Benchmark
A less stupid benchmark for Mako and Jinja2 to get an impression how code changes affect runtime performance.
{% block body %}{% endblock %}
${article.title|h}
${article.body}
- Name
- ${input_field('name')}
- ${input_field('email')}
- URL
- ${input_field('url')}
- Comment
- ${textarea('comment')}
- Captcha
- ${input_field('captcha')}
RealWorld Benchmark
A less stupid benchmark for Mako and Jinja2 to get an impression how code changes affect runtime performance.
${self.body()}
${page_title|e}
| ${cell} | % endfor
{{ page_title }}
| {{ cell }} | {% end %}
{{ page_title }}
| {{ cell }} | {% endfor %}
${page_title|h}
| ${cell} | % endfor
${page_title}
| ${cell} |
$cgi.escape($page_title)
| $cell | #end for
${page_title}
| #{cell} |
$cgi.escape($page_title)
| $cell | #end for
Page Title
| cell |
${page_title}
| ${row[cell]} |
${page_title|e}
| ${testmacro(cell)} | % endfor
{% endwith %}
{% debug %}
{% blocktrans with book|title as book_t and author|title as author_t %}
This is {{ book_t }} by {{ author_t }}
{% endblocktrans %}
{% blocktrans count list|length as counter %}
There is only one {{ name }} object.
{% plural %}
There are {{ counter }} {{ name }} objects.
{% endblocktrans %}
{% blocktrans with name|escape as name count list|length as counter %}
There is only one {{ name }} object.
{% plural %}
There are {{ counter }} {{ name }} objects.
{% endblocktrans %}
{% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %}
{% trans "This is the title." %}
{% regroup people by gender as grouped %} {% endblock %} PK |>] #|ao o & ext/django2jinja/templates/layout.htmlnu [
{% block page-body %}{% endblock %}
PK |>]}
+ ext/django2jinja/templates/subtemplate.htmlnu [ Hello World!
PK |>]Q`O|` ` ext/django2jinja/django2jinja.pynu [ # -*- coding: utf-8 -*-
"""
Django to Jinja
~~~~~~~~~~~~~~~
Helper module that can convert django templates into Jinja2 templates.
This file is not intended to be used as stand alone application but to
be used as library. To convert templates you basically create your own
writer, add extra conversion logic for your custom template tags,
configure your django environment and run the `convert_templates`
function.
Here a simple example::
# configure django (or use settings.configure)
import os
os.environ['DJANGO_SETTINGS_MODULE'] = 'yourapplication.settings'
from yourapplication.foo.templatetags.bar import MyNode
from django2jinja import Writer, convert_templates
def write_my_node(writer, node):
writer.start_variable()
writer.write('myfunc(')
for idx, arg in enumerate(node.args):
if idx:
writer.write(', ')
writer.node(arg)
writer.write(')')
writer.end_variable()
writer = Writer()
writer.node_handlers[MyNode] = write_my_node
convert_templates('/path/to/output/folder', writer=writer)
Here is an example hos to automatically translate your django
variables to jinja2::
import re
# List of tuple (Match pattern, Replace pattern, Exclusion pattern)
var_re = ((re.compile(r"(u|user)\.is_authenticated"), r"\1.is_authenticated()", None),
(re.compile(r"\.non_field_errors"), r".non_field_errors()", None),
(re.compile(r"\.label_tag"), r".label_tag()", None),
(re.compile(r"\.as_dl"), r".as_dl()", None),
(re.compile(r"\.as_table"), r".as_table()", None),
(re.compile(r"\.as_widget"), r".as_widget()", None),
(re.compile(r"\.as_hidden"), r".as_hidden()", None),
(re.compile(r"\.get_([0-9_\w]+)_url"), r".get_\1_url()", None),
(re.compile(r"\.url"), r".url()", re.compile(r"(form|calendar).url")),
(re.compile(r"\.get_([0-9_\w]+)_display"), r".get_\1_display()", None),
(re.compile(r"loop\.counter"), r"loop.index", None),
(re.compile(r"loop\.revcounter"), r"loop.revindex", None),
(re.compile(r"request\.GET\.([0-9_\w]+)"), r"request.GET.get('\1', '')", None),
(re.compile(r"request\.get_host"), r"request.get_host()", None),
(re.compile(r"\.all(?!_)"), r".all()", None),
(re.compile(r"\.all\.0"), r".all()[0]", None),
(re.compile(r"\.([0-9])($|\s+)"), r"[\1]\2", None),
(re.compile(r"\.items"), r".items()", None),
)
writer = Writer(var_re=var_re)
For details about the writing process have a look at the module code.
:copyright: (c) 2009 by the Jinja Team.
:license: BSD.
"""
import re
import os
import sys
from jinja2.defaults import *
from django.conf import settings
from django.template import defaulttags as core_tags, loader, TextNode, \
FilterExpression, libraries, Variable, loader_tags, TOKEN_TEXT, \
TOKEN_VAR
from django.template.debug import DebugVariableNode as VariableNode
from django.templatetags import i18n as i18n_tags
from StringIO import StringIO
_node_handlers = {}
_resolved_filters = {}
_newline_re = re.compile(r'(?:\r\n|\r|\n)')
# Django stores an itertools object on the cycle node. Not only is this
# thread unsafe but also a problem for the converter which needs the raw
# string values passed to the constructor to create a jinja loop.cycle()
# call from it.
_old_cycle_init = core_tags.CycleNode.__init__
def _fixed_cycle_init(self, cyclevars, variable_name=None):
self.raw_cycle_vars = map(Variable, cyclevars)
_old_cycle_init(self, cyclevars, variable_name)
core_tags.CycleNode.__init__ = _fixed_cycle_init
def node(cls):
def proxy(f):
_node_handlers[cls] = f
return f
return proxy
def convert_templates(output_dir, extensions=('.html', '.txt'), writer=None,
callback=None):
"""Iterates over all templates in the template dirs configured and
translates them and writes the new templates into the output directory.
"""
if writer is None:
writer = Writer()
def filter_templates(files):
for filename in files:
ifilename = filename.lower()
for extension in extensions:
if ifilename.endswith(extension):
yield filename
def translate(f, loadname):
template = loader.get_template(loadname)
original = writer.stream
writer.stream = f
writer.body(template.nodelist)
writer.stream = original
if callback is None:
def callback(template):
print template
for directory in settings.TEMPLATE_DIRS:
for dirname, _, files in os.walk(directory):
dirname = dirname[len(directory) + 1:]
for filename in filter_templates(files):
source = os.path.normpath(os.path.join(dirname, filename))
target = os.path.join(output_dir, dirname, filename)
basetarget = os.path.dirname(target)
if not os.path.exists(basetarget):
os.makedirs(basetarget)
callback(source)
f = file(target, 'w')
try:
translate(f, source)
finally:
f.close()
class Writer(object):
"""The core writer class."""
def __init__(self, stream=None, error_stream=None,
block_start_string=BLOCK_START_STRING,
block_end_string=BLOCK_END_STRING,
variable_start_string=VARIABLE_START_STRING,
variable_end_string=VARIABLE_END_STRING,
comment_start_string=COMMENT_START_STRING,
comment_end_string=COMMENT_END_STRING,
initial_autoescape=True,
use_jinja_autoescape=False,
custom_node_handlers=None,
var_re=[],
env=None):
if stream is None:
stream = sys.stdout
if error_stream is None:
error_stream = sys.stderr
self.stream = stream
self.error_stream = error_stream
self.block_start_string = block_start_string
self.block_end_string = block_end_string
self.variable_start_string = variable_start_string
self.variable_end_string = variable_end_string
self.comment_start_string = comment_start_string
self.comment_end_string = comment_end_string
self.autoescape = initial_autoescape
self.spaceless = False
self.use_jinja_autoescape = use_jinja_autoescape
self.node_handlers = dict(_node_handlers,
**(custom_node_handlers or {}))
self._loop_depth = 0
self._filters_warned = set()
self.var_re = var_re
self.env = env
def enter_loop(self):
"""Increments the loop depth so that write functions know if they
are in a loop.
"""
self._loop_depth += 1
def leave_loop(self):
"""Reverse of enter_loop."""
self._loop_depth -= 1
@property
def in_loop(self):
"""True if we are in a loop."""
return self._loop_depth > 0
def write(self, s):
"""Writes stuff to the stream."""
self.stream.write(s.encode(settings.FILE_CHARSET))
def print_expr(self, expr):
"""Open a variable tag, write to the string to the stream and close."""
self.start_variable()
self.write(expr)
self.end_variable()
def _post_open(self):
if self.spaceless:
self.write('- ')
else:
self.write(' ')
def _pre_close(self):
if self.spaceless:
self.write(' -')
else:
self.write(' ')
def start_variable(self):
"""Start a variable."""
self.write(self.variable_start_string)
self._post_open()
def end_variable(self, always_safe=False):
"""End a variable."""
if not always_safe and self.autoescape and \
not self.use_jinja_autoescape:
self.write('|e')
self._pre_close()
self.write(self.variable_end_string)
def start_block(self):
"""Starts a block."""
self.write(self.block_start_string)
self._post_open()
def end_block(self):
"""Ends a block."""
self._pre_close()
self.write(self.block_end_string)
def tag(self, name):
"""Like `print_expr` just for blocks."""
self.start_block()
self.write(name)
self.end_block()
def variable(self, name):
"""Prints a variable. This performs variable name transformation."""
self.write(self.translate_variable_name(name))
def literal(self, value):
"""Writes a value as literal."""
value = repr(value)
if value[:2] in ('u"', "u'"):
value = value[1:]
self.write(value)
def filters(self, filters, is_block=False):
"""Dumps a list of filters."""
want_pipe = not is_block
for filter, args in filters:
name = self.get_filter_name(filter)
if name is None:
self.warn('Could not find filter %s' % name)
continue
if name not in DEFAULT_FILTERS and \
name not in self._filters_warned:
self._filters_warned.add(name)
self.warn('Filter %s probably doesn\'t exist in Jinja' %
name)
if not want_pipe:
want_pipe = True
else:
self.write('|')
self.write(name)
if args:
self.write('(')
for idx, (is_var, value) in enumerate(args):
if idx:
self.write(', ')
if is_var:
self.node(value)
else:
self.literal(value)
self.write(')')
def get_location(self, origin, position):
"""Returns the location for an origin and position tuple as name
and lineno.
"""
if hasattr(origin, 'source'):
source = origin.source
name = '_(Welcome)
_(This is a paragraph)
Requires the i18n extension to be loaded and configured. """ def filter_stream(self, stream): paren_stack = 0 for token in stream: if token.type is not 'data': yield token continue pos = 0 lineno = token.lineno while 1: if not paren_stack: match = _outside_re.search(token.value, pos) else: match = _inside_re.search(token.value, pos) if match is None: break new_pos = match.start() if new_pos > pos: preval = token.value[pos:new_pos] yield Token(lineno, 'data', preval) lineno += count_newlines(preval) gtok = match.group() if gtok[0] == '\\': yield Token(lineno, 'data', gtok[1:]) elif not paren_stack: yield Token(lineno, 'block_begin', None) yield Token(lineno, 'name', 'trans') yield Token(lineno, 'block_end', None) paren_stack = 1 else: if gtok == '(' or paren_stack > 1: yield Token(lineno, 'data', gtok) paren_stack += gtok == ')' and -1 or 1 if not paren_stack: yield Token(lineno, 'block_begin', None) yield Token(lineno, 'name', 'endtrans') yield Token(lineno, 'block_end', None) pos = match.end() if pos < len(token.value): yield Token(lineno, 'data', token.value[pos:]) if paren_stack: raise TemplateSyntaxError('unclosed gettext expression', token.lineno, stream.name, stream.filename) PK |>]} } ext/jinja.elnu [ ;;; jinja.el --- Jinja mode highlighting ;; ;; Author: Georg Brandl ;; Copyright: (c) 2009 by the Jinja Team ;; Last modified: 2008-05-22 23:04 by gbr ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;;; Commentary: ;; ;; Mostly ripped off django-mode by Lennart Borgman. ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;; This program is free software; you can redistribute it and/or ;; modify it under the terms of the GNU General Public License as ;; published by the Free Software Foundation; either version 2, or ;; (at your option) any later version. ;; ;; This program is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ;; General Public License for more details. ;; ;; You should have received a copy of the GNU General Public License ;; along with this program; see the file COPYING. If not, write to ;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth ;; Floor, Boston, MA 02110-1301, USA. ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ;;; Code: (defconst jinja-font-lock-keywords (list ; (cons (rx "{% comment %}" (submatch (0+ anything)) ; "{% endcomment %}") (list 1 font-lock-comment-face)) '("{# ?\\(.*?\\) ?#}" . (1 font-lock-comment-face)) '("{%-?\\|-?%}\\|{{\\|}}" . font-lock-preprocessor-face) '("{#\\|#}" . font-lock-comment-delimiter-face) ;; first word in a block is a command '("{%-?[ \t\n]*\\([a-zA-Z_]+\\)" . (1 font-lock-keyword-face)) ;; variables '("\\({{ ?\\)\\([^|]*?\\)\\(|.*?\\)? ?}}" . (1 font-lock-variable-name-face)) ;; keywords and builtins (cons (rx word-start (or "in" "as" "recursive" "not" "and" "or" "if" "else" "import" "with" "without" "context") word-end) font-lock-keyword-face) (cons (rx word-start (or "true" "false" "none" "loop" "self" "super") word-end) font-lock-builtin-face) ;; tests '("\\(is\\)[ \t]*\\(not\\)[ \t]*\\([a-zA-Z_]+\\)" (1 font-lock-keyword-face) (2 font-lock-keyword-face) (3 font-lock-function-name-face)) ;; builtin filters (cons (rx "|" (* space) (submatch (or "abs" "batch" "capitalize" "capture" "center" "count" "default" "dformat" "dictsort" "e" "escape" "filesizeformat" "first" "float" "format" "getattribute" "getitem" "groupby" "indent" "int" "join" "jsonencode" "last" "length" "lower" "markdown" "pprint" "random" "replace" "reverse" "round" "rst" "slice" "sort" "string" "striptags" "sum" "textile" "title" "trim" "truncate" "upper" "urlencode" "urlize" "wordcount" "wordwrap" "xmlattr"))) (list 1 font-lock-builtin-face)) ) "Minimal highlighting expressions for Jinja mode") (define-derived-mode jinja-mode nil "Jinja" "Simple Jinja mode for use with `mumamo-mode'. This mode only provides syntax highlighting." ;;(set (make-local-variable 'comment-start) "{#") ;;(set (make-local-variable 'comment-end) "#}") (setq font-lock-defaults '(jinja-font-lock-keywords))) ;; mumamo stuff (when (require 'mumamo nil t) (defun mumamo-chunk-jinja3 (pos max) "Find {# ... #}" (mumamo-quick-chunk-forward pos max "{#" "#}" 'borders 'jinja-mode)) (defun mumamo-chunk-jinja2 (pos max) "Find {{ ... }}" (mumamo-quick-chunk-forward pos max "{{" "}}" 'borders 'jinja-mode)) (defun mumamo-chunk-jinja (pos max) "Find {% ... %}" (mumamo-quick-chunk-forward pos max "{%" "%}" 'borders 'jinja-mode)) ;;;###autoload (define-mumamo-multi-major-mode jinja-html-mumamo "Turn on multiple major modes for Jinja with main mode `html-mode'. This also covers inlined style and javascript." ("Jinja HTML Family" html-mode (mumamo-chunk-jinja mumamo-chunk-jinja2 mumamo-chunk-jinja3 mumamo-chunk-inlined-style mumamo-chunk-inlined-script mumamo-chunk-style= mumamo-chunk-onjs= ))) ;;;###autoload (define-mumamo-multi-major-mode jinja-nxhtml-mumamo "Turn on multiple major modes for Jinja with main mode `nxhtml-mode'. This also covers inlined style and javascript." ("Jinja nXhtml Family" nxhtml-mode (mumamo-chunk-jinja mumamo-chunk-jinja2 mumamo-chunk-jinja3 mumamo-chunk-inlined-style mumamo-chunk-inlined-script mumamo-chunk-style= mumamo-chunk-onjs= ))) ) (provide 'jinja) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; jinja.el ends here PK |>]l6 C@ @ html/_sources/api.rst.txtnu [ API === .. module:: jinja2 :synopsis: public Jinja2 API This document describes the API to Jinja2 and not the template language. It will be most useful as reference to those implementing the template interface to the application and not those who are creating Jinja2 templates. Basics ------ Jinja2 uses a central object called the template :class:`Environment`. Instances of this class are used to store the configuration and global objects, and are used to load templates from the file system or other locations. Even if you are creating templates from strings by using the constructor of :class:`Template` class, an environment is created automatically for you, albeit a shared one. Most applications will create one :class:`Environment` object on application initialization and use that to load templates. In some cases however, it's useful to have multiple environments side by side, if different configurations are in use. The simplest way to configure Jinja2 to load templates for your application looks roughly like this:: from jinja2 import Environment, PackageLoader, select_autoescape env = Environment( loader=PackageLoader('yourapplication', 'templates'), autoescape=select_autoescape(['html', 'xml']) ) This will create a template environment with the default settings and a loader that looks up the templates in the `templates` folder inside the `yourapplication` python package. Different loaders are available and you can also write your own if you want to load templates from a database or other resources. This also enables autoescaping for HTML and XML files. To load a template from this environment you just have to call the :meth:`get_template` method which then returns the loaded :class:`Template`:: template = env.get_template('mytemplate.html') To render it with some variables, just call the :meth:`render` method:: print template.render(the='variables', go='here') Using a template loader rather than passing strings to :class:`Template` or :meth:`Environment.from_string` has multiple advantages. Besides being a lot easier to use it also enables template inheritance. .. admonition:: Notes on Autoescaping In future versions of Jinja2 we might enable autoescaping by default for security reasons. As such you are encouraged to explicitly configure autoescaping now instead of relying on the default. Unicode ------- Jinja2 is using Unicode internally which means that you have to pass Unicode objects to the render function or bytestrings that only consist of ASCII characters. Additionally newlines are normalized to one end of line sequence which is per default UNIX style (``\n``). Python 2.x supports two ways of representing string objects. One is the `str` type and the other is the `unicode` type, both of which extend a type called `basestring`. Unfortunately the default is `str` which should not be used to store text based information unless only ASCII characters are used. With Python 2.6 it is possible to make `unicode` the default on a per module level and with Python 3 it will be the default. To explicitly use a Unicode string you have to prefix the string literal with a `u`: ``u'Hänsel und Gretel sagen Hallo'``. That way Python will store the string as Unicode by decoding the string with the character encoding from the current Python module. If no encoding is specified this defaults to 'ASCII' which means that you can't use any non ASCII identifier. To set a better module encoding add the following comment to the first or second line of the Python module using the Unicode literal:: # -*- coding: utf-8 -*- We recommend utf-8 as Encoding for Python modules and templates as it's possible to represent every Unicode character in utf-8 and because it's backwards compatible to ASCII. For Jinja2 the default encoding of templates is assumed to be utf-8. It is not possible to use Jinja2 to process non-Unicode data. The reason for this is that Jinja2 uses Unicode already on the language level. For example Jinja2 treats the non-breaking space as valid whitespace inside expressions which requires knowledge of the encoding or operating on an Unicode string. For more details about Unicode in Python have a look at the excellent `Unicode documentation`_. Another important thing is how Jinja2 is handling string literals in templates. A naive implementation would be using Unicode strings for all string literals but it turned out in the past that this is problematic as some libraries are typechecking against `str` explicitly. For example `datetime.strftime` does not accept Unicode arguments. To not break it completely Jinja2 is returning `str` for strings that fit into ASCII and for everything else `unicode`: >>> m = Template(u"{% set a, b = 'foo', 'föö' %}").module >>> m.a 'foo' >>> m.b u'f\xf6\xf6' .. _Unicode documentation: https://docs.python.org/dev/howto/unicode.html High Level API -------------- The high-level API is the API you will use in the application to load and render Jinja2 templates. The :ref:`low-level-api` on the other side is only useful if you want to dig deeper into Jinja2 or :ref:`develop extensions%s
' % p.replace('\n', Markup('\n')) for p in _paragraph_re.split(escape(value))) if eval_ctx.autoescape: result = Markup(result) return result Context filters work the same just that the first argument is the current active :class:`Context` rather than the environment. .. _eval-context: Evaluation Context ------------------ The evaluation context (short eval context or eval ctx) is a new object introduced in Jinja 2.4 that makes it possible to activate and deactivate compiled features at runtime. Currently it is only used to enable and disable the automatic escaping but can be used for extensions as well. In previous Jinja versions filters and functions were marked as environment callables in order to check for the autoescape status from the environment. In new versions it's encouraged to check the setting from the evaluation context instead. Previous versions:: @environmentfilter def filter(env, value): result = do_something(value) if env.autoescape: result = Markup(result) return result In new versions you can either use a :func:`contextfilter` and access the evaluation context from the actual context, or use a :func:`evalcontextfilter` which directly passes the evaluation context to the function:: @contextfilter def filter(context, value): result = do_something(value) if context.eval_ctx.autoescape: result = Markup(result) return result @evalcontextfilter def filter(eval_ctx, value): result = do_something(value) if eval_ctx.autoescape: result = Markup(result) return result The evaluation context must not be modified at runtime. Modifications must only happen with a :class:`nodes.EvalContextModifier` and :class:`nodes.ScopedEvalContextModifier` from an extension, not on the eval context object itself. .. autoclass:: jinja2.nodes.EvalContext .. attribute:: autoescape `True` or `False` depending on if autoescaping is active or not. .. attribute:: volatile `True` if the compiler cannot evaluate some expressions at compile time. At runtime this should always be `False`. .. _writing-tests: Custom Tests ------------ Tests work like filters just that there is no way for a test to get access to the environment or context and that they can't be chained. The return value of a test should be `True` or `False`. The purpose of a test is to give the template designers the possibility to perform type and conformability checks. Here a simple test that checks if a variable is a prime number:: import math def is_prime(n): if n == 2: return True for i in xrange(2, int(math.ceil(math.sqrt(n))) + 1): if n % i == 0: return False return True You can register it on the template environment by updating the :attr:`~Environment.tests` dict on the environment:: environment.tests['prime'] = is_prime A template designer can then use the test like this: .. sourcecode:: jinja {% if 42 is prime %} 42 is a prime number {% else %} 42 is not a prime number {% endif %} .. _global-namespace: The Global Namespace -------------------- Variables stored in the :attr:`Environment.globals` dict are special as they are available for imported templates too, even if they are imported without context. This is the place where you can put variables and functions that should be available all the time. Additionally :attr:`Template.globals` exist that are variables available to a specific template that are available to all :meth:`~Template.render` calls. .. _low-level-api: Low Level API ------------- The low level API exposes functionality that can be useful to understand some implementation details, debugging purposes or advanced :ref:`extension
-
{% for user in users %}
- {{ user.username }} {% endfor %}
-
% for item in list:
- ${item} % endfor
-
% for item in list:
- ${item} % endfor
My Webpage
{{ a_variable }} {# a comment #} The following example shows the default configuration settings. An application developer can change the syntax configuration from ``{% foo %}`` to ``<% foo %>``, or something similar. There are a few kinds of delimiters. The default Jinja delimiters are configured as follows: * ``{% ... %}`` for :ref:`Statements
{% if True %}
yay
{% endif %}
gets rendered with blank lines inside the div::
yay
But with both `trim_blocks` and `lstrip_blocks` enabled, the template block
lines are removed and other whitespace is preserved::
yay
You can manually disable the `lstrip_blocks` behavior by putting a
plus sign (``+``) at the start of a block::
{%+ if something %}yay{% endif %}
You can also strip whitespace in templates by hand. If you add a minus
sign (``-``) to the start or end of a block (e.g. a :ref:`for-loop` tag), a
comment, or a variable expression, the whitespaces before or after
that block will be removed::
{% for item in seq -%}
{{ item }}
{%- endfor %}
This will yield all elements without whitespace between them. If `seq` was
a list of numbers from ``1`` to ``9``, the output would be ``123456789``.
If :ref:`line-statements` are enabled, they strip leading whitespace
automatically up to the beginning of the line.
By default, Jinja2 also removes trailing newlines. To keep single
trailing newlines, configure Jinja to `keep_trailing_newline`.
.. admonition:: Note
You must not add whitespace between the tag and the minus sign.
**valid**::
{%- if foo -%}...{% endif %}
**invalid**::
{% - if foo - %}...{% endif %}
Escaping
--------
It is sometimes desirable -- even necessary -- to have Jinja ignore parts
it would otherwise handle as variables or blocks. For example, if, with
the default syntax, you want to use ``{{`` as a raw string in a template and
not start a variable, you have to use a trick.
The easiest way to output a literal variable delimiter (``{{``) is by using a
variable expression::
{{ '{{' }}
For bigger sections, it makes sense to mark a block `raw`. For example, to
include example Jinja syntax in a template, you can use this snippet::
{% raw %}
-
{% for item in seq %}
- {{ item }} {% endfor %}
-
# for item in seq
- {{ item }} # endfor
-
{% for item in seq %}
- {{ item }} {% endfor %}
-
# for href, caption in [('index.html', 'Index'),
('about.html', 'About')]:
- {{ caption }} # endfor
{% block content %}{% endblock %}
In this example, the ``{% block %}`` tags define four blocks that child templates
can fill in. All the `block` tag does is tell the template engine that a
child template may override those placeholders in the template.
Child Template
~~~~~~~~~~~~~~
A child template might look like this::
{% extends "base.html" %}
{% block title %}Index{% endblock %}
{% block head %}
{{ super() }}
{% endblock %}
{% block content %}
Index
Welcome to my awesome homepage.
{% endblock %} The ``{% extends %}`` tag is the key here. It tells the template engine that this template "extends" another template. When the template system evaluates this template, it first locates the parent. The extends tag should be the first tag in the template. Everything before it is printed out normally and may cause confusion. For details about this behavior and how to take advantage of it, see :ref:`null-master-fallback`. The filename of the template depends on the template loader. For example, the :class:`FileSystemLoader` allows you to access other templates by giving the filename. You can access templates in subdirectories with a slash:: {% extends "layout/default.html" %} But this behavior can depend on the application embedding Jinja. Note that since the child template doesn't define the ``footer`` block, the value from the parent template is used instead. You can't define multiple ``{% block %}`` tags with the same name in the same template. This limitation exists because a block tag works in "both" directions. That is, a block tag doesn't just provide a placeholder to fill - it also defines the content that fills the placeholder in the *parent*. If there were two similarly-named ``{% block %}`` tags in a template, that template's parent wouldn't know which one of the blocks' content to use. If you want to print a block multiple times, you can, however, use the special `self` variable and call the block with that name::{{ self.title() }}
{% block body %}{% endblock %} Super Blocks ~~~~~~~~~~~~ It's possible to render the contents of the parent block by calling `super`. This gives back the results of the parent block:: {% block sidebar %}Table Of Contents
... {{ super() }} {% endblock %} Named Block End-Tags ~~~~~~~~~~~~~~~~~~~~ Jinja2 allows you to put the name of the block after the end tag for better readability:: {% block sidebar %} {% block inner_sidebar %} ... {% endblock inner_sidebar %} {% endblock sidebar %} However, the name after the `endblock` word must match the block name. Block Nesting and Scope ~~~~~~~~~~~~~~~~~~~~~~~ Blocks can be nested for more complex layouts. However, per default blocks may not access variables from outer scopes:: {% for item in seq %}Members
-
{% for user in users %}
- {{ user.username|e }} {% endfor %}
-
{% for key, value in my_dict.iteritems() %}
- {{ key|e }}
- {{ value|e }} {% endfor %}
-
{% for user in users %}
- {{ user.username|e }} {% else %}
- no users found {% endfor %}
-
{%- for item in sitemap recursive %}
- {{ item.title }} {%- if item.children -%} {%- endif %} {%- endfor %}
{{ entry.category }}
{% endif %}{{ entry.message }}
{% endfor %} .. _if: If ~~ The `if` statement in Jinja is comparable with the Python if statement. In the simplest form, you can use it to test if a variable is defined, not empty and not false:: {% if users %}-
{% for user in users %}
- {{ user.username|e }} {% endfor %}
{{ input('username') }}
{{ input('password', type='password') }}
If the macro was defined in a different template, you have to :ref:`import{{ title }}
{{ caller() }}
-
{%- for user in users %}
{{ user.username|e }}
{{ caller(user) }}
{%- endfor %}
- {{ user.realname|e }}
- {{ user.description }}
- Realname
- Description
- Username
- {{ forms.input('username') }}
- Password
- {{ forms.input('password', type='password') }}
{{ forms.textarea('comment') }}
Alternatively, you can import specific names from a template into the current namespace:: {% from 'forms.html' import input as input_field, textarea %}- Username
- {{ input_field('username') }}
- Password
- {{ input_field('password', type='password') }}
{{ textarea('comment') }}
Macros and variables starting with one or more underscores are private and cannot be imported. .. versionchanged:: 2.4 If a template object was passed to the template context, you can import from that object. .. _import-visibility: Import Context Behavior ----------------------- By default, included templates are passed the current context and imported templates are not. The reason for this is that imports, unlike includes, are cached; as imports are often used just as a module that holds macros. This behavior can be changed explicitly: by adding `with context` or `without context` to the import/include directive, the current context can be passed to the template and caching is disabled automatically. Here are two examples:: {% from 'forms.html' import input with context %} {% include 'header.html' without context %} .. admonition:: Note In Jinja 2.0, the context that was passed to the included template did not include variables defined in the template. As a matter of fact, this did not work:: {% for box in boxes %} {% include "render_box.html" %} {% endfor %} The included template ``render_box.html`` is *not* able to access `box` in Jinja 2.0. As of Jinja 2.1, ``render_box.html`` *is* able to do so. .. _expressions: Expressions ----------- Jinja allows basic expressions everywhere. These work very similarly to regular Python; even if you're not working with Python you should feel comfortable with it. Literals ~~~~~~~~ The simplest form of expressions are literals. Literals are representations for Python objects such as strings and numbers. The following literals exist: "Hello World": Everything between two double or single quotes is a string. They are useful whenever you need a string in the template (e.g. as arguments to function calls and filters, or just to extend or include a template). 42 / 42.23: Integers and floating point numbers are created by just writing the number down. If a dot is present, the number is a float, otherwise an integer. Keep in mind that, in Python, ``42`` and ``42.0`` are different (``int`` and ``float``, respectively). ['list', 'of', 'objects']: Everything between two brackets is a list. Lists are useful for storing sequential data to be iterated over. For example, you can easily create a list of links using lists and tuples for (and with) a for loop::-
{% for href, caption in [('index.html', 'Index'), ('about.html', 'About'),
('downloads.html', 'Downloads')] %}
- {{ caption }} {% endfor %}
-
{% for user in users %}
- {{ user.username }} {% endfor %} {% for number in range(10 - users|count) %}
- ... {% endfor %}
-
{% for folder in folders %}
- {{ folder|e }} {% endfor %} {% for filename in files %}
- {{ filename|e }} {% endfor %}
{% trans %}Hello {{ user }}!{% endtrans %}
To translate a template expression --- say, using template filters, or by just accessing an attribute of an object --- you need to bind the expression to a name for use within the translation block::{% trans user=user.username %}Hello {{ user }}!{% endtrans %}
If you need to bind more than one expression inside a `trans` tag, separate the pieces with a comma (``,``):: {% trans book_title=book.title, author=author.name %} This is {{ book_title }} by {{ author }} {% endtrans %} Inside trans tags no statements are allowed, only variable tags are. To pluralize, specify both the singular and plural forms with the `pluralize` tag, which appears between `trans` and `endtrans`:: {% trans count=list|length %} There is {{ count }} {{ name }} object. {% pluralize %} There are {{ count }} {{ name }} objects. {% endtrans %} By default, the first variable in a block is used to determine the correct singular or plural form. If that doesn't work out, you can specify the name which should be used for pluralizing by adding it as parameter to `pluralize`:: {% trans ..., user_count=users|length %}... {% pluralize user_count %}...{% endtrans %} When translating longer blocks of text, whitespace and linebreaks result in rather ugly and error-prone translation strings. To avoid this, a trans block can be marked as trimmed which will replace all linebreaks and the whitespace surrounding them with a single space and remove leading/trailing whitespace:: {% trans trimmed book_title=book.title %} This is {{ book_title }}. You should read it! {% endtrans %} If trimming is enabled globally, the `notrimmed` modifier can be used to disable it for a `trans` block. .. versionadded:: 2.10 The `trimmed` and `notrimmed` modifiers have been added. It's also possible to translate strings in expressions. For that purpose, three functions exist: - `gettext`: translate a single string - `ngettext`: translate a pluralizable string - `_`: alias for `gettext` For example, you can easily print a translated string like this:: {{ _('Hello World!') }} To use placeholders, use the `format` filter:: {{ _('Hello %(user)s!')|format(user=user.username) }} For multiple placeholders, always use keyword arguments to `format`, as other languages may not use the words in the same order. .. versionchanged:: 2.5 If newstyle gettext calls are activated (:ref:`newstyle-gettext`), using placeholders is a lot easier: .. sourcecode:: html+jinja {{ gettext('Hello World!') }} {{ gettext('Hello %(name)s!', name='World') }} {{ ngettext('%(num)d apple', '%(num)d apples', apples|count) }} Note that the `ngettext` function's format string automatically receives the count as a `num` parameter in addition to the regular parameters. Expression Statement ~~~~~~~~~~~~~~~~~~~~ If the expression-statement extension is loaded, a tag called `do` is available that works exactly like the regular variable expression (``{{ ... }}``); except it doesn't print anything. This can be used to modify lists:: {% do navigation.append('a string') %} Loop Controls ~~~~~~~~~~~~~ If the application enables the :ref:`loopcontrols-extension`, it's possible to use `break` and `continue` in loops. When `break` is reached, the loop is terminated; if `continue` is reached, the processing is stopped and continues with the next iteration. Here's a loop that skips every second item:: {% for user in users %} {%- if loop.index is even %}{% continue %}{% endif %} ... {% endfor %} Likewise, a loop that stops processing after the 10th iteration:: {% for user in users %} {%- if loop.index >= 10 %}{% break %}{% endif %} {%- endfor %} Note that ``loop.index`` starts with 1, and ``loop.index0`` starts with 0 (See: :ref:`for-loop`). With Statement ~~~~~~~~~~~~~~ .. versionadded:: 2.3 The with statement makes it possible to create a new inner scope. Variables set within this scope are not visible outside of the scope. With in a nutshell:: {% with %} {% set foo = 42 %} {{ foo }} foo is 42 here {% endwith %} foo is not visible here any longer Because it is common to set variables at the beginning of the scope, you can do that within the `with` statement. The following two examples are equivalent:: {% with foo = 42 %} {{ foo }} {% endwith %} {% with %} {% set foo = 42 %} {{ foo }} {% endwith %} An important note on scoping here. In Jinja versions before 2.9 the behavior of referencing one variable to another had some unintended consequences. In particular one variable could refer to another defined in the same with block's opening statement. This caused issues with the cleaned up scoping behavior and has since been improved. In particular in newer Jinja2 versions the following code always refers to the variable `a` from outside the `with` block:: {% with a={}, b=a.attribute %}...{% endwith %} In earlier Jinja versions the `b` attribute would refer to the results of the first attribute. If you depend on this behavior you can rewrite it to use the ``set`` tag:: {% with a={} %} {% set b = a.attribute %} {% endwith %} .. admonition:: Extension In older versions of Jinja (before 2.9) it was required to enable this feature with an extension. It's now enabled by default. .. _autoescape-overrides: Autoescape Overrides -------------------- .. versionadded:: 2.4 If you want you can activate and deactivate the autoescaping from within the templates. Example:: {% autoescape true %} Autoescaping is active within this block {% endautoescape %} {% autoescape false %} Autoescaping is inactive within this block {% endautoescape %} After an `endautoescape` the behavior is reverted to what it was before. .. admonition:: Extension In older versions of Jinja (before 2.9) it was required to enable this feature with an extension. It's now enabled by default. PK |>]ܛ html/_sources/tricks.rst.txtnu [ Tips and Tricks =============== .. highlight:: html+jinja This part of the documentation shows some tips and tricks for Jinja2 templates. .. _null-master-fallback: Null-Master Fallback -------------------- Jinja2 supports dynamic inheritance and does not distinguish between parent and child template as long as no `extends` tag is visited. While this leads to the surprising behavior that everything before the first `extends` tag including whitespace is printed out instead of being ignored, it can be used for a neat trick. Usually child templates extend from one template that adds a basic HTML skeleton. However it's possible to put the `extends` tag into an `if` tag to only extend from the layout template if the `standalone` variable evaluates to false which it does per default if it's not defined. Additionally a very basic skeleton is added to the file so that if it's indeed rendered with `standalone` set to `True` a very basic HTML skeleton is added:: {% if not standalone %}{% extends 'master.html' %}{% endif -%}This is the page body.
{% endblock %} Alternating Rows ---------------- If you want to have different styles for each row of a table or list you can use the `cycle` method on the `loop` object::-
{% for row in rows %}
- {{ row }} {% endfor %}
| {{ cell }} | {% endfor %}
' + _('Hide Search Matches') + '
') .appendTo($('#searchbox')); } }, /** * init the domain index toggle buttons */ initIndexTable : function() { var togglers = $('img.toggler').click(function() { var src = $(this).attr('src'); var idnum = $(this).attr('id').substr(7); $('tr.cg-' + idnum).toggle(); if (src.substr(-9) === 'minus.png') $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); else $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); }).css('display', ''); if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { togglers.click(); } }, /** * helper function to hide the search marks again */ hideSearchWords : function() { $('#searchbox .highlight-link').fadeOut(300); $('span.highlighted').removeClass('highlighted'); }, /** * make the url absolute */ makeURL : function(relativeURL) { return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; }, /** * get the current relative url */ getCurrentURL : function() { var path = document.location.pathname; var parts = path.split(/\//); $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { if (this === '..') parts.pop(); }); var url = parts.join('/'); return path.substring(url.lastIndexOf('/') + 1, path.length - 1); }, initOnKeyListeners: function() { $(document).keyup(function(event) { var activeElementType = document.activeElement.tagName; // don't navigate when in search box or textarea if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT') { switch (event.keyCode) { case 37: // left var prevHref = $('link[rel="prev"]').prop('href'); if (prevHref) { window.location.href = prevHref; return false; } case 39: // right var nextHref = $('link[rel="next"]').prop('href'); if (nextHref) { window.location.href = nextHref; return false; } } } }); } }; // quick alias for translations _ = Documentation.gettext; $(document).ready(function() { Documentation.init(); });PK |>]>ta % html/_static/documentation_options.jsnu [ var DOCUMENTATION_OPTIONS = { URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), VERSION: '2.10.1', LANGUAGE: 'None', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true, SOURCELINK_SUFFIX: '.txt' };PK |>]' html/_static/down-pressed.pngnu [ PNG IHDR a IDATxc @ J@lKf[^g%_ HK Ŀ D Ab3CGhr.x /`X Wʱ 2 eF+,.xEJ lAR $WT?0i)1 m aU IENDB`PK |>]9. html/_static/down.pngnu [ PNG IHDR 7 IDATxP@ @Iߗ`&"z6xK@kbϢxs]M :/+gPd2GeÐ~߸J_c S_ S%exdU](UH>&;4i$n3> ycd IENDB`PK |>]S[S html/_static/file.pngnu [ PNG IHDR a IDATxR){l ۶ f=@ :3~箄rX$AX-D ~ lj(P%8<<9:: PO&$ l~X&EW^4wQ}^ͣ i0/H/@F)Dzq+j[SU5h/oY G&Lfs|{3%U+S`AF IENDB`PK |>]5Q( ( html/_static/jinja-small.pngnu [ PNG IHDR e sBIT|d pHYs ~ ~ [ tEXtSoftware www.inkscape.org< IDATxy,Guw}{Z6AY ` 0`00 ^f 6a!60ad"C 0F I0hyBOzһۻ}{̾ٙYU}}/23:uɓ~SD \? SJNgJ)vDe+9Y85Mbr9_}:=7Slk TD~ Md/zm Z8ۦDt:t]QJ]0U96$4~:0 $v a)"r"6=Ed SlDq%3y$1h" R