({{, (RefLink[FormObject, paclet:ref/FormObject])[{"(Subscript[name, 1])"->(Subscript[type, 1]),"(Subscript[name, 2])"->(Subscript[type, 2]),…}] 
represents a form with fields having names (Subscript[name, i]) that take data of type (Subscript[type, i]).}, {, (RefLink[FormObject, paclet:ref/FormObject])[{{"(Subscript[name, 1])",(Subscript[label, 1])}->(Subscript[type, 1]),…}]
uses (Subscript[label, i]) as the label for the field named (Subscript[name, i]).}, {, (RefLink[FormObject, paclet:ref/FormObject])[{"(Subscript[name, 1])"->(Subscript[assoc, 1]),…,(Subscript[obj, j]),…}]
uses full specification (Subscript[assoc, i]) for a field, and (Subscript[obj, j]) as part of the layout of the form.}})

OpenersNotesSection(Spacer1)Details and Options

(RefLink[FormObject, paclet:ref/FormObject])[…] displays in a notebook interface as a form with fields that can be filled in, either by entering text or using other controls.

(RefLink[FormObject, paclet:ref/FormObject]) can be used to specify the structure of a form in (RefLink[FormFunction, paclet:ref/FormFunction]).

When evaluated, (RefLink[FormObject, paclet:ref/FormObject])[…] is converted to (RefLink[FormObject, paclet:ref/FormObject])[fields], in which each entry in fields has a full specification of the form "(Subscript[name, i])"->(Subscript[assoc, i]). The elements of the full specification (Subscript[assoc, i]) include:

(RefLink[Setting, paclet:ref/Setting])[FormObject[…]] gives an association of the form <|"(Subscript[name, 1])"->(Subscript[val, 1]),…|>, where the (Subscript[val, i]) are the values obtained by interpreting the "Input" element associated with each "(Subscript[name, i])" according to the "Interpreter" associated with the "(Subscript[name, i])".

If "Input" is missing, or "Interpreter" fails, then the value of "Value" is a (RefLink[Failure, paclet:ref/Failure]) object.

(RefLink[FormObject, paclet:ref/FormObject])[…][<|"(Subscript[name, 1])"->(Subscript[input, 1]),…|>] yields a (RefLink[FormObject, paclet:ref/FormObject])[…] in which the "Input" corresponding to each of the (Subscript[name, i]) included has been replaced with (Subscript[input, i]).

In (RefLink[FormObject, paclet:ref/FormObject])[{…,(Subscript[obj, j]),…}], the (Subscript[obj, j]) can be (RefLink[Delimiter, paclet:ref/Delimiter]), representing a horizontal delimiter.

They can also be expressions with heads (RefLink[Style, paclet:ref/Style]), (RefLink[Row, paclet:ref/Row]), (RefLink[Item, paclet:ref/Item]), (RefLink[Text, paclet:ref/Text]), (RefLink[ExpressionCell, paclet:ref/ExpressionCell]), and (RefLink[TextCell, paclet:ref/TextCell]), as well as views and layout constructs such as (RefLink[TabView, paclet:ref/TabView]) and (RefLink[Grid, paclet:ref/Grid]).

In (RefLink[FormObject, paclet:ref/FormObject])[{"(Subscript[name, 1])"->(Subscript[type, 1]),…}], the (Subscript[type, i]) are used to give values for "Interpreter" in the full specification.

Possible forms of type specifications are:

If only "(Subscript[name, i])" is given, without a rule giving (Subscript[type, i]), then the interpreter is assumed to be (RefLink[Identity, paclet:ref/Identity]), so that the value is exactly whatever is given as the corresponding "Input" element.

By default, the control used for each field is determined by the type of input specified. For type (StringTypeLink["String", paclet:ref/format/String]), a single line of input is by default expected on the web; typing (StringTypeLink["Text", paclet:ref/format/Text]) yields a multiline text field.

