Form

Form object that displays a set of input fields for data entry and editing.

The form can be connected to a datasource or populated with a set of items.

Form fields can also be submitted by an external button with action=submit, according to the button's container/page scope.

Attributes

Common

ID

Sets the object's ID.

The ID identifies the object and is used to reference it in UISet actions, allowing to change its attributes dynamically.

The ID is not unique, it can be shared among multiple objects to quickly change a common attribute.

IDs can't be changed with a UISet action, but they can have a Value Binding assigned to them. Value Bindings on IDs allow an object to be dinamically attached to a set of attribute values.

E.g. the following Value Binding switches the ID of the object between mybutton1 and mybutton2 based on the value of the UISet button.address:

Value binding:

="mybutton" + ui('button', 'address')

UISet:

UISet('button', 'address', '1') switches the ID to mybutton1

UISet('button', 'address', '2') switches the ID to mybutton2

Position and Size

Position

Sets the object's position.

Attribute Values

Value	Description	Example
x<left>y<top>	Specify left/top coordinates in pixels.	x10y20

This attribute is available when parent's layout is neither "flex" nor "grid".

When parent's layout is neither "flex" nor "grid", this attribute defaults to x0y0.

Flex Grow

Specifies if the objects should grow to fill the available space.

Attribute Values

Value	Description
false	Default value. Objects do not grow to fill the available space.
true	Objects expand to fill the available space.

This attribute is available when parent's layout is "flex".

The default value is: false.

Flex Shrink

Specifies if the objects should shrink to fit the available space.

Attribute Values

Value	Description
false	Default value. Objects do not shrink to fit the available space.
true	Objects shrink to fit the available space.

This attribute is available when parent's layout is "flex".

The default value is: false.

Column

Specifies the starting column of the object inside a grid container.

Minimum value is 1.

Attribute Values

Value	Description
<int>	Column index starting from 1.

This attribute is available when parent's layout is "grid".

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Column Span

Specifies how many grid columns the object spans.

Minimum value is 1.

Attribute Values

Value	Description
<int>	Column span starting from 1.

This attribute is available when parent's layout is "grid".

When parent's layout is "grid", this attribute defaults to 1.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Row

Specifies the starting row of the object inside a grid container.

Minimum value is 1.

Attribute Values

Value	Description
[empty]	Auto placement by the grid.
<int>	Row index starting from 1.

This attribute is available when parent's layout is "grid".

When parent's layout is "grid", this attribute defaults to auto.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Row Span

Specifies how many grid rows the object spans.

Minimum value is 1.

Attribute Values

Value	Description
<int>	Row span starting from 1.

This attribute is available when parent's layout is "grid".

When parent's layout is "grid", this attribute defaults to 1.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Width

Sets the object's width in pixels.

Minimum value is 120.

Height

Sets the object's height in pixels.

Minimum value is 120.

Form

Items

Specifies the form items used to build the form. Each item can declare fields, titles, spacers and other UI elements.

In items mode, field items also provide the form's data mapping through the Data Name attribute.

Attribute Values

Value	Description
<JSON Array>	Form item definitions.

Submit Button

Specifies whether to display the submit button. Fields can also be submitted by an external button with action=submit in the same container/page scope.

Attribute Values

Value	Description
true	Default value. The submit button is displayed.
false	The submit button is not displayed.

The default value is: true.

Submit Button Label

Specifies the label displayed on the submit button.

Attribute Values

Value	Description
<string>	Label text.

This attribute is available when submitbutton is "true".

Feedback

If feedback is enabled, when the action is performed, a loader is displayed until the server responds.

Also the action can't be performed again until the server responds.

Attribute Values

Value	Description
false	Default value. Feedback is disabled.
true	Feedback is enabled.

This attribute is available when submitbutton is "true".

The default value is: false.

Confirm Message

The confirmation message to be displayed if the "confirm" attribute is set to "popup".

Attribute Values

Value	Description	Example
<string>	The message to be displayed in the confirm popup.	Are you sure?

This attribute is available when submitbutton is 'true'and (confirm=='popup').

Data

Data Mode

Specifies the object's data mode, which controls the way the form's data is populated.

In items mode, the data is populated with a uiSet of the values attribute. In datasource mode, the data is populated from a datasource.

