XML in Basalt

Basalt provides an XML parser that lets you define your UI layout in a declarative way. This can make your code more readable and maintainable.

Basic Usage

local main = basalt.getMainFrame()

-- Load from file
local xmlFile = fs.open("myUI.xml", "r")
main:loadXML(xmlFile.readAll())
xmlFile.close()

-- Or directly as string
main:loadXML([[
    <frame width="30" height="10">
        <button text="Click me!" x="2" y="2"/>
    </frame>
]])

Working with Variables

The XML parser uses a scope system to access variables and functions. Any variables you want to use in your XML must be passed in the scope:

local scope = {
    title = "My App",
    buttonWidth = 10,
    handleClick = function(self)
        self:setText("Clicked!")
    end
}

main:loadXML([[
    <frame>
        <label text="${title}"/>
        <button width="${buttonWidth}" onClick="handleClick"/>
    </frame>
]], scope)

State Management

Basalt's state system integrates seamlessly with XML, allowing you to bind element properties to reactive states.

Inline State Binding

Use the State: suffix on any attribute to bind it to a state:

local scope = {}

main:loadXML([[
    <button 
        textState:clicked="Clicked me!"
        backgroundState:clicked="gray"
    />
]], scope)

This automatically calls setTextState("clicked", "Click me!") and setBackgroundState("clicked", "gray").

Nested State Configuration

For more complex state setups, use the <state> tag:

main:loadXML([[
    <button>
        <state name="hover">
            <background>lightGray</background>
            <foreground>black</foreground>
        </state>
        <state name="clicked">
            <background>blue</background>
            <foreground>white</foreground>
        </state>
    </button>
]], scope)

Custom XML Tags

You can register custom tags to create reusable components or handle special logic.

Registering a Custom Tag

local XMLParser = basalt.getXMLParser()

XMLParser.registerTagHandler("card", function(node, parent, scope)
    -- Create a frame container
    local card = parent:addFrame()
    card:setBackground(colors.gray)
    card:setSize(20, 10)
    
    -- Parse title attribute
    if node.attributes.title then
        local title = node.attributes.title:gsub("^\"", ""):gsub("\"$", "")
        local titleLabel = card:addLabel()
        titleLabel:setText(title)
        titleLabel:setPosition(2, 1)
    end
    
    -- Process children inside the card
    if node.children then
        for _, child in ipairs(node.children) do
            local childTag = child.tag:sub(1,1):upper() .. child.tag:sub(2)
            if card["add" .. childTag] then
                local element = card["add" .. childTag](card)
                element:fromXML(child, scope)
            end
        end
    end
    
    return card
end)

Using Custom Tags

main:loadXML([[
    <card title="User Info">
        <label x="2" y="3" text="Name: John"/>
        <label x="2" y="4" text="Age: 25"/>
    </card>
]])

Advanced Custom Tag Example

Create a reusable dialog component:

XMLParser.registerTagHandler("dialog", function(node, parent, scope)
    local dialog = parent:addFrame()
    dialog:setSize(30, 15)
    dialog:setBackground(colors.black)
    dialog:addBorder({left=true, right=true, top=true, bottom=true})
    dialog:center()
    
    -- Title bar
    if node.attributes.title then
        local title = node.attributes.title:gsub("^\"", ""):gsub("\"$", "")
        local titleBar = dialog:addLabel()
        titleBar:setText(title)
        titleBar:setPosition(2, 1)
        titleBar:setForeground(colors.white)
    end
    
    -- Close button
    local closeBtn = dialog:addButton()
    closeBtn:setText("X")
    closeBtn:setPosition(28, 1)
    closeBtn:setSize(2, 1)
    closeBtn:onClick(function()
        dialog:remove()
    end)
    
    -- Content area (process children)
    if node.children then
        for _, child in ipairs(node.children) do
            local childTag = child.tag:sub(1,1):upper() .. child.tag:sub(2)
            if dialog["add" .. childTag] then
                local element = dialog["add" .. childTag](dialog)
                element:fromXML(child, scope)
            end
        end
    end
    
    return dialog
end)

