Interface IFormService

Defines operations for loading, validating, and processing forms and their controls.

Namespace: DataWeb.Data

Assembly: DataWeb.Core.dll

Syntax

public interface IFormService

Methods

GetFormAsync(string, string, CancellationToken)

Loads and initializes a Form by name and optional culture.

Declaration

Task<Form> GetFormAsync(string name, string culture = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	name	The name of the form to load.
string	culture	The culture used to localize the form (e.g. it-IT). Defaults to the current thread culture.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<Form>	A task that returns the initialized Form.

GetFormDefaultValuesAsync(Form, IUser, string, NavigationContext, CancellationToken)

Resolves the default value for each control in the form that has a bound DataField.

Declaration

Task<Dictionary<string, object>> GetFormDefaultValuesAsync(Form form, IUser user, string itemId = null, NavigationContext navigationContext = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Form	form	The Form whose control defaults are resolved.
IUser	user	The IUser requesting the defaults.
string	itemId	The Id of the item context, if applicable.
NavigationContext	navigationContext	The NavigationContext for the form, if applicable.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<Dictionary<string, object>>	A task that returns a case-insensitive Dictionary<TKey, TValue> of control names to their default values.

GetFormValuesAsync(Form, Dictionary<string, object>, IUser, string, NavigationContext, Control, CancellationToken)

Reads the stored data for each visible control in the form and returns the processed values. Keys use Pascal case for root forms and camel case for nested forms (when parentControl is set). Reactive events are evaluated and applied to sibling controls after each value is resolved.

Declaration

Task<Dictionary<string, object>> GetFormValuesAsync(Form form, Dictionary<string, object> sectionData, IUser user, string itemId = null, NavigationContext navigationContext = null, Control parentControl = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Form	form	The Form whose control values are read.
Dictionary<string, object>	sectionData	The raw data record that provides the source values.
IUser	user	The IUser requesting the form; used to filter role-restricted controls.
string	itemId	The Id of the item being viewed, if applicable.
NavigationContext	navigationContext	The NavigationContext for the form, if applicable.
Control	parentControl	The parent Control when this form is nested inside another control, or null for the root form.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<Dictionary<string, object>>	A task that returns a case-insensitive Dictionary<TKey, TValue> of control names to processed values.

GetFormsAsync(FormFilter, string, CancellationToken)

Loads and initializes all forms matching the specified filter and culture.

Declaration

Task<IEnumerable<Form>> GetFormsAsync(FormFilter filter = null, string culture = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
FormFilter	filter	The FormFilter criteria to apply. Defaults to an empty filter (all forms).
string	culture	The culture used to localize the forms (e.g. it-IT). Defaults to the current thread culture.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<IEnumerable<Form>>	A task that returns the collection of initialized Form objects.

UpdateDataWithFormAsync(Dictionary<string, object>, Form, List<ProvidedValue>, IUser, string, NavigationContext, Control, CancellationToken)

Processes the submitted values for all eligible controls and writes the results into sectionData. Controls that are read-only, have no bound data field, or are not accessible to the user are skipped. Structured and sub-field data are serialized after all controls have been processed. When parentControl is null, the method is treated as the root form and structured fields are finalized.

Declaration

Task UpdateDataWithFormAsync(Dictionary<string, object> sectionData, Form form, List<Form.ProvidedValue> providedValues, IUser user, string itemId = null, NavigationContext navigationContext = null, Control parentControl = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Dictionary<string, object>	sectionData	The data record to update in place.
Form	form	The Form that defines the controls and their data bindings.
List<Form.ProvidedValue>	providedValues	The submitted values for the form's controls.
IUser	user	The IUser saving the form; used to filter role-restricted controls.
string	itemId	The Id of the item being edited, or null for new items.
NavigationContext	navigationContext	The NavigationContext for the form, if applicable.
Control	parentControl	The parent Control when this form is nested, or null for the root form.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task	A task that represents the asynchronous update operation.

ValidateControlContextAsync(string, string, string, IUser, CancellationToken)

Validates that the specified control exists in the form and is accessible to the user. Supports dot-notation paths (e.g. "ParentControl.ChildControl") to traverse nested forms. Optionally verifies that the control's type matches controlType.

Declaration

Task<ValidateControlContextResult> ValidateControlContextAsync(string formName, string controlFullName, string controlType, IUser user, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	formName	The name of the root form containing the control.
string	controlFullName	The dot-notation path to the control (e.g. "Section.FieldName").
string	controlType	The expected type of the control, or null to skip type validation.
IUser	user	The IUser whose role-based access is checked.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<ValidateControlContextResult>	A task that returns a ValidateControlContextResult with IsValid = true and the resolved form and control on success, or an error on failure.

ValidateControlContextWithActionAsync(string, string, string, string, string, string, Module, IUser, CancellationToken)

Validates control context in the presence of a ContextAction. When actionName is provided, the action is resolved from the source control (for "Form" context) or from the module, then the dialog form defined on the action is used to validate controlFullName. When actionName is empty, delegates directly to ValidateControlContextAsync(string, string, string, IUser, CancellationToken).

Declaration

Task<ValidateControlContextResult> ValidateControlContextWithActionAsync(string formName, string controlFullName, string controlType, string actionName, string actionContext, string sourceFullName, Module explorerModule, IUser user, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	formName	The name of the root form.
string	controlFullName	The dot-notation path to the control to validate.
string	controlType	The expected type of the control, or null to skip type validation.
string	actionName	The name of the action that provides the dialog form context, or null to skip action resolution.
string	actionContext	The context scope of the action (e.g. "Form" or a module context key).
string	sourceFullName	The dot-notation path to the source control that owns the action.
Module	explorerModule	The Module used to resolve module-level actions when actionContext is not "Form".
IUser	user	The IUser whose role-based access is checked.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<ValidateControlContextResult>	A task that returns a ValidateControlContextResult with IsValid = true and the resolved form and control on success, or an error on failure.

ValidateFormAsync(Form, List<ProvidedValue>, IUser, Dictionary<string, object>, string, NavigationContext, string, CancellationToken)

Validates all visible, non-read-only controls in the form that are accessible to the user. When prefix is provided, it is prepended to each error's Name (e.g. for nested list items).

Declaration

Task<List<ValidationError>> ValidateFormAsync(Form form, List<Form.ProvidedValue> providedValues, IUser user, Dictionary<string, object> sectionData, string itemId = null, NavigationContext navigationContext = null, string prefix = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Form	form	The Form to validate.
List<Form.ProvidedValue>	providedValues	The submitted values for the form's controls.
IUser	user	The IUser submitting the form; used to filter role-restricted controls.
Dictionary<string, object>	sectionData	The current data record, used by controls that cross-reference other fields during validation.
string	itemId	The Id of the item being edited, or null for new items.
NavigationContext	navigationContext	The NavigationContext for the form, if applicable.
string	prefix	An optional dot-notation prefix prepended to each error name (e.g. "Items.0").
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<List<ValidationError>>	A task that returns the list of ValidationError objects, empty if the form is valid.