mediawiki / scss
Allows using SCSS files for MediaWiki styling
Fund package maintenance!
JeroenDeDauw
Installs: 45 512
Dependents: 1
Suggesters: 0
Security: 0
Stars: 4
Watchers: 5
Forks: 2
Open Issues: 0
Requires
- php: >=8.0
- scssphp/scssphp: ^1.12.1
Requires (Dev)
- mediawiki/mediawiki-codesniffer: ^v41.0.0
- phpstan/phpstan: ^1.10.15
- phpunit/phpunit: ^9.6.8
- slevomat/coding-standard: ^v8.11.1
- vimeo/psalm: ^5.12.0
README
The MediaWiki SCSS library provides a ResourceLoader module capable of compiling SCSS.
Requirements
Use
An SCSS module is defined much like any other style module. See the manual for
$wgResourceModules.
It should also be possible to add the module definition to the extension.json
of a MediaWiki extension. See
Developing_with_ResourceLoader
Some additional keys may be used:
-
class
: This is mandatory. It selects the class to be used for the module. For SCSS, the value has to be'SCSS\\ResourceLoaderSCSSModule'
-
styles
: It is not an additional key, but it has extended semantics. This key contains the list of the module's style files. Each file can optionally be given a position to influence the order in which the files are compiled. Allowed values for the position arebeforeFunctions
functions
afterFunctions
beforeVariables
variables
afterVariables
beforeMain
main
afterMain
If no position is given,
main
will be assumed.All files of one module will be compiled together, i.e., variables, mixins etc., will be shared between them.
-
variables
: An array of variables and values to override the SCSS variables in the style files. This allows changing values (e.g., colors, fonts, margins) without having to modify the actual style files. -
cacheTriggers
: Compiling SCSS is expensive, so compiled results are cached. This option lists files that, when changed, will trigger flushing of the cache and re-compiling of the style files.All files on this list will be checked for each web request. To minimizes the load on the file system and the time to build the page, it is not advisable to add all style files to this list.
Here is an example definition:
$wgResourceModules[ 'ext.MyExtension.styles' ] = [ 'class' => 'SCSS\\ResourceLoaderSCSSModule', 'localBasePath' => $localBasePath, 'remoteBasePath' => $remoteBasePath, 'position' => 'top', 'styles' => [ 'modules/ext.MyExtension.foo.scss' => 'main', 'modules/ext.MyExtension.bar.scss' ], 'variables' => [ 'red' => '#ff0000', 'green' => '#00ff00', 'blue' => '#0000ff', ], 'cacheTriggers' => [ 'LocalSettings.php', 'composer.lock', ], ];
The extension uses the scssphp/scssphp compiler, which has some limitations. See the issue list.
Cache type
$egScssCacheType
can be set to request a specific cache type for the compiled
styles. To disable caching of SCSS styles altogether (e.g., during development),
set $egScssCacheType = CACHE_NONE;
. This should never be done on a production
site.
Professional Support
The SCSS extension is maintained by Professional Wiki. You can contract us to help you install or customize SCSS. We also do development work.
Running the tests
The tests can only be run when the library is loaded within MediaWiki.
You can add it via composer.local.json
(probably using dev-master
).
Inside your MediaWiki root directory
php tests/phpunit/phpunit.php -c vendor/mediawiki/scss/phpunit.xml.dist
License
You can use the SCSS extension under the GNU General Public License, version 3 (or any later version).
Release notes
Version 4.0.0
Released on 2024-04-25
- Raised minimum MediaWiki version from 1.35 to 1.39
- Raised minimum PHP version from 7.4.3 to 8.0
- Raised minimum
scssphp
version from 1.10.2 to 1.12.1 - Modernized coding standards
Version 3.0.1
Released on 2022-07-25
- Added preliminary compatibility with MediaWiki 1.39
Version 3.0.0
Released on 2022-03-30
- Raised minimum MediaWiki version from 1.27 to 1.35
- Raised minimum PHP version from 5.6 to 7.4.3
- Raised minimum
scssphp
version from 1.5.2 to 1.10.2
Version 2.0.8
Released on 2022-07-25
- Added preliminary compatibility with MediaWiki 1.39
Version 2.0.7
Released on 2021-05-18
- Increased minimum version of
scssphp
Version 2.0.6
Released on 2021-05-15
- Temporarily limit the version of
scssphp
below 1.5 to avoid breaking changes
Version 2.0.5
Released on 2020-12-27
- Added compatibility with MediaWiki 1.36
Version 2.0.4
Released on 2020-09-07
- Switched to new version of
scssphp
Version 2.0.3
Released on 2020-09-07
- Temporarily fixed the version of
scssphp
to 1.1.1 to avoid the 1.2 bug
Version 2.0
Released on 2020-04-19
- Turned MediaWiki extension into a standard PHP/Composer library
- Switched to new version of
scssphp
Version 1.0
Released on 2019-04-28
- Initial release