-- Usage
main:loadXML([[
    <dialog title="Settings">
        <label x="2" y="3" text="Volume:"/>
        <slider x="2" y="4" width="20"/>
        <button x="2" y="6" text="Save"/>
    </dialog>
]])

Unregistering Custom Tags

XMLParser.unregisterTagHandler("card")

Checking for Custom Tags

local handler = XMLParser.getTagHandler("card")
if handler then
    -- Handler exists
end

Event Handlers

There are two ways to define event handlers:

1. Reference a Function in Scope

local scope = {
    btnClick = function(self)
        self:setText("Clicked!")
    end
}

main:loadXML([[
    <button onClick="btnClick"/>
]], scope)

2. Using CDATA Sections

<button>
    <onClick>
        <![CDATA[
            function(self)
                self:setText("Clicked!")
            end
        ]]>
    </onClick>
</button>

Property Types

The XML parser automatically converts values based on the property type:

<button
    x="5"                <!-- Converted to number -->
    visible="true"       <!-- Converted to boolean -->
    background="blue"    <!-- Converted to colors.blue -->
    text="${title}"      <!-- Evaluated from scope -->
/>

Custom Attributes

Elements can store custom XML data that isn't a standard property:

main:loadXML([[
    <button customId="btn1" customData="test">
        <onClick>
            <![CDATA[
                function(self)
                    local custom = self:getCustomXML()
                    basalt.debug(custom.attributes.customId)
                end
            ]]>
        </onClick>
    </button>
]])

Custom attributes and children are stored in the customXML property and can be accessed via getCustomXML().

Important Notes

1. Scope Variables

   • All variables must be defined in the scope
   • Functions referenced in events must be in scope
   • Global variables are not automatically available

2. Event Handlers

   • Always use CDATA for inline functions
   • Function references must match exactly
   • Events are case-sensitive

3. Expressions

   • Use ${...} for scope access
   • Expressions have access to scope variables
   • Complex logic should be in Lua code

4. State Bindings

   • State names are automatically extracted from attribute names
   • Use propertyState:stateName format for inline binding
   • Nested <state> tags provide better organization

5. Custom Tags

   • Custom handlers have full access to parent, node, and scope
   • Must manually process child nodes if needed
   • Can return elements for further manipulation

Complete Example

local XMLParser = basalt.getAPI("xml")

-- Register custom card component
XMLParser.registerTagHandler("card", function(node, parent, scope)
    local card = parent:addFrame()
    card:setBackground(colors.gray)
    card:setSize(25, 8)
    
    if node.attributes.title then
        local title = node.attributes.title:gsub("^\"", ""):gsub("\"$", "")
        card:addLabel():setText(title):setPosition(2, 1)
    end
    
    if node.children then
        for _, child in ipairs(node.children) do
            local childTag = child.tag:sub(1,1):upper() .. child.tag:sub(2)
            if card["add" .. childTag] then
                local element = card["add" .. childTag](card)
                element:fromXML(child, scope)
            end
        end
    end
    
    return card
end)

-- Setup scope
local scope = {
    appTitle = "My App",
    colors = colors,
    hoverColor = colors.lightGray,
    handleSubmit = function(self)
        basalt.debug("Submitted!")
    end
}

-- Load XML
main:loadXML([[
    <frame background="${colors.gray}">
        <label 
            x="2" y="2"
            text="${appTitle}"
        />
        
        <card title="User Profile" x="2" y="4">
            <label x="2" y="2" text="Name:"/>
            <input x="8" y="2" width="15"/>
            
            <button 
                x="2" y="4" 
                text="Submit"
                onClick="handleSubmit"
                backgroundState:hover="${hoverColor}"
            />
        </card>
    </frame>
]], scope)