Composition for django templates.
Project description
Django Compose Tag
Compose templates easily
Django Compose tags provide the tags to ease templates composition,
with an api close to the include
template tag.
The api is thought to ease the implementation and usage of design systems in django.
Overview
Write your template as you would for the include
tag:
<!-- card.html -->
<article class="card">
<div class="card-body">{{ children }}</div>
<footer class="card-footer">{{ footer }}</footer>
</article>
The compose
tag
The compose
template tag behave similarly to django's include
.
The main difference is that the content between {% compose %}
and {% endcompose %}
is regular django template that's accessible withing the composed template as the {{ children }}
variable.
{% load compose %}
{% compose "card.html" footer="My footer" %}
<p>card.html receive this as the {{ children }} variable</p>
<p>You can use {{ context_varialbe }} in here.</p>
{% endcompose %}
By default the composed template doesn't have access to the context, if you need access to the context set the takes_context option {% compose "card.html" takes_context %}
. takes_context
is the opposite of the only
The define
tag
define
The define
template tag allows you to set a new variable from within a template. That's a convenient way to use template rendered variables for any tag parameter.
{% define mylink %}<a href={{ link.url }}>Go to {{ link.name }}{% enddefine %}
{% include "card.html" children="Card body" footer=mylink %}
{% compose "card.html" footer=mylink %}
Card body with {{ context_variable }}
{% endcompose %}
Custom composition tag
composition_tag
is to compose
what inclustion_tag
is to the include
tag.
Define you tag function and decorate it with composition_tag
, the decorator takes care of passing the children as the first argument of your custom tag.
# mydesignsystem/templatetags/mydesignsystem.py
from django.template import Library
from compose_tags import composition_tag
register = Library()
@register.tag
@composition_tag('card.html', takes_context=True)
def card(children, context, next, cancelable=False):
return {
"children": children,
"footer": create_footer(next, cancelable),
}
Then use it in your templates, by default the tag is named after your function name.
{% load mydesignsystem %}
{% card next=someurl cancelable=True %}My card children{% endcard %}
Declaring composition_tag
There are multiple ways to use composition_tag. The first is as a decorator:
@register.tag
@composition_tag('template.html')
def mytag(children, **kwargs):
# Usage: {% mytag %}children{% endmytag %}
...
@register.tag("customname")
@composition_tag('template.html')
def mytag(children, **kwargs):
# Usage: {% customname %}children{% endcustomname %}
...
When you don't need to do any python processing, there is a default implementation that forward all parameters as is. When you rely on that default implementation the default tag name is derived from the template name.
Which mean register.tag(composition_tag("button.html"))
is equivalent to
@register.tag
@composition_tag('button.html')
def button(children, **kwargs):
return {
**kwargs,
"children": children
}
As with the decorator usage, you can override the tag name: register.tag("mybutton", composition_tag("button.html"))
Requirements
- Python (3.6, 3.7, 3.8, 3.9, 3.10, 3.11)
- Django (2.2, 3.0, 3.1, 3.2, 4.0, 4.1)
We highly recommend and only officially support the latest patch release of each Python and Django series.
Installation
Install using pip install django-compose-tags
Add 'compose_tags'
to your INSTALLED_APPS
setting.
INSTALLED_APPS = [
...
'compose_tags',
]
If you use compose
a lot we recommend you add it to your builtins:
TEMPLATES = [
{
"BACKEND": "django.template.backends.django.DjangoTemplates",
"OPTIONS": {
# ...
"builtins": ["compose_tags.templatetags.compose"],
}
}
]
Alternatives
Django Compose Tag purposely provide a simple api based solely on templates.
If Django Compose Tag doesn't cover your requirements we recommend you take a look at jinja.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django-compose-tags-0.0.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5e47a3ab612db6164ddb509b257de4c913022e102f4bf83b06f5a9c08af0338b |
|
MD5 | ccf29911f3422cfb90919ed26f04a921 |
|
BLAKE2b-256 | b6534f9dd925fe58e0896467b765c0f8817f3e3323991af5fe6693e8efa536e0 |
Hashes for django_compose_tags-0.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a8543cafab8bcee706bcce96d9f3a2203ddb432c48e7b15afacf61e50941f174 |
|
MD5 | cc19d8159b64414027c964d4dabb531f |
|
BLAKE2b-256 | e92631b525d61ff1bd5ceecd7a68797a464941acc71fdcbcf34bd0d7b0d8b10f |