Jump to content

Manual:$wgResourceModuleSkinStyles

From mediawiki.org
ResourceLoader: $wgResourceModuleSkinStyles
Array of additional skin-provided stylesheets to existing ResourceLoader modules.
Introduced in version:1.24.0 (Gerrit change 141259; git #3971d064)
Removed in version:Still in use
Allowed values:(multi-dimensional array)
Default value:[]
This configuration option must not be used by extensions. They should use the skinStyles property of their own ResourceLoader modules to provide per-skin styles. This is for skins only to customize existing modules for themselves.

The $wgResourceModuleSkinStyles global enables skins to provide additional stylesheets to customize existing ResourceLoader modules. Skins can modify it by editing the ResourceModuleSkinStyles key in skin.json. Extensions can make their module styles customizable by skins by setting the skinStyles key on their ResourceLoader module definitions.

This both makes it easier (or at all possible) to override default styles and lowers the style footprint of a skin by not loading styles unused on most pages. For example, if a skin has a lot of CSS code to override the appearance of the Special:UserLogin page, then it can put this in a separate CSS or LESS file that overrides 'mediawiki.special.userlogin.login.styles' and ResourceLoader will only load that skin CSS when a page requires this module.

$wgResourceModuleSkinStyles is a multidimensional array. On the first level it contains the name of the package (skin/extension), which adds additional styles (in the following example called "foo"). On the second level it contains key-value-pairs:

  • The keys always are the module names, for which additional styles should be used. By default, your definition will then replace the CSS/LESS file, which has already defined styles for this module before. If the module name in contrast is prepended by a + sign, then your styles will be added to those styles, which had already been defined before, thus not replacing complete files, but preserving all styles and only overwriting/adding those, which you are defining.
  • The value is the relative path to the according file. Multiple files can be added to a module by writing them inside an array.

Vector is one of the skins using this method, and provides a good practical usage demonstration. The definition can be found under the key ResourceModuleSkinStyles.

See documentation for $wgResourceModules for basic information about defining and using ResourceLoader modules.

Documentation

The ResourceModuleSkinStyles key inside skin.json can be used to alter the styles of known ResourceLoader modules that have been defined in the ResourceModules key of other extensions.

The styles defined using $wgResourceModuleSkinStyles are later added to the skinStyles list of the existing module. The styles list can not be modified or disabled.

For example, if this is the definition of the ResourceLoader module bar:

$wgResourceModules['bar'] = [
  'scripts' => 'resources/bar/bar.js',
  'styles' => 'resources/bar/main.css',
];

then this is how skin Foo would provide additional styles for it:

$wgResourceModuleSkinStyles['foo'] = [
  'bar' => 'skins/Foo/bar.css',
];

This is mostly equivalent to:

$wgResourceModules['bar'] = [
  'scripts' => 'resources/bar/bar.js',
  'styles' => 'resources/bar/main.css',
  'skinStyles' => [
    'foo' => 'skins/Foo/bar.css',
  ],
];

If the module already defines its own entry in skinStyles for a given skin, then $wgResourceModuleSkinStyles is ignored.

If a module defines a skinStyles['default'] the skin may want to extend that instead of replacing them. This can be done using the + prefix.

Example:

$wgResourceModules['bar'] = [
  'scripts' => 'resources/bar/bar.js',
  'styles' => 'resources/bar/basic.css',
  'skinStyles' => [
    'default' => 'resources/bar/additional.css',
  ],
];
// Note the <code>+</code> character:
$wgResourceModuleSkinStyles['foo'] = [
  '+bar' => 'skins/Foo/bar.css',
];

This is mostly equivalent to:

$wgResourceModules['bar'] = [
  'scripts' => 'resources/bar/bar.js',
  'styles' => 'resources/bar/basic.css',
  'skinStyles' => [
    'default' => 'resources/bar/additional.css',
    'foo' => [
      'resources/bar/additional.css',
      'skins/Foo/bar.css',
    ],
  ],
];

In other words, as a module author, use the styles list for stylesheets that may not be disabled by a skin. To provide default styles that may be extended or replaced, use skinStyles['default'].

As with $wgResourceModules, paths default to being relative to the MediaWiki root. You should always provide a localBasePath and remoteBasePath (or remoteExtPath/remoteSkinPath).

Example:

$wgResourceModuleSkinStyles['foo'] = [
  'bar' => 'bar.css',
  'quux' => 'quux.css',
  'remoteSkinPath' => 'Foo',
  'localBasePath' => __DIR__,
];
MediaWiki version:
1.25
Gerrit change 161173

Clearing MediaWiki UI styles

Core MediaWiki adds the CSS of MediaWiki UI ResourceLoader modules as the default skinStyles, allowing skins to override their styling. For an extreme example, to eliminate most styling:

$wgResourceModuleSkinStyles['foo'] = [
        'mediawiki.ui' => [],
        'mediawiki.ui.checkbox' => [],
        'mediawiki.ui.radio' => [],
        'mediawiki.ui.anchor' => [],
        'mediawiki.ui.button' => [],
        'mediawiki.ui.input' => [],
        'mediawiki.ui.icon' => [],
        'mediawiki.ui.text' => [],
);

See also