Head, scripts and global attributes

Settings of the page itself

The first lines inside page:, before any element, describe the page and not something on it. title is the text on the browser tab, in bookmarks and in a search result. lang says which language the text is in, and the values are en, fa and ar. Screen readers choose their voice from it and browsers choose the right quotation marks and word breaks. dir sets the direction of the text: ltr or rtl, or the words left to right and right to left. favicon is the address of the small icon on the tab.

A file written in English starts with lang = "en" and dir = "ltr", and a Persian file with fa and rtl, so you write these two only when the page differs from its file. Any style property written at this level, such as background, color or font family, styles the whole page body.

page:
    title = "Corner Bakery"
    lang = "en"
    dir = "ltr"
    favicon = "/favicon.svg"
    background = "#fdf6ec"
    color = "#3b2a1a"
    font family = "Georgia, serif"
    padding = 28
    meta: name = "description" content = "Fresh bread every morning." end
    heading: size = 1 content = "Corner Bakery" end
    paragraph: content = "Fresh bread every morning." end
    paragraph: content = "The tab says Corner Bakery, the page language is English and the text runs left to right." end
end

The page does not show most of what you set here, so it is worth knowing what the compiler builds for you. Every page starts with <!doctype html>, then a head that holds <meta charset="utf-8">, which makes every letter of every language display correctly, and <meta name="viewport" content="width=device-width, initial-scale=1">, which tells phones to use the real screen width instead of pretending to be a wide desktop. You never have to write these two. Without a title, the tab says "Salam Page".

Meta tags, links and base

Some elements describe the page and are never drawn. You can write them anywhere inside page:, and the compiler moves them into the head: meta, head link, base and style.

meta carries a fact as a pair, name and content. A description is the summary under a search result. robots with noindex asks search engines to skip the page. theme-color colours the browser bar on a phone. For link previews in chat apps, the Open Graph protocol uses property instead of name: og:title, og:description, og:image. And http_equiv lets a tag behave like an HTTP header.

head link connects the page to another address and names the relation in rel. stylesheet loads CSS, icon sets an icon, canonical says which address is the real one when the same page can be reached in several ways, preload asks the browser to start downloading a font or image early, and alternate with a hreflang points to the translation. Its address is url. The name has two words so that it does not clash with link, the clickable link in the body.

base changes the address that all relative addresses start from. It can help a page that lives deep in a site, but it changes every relative link and file after it, so most pages leave it out.

The example below puts a description and a canonical link in its head, and a button reads them back with dom.Query, which finds an element by a CSS selector, and dom.GetAttr, which reads one of its attributes.

import dom

func readHead:
    html := dom.Query("html")
    dom.SetText(dom.ById("out-title"), "Title: " + dom.GetText(dom.Query("title")))
    dom.SetText(dom.ById("out-lang"), "Language: " + dom.GetAttr(html, "lang"))
    dom.SetText(dom.ById("out-desc"), "Description: " + dom.GetAttr(dom.Query("meta[name=description]"), "content"))
    dom.SetText(dom.ById("out-canon"), "Canonical: " + dom.GetAttr(dom.Query("link[rel=canonical]"), "href"))
end

page:
    title = "Reading the head"
    meta: name = "description" content = "A page that reads its own head." end
    head link: rel = "canonical" url = "https://example.com/head" end
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    button: click = readHead content = "Read the head" end
    paragraph: id = "out-title" content = "Title: ?" end
    paragraph: id = "out-lang" content = "Language: ?" end
    paragraph: id = "out-desc" content = "Description: ?" end
    paragraph: id = "out-canon" content = "Canonical: ?" end
end

Styles, scripts and noscript

Salam has style properties and event attributes for most work, but two elements are kept for raw text. style holds plain CSS in its content, for the things the properties do not cover: @keyframes, custom properties, rules for printing or for dark mode. With media the rules apply only when the query matches. Like meta, it moves to the head.

script holds JavaScript, either in content or in a file given with url. Unlike the elements above, a script stays where you write it, so put it after the elements it changes. If the code contains double quotes, write the string between backticks. Four attributes decide when a script from a file runs. A classic script runs the moment the browser reaches it, and stops the page until it is done. defer downloads the file while the page is read and runs it after the whole page is read, in order. async runs it the moment it has arrived, in any order, which suits an independent script such as statistics. type = "module" makes it an ES module and also waits for the page like defer. nomodule is the opposite switch: browsers that know modules skip it, so it is a fallback for very old ones. For a script from another site, add integrity (a hash of the file you expect) and crossorigin, so that a changed file cannot run on your page.