Possible controls explicitly given as the value associated with "Control" include (RefLink[InputField, paclet:ref/InputField]), (RefLink[PopupMenu, paclet:ref/PopupMenu]), (RefLink[Slider, paclet:ref/Slider]), and (RefLink[RadioButtonBar, paclet:ref/RadioButtonBar]).

The specification "(Subscript[name, i])"->(RefLink[AutoSubmitting, paclet:ref/AutoSubmitting])[(Subscript[type, i])] indicates that when the field associated with (Subscript[name, i]) is entered, the whole form should automatically be submitted.

(RefLink[FormObject, paclet:ref/FormObject])[(RefLink[AutoSubmitting, paclet:ref/AutoSubmitting])[spec]] indicates that a form should automatically be submitted whenever any of its fields are entered.

Overall options for (RefLink[FormObject, paclet:ref/FormObject]) include:

Typical elements in the setting for (RefLink[AppearanceRules, paclet:ref/AppearanceRules]) include:

Possible settings for "ItemLayout" include "Horizontal", "Vertical", and "Inline".

OpenersPrimaryExamplesSection(Spacer1)Examples  (27)

OpenersExampleSection0(Spacer1)Basic Examples  (3)

Create an unfilled form:

FormObject[{"first"->"String","second"->"Number"}]

form=FormObject[{"first"->"String","second"->"Number"}];

Specify inputs for the form as strings:

form[<|"first"->"a string","second"->"444"|>]

Find the inputs that have been provided for the form:

Setting[%]

The number has been parsed to an explicit number:

InputForm[%]

This input given for the second field cannot be parsed to a number, so a message is shown:

form[<|"first"->"a string","second"->"not a number"|>]

The setting contains a symbolic failure object:

Setting[%]

Use different controls:

FormObject["Slider"-><|"Interpreter"->Restricted["Number", {1, 100}],"Control"->Slider|>]

OpenersExampleSection1(Spacer1)Scope  (17)

OpenersExampleSubsection0(Spacer1)FormObject Structure  (1)

A valid (RefLink[FormObject, paclet:ref/FormObject]) evaluates to an object with an (RefLink[Association, paclet:ref/Association]) with all meta-information:

FormObject["x" -> "Number" -> 3] // InputForm

OpenersExampleSubsection1(Spacer1)Form Submit  (1)

A form is submitted with subvalues:

FormObject["x" -> "Number" -> 3]["x" -> "abc"]

When a form is submitted, data is stored in the second argument and input is inside the first argument:

FormObject["x" -> "Number"]["x" -> "2"] // InputForm

OpenersExampleSubsection2(Spacer1)Form metadata  (3)

You can extract form meta with subvalues:

form = FormObject[{"x" -> "Number", "y" -> "Number"}];
form = form[{"x" -> "3", "y" -> "4"}];
form[All, "Input"]

You can extract "Help", "Control", "Interpreter", etc.:

form["x", "Interpreter"]

"Control" gives you the default formatted controller:

form["x", "Control"]

Use "Failure" to get the failure:

form["x", "Failure"]

If you do not specify a part to extract, the whole controller (with label and help) is returned:

form["x"]

You can extract (RefLink[AppearanceRules, paclet:ref/AppearanceRules]) in the same way:

form =FormObject["Number" -> "Integer", AppearanceRules-><|"Title" -> "My Form", "ItemLayout" -> "Vertical", "Description" -> "My description"|>, PageTheme ->"Black"]

form[AppearanceRules, "Title"]

form[AppearanceRules, "ItemLayout"]

form[PageTheme]

Use (RefLink[Setting, paclet:ref/Setting]) to extract the cleaned data:

FormObject["x" -> "Integer"] // Setting

You can perform several submissions with partial data:

FormObject[{"x" -> "Integer", "y" -> "Integer"}]["x" -> "2"] // Setting

FormObject[{"x" -> "Integer", "y" -> "Integer"}]["x" -> "2"]["y" -> "3"] // Setting

Using a form with defaults is considered valid even if not submitted:

FormObject["x" -> "Integer" -> 3] // Setting

