Light Dark System

Input Widget

Et2InputWidget Mixin

Overview

Et2InputWidget is the mixin that makes a widget an input: something with a value the user can change, that validates, and that gets submitted back to the server. Every field in this reference - textbox, select, date, checkbox, file - is built from it, on top of Et2Widget. 

export class Et2Example extends Et2InputWidget(LitElement) { … }
export class Et2Example extends Et2InputWidget(SlInput) { … }   // wrapping a Shoelace input

Value

The value is not declared here as a property, because each widget stores it in whatever shape suits it - a string, a number, an array for a multi-select, an object for a link. What the mixin defines is the contract around it: getInputNode() returns the element actually holding the value (often inside a Shoelace component’s shadow root), and handleSlChange() bridges a wrapped Shoelace component’s own change event to eTemplate’s.

Two things that catch people out:

  • A widget’s submitted value is not always what it displays. Check the individual widget’s page - a date widget displays in the user’s format but submits a fixed one, and a checkbox submits selectedValue/unselectedValue rather than true/false.
  • Setting a property before the element has upgraded is fine - Lit replays it - but calling a method or reading updateComplete is not. Wait for customElements.whenDefined() first.

Validation

validate() runs the widget’s validators and isValid() reports the result. needed marks a field as required. Validation errors sent by the server arrive through the array managers (Et2Widget) and are shown against the right field automatically.

hasFeedbackFor carries which kinds of feedback are currently displayed, which is how a field shows an error state without the template having to manage it.

Validation happens on submit, and a failing field blocks it. A button with noValidation submits anyway - useful for “cancel” or for a button that only needs the current values, not correct ones.

Submitting

submit() sends the surrounding eTemplate to the server. Which widgets contribute a value is worth being precise about, because it is a common source of “my value did not arrive”:

State Submits a value?
normal yes
hidden yes
readonly no
disabled when the page was generated or submitted no

See Disabled vs Readonly vs Hidden.

Focus and blur

et2HandleFocus() and et2HandleBlur() normalise focus handling across plain elements and wrapped Shoelace components, which report focus from inside their shadow root. autofocus puts the cursor in the field when the template loads.

disabled behaves normally here

Et2Widget’s base style hides a disabled widget outright (:host([disabled]) {display: none}). This mixin overrides that back to display: initial, so on an input disabled does what it should: the field stays visible and shows that it cannot be edited. That override is the reason inputs and everything else disagree about what disabled means.

Used by

This mixin is applied by the following widgets.

Properties

Name Description Type Default
autofocus Have browser focus this input on load. Overrides etemplate2.focusOnFirstInput(), use only once per page https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes boolean -
hasFeedbackFor Get a list of feedback types string[] -
translate List of properties that get translated Done separately to not interfere with properties - if we re-define label property, labels go missing. - -
needed Compatibility for deprecated name “needed”
use required instead 		- -

Methods

Name Description Arguments
et2HandleBlur() If the value is unchanged, put any held validation messages back Named et2HandleBlur to avoid overwriting handleBlur() in Shoelace components _ev: FocusEvent
et2HandleFocus() When input receives focus, clear any validation errors. If the value is the same on blur, we’ll put them back The ones from the server (ManualMessage) can interfere with submitting. Named et2HandleFocus to avoid overwriting handleFocus() in Shoelace components _ev: FocusEvent
getInputNode() Get input to e.g. set aria-attributes -
handleSlChange() Handle sl-change event from Shoelace components and dispatch a change event so anything listening for change events can react to it instead of having to listen for both sl-change and change. event:
isValid() Used by etemplate2 to determine if we can submit or not messages:
submit() Called whenever the template gets submitted. We return false if the widget is not valid, which cancels the submission. _values:
validate() Massively simplified validate, as compared to what ValidatorMixin gives us, since ValidatorMixin extends FormControlMixin which breaks SlSelect’s render() We take all validators for the widget, and if there’s a value (or field is required) we check the value with each validator. For array values we check each element with each validator. If the value does not pass the validator, we collect the message and display feedback to the user. We handle validation errors from the server with ManualMessages, which always “fail”. If the value is empty, we only validate if the field is required. skipManual:
_oldChange() Change handler calling custom handler set via onchange attribute _ev: Event