In the example two scripts write into the same paragraph. The module script is written first, but the classic script comes out first, because the module waits for the page.

page:
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    script: type = "module" content = "document.getElementById('log').textContent += ' module(waits for the page)'" end
    paragraph: content = "Order of events:" end
    paragraph: id = "log" content = "" end
    script: content = "document.getElementById('log').textContent += ' classic(runs at once)'" end
    noscript: content = "This page needs JavaScript to show the order." end
end

noscript is shown only when scripts are off or blocked. Give it a short message or a plain fallback, so that a visitor without JavaScript sees something useful instead of an empty space. In the preview above the script ran, so you cannot see it.

Templates, slots and shadow trees

A template is a block of elements that the browser reads but does not draw. Scripts copy it to build new pieces of a page. Give it shadowrootmode and it becomes something more useful: the private inside of its parent element, called a shadow tree. Styles from the rest of the page do not enter a shadow tree and its styles do not leak out, which makes it a good place for a self-contained widget.

The parent element is the host. Its own children are not drawn directly. They are shown in the slot elements of the shadow tree: a slot with a name takes the children whose slot attribute is that name, and an unnamed slot takes the rest. What you write inside a slot is shown only when nothing was given for it.

page:
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box:
        id = "card"
        template:
            shadowrootmode = "open"
            box:
                part = "frame"
                inline style = "border: 2px solid crimson; padding: 8px; border-radius: 8px"
                paragraph: inline style = "margin: 0 0 6px; color: crimson" content = "Inside the shadow" end
                slot: end
                slot: name = "note" content = "no note" end
            end
        end
        span: content = "Light child. " end
        span: slot = "note" content = "A named note" end
    end
    paragraph: content = "Outside the card." end
end

Here shadowrootmode = "open" lets scripts reach the tree through element.shadowRoot, and closed hides it. Three more attributes, shadowrootdelegatesfocus, shadowrootclonable and shadowrootserializable, are switches for focus, copying and saving, and are listed in the reference. A shadow tree can open a door for outside styles: give an inside element a part and the page can style it with ::part(name), and exportparts passes parts through one more level.

Attributes that every element has

A few attributes work on any element, whatever its name. You already know content, the text of the element. These are the ones to learn first.

id names one element, uniquely in the page. Links, labels and scripts find the element by it, and the compiler checks the ids that you write in the same page, so a wrong name in dom.ById is an error at build time and not a silent bug. class is a group name. Salam makes its own classes for your style properties and shares one class between elements with identical styles, so you rarely write one yourself. When you do, remember the rule: two elements with the same class and different style properties are an error (E136), because they would fight over the class. title is a tooltip, and it does not show on touch screens, so it is only a hint. inline style takes a string of CSS and overrides everything else, which makes it the last choice. hidden hides an element. With until-found the element is hidden but the browser can still find its text in a search and open it.

The next group is about how a visitor works with the element. tabindex = 0 puts an element in the Tab order, and -1 lets only a script focus it. accesskey gives it a shortcut key. contenteditable lets the visitor edit its content. draggable lets them drag it. inert turns an element and everything in it off. autofocus moves the cursor into an element when the page opens. The example below makes a note editable, reads it on every keystroke with an input handler, and shows it in a second paragraph.

import dom

func mirror:
    dom.SetText(dom.ById("status"), "The note says: " + dom.GetText(dom.ById("note")))
end

page:
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    paragraph: content = "Click the box and type. It is a normal element that you can edit." end
    box:
        id = "note"
        contenteditable = true
        spellcheck = true
        tabindex = 0
        padding = 12
        border = "2px dashed #64748b"
        border radius = 8
        content = "A short note"
        input = mirror
    end
    paragraph: id = "status" content = "The note says: A short note" end
end

For text input there are hints for phone keyboards: inputmode picks the keyboard, enterkeyhint labels the Enter key, and autocapitalize, autocorrect, spellcheck and writingsuggestions control what the keyboard and the browser do to the text. lang and dir work on a single element too, so an English name inside a Persian paragraph can carry its own direction. translatable = "no" asks translation tools to leave a word, such as a brand name, as it is.

Popovers without a script

A popover is a box that stays hidden until something opens it, and then floats above the page. The browser does all the work: no handler, no hidden toggling, no z-index. Give the box popover and an id. Give a button popover target with the same id. With popover = "auto" the box closes when the visitor clicks outside it or presses Escape, and it closes other auto popovers first. With manual it stays until something closes it. A second attribute, popover target action, says what the button does: toggle (the default), show or hide.

