Forms – the screens users work with records in¶

A form is the screen on which a user sees and edits a record. This chapter explains what a form is made of, how you build one in the form editor, where nexxcite shows forms, and which settings every block of a form shares. Each block type has a reference page of its own; section 10 lists them all.

It is intended for administrators who design the user interface of nexxcite.

1. Forms at a glance¶

A form is a tree of blocks. Some blocks show or edit something – an input, a label, a button. Others are containers that arrange the blocks inside them – in a column, in a row, in a grid, in tabs. The form itself is a column (a vertical stack) at the root of the tree.

Term	Meaning
Form	A stored definition that describes a screen. It belongs to an entity and shows one record of that entity at a time.
Block	One element of a form. Every block has a type ("Input Block", "Label Block", …) and its own settings.
Container	A block that holds other blocks: vertical and horizontal stacks, grid layout, repeater, scroll strip, element, tabs.
Entity context	The entity the form belongs to. Its fields and relationships are what the blocks can bind to. A form without an entity context – shown as "(None)" – has no record.
Stored block	A form that is embedded into other forms. A change to it reaches every form that embeds it (section 7).
Parameter	A value a stored block takes from the form that embeds it (section 7).

Most settings of a block are expressions: instead of a fixed value you can compute the value from the record, from the current user or from other data. A label can show a field, a button can be disabled while a status is "Closed", a whole section can be hidden for some roles. How expressions work is described in Expressions.

What a form does not decide is whether data is valid. A form is only active while somebody has it open; a validation rule applies on every save, also for actions, imports and mailbox listeners. Rules such as "this field is required" belong into business rules. The form shows them – a required field that is still empty is marked automatically (section 8).

2. Where nexxcite shows forms¶

Situation	Which form	Where you set it
A record is opened without naming a form – a link, a record list, a search result, an action that opens a record without a form	The default form of the entity	Entity editor, "Default Form"
An action opens a record or creates one with a form	The form named in the command, otherwise the default form	Commands "Go to record", "Create record", "Create related record" (see Actions)
An action opens a form in a dialog over the current screen	The form named in the command	Command "Open form dialog"
Related records inside a form	The form set on the block	Related Items Block, Related Items Timeline Block, Related Items Selector Block, preview of the Related Items Grid Block
A popover that opens on a click	The form set on the block	Element Block, "Popover Form"
A result card of the global search	The global search preview form of the entity	Entity editor, "Global Search Preview Form"
A user opens their own profile (address `/identity/account/my`)	The profile form	Admin Studio → System → Settings, "Profile form" (see Global settings)
An entry of a list	The form of the list definition	Lists

The record header¶

A form opened as a page shows a header band above the form when there is something to show in it:

the public id and the title of the record, both taken from the entity (its title expression and public id field),
"Back to List" and arrows to the previous and next record when the record was opened from a result list,
the bookmark button that saves the record to a collection, when the entity allows it and the user may save records (see Collections).

The header is not part of the form definition and cannot be configured in the form editor.

3. Creating and managing forms¶

Forms are managed in Admin Studio → Design → Forms (or in the area Entities, below the entity they belong to). When you create a form, you choose its entity. A form can also be created without an entity ("(None)"); such a form has no record and is meant to be embedded as a reusable stored block (section 7).

Permission	Allows
"Open Form Block Manager"	Opening the list of forms
"Add Form Block"	Saving a new form
"Edit Form Block"	Saving changes to an existing form
"Delete Form Block"	Deleting forms

By default, only the role "System Developer" has these permissions (see Roles and permissions). Users who only work with records in forms need none of them.

While a sketch is open, saving a form puts the change into the sketch instead of publishing it.

4. The form editor¶

Layout¶

┌──────────────────────────────────────────────────────────────────────────┐
│ Save & Close ▾ │ ↶ ↷ │ Form Properties │ Add Form Block │ … │   View Code  │  Toolbar
├──────────────┬─────────────────────────────────────────┬─────────────────┤
│ Search Blocks│                                         │ Properties of   │
│ Form Props.  │          Preview (canvas)               │ the selected    │
│ ▸ Block tree │                                         │ block           │
│              │  [mode] [screen size] [zoom] [👁] [🗑]  │                 │
└──────────────┴─────────────────────────────────────────┴─────────────────┘

