UIFormContext

class UIFormContext

extends Component

Represents form field data that can be used by input field components. By default, a formContext property on AppActivity or ViewComponent instances is used, but an alternative form context instance may be bound using a UIForm or UIFormContextController component. Whenever the form data changes, an event of type UIFormContextChangeEvent (with name "FormChange") is emitted.

To create a typed form context instance, use the static create method instead of the constructor.

Constructor

<TData = any>(): UIFormContext<TData>

.create() static

<TData extends object>(values: TData): UIFormContext<TData>

Create a typed instance with given values.

.get()

<K extends keyof TData>(name: K): TData[K]

Retrieve the value for a field with given name.

.has()

(name: string): boolean

Returns true if the field with given name is set (but might be undefined).

.set()

(name?: keyof TData, value?: any, validate?: boolean, silent?: boolean): void

  • name — Name of the field to set.
  • value — New field value.
  • validate — Set to true to automatically run the validation test for this field, if any.
  • silent — Set to true to avoid emitting a change event after setting the value; this means that bound components will not be updated immediately, since the field value itself cannot be observed directly.

Set the value for a field with given name.

.unset()

(name: keyof TData): void

Remove the value for a field with given name, including any associated error, and emit a change event. The field will also no longer be validated.

.clear()

(): void

Remove all field values from this instance, including any associated errors, and emit a change event. None of the existing fields will be validated anymore, until they are set again (using set()).

.serialize()

(): any

Returns a plain object that contains properties for all fields and their values.

.required()

(name: keyof TData, description?: string): this

Add a validation test for a field with given name, which results in an error if the current value is undefined, null, false, or an empty string (but not the number ‘0’). The description is used for generating error messages.

.test()

<K extends keyof TData>(name: K, f: (test: ValidationTest<TData[K]>) => void): this

Add a validation test for a field with given name, replacing the current test for the same name, if any. The function is called whenever the field value changes (unless prevented using the respective parameter for the set() method) and upon invocation of validate() and validateAll() methods. If the function throws an error, either directly or using the methods of the UIFormContext.ValidationTest instance (single parameter), the resulting error is added to the errors object.

.validate()

(name: keyof TData): boolean

Validate the current value of a field with given name; updates the error object, but does not emit a change event. To add validation tests, use the test() method.

.validateAll()

(): this

Validate the current values of all fields that have been set; updates the error object, but does not emit a change event.

.errorCount

number

The number of errors that have been recorded after validation of one or more fields.

Note: This starts out at 0, and is only updated when values are set and/or validated. To retrieve the total number of errors for this instance, call validateAll() before reading this property.

.valid

boolean

True if there are currently no recorded errors.

Note: This only reflects validated fields; call validateAll() before reading this property to ensure all fields are tested first.

.errors

{ [name in keyof TData]: Error; }

All errors that have been recorded after validating one or more fields; see also errorCount.

.isPresetComponent() protected

(): boolean

Inherited from Component.isPresetComponent.

.delegateEvent() protected

(e: ManagedEvent, propertyName: string): boolean | void

Inherited from Component.delegateEvent.

.getParentComponent()

<TParent extends Component = Component>(ParentClass?: ComponentConstructor<TParent>): TParent

Inherited from Component.getParentComponent.

.getBoundParentComponent()

<TParent extends Component>(ParentClass?: ComponentConstructor<TParent>): TParent

Inherited from Component.getBoundParentComponent.

.emitAction()

(name: string, inner?: ManagedEvent, context?: ManagedObject): void

Inherited from Component.emitAction.

.propagateComponentEvent() deprecated

(name: string, inner?: ManagedEvent): void

Inherited from Component.propagateComponentEvent.

.managedId

number

Inherited from ManagedObject.managedId.

.managedState

ManagedState

Inherited from ManagedObject.managedState.

.getReferenceCount() protected

(): number

Inherited from ManagedObject.getReferenceCount.

.getManagedReferrers() protected

(): ManagedObject[]

Inherited from ManagedObject.getManagedReferrers.

.getManagedParent() protected

<TParent extends ManagedObject = ManagedObject>(ParentClass?: ManagedObjectConstructor<TParent>): TParent

Inherited from ManagedObject.getManagedParent.

.emit()

<TEvent extends ManagedEvent = ManagedEvent, TConstructorArgs extends any[] = any[]>(e: string | TEvent | (new (...args: TConstructorArgs) => TEvent), ...constructorArgs: TConstructorArgs): this

Inherited from ManagedObject.emit.

.emitChange()

(name?: string): void

Inherited from ManagedObject.emitChange.

.propagateChildEvents() protected deprecated

(...types: ((new (...args: any[]) => ManagedEvent) | ((e: ManagedEvent) => any))[]): this

Inherited from ManagedObject.propagateChildEvents.

.activateManagedAsync() protected

(): Promise<any>

Inherited from ManagedObject.activateManagedAsync.

.deactivateManagedAsync() protected

(): Promise<void>

Inherited from ManagedObject.deactivateManagedAsync.

.destroyManagedAsync() protected

(): Promise<void>

Inherited from ManagedObject.destroyManagedAsync.

.onManagedStateActivatingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateActivatingAsync.

.onManagedStateActiveAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateActiveAsync.

.onManagedStateDeactivatingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateDeactivatingAsync.

.onManagedStateInactiveAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateInactiveAsync.

.onManagedStateDestroyingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateDestroyingAsync.


UIFormContext.ValidationTest

Encapsulates the current value for a specific form field, as passed to validation test functions; see UIFormContext.test().

Constructor

<TValue>(name: string, value?: TValue): ValidationTest<TValue>

.name

string

The name of the form field being validated.

.value

TValue

The current form field value.

.required()

(description?: string): this

Throws an error when the current value is undefined, null, false, or an empty string (but not the number ‘0’); the resulting error refers to the field name, or given description.

.typeOf()

(typeName: string): this

Throws an error when the type of the current field value (result of the typeof operator) does not match given type.

.assert()

(condition: boolean, errorMessage: string): this

Throws an error when the given parameter is false; the resulting error is an instance of AppException with given error message.