page:
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    button: popover target = "tip" content = "What is a popover?" end
    box:
        id = "tip"
        popover = "auto"
        padding = 14
        border = "1px solid #94a3b8"
        border radius = 8
        content = "A box that opens on top of the page. Click outside it or press Escape to close."
    end
end

ARIA: when the element is not enough

Screen readers and other assistive tools do not see your page. They read what the browser knows about each element: its role, its name, and its state. A button is known as a button, a list as a list, and nothing more is needed. The first rule of ARIA is to use the native element when one exists. ARIA attributes exist for the cases where you build something by hand or the state changes: role names what a plain box is (progressbar, status, tablist), and the attributes written aria and a name add a label, a state or a link between elements.

Three are used all the time. aria label gives a name to an element without visible text, such as a button that holds only an icon. aria hidden hides decoration from screen readers. aria expanded and aria controls say that a button opens or closes something, and which element it is. The browser does not keep aria expanded up to date. Your code must change it each time the state changes, as the example does.

import dom

mut shown := false

func toggleMenu:
    shown = not shown
    button := dom.ById("menu-button")
    if shown:
        dom.SetAttr(button, "aria-expanded", "true")
        dom.SetText(button, "Hide the menu")
    else:
        dom.SetAttr(button, "aria-expanded", "false")
        dom.SetText(button, "Show the menu")
    end
    dom.SetBool(dom.ById("menu"), "hidden", not shown)
end

page:
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    button:
        id = "menu-button"
        aria expanded = "false"
        aria controls = "menu"
        click = toggleMenu
        content = "Show the menu"
    end
    list:
        id = "menu"
        hidden = true
        item: content = "Home" end
        item: content = "Shop" end
        item: content = "Contact" end
    end
end

The handler flips a variable, sets aria-expanded to the new value with dom.SetAttr, changes the button text, and shows or hides the list with dom.SetBool on its hidden property. Any other ARIA attribute is written the same way: aria, a space, then the name, such as aria live or aria describedby.

Data attributes

Sometimes an element needs to carry a small fact for your own code: the id of a record, a price, a mode. For that, write data, a space and a name. data price = "12" becomes data-price in the HTML, and several words are joined with hyphens. Values are always strings. The attribute is invisible, CSS can match it with a selector like [data-mode='dark'], and a handler can read it with dom.GetAttr.

In the example all three buttons share one handler. It receives the event, asks dom.EventTarget which button was clicked, and reads that button's data. This is a good way to avoid writing one function for each button.

import dom

func showPlan(e: i64):
    plan := dom.EventTarget(e)
    dom.SetText(dom.ById("chosen"), dom.GetAttr(plan, "data-plan") + " plan, " + dom.GetAttr(plan, "data-price") + " dollars a month")
end

page:
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    box:
        display = flex
        gap = 8
        margin = "0 0 12px"
        button: data plan = "Basic" data price = "5" click = showPlan content = "Basic" end
        button: data plan = "Team" data price = "12" click = showPlan content = "Team" end
        button: data plan = "Company" data price = "40" click = showPlan content = "Company" end
    end
    paragraph: id = "chosen" content = "Choose a plan." end
end

Names such as mode, lang, view, only and id are listed in the reference, but only as examples of the pattern. Any name works. Write the name in English letters if a script has to read it.

Splitting a site into parts

A page that repeats the same box ten times, or ten pages that repeat the same footer, are signs that you need parts. Salam has three tools. A component is a named, reusable element with parameters. Inside it, content: end marks the place where the children written at the call go. A const above the page holds a value that is used in several places. repeat on an element writes it that many times. The example below uses all three.

const SHOP := "Corner Bakery"

component Panel(title):
    section:
        padding = 14
        margin = "0 0 12px"
        border = "1px solid #cbd5e1"
        border radius = 8
        heading: size = 3 margin = "0 0 6px" content = title end
        content: end
    end
end

page:
    title = SHOP
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    Panel: title = "Opening hours"
        paragraph: content = "Every day from 7 to 19." end
    end
    Panel: title = "Today's bread"
        list:
            item: repeat = 3 content = "A fresh loaf" end
        end
    end
    footer: content = SHOP + ", open every day" end
end

The third tool is include, which pulls another file into this one. Put your components, or a footer shared by every page, into a file of their own, and include it at the top of each page:

component Panel(title):
    section:
        heading: size = 3 content = title end
        content: end
    end
end

