== Extending templates ==

(Originally posted here by Simon Willison on 6th August 2008)

Django's template inheritance mechanism allows templates to extend other templates and replace named blocks within them. See here for a full explanation: http://www.djangoproject.com/documentation/templates/#template-inheritance

This feature becomes even more powerful when coupled with Django's template path concept, as discussed by Jeff Croft in this article: http://jeffcroft.com/blog/2008/aug/05/default-templates-django/

A frequently requested feature is the ability to provide an over-ride template that also extends itself. Consider the following:

{{{
# In settings.py
TEMPLATE_DIRS = ('/var/templates/default', '/var/templates/mysite')

# In default/homepage.html
BIG COMPLEX TEMPLATE HERE
{% block stylesheets %}<link rel="stylesheet" type="text/css" href="styles.css">{% endblock %}
MORE BIG COMPLEX TEMPLATE HERE

# In mysite/homepage.html
{% extends "homepage.html" %}
{% block stylesheets %}<link rel="stylesheet" type="text/css" href="mysite-styles.css">{% endblock %}
}}}

In other words, we want mysite/homepage.html to reuse default/homepage.html almost entirely, only replacing the stylesheets named block.

The above won't work - Django will throw confusing errors.

It turns out it IS possible to get this to work, if you're willing to do some devious tricks with your TEMPLATE_DIRS setting. Consider the following:

{{{
# In settings.py
TEMPLATE_DIRS = ('/var/templates/default', '/var/templates/mysite', '/var/templates')

# In mysite/homepage.html
{% extends "default/homepage.html" %}
{% block stylesheets %}<link rel="stylesheet" type="text/css" href="mysite-styles.css">{% endblock %}
}}}

hello


An alternative approach without using the parent directory trick: http://github.com/stephenmcd/django-overextends