Manual:ResourceLoaderSkinModule

From mediawiki.org
Jump to navigation Jump to search

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": "ResourceLoaderSkinModule",
        "features": {
                "normalize": true,
                "elements": true,
                "content": true,
                "legacy": false,
                "interface": true,
                "logo": true
        },
        "styles": [ "resources/skin.css" ]
},
MediaWiki version:
1.36

Features[edit]

Feature 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.
normalize true Normalizes browser default styles to sensible defaults. n/a
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`.
legacy false Historic feature, do not use where possible. 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.


The remaining styles in this module should be redundant. Skins migrating away from it may need to enable `mediawiki.pager.tablePager`, `mediawiki.action.styles`

n/a Will be deprecated in 1.37 (T89981)
Content styles
content false Alias for "content-thumbnails". n/a Deprecated. Don't use.
content-thumbnails false Styles for thumbnails and floated elements. Needed by skins that wish to support thumbnail arrangement in the page. n/a Will soon be replaced with `content-media` in https://gerrit.wikimedia.org/r/690769
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 Do not use, unless you know what you are doing.
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
content-links-external false The skin will apply optional styling rules to links to provide icons for different file types.
content-body true Styles associated with the parser. n/a Do not disable/enable unless you know what you are doing.
content-tables false Styles associated with tables created by wikitext. Replace if you are unhappy with the aesthetic look. n/a
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.
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.
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.
toc true Provides a styled gray box of categories. Can be disabled if skin disables or provides its own table of contents.
i18n support
i18n-ordered-lists false Styles for ordered lists elements that support mixed language content.
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
i18n-headings false Styles for line-heights of headings across different languages.

For skins deprecating the legacy feature[edit]

Skins using the `legacy` feature should instead enable the following features

Before:

"skins.legacy": {
    "class": "ResourceLoaderSkinModule",
    "features": {
        "legacy": true
    },
    ..
}

After:

"skins.legacy": {
    "class": "ResourceLoaderSkinModule",
    "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[edit]

Without this, you may notice some elements look a little off, particularly in print mode. However if your skin provides alternatives you can ignore.

visualClear[edit]

Skins 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.[edit]

Skins 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.[edit]

If 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[edit]

please 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[edit]

Previously 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[edit]

There 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;
}