2021pedia:TemplateStyles

<languages/> Template:ExtensionTypes

<translate> Extensions let you customize how MediaWiki looks and works. </translate>

• <translate> Wiki users can [[<tvar name=cat>Special:MyLanguage/Category:Extensions by category</tvar>|browse through extensions]].</translate>
• <translate> System administrators can [[<tvar name=1>#Installing an extension</tvar>|install]] (or remove) extensions on the MediaWiki installations that they manage.</translate>
• <translate> Developers can [[<tvar name=man>Special:MyLanguage/Manual:Developing extensions</tvar>|write new extensions]] or [[<tvar name=cat>Special:MyLanguage/Category:Unmaintained extensions</tvar>|improve or maintain extensions]]. </translate>

<translate> While some extensions are maintained by MediaWiki developers, others were written by third-party developers.</translate> <translate> As a result, many have bugs, and they are not all guaranteed to be compatible with each other.</translate> <translate> Some are unmaintained; not all extensions work on all versions of MediaWiki.</translate> <translate> Use any extension, especially those tagged as insecure, at your own risk.</translate> <translate> If you are using an extension that requires patches to the core software, be sure to backup your database.</translate> <translate> This helps avoid the risk of breaking your wiki.</translate>

<translate>

Types of extensions

</translate>

Template:InfoCard Template:InfoCard

<translate>

Browsing extensions

</translate> <translate> You can browse <tvar name=cat></tvar> to see the full range of extensions that have already been written.</translate> <translate> For information on installing these extensions or writing your own, see below.</translate>

<translate>

Checking installed extensions

</translate> <translate> Only someone with administration access to the filesystem (and often the database too) on a server can install extensions for MediaWiki, but anyone can check which extensions are active on an instance of MediaWiki by accessing the <tvar name=special>Special:Version</tvar> page.</translate> <translate> For example, these extensions are active in the English Wikipedia.</translate>

<translate>

Installing an extension

</translate> <translate> MediaWiki is ready to accept extensions just after [[<tvar name=man>Special:MyLanguage/Manual:Installation</tvar>|installation]] is finished.</translate> <translate> To add an extension follow these steps:</translate>

1. <translate> Before you start</translate>

   <translate> Many extensions provide instructions designed for installation using unix commands.</translate> <translate> You require shell access (SSH) to enter these commands listed on the extension help pages.</translate>

2. <translate> Download your extension.</translate>

   <translate> [[<tvar name=special>Special:ExtensionDistributor</tvar>|Extension Distributor]] helps you to select and download most of the popular extensions.</translate>

   <translate> Extensions are usually distributed as modular packages.</translate> <translate> They generally go in their own subdirectory of <tvar name=IP>/extensions/</tvar>.</translate> <translate> A list of extensions stored in the Wikimedia [[<tvar name=gerrit>Special:MyLanguage/Gerrit</tvar>|Git repository]] is located at <tvar name=extensions>git:mediawiki/extensions</tvar>.</translate> <translate> Some extensions [[<tvar name=cat>Special:MyLanguage/Category:Extensions which host their code in-wiki</tvar>|don't use version control]] and are not recommended.</translate>

   <translate> Some extensions are also available in [[<tvar name=1>Special:MyLanguage/Software bundles</tvar>|bundles]], <tvar name=composer></tvar> or [[<tvar name=2>Special:MyLanguage/Comparison of extensions in distributions</tvar>|package repositories]].</translate>

3. <translate> Install your extension.</translate>.

   <translate> At the end of the <tvar name=LocalSettings></tvar> file, add:</translate>

   wfLoadExtension( 'ExtensionName' );
   

   <translate> This line forces the PHP interpreter to read the extension file, and thereby make it accessible to MediaWiki.</translate>

   <translate> Some extensions can conflict with maintenance scripts, for example if they directly access $_SERVER (not recommended).</translate>

   <translate> In this case they can be wrapped in the conditional so maintenance scripts can still run.</translate>

if ( !$wgCommandLineMode ) {
   wfLoadExtension ( 'ExtensionName' );
}

<translate> : The maintenance script <tvar name=ImportDump></tvar> will fail for any extension which requires customized namespaces which is included inside the conditional above such as <tvar name=1></tvar>, <tvar name=2></tvar>.</translate>

<span class="citation wikicite" id="endnote_<translate> Ensure that required permissions are set for extensions!</translate>">^

<span class="citation wikicite" id="endnote_<translate> While this installation procedure is sufficient for most extensions, some require a different installation procedure.</translate> <translate> Check your extension's documentation for details.</translate>">^

<span class="citation wikicite" id="endnote_<translate> If you want to alter configuration variables in LocalSettings.php, you have to do this typically after including the extension.</translate> <translate> Otherwise defaults defined in the extension will overwrite your settings.</translate>">^

<translate>

Upgrading an extension

</translate> <translate> Some extensions require to be updated whenever you update MediaWiki, while others work with multiple versions.</translate> <translate> To upgrade to a new version of an extension:</translate>

<translate>

1. Download the new version of the extension</translate>

<translate>

1. Replace all the extension files in the extension/ExtensionName directory with the new files.</translate> <translate> Do not remove the extension configuration present in LocalSettings.php</translate>

<translate>

1. If the extension requires changes to the MediaWiki database, you will need to run the Update.php maintenance script.</translate> <translate> Most extensions will mention if this script needs to be run or not.</translate> <translate> (Perform backup of your data before executing the script).</translate> <translate> If you don't have command line access, you can also use the [[<tvar name=man>Special:MyLanguage/Manual:Upgrading#Web_updater</tvar>|web updater]].</translate>

<span class="citation wikicite" id="endnote_<translate> These instructions cover 99% of extensions.</translate> <translate> If the specific extension you are upgrading has instructions that differ from these, you should probably follow the specific extension's instructions</translate>">^

<translate>

Uninstalling an extension

Remove the line from LocalSettings.php with the extension name to uninstall it: </translate>

wfLoadExtension( 'ExtensionName' );

<translate>

• You must remove any lines pertaining to the configuration of the extension.

See also

</translate>

• - <translate> Information about translating extensions.</translate>

[[Category:Customization techniques{{#translation:}}|TemplateStyles]] [[Category:Extension creation{{#translation:}}]]

The ShortDescription extension allows wikis to add short descriptions to wikitext pages, similar to the implementation on Wikipedia and Wikibase. On top of that, it replaces the site tagline with short description on pages with short description.

Installation

Note that the latest version is located in the GitHub repo instead of Gerrit. Template:ExtensionInstall

Features

• Define short description on the page with the magic word {{SHORTDESC}}, same as the implementation on Wikipedia
• Retrieve short description on any wiki pages with the magic word {{GETSHORTDESC}}
• Add short description underneath the page title on most skins, if the skin supports site tagline (#siteSub)
  • Note that the short description with replace the default site tagline message on pages with short description
  • Does not apply to Skin:Citizen and Skin:Minerva Neue, as they have native support
• Allow short description to be accessed through the Action API
• Provide description to the REST API search endpoint
• Add short description to page information (&action=info)
• Provide description for extensions such as MobileFrontend, RelatedArticles

Configurations

The extension works out of the box without any configurations. The config flags allow more customization on the specific features in the extension.

Name	Description	Values	Default
Template:Phpi	Enables short descritption in site tagline	Template:Phpi - enable; Template:Phpi - disable	Template:Phpi
Template:Phpi	Provide short description to the Opensearch API module	Template:Phpi - enable; Template:Phpi - disable	Template:Phpi

Usage

Add short description

To add Bacon ipsum dolor amet turkey as short description, simply add {{SHORTDESC:Bacon ipsum dolor amet turkey}} on the page.

Retrive short description on wikipage

To retrive the short description on the page Bacon, simply add {{GETSHORTDESC:Bacon}} on the page. If you are retrieving the short description on the same page (e.g. getting the short description of Bacon on the Bacon page), simply add {{GETSHORTDESC:}}.

Retrieve short description through Action API

The short description can be called through the description property in query action in the Action API (e.g.api.php?action=query&prop=description). It is also accessible through the shortdesc property inside pageprops.

Retrieve short description through REST API

The short description can be accessed through the description property in the search endpoint in the REST API.

Screenshots

• 

  ShortDescription on Skin:Citizen

• 

  ShortDescription on Skin:Minerva

• 

  ShortDescription on Skin:Monobook

• 

  ShortDescription on Skin:Timeless

• 

  ShortDescription on Skin:Vector

See also

• T184000 - Magic word on English WP to override display of Wikidata short description
• Extension:Wikibase Client - provide the description functionality on Wikimedia projects
• Extension:RelatedArticles - Use the description from this extension under wikidata mode
• Extension:Description2 - An extension that adds a description meta tag generated automatically from the first paragraph of the page, or manually overridden.

TemplateStyles allow custom CSS pages to be used to style content without an interface administrator having to edit sitewide CSS. TemplateStyles make it more convenient for editors to style templates; for example, those templates for which the sitewide CSS for the mobile skin or another skin (e.g. Timeless) currently negatively affects the display of the template.

Guidelines

• The style must apply only to the associated template's output. It may also apply to highly-relevant nearby wikitext where the template is used. (For example, there are many table templates which should have TemplateStyles which are provided entirely in templates, or which may provide a legend to a wikitext table.) It would otherwise be confusing if adding a template to one part of a page were to completely or partially change the display or styling of an unrelated part of the page.
• Style pages should be associated with a specific template or group of templates, and named accordingly. This allows style pages to be easily identified and edited. In general, this means that a style page should be a subpage of the related template, e.g.: Template:Template:Var/styles.css or Template:Template:Var/styles-Template:Var.css, but not Template:styles-Template:Var.css nor Template:Template:Var.css.
• Generally follow the MediaWiki coding conventions for CSS. Some specifics:
  • Use selectors that are highly likely to be unique to the template being used. This reduces the chance of conflicting CSS rules arising accidentally. Examples: Use .Template:Var-row rather than .row or .Template:Var tr rather than tr.
  • Avoid using #id per the conventions. HTML IDs are supposed to be unique on a page. Templates are rarely used uniquely, and those that are initially single-use-per-page are often later used in unanticipated ways. Use classes instead of IDs for styling.
  • Avoid using !important per the conventions, except in mobile views to override style input from the associated template. Use of !important in TemplateStyles is exceptionally difficult to override because of loading order of styles (personal CSS then TemplateStyles).
• In templates intended to be substituted, or those likely to be substituted, use {{ifsubst}} to remove the TemplateStyles tag. Example: {{allcaps}}.
  • Inline styles may be used as the "if substed" case in a substituted template. Example: {{smallcaps}}.
• Images that do not require attribution (i.e. those in the public domain) are the only images that may be used as background images. For normal file usage, attribution is provided on the file description page, accessed by clicking the image. This is not possible if the image is being used as the background.
• The protection level of style pages should match that of their associated template. If a template is high-risk, then its styles are also high-risk, and should have the same protection. If a template is not high-risk, then vandalism to cause chaos could be achieved just by editing the template itself. A higher protection level for the style page would encourage editors to add inline styles to the template, since the template would be editable but the style page would not. Any templates using CSS pages with the wrong protection level will be categorized in Category:Templates using TemplateStyles with a different protection level.
• Remember to add /* {{pp-template}} */ to any protected CSS pages to ensure that they display the appropriate lock icon. Protected templates using CSS pages that lack the lock icon will be categorized in Category:Templates using TemplateStyles without padlocks.

Note that the Manual of Style, including the Accessibility guidelines, still applies.

Workflow for conversion

1. In Template:Template:Var, identify all of the inline styles that can be moved to a separate stylesheet.
2. Create Template:Template:Var/styles.css containing all the classes that will replace the inline styles. Use template-specific class names where possible.
3. In Template:Template:Var (or its Template:Template:Var/sandbox if you want to test first), add <templatestyles src="Template:Var/styles.css" /> (you don't need to specify the Template: namespace). It's probably best at the top so that it is obvious and to avoid a flash of unstyled content, but it will need to be on its own line if the template begins with wiki markup that has to start on a new line (e.g. wiki-table).
4. Amend the template (or sandbox) to replace the inline styles with the classes you defined in Template:Template:Var/styles.css
5. Do as much checking as you can. If you tested in the sandbox you can check the testcases page where it exists, but specifically check that the styles you affected render properly.
   1. Specifically, for templates meant to be used inline, check to see if there are uses inside of links. TemplateStyles templates will not work inside links (right now).
6. If you used the sandbox, either make an edit request for the main template or do the update if you are confident of your changes.
7. Request or amend the protection level of Template:Template:Var/styles.css to match that of Template:Template:Var as necessary.
8. Add {{Uses TemplateStyles}} to the template's documentation to show which TemplateStyles stylesheets it uses.

Tips

• Uses of TemplateStyles stylesheets are recorded just like template transclusion and Scribunto module invocation. Special:WhatLinksHere and the "Templates used in this preview" section beneath the edit form will work for them in the usual manner.
• To search for TemplateStyles stylesheets, you can [[Special:Search/all: contentmodel:sanitized-css|search for Template:Tt]]. See also mw:Help:CirrusSearch#Contentmodel.
• When {{Uses TemplateStyles}} is placed on a template's documentation, it adds the template to Category:Templates using TemplateStyles. If the TemplateStyles stylesheet has a different protection level, the template will be tracked in Category:Templates using TemplateStyles with a different protection level (0 pages).
• TemplateStyles experiments can be created at Template:TemplateStyles sandbox, e.g. for use in Module:Sandbox module experiments.

Overriding TemplateStyles

Because of the way TemplateStyles is implemented, overriding TemplateStyles in your personal CSS requires a little more effort than normal. The rules on a specific TemplateStyles sheet are not the full CSS rules, nor can you match the selectors to override them.

1. Each selector is 'hoisted' to .mw-parser-output, so to override a rule in a TemplateStyles sheet that looks like .documentation {}, a naive override in your personal CSS file would need to look like .mw-parser-output .documentation {}.
2. However, in the HTML each TemplateStyles style is Template:Em placed after your personal CSS file loads. Accordingly, the new rule would need to be more specific. That can come in a couple ways. The easiest is to select the HTML element also as in: .mw-parser-output div.documentation {}. Another way would be to double one of the class selectors, as in .mw-parser-output.mw-parser-output .documentation {} or .mw-parser-output .documentation.documentation {}. This latter way is a little more future-proof but looks a little weirder.
3. Lastly, !important can always override styles in your personal CSS. The usual caveats regarding !important apply. Prefer one of the two options in bullet two if possible. (You must do this to override inline styles, regardless of any of the above; some templates cannot move everything to TemplateStyles per the flexibility given to template users. Implementers of templates should consider whether parameters like style and width are actually necessary. See also phab:T200632.)

Examples

• mw:Help:TemplateStyles/examples
  • mw:Template:Stylish (CSS)
  • mw:Template:ResponsiveAmboxExample (CSS)
• Template:Thermometer and Template:Thermometer/styles.css give a simple demonstration of how TemplateStyles may be mixed with inline styles (where a parameter is passed to change one or more styles)

See also

• Wikipedia:Lua

External links

• mw:Extension:TemplateStyles
• mw:Help:TemplateStyles