-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
perf: add redwood compatibility (#55)
* chore: update plugin and workflows requirements * docs: improve README & update changelog * fix: footer_overrides were skipped rendering the default one eduNEXT/eox-release#9
- Loading branch information
Showing
17 changed files
with
241 additions
and
180 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,154 +1,225 @@ | ||
| ======================= | ||
| Open edX Theming Plugin | ||
| ======================= | ||
| =========== | ||
| EOX Theming | ||
| =========== | ||
| |Maintainance Badge| |Test Badge| |PyPI Badge| |Python Badge| | ||
|
|
||
| Features | ||
| -------- | ||
| .. |Maintainance Badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen | ||
| :alt: Maintainance Status | ||
| .. |Test Badge| image:: https://img.shields.io/github/actions/workflow/status/edunext/eox-theming/.github%2Fworkflows%2Ftests.yml?label=Test | ||
| :alt: GitHub Actions Workflow Test Status | ||
| .. |PyPI Badge| image:: https://img.shields.io/pypi/v/eox-theming?label=PyPI | ||
| :alt: PyPI - Version | ||
| .. |Python Badge| image:: https://img.shields.io/pypi/pyversions/eox-theming.svg | ||
|
|
||
| This plugin provides a stable place from where to create and launch your openedx theme. | ||
| Overview | ||
| ======== | ||
|
|
||
| Eox theming is a plugin for `Open edX platform <https://github.com/openedx/edx-platform>`_, and part of the Edunext Open edX Extensions (aka EOX) that provides a series of tools to customize and launch themes. | ||
|
|
||
| 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 | | ||
| +------------------+---------------------+ | ||
|
|
||
| **NOTE**: From Lilac version Django 2.2 is not supported, you should use Django 3.2 and eox-tenant >=4.0. | ||
|
|
||
| The following changes to the plugin settings are necessary. If the release you are looking for is | ||
| not listed, then the accumulation of changes from previous releases is enough. | ||
|
|
||
| Juniper | ||
| ~~~~~~~ | ||
|
|
||
| .. code-block:: bash | ||
| EOX_THEMING_BASE_FINDER_BACKEND = 'eox_theming.edxapp_wrapper.backends.j_finders' | ||
| EOX_THEMING_BASE_LOADER_BACKEND = 'eox_theming.edxapp_wrapper.backends.j_loaders' | ||
| EOX_THEMING_SITE_THEME_BACKEND = 'eox_theming.edxapp_wrapper.backends.j_models' | ||
| EOX_THEMING_CONFIGURATION_HELPER_BACKEND = 'eox_theming.edxapp_wrapper.backends.j_configuration_helpers' | ||
| EOX_THEMING_THEMING_HELPER_BACKEND = 'eox_theming.edxapp_wrapper.backends.j_theming_helpers' | ||
| EOX_THEMING_STORAGE_BACKEND = 'eox_theming.edxapp_wrapper.backends.j_storage' | ||
| STATICFILES_STORAGE = 'eox_theming.theming.storage.EoxProductionStorage' | ||
| EOX_THEMING_EDXMAKO_BACKEND = 'eox_theming.edxapp_wrapper.backends.j_mako' | ||
| Koa (optional)** | ||
| ~~~~~~~~~~~~~~~~ | ||
|
|
||
| .. code-block:: bash | ||
| EOX_THEMING_STORAGE_BACKEND = 'eox_theming.edxapp_wrapper.backends.l_storage' | ||
| EOX_THEMING_EDXMAKO_BACKEND = 'eox_theming.edxapp_wrapper.backends.l_mako' | ||
| 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. | ||
|
|
||
| Lilac - Maple - Nutmeg - Olive - Palm - Quince | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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 <https://github.com/eduNEXT/eox-theming/blob/v2.0.0/README.md>`_ to the ``Compatibility Notes`` section; you'll see something like this: | ||
|
|
||
| .. code-block:: bash | ||
| .. code-block:: python | ||
| 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. | ||
|
|
||
| Those settings can be changed in ``eox_theming/settings/common.py`` or, for example, in ansible configurations. | ||
| 🚨 If the release you are looking for is not listed, please note: | ||
|
|
||
| **NOTE**: the current ``common.py`` works with Open edX lilac version. | ||
| - If the Open edX release is compatible with the current eox-theming version (see `Compatibility Notes <https://github.com/eduNEXT/eox-theming?tab=readme-ov-file#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 <https://github.com/eduNEXT/eox-theming/blob/v2.0.0/README.md>`_). | ||
|
|
||
| Installation | ||
| ------------ | ||
|
|
||
| Open edX devstack | ||
| ~~~~~~~~~~~~~~~~~ | ||
|
|
||
| - Clone this repo in the src folder of your devstack. | ||
| - Open a new Lms/Devstack shell. | ||
| - Install the plugin as follows: pip install -e /path/to/your/src/folder | ||
| - Restart lms/cms services. | ||
| Pre-requirements | ||
| ================ | ||
| #. Ensure you have a theme or themes following the `Changing Themes guide <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/changing_appearance/theming/index.html>`_ | ||
| #. Ensure your environment is well-configured according to the `Settings`_ section | ||
|
|
||
| Tutor | ||
| ~~~~~ | ||
| .. 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 <https://github.com/eduNEXT/tutor-contrib-edunext-distro?tab=readme-ov-file#themes>`_ | ||
|
|
||
| - Install the plugin with OPENEDX_EXTRA_PIP_REQUIREMENTS, this should be added in the config.yml. | ||
| - Restart lms/cms services. | ||
| Installation | ||
| ============ | ||
|
|
||
| Usage | ||
| ----- | ||
| #. Install the plugin adding it to ``OPENEDX_EXTRA_PIP_REQUIREMENTS`` in the ``config.yml``. | ||
|
|
||
| .. code-block:: yaml | ||
| OPENEDX_EXTRA_PIP_REQUIREMENTS: | ||
| - eox-theming=={{version}} | ||
| Include a usage description for your plugin. | ||
| #. Save the configuration with ``tutor config save`` | ||
| #. Launch the platform with ``tutor local launch`` | ||
|
|
||
| Settings | ||
| ~~~~~~~~ | ||
| ======== | ||
|
|
||
| To start using eox-theming, we must make the settings shown in the tenant settings (if we don't have one created, create it and configure it), add some available settings to the tenant: | ||
| If you chose to use ``Distro Tutor Plugin``, just follow the instructions given in the `Themes section <https://github.com/eduNEXT/tutor-contrib-edunext-distro/blob/master/README.md#themes>`_. Otherwise, if you are doing the process manually, follow this steps: | ||
|
|
||
| .. code-block:: json | ||
| #. Add the themes to your instance by adding your themes folder to the container shared folder ``env/build/openedx/themes`` | ||
|
|
||
| {"THEME_OPTIONS":{"theme":{"grandparent":"test-3","name":"test-1","parent":"test-2"}}} | ||
| #. Compile the themes after adding them: | ||
|
|
||
| .. code-block:: bash | ||
| tutor images build openedx | ||
| tutor local do init | ||
| For this, you must also make sure you have eox-tenant installed in your environment, | ||
| and to configure it we must locate the `common.py`_ | ||
| file and set the ``USE_EOX_TENANT`` variable to ``True`` | ||
| # or | ||
| .. _common.py: https://github.com/eduNEXT/eox-tenant/blob/master/eox_tenant/settings/common.py#L52 | ||
| tutor local launch | ||
| Include the follow configuration in devstack.py: | ||
| #. Add the following settings to your environment file ``env/apps/openedx/settings/lms/production.py``: | ||
|
|
||
| .. code-block:: python | ||
| .. code:: python | ||
| 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") | ||
| """ | ||
| Production Django settings for eox_theming project. | ||
| """ | ||
| from __future__ import unicode_literals | ||
| def plugin_settings(settings): | ||
| """ | ||
| Set of plugin settings used by the Open Edx platform. | ||
| More info: https://github.com/edx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst | ||
| """ | ||
| settings.STATICFILES_FINDERS = [ | ||
| 'eox_theming.theming.finders.EoxThemeFilesFinder', | ||
| ] + settings.STATICFILES_FINDERS | ||
| settings.STATICFILES_STORAGE = 'eox_theming.theming.storage.EoxDevelopmentStorage' | ||
| from lms.envs.common import _make_mako_template_dirs # pylint: disable=import-error | ||
| settings.ENABLE_COMPREHENSIVE_THEMING = True | ||
| settings.COMPREHENSIVE_THEME_DIRS = [ | ||
| '/edx/src/themes/ednx-test-themes/edx-platform/', | ||
| ] | ||
| settings.TEMPLATES[1]["DIRS"] = _make_mako_template_dirs | ||
| settings.derive_settings("lms.envs.devstack") | ||
| Note that in ``COMPREHENSIVE_THEME_DIRS`` it must contain a list of directories where the folders of the themes to be tested are located. | ||
| 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: | ||
|
|
||
| .. code-block:: json | ||
| { | ||
| "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: | ||
|
|
||
| .. code-block:: txt | ||
| 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: | ||
|
|
||
| .. code:: python | ||
| 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: | ||
|
|
||
| .. code-block:: json | ||
| "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. | ||
|
|
||
| .. _CONTRIBUTING: https://github.com/eduNEXT/eox-theming/blob/master/CONTRIBUTING.rst | ||
|
|
||
|
|
||
| License | ||
| ======= | ||
|
|
||
| This project is licensed under the AGPL-3.0 License. See the `LICENSE <LICENSE.txt>`_ file for details. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,4 +4,4 @@ | |
|
|
||
| from __future__ import unicode_literals | ||
|
|
||
| __version__ = '7.1.0' | ||
| __version__ = '7.2.0' | ||
Oops, something went wrong.