Control properties

ControlBase

Each control uses the abstract class ControlBase as a starting point to customize properties and behaviors.

Depending on the type of control, some properties are relevant and participate in loading, managing, and saving data.

The Json data is retrieved from the database through the FormStore and processed by FormService to create a Form instance with the Controls collection of ControlBase elements declined in various concrete classes (TextBox, Label, DropDownList, and so on).

Here is the form's lifecycle during the data reading phase:

And here is the write phase:

Properties of ControlBase

ControlBase provides concrete classes with a series of properties mapped onto their respective Json fields. Let's see which they are.

Property	Description
Name	The unique name of the control in the form.
Type	The type of control.
Group	The control group to apply cumulative events, like hiding an entire set of controls.
Title	The localized title of the control for the available cultures in the DataWeb instance. At least en-US is required.
DataField	The name of the field in the database.
DataSubField	If set and the DataType is Structured, then sets the value of this control as a node in a Json structure and saves it in DataField.
DataType	The data type for validation, formatting, saving, and native handling.
DataSourceMode	Allows setting the data source for controls that provide a list of values, such as DropDownList or CheckBoxList. For List value, data is taken from a DataWeb list; for ControlClass value, data is taken from the implemented method in the derived class GetListValuesAsync.
DataSource	The name of the data source. For DataSourceMode List, it's the name of the DataWeb list.
IsLateDataBinding	Specifies whether data retrieval occurs on form load or only on the execution of an event from another control. Used to load specific data based on the value of a previous control.
DefaultValueMode	Allows setting the default value. For Value, data is taken from DefaultValue; for ControlClass value, data is taken from the implemented method in the derived class GetDefaultValueAsync.
DefaultValue	Indicates the default value in string format to apply to the control when creating a new item.
IsVersionLinked	If active, upon saving, the control value will be replicated in all versions of the item.
IsVisible	Specifies whether the control is visible or hidden.
IsReadOnly	Specifies whether the control is read-only.
IsRequired	Specifies whether the control is required.
RegularExpression	Allows setting a validation RegEx for the data. Applies only to DataType String.
MaxLength	Allows setting a maximum length for the value. Applies only to DataType String.
StylePath	Specifies a dedicated style for the Html management controls.
FormName	Specifies the name of the form to use for controls with nested Json structures.
ListControlNames	Specifies values in table for controls with nested Json structures.
FileTagName	Specifies the tag to distinguish the uploaded file in the document repository.
FileTypes	Specifies the file types supported by the file upload control.
FileMaxSize	Specifies the maximum size in bytes of the file uploaded with the file upload control.
FileMaxCount	Indicates how many files can be concurrently processed by the file upload control.
CustomControlComponent	Allows specifying a custom Vue.js component for the control.
CustomControlOptions	Allows specifying custom options for the control in Json format.
ControlClass	Defines the concrete class of the control. If not specified, it is automatically set to the default one for Type.
IsVisibleRoles	Sets visibility permissions for the control based on user roles and the value of VisibleRoles.
VisibleRoles	Contains the roles enabled to view the control.
Actions	Contains actions set on the control, such as data updates or navigation to another section.
Events	Contains events set on the control to change the behavior (DataSource, IsVisible, IsRequired) of other dependent controls.

ControlBase Hooks

ControlBase provides a series of customizable methods that are executed during the control's lifecycle.

Hook	Description
GetDefaultValueAsync	Allows setting custom behavior for retrieving the default value of the control.
ProcessOnGetValueAsync	Allows setting custom behavior during the data retrieval phase. This hook, for example, allows transforming a value before it is displayed.
GetListValuesAsync	Allows setting a custom dataset.
ValidateAsync	Allows customizing data validation, for example, with a database-based check.
ProcessOnSaveDataAsync	Allows setting custom behavior during the data saving phase. This hook, for example, allows processing a value before it is saved, potentially involving other fields for multiple updates.
IsUpdateDataAsync	Indicates whether the data is updatable in the database. If false, the control is not considered during the data saving phase.
SetCustomActionAsync	Allows customizing behavior upon the execution of a server-side action on the control, such as sending a notification or running a process.

ControlBase Support Methods

These methods are used in the default implementations of the hooks and can be useful in customized versions.

Method	Description
GetControlDefaultValue	Retrieves the default value from the DefaultValue field, handling its conversion into the native type and managing boolean formatting.
ValidateControlIsRequired	Verifies that the value is present based on the control's DataType.
ValidateControlDataType	Validates the entered data format to comply with the control's DataType.
SanitizeControlValue	Removes all HTML tags from the entered value.
AddActionUpdateData	Adds an action to update the control's data.
AddActionSetNavigation	Adds an action to navigate to a DataWeb section.
AddActionSetRemoteAction	Adds an action to execute a server-side action.
AddActionSetLocalAction	Adds an action to execute a client-side action.
AddEventSetIsVisible	Adds a visibility event for a control or a group of controls.
AddEventSetIsRequired	Adds a required value event for a control or a group of controls.
AddEventSetDataSourceParameter	Adds a data update event for a control or a group of controls.

Control customization