MosisService/portal/internal/web/docs/api/lua-api.md

Lua API Reference

Complete reference for the Mosis Lua API available to apps.

Global Objects

document

The current RML document. Use to query and modify UI elements.

-- Get element by ID
local elem = document:GetElementById("my-id")

-- Get elements by tag
local buttons = document:GetElementsByTagName("button")

-- Get elements by class
local cards = document:GetElementsByClassName("card")

event

Available in event handler functions. Contains information about the triggering event.

function handleClick(event)
    local target = event:GetCurrentElement()
    local eventType = event.type
end

Document Methods

GetElementById(id)

Returns the element with the specified ID, or nil if not found.

local element = document:GetElementById("username-input")
if element then
    element.inner_rml = "Found!"
end

GetElementsByTagName(tag)

Returns a table of all elements with the specified tag name.

local buttons = document:GetElementsByTagName("button")
for i, btn in ipairs(buttons) do
    btn:SetClass("styled", true)
end

GetElementsByClassName(class)

Returns a table of all elements with the specified class name.

local items = document:GetElementsByClassName("list-item")

CreateElement(tag)

Creates a new element with the specified tag name.

local div = document:CreateElement("div")
div.inner_rml = "New element"
parent:AppendChild(div)

CreateTextNode(text)

Creates a text node with the specified content.

local text = document:CreateTextNode("Hello")
element:AppendChild(text)

Element Properties

inner_rml

Gets or sets the inner RML content of an element.

-- Get content
local content = element.inner_rml

-- Set content (parses RML)
element.inner_rml = "<strong>Bold text</strong>"

id

Gets or sets the element's ID.

local id = element.id
element.id = "new-id"

style

Access to the element's inline styles.

element.style.width = "100dp"
element.style.backgroundColor = "#ff0000"
element.style.display = "none"

parent_node

Returns the parent element, or nil if none.

local parent = element.parent_node

first_child / last_child

Returns the first or last child element.

local first = container.first_child
local last = container.last_child

next_sibling / previous_sibling

Returns the next or previous sibling element.

local next = element.next_sibling

child_nodes

Returns a table of all child elements.

local children = element.child_nodes
for i, child in ipairs(children) do
    print(child.id)
end

tag_name

Returns the element's tag name (lowercase).

local tag = element.tag_name  -- "div", "button", etc.

offset_width / offset_height

Returns the rendered dimensions of the element.

local width = element.offset_width
local height = element.offset_height

offset_left / offset_top

Returns the position relative to the offset parent.

local x = element.offset_left
local y = element.offset_top

Element Methods

GetAttribute(name)

Returns the value of the specified attribute.

local value = input:GetAttribute("value")
local placeholder = input:GetAttribute("placeholder")

SetAttribute(name, value)

Sets the value of the specified attribute.

input:SetAttribute("placeholder", "Enter text...")
button:SetAttribute("disabled", "disabled")

RemoveAttribute(name)

Removes the specified attribute.

button:RemoveAttribute("disabled")

HasAttribute(name)

Returns true if the element has the specified attribute.

if button:HasAttribute("disabled") then
    print("Button is disabled")
end

SetClass(name, add)

Adds or removes a class from the element.

-- Add class
element:SetClass("active", true)

-- Remove class
element:SetClass("active", false)

IsClassSet(name)

Returns true if the element has the specified class.

if element:IsClassSet("selected") then
    print("Element is selected")
end

AppendChild(element)

Appends a child element.

local child = document:CreateElement("div")
parent:AppendChild(child)

InsertBefore(element, reference)

Inserts an element before the reference element.

parent:InsertBefore(newElement, referenceElement)

RemoveChild(element)

Removes a child element.

parent:RemoveChild(childElement)

Focus()

Sets focus to the element.

input:Focus()

Blur()

Removes focus from the element.

input:Blur()

Click()

Simulates a click on the element.

button:Click()

ScrollIntoView(alignToTop)

Scrolls the element into view.

element:ScrollIntoView(true)  -- align to top
element:ScrollIntoView(false) -- align to bottom

AddEventListener(event, handler)

Adds an event listener to the element.

button:AddEventListener("click", function(event)
    print("Clicked!")
end)

RemoveEventListener(event, handler)

