Manual:SkinMustache.php

From mediawiki.org
Jump to navigation Jump to search

The SkinMustache class 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 MediaWiki: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

Menus (aka portlets/portals)[edit]

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

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
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 Manual:Hooks/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 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