Manual:SkinMustache.php
| MediaWiki file: SkinMustache.php | |
|---|---|
| Location: | includes/skins/ |
| Source code: | master • 1.42.3 • 1.41.4 • 1.39.10 |
| Classes: | SkinMustache |
The SkinMustache class is a generic class for use with Mustache templates. It allows skin developers the flexibility to display the underlying data however they chose. A Mustache template is associated with the skin to be rendered and receives template data as described below.
To explore this more see Manual:How to make a MediaWiki skin.
Template data
[edit]All data referenced here can be explored using the SkinJSON skin.
The Mustache skin associated with a skin receives the following data:
| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| array-sections | Section[] | Allows skins to render table of contents separately from the article body. | 1.38 |
| data-logos | DataLogos | Provides access to information about logos as described in $wgLogos | 1.36 |
| array-indicators | DataHtmlObject[] | An array of raw HTML items. Can be used to display Help:Page_status_indicators | 1.35 |
| data-search-box | DataSearchBox | Used to render the search (see below) | 1.35 |
| html-site-notice | string (HTML) | Render via triple braces to support the display of banners.
Including this adds support for site notices. |
1.35 |
| html-user-message | string (HTML) | Can be used to display the yellow message bar notifying the user they have talk page messages inside the article body.
Example of the user message: File:010405ah.png |
1.35 |
| html-title | string (HTML) | Must be rendered to display the page title. Note that wikipage titles may contain certain HTML elements for example the `i` tag for italized text. The HTML does not include the heading tag, as it's up to you which tag to use e.g. h1 or h2.
If your skin is to be designed to support multiple languages you should also output {{{html-user-language-attributes}}} |
1.35 |
| html-subtitle | string (HTML) | Can be rendered to display subtitles under the page html-title. By default this is an empty string, but on certain pages - for example user subpages, and with certain MediaWiki extensions it will appear. Read more about subtitles. The subtitle should be considered a block element, which may have several rows. | 1.35 |
| html-body-content | string (HTML) | Must be rendered to display the content of the page | 1.35 |
| html-categories | string (HTML) | Can be rendered to display categories | 1.35 |
| html-after-content | string (HTML) | Usually empty, but can be used to allow extensions such as RelatedArticles to render underneath an article (for example adverts). Include this HTML in a place that makes sense after the main content. | 1.35 |
| html-undelete-link | string (HTML) | Must be rendered if you want your skin to support a box on pages that have been deleted allowing them to be undeleted. | 1.35 |
| html-user-language-attributes | string (HTML) | HTML attributes that reflect the user's preferred language and its direction. Must be used on an element if you support RTL languages. Any child of the element will inherit these properties. Read more about language codes in the HTML spec.
As a general rule of thumb, you should only need to put this in root node(s) inside your skin.mustache file. |
1.35 |
| link-mainpage | string | the URL of the main page. Can be used to link back to the home page | 1.36 |
| data-portlets | DataPortletsObject | Can be used to render menus that extensions can extend and site admins can configure. Each menu must be accessed by name.
See below and the rendering menus section of Manual:How to make a MediaWiki skin. |
1.36 |
| data-portlets-sidebar | DataPortletSidebar | Can be used to render menus that traditionally appear in the sidebar of Vector that extensions can extend and site admins can configure. Data is separated into the first portlet and then an array of other portlets that must follow.
The content of this menu is treated separately from data-portlets as this menu can be configured inside the wiki via an edit to the Sidebar. See Manual:Interface/Sidebar for more information. The sidebar may contain a variable amount of submenus so is structured differently from data-portlets. |
1.36 |
| data-footer | DataFooter | Can be used to render footer links that extensions can extend and site admins can configure. Usually this contains links such as the "mobile view", disclaimers and privacy policy but can be configured by LocalSettings.php and extension. Read more about customization of the footer. | 1.36 |
| msg-<message-key> | string | A skin can declare messages at skin registration. Any message declared will be translated and passed to the template escaped. HTML messages are currently not supported.
Messages can be defined locally to the skin inside i18n/en.json or you can use any of the messages defined in core. Learn more about Localisation. |
1.36 |
| is-anon | boolean | true on pages where the user is not logged in
|
1.38 |
| is-article | boolean | true on pages where the page being read is "an article" (e.g. main namespace)
|
1.38 |
| is-specialpage | boolean | true on pages where the page being read is a special page e.g. Special:Preferences
|
1.38 |
| is-mainpage | boolean | true if the page is the main page.
|
1.38 |
For backward compatibility there are several types of Menus to be aware of when rendering in SkinMustache. It is hoped in future a standardized menu format will be used for all.
Section
[edit]| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| toclevel | number | Is this an h1, h2, h3? | 1.38 |
| line | string | The heading of the section. | 1.38 |
| level | string | 1.38 | |
| number | string | 1.38 | |
| index | string | 1.38 | |
| from_title | string | The page associated. Perhaps redundant. | 1.38 |
| byteoffset | integer | The byte offset where the section occurs. | 1.38 |
| anchor | string | The anchor link | 1.38 |
| has-subsections | boolean | Does this section have subsections? | 1.38 |
| is-last-item | boolean | Is this section the last of the current toclevel | 1.38 |
AttributeData
[edit]| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| key | string | The name of an HTML attribute e.g. "href" | 1.40 |
| value | string | The value of a HTML attribute e.g. "/wiki/Link" | 1.40 |
PortletLinkData
[edit]| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| icon | string | Icon name | 1.40 |
| array-attributes | AttributeData[] | Array of all the HTML attributes that can be rendered on a link. | 1.40 |
| text | string | Text of the link | 1.40 |
PortletListItemData
[edit]| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| html-item | string | HTML representation of list item and link | 1.40 |
| name | string | ID unique to this specific menu (not typically rendered but can be useful for instrumentation purposes) | 1.40 |
| id | string | ID of the menu item, typically rendered as ID attribute on list item (li) | 1.40 |
| class | string | class attribute of the menu item, typically rendered as ID attribute on list item (li)
|
1.40 |
| html | string | HTML of just the link (see also array-links) | 1.40 |
| array-links | PortletLinkData | Data structure representing the link(s) contained in the menu item. | 1.40 |
PortletData
[edit]Menus (aka portlets/portals) in SkinMustache have a consistent data structure that looks like follows:
| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| id | string | The HTML ID attribute of the portlet. Must be output for compatibility with gadgets and extensions on a container element. | 1.36 |
| class | string | The HTML class attribute of the portlet. Must be output for compatibility with gadgets and extensions on a container element. | 1.36 |
| label | string | The human readable name of the menu. Can be used for rendering a header for the menu. Generally, it is important to display this to all users when rendering groups of menus (e.g. sidebar, DataPortletSidebar) but not for single menus (DataPortletsObject).
We recommend you consider always rendering this in the page, as this label is important to screen readers and making your skin accessible. |
1.36 |
| html-tooltip | string (HTML) | Other HTML Attributes that should be output along the ID and class. This may contain access key and title attributes. | 1.36 |
| array-items | PortletListItemData | Equivalent of html-items for skin developers who need more flexibility. | 1.40 (9c4f70c22251) |
| html-items | string (HTML) | The list items representing the menu. Note when rendering this you must wrap it inside a list tag e.g. ol or ul | 1.36 |
| html-after-portal | string (HTML) | Extensions such as UniversalLanguageSelector have expressed a desire to add HTML at the end of a menu. Rendering is optional.
Note, despite the name skin developers may decide to render this in the same place as html-before-portlet. Note this is not the same as html-before-portlet. You must render both for full extension compatibility. |
1.36 |
| html-before-portal | string (HTML) | Can be rendered to allow extensions to add HTML before a menu. Rendering is optional.
Note this is not the same as html-after-portlet. You must render both for full extension compatibility. |
1.37 |
DataPortletSidebar
[edit]| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| data-portlets-first | PortletData | Must be used if your skin supports languages | 1.36 |
| array-portlets-rest | PortletData[] | Can be used to allow extensions to surface settings controls outside the context of Special:Preferences. | 1.36 |
DataPortletsObject
[edit]The data-portlets object allows access to all the different menus that are available to render. Menus are organized into different buckets. A skin developer can choose to render each of these separately, to modify these buckets via the SkinTemplateNavigation::Universal hook, or omit them. Each menu contains data consistent with data-portlets-sidebar.
| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| data-languages | PortletData | Must be used if your skin supports languages | 1.36 |
| data-user-interface-preferences | PortletData | Can be used to allow extensions to surface settings controls outside the context of Special:Preferences. | 1.37 |
| data-user-page | PortletData | Should be used to render a link to the user's user page and user talk page. | 1.37 |
| data-user-menu | PortletData | Should be used to render links personal to a user e.g. their user contributions page and sandbox. | 1.37 |
| data-notifications | PortletData | Should be used to render user notifications e.g. support Echo | 1.37 |
| data-namespaces | PortletData | Must be used to provide access to the discussion page. | 1.36 |
| data-views | PortletData | Must be used to provide access to the edit and history links | 1.36 |
| data-actions | PortletData | Must be used to provide access to admins to protect, delete and move actions. | 1.36 |
| data-variants | PortletData | Must be used if your skin supports language variants | 1.36 |
| data-personal | PortletData | Should not be used if data-notifications, data-user-menu, data-user-page or data-user-interface-preferences are being used. In 1.37 this menu bucket was split up into multiple buckets. Usage is discouraged in new skins. | 1.36 |
DataFooterLine
[edit]| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| id | string | HTML ID attribute of item | 1.36 |
| className | string | CSS classes for that item that can be used. Note this property name is inconsistent with others. It may be renamed to class in future. | 1.36 |
| array-items | DataFooterItem (1.36)|PortletListItemData (1.40) | Array of footer items to render | 1.36 |
DataFooterItem
[edit]| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| name | string | A unique name/key you can use to identify the footer line from others. | 1.36 |
| id | string | The HTML ID attribute of the footer element, derived from name | 1.36 |
| html | string (HTML) | The raw HTML (usually a link) | 1.36 |
DataFooter
[edit]| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| data-info | DataFooterLine | Contains last modified information. | 1.36 |
| data-places | DataFooterLine | Used to render privacy, disclaimer. Used by MobileFrontend to add mobile view link. | 1.36 |
| data-icons | DataFooterLine | Used to render icon images | 1.36 |
Other
[edit]DataHtmlObject
[edit]When dealing with this type, you are expected to create a container with id and class as attributes and html as its inner HTML. The container may contain other elements if you wish. The primary reason for the existence of this type, is you may want to render certain items as lists (`li` element) or blocks (`div` elements).
| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| id | string | An id of container element | 1.35 |
| class | string | classes for container element | 1.35 |
| html | string | raw HTML of component | 1.35 |
DataSearchBox
[edit]| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| form-action | string | Where the form should post to e.g. /w/index.php | 1.35 |
| html-button-search-fallback | string (HTML) | A button that triggers a full text search. Usually, e.g. in Vector skin, this is hidden for users with JavaScript, but is important to include when considering the primary action of the form (e.g. what happens when the user hits ENTER key). In the MonoBook skin for example, two buttons are rendered to the user.
Consider placing this element after html-button-search and using `.client-js .mw-fallbackSearchButton` selector to hide this element. Rendering this is optional, if you render html-button-search and at the discretion of the skin developer. See also html-button-fulltext-attributes. |
1.35 |
| html-button-search | string (HTML) | A button that goes to a page with this exact name if it exists. If this is made the primary action of the form you should consider linking to the Special:Search page.
Rendering this is optional, if you render html-button-search-fallback and at the discretion of the skin developer. See also html-button-go-attributes. |
1.35 |
| html-input | string (HTML) | search input element with placeholder text | 1.35 |
| page-title | string (HTML) | This is a input[type=hidden] providing the localized title for search e.g. Special:Search. You must render it for your form to work without JavaScript as otherwise the search form will not know where to submit to.
Note, you should not hardcode this HTML as some extensions may change the default search page, for example, Extension:MediaSearch. |
1.35 |
| html-input-attributes | string (HTML) | Helper template data that can be used instead of `html-input` to render a search input that is compatible with installed extensions and MediaWiki code. | 1.38 |
| html-button-go-attributes | string (HTML) | Helper template data that can be used instead of `html-button-search` to render a button or input[type=submit] element that is compatible with installed extensions and MediaWiki code. | 1.38 |
| html-button-fulltext-attributes | string (HTML) | Helper template data that can be used instead of `html-button-search-fallback` to render a button or input[type=submit] element that is compatible with installed extensions and MediaWiki code. | 1.38 |
DataLogos
[edit]Note this data structure can be extended by extensions, and site configuration in LocalSettings.php
| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| icon | string | Path to a square icon | 1.35 |
| 1x | string | Path to a square icon at 1x resolution | 1.35 |
| 2x | string | Path to a square icon at 2x resolution | 1.35 |
| wordmark | LogoObject | For a text logo e.g. Wikipedia | 1.35 |
| tagline | LogoObject | Tagline for a site e.g. "The free encyclopedia".
Not to be confused with {{msg-tagline}} which renders the message called "tagline", however this can be used as a good fallback for when a tagline is not defined e.g. {{#data-logos}} {{! access logo data }}
{{#tagline}} {{! tagline is defined! }}
<img src="{{src}}">
{{/tagline}}
{{^tagline}} {{! tagline is not defined! }}
{{msg-tagline}} {{! render a message in its place }}
{{/tagline}}
|
1.35 |
LogoObject
[edit]Note this data structure can be extended by extensions, and site configuration in LocalSettings.php
| Template key | Data type | Usage | Available in MediaWiki version |
|---|---|---|---|
| src | string | URL to the logo component | 1.35 |
| width | number | Width in pixels | 1.35 |
| height | number | Height in pixels | 1.35 |
| style | string | The value of a style attribute which expresses the height and width in em's based on a default browser font size of 16px. Can be used to make logos scale with changes to browser text size. | 1.38 |