Removes an event listener from the element.

local handler = function(event) print("Click") end
button:AddEventListener("click", handler)
button:RemoveEventListener("click", handler)

Event Object

type

The event type string (e.g., "click", "change").

if event.type == "click" then
    -- handle click
end

target_element

The element that originally triggered the event.

local target = event.target_element

current_element

The element the event handler is attached to.

local current = event.current_element

GetCurrentElement()

Returns the current element (same as current_element).

local elem = event:GetCurrentElement()

StopPropagation()

Stops the event from bubbling up to parent elements.

event:StopPropagation()

StopImmediatePropagation()

Stops the event and prevents other handlers on the same element.

event:StopImmediatePropagation()

parameters

Table containing event-specific parameters.

-- Mouse events
local x = event.parameters.mouse_x
local y = event.parameters.mouse_y
local button = event.parameters.button  -- 0=left, 1=right, 2=middle

-- Keyboard events
local key = event.parameters.key_identifier
local ctrl = event.parameters.ctrl_key
local shift = event.parameters.shift_key
local alt = event.parameters.alt_key

Navigation

navigateTo(screen)

Navigates to a screen, pushing to history.

navigateTo("settings")  -- loads assets/settings.rml
navigateTo("screens/profile")  -- loads assets/screens/profile.rml

goBack()

Navigates back to the previous screen.

goBack()

goHome()

Navigates to the home screen, clearing history.

goHome()

replaceTo(screen)

Replaces current screen without adding to history.

replaceTo("login")  -- no back navigation possible

canGoBack()

Returns true if there's a previous screen in history.

if canGoBack() then
    backButton.style.display = "block"
else
    backButton.style.display = "none"
end

Timers

setTimeout(callback, delay)

Executes callback once after delay (milliseconds). Returns timer ID.

local id = setTimeout(function()
    print("Executed after 1 second")
end, 1000)

clearTimeout(id)

Cancels a timeout.

local id = setTimeout(callback, 1000)
clearTimeout(id)

setInterval(callback, interval)

Executes callback repeatedly. Returns timer ID.

local id = setInterval(function()
    updateClock()
end, 1000)

clearInterval(id)

Cancels an interval.

clearInterval(intervalId)

Storage

Persistent key-value storage. Data persists between app sessions.

storage.set(key, value)

Stores a value. Value can be string, number, boolean, or table.

storage.set("username", "alice")
storage.set("settings", { darkMode = true, fontSize = 16 })
storage.set("highScore", 1000)

storage.get(key)

Retrieves a stored value, or nil if not found.

local username = storage.get("username")
local settings = storage.get("settings")
if settings then
    print(settings.darkMode)
end

storage.remove(key)

Removes a stored value.

storage.remove("tempData")

storage.clear()

Removes all stored values.

storage.clear()

storage.keys()

Returns a table of all storage keys.

local keys = storage.keys()
for i, key in ipairs(keys) do
    print(key)
end

HTTP (requires network permission)

http.get(url, callback)

Makes a GET request.

http.get("https://api.example.com/data", function(response)
    if response.ok then
        local data = json.decode(response.body)
        print(data.message)
    else
        print("Error: " .. response.status)
    end
end)

http.post(url, options, callback)

Makes a POST request.

http.post("https://api.example.com/submit", {
    headers = {
        ["Content-Type"] = "application/json",
        ["Authorization"] = "Bearer token123"
    },
    body = json.encode({ name = "test" })
}, function(response)
    print("Status: " .. response.status)
end)

http.request(options, callback)

Makes a custom HTTP request.

http.request({
    method = "PUT",
    url = "https://api.example.com/resource/1",
    headers = { ["Content-Type"] = "application/json" },
    body = json.encode({ updated = true }),
    timeout = 5000  -- milliseconds
}, function(response)
    print(response.status)
end)

Response Object

Property	Type	Description
ok	boolean	true if status is 200-299
status	number	HTTP status code
statusText	string	Status message
headers	table	Response headers
body	string	Response body

JSON

json.encode(value)

Converts a Lua value to a JSON string.

local str = json.encode({
    name = "Alice",
    items = {"a", "b", "c"},
    count = 3
})
-- '{"name":"Alice","items":["a","b","c"],"count":3}'

