NE.Standard

Binding

A binding ties a component property to a location in the controller's object graph, addressed by a RecursivePath. This page covers how to write a path, which method binds it, and what happens when the value it resolves to is missing or invalid.

Paths

A RecursivePath is an immutable list of segments: a property name, an index ([0]), or a key (["abc"] or the bare [abc], both parsed the same way when the token is not an integer). ToString() renders the grammar and RecursivePath.Parse(path) reads it back:

Lines[0].Price

An index or a key is read inside a row's item: bound Relative in an order's row template, the path above reads that order's first line. Read from the controller, before any row (BindTitle("Orders[0].Total")), it is refused when the view compiles — one element per row is an item template (Scopes, below), whose rows each read their own item.

Every Bind* method comes in a typed expression overload alongside its string one — the expression is translated to a RecursivePath once when the view builds (RecursivePath.FromExpression), supporting nested members, indexers, captured values and casts, while nameof works for a single property:

new TextComponent().BindTitle<CounterController>(c => c.Count)
new TextComponent().BindTitle(nameof(CounterController.Count))

Bind* vs the raw Bind

A bindable property generates its own Bind<Name>(string path, UIBindingScope scope = ..., UIBindingMode mode = ..., bool optional = false) and Bind<Name><TSource>(Expression<Func<TSource, object?>> path, UIBindingScope scope = ..., UIBindingMode mode = ..., bool optional = false) — the defaults come from how the property was declared (see Modes, below). There is also a raw entry point every component inherits:

public TComponent Bind(UIProperty property, string path, UIBindingScope scope = UIBindingScope.Root, UIBindingMode? mode = null, bool optional = false)
public TComponent Bind<TSource>(UIProperty property, Expression<Func<TSource, object?>> path, UIBindingScope scope = UIBindingScope.Root, UIBindingMode? mode = null, bool optional = false)

Reach for the raw Bind only when binding by property key at runtime (a template that binds by IVisualComponent property object rather than by name). With no mode it takes the property's own default, as the generated method does — a field's Value binds TwoWay, a text's Title OneWay.

Bind throws at view-compile time if the property is not registered for the component, is not bindable (IsBindable = false), or does not support the requested mode.

Mistakes the compiler catches

A view is compiled with its controller's type — at startup, unless the route is Lazy — and these mistakes are caught there rather than in front of a user:

  • One element of a controller's collection by a fixed index or key (BindContext("Phases[0]"), BindTitle("Orders[\"o1\"].Total")) fails the compile with the component and the path named; a row template addresses one element per row.

  • A command the controller does not declare (OnClick("Sav")) fails the compile with the component, the event and the controller named.

  • A bound path the controller's types do not have (BindTitle("Titel")) is a warning in the log, whatever the scope: a Relative path inside an item template is checked through the collection's element type. A binding marked optional, a path through an object, and a property only a derived item type declares are not judged.

  • A path the server cannot read warns too: a controller property that is no [RecursiveMember] (a computed Header => …, a plain auto-property) or a step through a type that is no RecursiveObservable (Owner.Name where Owner is a record) resolves to nothing on the server. A row's own fields travel to the page whole, so the check stops at the first row.

  • A row's Root binding its item has too (BindTitle(nameof(Message.Title)) in a row, the controller holding a Title) warns: every row would show the controller's one value. Bind it Relative.

  • A declared list's row binding what none of its items has (SetItems(...) with a template binding Caption) warns, as a controller's list does; a BindContext path is checked as a property's.

  • A form nothing submits fails the compile: a field bound OnSubmit, or a SubmitOnEnter area, whose FormId no button's OnSubmit(formId, …) submits, nor a field's own submitting event (a code field's save, IFormSubmittingComponent). A view with a button whose submit form id is bound is not checked: that form is the page's to make.

  • Inline rename without a writable RenamedTitle fails the compile: enabling inline rename (SetRenamable(true) / BindRenamable, .Editable, OnRename*, OnItemRename*, UITabMenuEntries.Rename, or RenameItemEffect) requires a writable (TwoWay, OneWayToSource, or OnSubmit) BindRenamedTitle on the renamed component or item template.

Each warning carries its kind (UICompileWarning.Kind): a binding or a path that names nothing is UnresolvedBinding, which a test page refuses (see testing); a Root binding a row's item shadows, an argument no parameter takes and a selection binding its mode never reads are Advisory, logged only. An argument the framework adds itself (a drop's drop, an edited row's id) never warns. A page in Development writes every warning to its browser console.

Scopes

UIBindingScope says where a path is resolved from:

Value Resolves from
Relative The component's own context — inside an item template, the row being rendered. Pass it explicitly there; only a row's own properties default to it: an item's abilities (CanSelect, CanDrag, CanRemove, CanRename, CanShowContextMenu), a tree node's (ParentId, HasChildren, IsFolder, Expanded, DropTarget), a tab's Order and Pinned, and IRenamableComponent.RenamedTitle (a text's, a tree node's or a tab's).
Parent One level up from the context this component belongs to — not one visual hop. A plain visual child only inherits its context, so Parent on a component with no context of its own lands one level above its nearest context-defining ancestor.
Root The controller root. This is what a raw Bind and every generated Bind* but the row's own above default to — inside an item template this is almost never what is meant.

