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

As part of the 1.36 release in 2020, the SkinMustache class was added to MediaWiki core. This development makes it possible to use Mustache templates to make skins. It should appeal to skin developers who do not wish to use PHP, or would like to reduce their dependency on PHP. This tutorial aims to demonstrate the steps you may need to convert a PHP based SkinTemplate skin to SkinMustache.

Step 1: Use Skin Registration
Previously, a skin would need to declare a Skin PHP class that extends the SkinTemplate. It would need to define several properties that were used to define the skins internal key and the associated PHP template.

Since 1.36, this information can be defined at time of skin registration. Historically, skins have required the creation of 2 PHP classes. With the new registration process, you need at most 1 PHP class.

When declaring a skin, it's possible you can set the class value to "SkinTemplate" to use the default core interface: If your Skin contains hooks, we recommend pulling those out into a separate file.

Here is an example for Monobook: https://gerrit.wikimedia.org/r/c/mediawiki/skins/MonoBook/+/701142

Step 2: Unlock the power of templating
To follow this next step, it's assumed that a little knowledge of the Mustache template language has been acquired. At minimum, you should know the following Mustache basics described in the example below:

Hello World
Create a Mustache file with the relative path templates/skin.mustache To use the SkinMustache class, declare the class property as SkinMustache and pass the argument options templateDirectory and template name properties at registration. There is no need to include the file extension. Load the skin in your browser and you should see the contents of your Mustache file.

Using a custom class
To aid migration, you'll want to use your own custom class that extends SkinMustache, at least as an interim step and start redirecting the code from your skin template into templates.

Create a new skin class that extends SkinMustache, for example for the MonoBook skin this might be named SkinMonoBook.

When using a PHP based template e.g. MonoBookTemplate, the skin developer is expected to implement an execute function that echo's HTML. in SkinMustache, the approach is different. We provide an associative array of template data that is passed to a Mustache template.

In the example that follows, we set new data to pass to the Mustache template With this change we can make the following change to our template to output the data. Using this technique we can bridge our old skin with SkinMustache.

First we may need to refactor our execute method to separate out a function that returns a string which represents the body of the skin. It's important to note in SkinMustache, you are restricted to templating the content of the body tag.

Step 3: Embrace data.
At this point you should have a skin implementing SkinMustache which is leveraging BaseTemplate to generate HTML. The PHP inside your PHP template that implements BaseTemplate should be possible with Mustache.

TODO

Step 4: Fill out the missing data
TODO