Package su.onno.ui

Class FieldHintBuilder<O,T>

java.lang.Object
su.onno.ui.FieldHintBuilder<O,T>
public class FieldHintBuilder<O,T> extends Object
Per-field hint builder. Obtained from EntityConfigBuilder.field(String) inside a lambda passed to SectionBuilder.catalog/document/register.

Chain field-level setters; call field(String) to switch to another field on the same entity. Anything not set falls through to the scanner default.

  • Method Details

    • order

      public FieldHintBuilder<O,T> order(int order)

    • group

      public FieldHintBuilder<O,T> group(String group)

    • width

      public FieldHintBuilder<O,T> width(String width)

    • widget

      public FieldHintBuilder<O,T> widget(String widget)
      Override the control used to edit this field. Built-in hints include "switch"/ "toggle" (boolean), "textarea", "color" (a visual picker plus #RRGGBB input), "geojson" (the geometry editor — draw points, paths, and areas, stored as GeoJSON), and the media widgets "image", "avatar" (small round), "images"/"gallery" (several), and "file" (any type). The map widgets render on a theme-aware MapLibre basemap; the media widgets stream the chosen file to POST /api/media and store only the returned reference URL, so a plain String attribute holds it — see su.onno.ui.media.

    • placeholder

      public FieldHintBuilder<O,T> placeholder(String placeholder)
      Placeholder text shown in this field's empty input on the edit form.

    • format

      public FieldHintBuilder<O,T> format(String format)
      How this field's value is displayed in tables (list) and the detail surface. The hint is interpreted by value type:
      • Dates / date-times — a date pattern, e.g. "dd-MM-yy", "dd/MM/yyyy HH:mm" (uppercase D/Y are accepted as day/year).
      • Numbers — "integer", "decimal", "percent", an explicit ISO currency such as "currency:EUR", or a decimal pattern like "#,##0.00".
      It does not affect the edit form's input control (use widget(String) for that).

    • hint

      public FieldHintBuilder<O,T> hint(String hint)
      Optional help text for this field, surfaced in the UI as a hoverable ? icon next to the field's label (on the edit form, list column header, and read-only detail view). Keep it short — a sentence explaining what the field means or how to fill it in. Blank (default) shows no icon.

    • label

      public FieldHintBuilder<O,T> label(String label)
      Override this field's display label — the text shown next to the input on the edit form, in the list column header, and on the read-only detail view. Works for both custom attributes (overriding @Attribute(displayName=...)) and the built-in system columns (code/description on catalogs; number/date/posted on documents), which otherwise have no DSL path to a label. The primary use is localization, e.g. f.field("code").label("Код") or f.field("posted").label("Статус").

      This is the form/detail counterpart to ListSpec.label(String, String) (which only relabels the list header); a ListSpec.label(...) on the same field still wins for the list column specifically. Blank/unset falls through to the descriptor's display name.

    • hideInList

      public FieldHintBuilder<O,T> hideInList()

    • hideInForm

      public FieldHintBuilder<O,T> hideInForm()

    • hideInDetail

      public FieldHintBuilder<O,T> hideInDetail()

    • visibleInList

      public FieldHintBuilder<O,T> visibleInList(boolean v)

    • visibleInForm

      public FieldHintBuilder<O,T> visibleInForm(boolean v)

    • visibleInDetail

      public FieldHintBuilder<O,T> visibleInDetail(boolean v)

    • refSecondary

      public FieldHintBuilder<O,T> refSecondary(String targetFieldName)
      For a Ref field: show a secondary attribute of the picked record beneath its name in the ref picker, to disambiguate same-named records (e.g. a customer's phone). Names a field on the ref's target entity; the data already rides along in the picker payload, so this only tells the client which extra value to render. No effect on a non-ref field.

      Independent of search: the typeahead already matches every text column of the target, so a record is findable by this attribute whether or not it's shown. See issue #184.

    • refSecondary

      public <V> FieldHintBuilder<O,T> refSecondary(Field<T,V> targetField)
      Compiler-checked counterpart of refSecondary(String).

    • refFilter

      public FieldHintBuilder<O,T> refFilter(String filter)
      For a Ref field: narrow the picker's options with a predicate over the ref's target entity, in the same small field op value AND … grammar a dashboard widget's config("filter", …) uses. A ${field} placeholder substitutes the form's current value of another field, making pickers cascade: 
       f.field("employee").refFilter("department = ${department}");   // header field → header field
 f.field("lines.book").refFilter("supplier = ${supplier}");     // line cell ← header field

      While a referenced field is still empty the filter is skipped (the picker shows everything); once it's set, options narrow and a later change clears the dependent field. Static predicates work too (no placeholder), e.g. "active = true". Left-hand names are fields of the target entity; parsing is the injection-safe WidgetFilter (known-column allowlist, bound values), so an unknown name degrades to "no filter", never an error. No effect on a non-ref field.

    • refOptions

      public FieldHintBuilder<O,T> refOptions(Class<? extends RefOptionDecorator> decoratorType)
      Decorate this reference picker's options using the given application-provided Spring bean. The decorator receives live parent-form and tabular-row context and can add a status badge, disable an option, and explain a conflict. Resolution is batched across the current search page. 
       f.field("participants.employee")
     .refOptions(EmployeeAvailability.class)
     .uniqueWithinSection();

    • uniqueWithinSection

      public FieldHintBuilder<O,T> uniqueWithinSection()
      For a reference column in a tabular section, disable values already selected in sibling rows. The current row's own value remains selectable. This is immediate UI guidance; domain validation remains the authoritative safeguard on write.

    • field

      public FieldHintBuilder<O,Object> field(String name)
      Switch to configuring another field on the same entity.

    • field

      public <V> FieldHintBuilder<O,Object> field(Field<O,V> field)
      Continue with a compiler-checked field on the same entity.