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
69 lines
2.4 KiB
Python
69 lines
2.4 KiB
Python
"""
|
|
Tests for methods defined in builtin_assets.py
|
|
"""
|
|
from unittest import TestCase
|
|
from unittest.mock import patch
|
|
|
|
from django.core.exceptions import ImproperlyConfigured
|
|
from web_fragments.fragment import Fragment, FragmentResource
|
|
|
|
from xmodule.util import builtin_assets
|
|
|
|
|
|
class AddSassToFragmentTests(TestCase):
|
|
"""
|
|
Tests for add_sass_to_fragment.
|
|
|
|
We would have liked to also test two additional cases:
|
|
* When a theme is enabled, and add_sass_to_fragment is called with a
|
|
theme-overriden Sass file, then a URL to themed CSS is added.
|
|
* When a theme is enabled, but add_sass_to_fragment is called with a Sass
|
|
file that the theme doesn't override, then a URL to the original (unthemed)
|
|
CSS is added.
|
|
Unfortunately, under edx-platform tests, settings.STATICFILES_STORAGE does not
|
|
include the ThemeStorage class, so themed URL generation doesn't work.
|
|
"""
|
|
|
|
def test_absolute_path_raises_value_error(self):
|
|
fragment = Fragment()
|
|
with self.assertRaises(ValueError):
|
|
builtin_assets.add_sass_to_fragment(
|
|
fragment,
|
|
"/openedx/edx-platform/xmodule/assets/ProblemBlockDisplay.scss",
|
|
)
|
|
|
|
def test_not_scss_raises_value_error(self):
|
|
fragment = Fragment()
|
|
with self.assertRaises(ValueError):
|
|
builtin_assets.add_sass_to_fragment(
|
|
fragment,
|
|
"vertical/public/js/vertical_student_view.js"
|
|
)
|
|
|
|
def test_misspelled_path_raises_not_found(self):
|
|
fragment = Fragment()
|
|
with self.assertRaises(FileNotFoundError):
|
|
builtin_assets.add_sass_to_fragment(
|
|
fragment,
|
|
"ProblemBlockDisplayyyy.scss",
|
|
)
|
|
|
|
def test_static_file_missing_raises_improperly_configured(self):
|
|
fragment = Fragment()
|
|
with patch.object(builtin_assets, 'get_static_file_url', lambda _path: None):
|
|
with self.assertRaises(ImproperlyConfigured):
|
|
builtin_assets.add_sass_to_fragment(
|
|
fragment,
|
|
"ProblemBlockDisplay.scss",
|
|
)
|
|
|
|
def test_happy_path(self):
|
|
fragment = Fragment()
|
|
builtin_assets.add_sass_to_fragment(fragment, "ProblemBlockDisplay.scss")
|
|
assert fragment.resources[0] == FragmentResource(
|
|
kind='url',
|
|
data='/static/css/ProblemBlockDisplay.css',
|
|
mimetype='text/css',
|
|
placement='head',
|
|
)
|