json.decode(str)

Parses a JSON string into a Lua value.

local data = json.decode('{"name":"Alice","age":25}')
print(data.name)  -- "Alice"
print(data.age)   -- 25

Logging

print(...)

Outputs to the debug console. Accepts multiple arguments.

print("Debug message")
print("Value:", someValue, "Count:", count)

console.log(...)

Alias for print().

console.log("Hello")

console.warn(...)

Logs a warning message.

console.warn("Something might be wrong")

console.error(...)

Logs an error message.

console.error("Something went wrong:", errorMessage)

Utility Functions

tostring(value)

Converts a value to a string.

local str = tostring(123)  -- "123"

tonumber(value)

Converts a value to a number.

local num = tonumber("123")  -- 123
local invalid = tonumber("abc")  -- nil

type(value)

Returns the type of a value as a string.

type("hello")  -- "string"
type(123)      -- "number"
type(true)     -- "boolean"
type({})       -- "table"
type(nil)      -- "nil"
type(print)    -- "function"

pairs(table)

Iterator for all key-value pairs.

for key, value in pairs(myTable) do
    print(key, value)
end

ipairs(table)

Iterator for array elements (integer keys starting from 1).

for index, value in ipairs(myArray) do
    print(index, value)
end

pcall(func, ...)

Calls a function in protected mode (catches errors).

local success, result = pcall(function()
    return json.decode(maybeInvalidJson)
end)

if success then
    print("Parsed:", result)
else
    print("Error:", result)
end

Standard Libraries

string

string.len(s)           -- length
string.upper(s)         -- uppercase
string.lower(s)         -- lowercase
string.sub(s, i, j)     -- substring
string.find(s, pattern) -- find pattern
string.gsub(s, pattern, repl) -- replace
string.match(s, pattern)      -- match pattern
string.format(fmt, ...)       -- format string
string.byte(s, i)       -- character code
string.char(...)        -- character from code
string.rep(s, n)        -- repeat string
string.reverse(s)       -- reverse string
string.split(s, sep)    -- split by separator (extension)
string.trim(s)          -- trim whitespace (extension)

math

math.abs(x)       -- absolute value
math.ceil(x)      -- round up
math.floor(x)     -- round down
math.round(x)     -- round to nearest (extension)
math.max(...)     -- maximum
math.min(...)     -- minimum
math.sqrt(x)      -- square root
math.pow(x, y)    -- power
math.exp(x)       -- e^x
math.log(x)       -- natural log
math.sin(x)       -- sine
math.cos(x)       -- cosine
math.tan(x)       -- tangent
math.asin(x)      -- arc sine
math.acos(x)      -- arc cosine
math.atan(x)      -- arc tangent
math.atan2(y, x)  -- arc tangent of y/x
math.deg(x)       -- radians to degrees
math.rad(x)       -- degrees to radians
math.random()     -- random 0-1
math.random(n)    -- random 1-n
math.random(m, n) -- random m-n
math.randomseed(x) -- set random seed
math.pi           -- 3.14159...
math.huge         -- infinity

table

table.insert(t, value)      -- append
table.insert(t, pos, value) -- insert at position
table.remove(t)             -- remove last
table.remove(t, pos)        -- remove at position
table.sort(t)               -- sort ascending
table.sort(t, comp)         -- sort with comparator
table.concat(t, sep)        -- join to string
table.unpack(t)             -- unpack to values (extension)
table.pack(...)             -- pack values to table (extension)

os

os.time()           -- current timestamp
os.time(t)          -- timestamp from table
os.date()           -- current date string
os.date(format)     -- formatted date
os.date(format, t)  -- formatted date for timestamp
os.date("*t")       -- date as table
os.difftime(t2, t1) -- time difference
os.clock()          -- CPU time used

Date format codes:

• %Y - 4-digit year
• %m - month (01-12)
• %d - day (01-31)
• %H - hour (00-23)
• %M - minute (00-59)
• %S - second (00-59)
• %a - abbreviated weekday
• %A - full weekday
• %b - abbreviated month
• %B - full month

See Also

• Lua Scripting Guide - Tutorials and examples
• Permissions Guide - Permission system
• UI Design Guide - RML/RCSS reference