This is parts.salam, which contains only the component. Then every page that needs it says:

page:
    include = "parts.salam"
    Panel: title = "Hours"
        paragraph: content = "Every day from 7 to 19." end
    end
end

include

The path is relative to the file that includes the other one. An included file may hold components and also a page: block, whose elements are placed where the include is. Including a file that does not exist is a build error, and so is a file that includes itself.

Reference: head elements and global attributes

Below are the elements that live in the head or around it, then the global attributes, ARIA and data attributes. Every example is checked by the compiler. Persian names work in any file, and the Persian lessons use them.

page (Persian: صفحه)

The page block itself. It is not an HTML tag: it stands for the whole document. Directly inside it you can set title, lang, dir and favicon, any style property (it styles the page body), and then the elements of the page. The compiler writes the <head> for you, with charset and viewport already in it.

page:
    title = "Corner Bakery"
    lang = "en"
    background = "#fdf6ec"
    paragraph: content = "Fresh bread every morning." end
end

meta (Persian: متا; HTML: <meta>)

Information about the page that is not shown on it: a description for search engines, the colour of the browser bar, the text that a chat app shows when someone shares your link. It goes in the head by itself, wherever you write it. A meta has no children.

meta: name = "description" content = "Fresh bread every morning." end

Only inside: page · Void element, it cannot have children

head link (Persian: پیوند سر; HTML: <link>)

Connects the page to another file or address and says what the relation is. Style sheets, icons, fonts to load early, the canonical address of the page and the feed of a blog are all written this way. It is called head link to keep it apart from link, the clickable anchor that goes in the body. rel and url are required.

head link: rel = "stylesheet" url = "/site.css" end

Required: rel, url · Only inside: page · Void element, it cannot have children

base (Persian: پایه نشانی; HTML: <base>)

Sets the address that every relative link and file on the page is measured from, and the default target of links. There can be only one, and it changes every relative address after it, so use it with care.

base: url = "https://example.com/docs/" end

Only inside: page · Void element, it cannot have children

style (Persian: ظاهر سفارشی; HTML: <style>)

A block of raw CSS, for the rules that the style properties cannot express: @keyframes, custom properties (--brand), @media print and prefers-color-scheme. Its text is written as it is, so use the content attribute. Like meta, it moves to the head by itself.

style: content = "@keyframes pulse { to { opacity: 0.4 } }" end

script (Persian: اسکریپت سفارشی; HTML: <script>)

A piece of JavaScript, either written in content or loaded from a file with url. It stays where you write it, so put it after the elements it changes. Most Salam pages do not need it, because event attributes and the dom package cover the usual work, but it is the way to use a JavaScript library.

script: content = "document.title = 'Hello'" end

noscript (Persian: بدون اسکریپت; HTML: <noscript>)

Content that is shown only when scripts are switched off or blocked. Use it for a short message or a plain fallback, so a visitor without JavaScript is not left with a blank area.

noscript: content = "Turn on JavaScript to use the calculator." end

template (Persian: قالب; HTML: <template>)

A block that the browser reads but does not show. Scripts clone it to make new pieces of the page. With the shadowrootmode attribute it turns into a shadow root of its parent, which is a private tree of elements with its own styles. See the shadow DOM section above.

box:
    template:
        shadowrootmode = "open"
        paragraph: inline style = "color: teal" content = "I live in a shadow root" end
    end
end

slot (Persian: جایگاه; HTML: <slot>)

A hole inside a shadow tree where the host's own children are shown. Whatever you write inside the slot is the fallback, used when nothing is given for it.

box:
    template:
        shadowrootmode = "open"
        slot: content = "Nothing to show" end
    end
end

Global attributes: identity, text and style

These work on every element. The include attribute is explained in the section on splitting a site.

Global attributes: focus, editing and dragging

Global attributes: language and text input

Global attributes: microdata

Microdata marks up facts about a thing, so search engines can show them in rich results.

Global attributes: shadow trees and scripting

ARIA attributes

The role attribute comes first, then the ARIA attributes that Salam knows by name. All others follow the general pattern in the last row.

Data attributes

Try it yourself

• Add a description and an Open Graph og:title to one of your pages, then read them back with dom.Query and dom.GetAttr as in the head example.
• Change the aria example so that the button also toggles aria pressed. What does a screen reader announce, and which of the two attributes fits a menu button better?
• Make a component Card with a title and a content: end slot, use it three times with repeat and then move it to its own file with include.
• Put a second element with the class card and a different colour on the page, and read the error. Then fix it in two ways.