Forms

The form and the submit

A form holds controls and knows where to send them. action is the address that receives the data and method is how it travels: get puts the data into the address and suits searches, post puts it into the body of the request and is the right choice for everything that changes something or is private. When the form has a file input, add enctype = "multipart/form-data". The other form attributes are in the reference below: autocomplete, novalidate, target, rel, accept charset and name.

A real send would leave the page, and the previews in this lesson must stay on it. So most examples here listen to the button and decide for themselves what happens. The click attribute of a submit button is a function that runs when the button is pressed. It receives the event, and dom.PreventDefault stops the default action, which is sending the form. That also skips the browser's checks, so the function asks for them: reportValidity checks every field and shows the browser's message at the first bad one, and as bool turns its answer into true or false. After that you read each field with dom.GetValue(dom.ById("id")) and use the text as you like. The event is the plain i64 parameter of the function.

On a page of your own you can give the same function to the submit attribute of the form. The browser then runs its checks first and calls your function only when they pass, so reportValidity is not needed.

import dom

func Join(e: i64):
    dom.PreventDefault(e)
    if dom.Call0(dom.ById("sign"), "reportValidity") as bool:
        name := dom.GetValue(dom.ById("name"))
        mail := dom.GetValue(dom.ById("mail"))
        dom.SetText(dom.ById("out"), "Welcome, " + name + ". We will write to " + mail + ".")
    end
end

page:
    title = "Sign up"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" max width = "24rem" end
    global: selector = "label" display = block margin = "0.8rem 0 0.2rem" end
    global: selector = "input" padding = 6 width = "100%" box sizing = "border-box" end
    form: id = "sign"
        label: for = "name" content = "Your name" end
        input: id = "name" name = "name" required = true placeholder = "Ada Lovelace" end
        label: for = "mail" content = "Email" end
        input: id = "mail" name = "mail" type = email required = true placeholder = "ada@example.com" end
        button: type = submit click = Join content = "Join" margin = "1rem 0" padding = "6px 18px" end
    end
    paragraph: id = "out" color = "#0f766e" end
end

Leave the fields empty and press Join: the browser shows its message and nothing else happens, because reportValidity answered no. Write something that is not an address in the Email field and it refuses again. Only a complete form gets past the if, which is why you can trust the values inside it, at least as far as the browser checks go.

Labels

Every control needs a label. Connect them in one of two ways. Give the control an id and write the same id in for of the label, as the sign up example does: Salam checks at compile time that an element with that id exists, so a typo cannot silently break the link. Or put the control inside the label, as the pizza example further down does, and no for is needed. Either way a click on the label text focuses the control or ticks the checkbox, and a screen reader reads the label when the control gets the focus.

The placeholder attribute is not a label. It is a hint in the empty box, it vanishes when the visitor types and many people find the grey text hard to read. Use it for an example of the format, and keep the label.

Input types

input is one element with many faces. Its type decides the face, the keyboard a phone shows, and what the browser checks. Without a type it is a text box. The table lists every type that Salam names, with its Persian name, which you use in Persian files.

Other HTML types, such as datetime-local, month, week and image, are not in Salam's list but you can write them as quoted strings, for example type = "month". The image type is a submit button drawn as a picture, and it uses url for the picture, alt for its text and width and height.

page:
    title = "Input types"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    form:
        display = grid
        grid template columns = "7rem 12rem"
        gap = "0.6rem 1rem"
        label: for = "n" content = "Number" end
        input: id = "n" type = number end
        label: for = "p" content = "Phone" end
        input: id = "p" type = tel end
        label: for = "u" content = "Web page" end
        input: id = "u" type = url end
        label: for = "q" content = "Search" end
        input: id = "q" type = search end
        label: for = "d" content = "Date" end
        input: id = "d" type = date end
        label: for = "t" content = "Time" end
        input: id = "t" type = time end
        label: for = "c" content = "Colour" end
        input: id = "c" type = color end
        label: for = "v" content = "Volume" end
        input: id = "v" type = range end
    end
end

The form above is a grid with two columns, set with display = grid and grid template columns, so that every label stands to the left of its control. gap is the space between rows and columns. Open it on a phone and each control brings its own keyboard.

Letting the browser check

Most of the checking comes from attributes on the control. required forbids an empty value. minlength and maxlength bound the number of characters, and pattern takes a regular expression that the whole value must match. For numbers and dates, min, max and step set the range and the grid of allowed values. size only changes how wide a text box looks, and does not check anything. readonly keeps a value from being edited but still sends it, while disabled also keeps it from being sent. autofocus puts the cursor in a field when the page opens, multiple allows several files or addresses, and autocomplete tells the browser what the field holds so that it can offer the saved value.

