django-template-partials

django-template-partials integrates with the Django template loader, allowing you to target a specific partial directly via a string identifier using the # syntax.

In a View

You can set self.template_name (or the equivalent in your view) to include the partial name:

self.template_name = "example.html#test-partial"

Using the include tag

You can also include a specific partial from another template using the standard {% include %} tag:

{% include "example.html#test-partial" %}

# In view handler
self.template_name = "example.html#test-partial"

After migrating to Django Core, the partials tag is built-in. You must remove the {% load partials %} statement from your templates. The {% partialdef %} and {% endpartialdef %} tags will continue to function without the explicit load statement.

<!-- Before migration -->
{% load partials %}
{% partialdef my-partial %}
<!-- content -->
{% endpartialdef %}

<!-- After migration -->
{% partialdef my-partial %}
<!-- content -->
{% endpartialdef %}

To use partials, load the partials tags in your template. You can define a reusable named block using {% partialdef %} and render it later using {% partial %}.

Defining a partial

Use {% partialdef name %}. You can optionally include the name in the closing tag for readability: {% endpartialdef name %}.

Reusing a partial

Use {% partial name %} to render the content of the defined partial at that location. The partial is rendered with the current template context.

{% load partials %}

{% partialdef test-partial %}
TEST-PARTIAL-CONTENT
{% endpartialdef test-partial %}

{% block main %}
BEGINNING
{% partial test-partial %}
MIDDLE
{% partial test-partial %}
END
{% endblock main %}

Install the package using pip and add template_partials to your Django INSTALLED_APPS configuration.

pip install django-template-partials

INSTALLED_APPS = [
    "template_partials",
    ...,
]

Partials are rendered with the current template context. This allows them to work naturally inside loops. If you need to provide specific variables to a partial, use the standard Django {% with %} tag.

{% for object in object_list %}
    {% partial test-partial %}
{% endfor %}

{% with name=value othername=othervalue %}
    {% partial test-partial %}
{% endwith %}

The Loader class is a wrapper that integrates with Django's template loading system to enable partials. It takes a list of existing template loaders and attempts to resolve templates from them in order.

When a template name is requested using the # syntax (e.g., template_name#partial_name), the loader:

1. Splits the name into the base template_name and the partial_name.
2. Uses the underlying loaders to find the base template.
3. If a partial_name was provided, it searches the template for a defined partial with that name.
4. Returns the partial template object, making partials transparent to the view and response layers.

To avoid adding {% load partials %} to every template, you can add the partials tags to your Django template engine's builtins configuration in settings.py.

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "OPTIONS": {
            "builtins": [
                "template_partials.templatetags.partials",
            ],
            ...
        },
    },
    ...
]

OPTIONS = {
    "builtins": ["template_partials.templatetags.partials"],
}

To request a specific partial from a template, use the # character as a delimiter in the template name string. The format is:

template_name#partial_name

If the # character is not present, the loader returns the full template as usual. If the # character is present but the partial_name does not exist within the template, a TemplateDoesNotExist exception is raised.

# Example of how a template name is parsed internally
template_name, _, partial_name = "path/to/template.html#my_partial".partition("#")
# template_name is "path/to/template.html"
# partial_name is "my_partial"

As of Django 6.0, the partial and partialdef template tags are included in Django core.

If you are using django-template-partials, you no longer need to include {% load partials %} in your templates when running on Django 6.0 or later. For detailed migration instructions, refer to the project's Migration.md.

By default, adding template_partials to your INSTALLED_APPS automatically configures the Django template engine to support partials. It does this by wrapping your existing template loaders with template_partials.loader.Loader.

This automatic configuration modifies your TEMPLATES setting to include the partials loader as a layer over your standard filesystem and app directory loaders.

# In your settings.py
INSTALLED_APPS = [
    ...
    "template_partials",
    ...
]