In datasource mode, the form values are refreshed when the form or its page become visible.

While the form is visible and enabled, later datasource value refreshes do not overwrite the fields automatically, to avoid changing values while the user is editing. If the datasource columns change, the form is rebuilt and the datasource values are applied. If the form is disabled, datasource refreshes are applied to the visible fields.

To force a refresh from the datasource for the current row, send the Data Key again, even with the same value.

Attribute Values

Value	Description
items	Default value. Data is populated using the "items" attribute.
datasource	Data is populated with a datasource.

The default value is: items.

note

This attribute is static. Its value can't be changed dynamically with a uiSet command or with a value binding.

Datasource ID

The ID of the datasource to which the form is connected.

Attribute Values

Value	Description
[Datasource ID]	The datasource ID as defined on the server.

This attribute is available when datamode is "datasource".

Command Name

Specifies the command name that is sent to the server.

If the name starts with $, then the server will automatically set a variable with the same name as the command, containing the command's parameter.

Attribute Values

Value	Description	Example
<string>	A command name.
$[variable name]	A command name that sets a variable.	$myvar
$[variable name]!	A command name that sets a persistent variable.	$myvar!

This attribute is available when submitbutton is "true".

When submitbutton is "true", this attribute defaults to the id attribute.

Values

Specifies the form's data as a JSON object. The keys of the object correspond to the Data Name attributes of the form items.

In items mode, this provides the form's data directly. In datasource mode with an empty Data Key, this provides initial/default values for add or duplicate operations (e.g., pre-filling fields when duplicating a row).

Use an empty string to clear all the fields' values.

Attribute Values

Value	Description	Example
<text>	A JSON object representing the form's data.	{ "firstName": "John", "lastName": "Doe" }
[empty]	Clears all field values.

This attribute is available when datamode is "items" or datakey is empty.

Data Key

In datasource mode, specifies the key of the datasource row to be edited. In items mode (when using add or edit commands), acts as a semantic identifier to distinguish between add and edit operations.

If empty, the form is in "add" mode, otherwise it's in "edit" mode. If a list of keys is specified (comma-separated), the form is in "multi-edit" mode.

In datasource mode, sending the same key again forces the form to reload the values for that row.

Attribute Values

Value	Description
<string>	The key identifier (datasource row key or semantic identifier).

Commands

Specifies the set of commands that are sent to the server when the user performs specific actions.

The submit command sends the fields as parameters, and can be handled with the userSubmit callback. All other commands are sent with a JSON parameter containing the action and field values, and can be handled with userCommand callbacks.

Each command is sent with the name specified in the Command Name attribute, or form's ID, and a JSON parameter based on the command type.

The reply of the edit-change command can specify a JSON with a fields property, which applies changes to the form's fields. Each field is identified by its name (or index starting from 1, if in items mode), and the properties are a selection of the column attributes. Note: some attributes trigger a redraw of the form. The following attributes can be specified:

• type - the field type (redraws the form)
• visible - whether the field is visible (redraws the form)
• value - the value of the field
• enabled - whether the field is enabled
• placeholder - the placeholder of the field
• readonly - whether the field is readonly
• items - the items of a select field in "items" mode
• list - the items of a select field in "list" mode
• prefix - the prefix of the field
• suffix - the suffix of the field
• clearbutton - whether the clear button is visible
• required - whether the field is required
• focustooltip - the tooltip of the field when focused
• error - set or clear the field error state (true, false, or an error message string)
• multienabled - if multiple rows are being edited, whether the field is checked for editing

E.g. { "fields": { "field1": { "value": "new value", "enabled": "false", "type": "select", ... }, ... } }

All standard command reply parameters are also supported (page, error, etc.).

Inline buttons (fitem with type=inline-button and action=command) are sent through the same command channel. Their payload is edit-change-like and includes form context: { "action": "command", "field": "<field>", "key": "<row key>", "values": { "<field>": "<value>", ... }, "button": "<button name>" } For multi-edit, keys replaces key.

Attribute Values

