WOLFRAM

Wolfram Language & System Documentation Center
Wolfram Language Home Page »

FormObject   

Listing of Field Types »

✖
FormObject[{"name1"type1,"name2"type2,…}]

represents a form with fields having names namei that take data of type typei.

✖
FormObject[{{"name1",label1}type1,…}]

uses labeli as the label for the field named namei.

✖
FormObject[{"name1"assoc1,…,objj,…}]

uses full specification associ for a field, and objj 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 "namei"->associ. The elements of the full specification associ 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 <|"name1"->val1,…|>, where the vali are the values obtained by interpreting the "Input" element associated with each "namei" according to the "Interpreter" associated with the "namei".
  • If "Input" is missing, or "Interpreter" fails, then the value of "Value" is a Failure object.
  • FormObject[…][<|"name1"->input1,…|>] yields a FormObject[…] in which the "Input" corresponding to each of the namei included has been replaced with inputi.
  • In FormObject[{…,objj,…}], the objj 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[{"name1"->type1,…}], the typei 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
    tfunany function to be applied to the raw input
  • If only "namei" is given, without a rule giving typei, 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 "namei"->AutoSubmitting[typei] indicates that when the field associated with namei 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 Automaticassociation giving overall appearance rules
    FormLayoutFunction Automaticfunction to generate final layout for the form
    PageThemeAutomaticoverall theme to use when the page is deployed
  • Typical elements in the setting for AppearanceRules include:
  • "Title"Noneoverall title for the form
    "Description"Nonedescription to include at the top of the form
    "RequiredFieldIndicator"Noneindicator 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 allclose all

Basic Examples  (3)Summary of the most common use cases

Create an unfilled form:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-25oi2r
Out[1]=1
In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-ymq25

Specify inputs for the form as strings:

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-w50o4p
Out[2]=2

Find the inputs that have been provided for the form:

In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-p1sc90
Out[3]=3

The number has been parsed to an explicit number:

In[4]:=4
✖
https://wolfram.com/xid/0e7nnqmq-r18kl9

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

In[5]:=5
✖
https://wolfram.com/xid/0e7nnqmq-rlfp8b
Out[5]=5

The setting contains a symbolic failure object:

In[6]:=6
✖
https://wolfram.com/xid/0e7nnqmq-9nhbrr
Out[6]=6

Use different controls:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-6gz35p
Out[1]=1

Scope  (17)Survey of the scope of standard use cases

FormObject Structure  (1)

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-mgv4fp

Form Submit  (1)

A form is submitted with subvalues:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-s8evso
Out[1]=1

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

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-wz09sp

Form metadata  (3)

You can extract form meta with subvalues:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-iwcxgh
Out[1]=1

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

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-597dmm
Out[2]=2

"Control" gives you the default formatted controller:

In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-qidokk
Out[3]=3

Use "Failure" to get the failure:

In[4]:=4
✖
https://wolfram.com/xid/0e7nnqmq-jv89be
Out[4]=4

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

In[5]:=5
✖
https://wolfram.com/xid/0e7nnqmq-4eymu3
Out[5]=5

You can extract AppearanceRules in the same way:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-omtl3n
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-5eueht
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-ojxmhj
Out[3]=3
In[4]:=4
✖
https://wolfram.com/xid/0e7nnqmq-159347
Out[4]=4

Use Setting to extract the cleaned data:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-2k0tjr
Out[1]=1

You can perform several submissions with partial data:

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-gkvdrs
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-vz2zgx
Out[3]=3

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

In[4]:=4
✖
https://wolfram.com/xid/0e7nnqmq-ob0iur
Out[4]=4

Interpreter Specifications  (3)

Use rich Interpreter specifications:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-fv3l5m
Out[1]=1

A list can be used to create a menu:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-i8c7yw
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-e3ttsv
Out[2]=2

Choices can be any expression:

In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-4p625p
Out[3]=3

Use a custom interpretation function:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-zjoadk
Out[1]=1

Defaults  (1)

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-oecudv
Out[1]=1

Use RuleDelayed to defer evaluation:

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-fnvuat
Out[2]=2

Input  (1)

Specify an initial value for a field:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-2hxlxl
Out[1]=1

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

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-uttt1v
Out[2]=2

Controls  (2)

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-mrupb9
Out[1]=1

Or file pickers for file formats:

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-5ac68s
Out[2]=2

Checkboxes for "Boolean":

In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-fo24kj
Out[3]=3

You can change the default controller:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-22y8yu
Out[1]=1

Multiple choices support various types of controllers:

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-bdwfhl
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-b3s5mh
Out[3]=3