A nested items example: an items view binds its rows from the controller, and its row template — one component tree, compiled once and reused for every row — binds relative to whichever row it is currently rendering:

new ItemsViewComponent()
    .BindItems(nameof(ContextMenuGroupContext.Deploys), UIBindingScope.Relative)
    .SetTemplate(new ActionComponent()
        .BindTitle(nameof(DemoDeploymentRow.Service), UIBindingScope.Relative)
    )

Inside a template a plain visual child inherits its enclosing row's context, so Relative there resolves against the row rather than the view root — the source of the "almost never Root" rule above. Nesting one more items view inside a row template compounds the same rule: its own Relative binding appends to the row's path, producing something like "Groups[].SubItems" for the inner collection.

Modes

UIBindingMode:

Value Direction
OneWay Source to target only.
TwoWay Both directions.
OneWayToSource Target to source only — the initial change set does not carry this value, so nothing but the renderer ever writes it; use it for state the server only stores.
OnSubmit Target-to-source updates are buffered on the client until an explicit submit (ButtonComponent.OnSubmit(formId, command)), then flushed before the command runs. Unlike OneWayToSource, the initial change set does carry this value. The field needs a form id (see A form, below).

A property must declare the matching BindingCapabilities (UIBindingCapabilities: SourceToTarget, TargetToSource, SubmitBufferedTargetToSource, a [Flags] enum) for a mode to be accepted — IInputComponent.Value declares all three plus DefaultBindingMode = UIBindingMode.TwoWay, which is why BindValue defaults to two-way without saying so.

What a null value renders

A binding that resolves to null does not clear the property — it falls back to the value the component was authored with (Set*), or, absent that, the property's registered default. A controller holding null for a bound property therefore renders exactly what the same component renders unbound. This is also why a property both Set* and Bind*-ed comes back to the set value rather than to nothing when the bound value is missing.

Static-only properties

A property declared IsBindable = false, GenerateBinder = false generates no Bind<Name> method, and Bind(UIProperty, …) refuses it at compile time with a thrown error — never a silent no-op. Reach for this when a property is genuinely render-time-only (read once to build a picker, for instance); it is not a workaround for "I don't want this bound yet."

Responsive values

Any UIResponsive<T>? property gets a convenience Set* overload alongside its plain one:

public TComponent SetWidth(UILayoutLength value, UILayoutLength? sm = null, UILayoutLength? md = null, UILayoutLength? xl = null, UILayoutLength? xxl = null)

sm, md, xl, xxl are the breakpoint tiers; an unset tier falls back to the next narrower one that is set, down to the base value (mobile-first). SetPlacement on every visual component follows the same shape (see views, placement grid).

BindContext

BindContext(path, scope) binds the component's context rather than one of its properties — the base path every relative binding and action argument inside this component (and its descendants, if it is a container) resolves against. It names a member or an object, not one element of a collection: one element per row is an item template, whose rows each take their item as context.

public virtual TComponent BindContext(string path, UIBindingScope scope = UIBindingScope.Root)
public virtual TComponent BindContext<TSource>(Expression<Func<TSource, object?>> path, UIBindingScope scope = UIBindingScope.Root)
public virtual TComponent BindContext(RecursivePath path, UIBindingScope scope = UIBindingScope.Root)

Two-way sync

A two-way-bound value syncs on the native change event, not input — fewer round-trips — except where a text input, a text area or a search sets SetDebounceMilliseconds: it commits while typing, that long after the last keystroke. The property still needs its capability declared correctly (see Modes, above) or the client's write is silently dropped by the runtime rather than applied.

Validation on inputs

