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
55 lines
2.4 KiB
Python
55 lines
2.4 KiB
Python
"""
|
|
Utilities for adding edx-platform assets to built-in XBlocks.
|
|
|
|
These should not be used to support any XBlocks outside of edx-platform.
|
|
"""
|
|
from pathlib import Path
|
|
|
|
import webpack_loader
|
|
from django.conf import settings
|
|
from django.core.exceptions import ImproperlyConfigured
|
|
|
|
from openedx.core.djangoapps.theming.helpers_static import get_static_file_url
|
|
|
|
|
|
def add_sass_to_fragment(fragment, sass_relative_path):
|
|
"""
|
|
Given a Sass path relative to xmodule/assets, add a compiled CSS URL to the fragment.
|
|
|
|
Raises:
|
|
* ValueError if {sass_relative_path} is absolute or does not end in '.scss'.
|
|
* FileNotFoundError if edx-platform/xmodule/assets/{sass_relative_path} is missing.
|
|
* ImproperlyConfigured if the lookup of the static CSS URL fails. This could happen
|
|
if Sass wasn't compiled, CSS wasn't collected, or the staticfiles app is misconfigured.
|
|
|
|
Notes:
|
|
* This function is theme-aware. That is: If a theme is enabled which provides a compiled
|
|
CSS file of the same name, then that CSS file will be used instead.
|
|
"""
|
|
if not isinstance(sass_relative_path, Path):
|
|
sass_relative_path = Path(sass_relative_path)
|
|
if sass_relative_path.is_absolute():
|
|
raise ValueError(f"sass_relative_path should be relative; is absolute: {sass_relative_path}")
|
|
if sass_relative_path.suffix != '.scss':
|
|
raise ValueError(f"sass_relative_path should be .scss file; is: {sass_relative_path}")
|
|
sass_absolute_path = Path(settings.REPO_ROOT) / "xmodule" / "assets" / sass_relative_path
|
|
if not sass_absolute_path.is_file():
|
|
raise FileNotFoundError(f"Sass not found: {sass_absolute_path}")
|
|
css_static_path = Path('css') / sass_relative_path.with_suffix('.css')
|
|
css_url = get_static_file_url(str(css_static_path)) # get_static_file_url is theme-aware.
|
|
if not css_url:
|
|
raise ImproperlyConfigured(
|
|
f"Did not find CSS file {css_static_path} (compiled from {sass_absolute_path}) "
|
|
f"in staticfiles storage. Perhaps it wasn't collected?"
|
|
)
|
|
fragment.add_css_url(css_url)
|
|
|
|
|
|
def add_webpack_js_to_fragment(fragment, bundle_name):
|
|
"""
|
|
Add all JS webpack chunks to the supplied fragment.
|
|
"""
|
|
for chunk in webpack_loader.utils.get_files(bundle_name, None, 'DEFAULT'):
|
|
if chunk['name'].endswith(('.js', '.js.gz')):
|
|
fragment.add_javascript_url(chunk['url'])
|