Value	Description
add	Sends a command when the user inserts a row (confirms the add). This command is triggered when the Data Key attribute is empty. The command parameter is a JSON: { "action": "add", "data": { "<field name>": "<value>", ... } } The data property is a JSON containing the values of the fields of the inserted row.
edit	Sends a command when the user updates a row (confirms the edit). This command is triggered when the Data Key attribute is set. The command parameter is a JSON: { "action": "edit", "key": "<row key>", "data": { "<field name>":"<value>", ... } } The key property is the key of the updated row. The data property is a JSON containing the values of the fields of the updated row. For multiple row updates, the key property is replaced by the keys property, which is an array of keys: { "action": "edit", "keys": ["<row key>", ...], "data": { "<field name>": "<value>", ... } } For inline edits (datasource mode only), an inline property is added to the command parameter: { "action": "edit", "key": "<row key>", "field": "<field name>", "value": "<value>", "inline": "true" }.
edit-change	Sends a command when the user changes the value of a field. The command includes the key if any, the id of the edited field and the current values of all fields, including disabled ones. In multi-edit mode if a field has multiple values (and the field's edit checkbox is not checked), a null value is sent. Command parameter: { "action": "edit-change", "key": "<row key>", "field": "<field name>", "values": { "<field name>": "<value>", ... } } The key property is the key of the edited row. For multiple row updates, the key property is replaced by the keys property, which is an array of keys: { "action": "edit-change", "keys": ["<row key>", ...], "field": "<field name>", "values": { "<field name>": "<value>", ... } } For inline edits, an inline property is added to the command parameter: { "action": "edit-change", "key": "<row key>", "field": "<field name>", "value": "<value>", "inline": "true" } In the JSON reply, the server can specify UISets for specific edit fields attributes: { "fields": { "<field name>": { "value": "value", "enabled": "false", "type":"select", ... }, ... } }.
submit	Sends a submit command when the user submits the form, with the values of the fields as parameters. Disabled fields are not sent unless their Save Value is true. Available in both datasource and items modes. Can be handled with the userSubmit callback.

note

This attribute is static. Its value can't be changed dynamically with a uiSet command or with a value binding.

Layout

Layout

Specifies the layout of the form items.

Attribute Values

Value	Description
basic	Default value. All items are displayed in a single column.
tabs	Items are grouped into tabs.
steps	Items are grouped into steps.

The default value is: basic.

Tab Labels

Specifies the labels of the tabs, separated by comma.

Attribute Values

Value	Description	Example
<string>	Comma-separated list of tab labels.	Tab1,Tab2,Tab3

This attribute is available when layout is "tabs".

Step Labels

Specifies the labels of the steps, separated by comma.

Attribute Values

Value	Description	Example
<string>	Comma-separated list of step labels.	Step1,Step2,Step3

This attribute is available when layout is "steps".

Label Position

Specifies the position of the labels in relation to the edit fields.

Attribute Values

Value	Description
left	Default value. Labels are displayed to the left of the edit fields.
top	Labels are displayed above the edit fields.
hidden	Labels are not displayed.

The default value is: left.

Field Height

Specifies the default height of the form fields in pixels.

Minimum value is 16.

Attribute Values

Value	Description
<int>	Height in pixels.

The default value is: 24.

Field Error Display

Specifies the default display mode for the form fields' error messages.

Attribute Values

Value	Description
tooltip	Default value. Display field error messages as tooltips.
inline	Display field error messages under the field.

The default value is: tooltip.

Padding

Specifies the inner padding of the form content area in pixels.

Minimum value is 0.

Attribute Values

Value	Description
<int>	Padding in pixels.

The default value is: 12.

Reset Button

Specifies whether to display the reset button.

Attribute Values

Value	Description
true	The reset button is displayed.
false	Default value. The reset button is not displayed.

The default value is: false.

Display Legend

Specifies whether to display the form's legend.

Attribute Values

Value	Description
true	Default value. The legend is displayed.
false	The legend is not displayed.

The default value is: true.

Legend

Specifies the legend text displayed at the bottom of the form. By default it displays "* Required" when there are required fields in the form.

Attribute Values

Value	Description
<string>	Legend text.

This attribute is available when displaylegend is "true".

Panel

Panel

Shows a panel that frames the object. Its style can be modified.

Attribute Values

Value	Description
true	Default value. Shows the panel.
false	Hides the panel.

The default value is: true.

Panel Color

Specifies the panel color.

Attribute Values

Value	Description
default	Default color.
primary	Primary color, used to highlight important areas.
warning	Warning color, used to highlight warning areas.
success	Success color, used to highlight success areas.
error	Error color, used to highlight error areas.
red,blue,yellow,green,yellow,purple,orange,green	Palette colors.
custom	Custom color, defined in the "Custom Color" attribute.

This attribute is available when panel is "true".

When panel is "true", this attribute defaults to true.

Panel Custom Color

Specifies the panel custom color.

Attribute Values

Value	Description	Example
<html color>	Color in any html accepted format.	#ff0000

This attribute is available when panelstyle is "custom" or panelstyle is "glass" or panelcolor is "custom".

When panelstyle is "custom" or panelstyle is "glass" or panelcolor is "custom", this attribute defaults to true.

View

Visible

Sets the object's visibility.

Attribute Values

Value	Description
true	Default value. Visible.
false	Hidden.

The default value is: true.

Enabled

Specifies if the object is enabled or disabled. A disabled object appears as grayed out and can't be interacted with.

Attribute Values

Value	Description
true	Default value. Enabled.
false	Disabled.

The default value is: true.

Blink

Blinks the object at the specified speed.

Attribute Values

Value	Description
false	Default value. Not blinking.
slow	Blinks slowly.
fast	Blinks fast.

The default value is: false.

Transition

Specifies the transition effect when the object is shown or hidden.

Attribute Values

Value	Description
none	Default value. No transition.
fade	Fade in/out.
fade-left	Slide from left and fade in/out.
fade-right	Slide from right and fade in/out.
fade-up	Slide from top and fade in/out.
fade-down	Slide from bottom and fade in/out.
slide-left	Slide from left.
slide-right	Slide from right.
slide-up	Slide from top.
slide-down	Slide from bottom.
zoom-in	Zoom in.
zoom-out	Zoom out.
3d-flip-left	3D flip from left.
3d-flip-right	3D flip from right.

The default value is: none.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Transition Duration

Specifies the transition duration in milliseconds.

Attribute Values

Value	Description
<integer>	Duration in milliseconds.

This attribute is available when transition is not "none".

When transition is not "none", this attribute defaults to 300.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Transition Delay

Specifies the transition delay in milliseconds.

Attribute Values

Value	Description
<integer>	Delay in milliseconds.

This attribute is available when transition is not "none".

When transition is not "none", this attribute defaults to 0.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Opacity

Sets the object's opacity. Opacity is the degree to which content behind an object is hidden.

Attribute Values

Value	Description
0	The object is fully transparent.
>0.0, <1.0	The object is translucent (content behind the element can be seen).
1.0	Default value. The object is fully opaque.

The default value is: 1.0.

Rotation

Specifies the degrees by which the object is rotated. A positive number rotates it clockwise, while a negative value rotates it counter-clockwise.

The default value is: 0.

CSS Class

Specifies a CSS Class that applies to the object, useful to customize its appearance. Custom CSS Classes are specified within the custom.css file.

Margin

Specifies the margin of the object. The margin is the space outside the object's border.

Attribute Values

Value	Description	Example
<int>	Specify the margin in pixels for all sides of the object.
<top> <right> <bottom> <left>	Specify the margin in pixels for each side of the object.	10 20 30 40

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

View Scale

Specifies the scale of the object. The scale is the ratio between the object's size and the size of the view it is contained in.

Attribute Values

Value	Description
<float>	Specify the scale for both width and height of the object.

The default value is: 1.0.

note

This attribute is experimental. It might not work properly and it might be modified or removed in a future release.

Meta

Comment

Specifies a comment, visible only in the Project Editor. It can be used to add a note or a tag to the object. The filter in the object's SELECT panel applies to the comment as well.

note

This attribute is static. Its value can't be changed dynamically with a uiSet command or with a value binding.

Exclude

Excludes the object from the UI. Useful to temporarily hide an object without deleting it. Different from the "Visible" attribute, which hides the object in the UI but keeps it in the project, allowing it to be shown again with a UISet.

Attribute Values

Value	Description
false	Default value. Object is included in the UI.
true	Object is excluded from the UI.

The default value is: false.

note

This attribute is static. Its value can't be changed dynamically with a uiSet command or with a value binding.