Wolfram Language & System Documentation Center

FormObject   

Listing of Field Types »

FormObject[{"name₁"type₁,"name₂"type₂,…}]

represents a form with fields having names name_i that take data of type type_i.

FormObject[{{"name₁",label₁}type₁,…}]

uses label_i as the label for the field named name_i.

FormObject[{"name₁"assoc₁,…,obj_j,…}]

uses full specification assoc_i for a field, and obj_j as part of the layout of the form.

Details and Options

FormObject[…] displays in a notebook interface as a form with fields that can be filled in, either by entering text or using other controls.
FormObject can be used to specify the structure of a form in FormFunction.
When evaluated, FormObject[…] is converted to FormObject[fields], in which each entry in fields has a full specification of the form "name_i"->assoc_i. The elements of the full specification assoc_i include:

	"Input"	the raw input, if any, for the field (often a string)
	"Interpreter"	the interpreter to be used for the field
	"Required"	whether input is required for the field
	"Default"	a default value, if any, for the field
	"Control"	the type of control to provide for the field
	"AutoSubmitting"	whether entering the field automatically submits the form
	"Disambiguation"	whether to ask for disambiguation of interpretations
	"Label"	a label to display for the field
	"Hint"	hint to display inside an input field
	"Masked"	whether to mask input given in an input field
	"Help"	help to associate with the field

Setting[FormObject[…]] gives an association of the form <|"name₁"->val₁,…|>, where the val_i are the values obtained by interpreting the "Input" element associated with each "name_i" according to the "Interpreter" associated with the "name_i".
If "Input" is missing, or "Interpreter" fails, then the value of "Value" is a Failure object.
FormObject[…][<|"name₁"->input₁,…|>] yields a FormObject[…] in which the "Input" corresponding to each of the name_i included has been replaced with input_i.
In FormObject[{…,obj_j,…}], the obj_j can be Delimiter, representing a horizontal delimiter.
They can also be expressions with heads Style, Row, Item, Text, ExpressionCell, and TextCell, as well as views and layout constructs such as TabView and Grid.
In FormObject[{"name₁"->type₁,…}], the type_i are used to give values for "Interpreter" in the full specification.
Possible forms of type specifications are:

	"form"	any form supported by Interpreter
	Restricted[…],etc.	any restricted form etc. supported by Interpreter
	Interpreter[…]	any complete Interpreter object
	tfun	any function to be applied to the raw input

If only "name_i" is given, without a rule giving type_i, then the interpreter is assumed to be 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 "String", a single line of input is by default expected on the web; typing "Text" yields a multiline text field.
Possible controls explicitly given as the value associated with "Control" include InputField, PopupMenu, Slider, and RadioButtonBar.
The specification "name_i"->AutoSubmitting[type_i] indicates that when the field associated with name_i is entered, the whole form should automatically be submitted.
FormObject[AutoSubmitting[spec]] indicates that a form should automatically be submitted whenever any of its fields are entered.
Overall options for FormObject include:

AppearanceRules	Automatic	association giving overall appearance rules
FormLayoutFunction	Automatic	function to generate final layout for the form
PageTheme	Automatic	overall theme to use when the page is deployed

Typical elements in the setting for AppearanceRules include:

"Title"	None	overall title for the form
"Description"	None	description to include at the top of the form
"RequiredFieldIndicator"	None	indicator to show required fields
"SubmitLabel"	"Submit"	text for the submit button of the form
"AddLabel"	"+"	text of the add button for repeating elements
"DeleteLabel"	"-"	text of the delete button
"AddTooltip"	"Add"	tooltip for the add button
"DeleteTooltip"	"Remove"	tooltip for the delete button
"NextLabel"	"Next"	text of the "next" button for multipage forms
"ItemLayout"	"Horizontal"	layout of field labels and messages

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

Examples

open all close all

Basic Examples (1)

Create an unfilled form:

Wolfram Language code: form = FormObject[{"first" -> "String", "second" -> "Number"}]

Specify inputs for the form as strings:

Wolfram Language code: form[<|"first" -> "a string", "second" -> "444"|>]

Find the inputs that have been provided for the form:

Wolfram Language code: Setting[%]

The number has been parsed to an explicit number:

Wolfram Language code: InputForm[%]

Scope (19)

Create an unfilled form:

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

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

Wolfram Language code: form[<|"first" -> "a string", "second" -> "not a number"|>]

The setting contains a symbolic failure object:

Wolfram Language code: Setting[%]

Use different controls:

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

FormObject Structure (1)

A valid FormObject evaluates to an object with an Association with all meta-information:

Wolfram Language code: FormObject["x" -> "Number" -> 3]//InputForm

Form Submit (1)

A form is submitted with subvalues:

Wolfram Language code: 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:

Wolfram Language code: FormObject["x" -> "Number"]["x" -> "2"]//InputForm

Form metadata (3)

You can extract form meta with subvalues:

Wolfram Language code:

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

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

Wolfram Language code: form["x", "Interpreter"]

"Control" gives you the default formatted controller:

Wolfram Language code: form["x", "Control"]

Use "Failure" to get the failure:

Wolfram Language code: form["x", "Failure"]

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

Wolfram Language code: form["x"]

You can extract AppearanceRules in the same way:

Wolfram Language code:

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

Wolfram Language code: form[AppearanceRules, "Title"]

Wolfram Language code: form[AppearanceRules, "ItemLayout"]

Wolfram Language code: form[PageTheme]

Use Setting to extract the cleaned data:

Wolfram Language code: FormObject["x" -> "Integer"]//Setting