Part	What it does
Toolbar	Saving, undo and redo, the form properties, adding, removing, copying and pasting blocks, the code view
Block tree	The structure of the form. Selecting a block here selects it in the preview and shows its properties.
Preview	The form as users will see it, drawn for a new, empty record of the entity. A click on a block selects it.
Property panel	The settings of the selected block, or of the form itself

The three panes can be resized with the handles between them.

Button	Effect
"Save & Close" (with the arrow: "Save without closing")	Saves the form, see Admin Studio
Undo, Redo (arrows)	Takes back the last change or restores it (see below)
"Form Properties"	Shows the settings of the form itself in the property panel
"Add Form Block"	Opens the palette of block types. The new block is added into the selected block if that one takes children, otherwise next to it; without a selection at the end of the form.
"Add Stored Block"	Opens the list of forms to pick a stored block from (section 7)
"Remove Block"	Removes the selected block with everything inside it
"Copy Block"	Puts the selected block on the block clipboard
"Paste Block"	Inserts the block from the clipboard (see below)
"View Code"	Shows the form as text. "Graphical Editor" switches back.

The palette¶

"Add Form Block" lists every block type by the name shown in the table in section 10, for example "Input Block" or "Tab Block". The same list opens from "+Above", "+Inside" and "+Below" in the block tree and from the tab on the selected block in the preview; there it is sorted alphabetically, has a filter field at the top, and only offers the types allowed at that position.

In a form without an entity, the palette leaves out the blocks that need a record: Input Block, Date Range Input Block, Radio Button Block, the five related items blocks and Files Block.

The block tree¶

Search Blocks filters the tree by block name. The two buttons beside it expand or collapse all blocks.
A double click on the name of a block renames it in place. The name is only for you – users never see it – but it is what the tree and the AI assistant identify the block by.
Hovering over a name shows the block type.
A block with a visibility condition carries an eye icon, because it may be missing in the preview.
Drag and drop moves a block above, into or below another block. The tree only accepts a drop where the nesting rules allow it – a tab item, for example, only inside a tab block.
The menu at the end of the selected row offers:

Entry	Effect
"Delete"	Removes the block
"Clone"	Inserts a copy of the block directly below it. The copy gets the name "… (Copy)".
"Copy ID"	Copies the ID of the block definition to the clipboard. For a stored block it is the ID of the stored block itself.
"Copy"	Puts the block on the block clipboard
"Paste Above", "Paste Inside", "Paste Below"	Inserts the block from the clipboard there. Only offered where the nesting rules allow it.
"+Above", "+Inside", "+Below"	Adds a new block of the chosen type there

The preview¶

The preview draws the form for a new, empty record of the entity. Values you type into it are kept while you change the form, but they are never saved. A form without an entity is drawn without a record; its parameters show their default values.

The bar at the bottom of the preview:

Control	Effect
"Block selector mode"	A click selects the block under the pointer. The selected block carries a tab with its name and buttons to add a block above, inside or below it.
"Drag mode"	Dragging moves the canvas, for a form larger than the screen
"Interaction mode"	The form reacts like in the application: you can type, switch tabs, unfold sections
"Desktop", "Tablet", "Phone"	Draws the canvas at 1800 × 850, 1024 × 768 or 420 × 850 pixels
"Custom size"	The size you last dragged the canvas to. Drag the right edge, the bottom edge or the corner of the canvas to change it (from 240 × 200 up to 3840 × 3840 pixels).
"Zoom out", zoom value, "Zoom in"	Zooms in steps of 10 % (5 % to 250 %). A click on the value resets it to 100 %.
Eye	"Show all blocks (ignore visibility conditions)" – useful because many blocks are hidden on a new record. Not remembered.
Bin	"Remove selected block (Del)" – also with the Del key

The editor remembers screen size, custom size and zoom per user. They apply to the form editor and the dashboard editor together.