Besides the message that the browser shows, your code can ask each control about its validity. The example reads it on every keystroke with the input event. dom.GetProp(field, "validity") gives an object whose properties are true or false: valueMissing when a required field is empty, tooShort when it is shorter than minlength, patternMismatch when it does not match the pattern, and rangeUnderflow and rangeOverflow when a number is outside min and max. dom.EventTarget(e) tells the shared handler which field it was called for.

import dom

func Check(e: i64):
    field := dom.EventTarget(e)
    v := dom.GetProp(field, "validity")
    mut text := "Looks good."
    if dom.GetBool(v, "valueMissing"): text = "This field is required."
    else dom.GetBool(v, "tooShort"): text = "Use at least 3 characters."
    else dom.GetBool(v, "patternMismatch"): text = "Letters only, no spaces."
    else dom.GetBool(v, "rangeUnderflow"): text = "You must be 18 or older."
    else dom.GetBool(v, "rangeOverflow"): text = "Please enter an age up to 99."
    end
    dom.SetText(dom.ById(dom.GetStr(field, "id") + "-note"), text)
end

page:
    title = "Validation"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    style: content = "input:user-invalid { border: 2px solid #dc2626 } input:user-valid { border: 2px solid #16a34a }" end
    form:
        label: for = "user" content = "Username" end
        input: id = "user" required = true minlength = 3 pattern = "[A-Za-z]+" input = Check end
        paragraph: id = "user-note" content = "At least 3 letters." end
        label: for = "age" content = "Age" end
        input: id = "age" type = number required = true min = 18 max = 99 input = Check end
        paragraph: id = "age-note" content = "From 18 to 99." end
    end
end

The two border colours come from a CSS rule written with the page wide style element: input:user-invalid and input:user-valid. These match only after the visitor has touched the field and left it, so a form that is still empty does not show red from the first second. The older :invalid matches at once and looks angry on a fresh form.

Longer text

For text that may take several lines use text area. It has rows and cols for its starting size, maxlength and minlength for the length, and wrap: with soft long lines only wrap on the screen, with hard the line breaks are also put into the text that is sent, which needs cols. The text between the tags in HTML is the starting text, and in Salam it is content. An input with type = "textarea" is the same element written differently.

A counter that tells the visitor how many characters are left is a small kindness when you set a limit. The example reads textLength from the box, which counts characters, not bytes, so it is right for Persian text as well.

import dom

const LIMIT := 80

func Count:
    used := dom.GetNum(dom.ById("bio"), "textLength") as i64
    dom.SetText(dom.ById("left"), "" + (LIMIT - used) + " characters left")
end

page:
    title = "Long text"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    label: for = "bio" content = "About you" end
    text area:
        id = "bio"
        name = "bio"
        rows = 4
        cols = 40
        maxlength = LIMIT
        placeholder = "A few words about yourself"
        input = Count
        display = block
        margin = "0.4rem 0"
    end
    small: id = "left" content = "80 characters left" end
end

Checkboxes, radio buttons and groups

A checkbox is a yes or no. Several checkboxes with the same name are sent as a list of the ticked ones. A radio is one choice out of a set: all radio buttons that share a name belong together and the browser keeps one of them ticked. value is the text that is sent when the control is chosen, and checked chooses it from the start. To read a choice in code, use dom.GetBool(control, "checked").

Wrap a related set in a field set with a legend. A sighted visitor sees a box with a title. A screen reader announces the legend as the question when the visitor enters the group, and then reads each option, which a bare row of radio buttons cannot do. The form in the example reacts to the change event, which fires on the form for every change of any control inside it.

import dom

func Show:
    mut size := "small"
    if dom.GetBool(dom.ById("s-large"), "checked"): size = "large" end
    mut extras := ""
    if dom.GetBool(dom.ById("x-cheese"), "checked"): extras = extras + " cheese" end
    if dom.GetBool(dom.ById("x-olives"), "checked"): extras = extras + " olives" end
    dom.SetText(dom.ById("out"), "Size: " + size + ". Extras:" + extras)
end

page:
    title = "Pizza order"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    global: selector = "label" display = block margin = "0.3rem 0" end
    form: change = Show
        field set:
            legend: content = "Size" end
            label: input: id = "s-small" type = radio name = "size" value = "small" checked = true end span: content = " Small" end end
            label: input: id = "s-large" type = radio name = "size" value = "large" end span: content = " Large" end end
        end
        field set:
            legend: content = "Extras" end
            label: input: id = "x-cheese" type = checkbox name = "extra" value = "cheese" end span: content = " Cheese" end end
            label: input: id = "x-olives" type = checkbox name = "extra" value = "olives" end span: content = " Olives" end end
        end
    end
    paragraph: id = "out" content = "Size: small. Extras:" end
