Lua/Frame Object

Lua modules based on the Scribunto/Lua extension are stored in resource pages using the Module: namespace. Each module uses a table to hold functions and variables, and that containing table is returned at the end of the module code.^[1] This lesson will show you how to use the Lua Frame object in your scripts.

Prerequisites

This lesson assumes you have already completed the Tables lesson.

Create a Lua Script that Uses the Frame Object

To create a Lua script that uses the Frame object:

Navigate to Module:Sandbox.
Clear all existing code.
It's a sandbox. Everyone is free to play in the sandbox. But if you find another user is actively editing the sandbox at the same time, you may also use Module:Sandbox/Username, where Username is your Wikiversity username.
Add the following code and save the page:

local p = {}

local function tableToString(t)
    local key
    local value
    local result
 
    result = ''
 
    for key, value in pairs(t) do
        if (tonumber(key) ~= nil) then
            result = result .. ':table[' .. key .. '] is ' .. value .. '\n' 
        else
            result = result .. ':table[\'' .. key .. '\'] is ' .. value .. '\n' 
        end
    end
 
    return result
end
 
function p.args(frame)
    return ';args\n' .. tableToString(frame.args)
end

function p.callParserFunction(frame)
    return ';callParserFunction\n:' .. frame:callParserFunction('#time', 'Y-m-d H:i:s') .. '\n'
end

function p.expandTemplate(frame)
    return ';expandTemplate\n:' .. frame:expandTemplate({title = 'Template:Sandbox', args = {'arg1', 'arg2'}}) .. '\n'
end

function p.extensionTag(frame)
    return ';extensionTag\n:' .. frame:extensionTag('nowiki', '[[text]]', {}) .. '\n'
end

function p.getParent(frame)
	frame = frame:getParent()
    return ';getParent\n:' .. frame:getTitle() .. '\n'
end

function p.getTitle(frame)
    return ';getTitle\n:' .. frame:getTitle() .. '\n'
end

return p

Test Your Lua Script

To test your Lua script:

Navigate to either the Module_talk:Sandbox page, the Wikiversity:Sandbox page, or your own user or sandbox page.
Add the following code and save the page:

{{#invoke:Sandbox|args|These|are|arg3=frame args.}}
{{#invoke:Sandbox|callParserFunction}}
{{#invoke:Sandbox|expandTemplate}}
{{#invoke:Sandbox|extensionTag}}
{{#invoke:Sandbox|getParent}}
{{#invoke:Sandbox|getTitle}}

The result should be similar to:

args

table[1] is These

table[2] is are

table['arg3'] is frame args.

callParserFunction

2013-12-20 02:20:13

expandTemplate

2

extensionTag

[[text]]

getParent

Module talk:Sandbox

getTitle

Module:Sandbox

Understand Your Lua Script

To understand your Lua script:

local function tableToString(t) declares a local function named tableToString that accepts a single parameter t, which is the table to be converted to a string.
See Lua/Tables for more information.
function p.args(frame) declares a function named args which accepts a single parameter frame, which is the interface to the calling object.
- frame.args is a table of arguments passed to the function.
- Positional arguments are accessed by numeric position.
- Named arguments are accessed by name.
frame:callParserFunction('#time', 'Y-m-d H:i:s') calls the parser function #time, passing the string literal 'Y-m-d H:i:s' to display the current time.
frame:expandTemplate({title = 'Template:Sandbox', args = {'arg1', 'arg2'}}) calls the Template:Sandbox template, passing a table of parameter arguments and returns the result.
frame:extensionTag('nowiki', '[[text]]', {}) tags the given text to control processing when the text is returned to the calling object.
frame:getParent() returns the parent of the calling object, or in this case the page that invoked the module.
frame:getTitle() returns a string containing the title of the frame.

Conclusion

Congratulations! You've now created, tested, and understood a Lua script that uses the Frame object. Return to the main Lua page to learn about other Lua code libraries.