Manual talk:How to make a MediaWiki skin

Ask any question that is blocking you from writing a skin and help others build skins.

Hi, the issue I have with this article is that it starts off by saying that if you know HTML, CSS and Javascript you can create a skin. Knowledge of PHP and 'Mustache' are not essential. But thereafter the entire page talks about nothing else but PHP and Mustache.

I honestly do not even know where to begin with this. Having downloaded the example theme I see dozens of files and I have not the first clue where to start and what to do. Is MediaWiki simply not designed for beginners, like WordPress is for example?

You shouldn't need to know PHP, but Mustache is definitely a requirement (could you point me to where in the page it suggests that it isn't?).

Where is PHP referenced? I am only seeing reference to it in the advanced section.

Personally I recommend following the guide here as it is currently the most up to date:

Manual:How to make a MediaWiki skin#Option 3 - From the command line

Regarding where to start - I'd suggest modifying templates/skin.mustache, resources/skin.less and resources/skin.js to see instance feedback that it's working.

Hope this helps.

Where's the skin entry point? Is it the PHP class specified in skin.json -> ValidSkinNames.exampleSkin.class? If so, what method of that class is called by default?

I'm not sure I understand the question.

ValidSkinNames will register your skin.

The class you specify there will extend class Skin which will define an outputPage method which will echo the contents of the body HTML tag of the page.

Much of this is abstracted. For example if you use SkinMustache (the recommended way), this will render the content of skin.mustache with the template data returned by SkinMustache::getTemplateData().

Does this answer your question?

Yes, that makes sense, thank you. So for a Mustache skin, it looks like MW checks skin.json, loads the templateDirectory/template.mustache specified there, and fills it with data from the PHP class specified there, specifically its getTemplateData() method. Not super intuitive, but makes sense once explained. Maybe I can make this a little more prominent in the documentation or comments somewhere.

I created a Mustache skin, probably following the guidelines (no guarantee...) and that worked fine! Very happy with the skin, but then something weird happened. For a second user, the skin won't load because it isn't VE compatible, even if that user has the same user-rights as Admin.

Could you add some guidelines on how to make the skin VE compatible?

I'll do that now. TLDR: Extension:VisualEditor/Skin_requirements should help you here!

I am facing an issue with showing the menu items using {{{html-items}}} , the code mentioned in Manual:How to make a MediaWiki skin#Rendering menus with Mustache.

I want to use some specific classes for the menu items but it rendering HTML . How can i get the individual menu item name, url as data?

Depends on the MediaWiki version. In more recent versions of MediaWiki array-items is provided. See Manual:SkinMustache.php#PortletData

Looks like someone fixed it.

@Jdlrobson In section I want to change elements in the head of the HTML page please complete the sentence :

Modifications of the HEAD are better served via extensions and configuration inside LocalSettings.php.
For any questions please use the 

Thanks.

Christian 🇫🇷 FR (talk) 21:38, 5 January 2023 (UTC)

I want to migrate the skin Skin:MediaWikiBootstrap from SkinTemplate to SkinMustache as for the new skins SkinMustache is the recommended way. If there is any migration guide available then I may follow that.

Manual:How to make a MediaWiki skin/Migrating SkinTemplate based skins to SkinMustache

Done in Manual:How_to_make_a_MediaWiki_skin#Making_skins_compatible_with_languages_that_are_right-to-left_(RTL)

Update the tutorial to show what skins need to do to add RTL support (from Topic:Wbcuv2jihh1hkjrs)

Skins should not add additional functionality to the MediaWiki experience. Their sole responsibility is to render data passed to them.

How to show page stat? along with the view count, is there any other stat is available from core?

This is a bit out of scope for a skin. I would expect an extension to provide this kind of data. We don't have such data in MediaWiki core.

Not extensions can use Manual:Hooks/SkinAfterContent to output such information provided the skin renders html-after-content.

Documentation was expanded with information about footer. Please ask another question on talk page if something is still confusing.

In Topic:Wbcuv2jihh1hkjrs it was asked "how to control the footer links?"

Let's understand what's being asked here and update the documentation. Does the developer want to add / remove links on the skin level, or need a tutorial for displaying footer links, or other?

In short docs needs similar as Manual:Skinning Part 2#Footer.

There should be instructions on,

1. how to add new links to the footer area,
2. how to show texts form a file from the project root/ skin root (it could be a version number or some other text from a file)
3. what if I would like to show the license as text and not to show the icon
4. how to show "Powered by MediaWiki" as a line to text and not to show the logo
5. how to show the items in the list
6. and all the things mentioned in Manual:Skinning Part 2#Footer.

I've added Manual:SkinMustache.php#DataFooter to document the data relating to the footer that is passed down.

With SkinMustache, skins are expected to render content without opinion other than should I display this or not.

Most of this is being defined by configuration/extension hook.

For icons for example rendering text rather than a logo is discouraged as this is enabled by Manual:$wgFooterIcons. If you want to render text, you'll need to provide your own link and label using the technique in Manual:How_to_make_a_MediaWiki_skin#i18n.

Your template can render whatever HTML it chooses too, your skin.mustache file is yours to edit - so if you need to add new links or random license information that is not configurable just add it in the HTML, or even better still add it as part of an extension or LocalSettings.php using the associated hook: Manual:Hooks/SkinAddFooterLinks

Sitenotices are provided as an HTML string that is empty if no site notices are present. To conditionally render site notices:

{{#html-site-notice}}
{{{.}}}
{{/html-site-notice}}

{{{html-site-notice}}} shows the site notice, is there any way to get the data? can i check if there is any site notice?

There is no way to get at the underlying data. This is because of the way CentralNotice and other extensions work.

You are free to wrap the HTML in any HTML elements that you choose.

What is your use case here?

I will show the site notice within some HTML elements and I do not want to show that wrapper element if there is not notice to show. This is the primary need.

If I had the access to the data then I may try to format that in my way. But as you confirmed that it is not available, then that is ok too.

Mustache supports an if guard so you can conditionally render an element based on that. The string will be empty it there is no site notice to display.