Django: Extends or Include?

Question

My friend and I are having a small argument. In my current Django Project, I have created a file called menu.html which will contain a bunch of links configured and formatted into a list. Instead of manually hard-coding the menu into each page, I am currently including the menu using the following Django/Python code:

{% include 'menu.html' %}

However, my friend is suggesting that this is the incorrect way to do it. He said I need to use extends instead of include and then define content, something like this:

{% extend 'menu.html' %}
{% block content %}
The rest of my content here.
{% endblock %}

That's a bit of extra code. Does it really matter which I use? I would prefer to use the former.

Answer 1

Yes, it matters. First of all extends can only occur as the very first line of the file. Secondly, include pushes and pops a context object on the resolve stack, which means that value created in the context while in the include will go out of scope when it returns.

My rule is: create base.html template files that define the overall structure of your site and use liberal amounts of {% block foo %} around critical areas. Then all of your other templates extends the base (or something that itself extends the base) and you replace those blocks as needed.

include, on the other hand, is good for encapsulating things you may need to use in more than one place, maybe even on the same page.

Update:

I have been using my own library of template_tags for so long that I forget that Django's template language still has major gaps in functionality. The tag in question here is from an early django snippet called expr which I have heavily edited and extended. You can say, for example, {% expr 'Fred' as name %} (or any valid Python expression), and it will store the result in the 'name' slot in the current Context. If this occurs in an included template, name's value will be popped on exit from the template file.

You can sort of achieve this with the {% with %} tag, but expr gives me much greater flexibility, including doing arbitrarily complex calls. This originally came up when having to create complex cached objects that required expensive DBMS interactions that couldn't be done up in the view, they had to be invoked in the template itself.

Email me (in my profile) if you need to get deeper into this.