django-block-fragments 0.1.1

Reusable block fragments for the Django Template Language.

django-block-fragments

Render only the content of a specific block of a Django template. This also works for arbitrary template inheritance or when the block is in an included template.

Rendering only a part of a template is especially useful when using Django together with libraries like HTMX, see Template Fragments.

Installation

Install with pip:

pip install django-block-fragments

Or with uv:

uv add django-block-fragments

Then add block_fragments to INSTALLED_APPS:

INSTALLED_APPS = [
    ...,
    "block_fragments",
    ...,
]

[!NOTE] django-block-fragments currently only supports the Django template backend.

See Advanced configuration (below) for more options.

Usage

Once installed and having a template like this:

...
{% block content %}
Some content
{% endblock content %}
...

You can render just the "content" block in a view with:

from django.shortcuts import render

def my_view(request):
    return render(request, "template.html#content", {})

You can also include just the "content" block in another template:

{% include "template.html#content" %}

Advanced configuration

By default, adding "block_fragments" to your INSTALLED_APPS will try to configure any Django template backend to use the block fragments template loader.

If you need to control this behavior, you can use the alternative SimpleAppConfig, which will not adjust your TEMPLATES setting:

INSTALLED_APPS = [
    "block_fragments.apps.SimpleAppConfig",
    ...,
]

If you use SimpleAppConfig, you will need to configure the template loader yourself.

A wrap_loaders() function is available, and can be used to configure any specific template engine instance with the block fragments loader.

You can use the backend's NAME to wrap_loaders() to add the block fragments loader just for that backend:

from block_fragments.apps import wrap_loaders

TEMPLATES = [
    ...,
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "NAME": "myname",
        "OPTIONS": {
           ...,
        },
    },
    ...,
]

wrap_loaders("myname")

If the NAME isn't provided, the penultimate element of the BACKEND value is used - for example, "django.template.backends.django.DjangoTemplates" would be equivalent to a NAME of "django".

Under the hood, wrap_loaders() is equivalent to explicitly defining the loaders by-hand. Assuming defaults…

from django.conf import settings

default_loaders = [
    "django.template.loaders.filesystem.Loader",
    "django.template.loaders.app_directories.Loader",
]
cached_loaders = [("django.template.loaders.cached.Loader", default_loaders)]
block_fragment_loaders = [("block_fragments.loader.Loader", cached_loaders)]

settings.TEMPLATES[...]['OPTIONS']['loaders'] = block_fragment_loaders

… where TEMPLATES[...] is the entry in TEMPLATES with the NAME matching that passed to wrap_loaders().

Development

Fork, then clone the repo:

git clone [e-mail]:your-username/django-block-fragments.git

Install dependencies (needs uv to be installed):

uv sync

Then you can run the tests by using pytest:

uv run pytest

Or with coverage:

uv run pytest --cov

Acknowledgements

This project is heavily inspired and uses code from django-template-partials by Carlton Gibson and django-render-block by Patrick Cloke. So a big thank you to them!

FAQ

Why django-block-fragments when django-template-partials and django-render-block already exist?

I was looking for a way to reuse the already existing block tags of the Django Template Language (like django-render-block does) but also wanted to have the convenience of using template loaders (like django-template-partials does). So django-block-fragments tries to combine features of both of these great projects.

How to use django-block-fragments with django-cotton?

When using django-block-fragments together with django-cotton the automatic loader configuration won't work (as both would overwrite each other). So you must use the SimpleAppConfig and configure the template loaders manually like in the example below.

INSTALLED_APPS = [
    "django_cotton.apps.SimpleAppConfig",
    "block_fragments.apps.SimpleAppConfig",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "OPTIONS": {
            "loaders": [
                (
                    "block_fragments.loader.Loader",
                    [
                        (
                            "django.template.loaders.cached.Loader",
                            [
                                "django_cotton.cotton_loader.Loader",
                                "django.template.loaders.filesystem.Loader",
                                "django.template.loaders.app_directories.Loader",
                            ],
                        )
                    ],
                )
            ],
            "context_processors": [
                # no changes
            ],
            "builtins": [
                "django_cotton.templatetags.cotton",
            ],
        },
    },
]

[!NOTE] Because we're specifying the loaders manually, Django's APP_DIRS setting no longer has any effect. If you still want to load templates from the apps automatically, make sure to add the django.template.loaders.app_directories.Loader as in the example above.

License

MIT License