Manual:ResourceLoaderSkinModule
By MW 1.39 ResourceLoaderSkinModule.php was renamed to SkinModule.php. The documentation below is somewhat out of date.
ResourceLoaderSkinModule is a special kind of module that provides boilerplate styles to help you build a working skin. It can be used by registering a module in your skin's skin.json file like so:
"skins.myskin.styles": {
"class": "MediaWiki\\ResourceLoader\\SkinModule",
"features": {
"normalize": true,
"elements": true,
"content": true,
"interface": true,
"logo": true
},
"styles": [ "resources/skin.css" ]
},
MediaWiki version: | ≥ 1.36 |
Features
editFeature | Default value | Purpose | Required HTML | Notes |
---|---|---|---|---|
logo | false | Adds CSS to style an element with class `mw-wiki-logo` using the value of wgLogos['1x']. For new skins we recommend using img tag directly including the logo. | <div id="p-logo" role="banner">
<a class="mw-wiki-logo" href="/wiki/MediaWiki" title="Visit the main page"></a>
</div>
|
Will likely be deprecated in future. Using an img tag is recommended for skins going forward.
@since 1.35 |
normalize | true | Normalizes browser default styles to sensible defaults. | n/a | @since 1.35 |
elements | false | An opinionated set of styles to be used with or instead of `normalize`.
Only styles for single elements are included, no styling for complex structures like the TOC is present. This level is for skins that want to implement the entire style of even content area structures like the TOC themselves. May be redundant if using `normalize` depending on your skin. |
n/a | This can be considered as an opinionated version of `normalize`. @since 1.35 |
legacy | false | Historic feature, supported in MediaWiki 1.35-1.38. Has been split up into multiple features listed in this table. When enabled it will enable the `content-thumbnails`, `interface-category`, `content.tables` and i18n features (i18n-ordered-lists, i18n-all-lists-margins, i18n-headings.
|
n/a | Deprecated in 1.37 (T89981). Removed in 1.38 (T304325). @since 1.35 |
Content styles | ||||
content | false | Alias for "content-thumbnails". | n/a | Deprecated in 1.37. Don't use. @since 1.35 |
content-thumbnails | false | Styles for thumbnails and floated elements. Needed by skins that wish to support thumbnail arrangement in the page. | n/a | Deprecated in 1.37. Use content-media instead. @since 1.36 |
content-media | false | Styles for the new media structure on wikis where $wgUseNewMediaStructure is enabled. See https://www.mediawiki.org/wiki/Parsing/Media_structure. May be merged into content-thumbnails so should be considered unstable | n/a | Replaces content-thumbnails in 1.37, @since 1.36 |
content-links | false | The skin will apply optional styling rules for links that should be styled differently to the rules in `elements` and `normalize`. It provides support for .mw-selflink, a.new (red links), a.stub (stub links) and some basic styles for external links.
It also provides rules supporting the underline user preference. |
n/a | @since 1.36 |
content-links-external | false | The skin will apply optional styling rules to links to provide icons for different file types. | @since 1.37 | |
content-body | true | Styles associated with the parser. | n/a | Do not disable/enable unless you know what you are doing. Previously content-parser-output (@since 1.36) |
content-tables | false | Styles associated with tables created by wikitext. Replace if you are unhappy with the aesthetic look. | n/a | @since 1.36 |
Interface styles | ||||
interface | false | Provides basic styles for MediaWiki concepts such as indicators, menus (Allows gadget developers to hide them) to get started with a skin quicker. Includes the orange user message bar, edit links, and site notices. Advanced skin developers may wish to turn this off to provide their own styling rules.
Alias for interface-core, interface-indicators, interface-subtitle, interface-user-message, interface-site-notice and interface-edit-section-links. |
@since 1.35 | |
interface-category | false | Provides a styled gray box of categories. Can be disabled if skin does not support categories or wishes to style them differently. | @since 1.36 | |
interface-core | true | Required interface core styles. Disabling these is not recommended. | @since 1.39 | |
interface-edit-section-links | false | Default interface styling for edit section links. | @since 1.39 | |
interface-indicators | false | Default interface styling for indicators. | @since 1.39 | |
interface-message-box | false | Provides support for styling warning, error and success message boxes across all pages. Skins worried about performance may wish to limit where this feature is loaded by using an additional module. | @since 1.36 | |
interface-site-notice | false | Default interface styling for site notices. | @since 1.39 | |
interface-subtitle | false | Default interface styling for subtitle area. | @since 1.39 | |
interface-user-message | false | Default interface styling for html-user-message (you have new talk page messages box) | @since 1.39 | |
toc | true | Provides a styled gray box of categories. Can be disabled if skin disables or provides its own table of contents. | @since 1.36 | |
i18n support | ||||
i18n-ordered-lists | false | Styles for ordered lists elements that support mixed language content. | @since 1.35 | |
i18n-all-lists-margins | false | Styles for margins of list elements where LTR and RTL are mixed. | Will likely be renamed soon. See gerrit:680310 @since 1.35 | |
i18n-headings | false | Styles for line-heights of headings across different languages. | @since 1.35 |
For skins using deprecated modules
editThe mediawiki.skinning.interface, mediawiki.skinning.content, mediawiki.toc.styles, mediawiki.legacy.config, mediawiki.legacy.shared, mediawiki.legacy.commonPrint modules were removed in 1.39. Replacements are documented here.
mediawiki.skinning.interface
edit"skin.{name}.styles": {
"class": "MediaWiki\\ResourceLoader\\SkinModule",
"features": {
"content-links": true,
"content-media": true,
"interface-message-box": true,
"interface-category": true,
"content-tables": true,
"i18n-ordered-lists": true,
"i18n-all-lists-margins": true,
"i18n-headings": true,
"elements": true,
"interface": true,
"logo": true
},
..
}
For skins deprecating the legacy feature
editSkins using the `legacy` feature should instead enable the following features
Before:
"skins.legacy": {
"class": "MediaWiki\\ResourceLoader\\SkinModule",
"features": {
"legacy": true
},
..
}
After:
"skins.legacy": {
"class": "MediaWiki\\ResourceLoader\\SkinModule",
"features": {
"content-links": true,
"content-thumbnails": true,
"interface-message-box": true,
"interface-category": true,
"content-tables": true,
"i18n-ordered-lists": true,
"i18n-all-lists-margins": true,
"i18n-headings": true
},
..
}
When making this transition please report any bugs and heed the following advice...
Enabling the `normalize` and `elements` feature is recommended
editWithout this, you may notice some elements look a little off, particularly in print mode. However if your skin provides alternatives you can ignore.
visualClear
editSkins making use of `visualClear` should instead use the clear fix mixin (.mixin-clearfix()
). To aid migrating add the following style to your skin:
.visualClear {
clear: both;
}
Skins should define a red link color for links to non-existent pages.
editSkins using the legacy feature currently get red link color of ba0000
. Skins that use the content-links feature will get a color of d33
. In future skins will be able to define a LESS variable to override it.
For skins that do not import either, these links will appear as normal links.
Suggested:
a.new {
color: #ba0000;
}
Skins need to style their edit links if they are not including the `interface` feature.
editIf a skin does not include the `interface` feature, it may make sense for the skin to copy across the content of the deprecated styles inside resources/src/mediawiki.skinning/interface-edit-section-links.less. Skins are encouraged to be opinionated about how edit links display and to revise these as needed.
Skins using `error`, `warning` or `success` classes should provide their own styles
edit- Consider using `mw-messagebox`, `mw-warningbox` and `mw-successbox` instead and there associated Html::warningBox/Html::messageBox PHP classes.
Check your skin when printing
editplease check your print stylesheet, in particular for UI regressions relating to the footer.
- Only skins using the interface feature will hide elements with the `printfooter` class automatically.
- Skins using the #footer element with `interface` feature would previously get the footer displayed in a gray box. This is now the responsibility of the skin
@media (print) {
#footer {
background: #fff;
color: #000;
margin-top: 1em;
border-top: 1pt solid #aaa;
padding-top: 5px;
direction: ltr;
}
}
Note about directionality
editPreviously the `legacy` feature provided the following rules:
.mw-content-ltr {
/* @noflip */
direction: ltr;
}
.mw-content-rtl {
/* @noflip */
direction: rtl;
}
These rules are no longer necessary. All elements with these classes should have a `dir` HTML attribute to provide this rule.
Many wikis might use these classes without dir attributes, as discovered in T287701 so it may make sense for your skin to include them for now.
Ajax spinners
editThere will no longer be defaults for mw-ajax-loader and mw-small-spinner. Copy the styles if they are needed.
.mw-ajax-loader {
background-image: url( images/ajax-loader.gif );
background-position: center center;
background-repeat: no-repeat;
padding: 16px;
position: relative;
top: -16px;
}
.mw-small-spinner {
padding: 10px !important; /* stylelint-disable-line declaration-no-important */
margin-right: 0.6em;
background-image: url( images/spinner.gif );
background-position: center center;
background-repeat: no-repeat;
}