Name | eox-theming JSON |
Version |
9.0.0
JSON |
| download |
home_page | None |
Summary | Open edX Theming Plugin |
upload_time | 2025-02-11 23:08:37 |
maintainer | None |
docs_url | None |
author | eduNEXT |
requires_python | None |
license | AGPL |
keywords |
|
VCS |
|
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
===========
EOX Theming
===========
|Maintainance Badge| |Test Badge| |PyPI Badge| |Python Badge|
.. |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
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.
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 |
+------------------+---------------+
⚠️ 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 (Sumac). 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:: 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.
🚨 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 <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>`_).
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
.. 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>`_
Installation
============
#. Install the plugin adding it to ``OPENEDX_EXTRA_PIP_REQUIREMENTS`` in the ``config.yml``.
.. code-block:: yaml
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 <https://github.com/eduNEXT/tutor-contrib-edunext-distro/blob/master/README.md#themes>`_. 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:
.. code-block:: bash
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``:
.. 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")
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "eox-theming",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "eduNEXT",
"author_email": "contact@edunext.co",
"download_url": "https://files.pythonhosted.org/packages/db/da/ae4c25c7ec41b2a6346de012ed25c88413ea40e3c33887e98a5cc58e200a/eox_theming-9.0.0.tar.gz",
"platform": null,
"description": "===========\nEOX Theming\n===========\n|Maintainance Badge| |Test Badge| |PyPI Badge| |Python Badge|\n\n.. |Maintainance Badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen\n :alt: Maintainance Status\n.. |Test Badge| image:: https://img.shields.io/github/actions/workflow/status/edunext/eox-theming/.github%2Fworkflows%2Ftests.yml?label=Test\n :alt: GitHub Actions Workflow Test Status\n.. |PyPI Badge| image:: https://img.shields.io/pypi/v/eox-theming?label=PyPI\n :alt: PyPI - Version\n.. |Python Badge| image:: https://img.shields.io/pypi/pyversions/eox-theming.svg\n\nOverview\n========\n\nEox 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.\n\nThis 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.\n\nThe 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.\n\nCompatibility Notes\n===================\n\n+------------------+---------------+\n| Open edX Release | Version |\n+==================+===============+\n| Juniper | >= 1.0 < 2.0 |\n+------------------+---------------+\n| Koa | >= 2.0 < 3.0 |\n+------------------+---------------+\n| Lilac | >= 2.0 < 8.0 |\n+------------------+---------------+\n| Maple | >= 3.0 < 8.0 |\n+------------------+---------------+\n| Nutmeg | >= 4.0 < 8.0 |\n+------------------+---------------+\n| Olive | >= 5.0 < 8.0 |\n+------------------+---------------+\n| Palm | >= 6.0 < 8.0 |\n+------------------+---------------+\n| Quince | >= 7.0 < 9.0 |\n+------------------+---------------+\n| Redwood | >= 7.2.0 |\n+------------------+---------------+\n| Sumac | >= 8.1.0 |\n+------------------+---------------+\n\n\u26a0\ufe0f From Lilac version Django 2.2 is not supported, you should use Django 3.2 and eox-tenant >=4.0.\n\nThe plugin is configured for the latest release (Sumac). 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``.\n\nFor 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:\n\n.. code-block:: python\n\n EOX_THEMING_STORAGE_BACKEND = 'eox_theming.edxapp_wrapper.backends.l_storage'\n EOX_THEMING_EDXMAKO_BACKEND = 'eox_theming.edxapp_wrapper.backends.l_mako'\n\nThen you need to change the configuration in ``eox_theming/settings/common.py`` to use the appropriated ones.\n\n\ud83d\udea8 If the release you are looking for is not listed, please note:\n\n- 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.\n- 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>`_).\n\nPre-requirements\n================\n#. 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>`_\n#. Ensure your environment is well-configured according to the `Settings`_ section\n\n .. note::\n 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>`_\n\nInstallation\n============\n\n#. Install the plugin adding it to ``OPENEDX_EXTRA_PIP_REQUIREMENTS`` in the ``config.yml``.\n\n .. code-block:: yaml\n\n OPENEDX_EXTRA_PIP_REQUIREMENTS:\n - eox-theming=={{version}}\n\n#. Save the configuration with ``tutor config save``\n#. Launch the platform with ``tutor local launch``\n\nSettings\n========\n\nIf 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:\n\n#. Add the themes to your instance by adding your themes folder to the container shared folder ``env/build/openedx/themes``\n\n#. Compile the themes after adding them:\n\n .. code-block:: bash\n\n tutor images build openedx\n tutor local do init\n\n # or\n\n tutor local launch\n\n#. Add the following settings to your environment file ``env/apps/openedx/settings/lms/production.py``:\n\n .. code:: python\n\n COMPREHENSIVE_THEME_DIRS.extend(\n [\n \"/path-to-your-themes-folder/in-the-lms-container/edx-platform\",\n \"/path-to-your-themes-folder/in-the-lms-container/edx-platform/sub-folder-with-more-themes\",\n ]\n )\n EOX_THEMING_DEFAULT_THEME_NAME = \"my-theme-1\" # Or the theme you want\n\n ################## EOX_THEMING ##################\n if \"EOX_THEMING_DEFAULT_THEME_NAME\" in locals() and EOX_THEMING_DEFAULT_THEME_NAME:\n from lms.envs.common import _make_mako_template_dirs # pylint: disable=import-error\n ENABLE_COMPREHENSIVE_THEMING = True\n TEMPLATES[1][\"DIRS\"] = _make_mako_template_dirs\n derive_settings(\"lms.envs.production\")\n\nUsage\n=====\n\n#. 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:\n\n .. code-block:: json\n\n {\n \"EDNX_USE_SIGNAL\": true,\n \"THEME_OPTIONS\": {\n \"theme\": {\n \"name\":\"my-theme-1\",\n \"parent\":\"my-theme-2\",\n \"grandparent\":\"my-theme-3\"\n }\n }\n }\n\n#. 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.\n\nUse case example\n================\n\nHaving the following theme folder structure:\n\n.. code-block:: txt\n\n themes-main-folder\n \u251c\u2500\u2500 edx-platform\n \u2514\u2500\u2500 global-customizations\n \u2514\u2500\u2500 lms\n \u2514\u2500\u2500 static\n \u2514\u2500\u2500 templates\n \u2514\u2500\u2500 cms\n \u2514\u2500\u2500 static\n \u2514\u2500\u2500 templates\n \u2514\u2500\u2500 more-specific-customizations\n \u2514\u2500\u2500 org-customization-theme\n \u2514\u2500\u2500 lms\n \u2514\u2500\u2500 static\n \u2514\u2500\u2500 templates\n \u2514\u2500\u2500 cms\n \u2514\u2500\u2500 static\n \u2514\u2500\u2500 templates\n \u2514\u2500\u2500 much-more-specific-customizations\n \u2514\u2500\u2500 client-customization-theme\n \u2514\u2500\u2500 lms\n \u2514\u2500\u2500 static\n \u2514\u2500\u2500 templates\n \u2514\u2500\u2500 cms\n \u2514\u2500\u2500 static\n \u2514\u2500\u2500 templates\n\n**NOTE**\n\nYou 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.\n\n#. 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.\n\n#. Compile the themes running `tutor local launch`\n\n#. Then, ensure are properly configured the `Settings`_ required and customize these: \n\n .. code:: python\n\n COMPREHENSIVE_THEME_DIRS.extend(\n [\n \"/openedx/themes/themes-main-folder/edx-platform\",\n \"/openedx/themes/themes-main-folder/edx-platform/more-specific-customizations\",\n \"/openedx/themes/themes-main-folder/edx-platform/most-specific-customizations\"\n ]\n )\n EOX_THEMING_DEFAULT_THEME_NAME = \"client-customization-theme\"\n\n#. And finally, restart the platform with the ``tutor local restart`` so this settings are properly added\n\n#. 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:\n\n .. code-block:: json\n\n \"theme\": {\n \"name\":\"client-customization-theme\",\n \"parent\":\"org-customization-theme\",\n \"grandparent\":\"global-customizations\"\n }\n\n#. Restart again with ``tutor local restart`` and enjoy :)\n\nContributing\n============\n\nContributions are welcome! See our `CONTRIBUTING`_\nfile for more information - it also contains guidelines for how to maintain high code\nquality, which will make your contribution more likely to be accepted.\n\n.. _CONTRIBUTING: https://github.com/eduNEXT/eox-theming/blob/master/CONTRIBUTING.rst\n\n\nLicense\n=======\n\nThis project is licensed under the AGPL-3.0 License. See the `LICENSE <LICENSE.txt>`_ file for details.\n",
"bugtrack_url": null,
"license": "AGPL",
"summary": "Open edX Theming Plugin",
"version": "9.0.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d0b66e1f5041d62dc2753f5571dda6b2f3979e068c172568ad38f396b21518bf",
"md5": "1ea88702c26871d6c20178fee175b88a",
"sha256": "c5f494eae0a862ae72fb430257c7c530dd77a8665398214953fb9c68068a0d4d"
},
"downloads": -1,
"filename": "eox_theming-9.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1ea88702c26871d6c20178fee175b88a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 55194,
"upload_time": "2025-02-11T23:08:35",
"upload_time_iso_8601": "2025-02-11T23:08:35.441747Z",
"url": "https://files.pythonhosted.org/packages/d0/b6/6e1f5041d62dc2753f5571dda6b2f3979e068c172568ad38f396b21518bf/eox_theming-9.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dbdaae4c25c7ec41b2a6346de012ed25c88413ea40e3c33887e98a5cc58e200a",
"md5": "256fe49c2e513bbcce59970eaac905db",
"sha256": "b9af35366639391961d6cac0171cff242cc8669dde042e19b0cf2ea3311d556f"
},
"downloads": -1,
"filename": "eox_theming-9.0.0.tar.gz",
"has_sig": false,
"md5_digest": "256fe49c2e513bbcce59970eaac905db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 45908,
"upload_time": "2025-02-11T23:08:37",
"upload_time_iso_8601": "2025-02-11T23:08:37.505705Z",
"url": "https://files.pythonhosted.org/packages/db/da/ae4c25c7ec41b2a6346de012ed25c88413ea40e3c33887e98a5cc58e200a/eox_theming-9.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-11 23:08:37",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "eox-theming"
}