Input Block – a field the user edits¶
The input block binds to one field of the record and shows a control for it – a text box, a date picker, a switch, a list, a rich text editor and more. It is what makes a form a place to edit data rather than to look at it.
This page is part of the form block reference.
1. At a glance¶
| Purpose | Shows and edits the value of one field |
| Typical use | Every field the user fills in or changes |
| Related | Date Range Input Block, Radio Button Block, Label Block (values that are only read) |
The input block is only offered in forms that belong to an entity.
2. Settings¶
| Setting | Meaning | Default / required |
|---|---|---|
| "Control Type" | The control shown, see section 3. It has to suit the type of the field. | Required. With the empty value the block shows only its label and no control. |
| "Field" | The field of the record the input reads and writes | Required. Without a field the user can type, but nothing is stored. |
| "Disabled" | Condition under which the value cannot be changed | not disabled |
| "Label" | Caption above the control (beside it for CheckBox and Switch) | none |
| "Show label" | Condition under which the caption is shown | shown |
| "Placeholder" | Hint shown while the input is empty | none |
| "Prepend Icon", "Append Icon" (Appearance) | Icon in front of or behind the value | none |
| "No Required Marking" (Appearance) | Switches off the marking of a required field that is still empty | off |
| "No Words As Date" | DateBox and DateTimeBox only: switches off reading words as a date | off |
| "No Words As Time" | TimeBox only: switches off reading words as a time | off |
| "Show DropDown" | TextBox only: turns the text box into a combo box that offers the valid values of the field | off |
| "Sort Valid Values By" | TextBox (with "Show DropDown"), ListBox, RadioButtons and ButtonGroup: the order of the offered values, see section 4 | order of the rules |
| "Sort Valid Values Descending" | Reverses that order | off |
| "Picker Type" | DefinitionPicker only: which kind of definition can be picked | Required for DefinitionPicker – with None no picker is drawn |
| "Focus On Open", "Skip In Tab Order" | Places the cursor into the control when the form opens; lets the Tab key pass over it. See Cursor and tab key. | never, off |
The settings that only apply to some control types appear once that control type is chosen. In addition, the block has the settings every block has, including "Flush".
Every expression of the block can read the system functions AssociatedFieldValue (the current value
of the field), AssociatedFieldRequired (required and still empty) and AssociatedControlDisabled –
for example to color the block or to change its label.
3. Control types¶
| Control type | Shows | Suits fields of type |
|---|---|---|
| TextBox | A single line of text; with "Show DropDown" a combo box | Text |
| Password | A single line shown as dots | Text |
| InlineTextBox | Text that turns into an input when it is clicked | Text |
| MultilineTextBox | Several lines of plain text | Text |
| NumericBox | A number. For an integer field without decimals. Emptying it clears the field. | Decimal number, integer |
| DateBox | A date picker | Date, date and time |
| DateTimeBox | A date and time picker | Date and time |
| TimeBox | A time picker; the date part of the value is kept | Date and time |
| CheckBox | A tick box | Yes/no |
| Switch | A toggle | Yes/no |
| ListBox | A list of the valid values, all visible | Fields with a list or lookup validation rule |
| RadioButtons | One radio button per valid value | Fields with a list or lookup validation rule |
| ButtonGroup | The valid values as a row of connected buttons | Fields with a list or lookup validation rule; two to four short values |
| ColorPicker | A color picker | Text |
| HtmlRichTextBox | Formatted text with a toolbar, stored as HTML | Text |
| HtmlRichTextBoxInline | As above, the toolbar only appears while editing | Text |
| MarkdownRichTextBox | Formatted text with a toolbar, stored as Markdown | Text |
| MarkdownRichTextBoxInline | As above, the toolbar only appears while editing | Text |
| DefinitionPicker | Picks a definition of the kind set in "Picker Type": ActionDef, ExpressionDef, BusinessHoursDef, FormBlockDef, WidgetDef, EntityDef, CounterDef, GlobalValueDef | Text – for configuration records, not for business data |
| ExpressionPicker | Picks or writes an expression | Text – for configuration records |
| BoolExpressionPicker, DateExpressionPicker, DateTimeExpressionPicker, TimeExpressionPicker, ImageExpressionPicker, ColorExpressionPicker | Like ExpressionPicker; a fixed value is entered with a switch, a date, date-and-time or time picker, an icon picker or a color picker | Text – for configuration records |
Password only hides the value from someone looking at the screen. The field stores it as typed; exports, queries and everybody with access to the record see it. Credentials that a system signs in with belong in credentials, never in a record field.
InlineTextBox is no way to make a value read-only – the user still edits it, with one click more. A value nobody may change belongs in a Label Block.
Rich text and tables¶
The four rich text controls take tables. A table copied from a spreadsheet, a web page or a document is pasted as a table and stays one when the record is saved. In the Markdown controls it is stored as a Markdown table, whose first row is the header row; in the HTML controls as an HTML table.
The editor keeps a plain grid, so pasted tables are simplified:
- Every cell is one line. A line break inside a cell becomes a space.
- Merged cells are split; a cell that spanned several columns is followed by empty cells.
- Rows of different lengths are padded with empty cells.
- Column widths, cell colors and other spreadsheet formatting are not kept; bold and italic are. The alignment of a cell is kept in the HTML controls, but not in the Markdown controls, as Markdown text does not store it.
The toolbar has no button for tables yet: a table is pasted, and its cells are edited in place. Tab moves to the next cell. Enter inside a cell does not add a line; at the first or the last row it adds a paragraph before or after the table.
Words as dates and times¶
DateBox and DateTimeBox also read words in the language of the user (English or German): "morgen 10 uhr", "letzte woche montag 08:13", "vor 3 tagen", "next friday 3pm". TimeBox reads "9 uhr", "halb drei", "in 2 stunden", "3pm" and keeps the date the value already has. A hint under the field shows the date or time the words become; it is taken over with Enter or when the field is left. Dates and times in digits are read as before. Switch the words off with "No Words As Date" or "No Words As Time" only where users type something that could be mistaken for a date, such as codes.
4. Valid values¶
ListBox, RadioButtons, ButtonGroup and a TextBox with "Show DropDown" offer the valid values of the field. They come from the List Validation Rules and Lookup Validation Rules of the field (see Business rules):
- Only rules that are active and apply to the record are used. A rule whose condition is not met contributes nothing.
- The rules are read one after the other; a value that a later rule offers again is listed once.
- A lookup rule contributes at most 500 values.
- With "Use RecId" on a lookup rule, the field stores the id of the chosen record while the control shows the looked-up text.
- Without such a rule there is nothing to offer, and the control stays empty.
In the combo box of a TextBox, free text remains allowed unless a list rule applies, or a lookup rule with "Enforce Validation".
Ordering the values¶
Without "Sort Valid Values By" the values keep the order of the rules: a list rule as its values are written, a lookup rule as its own sorting says. "Sort Valid Values By" is a sort key, not a comparison: it is evaluated once per value, and the values are ordered by the results – as numbers when every result is a number, otherwise alphabetically. Inside it, two system functions describe the value at hand:
| System function | Value |
|---|---|
AssociatedValidValue |
The value the field stores when the option is chosen (the record id with "Use RecId") |
AssociatedValidValueLabel |
The text the option is shown with |
5. Behaviour¶
- The value is written into the record when the control reports a change; the form is then evaluated again. It is stored in the database when the record is saved.
- Required fields: while a Required For Save Rule applies to the field and the field is empty, the control is drawn in the warning color of the theme. Nothing has to be configured for this. The marking is not shown in the preview of the editor.
- The look of the control follows the block settings: padding, border and background apply to the control itself, font size and text color to its text.
6. Examples¶
Priority as buttons. The field "Priority" has a List Validation Rule with Low, Medium, High,
Critical. An input block with "Control Type" = ButtonGroup and "Label" = Priority shows four
connected buttons. A value added to the rule appears in the form by itself.
Categories in alphabetical order. A ListBox over a field with two lookup rules. "Sort Valid
Values By" = AssociatedValidValueLabel orders all values of both rules by the text the user sees.
Highlight a field the user still has to fill. "Background Color" = an expression that returns
#fef3c7 when AssociatedFieldValue is empty and nothing otherwise.
7. Limitations¶
- Whether a value is valid is not decided here. Bounds, required fields and allowed values belong into business rules; they apply on every save, also for actions and imports.
- Do not use a permanently disabled input to show a value; use a Label Block.
- Tables in rich text controls cannot be created or restructured in the editor – they are pasted, and rows and columns cannot be added or removed afterwards. See Rich text and tables.