Scribunto: An Introduction/When to convert a template

In the last chapter, we learned that Scribunto was developed to address performance problems with MediaWiki templates. In Scribunto, most of the features that templates use are available natively, and other template features can be accessed by preprocessing raw template code inside Scribunto modules. In other words, Scribunto can do everything that templates can. Furthermore, individual operations in Scribunto are faster than operations in template code. So, should all templates be converted to use Scribunto instead of template code?

Well, not quite.

There are various factors involved in whether it would be beneficial to convert a template, including its complexity, whether it handles large amounts of data, and what wikitext features it contains. It is also a good idea to assess the impact that conversion of a template would have, to make sure you spend your programming time wisely. On this page, we will learn how to find suitable templates to convert, and what templates should be left as they are.

Don't convert simple templates

To start with, very simple templates should not be converted to Lua. Templates that consist mostly of text and contain no or very few parser functions should be left as they are. There are two reasons for this.

The first reason is that there is a slight overhead involved when running Scribunto. MediaWiki is written in the PHP programming language, and Scribunto modules are written in the Lua programming language. Switching from one programming language to another requires some fairly complicated logistics, and this takes processing time. The cost of getting ready to run a Lua module is somewhere from two to four milliseconds, depending on the version of Scribunto being used. Once Lua is initialised, Lua code will run much faster than the equivalent template code, but the initial overhead means that very simple templates will run faster than the equivalent Lua modules.

The second reason is that simple templates are usually easier for editors to read than the equivalent Lua modules. While templates can be full of conditional logic and parser functions, their original function was to display the same or similar content on multiple pages. Templates gained a reputation as being difficult to read because of the complexity they acquired over the years; however, simple templates with a lot of text are easy to understand. Lua modules, on the other hand, have a specialised syntax that is geared towards expressing complex logic. Because of the ability to indent code and add comments, among other things, it is often easier to understand complex logic when expressed in Lua code rather than template code. However, for simple content, using templates is the more readable choice.

You can see all the arguments

Scribunto modules have one big advantage over templates: you can access all of a template's arguments. For a template to be able to use an argument, it has to be specified explicitly in the template code. For example, let's imagine that we are using a template that says hello to someone, called "Template:Hello". It has the following code:

Hello, {{{name}}}!

If we use this template with the code {{hello|name=Anna}}, it will display "Hello, Anna!" This is probably familiar to anyone who has used MediaWiki templates. But what if we call it with the code {{hello|name=Anna|abc=def}}?

The extra argument doesn't have any effect on the template; it simply displays "Hello, Anna!" However, in Lua modules, we can detect the fact that there is an extra argument, and change the display value based on it. For example, we could display an error message that says "Unexpected argument 'abc' detected".

Arbitrary arguments

This ability to see all the arguments passed to a template has a number of interesting effects. First, it means that Lua modules can accept an arbitrary number of arguments. For example, consider a template that prints out a list of names. It uses the parameters {{{1}}}, {{{2}}}, {{{3}}}, etc. for the name values. In template code, you have to specify each numbered parameter, and if you want to output a variable number of parameters you have to test whether each one exists.

List of names: {{{1}}}{{#if: {{{2|}}} | , {{{2}}} }}{{#if: {{{3|}}} | , {{{3}}} }} ...

This means that there is always an upper limit to the number of names that the template can output. If you want to output 20 names, there must be 20 parameters listed in the template code. Lua, however, has no such limit. All you have to do is write some code that constructs a list item for one name, and then use that code for every name passed to the template. If 20 names were passed to the template, you would use that code 20 times. If only three names were passed to the template, you would only use the code three times. And if 1000 names were passed to the template, there would still be no problems displaying them all.

The ability to get all the arguments passed to a template is one of the biggest reasons that Lua is faster than template code. Imagine that our example template above was written to output a maximum of 10 names.

List of names: {{{1}}}{{#if: {{{2|}}} | , {{{2}}} }}{{#if: {{{3|}}} | , {{{3}}} }}{{#if: {{{4|}}} | , {{{4}}} }}{{#if: {{{5|}}} | , {{{5}}} }}{{#if: {{{6|}}} | , {{{6}}} }}{{#if: {{{7|}}} | , {{{7}}} }}{{#if: {{{8|}}} | , {{{8}}} }}{{#if: {{{9|}}} | , {{{9}}} }}{{#if: {{{10|}}} | , {{{10}}} }}

Even if we only want a list of three names, the template still checks all 10 parameters to see if any of them contain a name. The Lua version, on the other hand, would only check the three names that we passed to it. Checking parameters takes a relatively long time, so Lua has a big performance advantage over template code for applications like this one.

For these reasons, templates with parameters like {{{1}}}, {{{2}}}, {{{3}}}, etc., or {{{value1}}}, {{{value2}}}, {{{value3}}}, etc., should almost always be converted to Lua.

Template-manipulation templates

Some templates aim to manipulate arguments from other templates. For example, Template:Unsubst on the English Wikipedia was used with other templates to check whether they had been substituted by mistake. If they had been, Template:Unsubst would output the unsubstituted version of the template instead. Template:Unsubst required template authors to input every parameter their template used manually; however, after this was converted to Lua in Module:Unsubst, parameters passed to templates were detected automatically. If you want to write a template that aims to process all of the arguments passed to it, then Lua is the tool to use.

Complex templates

The other main candidates for conversion to Lua are complex templates. Sometimes you will find very complex templates, that have many parser functions, and call subtemplates that also have many parser functions, which call yet more subtemplates... Due to their many levels, on Wikia these templates are known as inceplates, after the film Inception. These templates are the ones which benefit the most from being converted to Lua.