RoboHub

This page was generated from the source of RoboHub. Edit the source, not this page.

Forms

A schema-driven form engine. A module declares its form as data — a list of
fields, each naming its kind, its label, its validation rules and its default —
and this engine renders the controls, manages the submitted values, reports the
errors and hands the payload back. The same styling, the same error handling
and the same input controls serve every form in every host, so an upgrade or a
new global rule is written once.

How an application uses it

Add forms to deps and include it. It needs no host hooks and serves no
routes. Put forms_style() in the layout once so the controls look the same in
every form. Every shared module with a form (appshell, logging,
inventory, scheduler, widgets, rules) depends on it, and so does each
module's settings tab.

The idea

A form is metadata, and rendering is the engine's job. A module that wants a
form:

  1. declares a fixed FormField array describing its fields,
  2. hands it to the engine with its length to render,
  3. lets the engine read the submitted body back into it,
  4. asks the engine to validate (it writes a per-field error into it),
  5. reads the values back out - forms_value or forms_payload - once they pass.

The fields are passed as a dynamic array [FormField] with a count, because
that is what both backends can index: []FormField in Go, FormField* in C. An
enclosing Slice[FormField] carries its storage through a pointer that Go
cannot index.

A field

FormField{ "meshes", "select", "Gateway project",
    "The project whose gateway and devices this application uses.",
    "Choose a gateway project", false, "", "alpha|Alpha,beta|Beta", "alpha", "", "" }

The fields, in order:

namekindlabelhintplaceholderrequiredpatternoptionsvalueerrinput_mode
the keyhow it is drawnwhat the user readshelp under itghost text / select promptmust be filledthe rule`valuelabel,valuelabel` for a selectthe submitted answerthe last validation messagea mobile keyboard hint

kind is text, password, number, select, textarea, toggle or
hidden. pattern is one of ip, number, host, email, url, plain,
or empty for none. input_mode gives a text field a mobile keyboard hint such as
decimal or numeric, or is empty.

forms_open takes the active locale as its last argument and translates the
default submit label; a caller may pass i18n_t(req, "common.save") instead.

The round trip

// A consumer's own schema, drawn from its own defaults.
fn my_schema(fields: [FormField]) void {
    fields[0] = FormField{ "gateway", "text", "Gateway URL", "", "",
        true, "host", "", my_default("gateway"), "", "" }
    fields[1] = FormField{ "token", "password", "Token", "", "",
        false, "", "", my_default("token"), "", "" }
}

fn my_page(req: Request) Response {
    var schema: FormField[2]
    my_schema(schema)
    let content: string = forms_open(schema, 2, "/configure", "", i18n_locale(req))
    return html(status_ok(), "<h1>Configure</h1>" + content)
}

fn my_save(req: Request) Response {
    var schema: FormField[2]
    my_schema(schema)
    let body: string = request_body(req)
    // A submit has to carry the token the page drew; a cross-site form cannot.
    if !forms_csrf_ok(body) {
        return html(status_ok(), "<h1>Configure</h1><p>Refused: no form token.</p>")
    }
    forms_read(schema, 2, body)
    if !forms_validate(schema, 2) {
        let content: string = forms_open(schema, 2, "/configure", "", i18n_locale(req))
        return html(status_ok(), "<h1>Configure</h1>" + content)
    }
    // Valid: use what the user typed.
    my_persist("gateway", forms_value(schema, 2, "gateway"))
    my_persist("token", forms_value(schema, 2, "token"))
    return redirect("/configure")
}

The engine writes the submitted value and the error into the caller's own
array, so after a failed submit the same array re-renders with the user's input
and the highlights in place. Nothing here knows what the data means; it only
collects valid state and hands it across.

CSRF

Every form forms_open draws embeds the application's token in a hidden csrf
input; a form drawn by hand adds it with forms_csrf_field(). A consumer
verifies a submit with forms_csrf_ok(body) before acting on it; a cross-site
request cannot read that token from the victim's own page, so it cannot echo it,
and the forged post is refused.

The token is 256 random bits, made on first use and kept owner-only in the
application's workspace (<workspace>/data/csrf.txt). When no random value can
be had, the token is empty and every submit is refused rather than accepting a
guessable one. A token written by an older release is replaced.

Reference

Generated from the module's manifest and sources when this site was built.

Exports — what an application may call (provides.exports, imported as robohub.forms):

  • forms_open
  • forms_parse
  • forms_read
  • forms_validate
  • forms_value
  • forms_payload
  • forms_csrf_field
  • forms_csrf_ok
  • forms_style
  • forms_body
  • FormField

Release history

[0.1.1] - 2026-11-08

Form fields support mobile input modes, forms_open takes the active locale and translates the default submit label, and the form/CSRF/option/body markup is carried in templates.

[0.2.0] - 2026-11-12

The module publishes its interface: it is imported as robohub.forms, and exports forms_open, forms_parse, forms_read, forms_validate, forms_value, forms_payload, forms_csrf_field, forms_csrf_ok, forms_style. Everything else in it is its own, so an application that imports it cannot reach its helpers, and they never collide with the application's own names. Including it by name still works and is reported with the import to use instead.

[0.3.0] - 2026-11-12

FormField is exported, so an application that imports robohub.forms names the type of the fields it builds. A module's types are its own now, and one an importer names has to be listed under provides.exports.

[0.3.1] - 2026-11-12

The module builds on its own: it imports the template module whose vars it calls and declares the runtime functions it uses, rather than relying on the application that includes it to have declared them.

[0.3.2] - 2026-11-13

The CSRF token is 256 random bits from the runtime, kept owner-only in the application's workspace; a token an older release wrote — the workspace path and a timestamp, which anyone could work out — is replaced the first time it is read. A submit is compared with it without stopping at the first difference, and when no random value can be had every submit is refused rather than a guessable token used.

[0.3.3] - 2026-11-14

Trimming, URL escapes, form fields and decimals come from the toolchain (rho 0.7.0: str_trim, str_url_encode/str_url_decode, form_field, milli_*) rather than this module's own copy, the same on both backends. Needs rho 0.7.0. A value is trimmed of tabs and line breaks at its start as well as its end.

[0.3.4] - 2026-11-14

Its data is kept where app_workspace() says (rho 0.8.0) — the application's workspace, else ~/.rho/apps/<app> — so two applications started by hand no longer share this module's records. Copies of helpers the toolchain now provides (i64_to_str, str_lower, str_field, json_str_field, escape_html) are gone. Needs rho 0.8.0.

[0.3.5] - 2026-11-14

forms_body is exported: an application that brings its own fixed array of fields renders it with this, and a build said it was not promised.