Limitations of the preview. The record is new and empty, so everything that depends on saved data looks different from the application: related records are missing, required fields are not marked, and a repeater whose list is empty is drawn once with an empty element so that you can see its content.

The property panel¶

The panel shows the settings of the selected block, grouped into categories (section 6). At the top:

"Search Properties..." filters the settings by name.
"Hide defaults" hides every setting that still has the value of a newly created block, so only what you changed remains.

"Form Properties" (in the toolbar or at the top of the tree) shows the settings of the form itself: "Display Name", "Description", "Tags", "Stylesheet" (section 9), "CSS Classes" for the form and "Parameters" (section 7).

The block clipboard¶

Copying a block puts it on a clipboard that belongs to you:

It survives a reload of the page and is available in other browser tabs.
It holds one block at a time. The next copy replaces it.
A block copied in a form can be pasted into any other form – but not into a dashboard, and the other way round.
A block is copied with everything inside it. Pasting creates an independent copy; you can paste the same block as often as you like.
A stored block is copied as a reference: pasting it embeds the same stored block once more, together with the arguments of the copied occurrence – not a detached copy of its content.
"Paste Block" in the toolbar inserts into the selected block if it takes the copied block, otherwise next to it; without a selection at the end of the form. Where the block is not allowed, nothing is pasted.
A block inside a stored block cannot be copied on its own.

Expression and action settings have their own small clipboard: right-click the setting and choose "Copy" or "Paste".

Undo and redo¶

The two arrow buttons beside the save button take back the last change and restore it. A change is, for example, one edited setting, one added or moved block. The editor can take back up to 29 changes while it is open; closing the editor discards them. Undo does not take back a save – it only returns the editor to an earlier state, after which you can save again. The editor has no keyboard shortcuts for undo and redo.

Unsaved changes in the editor¶

Closing an editor that has unsaved changes asks whether to save them first – see Admin Studio.

5. Layout¶

A form is laid out with containers. Use them in this order of preference:

Container	Lays out its children	Typical use
Vertical Stack Block	under each other	Sections of a form, the default
Horizontal Stack Block	in a row, wrapping on narrow screens, optionally in columns per screen width	Two or three inputs side by side
Grid Layout Block	in a grid of columns and rows; children can span several cells	Fields that have to line up in columns
Tab Block with Tab Item Blocks	as tabs or as an accordion	A record with more content than fits on one page
Scroll Strip Block	on one line that scrolls instead of wrapping	Tags, a row of cards whose number depends on the data
Repeater Block	once per element of a JSON list	Content whose number is only known from the data
Element Block	as a single HTML element, clickable as a whole	A card that is clicked as a whole, a popover

Columns per screen width¶

The horizontal stack and the grid layout set their columns per width with the setting "Columns": one value for every width, and optional values from the breakpoints sm, md, lg, xl and 2xl upwards. Each value is either

a number of equal columns – 3, or
the widths of the columns – 7fr 3fr for a 70/30 split, 200px 1fr for a fixed and a flexible column.

Use fractions (fr) rather than percentages: 70% 30% plus the gap between the columns is wider than the row.

The breakpoints refer to the width of the surrounding container, not of the browser window. Normally that is the form; a block becomes such a container with "Is Container", and a block further down can refer to a named container with "Target Container Id". In our assessment the breakpoints correspond to the usual sizes of the CSS framework nexxcite uses – roughly 384, 448, 512, 576 and 672 pixels of container width for sm to 2xl. Check the result with the screen sizes of the preview.

Example: A detail section with a wide main column and a narrow side column. "Columns" = 1, "Columns (md)" = 7fr 3fr. On a phone both columns are stacked at full width; from the md breakpoint upwards they are split 70/30.

Folding sections¶

A vertical or horizontal stack can be made expandable: it is drawn only up to a folded height or width and offers a button to unfold it. The button only appears when something is really hidden. Folding saves room; it does not hide anything – a folded stack is completely loaded and one click away. To hide content, use the visibility condition.

Recommendations¶

Group by what the user does, not by the order of the fields in the entity.
One to three inputs per row. Set the columns per breakpoint instead of fixed widths.
Put the fields that identify the record first.
Use tabs for what is not needed all the time; everything needed at a glance belongs on the first tab.
Put related records at the bottom or on a tab of their own.
Put the toolbar of a form at the top.

