maykinmedia/django-label-loaders

Django Label Templates

A custom template loader for multi-site set-ups.

This is intended for users of django.contrib.sites for multi-site cases where a different site can have different templates, not only a different styling.

The custom template loaders will try to find a template for the currently active site, and fall back on a generic template.

Installation

Install with pip:

pip install django-label-templates

Configuration

Installed apps

Make sure that django.contrib.sites is in your INSTALLED_APPS.

Specify template loaders

You also need to enable the loader in the settings, similar to Django's cached template loader. The loader takes an iterable (list or tuple) of loaders to find the templates. Example - and probably most used - set-up:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        # APP_DIRS must be False if you specify the loaders yourself
        'APP_DIRS': False,
        'DIRS': [
            os.path.join(PROJECT_DIR, 'templates'),
        ],
        'OPTIONS': {
            'loaders': [
                ('label_templates.loaders.Loader', [
                    'django.template.loaders.filesystem.Loader',
                    'django.template.loaders.app_directories.Loader',
                ]),
            ],
        },
    },
]

If you wish, this template loader can also be wrapped in other loaders, like django.template.loaders.cached.Loader.

Configure the site labels

For the final step, one extra custom settings is required: SITELABELS.

# the import is safe and does NOT depend on django.conf.settings
from label_templates.sites import SiteLabels, SiteChoice

class SITELABELS(SiteLabels):
    site = SiteChoice('example.com', site_id=1)
    site2 = SiteChoice('example2.com', site_id=2)

This settings is used to look up the label-prefix for the templates. The site with ID=1 will resolve to a subfolder site/, so to load the template example.html, the loader will try to find site/example.html first, and failing that, will try to just load example.html.

For the site with ID=2, the prefix site2 is used.

Note

To find the matching site, the loader tries to get the label for the SiteChoice based on django.contrib.sites.models.Site.name, with a fallback to domain. So, for the first argument of SiteChoice, it's safest to enter the Site.name value.

Limitations

Since the {% extends %} tag uses the same loader configuration, you can not let a label-specific template inherit from a generic template with the same name.

A workaround is the following structure:

templates/
├── mylabel/
|   └── base.html  # extends _base.html and overrides stuff
├── _base.html
└── base.html  # extends _base.html, overrides nothing

Versions supported

This library is tested against Django 1.8 and 1.9. The corresponding Python versions for the Django versions apply. Consult tox.ini for an up to date build matrix.

django-label-loaders's Issues

django-label-loaders vs. django-template-labels

While it's no real impediment to using the code, I thought you'd like to know that the name passed as setup's url arg currently 404s (the readme also uses the python name in main heading and body text but uses the github name for the badge links which aren't hiddenwhen README'ing from the cli). Normally I would just submit a fix by PR, but while the github project name matches the module's name, the setup url correctly refers to the python package name... "django-label-template-loaders" seems like a mouthful to me, even by Django standards, so I'll leave the naming to you and just go work on some cache invalidation instead... ;)

Thanks for sharing your code!