Showing, hiding, enabling

These properties all come from the shared display fragment, so every block that includes it has them. They answer different questions and are often confused.

Property	Question it answers
`effect`	What happens to this block by default: nothing, disabled, hidden
`conditionalDisplay`	A 4D formula, evaluated server-side
`effectForConditionalDisplay`	What happens when that formula is false
`userRightNeeded`	Which right the visitor must hold
`linked`	Which other fields must be filled before this one is usable
`isBasedOnListboxSelection`	Whether the block depends on a listbox having a selection

`conditionalDisplay` runs on the server

It is a 4D formula run through EXECUTE FORMULA at render time, with the page's full context — the entity, the session, the process variables. Two consequences:

it can express real business rules, not just field comparisons;
it cannot be re-evaluated outside the render. That is precisely why file authorisation records a grant at render time instead of re-checking later (see Files).

The exception is the notLoaded and readOnly effects: the same formula is evaluated again when a form comes back to the server, with the context of that request (see below).

effectForConditionalDisplay only appears in the panel once a formula is set (visibleWhen: {conditionalDisplay: "*"}). It lets you choose between: do nothing, disable, hide, not generate the block at all or, for an input field, show it read-only.

In dev mode a hidden or not-loaded block stays visible, flagged with a badge — otherwise an editor could not reach a block hidden by its own rule.

The effects differ more than they look

disabled renders the block, greyed out.
hidden renders it and hides it.
notLoaded does not generate it at all — so nothing client-side can reveal it.
readOnly (input fields only) shows the label and the value, with no input.

Choose deliberately: hidden still ships the content to the browser. For anything that must not reach an unauthorised visitor, the answer is notLoaded or a right, not a CSS class.

Read-only input fields

The "Read-only" effect (readOnly) shows a field as a label and its value when the formula is false. It saves you from adding a text block next to a field just to show a value that must not be edited: it is the same block, with the same vt_FieldName and the same way of getting its value (page entity, vt_HowGetPk, selected item, vt_Value…). Only the output changes.

It is offered on fieldText, fieldSelect, fieldCheckbox and fieldToggle only. Other blocks, file upload, capture and containers included, do not offer it, and the panel refuses to save it on them.

Field	Displayed value
`fieldText`	the text; a date in the system short format; a password masked (`••••••••`); a multi-line text with its line breaks; rich text decoded and sanitised; in a multilingual field, the current language. A hidden field is left unchanged.
`fieldSelect`	the label of the selected option (option groups included); with multiple selection, the labels separated by commas
`fieldCheckbox`	the labels of the checked options, separated by commas
`fieldToggle`	Yes / No

An empty value shows as a dimmed dash. The label is the field's own label, without the required asterisk and the help icons, which only concern input.

One layout per label position

The value sits in the box of an input, without its border or background: same height, same text indent, same font size and same label placement as the editable field. In a grid that mixes editable and read-only fields, rows and texts therefore stay aligned. The height is a minimum: a long or multi-line value grows the box instead of overflowing.

Label position (`vl_LabelPosition`)	Read-only layout
Floating (0)	the label floats on the top edge of the box, as on a filled field
Top (1)	the field's label above the box
Left (2)	the label inside the box, before the value
Right (3)	the label inside the box, after the value

fieldCheckbox has no label position: its group label sits above the options, so it stays above. fieldToggle puts its label on the left, or on the right with the "Right" setting (vb_RevertLabel). Rich text always has its label above, as when editing.

For custom styling, the output exposes the classes bspk-readonly, bspk-readonly-label, bspk-readonly-value and bspk-readonly-text, the data-readonly attribute, and the block carries effectForConditionalDisplay="readOnly".

What the server guarantees

Unlike hidden and disabled, no script can make the field editable again. When a form is sent:

a read-only field is not validated: a required read-only field does not block the form;
a value sent under its name is removed from the request and never saved;
an event fired from that field is refused.

The formula is evaluated again with the request's context; if it raises an error, it counts as false, and the field stays read-only.

Tip: one dataclass function, used as the formula on every field of a record page (for instance "can this record be edited?"), switches the whole page to view mode by changing a single line of code.

Never write `hidden` in `customClass`

Use the effect. A raw hidden class fights the framework's own show/hide logic and wins at the wrong moment — typically after a showBloc that then appears to do nothing.

`linked` is a pipe-separated list

linked holds field names joined by |, emitted as an HTML attribute read by checkLinkedFields. It is stored in properties.linked — despite the name, it is not a relation.

Rights

userRightNeeded names a right, which the visitor must hold. For admin pages, the right follows the ADMIN_<SLUG> convention rather than a hard-coded DEV code.

Two traps were recorded when rights were introduced on admin screens: a null publish on an admin URL produced a 404, and every event on an admin screen answered 403 until the right was granted.

Reloading a conditional block

A conditional wrapper needs the hidden effect to have something to act on, and a reload targets the wrapper, not the block inside it. Reloading the inner block only re-renders content whose visibility is decided by its parent.