Skip to main content

DataControl class

📖 Description​

The DataControl class is the base from which UI control classes are derived. It is an abstract class and cannot be instantiated directly. It is derived from the Control class and adds functionality to simplify data handling for the UI controls that use it.

📦 Derived controls​

The following controls are derived from this class and are available in the Forms module:

🆕 constructor​

Creates a new DataControl instance.

Signature​

constructor(binding: Binding, default: any, properties: IControlProperties): Control

Parameters​

Parameters​

NameTypeOptionalDescription
bindingBindingNoSpecifies the data binding (generated with the bind method).
defaultanyNoSpecifies the default (initial) value for the data.
propertiesIControlPropertiesNoSpecifies the control properties.

Return value​

Returns a reference to the new DataControl instance.

📌 Statics​

🔧 bind​

Binds an object property to the control allowing its value to update automatically when the value of the control changes. If the control is disabled or invisible, the supplied valueWhenInactive is automatically set as the property value. When a control is enabled and visible, the supplied defaultWhenActive is set automatically if the property value is currently not defined.

Signature​

bind<Target, P extends keyof Target>(
  target: Target,
  property: P,
  valueWhenInactive: Target[P],
  defaultWhenActive?: Target[P],
  modifier?: (value?: Target[P]) => Target[P]
): Binding;

Parameters​

NameTypeOptionalDescription
targetTargetNoReference to the target object which contains the property.
propertyPNoSpecifies the name of the property.
valueWhenInactiveTarget[P]NoSpecifies the value which is set to the property when the control is inactive (disabled or invisible).
defaultWhenActiveTarget[P]YesSpecifies the default (initial) value that will be used when the control is active (enabled and visible).
modifier(value?: Target[P]) => Target[P]YesSpecifies a modifier function for the data.

Return value​

Returns a Binding instance that can be used in the controls constructor to bind a value to a control.

🗃️ Fields​

🏷️ feature​

Retrieves a reference to the feature of the form card.

Type​

Feature | undefined

🏷️ form​

Sets or retrieves the parent form.

Type​

Form | undefined

🏷️ hasFocus​

Retrieves if the control has input focus.

Type​

boolean

🏷️ hasLabel​

Retrieves if a label is set.

Type​

boolean

🏷️ isAwaiting​

Sets or retrieves if the control validation is awaiting.

Type​

boolean

🏷️ isDisabled​

Sets or retrieves if the control is disabled.

Type​

boolean

🏷️ isFailed​

Sets or retrieves if the control validation has failed.

Type​

boolean

🏷️ isFeatureEnabled​

Retrieves if the control is attached to an enabled feature.

Type​

boolean

🏷️ isFormEnabled​

Retrieves if the form is enabled.

Type​

boolean

🏷️ isFormReady​

Retrieves if the form is ready.

Type​

boolean

🏷️ isFormVisible​

Retrieves if the form is visible.

Type​

boolean

🏷️ isFused​

Retrieves if the control is fused with the form card. This is only possible with controls which have no separate label and are the one and only control inside of the form.

Type​

boolean

🏷️ isGroupVisible​

Retrieves if the form group is visible.

Type​

boolean

🏷️ isHovered​

Retrieves if the control is hovered.

Type​

boolean

🏷️ isInteractable​

Retrieves if the control is interactable.

Type​

boolean

🏷️ isInvalid​

Sets or retrieves if the control validation is invalid.

Type​

boolean

🏷️ isLocked​

Sets or retrieves if the control is locked (readonly).

Type​

boolean

🏷️ isObservable​

Retrieves if the control is observable.

Type​

boolean

🏷️ isPassed​

Sets or retrieves if the control validation has passed.

Type​

boolean

🏷️ isReadable​

Specifies it the control value is readable.

Type​

boolean

🏷️ isRequired​

Sets or retrieves if the control is required.

Type​

boolean

🏷️ isVisible​

Sets or retrieves the visibility of the control.

Type​

boolean

🏷️ modes​

Retrieves the supported modes for the control.

Type​

Mode

🏷️ style​

Retrieves the control style.

Type​

Style | undefined

🏷️ stylesheet​

Retrieves the stylesheet for the control.

Type​

Stylesheet

🏷️ tab​

Retrieves the tab index for the control.

Type​

number

🏷️ validation​

Sets or retrieves the validation state of the control.

Type​

"unknown" | "fail" | "invalid" | "pass" | "await"

