Lua templating/Getting started

This page covers some of the absolute basics for developing a simple lua template.

Basics

Before starting with lua templates, it is important to read up and get to know how to use regular wikitext templates, and preferably read/learn about lua in sites such as Wikibooks as well as reviewing Lua Reference manual.

Workspace

Lua templates are always stored in the Module namespace, and all work must always be saved there. For example, a module named helloworld would be stored in Module:Helloworld.

Creating a module

A module must always contain a table and a line containing a "return " for that table unless  it is a meta-module(see below). 

--Table
local p = {}
-- code goes here
return p

For a module to be invoked (or used in a page), it needs to have a function. However, this function must be part of the main table (e.g. invocable):

--Table
local invocable = {}

--can be invoked
function invocable.greet(frame)
   return "Live long and prosper"
end

-- can't be invoked 
function askname(frame)
   return "What's your name?"
end
return invocable

Execution time

Lua templates/modules in a page have a maximum time for execution currently set at 10 seconds. This means that lua modules within a page cannot take longer than 10 seconds to execute, or there will be an error.

Using input (parameters)

Input (or Template parameters) can be provided to a module during the invoke.

Syntax

{{#invoke:modulename|functioname|input1|input2|input3|...}}

Once the above code is executed a table (called frame) is created containing all those inputs, and it is passed to a function, and stored in a subtable called args (e.g. frame.args). For example, using the invoke below will make use of the module:

{{#invoke:invocable|greet|john}}

{{#invoke:invocable|greet|name=john}}

--Module:Invocable
--Table
local invocable = {}

function invocable.greet(frame)
   local name = frame.args[1] or frame.args["name"]

   return "Live long and prosper " ..name
end

return invocable

Output : Live long and prosper john

Explanation : Args is a list containing all parameters, args[1] refers to the first value, e.g. john, args["name"] accesses a named parameter "name".

Accessing template input

The invoke above cannot be used through a template because the values from a page, and a sub-page are kept separate. Those arguments can be accessed from a template by first retrieving the parent frame or table containing the arguments (i.e. frame.getParent()), and then using the sub-table (frame:getParent().args):

Template:Greet:

{{#invoke:invocable|greet}}

Module:Invocable:

--Table
local invocable = {}

function invocable.greet(frame)
   local parent = frame.getParent()
   local name = parent.args[1]
   local name2 = parent.args[2] or ""

   return "Live long and prosper :" ..name ..' '..name2
end

return invocable

Usage:

{{greet|Jack}}
Output:Live long and prosper : Jack 
{{greet|Jack|Jill}} 
Output:Live long and prosper : Jack  Jill

Example	Parameter	Template	Module	Output
{{greet|john}}	1	{{{1}}}	frame.getParent().args[1]	Live long and prosper john
{{greet|name=Spock}}	name	{{{name}}}	frame.getParent().args["name"]	Live long and prosper Spock
{{#invoke:invocable|greet|john}}	1		frame.args[1]	john
{{#invoke:invocable|greet|name=Worf}}	name		frame.args["name"]	Worf
{{#invoke:invocable|greet|jack|jill}}	1,2		frame.args[1], frame.args[2]	Live long and prosper : Jack Jill

Script errors

Whenever a module doesn't work properly it triggers a script error in a page. A good explanation of script errors is maintained by Wikipedia

Debug console

See Debug console.

Advanced

The advantage of lua is that it enables one to use external modules and tables that have been created by others. This reduces the need to reinvent the wheel, and more time can actually be spend creating new solutions.

Using other modules

To use libraries or modules one needs to import that library. This is done using the require method:

--Module:Libraries
local library = {}

function library.greet(frame)
   local invocable = require("Module:Invocable")

   return invocable.greet(frame)
end

return library

{{#invoke:library|greet|Zeus}}
Output:Live long and prosper Zeus

Note: The syntax is case sensitive so "Dev" ~= "dev".

Meta-Modules

These are modules that are not meant to be used in a page (e.g. {{#invoke), and don't necessarily have any functions that can be used in a page.

Using external tables

A external table can be retrieved in the same way as an external module, except that there is an extra method (mw.loadData) that loads it once per page, making it more efficient.

--Module:Tables
local tables = {'food','garden','relic'}

return tables

Usage:

--Module:showobjects
local p = {}

function p.show(frame)
   local objects = require("Module:Tables")
   --using loadData
   local objects2 = mw.loadData("Module:Tables")

   return objects[1] ..' & ' objects2[2]
end

return p

{{#invoke:showobjects|show}}
Output: "food & garden"

Global modules

Modules stored in Dev.wikia.com are called global modules. They work in a similar manner to modules stored in another wikia but they are accessed by any lua template. The difference lies only in the syntax used to obtain the modules:

local global_invocable = require("Dev:Invocable")
local global_Tables = mw.loadData("Dev:Tables")

See also

• Lua templating
• Lua templating/Debug console