You can perform several submissions with partial data:

Wolfram Language code: FormObject[{"x" -> "Integer", "y" -> "Integer"}]["x" -> "2"]//Setting

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

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

Wolfram Language code: FormObject["x" -> "Integer" -> 3]//Setting

Interpreter Specifications (3)

Use rich Interpreter specifications:

Wolfram Language code: FormObject[{"x" -> Restricted["Integer", {1, 10}]}][{"x" -> "23"}]

A list can be used to create a menu:

Wolfram Language code: FormObject["x" -> EntityList["Planet"]]

Wolfram Language code: FormObject["switch" -> {"On" -> True, "Off" -> False}]

Choices can be any expression:

Wolfram Language code:

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

Use a custom interpretation function:

Wolfram Language code:

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

Defaults (1)

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

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

Use RuleDelayed to defer evaluation:

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

Input (1)

Specify an initial value for a field:

Wolfram Language code: FormObject["Start" -> <|"Input" -> "Initial text"|>]

Use RuleDelayed to force a fresh evaluation every time the form is rendered:

Wolfram Language code:

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

Controls (2)

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

Wolfram Language code: FormObject[{"x" -> "Color"}]

Or file pickers for file formats:

Wolfram Language code: FormObject[{"x" -> "Image"}]

Checkboxes for "Boolean":

Wolfram Language code: FormObject[{"x" -> "Boolean"}]

You can change the default controller:

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

Multiple choices support various types of controllers:

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

Wolfram Language code:

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

The control specification also accepts pure functions:

Wolfram Language code:

FormObject[{"cat" -> <|"Interpreter" -> "String", "Control" -> Function[Tooltip[InputField[##], EntityValue[Entity["Species", "Species:FelisCatus"], EntityProperty["Species", "Image"]]]]|>}]

Label (1)

Change the label for a field:

Wolfram Language code: FormObject[{"x", "First Name"} -> "String"]

You can use RuleDelayed and return any expression:

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

Wolfram Language code:

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

Use None to remove the label:

Wolfram Language code: FormObject["Query" -> <|"Label" -> None, "Hint" -> "Search"|>]

Wolfram Language code:

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

Help (1)

Define a help message:

Wolfram Language code:

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

You can use RuleDelayed and return any expression:

Wolfram Language code:

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

Hint (1)

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

Wolfram Language code:

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

Masked (1)

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

Wolfram Language code:

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

Disambiguation (1)

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

Wolfram Language code: FormObject["where" -> "City"]["where" -> "Springfield"]

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

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

Generalizations & Extensions (1)

You can use a form inside an XMLTemplate; HTML code will be generated:

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

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

Extract metadata from a form and write a custom template:

Wolfram Language code:

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

Wolfram Language code:

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|>]

Options (2)

AppearanceRules (1)

Write a custom title and description:

Wolfram Language code:

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:

Wolfram Language code:

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

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

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

Wolfram Language code:

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

FormLayoutFunction (1)

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

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

Applications (1)

Use FormObject to validate data:

Wolfram Language code:

validator = FormObject[{"Date" -> Interpreter["StructuredDate", DateFormat -> {"MonthNameShort", "Day", "Year"}], "Value" -> "Number"}];
	
Map[
	Setting[validator[{"Date" -> First[#], "Value" -> Last[#]}]]&, 
	Import["ExampleData/financialtimeseries.csv"]
	]//Short

Properties & Relations (2)

You can use a FormObject as the first argument of APIFunction and FormFunction:

Wolfram Language code:

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]]

Wolfram Language code: CloudDeploy[APIFunction[signupForm, Identity]]

The single fields of a FormObject use Interpreter to transform the input in Wolfram Language expressions:

Wolfram Language code: fo1 = FormObject["x" -> "Country"]

This is effectively the same as:

Wolfram Language code: fo2 = FormObject["x" -> Interpreter["Country"]]

And the same as applying Interpreter directly:

Wolfram Language code: First[Setting[fo1["x" -> "france"]]] === First[Setting[fo2["x" -> "france"]]] === Interpreter["Country"]["france"]

Possible Issues (4)

"Hint" and "Masked" are supported only by InputField:

Wolfram Language code:

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

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

Wolfram Language code:

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

When using Alternatives in the Interpreter type, one might get the wrong controller:

Wolfram Language code: FormObject["x" -> "JSON" | "String"]

Explicitly setting the "Control" field can fix the problem:

Wolfram Language code:

FormObject["x" -> <|
	"Interpreter"  -> "JSON" | "String", 
	"Control" -> InputField
	|>]

FormObject is an inert representation of the form specification; as such, buttons in it do not work:

Wolfram Language code: FormObject["x" -> RepeatingElement["String"]]

When the Interpreter type is not of a form that supports lists, only the last element will be kept:

Wolfram Language code: FormObject["x" -> "Integer"]["x" -> {"1", "2", "3"}]

Top

FormObject

Details and Options

Examples

Basic Examples (1)

Scope (19)

FormObject Structure (1)

Form Submit (1)

Form metadata (3)

Interpreter Specifications (3)

Defaults (1)

Input (1)

Controls (2)

Label (1)

Help (1)

Hint (1)

Masked (1)

Disambiguation (1)

Generalizations & Extensions (1)

Options (2)

AppearanceRules (1)

FormLayoutFunction (1)

Applications (1)

Properties & Relations (2)

Possible Issues (4)

See Also

Tech Notes

Related Guides

Related Links

History

Text

CMS

APA

BibTeX

BibLaTeX

FormObject   