Wagtail-themes

Site specific theme loader for Django Wagtail.

• Issues: https://github.com/moorinteractive/wagtail-themes/issues
• Testing: https://travis-ci.org/moorinteractive/wagtail-themes
• Coverage: https://coveralls.io/github/moorinteractive/wagtail-themes

Compatibility

• Django >= 4.2
• Wagtail >= 5.0

For older version of Django & Wagtail please use wagtail-themes==0.4.1.

Example app

See the example app for a working multisite with two different themes.

Run make and the app will install all the necessary files and fixtures for you. You can login with admin:admin and check how example.com and blog.example.com serve different themes.

Installation

Install the package

pip install wagtail-themes

Add wagtailthemes to your INSTALLED_APPS

INSTALLED_APPS = [
    'wagtail.contrib.forms',
    'wagtail.contrib.redirects',
    'wagtail.embeds',
    'wagtail.sites',
    'wagtail.users',
    'wagtail.snippets',
    'wagtail.documents',
    'wagtail.images',
    'wagtail.search',
    'wagtail.admin',
    'wagtail',

    'modelcluster',
    'taggit',

    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    'wagtailthemes',
]

Add ThemeMiddleware to your MIDDLEWARE.

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    'wagtail.contrib.redirects.middleware.RedirectMiddleware',
    'wagtailthemes.middleware.ThemeMiddleware',
]

Now make sure the ThemeLoader is added to your loaders config in the setting TEMPLATES. Note that Django by default adds APP_DIRS to the setting, which conflicts with defining your custom loaders config.

Also note that the ThemeLoader must be placed on the top of the list (otherwise default templates will be found first).

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            os.path.join(BASE_DIR, 'templates'),
        ],
        # Remove 'APP_DIRS': True at this position
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
            'loaders': [
                'wagtailthemes.loaders.ThemeLoader',
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
            ]
        },
    },
]

Important: please make sure you don't have django.template.loaders.cached.Loader in your loaders.

Now select where your themes are stored with the WAGTAIL_THEME_PATH settings which has a default value of None.

WAGTAIL_THEME_PATH = 'themes'

Note that the setting WAGTAIL_THEME_PATH is optional. We strongly recommend using this if you have a large set of themes to keep your template directory maintainable.

Finally define your to be used themes in the setting WAGTAIL_THEMES

WAGTAIL_THEMES = [
    ('brand', 'Brand site'),
    ('personal', 'Personal site')
]

ThemeLoader

The ThemeLoader class searches for files in your (see settings above) defined DIRS config for TEMPLATES.

In this case templates files will be found in the following order (for this example code we have set brand as theme in our CMS)

1. /myapp/templates/themes/brand/
2. /myapp/templates/

Its wise to build your templates as you are used to and only override the template files you want to customize in your theme.