Question

In this excellent Google Tech Talk by Jacob Kaplan-Moss, Jacob says that they added support for the include template tag despite previous dogmatic objections, and says that people shouldn’t use it.

Does anyone know why? A quick search didn’t show anything that would explain why. There’s nothing relevant in the now-fixed ticket where support for an include tag was added. I use include tags liberally to avoid repeating myself, which seems like a good idea, but maybe I’m missing some core reason why those who know think it’s bad.

Answer 1

I suppose he wants to encourage template reuse by inheritance (using extends) rather than by composition. Perhaps the implication is that if you can’t organise your templates this way, the dogmatic opinion is that your site is organised poorly. (For example, if you are reusing a navigation menu, shouldn’t it always be in the same place in the page structure? Why should each individual page decide where to put it?)

By the way, using include doesn’t do much to help you stay DRY, because any context that the included template requires must be passed from all the views that use it.

By contrast, using a custom inclusion template tag allows you to execute arbitrary Python code at the point where the tag is included, rather than in the view (or by shoving it into a model just to make it easier to access in the template).

As a trivial example, I wanted to show a list of users’ avatars. Using include, it looks like this:

{% for user in users %}
    {% with user.gravatar_url as avatar_url %}
        {% include "foo/bar/avatar.html" %}
    {% endwith %}
{% endfor %}

With a custom tag:

{% for user in users %}
    {% gravatar user.email %}
{% endfor %}

Using the custom inclusion tag meant that the Gravatar hashing logic no longer had to be a concern of the User model, nor of the view function.

---

This said, I think are are some situations where you inevitably have similar data in the context of multiple templates, you don’t need to do anything fancy with it, you just want to display some of its attributes so you don’t want to write a function to make it work.

For example, I wrote a blog application (who hasn’t?) which had two types of archive view: a basic sequential, X-posts-per-page one, and a monthly archive view. Both templates obviously had a list of posts in their context, both used exactly the same summary template fragment to show a title and excerpt from each post, but each template presented them in a slightly different context. So I used:

{# in archive_index.html #}
{% extends "base.html" %}

{# some stuff specific to sequential archives here #}

{% for post in posts %}
    {% include "post_summary.html" %}
{% endfor %}

{# probably more stuff specific to sequential archives #}

And…

{# in archive_monthly.html #}
{% extends "base.html" %}

{# some stuff specific to monthly archives here #}

{% for post in posts %}
    {% include "post_summary.html" %}
{% endfor %}

{# probably more stuff specific to monthly archives #}

It really seems that in this case, composition makes more sense than inheritance. In fact it was difficult at first to imagine how inheritance would work here at all. Well, it’s still possible:

{# in base_archive.html #}
{% extends "base.html" %}

{% block archive_header %}{% endblock %}

{% for post in posts %}
    {% include "post_summary.html" %}
{% endfor %}

{% block archive_pagination %}{% endblock %}

Now, the two different archives extend this and just inject their unique stuff into the blocks:

{# in archive_monthly.html #}
{% extends "base_archive.html" %}

{% block archive_header %}
    <h1>Archive for {{ month }}</h1>
{% endblock %}

{% block archive_pagination %}
    {# previous/next month links here #}
{% endblock %}

I’ll leave imagining what archive_index.html looks like as an exercise for the (no doubt bored) reader.

Phew! It feels smart to have come up with a way of doing the same thing using both composition and inheritance, but is the latter just bending over backwards to conform to the dogma that Jacob Kaplan-Moss mentioned?

Having just watched the video (yes, all 1 hour 5 minutes of it, just so I could finish answering this question), I don’t think Jacob would be enormously bothered. It sounded like an off-the-cuff comment, maybe a reference to which technique you ought to consider first.