Form fields

Form fields are the inputs users fill in: preferences, widget settings and command arguments. You declare them in the manifest and Flare draws the form with its own controls. You don't write any UI.

The same shape is used in three places:

Where	Read as
preferences, for the whole plugin	ctx.preferences, in every function and component
a widget's settings	useWidget().settings, or the settings prop
a command's arguments	the command's arguments, when it runs

{
  "settings": [
    {
      "name": "container",
      "title": "Table or collection",
      "type": "container",
      "required": true
    },
    {
      "name": "field",
      "title": "Date field",
      "type": "field",
      "of": "container",
      "required": true
    },
    {
      "name": "days",
      "title": "Days",
      "type": "dropdown",
      "default": "14",
      "options": [
        { "title": "7 days", "value": "7" },
        { "title": "30 days", "value": "30" }
      ]
    },
    { "name": "goal", "title": "Goal", "type": "number", "placeholder": "1000" },
    {
      "name": "live",
      "title": "Count only live rows",
      "type": "checkbox",
      "default": true
    }
  ]
}

Fields

Field	Type	Default	What it is
name	string	required	How the code reads it: a letter, then letters, digits and underscores, up to 40. Unique in its form.
title	string	required	Its label, 1 to 60 characters.
description	string		A line of help under it, up to 280 characters.
type	string	required	What kind of field it is. Below.
required	boolean	false	Whether it must be filled in. A widget with an empty required setting prompts the user to set it up.
placeholder	string		Shown in an empty field, up to 80 characters.
default	string, number or boolean		The value until the user changes it.
options	{ title, value }[]		A dropdown's choices, at least one. Each value is a string.
of	string		For a field: the name of the container field in the same form to list fields from.

Types

Type	Drawn as	Its value
text	A text field.	A string.
password	A text field that hides its input. Stored encrypted as a preference.	A string.
number	A number field.	A number.
checkbox	A checkbox.	A boolean.
dropdown	A dropdown of its options.	The chosen option's value.
container	A picker of the open database's tables or collections.	The container's path, a string.
field	A picker of the fields of the container chosen in of.	The field's name, a string.

container and field let a widget work on any database. The user picks from what's there, and your code reads whatever names it's given.

A dropdown without options, or a field without of, fails manifest validation with a message naming the field.

In code

const field: FormField = {
  name: 'container',
  title: 'Table or collection',
  type: 'container',
  required: true,
};

FormField is the type of one field, and formFieldSchema in @flare/plugin/manifest is its schema. Preference values are typed PreferenceValue: a string, number, boolean or null.