Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions docs/tips.rst
Original file line number Diff line number Diff line change
Expand Up @@ -41,19 +41,21 @@ Partial Rendering
For requests made with htmx, you may want to reduce the page content you render, since only part of the page gets updated.
This is a small optimization compared to correctly setting up compression, caching, etc.

Using django-template-partials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Comment on lines -44 to -45
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we title this section "Using template partials" and then explain in terms of both django-template-partials and Django 6.0's new feature? I want it to still work for users who haven't upgraded to 6.0, especially since it's not even out yet!

Perhaps explain the 6.0 way, then the differences in django-template-partials: install the app, use {% load partial %} as well, ...

Using template partials
~~~~~~~~~~~~~~~~~~~~~~~~

The `django-template-partials package <https://github.com/carltongibson/django-template-partials>`__ extends the Django Template Language with reusable sections called “partials”.
It then allows you to render just one partial from a template.
Django 6.0 introduced built-in support for template partials.
This feature allows you to render just one partial from a template, which is particularly useful for htmx requests.
If you are using Django < 6.0, you can use the `django-template-partials <https://github.com/carltongibson/django-template-partials>`__ package.
The only major difference is the usage of the ``{% load partials %}`` tag at the top of the template.

Install ``django-template-partials`` and add its ``{% partialdef %}`` tag around a template section:
Define a partial using the ``{% partialdef %}`` tag around a template section:

.. code-block:: django

{% extends "_base.html" %}

{% load partials %}
{# {% load partials %} Only needed for Django < 6.0; not required for Django >= 6.0 #}

{% block main %}

Expand Down Expand Up @@ -106,12 +108,12 @@ This is done by adding ``#`` and the partial name to the template name:

htmx requests will render only the partial, whilst full page requests will render the full page.
This allows refreshing of the table without an extra view or separating the template contents from its context.
For a working example, see the Partial Rendering page of the :doc:`example project <example_project>`.
For a working example, see the "Partial Rendering" page of the :doc:`example project <example_project>`.

It’s also possible to use a partial from within a separate view.
This may be preferable if other customizations are required for htmx requests.

For more information on django-template-partials, see `its documentation <https://github.com/carltongibson/django-template-partials>`__.
For more information on Django's template partials, see `the Django documentation <https://docs.djangoproject.com/en/6.0/ref/templates/language/#template-partials>`__.

Swapping the base template
~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
1 change: 0 additions & 1 deletion example/example/settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,6 @@
INSTALLED_APPS = [
"example",
"django_htmx",
"template_partials",
"django.contrib.staticfiles",
]

Expand Down
3 changes: 1 addition & 2 deletions example/example/templates/partial-rendering.html
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
{% extends "_base.html" %}
{% load partials %}

{% block main %}
<section>
<p>
This example shows you how you can do partial rendering for htmx requests using <a href="https://github.com/carltongibson/django-template-partials">django-template-partials</a>.
This example shows you how you can do partial rendering for htmx requests using Django 6.0's built-in template partials.
The view renders only the content of the table section partial for requests made with htmx, saving time and bandwidth.
Paginate through the below list of randomly generated people to see this in action, and study the view and template.
</p>
Expand Down
3 changes: 1 addition & 2 deletions example/requirements.in
Original file line number Diff line number Diff line change
@@ -1,3 +1,2 @@
django
django-template-partials
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you test the example project with a fresh venv without django-template-partials installed? I think we need to drop template_partials from INSTALLED_APPS, at least:

"template_partials",

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I just ran manage.py check command.
I'll run and check.

django~=6.0a1
faker
14 changes: 4 additions & 10 deletions example/requirements.txt
Original file line number Diff line number Diff line change
@@ -1,18 +1,12 @@
# This file was autogenerated by uv via the following command:
# uv pip compile --universal requirements.in -o requirements.txt
asgiref==3.8.1
# uv pip compile requirements.in -o requirements.txt
asgiref==3.9.2
# via django
django==5.2
# via
# -r requirements.in
# django-template-partials
django-template-partials==24.4
django==6.0a1
# via -r requirements.in
faker==37.1.0
# via -r requirements.in
sqlparse==0.5.3
# via django
tzdata==2025.2
# via
# django
# faker
# via faker