Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/moorinl/wagtail-themes
Site specific theme loader for Django Wagtail.
https://github.com/moorinl/wagtail-themes
Last synced: 2 months ago
JSON representation
Site specific theme loader for Django Wagtail.
- Host: GitHub
- URL: https://github.com/moorinl/wagtail-themes
- Owner: moorinl
- License: mit
- Created: 2016-09-09T15:28:58.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2023-05-16T08:47:38.000Z (over 1 year ago)
- Last Synced: 2024-05-21T13:51:57.884Z (8 months ago)
- Language: Python
- Size: 93.8 KB
- Stars: 102
- Watchers: 6
- Forks: 13
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-wagtail - Wagtail Themes - Site-specific theme loader for Wagtail. (Apps / Misc)
README
# Wagtail-themes
Site specific theme loader for Django Wagtail.
[](https://pypi.python.org/pypi/wagtail-themes/)
[](https://github.com/moorinl/wagtail-themes/actions/workflows/ci.yml)
[](https://coveralls.io/github/moorinteractive/wagtail-themes?branch=master)
* Issues: [https://github.com/moorinteractive/wagtail-themes/issues](https://github.com/moorinteractive/wagtail-themes/issues)
* Testing: [https://travis-ci.org/moorinteractive/wagtail-themes](https://travis-ci.org/moorinteractive/wagtail-themes)
* Coverage: [https://coveralls.io/github/moorinteractive/wagtail-themes](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](https://github.com/moorinteractive/wagtail-themes/tree/master/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`
```python
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`.
```python
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).
```python
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`.
```python
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`
```python
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.