Lesson 24 of 49 · Layout language

Layout language: common for web and native

Salam's layout DSL is a declarative language for building interfaces: the same structure can produce web output (HTML/CSS/JS) or run as a native UI app drawn by Salam. This lesson covers what is common; web-specific details are in Layout on the web and native desktop details in Layout in native apps.

What is shared

In both targets you describe the interface as a tree of elements. A page: block (or صفحه:) is the root, each element opens with its name and a colon and closes with end (پایان), and attributes/styles are written as name = value. Element text is usually its content, elements can nest, and the structure stays readable.

Top-level page settings such as title, lang, and dir belong to the page. English files default to left-to-right; Persian files default to right-to-left. You can set them explicitly when needed.

layout-page.salam
page:
    title = "My app"
    lang = "english"
    dir = "left to right"
    header:
        background = #2563eb
        color = "white"
        padding = "24px"
        heading: size = 1 content = "Welcome to Salam" end
    end
    box:
        padding = "20px"
        paragraph: content = "This page was built from Salam code." end
    end
end

Simpler value syntax

In layout/style values you can now write many values in a shorter form: percentages like 50% and 100% without quotes, hex colors like #0f766e without quotes, units such as 12px/1rem/200ms in value contexts, and value lists/groups where supported. For example:

box:
    width = 50%
    max width = 480
    padding = 16, 24
    background = #f8fafc
    color = #0f766e
    border = 1, solid, #0f766e
end

Bare numbers are typically treated as pixels for length-like properties. Strings (such as text content, URLs, or specific textual values) still use quotes.

Elements, attributes, and styles

Element and property names are readable (English and Persian aliases). Common elements include box/div, paragraph, heading, link, image, list/item, form, input, and button. Boolean attributes like required = true are meaningful, while false is usually omitted. CSS properties are written alongside elements as attributes.

layout-form.salam
page:
    title = "Contact us"
    nav:
        link: url = "/" content = "Home" end
        link: url = "/blog" content = "Blog" end
        link: url = "https://github.com/SalamLang/Salam" target = "new" content = "Source" end
    end
    image: url = "/logo.png" alt = "Salam logo" end
    form:
        id = "contact"
        label: for = "email" content = "Your email" end
        input: id = "email" type = "email" name = "email" placeholder = "you@example.com" required = true end
        label: for = "message" content = "Message" end
        input: id = "message" type = "text" name = "message" end
        button: type = "submit" content = "Send" end
    end
    list:
        item: content = "We answer within a day" end
        item: content = "No account needed" end
    end
end

Use constants, global rules, and components to keep styles consistent and avoid repetition:

layout-style.salam
const ACCENT := "#0f766e"
const GAP := 16

page:
    title = "Pricing"
    global: box sizing = "border-box" end
    global: selector = "body" margin = "0" font family = "sans-serif" end
    section:
        display = "flex"
        gap = GAP + "px"
        padding = GAP * 2 + "px"
        box:
            border = 1px, solid, #ddd
            border radius = "12px"
            padding = GAP + "px"
            heading: size = 2 content = "Free" end
            paragraph: content = "For trying things out" end
        end
        box:
            border = 2px, solid + ACCENT
            border radius = "12px"
            padding = GAP + "px"
            heading: size = 2 content = "Pro" color = ACCENT end
            button:
                content = "Upgrade"
                background = ACCENT
                color = "white"
                hover background = #115e59
                cursor = "pointer"
            end
        end
    end
end

Components and reuse

A component (بخش) is a reusable piece of UI with parameters, used like a custom element. content: end marks the slot where nested children are inserted. To share components across files, include them (e.g. include = "parts.salam", path relative to the including file).

layout-component.salam
component Plan(name, price):
    box:
        border = 1px, solid, #ddd
        border radius = "12px"
        padding = "16px"
        heading: size = 2 content = name end
        paragraph: content = "$" + price + " a month" end
        content: end
    end
end

page:
    title = "Plans"
    Plan: name = "Basic" price = 4 end
    Plan: name = "Pro" price = 9
        list:
            item: content = "Private projects" end
            item: content = "Email support" end
        end
    end
end

Parameterized pages and dynamic structure

A layout/page can take parameters (e.g. layout Card(name: str, score: int):) and be rendered with runtime values. Inside parameterized layouts you can use conditions (if/else) and loops (each) to build dynamic UI. Parameter text is handled safely when inserted into the page.

layout-runtime.salam
page Card(name: str, score: int):
    title = "Card " + name
    heading: size = 2 content = name end
    if score >= 50:
        paragraph: content = "pass" end
    else:
        paragraph: content = "fail" end
    end
end

func main:
    println Card("Ali", 70)
end
Output<!doctype html><html lang="en" dir="ltr"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Card Ali</title></head><body><h2>Ali</h2><p>pass</p></body></html>
layout-inbox.salam
component Badge(text: str):
    span: content = text background = #fde68a end
end

page Inbox(user: str, subjects: Vector<str>):
    title = "Inbox of " + user
    heading: size = 1 content = "Hello, " + user end
    if subjects.IsEmpty():
        paragraph: content = "No new messages" end
    else:
        paragraph: content = "Unread: " + subjects.Len() end
        list:
            each i, s in subjects:
                item: content = (i + 1) + ". " + s end
            end
        end
    end
end

func main:
    mut subjects := Vector {} as Vector<str>
    defer subjects.Free()
    subjects.Push("Meeting at 10")
    subjects.Push("<b>FREE</b> prize & more")
    println Inbox("Sara", subjects)
    println Badge("new")
end
Output<!doctype html><html lang="en" dir="ltr"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Inbox of Sara</title></head><body><h1>Hello, Sara</h1><p>Unread: 2</p><ul><li>1. Meeting at 10</li><li>2. &lt;b&gt;FREE&lt;/b&gt; prize &amp; more</li></ul></body></html> <style>.badge-a{background:#fde68a}</style><span class="badge-a">new</span>

Two targets: web and native

The same DSL can target different runtimes, with different outputs and capabilities:

  • Web: build with salam page build to produce HTML/CSS/JS for browsers, with DOM/events and web/server integration. See Layout on the web.
  • Native (desktop): run/build with salam run --ui=native or salam build --ui=native to open a native window rendered by Salam's UI engine (no browser). See Layout in native apps.

For desktop apps that host web UI inside a native window (WebView, like Tauri/Electron model), see gui.webview; that is a different path from native DSL rendering.

Compile-time checks

The compiler checks element/attribute names and many values and reports helpful errors. This catches mistakes early for both web and native targets. For parameterized pages and untrusted input, follow the safety/validation rules of the chosen runtime (especially web/server paths).

Continue with Layout on the web for build/serve/browser details, or Layout in native apps for --ui=native and desktop behavior. Later lessons cover elements, CSS, events, and complete web projects in depth.