An input's validation message comes from up to four sources, and the strongest one shown wins:

  1. Client rules, added fluently:

    new TextInputComponent()
        .Required("Name is required.")
        .Regex(@"^\S+@\S+$", "Enter a valid email.", trigger: UIValidationTrigger.Blur, severity: UIValidationSeverity.Warning)
    
    public static TComponent Required<TComponent>(this TComponent input, string message,
        UIValidationTrigger trigger = UIValidationTrigger.Change, UIValidationSeverity severity = UIValidationSeverity.Error)
    
    public static TComponent Regex<TComponent>(this TComponent input, string pattern, string message,
        UIValidationTrigger trigger = UIValidationTrigger.Change, UIValidationSeverity severity = UIValidationSeverity.Error)
    
    public static TComponent RegexEach<TComponent>(this TComponent input, string pattern, string message,
        UIValidationTrigger trigger = UIValidationTrigger.Change, UIValidationSeverity severity = UIValidationSeverity.Error)
    
    public static TComponent Validate<TComponent>(this TComponent input, UIValidationTrigger trigger,
        UIComparisonOperator @operator, object? value, string message, UIValidationSeverity severity = UIValidationSeverity.Error)
    

    RegexEach is for a list value: every item must match — a multi-select's each key, and a tag typed into one taking free text is refused before it becomes a chip.

    A rule may compare with another field's value instead of a fixed one — "Password again" equal to "New password":

    TextInputComponent password = new TextInputComponent().SetType(UITextInputType.Password);
    new TextInputComponent()
        .SetType(UITextInputType.Password)
        .ValidateAgainst(password, UIComparisonOperator.Equal, "The passwords differ.")
    
    public static TComponent ValidateAgainst<TComponent>(this TComponent input, UIComponentReference other,
        UIComparisonOperator @operator, string message,
        UIValidationTrigger trigger = UIValidationTrigger.Change, UIValidationSeverity severity = UIValidationSeverity.Error)
    

    UIComponentReference converts implicitly from either an IInputComponent / IVisualComponent instance or a string componentId (and ValidationInto, FilterBy and SortBy accept the target component instance directly the same way).

    It is judged in the browser as either field changes: a reader who types the second field first and then changes the first sees the second judged again. The field compared with is another input, read as its own rules read it, standing in the same row as the judged field or in none; a comparison names it (Equal, Greater…), never Required or a pattern. The server does not judge it again, as it judges no field's rules — a check the data depends on stays the command's.

    Every rule but Required passes an empty value, so a field left empty — tabbed through, never typed in — says only that it is required, and an optional field's pattern judges only what was typed. A rule that must refuse an empty field goes with Required; a toggle's false is a value, which a rule may judge.

    UIValidationTrigger is Change (default), Blur, or Submit. UIValidationSeverity is Error (default — stops a submit and draws the required marker when it is a Required rule), Warning, or Info; each colours the field's edge in its own colour. Each takes its message as a UIPhrase too, a key with arguments — .Regex(@"^.{0,40}$", UIPhrase.Of("form.max", ("max", 40))) — and a string message is translated as a plain value is (see Localization).

  2. The controller, through the bindable Validation property every IInputComponent has:

    new TextInputComponent().BindValidation(nameof(FormController.NameValidation))
    
    public static UIValidationMessage Error(string message)
    public static UIValidationMessage Warning(string message)
    public static UIValidationMessage Info(string message)
    // and the same three taking a UIPhrase
    

    null means no message. A controller's own message never blocks a submit — the controller wrote it and judges the value again on the next attempt; clearing it is the controller's job.

  3. The runtime, when it refuses a value the controller could not take.

  4. The field's bounds. A number, date or time typed past its Min or Max stays as typed and is refused in words — "At most 10.", "Not after 30.09.2026." — never pulled back to the bound and never sent, so the controller keeps the last value it took. An emptied field is no value, which an optional one takes.

Only an error from a client rule, the runtime or a bound stops OnSubmit(formId, command) from dispatching — the controller's own error does not gate the press.

A form

