import{_ as i,a,b as n,ag as l}from"./chunks/framework.BcrMLAmg.js";const g=JSON.parse('{"title":"XML in Basalt","description":"","frontmatter":{},"headers":[],"relativePath":"guides/xml.md","filePath":"guides/xml.md","lastUpdated":1740474136000}'),t={name:"guides/xml.md"};function h(p,s,e,k,E,r){return n(),a("div",null,s[0]||(s[0]=[l(`

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

lua

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:

lua

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)

Event Handlers

There are two ways to define event handlers:

1. Reference a Function in Scope

lua

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

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

2. Using CDATA Sections

xml

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

Property Types

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

xml

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

Important Notes

Scope Variables
- All variables must be defined in the scope
- Functions referenced in events must be in scope
- Global variables are not automatically available
Event Handlers
- Always use CDATA for inline functions
- Function references must match exactly
- Events are case-sensitive
Expressions
- Use \${...} for scope access
- Expressions have access to scope variables
- Complex logic should be in Lua code

Example with Multiple Features

lua

local scope = {
    appTitle = "My App",
    colors = colors,
    handleSubmit = function(self)
        -- handle submission
    end
}

local xmlFile = fs.open("example.xml", "r")
main:loadXML(xmlFile.readAll(), scope)
xmlFile.close()

xml

<frame background="\${colors.gray}">
    <label 
        x="2" y="2"
        text="\${appTitle}"
    />
    <button 
        x="2" y="4"
        text="Submit"
        onClick="handleSubmit"
    />
    <button x="2" y="6">
        <onClick>
            <![CDATA[
                function(self)
                    self:getParent():remove()
                end
            ]]>
        </onClick>
    </button>
</frame>

`,21)]))}const o=i(t,[["render",h]]);export{g as __pageData,o as default};

XML in Basalt ​

Basic Usage ​

Working with Variables ​

Event Handlers ​

1. Reference a Function in Scope ​

2. Using CDATA Sections ​

Property Types ​

Important Notes ​

Example with Multiple Features ​