Skip to main content
Category: Controls · Sends commands: yes · Emits a value: yes (auto-injected on submit)

​
Mental model

A Form is a settings sheet. The user fills several fields and hits submit, and all of them travel together to the device — keyed by field ID. It’s the go-to when you need to send several values at once.

​
When to use it

  • Collect multiple values and send them in one command (config, calibration)
  • Any “fill these in, then apply” interaction

​
Settings

​
General — per field

Each field has:
  • Field ID — the key the value is sent under (read this in firmware)
  • Field Label · Field Type
  • Default value · Max length · Max value — validation

​
Style

Background, border, focus / error border, font, spacing per field.

​
Triggers

EventFires when
submitThe form is submitted (auto-injects all field values)
input / changeA field changes
focus / blurField focus changes
(common)load, ready, destroy, update, visible, hidden

​
Auto-injected fields on submit

On submit, the Form injects every field value into the action’s params, keyed by field ID — merged with any static params. See emitted values. Trigger: 
WHEN     submit
SEND TO  Current Device
EXECUTE  Config
Action   save   params: {}     ← device receives { "<fieldId>": <value>, … }
Firmware (Arduino) — read each field by its ID: 
device.setUserCommandHandler([](JsonObject &msg) {
  JsonObject p = device.findParams(msg, "Config", "save");
  if (!p.isNull()) {
    const char* name  = p["deviceName"];   // field IDs
    int         limit = p["maxTemp"];
    // apply the submitted settings
  }
});

​
Script API example

The same interactions from a dashboard script: 
widget.on('configForm', 'submit', async (fields) => {
  await db.insert('config_history', fields);   // archive every submission
  widget.setText('formStatus', 'Saved \u2713');
});

Database Form

Save form input straight to the database.

Emitted values

How fields auto-inject.