A form is not a component: it is a string id that a set of fields and a submit button share. SetFormId (or BindFormId) puts a field in it — any IInputComponent has FormId — and ButtonComponent.OnSubmit(formId, command) makes a button its submit button (OnSubmitShowingLoading(formId, command) also shows it busy for the command's round trip):

new StackPanelComponent()
    .SetSpacing(12)
    .AddChild(new TextInputComponent()
        .SetTitle("Email")
        .SetFormId(ProfileController.ProfileForm)
        .BindValue(nameof(ProfileController.Email), mode: UIBindingMode.OnSubmit)
        .Required("An email is required.", UIValidationTrigger.Submit)
        .Regex(@"^[^@\s]+@[^@\s]+\.[^@\s]+$", "That does not look like an email address.", UIValidationTrigger.Blur)
    )
    .AddChild(new TextInputComponent()
        .SetTitle("Display name")
        .SetFormId(ProfileController.ProfileForm)
        .BindValue(nameof(ProfileController.DisplayName))
    )
    .AddChild(new ButtonComponent()
        .SetTitle("Save")
        .SetVariant(UIButtonVariant.Primary)
        .OnSubmit(ProfileController.ProfileForm, nameof(ProfileController.Save))
    )
    .AddChild(new ButtonComponent()
        .SetTitle("Discard")
        .SetVariant(UIButtonVariant.Outline)
        .OnClick(nameof(ProfileController.Discard))
    )
public const string ProfileForm = "profile";

[UICommand]
public static UICommandResult Discard()
    => UICommandResult.Ok([new DiscardFormEffect(ProfileForm)]);

What the form id does:

  • It scopes a submit's validation. Pressing the submit button runs every Submit-trigger rule of the form's fields, then dispatches the command only if no field of the form holds an error — from those rules, from a Change or Blur rule failing at that moment, or from the runtime. A Warning or Info says its piece and lets the press through, and so does the controller's own message.
  • It is what an OnSubmit field waits for. A value bound OnSubmit stays in the browser until its form is submitted, and is sent after validation and before the command, so the command reads it already written. While the field holds an unsent edit, a value the server pushes does not overwrite it. A field bound OnSubmit with no form id fails the view's compile — its value could never be sent.
  • It lets Enter submit. Enter in a single-line field of a form presses the form's submit button, after the field has let go of its value. In a text area Enter breaks the line, unless the area says SetSubmitOnEnter(): then Enter commits its value and presses the form's button while the focus stays in the area, ready for the next message, and Shift+Enter breaks the line — a message the same as the last one is sent again once a push has cleared the area; an Enter that ends an input method's composition sends nothing. A text area that submits on Enter with no form id fails the view's compile.
  • It is a form to the browser too. The page carries a hidden <form> per form id, and the form's fields and submit button join it (form="ui-form-<id>"), so a password manager and autofill read each form apart: a sign-in's name and password share their form id, and a password that is no one's login (a token, a new password on a settings page) gets one of its own. A field with no form id stands in the page's own form. The browser's form submits nothing — everything above goes by the form id.

A field that takes one entry after another — a line added to a checklist, a label typed and added — needs no form: OnEnter on a text input or a text area runs a command on Enter. Enter alone commits the value first and the command waits for its answer, so it reads the value already written (and runs nothing for a value the controller refused); the field keeps the focus for the next entry and presses no form's button. In a text area Shift+Enter still breaks the line, and a chord keeps a field's ordinary rule. A held key runs it once, and a read-only, disabled or loading field runs nothing. In a row's template the row's key travels as any command's argument does:

new TextInputComponent()
    .SetPlaceholder("Add an item")
    .BindValue(nameof(ChecklistItem.Draft), UIBindingScope.Relative)
    .OnEnter(nameof(ChecklistController.AddItem), UIAction.ArgCurrentItemKey("id"))

A text area with both OnEnter and SubmitOnEnter fails the view's compile: Enter does one of them.

Escape leaves a field and commits what was typed in it. A field opened for a change — a message edited in the composer, a row's text edited in place — says OnEscape instead, and Escape becomes its cancel: the field goes back to the value it last committed (the one it was focused with, an earlier commit's, or one the server pushed since), what was typed after it is not sent and raises no change — a debounced field's waiting commit is dropped, not flushed — the field lets go of the focus as Escape always does, and then the command runs, with the row's key in a row's template, as OnEnter's does. A dialog or a popup the field stands in leaves that Escape to it, and the next one closes them. A held key runs it once; a read-only, disabled or loading field keeps the ordinary Escape and runs nothing. OnEscapeLiteral takes literal arguments.

new TextAreaComponent(ChatController.ComposerId)
    .BindValue(nameof(ChatController.Draft))
    .SetSubmitOnEnter()
    .SetFormId(ChatController.ChatForm)
    .OnEscape(nameof(ChatController.CancelEditAsync))

A form can mix modes: a TwoWay field (the display name above) sends each change as it happens and still counts in the form's validation, while an OnSubmit field (the email) reaches the controller only with the submit — the shape for a value that must not be half-written, or whose every change would start work on the server.

