kform/tech.ostack.kform/FormManager

FormManager

class FormManager @JvmOverloads constructor(formSchema: Schema<*>, initialValue: Any?, externalContexts: ExternalContexts? = null, validationMode: ValidationMode = ValidationMode.Auto, coroutineContext: CoroutineContext = Dispatchers.Default, autoInit: Boolean = true)(source)

Class responsible for managing the data and state of a form.

The form manager stores, provides access, and allows manipulating the content of a form with a provided formSchema in a concurrent and controlled manner. It further manages state associated with the different fields of the form such as keeping track of validation issues, "dirty" and "touched" states, and others.

All form value/state accesses and manipulations should go through an instance of the form manager, to make sure that changes are tracked and no "dangerous" concurrent operations are performed. As such, storing non-copied form values outside the form manager is highly discouraged. Certain methods like valueInfo, get, and validate take lambdas as arguments to guarantee that data access only happens within a "controlled environment", i.e. during the lifetime of the lambda.

A coroutineContext may be provided to specify the context of coroutines launched by the form manager.

Constructors

FormManager

@JvmOverloads

constructor(formSchema: Schema<*>, externalContexts: ExternalContexts? = null, validationMode: ValidationMode = ValidationMode.Auto, coroutineContext: CoroutineContext = Dispatchers.Default, autoInit: Boolean = true)

@JvmOverloads

constructor(formSchema: Schema<*>, initialValue: Any?, externalContexts: ExternalContexts? = null, validationMode: ValidationMode = ValidationMode.Auto, coroutineContext: CoroutineContext = Dispatchers.Default, autoInit: Boolean = true)

Types

Companion

object Companion

Properties

autoValidationStatus

val autoValidationStatus: StateFlow<AutoValidationStatus>

Status of the automatic validations.

Functions

addExternalIssues

suspend fun addExternalIssues(issues: Iterable<LocatedValidationIssue>)

Adds external issues to the form manager. Once added, each issue can be removed either manually via removeExternalIssues or automatically when the value referenced by the issue or one of the values referenced by the issue's dependencies change.

destroy

suspend fun destroy()

Destroys this form manager instance by cancelling its coroutine scope.

get

suspend fun <T, TResult> get(path: String, valueHandler: ValueHandler<T, TResult>): TResult

suspend fun <T, TResult> get(path: Path = AbsolutePath.ROOT, valueHandler: ValueHandler<T, TResult>): TResult

Runs the provided valueHandler with the single value at path. Returns the result of valueHandler.

getClone

suspend fun <T> getClone(path: String): T

suspend fun <T> getClone(path: Path = AbsolutePath.ROOT): T

Returns a clone (deep copy) of the single value at path. Equivalent to:

getExternalContext

suspend fun <T, TResult> getExternalContext(externalContextName: String, externalContextHandler: ExternalContextHandler<T, TResult>): TResult

Runs externalContextHandler with the external context named externalContextName currently available to validations.

has

suspend fun has(path: String): Boolean

suspend fun has(path: Path): Boolean

Returns whether there exists at least one value at a path matching path.

info

suspend fun <TResult> info(path: String, infoHandler: InfoHandler<TResult>): TResult

suspend fun <TResult> info(path: Path = AbsolutePath.MATCH_ALL, infoHandler: InfoHandler<TResult>): TResult

Runs infoHandler with all information of values at paths matching path. Returns the result of infoHandler.

init

suspend fun init(externalContexts: ExternalContexts? = null, validationMode: ValidationMode = ValidationMode.Auto, coroutineContext: CoroutineContext = Dispatchers.Default)

Initialises the form manager.

isDirty

suspend fun isDirty(path: String): Boolean

suspend fun isDirty(path: Path = AbsolutePath.ROOT): Boolean

Returns whether at least one value at a path matching path is dirty.

isPristine

suspend fun isPristine(path: String): Boolean

suspend fun isPristine(path: Path = AbsolutePath.ROOT): Boolean

Returns whether all values at a path matching path are pristine (i.e. are not dirty).

isTouched

suspend fun isTouched(path: String): Boolean

suspend fun isTouched(path: Path = AbsolutePath.ROOT): Boolean

Returns whether at least one value at a path matching path has been touched.

isUntouched

suspend fun isUntouched(path: String): Boolean

suspend fun isUntouched(path: Path = AbsolutePath.ROOT): Boolean