end

A field set can also be switched off in one go: disabled on the set disables every control inside. The next example reads a checkbox and sets disabled with dom.SetBool.

import dom

func Toggle:
    same := dom.GetBool(dom.ById("same"), "checked")
    dom.SetBool(dom.ById("ship"), "disabled", same)
end

page:
    title = "Grouped fields"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" max width = "26rem" end
    global: selector = "fieldset input" display = block margin = "0.4rem 0" padding = 5 end
    form:
        field set:
            legend: content = "Billing address" end
            input: name = "street" placeholder = "Street" end
            input: name = "town" placeholder = "Town" end
        end
        label: input: id = "same" type = checkbox change = Toggle end span: content = " Ship to the same address" end end
        field set: id = "ship"
            legend: content = "Shipping address" end
            input: name = "street2" placeholder = "Street" end
            input: name = "town2" placeholder = "Town" end
        end
    end
end

Choosing from a list

select is a drop-down list, and option is each line of it. The visitor sees the text of the option, and the form sends its value, so give a short code that your server understands. selected picks the starting option and disabled greys one out: a first line that is disabled and selected makes a good prompt, such as Choose a city. option group puts a heading over several options and needs a label. multiple turns the list into a box where several lines can be chosen, and size says how many lines are visible.

import dom

func Pick:
    dom.SetText(dom.ById("out"), "You chose: " + dom.GetValue(dom.ById("city")))
end

page:
    title = "Drop-down list"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    label: for = "city" content = "Where do you live? " end
    select: id = "city" name = "city" change = Pick
        option: value = "none" content = "Choose a city" disabled = true selected = true end
        option group: label = "Europe"
            option: value = "oslo" content = "Oslo" end
            option: value = "rome" content = "Rome" end
        end
        option group: label = "Asia"
            option: value = "tokyo" content = "Tokyo" end
            option: value = "seoul" content = "Seoul" disabled = true end
        end
    end
    paragraph: id = "out" content = "You chose: none" end
end

When the visitor should also be allowed to type something that is not in your list, use a data list. It is a list of suggestions that has no look of its own. Give it an id and name it in the list attribute of a text input: the browser then offers the matching suggestions while the visitor types.

import dom

func Echo:
    dom.SetText(dom.ById("out"), "Searching for " + dom.GetValue(dom.ById("lang")))
end

page:
    title = "Suggestions"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    label: for = "lang" content = "Favourite language " end
    input: id = "lang" list = "langs" placeholder = "Start typing" input = Echo end
    data list: id = "langs"
        option: value = "Salam" end
        option: value = "Python" end
        option: value = "Rust" end
        option: value = "Scheme" end
    end
    paragraph: id = "out" content = "Searching for" end
end

Buttons

A button has a type. A submit button sends the form, a reset button puts all fields back, and a button button does nothing until a script gives it something to do. Inside a form a button without a type is a submit button, which is how many forms get sent by accident: always write the type.

A submit button with a name and a value tells you which one was pressed, so one form can have Save and Delete. The buttons can also override the form for one press: form action, form method, form enctype, form target and form novalidate replace the form's own attribute. A Save draft button with form novalidate sends a half filled form. With form = "id" a button may stand outside the form it belongs to. In a submit handler on a real page, dom.GetProp(e, "submitter") is the button that was used. In the example each button has its own click handler instead, which reads the button's value with dom.GetStr(dom.EventTarget(e), "value"). The reset button below the form belongs to it through form = "note".

import dom

func Pressed(e: i64):
    dom.PreventDefault(e)
    dom.SetText(dom.ById("out"), "Pressed: " + dom.GetStr(dom.EventTarget(e), "value"))
end

page:
    title = "Buttons"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    global: selector = "button" padding = "6px 12px" margin = "0.4rem 0.4rem 0 0" end
    form: id = "note"
        input: id = "t" name = "title" placeholder = "Title" end
        button: type = submit name = "do" value = "save" click = Pressed content = "Save" end
        button: type = submit name = "do" value = "draft" click = Pressed content = "Save draft" end
        button: type = reset content = "Clear" end
        button: type = button value = "help" click = Pressed content = "Help" end
    end
    button: type = reset form = "note" content = "Clear from outside" end
    paragraph: id = "out" content = "Nothing pressed yet." end
end

Two more groups of attributes belong to buttons. popover target and popover target action show or hide an element that has the popover attribute, with no code. command and commandfor give a command such as show-modal to a dialog. Both are newer, so check the browsers your visitors use.

