EOX Theming

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 < 8.0
Maple	>= 3.0 < 8.0
Nutmeg	>= 4.0 < 8.0
Olive	>= 5.0 < 8.0
Palm	>= 6.0 < 8.0
Quince	>= 7.0 < 9.0
Redwood	>= 7.2.0
Sumac	>= 8.1.0
Teak	>= 9.0.0
Ulmo	>= 9.3.0

The plugin is configured for the latest release (Teak). 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

1. Ensure you have a theme or themes following the Changing Themes guide

2. Ensure your environment is well-configured according to the Settings section

   Note

   In order to simplify this process, we encourage the use of Distro Tutor Plugin for managing the addition and compilation of custom themes: README of Distro

Installation

1. Install the plugin adding it to OPENEDX_EXTRA_PIP_REQUIREMENTS in the config.yml.

   OPENEDX_EXTRA_PIP_REQUIREMENTS:
      - eox-theming=={{version}}

2. Save the configuration with tutor config save

3. 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:

1. Add the themes to your instance by adding your themes folder to the container shared folder env/build/openedx/themes

2. Compile the themes after adding them:

   tutor images build openedx
   tutor local do init
   
    # or
   
   tutor local launch

3. 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")

Note for Teak and later versions (>= 9.0.0):

Starting from Teak, the function _make_mako_template_dirs requires a settings argument. You need to update the configuration block like this:

from django.conf import settings
from lms.envs.common import _make_mako_template_dirs  # pylint: disable=import-error

ENABLE_COMPREHENSIVE_THEMING = True
TEMPLATES[1]["DIRS"] = _make_mako_template_dirs(settings)
derive_settings("lms.envs.production")

Usage

1. 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"
           }
       }
   }

2. 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.

1. 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.

2. Compile the themes running tutor local launch

3. 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"

4. And finally, restart the platform with the tutor local restart so this settings are properly added

5. 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"
   }

6. 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.