2021pedia:WP:Lua

<languages/> Template:ExtensionTypes

<translate> Extensions let you customize how MediaWiki looks and works. </translate>

• <translate> Wiki users can [[<tvar name=cat>Special:MyLanguage/Category:Extensions by category</tvar>|browse through extensions]].</translate>
• <translate> System administrators can [[<tvar name=1>#Installing an extension</tvar>|install]] (or remove) extensions on the MediaWiki installations that they manage.</translate>
• <translate> Developers can [[<tvar name=man>Special:MyLanguage/Manual:Developing extensions</tvar>|write new extensions]] or [[<tvar name=cat>Special:MyLanguage/Category:Unmaintained extensions</tvar>|improve or maintain extensions]]. </translate>

<translate> While some extensions are maintained by MediaWiki developers, others were written by third-party developers.</translate> <translate> As a result, many have bugs, and they are not all guaranteed to be compatible with each other.</translate> <translate> Some are unmaintained; not all extensions work on all versions of MediaWiki.</translate> <translate> Use any extension, especially those tagged as insecure, at your own risk.</translate> <translate> If you are using an extension that requires patches to the core software, be sure to backup your database.</translate> <translate> This helps avoid the risk of breaking your wiki.</translate>

<translate>

Types of extensions

</translate>

Template:InfoCard Template:InfoCard

<translate>

Browsing extensions

</translate> <translate> You can browse <tvar name=cat></tvar> to see the full range of extensions that have already been written.</translate> <translate> For information on installing these extensions or writing your own, see below.</translate>

<translate>

Checking installed extensions

</translate> <translate> Only someone with administration access to the filesystem (and often the database too) on a server can install extensions for MediaWiki, but anyone can check which extensions are active on an instance of MediaWiki by accessing the <tvar name=special>Special:Version</tvar> page.</translate> <translate> For example, these extensions are active in the English Wikipedia.</translate>

<translate>

Installing an extension

</translate> <translate> MediaWiki is ready to accept extensions just after [[<tvar name=man>Special:MyLanguage/Manual:Installation</tvar>|installation]] is finished.</translate> <translate> To add an extension follow these steps:</translate>

1. <translate> Before you start</translate>

   <translate> Many extensions provide instructions designed for installation using unix commands.</translate> <translate> You require shell access (SSH) to enter these commands listed on the extension help pages.</translate>

2. <translate> Download your extension.</translate>

   <translate> [[<tvar name=special>Special:ExtensionDistributor</tvar>|Extension Distributor]] helps you to select and download most of the popular extensions.</translate>

   <translate> Extensions are usually distributed as modular packages.</translate> <translate> They generally go in their own subdirectory of <tvar name=IP>/extensions/</tvar>.</translate> <translate> A list of extensions stored in the Wikimedia [[<tvar name=gerrit>Special:MyLanguage/Gerrit</tvar>|Git repository]] is located at <tvar name=extensions>git:mediawiki/extensions</tvar>.</translate> <translate> Some extensions [[<tvar name=cat>Special:MyLanguage/Category:Extensions which host their code in-wiki</tvar>|don't use version control]] and are not recommended.</translate>

   <translate> Some extensions are also available in [[<tvar name=1>Special:MyLanguage/Software bundles</tvar>|bundles]], <tvar name=composer></tvar> or [[<tvar name=2>Special:MyLanguage/Comparison of extensions in distributions</tvar>|package repositories]].</translate>

3. <translate> Install your extension.</translate>.

   <translate> At the end of the <tvar name=LocalSettings></tvar> file, add:</translate>

   wfLoadExtension( 'ExtensionName' );
   

   <translate> This line forces the PHP interpreter to read the extension file, and thereby make it accessible to MediaWiki.</translate>

   <translate> Some extensions can conflict with maintenance scripts, for example if they directly access $_SERVER (not recommended).</translate>

   <translate> In this case they can be wrapped in the conditional so maintenance scripts can still run.</translate>

if ( !$wgCommandLineMode ) {
   wfLoadExtension ( 'ExtensionName' );
}

<translate> : The maintenance script <tvar name=ImportDump></tvar> will fail for any extension which requires customized namespaces which is included inside the conditional above such as <tvar name=1></tvar>, <tvar name=2></tvar>.</translate>

<span class="citation wikicite" id="endnote_<translate> Ensure that required permissions are set for extensions!</translate>">^

<span class="citation wikicite" id="endnote_<translate> While this installation procedure is sufficient for most extensions, some require a different installation procedure.</translate> <translate> Check your extension's documentation for details.</translate>">^

<span class="citation wikicite" id="endnote_<translate> If you want to alter configuration variables in LocalSettings.php, you have to do this typically after including the extension.</translate> <translate> Otherwise defaults defined in the extension will overwrite your settings.</translate>">^

<translate>

Upgrading an extension

</translate> <translate> Some extensions require to be updated whenever you update MediaWiki, while others work with multiple versions.</translate> <translate> To upgrade to a new version of an extension:</translate>

<translate>

1. Download the new version of the extension</translate>

<translate>

1. Replace all the extension files in the extension/ExtensionName directory with the new files.</translate> <translate> Do not remove the extension configuration present in LocalSettings.php</translate>

<translate>

1. If the extension requires changes to the MediaWiki database, you will need to run the Update.php maintenance script.</translate> <translate> Most extensions will mention if this script needs to be run or not.</translate> <translate> (Perform backup of your data before executing the script).</translate> <translate> If you don't have command line access, you can also use the [[<tvar name=man>Special:MyLanguage/Manual:Upgrading#Web_updater</tvar>|web updater]].</translate>

<span class="citation wikicite" id="endnote_<translate> These instructions cover 99% of extensions.</translate> <translate> If the specific extension you are upgrading has instructions that differ from these, you should probably follow the specific extension's instructions</translate>">^

<translate>

Uninstalling an extension

Remove the line from LocalSettings.php with the extension name to uninstall it: </translate>

wfLoadExtension( 'ExtensionName' );

<translate>

• You must remove any lines pertaining to the configuration of the extension.

See also

</translate>

• - <translate> Information about translating extensions.</translate>

[[Category:Customization techniques{{#translation:}}|WP:Lua]] [[Category:Extension creation{{#translation:}}]]

The ShortDescription extension allows wikis to add short descriptions to wikitext pages, similar to the implementation on Wikipedia and Wikibase. On top of that, it replaces the site tagline with short description on pages with short description.

Installation

Note that the latest version is located in the GitHub repo instead of Gerrit. Template:ExtensionInstall

Features

• Define short description on the page with the magic word {{SHORTDESC}}, same as the implementation on Wikipedia
• Retrieve short description on any wiki pages with the magic word {{GETSHORTDESC}}
• Add short description underneath the page title on most skins, if the skin supports site tagline (#siteSub)
  • Note that the short description with replace the default site tagline message on pages with short description
  • Does not apply to Skin:Citizen and Skin:Minerva Neue, as they have native support
• Allow short description to be accessed through the Action API
• Provide description to the REST API search endpoint
• Add short description to page information (&action=info)
• Provide description for extensions such as MobileFrontend, RelatedArticles

Configurations

The extension works out of the box without any configurations. The config flags allow more customization on the specific features in the extension.

Name	Description	Values	Default
Template:Phpi	Enables short descritption in site tagline	Template:Phpi - enable; Template:Phpi - disable	Template:Phpi
Template:Phpi	Provide short description to the Opensearch API module	Template:Phpi - enable; Template:Phpi - disable	Template:Phpi

Usage

Add short description

To add Bacon ipsum dolor amet turkey as short description, simply add {{SHORTDESC:Bacon ipsum dolor amet turkey}} on the page.

Retrive short description on wikipage

To retrive the short description on the page Bacon, simply add {{GETSHORTDESC:Bacon}} on the page. If you are retrieving the short description on the same page (e.g. getting the short description of Bacon on the Bacon page), simply add {{GETSHORTDESC:}}.

Retrieve short description through Action API

The short description can be called through the description property in query action in the Action API (e.g.api.php?action=query&prop=description). It is also accessible through the shortdesc property inside pageprops.

Retrieve short description through REST API

The short description can be accessed through the description property in the search endpoint in the REST API.

Screenshots

• 

  ShortDescription on Skin:Citizen

• 

  ShortDescription on Skin:Minerva

• 

  ShortDescription on Skin:Monobook

• 

  ShortDescription on Skin:Timeless

• 

  ShortDescription on Skin:Vector

See also

• T184000 - Magic word on English WP to override display of Wikidata short description
• Extension:Wikibase Client - provide the description functionality on Wikimedia projects
• Extension:RelatedArticles - Use the description from this extension under wikidata mode
• Extension:Description2 - An extension that adds a description meta tag generated automatically from the first paragraph of the page, or manually overridden.

WP:Lua (talk) Help To do Resources Reference manual

Lua is a programming language that is available via the Scribunto MediaWiki extension on the English Wikipedia. Since February 2013, Lua code can be embedded into wiki templates by employing the "{{#invoke:}}" functionality of Scribunto. This extension supports Lua 5.1 as of October 2022.

The Lua source code is stored in pages called modules (e.g., Module:Example). These individual modules are then invoked (by code {{#invoke:<Module name>|<Function name>|(optional) param1 | param2...}}). Example:

Wikitext	Result
{{#invoke:Example|hello}}	Hello World!

Running a module

Modules are run on normal wiki pages using the #invoke parser function. The syntax of #invoke is similar to template syntax, but with some differences. The most important difference is that you need to specify a function name. A function is a set of instructions that takes input values, processes them, and returns an output value. This is much like what a template does: you give it arguments, it processes them, and you get a result. However, you can define many functions in one Lua module, whereas you can only define one template on one page.

Furthermore, you can't just run a Lua module directly – you can only run one of the module's functions. The module is just a container for the functions, and doesn't do anything by itself. So there are two reasons that we need to input a function name: we can't run a module by itself, and without specifying a function name, Lua will not know which function it is we want to run.

The simplest way to run a module from a wiki page is like this:

{{#invoke:module name|function name}}

For example, we can run Module:Example in this way, which has a function named "hello".

• {{#invoke:Example|hello}} → Hello World!

Using arguments

Arguments are passed to modules in the same way that they are passed to templates. Note, however, that the text after the first pipe character is always the function name; the first positional argument is the text after the second pipe.

{{#invoke:module name|function name|first positional argument|second positional argument|named argument = value}}

In Module:Example, the "hello_to" function greets different people depending on the first positional argument. It works like this:

• {{#invoke:Example|hello_to|Kate}} → Hello, Kate!
• {{#invoke:Example|hello_to|Fred}} → Hello, Fred!

A third function in Module:Example, named "count_fruit", uses the named arguments bananas and apples to count the number of bananas and apples we have. It can be run like this:

• {{#invoke:Example|count_fruit|apples=3|bananas=4}} → I have 4 bananas and 3 apples
• {{#invoke:Example|count_fruit|bananas=5|apples=2}} → I have 5 bananas and 2 apples

Most modules have a documentation page explaining what arguments can be used and what their effects will be.

Request a script

Visit Wikipedia talk:Lua to request help in writing a Lua script to perform a specific task on Wikipedia or another Wikimedia Foundation project.

History

Sordid history. {{qif}}, ParserFunctions, Lua extension, wiki scripting language debated (JavaScript v. Lua), mw:Extension:WikiScripts, Tim writes Scribunto with initial support for Lua.

Discussed for years, Lua was installed in 2012 for testing on test2.wikipedia.org, with open invitation to all editors to experiment with developing Lua modules. Lua was installed on the English Wikipedia in February 2013, after testing on mediawiki.org and Wikimedia test wikis.

About Lua

See also Brad Jorsch's short presentation for a basic example of how to convert a wikitext template into a Lua module.

Lua is a scripting language which can be used to analyze data, calculate expressions, and format results using functions or object-oriented programming. Although some Lua scripts can be kept simple, for easy understanding, Lua allows complex structures including tables, dynamic functions, and associative arrays where index subscripts can be words as well as index numbers. Lua also supports recursion of re-nested functions, so care should be taken to avoid excessive complexity where other users would not understand how to maintain a Lua module. The following is the source code of the module used for the examples above.

<strong class="error"><span class="scribunto-error" id="mw-scribunto-error-12">Lua error in package.lua at line 80: module &#039;Module:CallAssert&#039; not found.</span></strong>

A sample of Lua is highlighted by tag "<syntaxhighlight lang="lua">...</syntaxhighlight>" placed around the Lua source code. To view some more complex examples of Lua, see article: "Lua (programming language)".

For instructions on how to use Lua within MediaWiki (and hence Wikipedia), see mw:Extension:Scribunto/Lua reference manual.

Unit testing

A few unit testing frameworks are available for Lua scripts on Wikipedia. These allow an editor to execute the module with a given set of inputs and verify that the expected outputs are produced. They are useful for rapidly detecting software regressions, where modifications to a script introduce new (or identify old) problems.

By convention, unit tests for a module like Module:Example are placed in Module:Example/testcases, and are executed on Module talk:Example/testcases.

Module:ScribuntoUnit and Module:UnitTests are widely used test frameworks. Category:Modules for test tools has a few other to review which may be interesting.

MediaWiki-specific features

Overall: Lua can only get input as text strings passed to the {{#invoke:}} and what can be fetched via mw.title.new(...):getContent() and frame:expandTemplate(). Lua output will not be preprocessed unless frame:preprocess() is explicitly called, meaning that template calls, parser functions, etc. in the output will not work correctly. Also, all Lua in the page is limited to 10 seconds CPU time (you can look in the source code of a rendered page to see how long a template or module took to parse). And relative to standard Lua, Scribunto's Lua lacks all sorts of functions (see mw:Extension:Scribunto/Lua reference manual § Differences from standard Lua).

Lua input limitations

Lua code in Scribunto is only run when the page is being parsed. Therefore, the only user input that Lua can receive is by page editing – it cannot create a box that calculates the square root of a number you type in, or recalculate a piece of the Mandelbrot set depending on which part of the parent set you click on. The input Lua can receive includes any transcludeable text page on Wikipedia. This does not include graphics files (not even .SVG files, although they are actually text, unless you cut and paste it onto a Wiki text page), the list of pages listed in a category, nor the contents of non-transcludeable special pages.

Wikitext

Transcluded Wikipedia headers frequently contain a hidden code such as "UNIQ5ae8f2aa414ff233-h-3--QINU" which may need to be stripped out in order for them to be parsed effectively.

Wikilinks using the pipe trick [[Wikipedia:Help| ]] won't work if returned as output – they need to be written explicitly as [[Wikipedia:Help|Help]]. Other pre-save transforms, such as replacing ~~~~ with signatures, will also fail to be processed. Template transclusions, parser function calls, and variable substitutions (i.e. anything with a {{...}}) will not be processed, nor will tags such as <ref> or <nowiki>. Use frame:extensionTag to add tags like <ref> or <syntaxhighlight> to output.

Labeling converted templates

Please place the {{lua}} template on the documentation subpage of all templates that use Lua. It will help to better communicate Lua usage and template conversions.

See also

• Special:PrefixIndex/Module: – tracking of Lua modules can be done by using Special:PrefixIndex
• Help:Lua debugging – a how-to guide about debugging Lua modules
• Module:Sandbox provides a pseudo-namespace for experimenting with Lua modules
• WP:Lua requests – requests for Lua-based templates or tasks
• Category:Lua-based templates – groups of Lua-based templates
• Category:Lua metamodules
• Manual:Coding conventions/Lua – standards to improve the readability of code through consistency
• mw:Extension:Scribunto/Lua reference manual and all Modules.
• Wikipedia:Advanced template coding