6. Settings every block has¶

Every block has the settings below in addition to its own. The property panel groups them into categories; "Common" (the block's own settings) and "Layout" are open, the other categories are collapsed at first.

Category	Setting	Meaning
Common	"Display Name"	Name of the block in the tree. Not shown to users.
Common	"Visible"	Condition under which the block is shown. Empty: always visible. A hidden block is not evaluated at all – including everything inside it.
Layout	"Align Self"	Alignment of the block inside its parent stack (Start, Center, End, Stretch)
Layout	"Column Span", "Row Span"	How many columns and rows the block spans inside a grid layout or a horizontal stack with columns. Empty: 1.
Size	"Size"	Width, height, minimum and maximum width and height, each as a CSS length (`200px`, `50%`, `20rem`) or computed. A plain number means pixels.
Spacing	"Padding", "Margin"	Inner and outer spacing per side as a CSS length. Margin also takes `auto`.
Spacing	"Flush"	Only for blocks with a default spacing (input, date range input, radio button, button, label, related items selector): drops the default spacing of 8px, so the block sits edge to edge with its neighbours. A configured padding still applies.
Border	"Border"	Width per side, line style and corner radius
Border	"Border Color"	Color of the border
Typography	"Font Size", "Font Weight", "Text Align"	Presets for the text of the block and its content
Typography	"Text Decoration", "Text Transform"	Underline, overline or line-through; letter case for display (Uppercase, Lowercase, Capitalize). Only the display changes, the stored value stays as it is. None also removes what the surroundings would apply.
Typography	"Text Color"	Color of the text
Appearance	"Background Color"	Background of the block
Appearance	"Shadow", "Opacity"	Shadow preset; opacity in percent (0–100, empty: fully opaque)
Appearance	"Tooltip"	Text shown when the pointer rests on the block
Advanced	"CSS Styles"	Additional inline styles, for example `color: red;`. They are applied after all other settings and therefore win.
Advanced	"CSS Classes"	Additional CSS classes, for use in a stylesheet (section 9)

Colors are CSS colors (#15803d, rgb(…), a color name). All of these settings except the presets can be computed, so a block can, for example, turn red when a deadline has passed.

Exceptions: the Related Items Block has no element of its own and therefore only "Display Name" and "Visible". The Repeater Block and the other containers have no "Flush".

CSS classes of the blocks¶

Every block carries the class form-block and a class of its type, which you can use in a stylesheet:

Block	Class
Vertical, horizontal stack, grid layout, scroll strip, repeater	`verticalstack-form-block`, `horizontalstack-form-block`, `gridlayout-form-block`, `scrollstrip-form-block`, `repeater-form-block`
Input	`input-form-block` and `<control type>-input-form-block`, for example `datebox-input-form-block`
Date range input	`input-form-block daterange-input-form-block`
A required input that is still empty	additionally `nx-required-missing`
Other blocks	`label-form-block`, `badge-form-block`, `avatar-form-block`, `progress-form-block`, `skeleton-form-block`, `button-form-block`, `radiobutton-form-block`, `html-form-block`, `image-form-block`, `element-form-block`, `tab-form-block`, `tabitem-form-block`, `toolbar-form-block`, `files-form-block`, `relateditems-form-block`, `relateditemsgrid-form-block`, `relateditemslist-form-block`, `relateditemstimeline-form-block`, `relateditemsselector-form-block`

7. Stored blocks and parameters¶

Any form can be embedded into other forms as a stored block: "Add Stored Block" opens the list of forms, and the chosen one is inserted as a single node. It stays one definition – a change to it reaches every form that embeds it. A typical case is an address section that six entities share.

A form of an entity can embed stored blocks of the same entity and stored blocks without an entity. A form without an entity can only embed forms without an entity.
In the embedding form, the stored block is shown as one node with a special icon. Its content and its settings are read-only there; edit them in the stored block itself.
A stored block that would end up inside itself, directly or through other blocks, is left out.

Parameters¶

A stored block only pays off when it does not hard-code what differs between the places it is used in. That is what parameters are for.

Open the stored block and choose "Form Properties" → "Parameters". Add a parameter with "Name", "Description" and an optional "Default Value".
Inside the stored block, read the parameter with a variable expression. Every expression setting of the block offers the parameters as variables.
In every form that embeds the stored block, select it: the category "Arguments" shows one setting per parameter. These are the only settings of a stored block that the embedding form can change.

Rules:

Arguments are evaluated where the block is embedded – they can read the record and the parameters of the embedding form.
Inside a stored block, only its own parameters exist. It does not see the parameters of the form around it. A parameter that is not handed a value falls back to its default value.
In the preview of the stored block itself, the parameters have their default values.

Example: A stored block "Contact Card" without an entity has the parameters "Heading" and "Person". The ticket form embeds it twice: once with the argument "Heading" = Requester, once with Assignee, each with "Person" computed from a different field of the ticket.

8. Forms at runtime¶

When values are written¶

What a user types is written into the record of the form when the input reports the change – for a text box when the user leaves the field or presses Enter. The form is then evaluated again, so labels, visibility and disabled conditions follow the new value at once. Nothing is stored in the database until the record is saved – by a save button, a toolbar or an action.

A click on a button or toolbar entry waits until a change that is still being applied is complete, so the action never runs against the values from before the edit.

A form does not notice changes that other users or background processes make to the record while it is open. They appear when the record is refreshed – for example with the "Refresh" button of a Toolbar Block – or opened again.

Hidden, disabled, required¶

Situation	Effect
A block's "Visible" condition is false	The block and everything inside it is not drawn and not evaluated
A block's "Disabled" condition is true	The control cannot be changed or clicked. Related items blocks with a disabled condition disable everything in the forms they show, whatever those forms say.
A Required For Save Rule applies to a field and the field is empty	Input and date range input blocks bound to the field are drawn in the warning color of the theme. Switch it off per block with "No Required Marking".

Values that change with the time¶

A form is evaluated again whenever the record changes. A value that changes with the clock – the remaining time of a deadline, "due in 2 hours" – does not. For such values, the Label, Badge, Progress and HTML blocks offer "Auto Refresh": every "Refresh Interval (s)" seconds (default 30) only that block is evaluated and drawn again. Every refresh evaluates the block on the server for every open form, so choose the coarsest interval that is good enough. A failed refresh keeps the last values on the screen.

Cursor and tab key¶

Input, Date Range Input, Radio Button, Button and Related Items Selector blocks offer two settings for working with the keyboard:

Setting	Meaning	Default
"Focus On Open"	Condition under which the cursor is placed into the block when the form opens, so the user can start typing right away – for example only for a new record	never
"Skip In Tab Order"	The Tab key passes over the block. A click still reaches it.	off

"Focus On Open" applies when a page with a record or a dialog opens, and when the user moves on to another record in the same form. It does not take the cursor away while the user works in the form, and it does nothing when the cursor is already in the form or in another field of the page.
Of several blocks whose condition is true, the first one shown in the form wins.
A block the user can see comes first. Only when none asks for the cursor, a block on a tab that is not selected or in a collapsed accordion item gets it, and its tab or accordion item is opened. With "Preserve Selection" on the tab block, that tab is then remembered like a tab the user picked.
A block hidden by its "Visible" condition or disabled, or on a disabled tab, is passed over. A folded stack is unfolded.
Forms shown inside another form – the rows of a list, the cards of a timeline, preview forms – never take the cursor. Neither does the preview in the form editor.
The order of the Tab key is the order of the blocks in the form. "Skip In Tab Order" only takes blocks out of it; a different order is not possible.
To place the cursor at a later point, for example after a check in an action, use the UI command FocusInputBlockAction of Dispatch UI.

Values available to expressions¶

Besides the fields of the record, expressions in a form can read these system functions:

System function	Value
`AssociatedFormDefId`	The id of the form that is shown
`AssociatedModalId`	The id of the form as it is shown on screen – used, for example, to close the dialog it is shown in
`AssociatedFieldValue`	In the settings of an input, date range input or radio button block: the current value of its field
`AssociatedFieldRequired`	In the same blocks: whether the field is required and still empty
`AssociatedControlDisabled`	In the same blocks: whether the control is disabled
`AssociatedValidValue`, `AssociatedValidValueLabel`	Only in "Sort Valid Values By" of an input block, see Input Block

Leaving a record with unsaved changes¶

When a user leaves a record that has unsaved changes – by opening another record, a dashboard, a search result or the start page – nexxcite asks "Unsaved changes" with "Save", "Discard" and "Cancel". Reloading the page with F5 or Ctrl+R asks the same. Closing the tab, the reload button of the browser and the back button of the browser show the browser's own warning instead.

A form shown in a dialog is not covered by this question; the dialog decides on its own.

9. Styling forms¶

The settings of section 6 cover most needs. For everything else there are style sheets:

Where	Applies to
"Form Properties" → "Stylesheet"	This form. The result of the expression is inserted as a style sheet while the form is shown.
Admin Studio → System → Settings, "Form Styles"	Every form (see Global settings)
"Custom Styles" of a role	The whole application for users with that role (see Roles and permissions)

A style sheet of a form is not limited to the form's own elements: while the form is shown, its rules apply to the whole page. Write selectors that start with a class of your own – set it with "CSS Classes" on the form or on a block.

10. All blocks¶

Block (name in the palette)	Purpose	Needs an entity	Takes child blocks
Vertical Stack Block	Children under each other; foldable	No	Yes
Horizontal Stack Block	Children side by side, columns per width; foldable	No	Yes
Grid Layout Block	Children in a grid	No	Yes
Repeater Block	Children once per element of a JSON list	No	Yes
Scroll Strip Block	Children on one scrolling line	No	Yes
Element Block	Free HTML element, clickable, with popover	No	Yes
Tab Block	Tabs or accordion	No	Only tab items
Tab Item Block	One tab of a tab block	No	Yes
Input Block	Edits one field, with 26 control types	Yes	No
Date Range Input Block	Edits a period over two date fields	Yes	No
Radio Button Block	One option that writes a fixed value into a field	Yes	No
Label Block	Text, a heading, a value that is only read	No	No
Badge Block	A short value as a colored chip	No	No
Avatar Block	Picture or initials of a person or thing	No	No
Progress Block	A bar filled to a share	No	No
Skeleton Block	Placeholder for content that is still loading	No	No
Image Block	A picture or an icon	No	No
HTML Block	HTML produced by an expression	No	No
Button Block	Runs an action; optional menu of further buttons	No	Only buttons
Toolbar Block	An app bar and built-in save, refresh, discard buttons	No	No
Files Block	Attachments of the record	Yes	No
AI Assistant Block	Chat with an AI assistant	No	No
Related Items Block	Each related record rendered with a form	Yes	No
Related Items Grid Block	Related records as a table	Yes	No
Related Items List Block	Related records as a list	Yes	No
Related Items Timeline Block	Related records as a timeline	Yes	No
Related Items Selector Block	Searching and linking records	Yes	No

11. Frequently asked questions¶

A block is missing in the preview. Why? Most often its "Visible" condition is false for a new, empty record. The tree marks such blocks with an eye icon. Switch on "Show all blocks" in the bar of the preview to see them anyway.

Can I make a field required in the form? No. A field becomes required through a Required For Save Rule (a business rule). The form then marks it by itself.

Can I show a value that users must not change with a disabled input? Yes, but a Label Block is the better choice: it says to everyone reading the form later that the value is only shown.

Does a hidden block still cost time? No. A block whose visibility condition is false is not evaluated, nor is anything inside it. A folded stack, in contrast, is completely loaded.

I changed a stored block. Do I have to save the forms that embed it? No. The forms refer to the stored block and show the new version the next time they are drawn.

Can I paste a block from a form into a dashboard? No. The block clipboard only pastes blocks into the kind of editor they were copied in.

Can I undo a change after saving? No, not with the undo button. While a sketch is open, you can discard the change from the sketch instead (see Sketches and publishing).