The properties of the control
Control
Each control uses the Control abstract class as a basis for customizing properties and behaviors.
Depending on the type of control, some properties are relevant and participate in the upload, management, and saving of data.
The Json data is retrieved from the database through FormStore and processed by FormService to create a Form instance with the Controls collection of Control elements declined in the various concrete classes (TextBox, Label, DropDownList and so on).
Here's the life cycle of the form during the data reading phase:
And here is the writing phase:
The properties of Control
Control provides concrete classes with a series of properties mapped to their Json fields. Let's see what they are.
| Property | Description |
|---|---|
| Name | The unique name of the control on the form. |
| Type | The type of control. |
| Group | The control group to apply cumulative events such as hiding an entire set of controls. |
Title | The title of the localized control for the cultures available in the DataWeb instance. At least en-US is required. |
| DataField | The name of the field in the database. |
DataSubField | If it is set and the DataType field is Structured, then it sets the value of this control as a node of a Json structure and saves it to the DataField. |
| Datatype | The data type for validation, formatting, saving and native management. |
DataSourceMode | Allows you to set the data source for controls that propose a list of values, such as DropDownList or CheckBoxList. In the case of a List value, the data are taken from a DataWeb list; in the case of a ControlClass value, the data is taken from the method implemented in the GetListValuesAsync derived class. |
| DataSource | The name of the data source. In case of DataSourceMode List is the name of the DataWeb list. |
| IsLateDataBinding | Specifies whether data is retrieved when the form is loaded or only when an event of another control is executed. It is used to create load specific data based on the value of a previous control. |
DefaultValueMode | Allows you to set the default value. In the case of Value, the data is taken from DefaultValue; in the case of a ControlClass value, the data is taken from the method implemented in the GetDefaultValueAsync derived class. |
DefaultValue | Indicates in string format the default value to be applied to the control when creating a new item. |
| IsVersionLinked | If active, the value of the control will be replicated in all versions of the item when saved. |
| IsLocalization | If on, enable value translation during the machine translation step |
IsVisible | Specifies whether the control is visible or hidden. |
IsReadOnly | Specifies whether the control is read-only. |
IsRequired | Specifies whether the check is required. |
RegularExpression | Allows you to set up a RegEx for data validation. This applies only to DataType String. |
MaxLength | Allows you to set a maximum length for the value. This applies only to DataType String. |
StylePath | Indicates a dedicated style for Html management controls. |
FormName | Specifies the name of the form to use for controls with nested Json structures. |
ListControlNames | Specifies table values for controls with nested Json structures. |
FileTagName | Specifies the tag to distinguish the file uploaded to 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 processed simultaneously by the file upload control. |
CustomControlComponent | Allows you to specify a custom Vue.js component for the control. |
CustomControlOptions | Allows you to specify custom options for the control in Json format. |
ControlClass | Defines the concrete class of control. If it is not specified, the default Type is automatically set. |
IsVisibleRoles | Set view permissions on the control based on the user's roles and the value of VisibleRoles. |
VisibleRoles | Contains the roles that are enabled to view the control. |
Actions | Contains actions set on the control such as updating data or navigating to another section. |
Events | Contains events that are set on the control to change the behavior (DataSource, IsVisible, IsRequired) of other dependent controls |
Control hooks
Control provides a number of customizable methods that are executed throughout the control lifecycle.
| Hook | Description |
|---|---|
GetDefaultValueAsync | Allows you to set a custom behavior for retrieving the control's default value. |
| ProcessOnTranslateAsync | Allows you to set a custom behavior during the automatic value translation phase |
ProcessOnGetValueAsync | Allows you to set a custom behavior during the data retrieval phase. For example, this hook allows you to transform a value before it is displayed. |
GetListValuesAsync | Allows you to set up a custom dataset. |
ValidateAsync | It allows you to customize the validation of the data with, for example, a check on the database |
ProcessOnSaveDataAsync | Allows you to set a custom behavior during the data saving phase. This hook allows for example to process a value before it is saved, possibly involving other fields for multiple updates. |
IsUpdateDataAsync | Indicates whether or not the data is updatable in the database. If not, the check is not considered during the data saving phase. |
ProcessActionAsync | Allows you to customize the behavior when performing a server-side action on the control, such as sending a notification or running a process. |
Control Support Methods
These methods are used in default hook implementations and can come in handy in custom versions.
| Method | Description |
|---|---|
GetControlDefaultValue | Retrieves the default value from the DefaultValue field and handles its conversion to the native type and handling the Boolean format. |
ValidateControlIsRequired | Verify that the value is present based on the control's DataType |
ValidateControlDataType | Validates the format of the entered data so that it respects the DataType of the control |
SanitizeControlValue | Remove all Html tags from the entered value |
AddActionUpdateData | Adds an action to update the control data |
| AddActionSetNavigation | Adds a navigation action 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 group of controls |
AddEventSetIsRequired | Adds a required value event for a control or group of controls |
AddEventSetDataSourceParameter | Adds a data refresh event for a control or group of controls |