State, the DOM and timers
The last three lessons showed single events. A real page puts them together: it remembers something, reacts to a click or a key, and then updates what the reader sees. This lesson teaches that loop with small complete pages, a counter, a todo list, tabs, a stopwatch, a quiz, and the dom functions each one needs.
- State lives in variables
- Finding elements, reading and writing them
- State, styles and attributes
- Making and removing elements
- What an event tells you
- Timers and frames
- Remembering after the page closes
- Alerts, questions and prompts
- Components, repeat and handlers
- Components that remember: variables and state
- Components talking to each other
- Putting it together: a quiz
- When it does not work
- Try it yourself
State lives in variables
An interactive page is a loop of three steps: something happens, the program changes what it remembers, and the page is redrawn from what the program remembers. What the program remembers is its state. In Salam the state of a page is a handful of top level mut variables above the page: block. Handlers change them, and one function, usually called draw or show, copies them into the page.
import dom
mut count := 0
func draw:
shown := dom.ById("value")
dom.SetText(shown, "" + count)
if count < 0:
dom.SetStyle(shown, "color", "#dc2626")
else:
dom.SetStyle(shown, "color", "#0f172a")
end
end
func more:
count++
draw()
end
func fewer:
count--
draw()
end
func start_over:
count = 0
draw()
end
page:
title = "Counter"
font = system, sans margin = 1.5rem
box:
max width = 16rem margin = 0, auto padding = 20 text align = center border = 1px, solid, #e2e8f0 radius = 14
heading: id = "value" size = 1 content = "0" font size = 4rem margin = 0, 0, 12px, 0 end
button: padding = 8px, 18px hover background = #e0e7ff font size = 1.1rem border = 1px, solid, #cbd5e1 radius = 8 background = #f8fafc cursor = pointer id = "minus" click = fewer content = "-1" end
button: padding = 8px, 18px hover background = #e0e7ff font size = 1.1rem border = 1px, solid, #cbd5e1 radius = 8 background = #f8fafc cursor = pointer id = "plus" click = more content = "+1" margin = 0, 8px end
button: padding = 8px, 18px hover background = #e0e7ff font size = 1.1rem border = 1px, solid, #cbd5e1 radius = 8 background = #f8fafc cursor = pointer id = "zero" click = start_over content = "Reset" end
end
endLook at how the example is split. count is the only place that knows the number. fewer, more and start_over change it and call draw, and draw is the only function that touches the page. When something looks wrong on screen you know where to look: either the state is wrong or the drawing is. The red colour of a negative number is a rule inside draw, so it is applied every time, whichever handler ran.
The helpers come from import dom, and the whole list is on the dom package page. This lesson teaches the page side: which helper to reach for and how the parts fit together.
A page program does not need a main and nothing calls one. If you add one, the compiler starts counting only what main calls, and your handlers are reported as unused functions (error E066). Put the work in handlers, and see the storage section for code that must run when the page opens.
Finding elements, reading and writing them
To change an element you first need a handle on it. dom.ById("value") returns the element with that id, and the compiler checks the id for you: if no element of the same page has it, the build stops with error E138, so a typing mistake is found before the page ever runs.
E138: no element with id 'result2' in this file's layout
The check only sees ids written as plain text. An id built while the page runs, such as dom.ById("votes-" + name), is not checked, so a typing mistake there shows up as an error in the browser console instead. When there is no id to use, dom.Query(".note") returns the first element that matches a CSS selector, and dom.QueryAll("#books li") returns all of them as a list. Read a list with dom.CountOf(list) and dom.ItemAt(list, i), counting from 0.
With a handle you can read and write. dom.SetText(el, "...") and dom.GetText(el) deal with text, and dom.SetValue(el, "...") and dom.GetValue(el) with what is typed in a field. The character counter below reads the box on every input event, shows the count and the share of the limit, and switches the button off while the note is empty or too long.
import dom
const LIMIT := 80
func measure:
used := dom.GetNum(dom.ById("note"), "textLength") as i64
dom.SetText(dom.ById("used"), "" + used + " / " + LIMIT)
if used > LIMIT:
dom.SetStyle(dom.ById("used"), "color", "#dc2626")
dom.SetStyle(dom.ById("bar"), "width", "100%")
dom.SetStyle(dom.ById("bar"), "background", "#dc2626")
else:
dom.SetStyle(dom.ById("used"), "color", "#475569")
dom.SetStyle(dom.ById("bar"), "width", "" + used * 100 / LIMIT + "%")
dom.SetStyle(dom.ById("bar"), "background", "#4f46e5")
end
dom.SetBool(dom.ById("post"), "disabled", used == 0 or used > LIMIT)
end
page:
title = "Character counter"
font = system, sans margin = 1.5rem max width = 28rem
text area: id = "note" input = measure rows = 3 placeholder = "Write a short note" width = 100% padding = 10 font size = 1rem font = inherit radius = 8 border = 1px, solid, #cbd5e1 end
box: height = 6 background = #e2e8f0 radius = 3 margin = 6px, 0
box: id = "bar" height = 100% width = 0% background = #4f46e5 radius = 3 transition = 0.15s end
end
box: layout = row justify = between align = center
span: id = "used" content = "0 / 80" color = #475569 end
button: id = "post" disabled = true content = "Post" padding = 6px, 16px end
end
endThe count comes from dom.GetNum(field, "textLength"), a property the browser keeps for a text area, and not from text.len(). In the browser a Salam string counts UTF-8 bytes, so the Persian word سلام would count as 8. GetNum, GetStr, GetBool and GetProp read any property of an element, and they are how you reach whatever the other helpers do not cover.
A live filter needs no loop over elements, because the list is drawn from a vector and the search text, so the rows that match are the rows that exist. The input handler writes the text into a variable. An each over the books, with an if inside it, lets through only the titles that contain the text, a small function counts them, and a message appears when the count is zero.
func shelf(): Vector<str>:
mut books := Vector {} as Vector<str>
books.Push("The Little Prince")
books.Push("Pride and Prejudice")
books.Push("The Hobbit")
books.Push("Little Women")
books.Push("Moby Dick")
books.Push("Great Expectations")
ret books
end
func matches(title: str, needle: str): bool:
ret title.Lower().Includes(needle.Lower())
end
func found(books: Vector<str>, needle: str): int:
mut count := 0
repeat books.Len() in i:
if matches(books.Get(i), needle):
count++
end
end
ret count
end
func total(books: Vector<str>): int:
ret books.Len()
end
component Filter:
books := shelf() as Vector<str>
query := ""
box:
font = system, sans
margin = 24
max width = 416
input:
id = "q"
type = search
width = fill
padding = 10
font size = 16
radius = 8
border = 1, solid, #cbd5e1
placeholder = "Search the shelf"
input = (v: str): query = v end
end
paragraph: id = "found" color = #475569 margin = 6, 0 content = found(books, query) + " of " + total(books) end
list:
id = "books"
padding = 0
each title in books:
if matches(title, query):
item: key = title padding = 10, 12 margin = 6, 0 background = #f1f5f9 radius = 8 content = title end
end
end
end
if found(books, query) == 0:
paragraph: id = "none" color = #b45309 content = "Nothing on the shelf matches." end
end
end
end
page:
title = "Filter"
Filter: end
endWhen the rows are made by hand, a list from QueryAll is a snapshot. Rows added later are not in it, so ask again each time.
One more way to write is dom.SetHtml(el, "..."). It makes the browser read the string as HTML, so it can build a whole fragment in one call, and dom.SetHtml(el, "") empties an element. That is also the danger. A name typed by a visitor and put in with SetHtml is run as HTML, and a name such as <img src=x onerror=...> becomes a program. Text that came from outside always goes in with SetText, which shows every character as it is:
func echo:
dom.SetText(dom.ById("shown"), dom.GetValue(dom.ById("name")))
end
page:
input: id = "name" input = echo placeholder = "Your name" end
paragraph: id = "shown" end
end
A missing element is not an empty value. dom.ById and dom.Query give JavaScript null for an element that is not there, and using it stops the handler with an error in the console. When an element may be absent, ask first with dom.Exists("banner"), as in if dom.Exists("banner"): dom.Remove(dom.ById("banner")) end.
State, styles and attributes
There are three ways to change how an element looks or behaves, and the order of preference is the order below. First, state: declare a variable with := in a component, change it in a handler, and write the style that goes with it in an if inside the element. The page says what each state looks like, the handler only says which state it is, and the two stay apart. The theme switch below holds one variable, night, and every colour on the page follows it.
component Theme:
night := false
box:
font = system, sans
padding = 24
min height = 192
background = #f8fafc
color = #0f172a
transition = 300ms
if night:
background = #0f172a
color = #e2e8f0
end
box:
max width = 416
padding = 20
background = white
border = 1, solid, #e2e8f0
radius = 14
if night:
background = #1e293b
border = 1, solid, #334155
end
heading: size = 2 content = "Good evening" margin = 0, 0, 8, 0 end
paragraph: content = "One state variable changes every colour on the page." end
button:
id = "flip"
padding = 8, 16
radius = 8
border = 1, solid, #6366f1
background = #6366f1
color = white
cursor = pointer
click = (): night = not night end
content = night ? "Use the day theme" : "Use the night theme"
end
end
end
end
page:
title = "Theme"
Theme: end
endSecond, styles: dom.SetStyle(el, "width", "40%") sets one CSS property of one element, with its CSS name (background-color, not backgroundColor), and an empty value removes it again. It is the right tool for a value you work out while running, such as the width of the bar in the character counter. dom.GetStyle(el, "display") returns the value the browser is using now, for example none for a hidden element.
Third, attributes: dom.SetAttr(el, "aria-expanded", "true") and dom.GetAttr(el, "aria-expanded") read and write HTML attributes as text. They matter most for the accessibility attributes, because a screen reader reads aria-expanded and ignores the style. In a component you write the attribute from the same variable: this accordion keeps both in step, because open shows or hides the panel and also sets aria expanded.
component Fold(name: str, title: str):
open := false
box:
border = 1, solid, #e2e8f0
radius = 10
overflow = hidden
margin = 0, 0, 8, 0
button:
id = "h-" + name
width = fill
text align = start
padding = 12, 14
font size = 16
font weight = 400
border = 0
background = #f1f5f9
cursor = pointer
hover:
background = #e0e7ff
end
if open:
font weight = 700
end
aria expanded = open ? "true" : "false"
click = (): open = not open end
content = title
end
if open:
box:
padding = 0, 14, 12, 14
content: end
end
end
end
end
page:
title = "Accordion"
box:
font = system, sans
margin = 24
max width = 480
Fold: name = "ship" title = "How long does delivery take?"
paragraph: content = "Two to four working days inside the country." end
end
Fold: name = "back" title = "Can I return an item?"
paragraph: content = "Yes, within thirty days, if it is unused." end
end
Fold: name = "pay" title = "Which payment methods do you accept?"
paragraph: content = "Cards and bank transfer." end
end
end
endThe accordion is a component, and every fold keeps its own open. The section on reuse comes back to that. The browser also has the details element for exactly this job, with no script at all (see the lesson on page structure). The accordion is here because it shows state, styles and attributes working together.
Some things are not attributes but properties of the element: checked, disabled, value. The attribute only gives the starting value, and the property is the live one. Read and write those with dom.GetBool and dom.SetBool:
func agree_changed:
ticked := dom.GetBool(dom.ById("agree"), "checked")
dom.SetBool(dom.ById("join"), "disabled", not ticked)
end
page:
input: id = "agree" type = checkbox change = agree_changed end
label: for = "agree" content = "I accept the rules" end
button: id = "join" disabled = true content = "Join" end
end
Tabs put state and attributes together. One variable, sel, says which tab is chosen. Every tab gets a flag from it, styles itself with an if and sets aria selected, and one if chain shows the panel that goes with it.
component Tab(label: str, active: bool, pick):
button:
padding = 10, 18
border bottom = 3, solid, transparent
background = white
font size = 16
font weight = 400
cursor = pointer
hover:
background = #f1f5f9
end
if active:
border bottom = 3, solid, #4f46e5
font weight = 700
end
aria selected = active ? "true" : "false"
click = pick
content = label
end
end
component Tabs:
sel := 0
box:
font = system, sans
margin = 24
max width = 512
box:
layout = row
role = tablist
border bottom = 1, solid, #e2e8f0
Tab: label = "Overview" active = sel == 0 pick = (): sel = 0 end end
Tab: label = "Recipe" active = sel == 1 pick = (): sel = 1 end end
Tab: label = "Reviews" active = sel == 2 pick = (): sel = 2 end end
end
if sel == 0:
box: padding = 14, 4 content = "A flat bread baked on a hot stone in about four minutes." end
else if sel == 1:
box: padding = 14, 4 content = "Flour, water, salt and a spoon of yeast. Rest the dough for an hour." end
else:
box: padding = 14, 4 content = "Four and a half stars from 212 readers." end
end
end
end
page:
title = "Tabs"
Tabs: end
endWhen two things have to change together, derive both from one variable, as the tabs and the panel do. If the tab buttons and the panels were updated in different places, sooner or later one of them would be forgotten.
Making and removing elements
A page often has to grow: a new row in a list, a new message. In a component you do not make the element yourself: the list is a vector, items.Push(text) adds a task and the each over items draws its row, and taking the task out of the vector takes the row away. The todo list below does both.
import dom
func total(items: Vector<str>): int:
ret items.Len()
end
component Task(label: str, finish):
held := label
box:
layout = row
justify = between
align = center
padding = 8, 12
margin = 6, 0
background = #f1f5f9
radius = 8
paragraph: margin = 0 content = label end
button:
border = 0
background = #e0e7ff
radius = 6
padding = 4, 10
cursor = pointer
click = (): finish(held) end
content = "Done"
end
end
end
component Tasks:
items := Vector {} as Vector<str>
draft := ""
box:
font = system, sans
margin = 24
max width = 416
form:
id = "new"
layout = row
gap = 8
submit = (e: i64):
dom.PreventDefault(e)
if draft.Len() > 0:
items.Push("" + draft)
draft = ""
end
end
input:
id = "name"
grow = 1
padding = 8
font size = 16
value = draft
placeholder = "What needs doing?"
input = (v: str): draft = v end
end
button: id = "add" type = submit padding = 8, 16 border = 0 background = #4f46e5 color = white radius = 8 cursor = pointer content = "Add" end
end
list:
padding = 0
each task in items:
item:
key = task
Task: label = task
finish = (who: str):
repeat items.Len() in i:
if items.Get(i) == who:
items.RemoveAt(i)
break
end
end
end
end
end
end
end
paragraph: id = "left" color = #475569 content = total(items) + " to do" end
end
end
page:
title = "To do"
Tasks: end
endRead the submit handler first. It checks the text, pushes it on items and clears the field, and that is all: the each over items draws the row. The count is not a variable either: total is a function of items, so it can never disagree with the rows.
Each row is a small component with its own Done button. A row cannot change the list it is part of, so the page passes it a function, finish, and the row calls it with its text. The function finds the task in items and removes it, and the row goes with it. dom.Create, dom.Append and dom.Remove still exist, for an element that no component can make, and dom.OnEvent(el, "click", handler) adds a handler to an element made that way; when the handler must see the event, use dom.OnEventE and a lambda with an i64 parameter, such as (e: i64): hello(e) end.
The form of the example matters too. The field and the button sit in a form with a submit handler, so the Enter key adds a task as well as the button, with no key handling written. The handler calls dom.PreventDefault(e), because otherwise the browser would send the form and reload the page.
Text from a user goes into a row as its content, which is always shown as text. If you do build an element by hand, put the text in with dom.SetText, never SetHtml, for the reason given above.
What an event tells you
A handler declared with an i64 parameter receives the event, and a few helpers read it. dom.EventTarget(e) is the element that was hit, dom.EventX(e) and dom.EventY(e) the position of the pointer, dom.EventKey(e) the key, dom.PreventDefault(e) cancels what the browser would do next and dom.StopPropagation(e) stops the event reaching the elements above. Each has its lesson: mouse events, keyboard and forms, drag, drop and touch and media and the rest.
EventTarget is what lets one handler serve many elements that have no state of their own, for example rows made with dom.Create. When each element can be a component, give it its own state instead, as the seat picker below does: eight seats, each with its own taken, and a function that the page passes down so that every seat can say whether it was taken or given up. The page adds the answers up.
component Seat(change):
taken := false
button:
width = 44
height = 44
border = 2, solid, #94a3b8
radius = 8, 8, 14, 14
background = white
cursor = pointer
hover:
border = 2, solid, #4f46e5
end
if taken:
background = #4f46e5
border = 2, solid, #4f46e5
end
aria label = "Seat"
click = ():
taken = not taken
change(taken ? 1 : -1)
end
end
end
component Seats:
chosen := 0
box:
font = system, sans
margin = 24
box:
layout = grid
columns = 44, 44, 44, 44
gap = 10
Seat: change = (d: int): chosen += d end end
Seat: change = (d: int): chosen += d end end
Seat: change = (d: int): chosen += d end end
Seat: change = (d: int): chosen += d end end
Seat: change = (d: int): chosen += d end end
Seat: change = (d: int): chosen += d end end
Seat: change = (d: int): chosen += d end end
Seat: change = (d: int): chosen += d end end
end
paragraph: id = "summary" color = #475569 content = chosen + " of 8 seats chosen" end
end
end
page:
title = "Seats"
Seats: end
endTimers and frames
Three helpers run a function later. dom.SetTimeout(fn, ms) runs it once after that many milliseconds. dom.SetInterval(fn, ms) runs it again and again. Both return a number, and dom.ClearTimeout(id) and dom.ClearInterval(id) cancel the timer with that number. Keep the number in a top level variable declared mut id := 0 as i64, because a timer you cannot cancel keeps running for as long as the page is open. The functions take a function without parameters, so pass a lambda: (): tick() end.
The stopwatch starts an interval of 100 milliseconds when you press Start, adds one tenth of a second on every tick, and clears the interval when you press Stop. The toast does it with a timeout: it shows a message, and a second click first cancels the waiting timeout so that the message stays for a full two seconds from the last click.
import dom
mut tenths := 0
mut ticking := 0 as i64
mut running := false
func draw:
dom.SetText(dom.ById("time"), "" + tenths / 600 + ":" + tenths / 10 % 60 / 10 + tenths / 10 % 60 % 10 + "." + tenths % 10)
end
func tick:
tenths++
draw()
end
func start_stop:
if running:
dom.ClearInterval(ticking)
running = false
dom.SetText(dom.ById("go"), "Start")
else:
ticking = dom.SetInterval((): tick() end, 100)
running = true
dom.SetText(dom.ById("go"), "Stop")
end
end
func zero:
tenths = 0
draw()
end
page:
title = "Stopwatch"
font = system, sans margin = 1.5rem
box:
max width = 16rem margin = 0, auto padding = 20 text align = center border = 1px, solid, #e2e8f0 radius = 14
paragraph: id = "time" content = "0:00.0" font size = 3rem font = "ui-monospace", mono margin = 0, 0, 12px, 0 end
button: padding = 8px, 20px font size = 1.05rem border = 1px, solid, #cbd5e1 radius = 8 background = #f8fafc cursor = pointer id = "go" click = start_stop content = "Start" end
button: padding = 8px, 20px font size = 1.05rem border = 1px, solid, #cbd5e1 radius = 8 background = #f8fafc cursor = pointer id = "clear" click = zero content = "Reset" margin = 0, 0, 0, 8px end
end
endimport dom
mut waiting := 0 as i64
component Toast:
shown := false
box:
font = system, sans
margin = 24
button:
id = "copy"
padding = 10, 20
font size = 16
radius = 8
border = 1, solid, #4f46e5
background = #4f46e5
color = white
cursor = pointer
click = ():
dom.ClearTimeout(waiting)
shown = true
waiting = dom.SetTimeout((): shown = false end, 2000)
end
content = "Copy the link"
end
box:
id = "toast"
role = status
margin = 14, 0, 0, 0
padding = 10, 14
background = #0f172a
color = white
radius = 8
max width = 320
opacity = 0
translate = 0, 8
interactive = false
transition = 250ms
if shown:
opacity = 1
translate = 0, 0
end
content = "Link copied. This message goes away in two seconds."
end
end
end
page:
title = "Toast"
Toast: end
endA browser does not promise that an interval is exact. It can run late, and a tab in the background runs it a lot less often. The stopwatch counts ticks, which is simple and good enough to show the idea. For a clock that must be right, remember the start with dom.Now() (milliseconds since the page opened) and show the difference on every tick.
For movement use dom.RequestFrame(fn). It runs the function once, just before the browser draws the next picture, and passes the time in milliseconds. To keep going, the function asks for the next frame itself. This is smoother than an interval because it follows the screen. The ball below is placed from the time that has passed, and not by adding a fixed step, so it takes the same time on a slow screen and on a fast one.
import dom
mut began := 0.0
func slide(t: f64):
mut left := (t - began) / 4.0
if left < 240.0:
dom.RequestFrame((next: f64): slide(next) end)
else:
left = 240.0
end
dom.SetStyle(dom.ById("ball"), "left", "" + left + "px")
end
func launch:
began = dom.Now()
dom.RequestFrame((t: f64): slide(t) end)
end
page:
title = "Slide"
font = system, sans margin = 1.5rem
box: width = 280 height = 44 background = #e0e7ff radius = 22
box: id = "ball" position = absolute top = 4 left = 0 width = 36 height = 36 background = #4f46e5 radius = 50% end
end
button: id = "go" click = launch content = "Slide" margin = 14px, 0, 0, 0 padding = 8px, 18px border = 0 background = #4f46e5 color = white radius = 8 cursor = pointer end
endIf you want a loop that never stops, such as a game, dom.EveryFrame does the asking for you. The CSS lesson on transitions and animations comes first, though: when CSS can do the movement, let it.
Remembering after the page closes
Variables vanish when the page is closed. dom.StoreSetStr("note", text) keeps a string in the browser's localStorage, dom.StoreGetStr("note") gives it back (an empty string when nothing is stored), and StoreSetInt and StoreGetInt do the same for whole numbers. The data stays on the reader's device, for that site only, until it is cleared. Never store a password or anything private there, and never trust what you read back: it is only a convenience, and the visitor can change it.
Storage can be unavailable. A private window, a blocked setting or an embedded frame like the preview below can refuse it. The helpers do not stop the page when that happens: a write is dropped and a read gives an empty string, with a warning in the console. Your code should still behave. This note saves as you type and reads the value back to check it, so it can tell the reader when the browser would not keep it. Press the button, or reload a real page, to load the saved note.
import dom
func save_note:
text := dom.GetValue(dom.ById("text"))
dom.StoreSetStr("note", text)
if dom.StoreGetStr("note") == text:
dom.SetText(dom.ById("state"), "Saved on this device.")
else:
dom.SetText(dom.ById("state"), "This browser would not keep it.")
end
end
func load_note:
saved := dom.StoreGetStr("note")
if saved.Len() > 0:
dom.SetValue(dom.ById("text"), saved)
dom.SetText(dom.ById("state"), "Loaded your saved note.")
else:
dom.SetText(dom.ById("state"), "Nothing saved yet.")
end
end
page:
title = "Notes"
font = system, sans margin = 1.5rem max width = 28rem
text area: id = "text" input = save_note rows = 4 placeholder = "Your note" width = 100% padding = 10 font size = 1rem radius = 8 border = 1px, solid, #cbd5e1 end
box: layout = row justify = between align = center margin = 6px, 0
span: id = "state" content = "Nothing saved yet." color = #475569 end
button: id = "again" click = load_note content = "Load saved note" padding = 6px, 14px end
end
script: content = "window.addEventListener('DOMContentLoaded', function () { load_note(); });" end
endThe last line of the page is a small script element. The page: block has no start-up hook, so this line asks the browser to run load_note once the page has been read. It can name the function because a function used as an event handler (here the button's click) is also placed where the browser can find it. Without this line the page would load the note only when you press the button.
Alerts, questions and prompts
Three helpers use the browser's own dialogs: dom.Alert(message) shows a message, dom.Confirm(question) gives true or false, and dom.Prompt(question) gives the text the reader typed, or an empty string when they cancelled.
func wipe:
if dom.Confirm("Delete all notes?"):
dom.SetText(dom.ById("notes"), "")
end
end
page:
paragraph: id = "notes" content = "Three notes" end
button: click = wipe content = "Delete all" end
end
They are quick to write and poor to live with. The page freezes until the reader answers, you cannot style them, the browser may offer to block them, and a page embedded in another page is often not allowed to show them, in which case Confirm quietly answers false. Use them for a first test of an idea, and in a finished page use a dialog element (page structure) or a message inside the page like the toast above.
Components, repeat and handlers
A component is a piece of page you can use more than once, and its handlers can use the component's parameters. In the poll below, the lambda in Choice calls vote(name) with the name its own copy was made with, and the counter has an id built from the same name, so each copy counts its own votes.
import dom
func vote(name: str):
total := dom.ById("votes-" + name)
dom.SetText(total, "" + (dom.GetText(total).ToInt() + 1))
end
component Choice(name):
box:
class = "choice" layout = row justify = between align = center padding = 8px, 12px margin = 0, 0, 8px, 0 background = #f1f5f9 radius = 10
button: padding = 6px, 14px border = 1px, solid, #6366f1 radius = 8 background = white color = #4338ca cursor = pointer click = (): vote(name) end content = "Vote for " + name end
span: font size = 1.4rem font weight = bold color = #0f172a id = "votes-" + name content = "0" end
end
end
page:
title = "Poll"
font = system, sans margin = 1.5rem max width = 26rem
heading: size = 2 content = "Your favourite drink?" margin = 0, 0, 12px, 0 end
Choice: name = "Tea" end
Choice: name = "Coffee" end
Choice: name = "Juice" end
endTwo limits are worth knowing. A lambda in a page attribute takes no event parameter, so when a handler needs the event, name a function that has one, as the seat picker does. And a plain page is fixed: repeat = 8 makes eight identical copies, but each and if need runtime values and work only in a page with parameters, which the server fills in, inside a component that keeps variables, or when they read a mut variable (error E133 otherwise). That kind of page is covered in the first lesson of this part, and its ids must be different in every copy, so use a class or EventTarget there.
Components that remember: variables and state
The poll above keeps its numbers in the page and reads them back with dom. A component can instead keep a value of its own: a line votes := 0 at the top of its body gives every copy its own votes. There is no keyword to learn. The compiler looks at how each variable is used and decides what it is:
- A variable that some code changes (an assignment,
++, a method such aspush, a handler, a callback) is kept by each copy: it starts from its value once, when the copy is made, and keeps what the handlers did to it. - When the view also shows it (in an attribute, a text, an
iforeach, or a value passed to another component), it is state: after a handler changes it, the page redraws that copy by itself, its text, its attributes, and theifandeachinside it. When nothing in the view reads it (a click counter only a handler looks at, a timer id), changing it redraws nothing. - A variable that nothing changes, such as
label := "Votes for " + name, is derived: it is worked out again every time the copy is drawn, so it always follows the parameters and the state it is made from.
Nothing else on the page is touched, so the button keeps the focus and text typed into an input of the same copy stays where it is.
component Choice(name: str):
votes := 0
box:
class = "choice" layout = row gap = 12px align = center padding = 8px, 12px margin = 0, 0, 8px, 0 background = #f1f5f9 radius = 10
button: padding = 6px, 14px border = 1px, solid, #6366f1 radius = 8 background = white color = #4338ca cursor = pointer click = (): votes++ end content = "Vote for " + name end
span: font size = 1.4rem font weight = bold color = #0f172a content = "" + votes end
if votes >= 3:
span: class = "hot" font size = 0.9rem color = #b45309 content = "popular" end
end
end
end
page:
title = "Poll with variables"
font = system, sans margin = 1.5rem max width = 26rem
heading: size = 2 content = "Your favourite drink?" margin = 0, 0, 12px, 0 end
Choice: name = "Tea" end
Choice: name = "Coffee" end
Choice: name = "Juice" end
endA variable that changes starts from its declaration, which can use the component's parameters (count := start) and needs a type you can see: a literal, a typed parameter, or value as Type, as in items := Vector {} as Vector<str>. The page: block can declare variables the same way, at its top, instead of mut variables above it. Inside the component, if and each may read the state, and a row with a key keeps its element when the rows move. A component with state can sit inside each: every row gets its own copy of the state, which follows the row's key (or id, or its place when it has neither) when rows move. The page itself may also read a mut variable: every element, if or each that reads one is drawn again after any handler that changes it. One limit on the web: the copies, and the parts that read a mut variable, are drawn by the page script, so they appear only with JavaScript on. The same page runs in a native window with salam run page.salam --ui=native, where that limit is gone.
Components talking to each other
A component often needs to tell the one around it that something happened. There are two ways, and both work on the web and in a native window.
The first is a callback: the parent passes a function as a parameter and the child calls it from a handler. The lambda is written in the parent, so it changes the parent's state, and the parent is drawn again. A child whose parent passed nothing simply skips the call.
component Counter(change):
count := 0
button: click = (): count++ change(count) end content = "+1" end
end
component Pair:
sum := 0
box:
paragraph: content = "sum " + sum end
Counter: change = (v: int): sum += v end end
end
end
The second is an event that bubbles, for when the news should travel further than one level. The child writes emit("added", price), and the place where the component is used handles it with on added = (p: int): ... end. The event goes to the nearest handler, then to every level above it, up to an on added line at the top of the page block. A handler that calls stop() keeps it from going further. Here every shelf counts what was added to it and the page adds up the price, while the free sample stops at its shelf:
mut total := 0
component Item(name: str, price: int):
box:
class = "item" layout = row gap = 12px align = center margin = 6px, 0
span: content = name + ", " + price + " coins" end
button: padding = 4px, 12px border = 1px, solid, #6366f1 radius = 8 background = white color = #4338ca cursor = pointer click = (): emit("added", price) end content = "Add" end
end
end
component Shelf(title: str):
count := 0
box:
class = "shelf" padding = 8px, 12px margin = 0, 0, 12px, 0 background = #f1f5f9 radius = 10
heading: size = 3 content = title + ": " + count + " added" end
Item: name = "Tea" price = 3 on added = (): count++ end end
Item: name = "Cake" price = 5 on added = (): count++ end end
Item:
name = "Sample"
price = 0
on added = ():
count++
stop()
end
end
end
end
page:
title = "Events that bubble"
on added = (p: int): total += p end
font = system, sans margin = 1.5rem max width = 26rem
heading: size = 2 content = "Basket: " + total + " coins" margin = 0, 0, 12px, 0 end
Shelf: title = "Morning" end
Shelf: title = "Evening" end
endA handler takes the value as one typed parameter, or none when it does not need it. The compiler works out the route while it builds the page, so an event costs no more than calling the handlers yourself, and only the components whose state changed are drawn again. Put the statements of a longer handler on separate lines, as the sample does: on one line, count = n stop() would read n stop as one name.
Putting it together: a quiz
Here is a bigger one with a little of everything. The state is three variables: which question is showing, the score, and which answer was picked (minus one while none was). The questions are not in the markup. One function returns the question and its answers as a single string, Split("|") cuts it into parts, and a small function turns the picked answer into a mark for each choice, which the choice turns into its colour with if. Adding a question means adding one line.
func question(n: int): str:
switch n:
0: ret "Which element is the largest heading?|h1|h6|header|0" end
1: ret "Which attribute gives an image its text alternative?|alt|src|title|0" end
else: ret "Which event fires when a field changes as you type?|click|input|load|1" end
end
ret ""
end
func part(n: int, k: int): str:
ret question(n).Split("|").Get(k)
end
func right_answer(n: int): int:
ret part(n, 4).ToInt()
end
func mark(n: int, picked: int, k: int): int:
if picked < 0:
ret 0
end
if k == right_answer(n):
ret 1
end
if k == picked:
ret 2
end
ret 0
end
component Choice(label: str, mark: int, pick):
button:
width = fill
margin = 6, 0
padding = 10, 14
text align = start
font size = 16
border = 1, solid, #cbd5e1
radius = 8
background = white
cursor = pointer
hover:
background = #eef2ff
end
if mark == 1:
background = #dcfce7
border = 1, solid, #16a34a
end
if mark == 2:
background = #fee2e2
border = 1, solid, #dc2626
end
click = pick
content = label
end
end
component Quiz:
asked := 0
score := 0
picked := -1
box:
font = system, sans
margin = 24
max width = 448
if asked < 3:
heading: id = "ask" size = 3 content = part(asked, 0) end
Choice: label = part(asked, 1) mark = mark(asked, picked, 0) pick = ():
if picked < 0:
picked = 0
if right_answer(asked) == 0:
score++
end
end
end
end
Choice: label = part(asked, 2) mark = mark(asked, picked, 1) pick = ():
if picked < 0:
picked = 1
if right_answer(asked) == 1:
score++
end
end
end
end
Choice: label = part(asked, 3) mark = mark(asked, picked, 2) pick = ():
if picked < 0:
picked = 2
if right_answer(asked) == 2:
score++
end
end
end
end
paragraph:
id = "verdict"
color = #475569
content = picked < 0 ? "Pick an answer." : (picked == right_answer(asked) ? "Correct." : "Not this time.")
end
else:
heading: size = 3 content = "You scored " + score + " of 3." end
end
button:
id = "next"
padding = 8, 18
border = 0
background = #4f46e5
color = white
radius = 8
cursor = pointer
click = ():
if asked == 3:
asked = 0
score = 0
picked = -1
else picked >= 0:
asked++
picked = -1
end
end
content = asked == 3 ? "Play again" : "Next"
end
end
end
page:
title = "Quiz"
Quiz: end
endNotice the guard in each choice: once an answer is picked, picked is no longer negative and further clicks do nothing, so nobody scores twice. Notice also that Next does nothing until an answer is chosen. Checks like these are state again, and they are cheaper than hiding and showing buttons.
The pattern for every page in this lesson is the same. Decide what the page must remember. Describe the page from that state. Make each handler change the state and nothing else.
When it does not work
- Open the browser console (F12, then Console). An error in a handler appears there with its line, and nothing appears on the page. Most of the problems below are visible in it.
- Print what you want to know.
println "count is", countin a handler writes to the console, asconsole.logwould. It is the simplest way to see whether a handler runs at all and what the state is. - Nothing happens on click. Check that the function name is not a name the browser already owns (
reset,open,close,focus; see the note in the mouse lesson), and that there is nomainin the file. A call written with parentheses,click = more(), is not a silent failure: the compiler rejects it with error E137, because the attribute wants the function itself. - "Cannot read properties of null". An id or selector matched nothing. Compare it with the page, and remember that ids built at run time are not checked by the compiler.
- The page changes, then changes back. A form was sent. Call
dom.PreventDefault(e)in itssubmithandler. - A list is out of date. A
QueryAllresult is a snapshot. Ask again after you add or remove elements. - Persian text is counted wrong.
str.len()counts bytes in the browser. For what the reader sees usetextLengthas above.
mut clicks := 0
func more:
clicks++
println "clicks:", clicks
end
page:
button: click = more content = "Click and watch the console" end
end
Everything the page does in the browser can be seen and changed by the reader. Check anything that matters, such as prices, rights and limits, again on the server. The first lesson of this part shows how a Salam program serves a page, and the dom package page lists every helper with its signature.
Try it yourself
- Make the todo list keep its tasks: save the text of every task with
StoreSetStrwhen the list changes, and read it back when the page opens, as the notes example does. - Add a fourth question to the quiz, and under the final score a line that tells the reader how many answers were right in a row.
- Turn the stopwatch into a countdown: start from 30 seconds, stop at zero, and use
dom.SetTimeoutor the interval to show a message when time is up. - Make the accordion close the other panels when one opens, so only one is open at a time. Use
QueryAllto visit them all.