Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Tree: 072fdda37f
Fetching contributors…
Cannot retrieve contributors at this time
167 lines (119 sloc) 5.64 KB
.. Python jinjatag documentation master file, created by
sphinx-quickstart on Wed Mar 31 16:25:58 2010.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to the JinjaTag documentation
.. toctree::
:maxdepth: 4
The jinjatag library makes it easy to take a python function and turn it
into an extension for jinja2.
The library provides a set of decorators for common tasks that can be
sent to simple python functions.
See for source and issues.
Module Contents
JinjaTag Extension
.. class:: jinjatag.JinjaTag()
The ``JinjaTag`` extension that needs to be registered with the jinja2
environment to enable all of the decorated functions. You must register
an instance of this with your jinja2 environment to use. For example::
>>> import jinjatag
>>> jinja_tag = jinjatag.JinjaTag()
>>> jinja2_env = Environment(extensions=[jinja_tag])
>>> jinja_tag.init()
Use only one JinjaTag instance per jinja2 environment.
.. method:: JinjaTag.init()
This method of JinjaTag will complete the decorator registration with
jinja2. This must be called on the JinjaTag instance after adding it
to the jinja2 environment but before any template is compiled/rendered.
Must be called *after* registering the ``JinjaTag`` instance with jinja2.
Running ``init`` before registering with the jinja2 environment will break.
.. staticmethod:: jinjatag.simple_tag(name=None)
This decorator wraps a single function to produce a simple tag that
can be called in any template using the jinja2 environment registered
The name for the tag can either be specified as the name argument or taken
as the name of the wrapped function. In the simplest form, you can
just put ``@jinjatag.simple_tag`` at the top of your function and just
use it as a macro::
import jinjatag
def my_simple_tag(width, height=None):
height = width if height is None else height
return '<br>'.join('=' * width for _ in range(height))
In the jinja2 template, just call the ``my_simple_tag`` as you might
{% my_simple_tag width=5 height=5*2 %}
The tag's syntax is simple: every argument *must* be passed by name with
no commas between them.
To specify the name argument, simply pass it as the first argument
when calling the decorator::
def my_simple_tag(width, height=None):
. . .
And this can be so used:
{% my_other_tag width=5 height=5*2 %}
.. staticmethod:: jinjatag.simple_block(name=None)
The ``simple_block`` decorator represents a single wrapped block of
content. For instance, suppose we want to implement the block tag
caesar cipher, which shifts every letter in the block by a defined
amount. That tag might look like::
def caesar_cipher(body, shift=13):
return ''.join(chr((ord(c) - 96 + shift) % 26 + 96)
if c.islower() else c for c in body)
Then to use it in a template, you would just have to write::
{% caesar_cipher shift=10 %}
the quick brown fox jumped over the lazy dog.
{% if 1 %}
raising elephants is so utterly boring.
{% endif %}
{% end_caesar_cipher %}
Note the use of 'end_' to determine the endblock. Jinja2 convention
does not use an underscore, so the simple_block allows you to choose
which convention --- both will work. If the tag contains an underscore,
you will likely be more inclined to separate the end with an underscore.
.. staticmethod:: jinjatag.multibody_block(name=None)
Sometimes the ``simple_block`` isn't enough---you want to be able to pull
in multiple block components and mix them to synthesize the result.
The ``multibody_block`` tag is what allows you to do this.
Once a multibody_block tag is defined with name ``NAME``, sub-blocks
can be defined within the main block with two additional tags::
{% NAME_block 'subblock_name' %}
{% NAME_end_block %}
The rendered output of the contents of the block will then be passed
as a keyword argument to the wrapped function. This is best described
with an example::
def captioned_object(body, header, caption, width='auto'):
return '''<div class="captioned" style="width: {};">
<p class="caption">{}</p>
</div>'''.format(width, header, body, caption)
Then to use this block in template code, one has the option
of *either* using the keyword argument syntax as in ``simple_tag``
or create whole sub-blocks. For example::
{% captioned_object width='200px' %}
<img src="me.jpg">
{% captioned_object_block 'header' %}
{% captioned_object_end_block %}
{% captioned_object_block 'footer' %}
Me on vacation
{% captioned_object_end_block %}
{% end_captioned_object %}
This will pass the arguments ``body, header, footer, and width`` to the
function. We could also put everything on one line::
{% captioned_object header='Image' footer='Me on vacation' width='200px' %}
<img src="me.jpg">
{% end_captioned_object %}
Note that to the function defined above, both templates are equivalent.
Jump to Line
Something went wrong with that request. Please try again.