DiscardFormEffect(formId), returned from a command, drops the form's unsent edits: every OnSubmit field of the form shows the value the server holds again. What the page's rules, the bounds and the runtime said of every field of the form goes with them, changed or not, and the form stands as unvisited; the controller's bound message and a package's mark stay. A TwoWay field has nothing unsent to drop. The discard button is an ordinary OnClick — an OnSubmit one would send the edits before the command could throw them away.

A field's caption row is one caption line: a badge in it is centred on that line rather than growing the row, and a long caption ends in an ellipsis rather than wrapping its required mark. SetHelp(help) on any input fills its caption's badge: the help glyph alone, a UIBadgeVariant.Plain badge (no ground, in the muted ink, coming up to the text's ink under the pointer), with the words — a text, a key or a UIPhrase — as the badge's tooltip, translated as a badge's tooltip is; a blank text is refused. It sits where the input's badge sits: trailing at the caption row's end, unless SetBadgePlacement(UITextBadgePlacement.Inline) puts it beside the words, and beside a checkbox's or a switch's label. The badge is no tab stop: its words are the field control's accessible description, so a reader tabbing in hears them with the field, and the pointer's hover shows them; in a caption outside the field's box a press or a touch shows them too, the next press, on it or elsewhere, hides them, and a press on it never ticks the box around it:

new TextInputComponent()
    .SetTitle("Display name")
    .SetHelp("Shown beside your messages; your sign-in name stays private.")
    .BindValue(nameof(ProfileController.DisplayName))

A text input and a text area carry buttons of the author's at either end — AddLeadingAction and AddTrailingAction, as many as wanted, in the order added (on a text input SetTrailingAction puts one in place of all). A text input's stand in its row; a text area's stand beside its text on the bottom line, outside its scroll, and the text reaches the buttons after it in the tab order. A split button stands among them as compact as a plain one. Each also takes a FlyoutComponent: its anchor, which must be a button, stands with the others and its panel opens from it — an emoji panel, a list of snippets; a flyout whose anchor is no button is refused where it is added. On a select, search or multi-select, trailing actions stand inside the field before its rightmost divided chevron cell. Above the field, any input may carry compact actions on its 16 px caption line via SetHeaderAction / SetHeaderActions without raising the title or pushing the field box down, and a TextAreaComponent or CodeInputComponent configured with SetExpandable(...) adds a full-height modal expand mode (with separate inline and dialog parameters, also triggerable via ExpandFieldEffect). SetAutoGrow(maxRows) makes a text area grow with its text from its Rows to maxRows lines, then scroll. Together they are a chat's composer:

new TextAreaComponent("composer")
    .SetPlaceholder("Write a message")
    .SetRows(1)
    .SetAutoGrow(6)
    .SetSubmitOnEnter()
    .SetFormId(ChatController.ChatForm)
    .BindValue(nameof(ChatController.Draft))
    .AddLeadingAction(UIIconButtons.Attach().OnClick(nameof(ChatController.Attach)))
    .AddTrailingAction(UIIconButtons.Send().OnSubmit(ChatController.ChatForm, nameof(ChatController.Send)))

UIForm.Composer(textArea, attachments?, banners) wraps that composer text area in a calm SurfaceComponent (SetWindowFoot, no border or focus halo) with an optional shelf FileInputComponent wired to accept file drops across the panel and any quote banners above the field. Both TextInputComponent and TextAreaComponent also support inline trigger suggestions (@, /) via AddTrigger, SetTriggerItems/BindTriggerItems (UITextTriggerItem), OnTriggerSearch, OnTriggerSelect, and OnTriggerClick: typing a trigger character opens a suggestion popup at the caret (stepping into a second-level category or inserting a leaf token), and completed trigger tokens render as interactive inline pills that delete whole on Backspace/Delete and raise OnTriggerClick when clicked.

InsertTextEffect puts text at a field's caret from elsewhere, in place of its selection, as typing would — the caret after it, the field's own undo holding it, its binding and validation following (see interactions and effects). The field keeps its selection while the focus is in a panel beside it, so an emoji panel's tile inserts where the reader stopped:

new ButtonComponent()
    .SetTitle(emoji)
    .InteractOn("click", InsertTextEffect.Literal("composer", emoji))

A read-only or disabled field takes nothing, and a text longer than the room the field's MaxLength leaves is refused whole rather than cut.

Where to go next

  • Views for the placement grid and the fluent style Bind* is part of.
  • Controllers for the paths [RecursiveMember] properties expose.
  • Interactions and effects for interactions, which write a property directly rather than through a binding.