▶️ Methods​

🔧 autoFocus​

Enables auto-focus for the control.

Signature​

autoFocus(focusAuto?: boolean): this

Parameters​

NameTypeOptionalDescription
focusAutobooleanYesSpecifies if auto-focus is enabled or not.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 autoValidate​

Enables automatic control validation.

Signature​

autoValidate(
  fn: (
    control: Control,
    sType: "initial" | "revalidate" | "data" | "visible" | "disabled" | "required" | "locked" | "focus" | "blur",
    callback: Callback
  ) => "unknown" | "fail" | "invalid" | "pass" | "await" | Callback
): this

Parameters​

NameTypeOptionalDescription
fnSee signatureNoSpecifies the validator function.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 await​

Sets the control validation to waiting.

Signature​

await(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 bind​

Specifies a bind function (invoked when the control is initialized).

Signature​

bind(fn: (control: this) => void): this

Parameters​

NameTypeOptionalDescription
fn(control: this) => voidNoSpecifies the function to execute.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 blur​

Blurs the focus of the control.

Signature​

blur(): void

🔧 compactModeOnly​

Sets the control mode to compact only.

Signature​

compactModeOnly(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 destroy​

Destroys the control.

Signature​

destroy(): void

🔧 disable​

Disables the control.

Signature​

disable(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 disabled​

Specifies the state of the control.

Signature​

disabled(disabled?: boolean): this

Parameters​

NameTypeOptionalDescription
disabledbooleanYesSpecifies if the control is disabled (default is true).

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 draw​

Draws the control.

Signature​

draw(parent: Element): void

Parameters​

NameTypeOptionalDescription
parentElementNoReference to the parent form element.

🔧 enable​

Enables the control.

Signature​

enable(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 execute​

Specifies a function which is invoked when the control is initialized.

Signature​

execute(fn: (control: this) => void): this

Parameters​

NameTypeOptionalDescription
fn(control: this) => voidNoSpecifies the function to execute.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 fail​

Sets the control validation to failed.

Signature​

fail(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 focus​

Sets the focus to the control.

Signature​

focus(to?: "first" | "last"): boolean

Parameters​

NameTypeOptionalDescription
to"first" | "last"YesSpecifies if the focus should be set to the first or last item in the control (in case a control has multiple items).

Return value​

Returns true if the focus is set.

🔧 focusTo​

Sets the focus to the previous or next item in the control. Override this function if you need to shift focus within a control.

Signature​

focusTo(to: "previous" | "next"): boolean

Parameters​

NameTypeOptionalDescription
to"previous" | "next"NoSpecifies if the focus is set to the previous or next control.

Return value​

Returns true if the focus is set.

🔧 groupVisibility​

Specifies the visibility of the control group.

Signature​

groupVisibility(visible: boolean): void

Parameters​

NameTypeOptionalDescription
visiblebooleanNoSpecifies if the control group is visible.

🔧 hide​

Hides the control.

Signature​

hide(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔒 hover​

Sets the hover state.

Signature​

hover(hover: boolean): void

Parameters​

NameTypeOptionalDescription
hoverbooleanNoSpecifies if the hover is active.

🔧 indent​

Enables control indentation. This can only be set during construction.

Signature​

indent(size: number): this

Parameters​

NameTypeOptionalDescription
sizenumberNoSpecifies the indent size in pixels.

Return value​

Returns a reference to the Control instance to allow chaining.

🔒 initialized​

Marks the control as initialized.

Signature​

initialized(): void

🔒 input​

Sets the input data for the control.

Signature​

input(data: any): any

Parameters​

NameTypeOptionalDescription
dataanyNoSets the input data for the control.

Return value​

Returns the data value of the control.

🔧 invalid​

Sets the control validation to invalid.

Signature​

invalid(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔒 keyboard​

Attach keyboard events to the control.

Signature​

keyboard(
  element: Element,
  onEnter?: () => boolean,
  enterOverride?: boolean,
  onKeyPress?: (keyboardEvent: IKeyboardEvent) => boolean
): void

Parameters​

NameTypeOptionalDescription
elementElementNoReference to the element to bind the events to.
onEnter() => booleanYesSpecifies the function which is invoked when an enter is detected.
enterOverridebooleanYesOverrides the default enter behavior from an element (for example the textarea, default is false).
onKeyPress(keyboardEvent: IKeyboardEvent) => booleanYesInvoked when a key is pressed.

🔧 label​

Sets the label for the control.

tip

If you want to use markdown in the label, activate it first using the markdown method.

Signature​

label(label: string): this

Parameters​

NameTypeOptionalDescription
labelstringNoSpecifies the control label.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 labelCompact​

Sets the compact label for the control.

Signature​

labelCompact(label: string): this

Parameters​

NameTypeOptionalDescription
labelstringNoSpecifies the compact control label.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 lock​

Locks the control.

Signature​

lock(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 locked​

Specifies if the control is locked (readonly).

Signature​

locked(locked?: boolean): this

Parameters​

NameTypeOptionalDescription
lockedbooleanYesSpecifies if the control is locked/readonly (default is true).

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 markdown​

Specifies if the label should support markdown formatting.

Signature​

markdown(options?: IMarkdownOptions): this

Parameters​

NameTypeOptionalDescription
optionsIMarkdownOptionsYesSpecifies the markdown options.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 mode​

Sets the supported mode for the control.

Signature​

mode(mode: "compact" | "normal" | "both"): this

Parameters​

NameTypeOptionalDescription
mode"compact" | "normal" | "both"NoSpecifies the desired mode.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 normalModeOnly​

Sets the control mode to normal only.

Signature​

normalModeOnly(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔒 onBlur​

Invoked when the control loses focus.

Signature​

onBlur(): void

🔒 onChange​

Invoked when the control changed.

Signature​

onChange(
  change: "visible" | "disabled" | "required" | "locked" | "focus" | "hover" | "validation"
): void

Parameters​

NameTypeOptionalDescription
change"visible" | "disabled" | "required" | "locked" | "focus" | "hover" | "validation"NoSpecifies the change that occurred.

🔒 onData​

Invoked when the data of the control is changed.

Signature​

onData(): void

🔒 onDisable​

Invoked when the control is disabled.

Signature​

onDisable(): void

🔒 onDraw​

Abstract method

This method is abstract and needs implementation in the derived control class.

Invoked when the control should be drawn.

Signature​

onDraw(parent: Element): Element

Parameters​

NameTypeOptionalDescription
parentElementNoReference to the parent form element.

Return value​

Returns a reference to the control element.

🔒 onEnable​

Invoked when the control is enabled.

Signature​

onEnable(): void

🔒 onEnter​

Invoked when the enter (return) key is pressed.

Signature​

onEnter(element: Element): boolean

Parameters​

NameTypeOptionalDescription
elementElementNoReference to the element.

Return value​

Return true if you want to cancel key bubbling.

🔒 onEscape​

Invoked when the escape key is pressed.

Signature​

onEscape(element: Element): boolean

Parameters​

NameTypeOptionalDescription
elementElementNoReference to the element.

Return value​

Return true if you want to cancel key bubbling.

🔒 onExecute​

Invoked when the control is executed.

Signature​

onExecute(): void

🔒 onFocus​

Invoked when the control captures focus.

Signature​

onFocus(autoFocus: boolean): void

Parameters​

NameTypeOptionalDescription
autoFocusbooleanNoSpecifies if an auto-focus was active.

🔒 onFocusOptions​

Invoked when the focus state of the control is changed.

Signature​

onFocusOptions(): void

🔧 onFormActivate​

Invoked when the control form is activated.

Signature​

onFormActivate(): void

🔧 onFormDeactivate​

Invoked when the control form is deactivated.

Signature​

onFormDeactivate(): void

🔧 onFormDisable​

Invoked when the control form is disabled.

Signature​

onFormDisable(): void

🔧 onFormEnable​

Invoked when the control form is enabled.

Signature​

onFormEnable(): void

🔧 onFormResize​

Invoked when the parent form is resized.

Signature​

onFormResize(): void

🔧 onHide​

Invoked when the control is hidden.

Signature​

onHide(): void

🔒 onHover​

Invoked when the control is hovered.

Signature​

onHover(): void

🔧 onInit​

Invoked when the control is initialized.

Signature​

onInit(): boolean

Return value​

Return true if the control is initialized.

🔒 onLock​

Invoked when the control is locked.

Signature​

onLock(): void

🔧 onMeasure​

Invoked when the control is measured. A measure correction in pixels can be supplied in the return value.

Signature​

onMeasure(): number

Return value​

Returns the measure correction for the control.

🔧 onMode​

Invoked when the control mode is changed.

Signature​

onMode(): void

🔒 onOptional​

Invoked when the control is optional.

Signature​

onOptional(): void

🔧 onRequestAutoFocus​

Fired when auto-focus is requested.

Signature​

onRequestAutoFocus(): boolean

Return value​

Returns true if the focus is set.

🔒 onRequire​

Invoked when the control is required.

Signature​

onRequire(): void

🔧 onResized​

Invoked when the control is resized.

Signature​

onResized(): void

🔧 onShow​

Invoked when the control is shown.

Signature​

onShow(): void

🔒 onUnlock​

Invoked when the control is unlocked.

Signature​

onUnlock(): void

🔒 onUpdate​

Invoked when the control needs to be updated.

Signature​

onUpdate(): void

🔒 onValidate​

Invoked when the control validation state is changed.

Signature​

onValidate(): void

🔒 output​

Retrieves the output data for the control.

Signature​

output(): any

Return value​

Returns the data value of the control.

🔧 pass​

Sets the control validation to passed.

Signature​

pass(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 pauseBinding​

Pauses the data binding. The controls stops observing the property that is bound to the control and doesn't update it automatically when the data in the control changes. To resume it invoke resumeBinding.

Signature​

pauseBinding(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 readonly​

Makes the control readonly.

Signature​

readonly(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 redraw​

Redraws a control.

Signature​

redraw(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 reference​

Sets the control reference.

tip

This can be used in combination with the controlWithReference method of the Form class to retrieve a control from a form (in case you didn't assign the control instance to a variable).

Signature​

reference(reference: string): this

Parameters​

NameTypeOptionalDescription
referencestringNoSpecifies the reference.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 refresh​

Forces a data refresh, syncing the internal control data with the current bind data.

Signature​

refresh(): void

🔧 require​

Makes the control required.

Signature​

require(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 required​

Specifies if the control is required.

Signature​

required(required?: boolean): this

Parameters​

NameTypeOptionalDescription
requiredbooleanYesSpecifies if the control is required (default is true).

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 resize​

Resizes the parent form.

Signature​

resize(): void

🔧 resumeBinding​

Resumes the data binding after is was paused.

Signature​

resumeBinding(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 show​

Shows the control.

Signature​

show(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 unbind​

Specifies an unbind function (invoked when the control is destroyed).

Signature​

unbind(fn: (control: this) => void): this

Parameters​

NameTypeOptionalDescription
fn(control: this) => voidNoSpecifies the function to execute.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 unlock​

Unlocks the control.

Signature​

unlock(): this

Return value​

Returns a reference to the Control instance to allow chaining.

🔒 updateControl​

Updates the control state.

Signature​

updateControl(
  change: "visible" | "disabled" | "required" | "locked" | "focus" | "hover" | "validation",
): void
NameTypeOptionalDescription
change"visible" | "disabled" | "required" | "locked" | "focus" | "hover" | "validation"NoSpecifies what is changed.

🔒 updateFocus​

Updates the focus state of a control.

Signature​

updateFocus(
  hover: boolean,
  autoBlur: boolean,
  virtualElement?: Element,
  physicalElement?: Element
): void

Parameters​

NameTypeOptionalDescription
hoverbooleanNoSpecifies if the control has captured focus.
autoBlurbooleanNoSpecifies if the auto-blur should be used.
virtualElementElementYesSpecifies the virtual focus subject (the element that renders the visual focus indication).
physicalElementElementYesSpecifies the physical focus subject (the element that actually gets the focus, for example, a text input field).

🔧 validate​

Sets the validation state of the control or invokes a validation cycle if automatic validation is activated.

Signature​

validate(
  validation?: "unknown" | "fail" | "invalid" | "pass" | "await" | "initial" | "revalidate" | "data" | "visible" | "disabled" | "required" | "locked" | "focus" | "blur"
): this

Parameters​

NameTypeOptionalDescription
validation"unknown" | "fail" | "invalid" | "pass" | "await" | "initial" | "revalidate" | "data" | "visible" | "disabled" | "required" | "locked" | "focus" | "blur"YesSpecifies the validation state.

Return value​

Returns a reference to the Control instance to allow chaining.

🔧 visible​

Specifies the visibility of the control.

Signature​

visible(visible?: boolean): this

Parameters​

NameTypeOptionalDescription
visiblebooleanYesSpecifies if the control is visible (default is true).

Return value​

Returns a reference to the Control instance to allow chaining.