RETIRED, further work has moved to Debian project infrastructure
Go to file
Stefan Wehrmeyer a0b3083c06 Add .gitignore
2015-12-20 15:20:57 +01:00
docs Added sphinx-me generated docs shell. 2012-06-09 14:30:52 +10:00
overextends Only add builtins template option on Django >= 1.9 2015-12-20 15:20:50 +01:00
test_project Only add builtins template option on Django >= 1.9 2015-12-20 15:20:50 +01:00
.gitignore Add .gitignore 2015-12-20 15:20:57 +01:00
.hgignore Added .hgignore 2012-06-10 15:22:41 +10:00
.travis.yml Update supported/testing Django versions. 2015-07-23 09:51:41 +10:00
AUTHORS Added Carlton Gibson to AUTHORS. 2015-10-10 14:07:16 +11:00
LICENSE Added setup files: setup.py, LICENSE, MANIFEST. 2012-06-09 14:30:11 +10:00
MANIFEST.in Added setup files: setup.py, LICENSE, MANIFEST. 2012-06-09 14:30:11 +10:00
README.rst Don't import add_to_builtins on Django 1.9 2015-10-09 22:27:16 +02:00
setup.cfg Added wheel config 2014-02-18 12:34:32 +11:00
setup.py Update Python version classifiers in setup.py 2015-07-26 13:44:10 +10:00

image

Created by Stephen McDonald

Introduction

A Django reusable app providing the overextends template tag, a drop-in replacement for Django's extends tag, which allows you to use circular template inheritance.

The primary use-case for overextends is to simultaneously override and extend templates from other reusable apps, in your own Django project.

Example

Consider the following settings module and templates, with the apps app1 and app2 bundled in the project, for example's sake:

# settings.py
INSTALLED_APPS = (
    "app1",
    "app2",
    "overextends",
)
TEMPLATE_LOADERS = (
    "django.template.loaders.filesystem.Loader",
    "django.template.loaders.app_directories.Loader",
)
PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
TEMPLATE_DIRS = (os.path.join(PROJECT_ROOT, "templates"),)

<!-- myproject/app1/templates/pages/page.html -->
<h1>Title</h1>
{% block main %}
<p>A paragraph in app1</p>
{% enblock %}
<footer>Copyright 2012</footer>

<!-- myproject/app2/templates/pages/page.html -->
{% overextends "pages/page.html" %}
{% block main %}
<p>A paragraph in app2, that wants to be on top of app1's main block</p>
{{ block.super }}
{% enblock %}

<!-- myproject/templates/pages/page.html -->
{% overextends "pages/page.html" %}
{% block main %}
{{ block.super }}
<p>A paragraph in the project's template directory, under the other main blocks</p>
{% enblock %}

The resulting HTML rendered when pages/page.html was loaded would be:

<h1>Title</h1>
<p>A paragraph in app2, that wants to be on top of app1's main block</p>
<p>A paragraph in app1</p>
<p>A paragraph in the project's template directory, under the other main blocks</p>
<footer>Copyright 2012</footer>

For a detailed analysis of why you would use this approach, how it works, and alternative approaches, read my initial blog post: Circular Template Inheritance for Django

Installation

The easiest way to install django-overextends is directly from PyPi using pip by running the following command:

$ pip install -U django-overextends

Otherwise you can download django-overextends and install it directly from source:

$ python setup.py install

Project Configuration

Once installed you can configure your project to use django-overextends by adding the overextends app to the INSTALLED_APPS in your project's settings module:

INSTALLED_APPS = (
    # ... other apps here ...
    'overextends',
)

For Django 1.9+ you must add overextends to the builtins key of your TEMPLATES setting:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'APP_DIRS': True,
        'OPTIONS': {
            'builtins': ['overextends.templatetags.overextends_tags'],
        }
    },
]

Note that while the overextends tag is provided by the package overextends.templatetags.overextends_tags, it is unnecessary to use {% load overextends_tags %} in your templates. Like the extends tag, overextends must be the first tag in your template, so it is automatically added to Django's built-in template tags, removing the need to load its tag library in each template.