Showing results

Three elements show values instead of asking for them. output holds a result, like the number beside a slider; its for lists the controls it is calculated from, and Salam checks the ids. progress is a bar for how much of a job is done, with value out of max. meter shows a value on a known scale, and low, high and optimum tell the browser which part of the scale is good: the bar turns green, yellow or red.

import dom

func Move:
    level := dom.GetValue(dom.ById("level"))
    dom.SetText(dom.ById("shown"), level + " %")
    dom.SetStr(dom.ById("bar"), "value", level)
    dom.SetStr(dom.ById("gauge"), "value", level)
end

page:
    title = "Output, progress, meter"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    global: selector = "progress, meter" display = block width = "16rem" margin = "0.6rem 0" end
    form:
        label: for = "level" content = "Battery level " end
        input: id = "level" type = range min = 0 max = 100 value = 40 input = Move end
        output: id = "shown" for = "level" content = "40 %" end
    end
    progress: id = "bar" value = 40 max = 100 end
    meter: id = "gauge" value = 40 min = 0 max = 100 low = 25 high = 75 optimum = 100 end
end

Drag the slider and all three change. progress and meter look alike and mean different things. A task that is going to finish is a progress. A reading that goes up and down, such as battery charge, is a meter.

Files

A file input opens the file chooser. accept filters what it offers, with MIME types such as image/png, wildcards such as image/* and extensions such as .pdf. It is a convenience: a visitor can still pick another file, so check the type on the server. multiple allows several files. A form that sends files must be a post form with enctype = "multipart/form-data". In code, dom.GetProp(input, "files") is the list of chosen files, dom.CountOf counts them and dom.ItemAt picks one.

import dom

func Listed:
    files := dom.GetProp(dom.ById("pics"), "files")
    n := dom.CountOf(files)
    mut text := "No files chosen."
    if n > 0: text = "Chosen: " + dom.GetStr(dom.ItemAt(files, 0), "name") end
    if n > 1: text = text + " and " + (n - 1) + " more" end
    dom.SetText(dom.ById("out"), text)
end

page:
    title = "File upload"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    form: method = post enctype = "multipart/form-data"
        label: for = "pics" content = "Pictures " end
        input: id = "pics" name = "pics" type = file accept = "image/png, image/jpeg, .webp" multiple = true change = Listed end
    end
    paragraph: id = "out" content = "No files chosen." end
end

The Jalali date

Salam has an input type of its own for Persian dates, jalali date (in Persian files تاریخ شمسی). It is a text box that types Persian digits whatever keyboard the visitor has, adds the slashes, and tells the browser the date is invalid when the month or the day does not exist, which also respects leap years. Latin and Arabic digits that the visitor pastes are converted. The box shows the digits ۱۴۰۵/۰۸/۰۴, and the same date with Latin digits, 1405/08/04, is kept in the data-value attribute for your code to read with dom.GetAttr.

import dom

func Changed:
    day := dom.GetAttr(dom.ById("birth"), "data-value")
    dom.SetText(dom.ById("out"), "Stored value: " + day)
end

page:
    title = "Persian date"
    global: selector = "body" font family = "system-ui, sans-serif" margin = "1.5rem" end
    label: for = "birth" content = "Birthday (Jalali) " end
    input: id = "birth" name = "birth" type = "jalali date" placeholder = "1380/01/01" change = Changed end
    paragraph: id = "out" content = "Stored value:" end
end

Reference: every form element

Each element is shown with an example, and the attributes that belong only to that element are listed under it. The attributes that every element has are in the lesson on the head and global attributes, and the events, such as submit, input and change, are in the lesson on keys and form events. The examples are checked by the compiler, so you can paste any of them into a page: block. Persian names work in any file, and the Persian lessons use them.

form (Persian: فرم; HTML: <form>)

A form collects what the visitor types or picks and sends it to an address. Inputs, buttons and the other form controls go inside it. A form can also run code instead of sending: write a submit handler that calls dom.PreventDefault and reads the fields yourself, as the examples in this lesson do. Forms cannot be nested.

form: action = "/search" method = get
    label: for = "q" content = "Search" end
    input: id = "q" name = "q" type = search end
    button: type = submit content = "Go" end
end

input (Persian: ورودی; HTML: <input>)

A single form control. Its type decides what it is: a text box, a checkbox, a colour picker, a button and so on, 20 kinds in all that Salam names (see the table in the lesson). It has no content and no children. Give it a name, because a control without a name is not sent, and a label, because a control without a label is a puzzle for a screen reader.

label: for = "city" content = "City" end
input: id = "city" name = "city" placeholder = "Oslo" end

Void element, it cannot have children

textarea input (Persian: ورودی; HTML: <textarea>)

The form of text area that is written as an input with type = "textarea". It produces the same <textarea> tag, and its text comes from content. Prefer text area, which has the attributes that belong to a multi-line box (rows, cols, wrap).

input: type = "textarea" name = "note" content = "Write here" end

text area (Persian: متن بلند; HTML: <textarea>)

A box for text with several lines: a comment, a message, an address. The text inside is its starting content. The visitor can drag the corner to resize it unless CSS resize says otherwise. Line breaks the visitor types are sent as they are.

text area: name = "message" rows = 3 cols = 30 content = "Dear team," end

label (Persian: برچسب; HTML: <label>)

The caption of a form control. A click on the label focuses or toggles its control, which makes small checkboxes much easier to hit, and screen readers read it when the control is focused. Connect them with for (the id of the control) or by putting the control inside the label.

label: for = "mail" content = "Email" end
input: id = "mail" type = email end

button (Persian: دکمه; HTML: <button>)

A button with any content: text, or an image next to text. Inside a form its default type is submit, which sends the form. For a button that only runs code, say type = button or the form is sent by accident.

button: type = button content = "Click me" end

select (Persian: انتخاب; HTML: <select>)

A drop-down list: the visitor picks one of the options, or several with multiple. The value that is sent is the value of the chosen option, or its text when it has none. Use it for four or more choices; for two or three, radio buttons show the options without a click.

select: name = "fruit"
    option: value = "apple" content = "Apple" end
    option: value = "pear" content = "Pear" end
end

option (Persian: گزینه; HTML: <option>)

One choice in a select, an option group or a data list. Its text is what the visitor sees, and its value is what is sent. In a data list the value is the suggestion.

select: name = "fruit"
    option: value = "apple" content = "Apple" end
end

Only inside: select, option group, data list

option group (Persian: گروه گزینه; HTML: <optgroup>)

A named group of options inside a select. The visitor sees the name as a bold line that cannot be chosen. It must have a label, and the compiler stops without one.

select: name = "city"
    option group: label = "Europe"
        option: value = "oslo" content = "Oslo" end
        option: value = "rome" content = "Rome" end
    end
end

Required: label · Only inside: select

data list (Persian: فهرست پیشنهاد; HTML: <datalist>)

A list of suggestions for a text input. Link it with the input's list attribute. Unlike select it does not force a choice: the visitor may type something that is not in the list. It is invisible by itself.

input: name = "browser" list = "browsers" end
data list: id = "browsers"
    option: value = "Firefox" end
    option: value = "Chrome" end
end

field set (Persian: گروه فیلد; HTML: <fieldset>)

Groups related controls in a box, such as the lines of an address or a set of radio buttons. A screen reader announces the legend when the visitor enters the group, which is how a bare list of radio buttons gets its question.

field set:
    legend: content = "Delivery" end
    label: input: type = radio name = "d" end span: content = " Home" end end
    label: input: type = radio name = "d" end span: content = " Office" end end
end

legend (Persian: عنوان گروه; HTML: <legend>)

The title of a field set. It must be the first child of the group and is drawn on its border.

field set:
    legend: content = "Payment" end
    input: name = "card" placeholder = "Card number" end
end

Only inside: field set

output (Persian: خروجی; HTML: <output>)

The result of a calculation or of the visitor's action, such as the value next to a slider. Screen readers announce changes in it politely. Set its text from a script with dom.SetText.

input: id = "a" type = number value = 2 end
output: for = "a" content = "4" end

progress (Persian: پیشرفت; HTML: <progress>)

A bar for how far a task has got, such as an upload. Without value it shows an endless busy animation. For a measurement that is not progress, such as disk use, take meter. Put a text next to it as well, since the bar alone says little to a screen reader.

progress: value = 30 max = 100 end

meter (Persian: سنجه; HTML: <meter>)

A gauge for a value inside a known range: battery level, a score, how full a disk is. Browsers colour it green, yellow or red from low, high and optimum. It is not for progress: use progress for that.

meter: value = 6 min = 0 max = 10 low = 3 high = 8 optimum = 10 end

Required: value

Try it yourself

• Make a contact form with a name, an email, a topic in a select and a message in a text area with a character counter. Show the collected values in a paragraph when it is sent.
• In the validation example, add a Repeat password field and report an error until the two passwords are the same. Read both with dom.GetValue.
• Build a small order form with a number of items (min = 1), a delivery choice in radio buttons and a total shown in an output.
• Give the Jalali date field a required and see what the browser does when it is empty and when the date is 1405/13/40.