Open edX Theming Plugin
Project description
Overview
Eox theming is a plugin for Open edX platform, and part of the Edunext Open edX Extensions (aka EOX) that provides a series of tools to customize and launch themes.
This plugin improves the edx-platform by enhancing its Django and Mako template management. It allows for a more flexible theming process by introducing different levels of customization, enabling templates to be accessed from various theme directories where custom themes were stored.
The plugin conducts a hierarchical search for the requested template. It begins with the main theme (identified by name), then moves to the second level (identified by parent), and finally to the third level (identified by grandparent). This hierarchical approach ensures that the plugin searches through the theme directories, prioritizing the most specific customizations over the default ones. You can find how to use the theme hierarchy in the upcoming Usage section.
Compatibility Notes
Open edX Release |
Version |
---|---|
Juniper |
>= 1.0 < 2.0 |
Koa |
>= 2.0 < 3.0 |
Lilac |
>= 2.0 |
Maple |
>= 3.0 |
Nutmeg |
>= 4.0 |
Olive |
>= 5.0 |
Palm |
>= 6.0 |
Quince |
>= 7.0 |
Redwood |
>= 7.2.0 |
⚠️ From Lilac version Django 2.2 is not supported, you should use Django 3.2 and eox-tenant >=4.0.
The plugin is configured for the latest release (Redwood). If you need compatibility for previous releases, go to the README of the relevant version tag and if it is necessary you can change the configuration in eox_theming/settings/common.py.
For example, if you need compatibility for Koa, you can go to the v2.0.0 README to the Compatibility Notes section; you’ll see something like this:
EOX_THEMING_STORAGE_BACKEND = 'eox_theming.edxapp_wrapper.backends.l_storage'
EOX_THEMING_EDXMAKO_BACKEND = 'eox_theming.edxapp_wrapper.backends.l_mako'
Then you need to change the configuration in eox_theming/settings/common.py to use the appropriated ones.
🚨 If the release you are looking for is not listed, please note:
If the Open edX release is compatible with the current eox-theming version (see Compatibility Notes), the default configuration is sufficient.
If incompatible, you can refer to the README from the relevant version tag for configuration details (e.g., v2.0.0 README).
Pre-requirements
Ensure you have a theme or themes following the Changing Themes guide
Ensure your environment is well-configured according to the Settings section
Installation
Install the plugin adding it to OPENEDX_EXTRA_PIP_REQUIREMENTS in the config.yml.
OPENEDX_EXTRA_PIP_REQUIREMENTS: - eox-theming=={{version}}
Save the configuration with tutor config save
Launch the platform with tutor local launch
Settings
If you chose to use Distro Tutor Plugin, just follow the instructions given in the Themes section. Otherwise, if you are doing the process manually, follow this steps:
Add the themes to your instance by adding your themes folder to the container shared folder env/build/openedx/themes
Compile the themes after adding them:
tutor images build openedx tutor local do init # or tutor local launch
Add the following settings to your environment file env/apps/openedx/settings/lms/production.py:
COMPREHENSIVE_THEME_DIRS.extend( [ "/path-to-your-themes-folder/in-the-lms-container/edx-platform", "/path-to-your-themes-folder/in-the-lms-container/edx-platform/sub-folder-with-more-themes", ] ) EOX_THEMING_DEFAULT_THEME_NAME = "my-theme-1" # Or the theme you want ################## EOX_THEMING ################## if "EOX_THEMING_DEFAULT_THEME_NAME" in locals() and EOX_THEMING_DEFAULT_THEME_NAME: from lms.envs.common import _make_mako_template_dirs # pylint: disable=import-error ENABLE_COMPREHENSIVE_THEMING = True TEMPLATES[1]["DIRS"] = _make_mako_template_dirs derive_settings("lms.envs.production")
Usage
With eox-tenant create a new route or modify an existing one to point to a tenant config that lists your theme names in hierarchical order. This hierarchy, which follows the priority for template lookup, uses the attributes name, parent, and grandparent respectively. Your tenant config JSON will need a property similar to the following one:
{ "EDNX_USE_SIGNAL": true, "THEME_OPTIONS": { "theme": { "name":"my-theme-1", "parent":"my-theme-2", "grandparent":"my-theme-3" } } }
If you want to use different themes or modify the hierarchy, you just have to modify the “THEME_OPTIONS” property in your tenant config ensuring the theme you want to use was previously added to the platform.
Use case example
Having the following theme folder structure:
themes-main-folder
├── edx-platform
└── global-customizations
└── lms
└── static
└── templates
└── cms
└── static
└── templates
└── more-specific-customizations
└── org-customization-theme
└── lms
└── static
└── templates
└── cms
└── static
└── templates
└── much-more-specific-customizations
└── client-customization-theme
└── lms
└── static
└── templates
└── cms
└── static
└── templates
NOTE
You can see there are 3 levels of customization in the themes folder: global-customizations, more-specific-customizations, and much-more-specific-customizations; the names are just to illustrate the hierarchy that the example will follow.
Add the themes-main-folder to env/build/openedx/themes folder in your environment to make the themes available to the platform; this folder is shared with the container.
Compile the themes running tutor local launch
Then, ensure are properly configured the Settings required and customize these:
COMPREHENSIVE_THEME_DIRS.extend( [ "/openedx/themes/themes-main-folder/edx-platform", "/openedx/themes/themes-main-folder/edx-platform/more-specific-customizations", "/openedx/themes/themes-main-folder/edx-platform/most-specific-customizations" ] ) EOX_THEMING_DEFAULT_THEME_NAME = "client-customization-theme"
And finally, restart the platform with the tutor local restart so this settings are properly added
Now you just have to create a Route with the "theme" attribute in the tenant config to point to your themes in the hierarchy you choose:
"theme": { "name":"client-customization-theme", "parent":"org-customization-theme", "grandparent":"global-customizations" }
Restart again with tutor local restart and enjoy :)
Contributing
Contributions are welcome! See our CONTRIBUTING file for more information - it also contains guidelines for how to maintain high code quality, which will make your contribution more likely to be accepted.
License
This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for eox_theming-7.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 37947b67ce14952854579edb7b08b1b34f18c7792bf9c9013b77a1da3b533395 |
|
MD5 | ff620bc5ddd83a8d62e0aa3f78ebabbb |
|
BLAKE2b-256 | c2df0d15ee96da4e6942f56b5aa30cab843de3479dcc395aa9b242f7a14e3797 |