https://github.com/stephenmcd/django-overextends

Circular template inheritance for Django
https://github.com/stephenmcd/django-overextends

Last synced: 28 days ago
JSON representation

Circular template inheritance for Django

• Host: GitHub
• URL: https://github.com/stephenmcd/django-overextends
• Owner: stephenmcd
• License: bsd-2-clause
• Created: 2012-06-09T04:32:54.000Z (over 12 years ago)
• Default Branch: master
• Last Pushed: 2020-03-25T19:51:02.000Z (over 4 years ago)
• Last Synced: 2024-11-07T09:11:44.462Z (about 1 month ago)
• Language: Python
• Homepage:
• Size: 37.1 KB
• Stars: 108
• Watchers: 8
• Forks: 26
• Open Issues: 7
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

• starred-awesome - django-overextends - Circular template inheritance for Django (Python)

README

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

   :target: http://travis-ci.org/stephenmcd/django-overextends

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"),)

    

    
Title

    {% block main %}

    
A paragraph in app1

    {% enblock %}

    Copyright 2012


    

    {% overextends "pages/page.html" %}

    {% block main %}

    
A paragraph in app2, that wants to be on top of app1's main block

    {{ block.super }}

    {% enblock %}


    

    {% overextends "pages/page.html" %}

    {% block main %}

    {{ block.super }}

    
A paragraph in the project's template directory, under the other main blocks

    {% enblock %}


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

    
Title

    
A paragraph in app2, that wants to be on top of app1's main block

    
A paragraph in app1

    
A paragraph in the project's template directory, under the other main blocks

    Copyright 2012


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.

.. _`Circular Template Inheritance for Django`: http://blog.jupo.org/2012/05/17/circular-template-inheritance-for-django/

.. _`pip`: http://www.pip-installer.org/