The control specification also accepts pure functions:

In[4]:=4
✖
https://wolfram.com/xid/0e7nnqmq-ty4yyt
Out[4]=4

Label  (1)

Change the label for a field:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-fe40vb
Out[1]=1

You can use RuleDelayed and return any expression:

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-2ar7k
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-hd0omk
Out[3]=3

Use None to remove the label:

In[4]:=4
✖
https://wolfram.com/xid/0e7nnqmq-w510a4
Out[4]=4
In[5]:=5
✖
https://wolfram.com/xid/0e7nnqmq-5ylswd
Out[5]=5

Help  (1)

Define a help message:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-2ozve5
Out[1]=1

You can use RuleDelayed and return any expression:

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-inxuzr
Out[2]=2

Hint  (1)

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-ynxnpk
Out[1]=1

Masked  (1)

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-d7xj4s
Out[1]=1

Disambiguation  (1)

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-1mhcla
Out[1]=1

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

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-gk1z1s
Out[2]=2

Generalizations & Extensions  (1)Generalized and extended use cases

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-ykekr7
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-if24yq
Out[2]=2

Extract metadata from a form and write a custom template:

In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-moajbl
Out[3]=3
In[4]:=4
✖
https://wolfram.com/xid/0e7nnqmq-b1a4ar
Out[4]=4

Options  (2)Common values & functionality for each option

AppearanceRules  (1)

Write a custom title and description:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-lc50lb
Out[1]=1

Use an image for branding:

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-y6kz35
Out[2]=2

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

In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-1sw2kb
Out[3]=3
In[4]:=4
✖
https://wolfram.com/xid/0e7nnqmq-4w5qpc
Out[4]=4

FormLayoutFunction  (1)

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-jyf1do
Out[1]=1

Applications  (1)Sample problems that can be solved with this function

Use FormObject to validate data:

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-nbqz3i

Properties & Relations  (2)Properties of the function, and connections to other functions

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-28wuvl
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-oagbeb
Out[2]=2

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-pwx7ot
Out[1]=1

This is effectively the same as:

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-me9ej6
Out[2]=2

And the same as applying Interpreter directly:

In[3]:=3
✖
https://wolfram.com/xid/0e7nnqmq-02zt3a
Out[3]=3

Possible Issues  (4)Common pitfalls and unexpected behavior

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-vsv3hh
Out[1]=1

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

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-pu5na0
Out[2]=2

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-mbtkrt
Out[1]=1

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

In[2]:=2
✖
https://wolfram.com/xid/0e7nnqmq-0n4v3e
Out[2]=2

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-g5343r
Out[1]=1

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

In[1]:=1
✖
https://wolfram.com/xid/0e7nnqmq-crd3ez
Out[1]=1
Wolfram Research (2014), FormObject, Wolfram Language function, https://reference.wolfram.com/language/ref/FormObject.html.
✖
Wolfram Research (2014), FormObject, Wolfram Language function, https://reference.wolfram.com/language/ref/FormObject.html.

Text

Wolfram Research (2014), FormObject, Wolfram Language function, https://reference.wolfram.com/language/ref/FormObject.html.

✖
Wolfram Research (2014), FormObject, Wolfram Language function, https://reference.wolfram.com/language/ref/FormObject.html.

CMS

Wolfram Language. 2014. "FormObject." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/FormObject.html.

✖
Wolfram Language. 2014. "FormObject." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/FormObject.html.

APA

Wolfram Language. (2014). FormObject. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/FormObject.html

✖
Wolfram Language. (2014). FormObject. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/FormObject.html

BibTeX

@misc{reference.wolfram_2025_formobject, author="Wolfram Research", title="{FormObject}", year="2014", howpublished="\url{https://reference.wolfram.com/language/ref/FormObject.html}", note=[Accessed: 18-April-2025 ]}

✖
@misc{reference.wolfram_2025_formobject, author="Wolfram Research", title="{FormObject}", year="2014", howpublished="\url{https://reference.wolfram.com/language/ref/FormObject.html}", note=[Accessed: 18-April-2025 ]}

BibLaTeX

@online{reference.wolfram_2025_formobject, organization={Wolfram Research}, title={FormObject}, year={2014}, url={https://reference.wolfram.com/language/ref/FormObject.html}, note=[Accessed: 18-April-2025 ]}

✖
@online{reference.wolfram_2025_formobject, organization={Wolfram Research}, title={FormObject}, year={2014}, url={https://reference.wolfram.com/language/ref/FormObject.html}, note=[Accessed: 18-April-2025 ]}