Guidelines:Modules

Overview

Modules are scripts for making templates using a full-fledged programming language. You can ask questions about Zelda Wiki modules in the  [ Discord] channel.

Templates
Modules exist as a means to create more complex templates. In order to contribute to modules, you must first understand how templates are used. You should also know to create a basic template without modules to get a sense of when Lua scripts are needed and why.

Getting Started
In order to contribute to modules, you'll need to learn basic programming in Lua. You'll also need to know the specifics of Lua scripting on MediaWiki.

Beginners
There are many excellent online resources designed to teach programming fundamentals... But none of them are in Lua. Fortunately, Lua is a small and simple language. Jump in and try to learn through the Exercises.

If you find you need more guided lessons, try Codeacademy's Python 2 course, or Khan Academy's Intro to JavaScript. Python is closer to Lua than JavaScript, but Khan Academy's course has the benefit of video talk-throughs. In any case the fundamental language concepts are the same.

Developers
If you already have some programming experience in other languages, read Learn Lua in 15 minutes.

Note the following in particular:

Scribunto

 * For a broader and more in-depth guide, see Gamepedia Help Wiki.
 * See also the full .

Scribunto is the name of the extension that enables Lua modules. The Lua on you see on MediaWiki is almost the same as standard Lua except for to library functions and packages. The main difference is in how Lua scripts are invoked.

The   is what bridges the gap between templates and module scripts. For example, the content of Template:Figurine is as follows:

This invokes Module:Figurine, which could look something like:

A page can invoke any function that is a field on the module's export table. The export table is the  object returned by the module, which is always named   by convention. In this case,  is the only function in the export table.

Functions called via  are passed a.
 * is a table of the arguments to . (There are none in the above example.)
 * is a table of the arguments to the template.
 * Example: If a page has, then   evaluates to the string   for that invocation.

The  operator and most other table functions don't work on.

A module can import another module and use its exported functions. This is done with the  function, as shown in the above example with Module:UtilsGame.

Scribunto pre-loads several MediaWiki-related libraries as the  object. The following libraries are of note, in addition to the :

Debugging

 * See also gphelp:Extension:Scribunto

You should never be in a situation where you're blindly submitting code and hoping that it works. The first two exercises of these guidelines cover how to debug with previewing, logging, and the debug console.

Always ensure that your code does not produce script errors. Please fix or revert any changes that do. Keep an eye on Category:Pages with Invalid Arguments as well.

Testing and Documentation
When coding a module, the best page to preview is often the corresponding template's documentation. If it exists, the page should have usage examples for every available feature. In fact, an effective way to write modules is actually to write the documentation examples before the code itself. When you're writing the actual code, previewing that documentation page will tell you if your code is working—and will give you material to debug with if it isn't. The practice of writing test cases before the code is called.

You should also write module documentation for any Lua function meant to be used by other modules (as is usually the case for utility module functions). Module documentation can double as automated unit tests via the  property. If the output of the function does not equal what is expected, the page is added to Category:Modules with failing tests.

Utility Modules
A utility module is a library-type module meant to be used by other modules, rather than being invoked by a template. Most template-facing modules use at least one of these:
 * Module:UtilsGame
 * Module:UtilsMarkup
 * Module:UtilsTable

A list of utility modules is available at Category:Utility Modules. Leverage utility modules as much as possible so that the wiki's codebase stays.

Higher-Order Functions
In utility modules such as Module:UtilsTable, you'll often see functions like these:

You might've expected the usual function syntax  instead. The above is an example of a higher-order function—a function that returns a function. The function call above is shorthand for:

Functions are written this way for increased reusability. They are often composed with the other type of higher-order function—one that accepts a function as an argument:

Exercises
Try the available exercises to test and develop your understanding of Lua, Scribunto, and Zelda Wiki's utilities.

Style
Once you are able to produce working code, make sure it adheres to Zelda Wiki's coding standards.

It is particularly important to use a consistent naming pattern, as plain text searching is the only way to observe function usage.