OpenersExampleSubsection3(Spacer1)Interpreter Specifications  (3)

Use rich (RefLink[Interpreter, paclet:ref/Interpreter]) specifications:

FormObject[{"x" -> Restricted["Integer",{1,10}]}][{"x" -> "23"}]

A list can be used to create a menu:

FormObject["x" -> EntityList["Planet"]]

FormObject["switch" -> {"On"->True,"Off"->False}]

Choices can be any expression:

FormObject[{
"Filter" -> ImageEffect[],
"Image" ->Map[
ImageResize[ExampleData[#], {100, 100}] &, ExampleData["TestImage"][[1;;6]]
]
}]

Use a custom interpretation function:

toObject[s_String] /; ToUpperCase[s] == s := myObject[s];
toObject[s_] := Failure["InterpretationFailure",<|"MessageTemplate" -> "Please insert an uppercased string"|>];
FormObject[{"x" -> toObject}]["x" -> "abc"]

OpenersExampleSubsection4(Spacer1)Defaults  (1)

Specify a default for a field; fields that have a default are not required:

FormObject[{"first"->"String","second"->"Number"->3}]// Setting

Use (RefLink[RuleDelayed, paclet:ref/RuleDelayed]) to defer evaluation:

FormObject[{"date"->"DateTime" :> DateObject[]}] // Setting

OpenersExampleSubsection5(Spacer1)Input  (1)

Specify an initial value for a field:

FormObject["Start" -> <|"Input" -> "Initial text"|>]

Use (RefLink[RuleDelayed, paclet:ref/RuleDelayed]) to force a fresh evaluation every time the form is rendered:

FormObject["x" -> <|"Interpreter" -> Restricted["Number", {1, 100}], "Input" :> RandomInteger[{1, 100}], "Control" -> Slider|>]

OpenersExampleSubsection6(Spacer1)Controls  (2)

Different types have different controllers. Color pickers for "Color":

FormObject[{"x" ->"Color"}]

Or file pickers for file formats:

FormObject[{"x" ->"Image"}]

Checkboxes for "Boolean":

FormObject[{"x" ->"Boolean"}]

You can change the default controller:

FormObject[{"x" -><|"Interpreter" -> Restricted["Integer",{1,10}], "Control" -> Slider|>}]

Multiple choices support various types of controllers:

FormObject[<|"x"-><|"Interpreter"->{"A"->1,"B"->2,"C"->3}, "Control" -> RadioButtonBar|>|>]

FormObject[<|"x"-><|"Interpreter"->{"A"->1,"B"->2,"C"->3}, "Control" -> InputField, "Help" -> "Write A, B or C"|>|>]

The control specification also accepts pure functions:

FormObject[{"cat"-><|"Interpreter"->"String", "Control" -> Function[Tooltip[InputField[##], EntityValue[(Entity["domestic cat", Entity["Species","Species:FelisCatus"], "Entity[\"Species\", \"Species:FelisCatus\"]", "species specification"]),(EntityProperty["image", EntityProperty["Species","Image"], "EntityProperty[\"Species\", \"Image\"]"])]]]|>}]

OpenersExampleSubsection7(Spacer1)Label  (1)

Change the label for a field:

FormObject[{"x", "First Name"} -> "String"]

You can use (RefLink[RuleDelayed, paclet:ref/RuleDelayed]) and return any expression:

FormObject["pc" -> <|"Label" :> "PC: " <> $MachineID|>]

FormObject[
"pc" -> <|"Label" :> GeoGraphics[
$GeoLocation,
GeoRange->Quantity[100,"Meters"]
]|>
]

Use (RefLink[None, paclet:ref/None]) to remove the label:

FormObject["Query"-> <|"Label" -> None, "Hint" -> "Search"|>]

FormObject[{
"First"-> <|"Label" -> None, "Hint" -> "First Name"|>,
"Last" -><|"Label" -> None, "Hint" -> "Last Name"|>
}]

OpenersExampleSubsection8(Spacer1)Help  (1)

Define a help message:

FormObject["x" -> <|
"Interpreter"->Restricted["Number", {0, 100}],
"Help" -> "Enter a positive number lower than 100."
|>]

You can use (RefLink[RuleDelayed, paclet:ref/RuleDelayed]) and return any expression:

FormObject["City" -> <|
"Interpreter" :> Restricted["City", First @ GeoIdentify["Country"]],
"Help" :> "Enter your favorite city in "<> CommonName[First @ GeoIdentify["Country"]]
|>]

OpenersExampleSubsection9(Spacer1)Hint  (1)

Use "Hint" to display a hint inside the controller:

FormObject["x" -> <|
"Hint" -> "Enter your name"
|>]

OpenersExampleSubsection10(Spacer1)Masked  (1)

Use "Masked" to hide the input in the controller:

FormObject["x" -> <|
"Masked" -> True,
"Input" -> "ABC"
|>]

OpenersExampleSubsection11(Spacer1)Disambiguation  (1)

For strings that are interpreted from natural language in the Wolfram Cloud, sometimes results might be ambiguous:

FormObject["where" -> "City"]["where" -> "Springfield"]

Disambiguation is off for most types by default, but it can be easily activated:

FormObject["amount" -><|"Interpreter"->"Quantity", "Disambiguation" -> All|>]["amount" -> "2 ounces"]

OpenersExampleSection2(Spacer1)Generalizations & Extensions  (1)

You can use a form inside an (RefLink[XMLTemplate, paclet:ref/XMLTemplate]); HTML code will be generated:

form = FormObject[{"x" -> "String", "y" -> {100, 200, 300}}]

XMLTemplate["<form method='GET'><wolfram:slot id='form'/></form>"][<|"form"->form|>]

Extract metadata from a form and write a custom template:

XMLTemplate["<form method='GET'>
<wolfram:sequence values='Values[#form[All, \"Control\"]]'>
	<p>`1`</p>
</wolfram:sequence>
</form>"][<|"form"->form|>]

XMLTemplate["<form method='GET'>
<p><wolfram:expr>#form[\"x\", \"Control\"]</wolfram:expr></p>

<p class='label'><wolfram:expr>#form[\"y\", \"Label\"]</wolfram:expr></p>
<p><wolfram:expr>#form[\"y\", \"Control\"]</wolfram:expr></p>

</form>"][<|"form" -> form|>]

OpenersExampleSection3(Spacer1)Options  (2)

OpenersExampleSubsection12(Spacer1)AppearanceRules  (1)

Write a custom title and description:

FormObject["Start" -> "Country", AppearanceRules-><|"Title" -> "Where do you want to go?", "Description" -> "Enter a country and we will find you an accomodation"|>]

Use an image for branding:

FormObject["Product" -> {"Flyers", "Business cards", "Leflets"}, AppearanceRules-><|"Title" ->, "Description" -> "What do you want to print today?"|>]

Use an "ItemLayout" to change form fields' appearance:

FormObject[{"First" -> "String", "Second" -> "String"},  AppearanceRules-><|"ItemLayout" -> "Vertical"|>]

FormObject[{"First" -> <|"Help" ->  "Insert a value"|>, "Second" -> <|"Help" ->  "Insert a value"|>}, AppearanceRules-><|"ItemLayout" -> "Inline"|>]

OpenersExampleSubsection13(Spacer1)FormLayoutFunction  (1)

A pure function can be specified to give a specific layout to a form:

FormObject["x" -> "Integer", FormLayoutFunction->Function[Row[{#["x"], Graphics3D[Sphere[]]}]]]

OpenersExampleSection4(Spacer1)Applications  (1)

Use (RefLink[FormObject, paclet:ref/FormObject]) to validate data:

validator = FormObject[{"Date" -> Interpreter["StructuredDate", DateFormat->{"MonthNameShort", "Day", "Year"}], "Value" -> "Number"}];

Map[
Setting[validator[{"Date" -> First[#], "Value" -> Last[#]}]] &,
Import["ExampleData/financialtimeseries.csv"]
] // Short

OpenersExampleSection5(Spacer1)Properties & Relations  (2)

You can use a (RefLink[FormObject, paclet:ref/FormObject]) as the first argument of (RefLink[APIFunction, paclet:ref/APIFunction]) and (RefLink[FormFunction, paclet:ref/FormFunction]):

signupForm = FormObject[{"Name" -> "String", "Email" -> "EmailAddress", "Password" -> <|"Masked" -> True, "Default" :> Hash[AbsoluteTime[]], "Help" -> "Leave the field blank and a password will be generated"|>}, AppearanceRules-><|"Title" -> "Signup", "SubmitLabel" -> "Signup now!"|>];
CloudDeploy[FormFunction[signupForm, Identity]]

CloudDeploy[APIFunction[signupForm, Identity]]

The single fields of a (RefLink[FormObject, paclet:ref/FormObject]) use (RefLink[Interpreter, paclet:ref/Interpreter]) to transform the input in Wolfram Language expressions:

fo1 = FormObject["x" -> "Country"]

This is effectively the same as:

fo2 = FormObject["x" -> Interpreter["Country"]]

And the same as applying (RefLink[Interpreter, paclet:ref/Interpreter]) directly:

First[Setting[fo1["x" -> "france"]]] === First[Setting[fo2["x"-> "france"]]]=== Interpreter["Country"]["france"]

OpenersExampleSection6(Spacer1)Possible Issues  (1)

"Hint" and "Masked" are supported only by (RefLink[InputField, paclet:ref/InputField]):

FormObject[{
"x" -> <|
"Hint" -> "Enter your name"
|>,
"password" -> <|
"Masked" -> True,
"Input" -> "ABC"
|>}
]

"Hint" and "Masked" are ignored by other controllers:

FormObject[{
"x" -> <|
"Interpreter" -> "Color",
"Hint" -> "Enter your name"
|>,
"y" -> <|
"Interpreter" -> "Image",
"Masked" -> True
|>}
]

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(RefLink[Setting, paclet:ref/Setting])  ▪  (RefLink[FormFunction, paclet:ref/FormFunction])  ▪  (RefLink[Grid, paclet:ref/Grid])  ▪  (RefLink[XMLTemplate, paclet:ref/XMLTemplate])  ▪  (RefLink[Manipulate, paclet:ref/Manipulate])  ▪  (RefLink[RepeatingElement, paclet:ref/RepeatingElement])  ▪  (RefLink[CompoundElement, paclet:ref/CompoundElement])  ▪  (RefLink[FormControl, paclet:ref/FormControl])}})}})

({{DocumentationFooterIconsRelatedTutorial.png, ({{Tutorials}, {▪(RefLinkPlain[Advanced Web Form Creation, paclet:tutorial/AdvancedWebFormCreation])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Control Objects, paclet:guide/ControlObjects])}, {▪(RefLinkPlain[Creating Form Interfaces & Apps, paclet:guide/CreatingFormsAndApps])}, {▪(RefLinkPlain[Setting Up Input Interpreters, paclet:guide/InterpretingStrings])}, {▪(RefLinkPlain[Web Operations, paclet:guide/WebOperations])}, {▪(RefLinkPlain[Setting Up User Interactions, paclet:guide/SettingUpUserInteractions])}, {▪(RefLinkPlain[Form Structure & Layout, paclet:guide/FormStructureAndLayout])}})}})

({{(Spacer1), ({{(Spacer1)Related Links}, {(WebLink[DocumentationFooterIconsRelatedLinks-EIWL.png(Spacer1)An Elementary Introduction to the Wolfram Language, https://www.wolfram.com/language/elementary-introduction/36-creating-websites-and-apps.html])(WebLink[: Creating Websites and Apps, https://www.wolfram.com/language/elementary-introduction/36-creating-websites-and-apps.html])}})}})