127c5c1ce2
In ~Palm and earlier, all built-in XBlock Sass was included into LMS and CMS
styles before being compiled. The generated CSS was coupled together with
broader LMS/CMS CSS. This means that comprehensive themes have been able to
modify built-in XBlock appearance by setting certain Sass variables. We say that
built-in XBlock Sass was, and is expected to be, "theme-aware".
Shortly after Palm, we decoupled XBlock Sass from LMS and CMS Sass [1]. Each
built-in block's Sass is now compiled into two separate CSS targets, one for
block editing and one for block display. The CSS, now located at
`common/static/css/xmodule`, is injected into the running Webpack context with
the new `XModuleWebpackLoader`. Built-in XBlocks already used
`add_webpack_to_fragment` in order to add JS Webpack bundles to their view
fragments, so when CSS was added to Webpack, it Just Worked.
This unlocked a slieu of simplifications for static asset processing [2];
however, it accidentally made XBlock Sass theme-*unaware*, or perhaps
theme-confused, since the CSS was targeted at `common/static/css/xmodule`
regardless of the theme. The result of this is that **built-in XBlock views will
use CSS based on the Sass variables _last theme to be compiled._** Sass
variables are only used in a handful of places in XBlocks, so the bug is subtle,
but it is there for those running off of master. For example, using edX.org's
theme on master, we can see that there is a default blue underline in the Studio
sequence nav [3]. With this bugfix, it becomes the standard edX.org
greenish-black [4].
This commit makes several changes, firstly to fix the bug, and secondly to leave
ourselves with a more comprehensible asset setup in the `xmodule/` directory.
* We remove the `XModuleWebpackLoader`, thus taking built-in XBlock Sass back
out of Webpack.
* We compile XBlock Sass not to `common/static/css/xmodule`, but to:
* `[lms|cms]/static/css` for the default theme, and
* `<THEME_ROOT>/[lms|cms]/static/css`, for any custom theme.
This is where the comprehensive theming system expects to find themable
assets. Unfortunately, this does mean that the Sass is compiled twice, both
for LMS and CMS. We would have liked to compile it once to somewhere in the
`common/`, but comprehensive theming does not consider `common/` assets to be
themable.
* We split `add_webpack_to_fragment` into two more specialized functions:
* `add_webpack_js_to_fragment` , for adding *just* JS from a Webpack bundle,
and
* `add_sass_to_fragment`, for adding static links to CSS compiled themable
Sass (not Webpack). Both these functions are moved to a new module
`xmodule/util/builtin_assets.py`, since the original module
(`xmodule/util/xmodule_django.py`) didn't make a ton of sense.
* In an orthogonal bugfix, we merge Sass `CourseInfoBlock`, `StaticTabBlock`,
`AboutBlock` into the `HtmlBlock` Sass files. The first three were never used,
as their styling was handled by `HtmlBlock` (their shared parent class).
* As a refactoring, we change Webpack bundle names and Sass module names to be
less misleading:
* student_view, public_view, and author_view: was `<Name>BlockPreview`, is now
`<Name>BlockDisplay`.
* studio_view: was `<Name>BlockStudio`, is now `<Name>BlockEditor`.
* As a refactoring, we move the contents of `xmodule/static` into the existing
`xmodule/assets` directory, and adopt its simper structure. We now have:
* `xmodule/assets/*.scss`: Top-level compiled Sass modules. These could be
collapsed away in a future refactoring.
* `xmodule/assets/<blocktype>/*`: Resources for each block, including both JS
modules and Sass includes (underscore-prefixed so that they aren't
compiled). This structure maps closely with what externally-defined XBlocks
do.
* `xmodule/js` still exists, but it will soon be folded into the
`xmodule/assets`.
* We add a new README [4] to explain the new structure, and also update a
docstring in `openedx/lib/xblock/utils` which had fallen out of date with
reality.
* Side note: We avoid the term "XModule" in all of this, because that's
(thankfully) become a much less useful/accurate way to describe these blocks.
Instead, we say "built-in XBlocks".
Refs:
1. https://github.com/openedx/edx-platform/pull/32018
2. https://github.com/openedx/edx-platform/issues/32292
3. https://github.com/openedx/edx-platform/assets/3628148/8b44545d-0f71-4357-9385-69d6e1cca86f
4. https://github.com/openedx/edx-platform/assets/3628148/d0b7b309-b8a4-4697-920a-8a520e903e06
5. https://github.com/openedx/edx-platform/tree/master/xmodule/assets#readme
Part of: https://github.com/openedx/edx-platform/issues/32292
57 lines
3.7 KiB
ReStructuredText
57 lines
3.7 KiB
ReStructuredText
xmodule
|
|
#######
|
|
|
|
The ``xmodule`` folder contains a variety of old-yet-important functionality core to both LMS and CMS, most notably:
|
|
|
|
* the ModuleStore, edx-platform's "Version 1" learning content storage backend;
|
|
* an XBlock Runtime implementation for ModuleStore-backed content;
|
|
* the "partitions" framework for differentiated XBlock content;
|
|
* implementations for the "stuctural" XBlocks: ``course``, ``chapter``, and ``sequential``;
|
|
* the implementations of several different built-in content-level XBlocks, such as ``problem`` and ``html``; and
|
|
* `assets for those built-in XBlocks`_.
|
|
|
|
.. _assets for those built-in XBlocks: https://github.com/openedx/edx-platform/tree/master/assets
|
|
|
|
Historical Context
|
|
******************
|
|
|
|
"XModule" was the original content framework for edx-platform, which gives the folder its current name.
|
|
XModules rendered specific course run content types to users for both authoring and learning.
|
|
For instance, there was an XModule for Videos, another for HTML snippets, and another for Sequences.
|
|
|
|
XModule was succeeded in ~2013 by the "XBlock" framework, which served the same purpose, but put additional focus into flexibility and modularity.
|
|
XBlock allows new content types to be created by anyone, completely external the edx-platform repository.
|
|
It remains the platform's flagship content plugin framework to this day.
|
|
|
|
For years, edx-platform supported both content frameworks simultaneously via a Frankenstein-ish hybrid XBlock+XModule runtime implementation in this directory.
|
|
Fortunately, in 2021, `all remaining XModules were converted into XBlocks`_.
|
|
Since support for the XModule framework is no longer necessary, `the BD-13 project`_ is now working to radically simplify the remaining XBlock runtime implementation.
|
|
|
|
This folder was moved from ./common/lib/xmodule/xmodule to its current location, ./xmodule. The reasons that this folder (along with several others) were moved are detailed in `this ADR about the dissolution of sub-projects`_.
|
|
|
|
.. _all remaining XModules were converted into XBlocks: https://discuss.openedx.org/t/xmodule-xblock-conversion-complete/4555
|
|
.. _the BD-13 project: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3062333478/BD-13+xModule+--+xBlock+Conversion+Phase+2
|
|
.. _this ADR about the dissolution of sub-projects: https://github.com/openedx/edx-platform/blob/master/docs/decisions/0015-sub-project-dissolution.rst
|
|
|
|
Direction
|
|
*********
|
|
|
|
**Maintain, Simplify, Extract & Replace.**
|
|
|
|
Currently, this directory contains a lot of mission-critical functionality, so continued maintenance and simplification of it is important.
|
|
Still, we aim to eventually dissolve the directory in favor of more focused & decoupled subsystems:
|
|
|
|
* ModuleStore is superseded by the `Blockstore`_ storage backend.
|
|
* Blockstore-backend content is rendered by a new, simplified `edx-platform XBlock runtime`_.
|
|
* Navigation, partitioning, and composition of learning content is being re-architected in the `openedx-learning`_ library.
|
|
* All new XBlocks are implemented in separate repositories, such as `xblock-drag-and-drop-v2`_.
|
|
|
|
To help with this direction, please **do not add new functionality to this directory**. If you feel that you need to add code to this directory, reach out on `the forums`_; it's likely that someone can help you find a different way to implement your change that will be more robust and architecturally sound!
|
|
|
|
.. _Blockstore: https://github.com/openedx/blockstore/
|
|
.. _edx-platform XBlock runtime: https://github.com/openedx/edx-platform/tree/master/openedx/core/djangoapps/xblock
|
|
.. _openedx-learning: https://github.com/openedx/openedx-learning
|
|
.. _xblock-drag-and-drop-v2: https://github.com/openedx/xblock-drag-and-drop-v2
|
|
.. _the forums: https://discuss.openedx.org
|
|
|