Skip to main content

A Django reusable app providing the ability to use circular template inheritance.

Project description

https://secure.travis-ci.org/stephenmcd/django-overextends.png?branch=master

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-overextends-0.4.3.tar.gz (8.1 kB view details)

Uploaded Source

Built Distribution

django_overextends-0.4.3-py2.py3-none-any.whl (11.5 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file django-overextends-0.4.3.tar.gz.

File metadata

File hashes

Hashes for django-overextends-0.4.3.tar.gz
Algorithm Hash digest
SHA256 f53bfcec62731d1b4811745616ddefa849faee98874b01bbabd794381cbb8261
MD5 23c8dbbf78d2be466f6eea4a8ff195fb
BLAKE2b-256 a0f14a3b61c7f304a1a6c75133aa8793fdb1d287f09a7006e560a52dd469ab83

See more details on using hashes here.

File details

Details for the file django_overextends-0.4.3-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for django_overextends-0.4.3-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 e9c1082e384473ec03ab53821691d79a3f160fef43c15a0de44741b5e9430e4d
MD5 d4743649679bd2b7dbb093e95cf3bc00
BLAKE2b-256 00ea843fc542fae2af50f5c3d543245e8175307328c82b6bd1ef4d2b0edf4943

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page