Returns whether all values at paths matching path are untouched (i.e. are not touched).

isValid

suspend fun isValid(path: String): Boolean

suspend fun isValid(path: Path = AbsolutePath.MATCH_ALL): Boolean

Returns whether the values at paths matching path are valid according to their schemas.

isValidPath

fun isValidPath(path: String): Boolean

fun isValidPath(path: Path): Boolean

Returns whether there exists at least one schema at a path matching path.

remove

suspend fun remove(path: String)

suspend fun remove(path: Path)

Removes the values matching path from their parent collection(s).

removeExternalContext

suspend fun <T> removeExternalContext(externalContextName: String): T?

Removes the external context with name externalContextName available to validations and returns it if it existed.

removeExternalIssues

suspend fun removeExternalIssues(path: String, code: String? = null)

suspend fun removeExternalIssues(path: Path = AbsolutePath.MATCH_ALL, code: String? = null)

Removes all external issues currently added to the form manager with paths matching path. If a code is provided, only the issues with the provided code are removed.

reset

suspend fun reset(path: String)

suspend fun reset(path: Path = AbsolutePath.ROOT)

Resets the values at path to their initial value.

schema

fun schema(path: String): Schema<*>

fun schema(path: Path = AbsolutePath.ROOT): Schema<*>

Returns the single schema matching path.

schemaInfo

fun schemaInfo(path: String): Sequence<SchemaInfo<*>>

fun schemaInfo(path: Path = AbsolutePath.MATCH_ALL): Sequence<SchemaInfo<*>>

Returns a sequence of information about the schemas at paths matching path.

set

suspend fun set(path: String, toSet: Any?)

suspend fun set(path: Path = AbsolutePath.ROOT, toSet: Any?)

Sets values at path with toSet.

setDirty

suspend fun setDirty(path: String)

suspend fun setDirty(path: Path = AbsolutePath.MATCH_ALL)

Sets all values at a path matching path as dirty, as well as their parents.

setExternalContext

suspend fun <T> setExternalContext(externalContextName: String, externalContext: T): T?

Sets an external context with name externalContextName to be available to validations and returns the previous external context associated with the same name if one existed.

setPristine

suspend fun setPristine(path: String)

suspend fun setPristine(path: Path = AbsolutePath.ROOT)

Sets all values at paths matching path as pristine (i.e. as not dirty), as well as their descendents.

setTouched

suspend fun setTouched(path: String)

suspend fun setTouched(path: Path = AbsolutePath.MATCH_ALL)

Sets all values at paths matching path as touched, as well as their parents.

setUntouched

suspend fun setUntouched(path: String)

suspend fun setUntouched(path: Path = AbsolutePath.ROOT)

Sets all values at paths matching path as untouched (i.e. as not touched), as well as their descendents.

setValidationMode

suspend fun setValidationMode(validationMode: ValidationMode)

Sets the validation mode.

suspend fun subscribe(path: String, onSubscription: OnSubscription? = null, eventHandler: EventHandler): Unsubscribe

suspend fun subscribe(path: Path = AbsolutePath.MATCH_ALL, onSubscription: OnSubscription? = null, eventHandler: EventHandler): Unsubscribe

Subscribes to all events with paths matching path by running eventHandler for each event. Returns a function that should be called to unsubscribe from the subscription.

validate

suspend fun validate(path: String): List<LocatedValidationIssue>

suspend fun validate(path: Path = AbsolutePath.MATCH_ALL): List<LocatedValidationIssue>

Validates all values at paths matching path and returns a list of all found validation issues.

suspend fun <TResult> validate(path: String, issuesHandler: IssuesHandler<TResult>): TResult

suspend fun <TResult> validate(path: Path = AbsolutePath.MATCH_ALL, issuesHandler: IssuesHandler<TResult>): TResult

Validates all values at paths matching path by running a function issuesHandler with the flow of all found validation issues. Returns the result of issuesHandler.

valueInfo

suspend fun <TResult> valueInfo(path: String, infoHandler: ValueInfoHandler<TResult>): TResult

suspend fun <TResult> valueInfo(path: Path = AbsolutePath.MATCH_ALL, infoHandler: ValueInfoHandler<TResult>): TResult

Runs the infoHandler lambda with the value-information of values at paths matching path. Returns the result of infoHandler.