Jinja2 Simple Tags

0.6.1 · active · verified Fri Apr 10

jinja2-simple-tags is a Python library that simplifies the creation of custom template tags within Jinja2 templates. It provides base classes like StandaloneTag, ContainerTag, and InclusionTag, allowing developers to extend Jinja2's functionality with Python code. The current version is 0.6.1, and it maintains an active release cadence.

Warnings

gotcha Output from custom tags (especially StandaloneTag) is HTML-escaped by default. If your tag generates raw HTML or script that should not be escaped, you must explicitly mark it as safe.
Fix: Set `safe_output = True` as a class attribute on your tag class, or return a `jinja2.Markup` object from your `render` method.
gotcha When using `InclusionTag`, be mindful of context inheritance. By default, it inherits the parent template's context. Explicitly manage context variables to avoid unexpected behavior or data leakage.
Fix: The `get_context()` method allows you to merge additional context variables. Understand Jinja2's context behavior (e.g., `with context` or `without context` in `include` statements) when designing your inclusion tags.
gotcha Jinja2-simple-tags relies on Jinja2's parsing. Common Jinja2 `TemplateSyntaxError` issues (e.g., unclosed tags, misspelled keywords, mismatched delimiters within the custom tag's arguments or content) will still apply and can be challenging to debug.
Fix: Carefully review your template syntax and the arguments passed to your custom tags. Enable Jinja2's strict undefined behavior for earlier detection of missing variables during development (`Environment(undefined=StrictUndefined)`).

Install

pip install jinja2-simple-tags Install with pip

Imports

StandaloneTag
```
from jinja2_simple_tags import StandaloneTag
```
Used for tags that do not require a closing tag.
ContainerTag
```
from jinja2_simple_tags import ContainerTag
```
Used for tags that require a closing tag and can contain content.
InclusionTag
```
from jinja2_simple_tags import InclusionTag
```
Used for tags that include other templates.

Quickstart

This quickstart demonstrates how to define a simple custom tag using StandaloneTag, register it with a Jinja2 environment, and render a template that uses the new tag to display the current time. Remember to pass your custom tag class to the `extensions` list of the Jinja2 Environment.

from jinja2 import Environment
from jinja2_simple_tags import StandaloneTag
from datetime import datetime

# 1. Define your custom standalone tag
class CurrentTimeTag(StandaloneTag):
    tags = {"now"}

    def render(self, format_string="%Y-%m-%d %H:%M:%S"): # Renamed 'format' to 'format_string' to avoid conflict with built-in format
        return datetime.now().strftime(format_string)

# 2. Set up Jinja2 Environment and load your extension
env = Environment(
    extensions=[CurrentTimeTag]
)

# 3. Create a template string using your custom tag
template_content = """
<p>The current date and time is: {% now %}</p>
<p>Formatted time: {% now '%H:%M' %}</p>
"""
template = env.from_string(template_content)

# 4. Render the template
output = template.render()
print(output)

view raw JSON →