Class Control

An abstract base class for controls that can be used on a form.

Inheritance

object

Control

ActionList

AutoComplete

AutoCompleteList

CheckBoxList

ColorPicker

CultureEditor

CustomControl

DataEditor

DateTimePicker

DropDownList

FileDownload

FileRender

FileUpload

Label

ListBox

ListEditor

NewsletterMailingList_MailingListPreview

NewsletterModel_NewsletterPreview

NewsletterModel_NewsletterSender

NewsletterRow_NewsletterReport

NewsletterSubscriber_TermsInfo

Note

RadioButtonList

Slug

TagEditor

TextArea

TextBox

TextEditor

TextEditorClassic

Title

User_AccountEditor

User_AccountNewsletter

User_TermsInfo

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: DataWeb.Data

Assembly: DataWeb.Core.dll

Syntax

public abstract class Control

Remarks

Initializes a new instance of the Control class with the specified form and service provider.

Constructors

Control(Form, IServiceProvider)

An abstract base class for controls that can be used on a form.

Declaration

protected Control(Form form, IServiceProvider serviceProvider)

Parameters

Type	Name	Description
Form	form	The form that the control belongs to.
IServiceProvider	serviceProvider	The service provider used to resolve dependencies.

Remarks

Initializes a new instance of the Control class with the specified form and service provider.

Fields

form

Declaration

protected readonly Form form

Field Value

Type	Description
Form

serviceProvider

Declaration

protected readonly IServiceProvider serviceProvider

Field Value

Type	Description
IServiceProvider

Properties

Actions

Gets or sets the list of actions associated with the control.

Declaration

public List<ContextAction> Actions { get; set; }

Property Value

Type	Description
List<ContextAction>

ControlClass

Gets or sets the CSS class for the control.

Declaration

public string ControlClass { get; set; }

Property Value

Type	Description
string

CustomControlComponent

Gets or sets the name of the custom control component.

Declaration

public string CustomControlComponent { get; set; }

Property Value

Type	Description
string

CustomControlOptions

Gets or sets the options for the custom control.

Declaration

public object CustomControlOptions { get; set; }

Property Value

Type	Description
object

DataField

Gets or sets the name of the data field that the control is bound to.

Declaration

public string DataField { get; set; }

Property Value

Type	Description
string

DataSource

Gets or sets the name of the data source that the control uses.

Declaration

public string DataSource { get; set; }

Property Value

Type	Description
string

DataSourceMode

Gets or sets the mode of the data source that the control uses.

Declaration

public string DataSourceMode { get; set; }

Property Value

Type	Description
string

DataSubField

Gets or sets the name of the subfield of the data field that the control is bound to.

Declaration

public string DataSubField { get; set; }

Property Value

Type	Description
string

DataType

Gets or sets the data type of the data field that the control is bound to.

Declaration

public string DataType { get; set; }

Property Value

Type	Description
string

DefaultValue

Gets or sets the default value of the control.

Declaration

public string DefaultValue { get; set; }

Property Value

Type	Description
string

DefaultValueMode

Gets or sets the mode of the default value of the control.

Declaration

public string DefaultValueMode { get; set; }

Property Value

Type	Description
string

Events

Gets or sets the list of events associated with the control.

Declaration

public List<Control.Event> Events { get; set; }

Property Value

Type	Description
List<Control.Event>

FileMaxCount

Gets or sets the maximum number of files that can be uploaded through the file input control.

Declaration

public int? FileMaxCount { get; set; }

Property Value

Type	Description
int?

FileMaxSize

Gets or sets the maximum size of the file that can be uploaded through the file input control.

Declaration

public long? FileMaxSize { get; set; }

Property Value

Type	Description
long?

FileTagName

Gets or sets the name of the file input control.

Declaration

public string FileTagName { get; set; }

Property Value

Type	Description
string

FileTypes

Gets or sets the list of file types that the file input control accepts.

Declaration

public List<string> FileTypes { get; set; }

Property Value

Type	Description
List<string>

FormName

Gets or sets the name of the form that the control belongs to.

Declaration

public string FormName { get; set; }

Property Value

Type	Description
string

Group

Gets or sets the group that the control belongs to.

Declaration

public string Group { get; set; }

Property Value

Type	Description
string

IsLateDataBinding

Gets or sets a value indicating whether the data binding is done at a later time.

Declaration

public bool IsLateDataBinding { get; set; }

Property Value

Type	Description
bool

IsLocalization

Gets or sets a value indicating whether the control supports localization.

Declaration

public bool IsLocalization { get; set; }

Property Value

Type	Description
bool

IsReadOnly

Gets or sets a value indicating whether the control is read-only.

Declaration

public bool IsReadOnly { get; set; }

Property Value

Type	Description
bool

IsRequired

Gets or sets a value indicating whether the control is required.

Declaration

public bool IsRequired { get; set; }

Property Value

Type	Description
bool

IsVersionLinked

Gets or sets a value indicating whether the control is linked to a version.

Declaration

public bool IsVersionLinked { get; set; }

Property Value

Type	Description
bool

IsVisible

Gets or sets a value indicating whether the control is visible.

Declaration

public bool IsVisible { get; set; }

Property Value

Type	Description
bool

IsVisibleRoles

Gets or sets a value indicating whether the control is visible to certain roles.

Declaration

public bool IsVisibleRoles { get; set; }

Property Value

Type	Description
bool

ListControlNames

Gets or sets a comma-separated list of the names of the controls in the list.

Declaration

public string ListControlNames { get; set; }

Property Value

Type	Description
string

MaxLength

Gets or sets the maximum length of the control value.

Declaration

public int? MaxLength { get; set; }

Property Value

Type	Description
int?

Name

Gets or sets the name of the control.

Declaration

public string Name { get; set; }

Property Value

Type	Description
string

RegularExpression

Gets or sets the regular expression that the control value should match.

Declaration

public string RegularExpression { get; set; }

Property Value

Type	Description
string

StylePath

Gets or sets the path to the style sheet for the control.

Declaration

public string StylePath { get; set; }

Property Value

Type	Description
string

Title

Gets or sets the title of the control.

Declaration

public string Title { get; set; }

Property Value

Type	Description
string

Type

Gets or sets the type of the control.

Declaration

public string Type { get; set; }

Property Value

Type	Description
string

VisibleRoles

Gets or sets the list of roles that the control is visible to.

Declaration

public List<string> VisibleRoles { get; set; }

Property Value

Type	Description
List<string>

Methods

AddActionSetLocalAction(string, string, ContextActionType)

Adds a client-side local action to the control's Actions list. Local actions are handled entirely on the client without a server round-trip.

Declaration

public void AddActionSetLocalAction(string title, string name, ContextActionType type)

Parameters

Type	Name	Description
string	title	The display title of the action.
string	name	The client-side name used to identify and dispatch the action.
ContextActionType	type	The ContextActionType of the action.

AddActionSetNavigation(string, Step, List<Step>)

Adds a navigation action to the control's Actions list.

Declaration

public void AddActionSetNavigation(string title, ContextAction.Step currentStep, List<ContextAction.Step> newSteps)

Parameters

Type	Name	Description
string	title	The display title of the action.
ContextAction.Step	currentStep	The current ContextAction.Step to replace in the navigation context, or null to append.
List<ContextAction.Step>	newSteps	The ContextAction.Step objects that define the target navigation state.

AddActionSetNavigation(string, List<Step>)

Adds a navigation action to the control's Actions list without a current step.

Declaration

public void AddActionSetNavigation(string title, List<ContextAction.Step> newSteps)

Parameters

Type	Name	Description
string	title	The display title of the action.
List<ContextAction.Step>	newSteps	The ContextAction.Step objects that define the target navigation state.

AddActionSetRemoteAction(string, string, ContextActionType, string, bool, bool, bool)

Adds a remote action to the control's list of actions. Remote actions are executed server-side and can optionally display a confirmation dialog, save the item before processing, or reload after completion.

Declaration

public void AddActionSetRemoteAction(string title, string name, ContextActionType type, string dialogFormName = null, bool isConfirmRequired = false, bool isSaveItemBeforeProcess = false, bool isReloadAfterProcess = false)

Parameters

Type	Name	Description
string	title	The display title of the action.
string	name	The server-side name used to identify the action in ProcessActionAsync(ContextAction, IUser, string, object, List<ProvidedValue>, NavigationContext, CancellationToken).
ContextActionType	type	The ContextActionType of the action.
string	dialogFormName	The name of the form to display in a dialog before the action is executed, if applicable.
bool	isConfirmRequired	When true, the user must confirm before the action is executed.
bool	isSaveItemBeforeProcess	When true, the item is saved before the action is executed.
bool	isReloadAfterProcess	When true, the page is reloaded after the action completes.

AddActionUpdateData()

Adds a standard UpdateData action to the control's Actions list. This action signals the client to submit updated data when triggered.

Declaration

public void AddActionUpdateData()

AddEventSetDataSourceParameter(List<string>, List<string>)

Adds an event that propagates the value of one or more source controls as a data-source parameter to one or more target controls, allowing dynamic filtering of their data sources.

Declaration

public void AddEventSetDataSourceParameter(List<string> referenceNames, List<string> targetNames)

Parameters

Type	Name	Description
List<string>	referenceNames	The names of the controls whose values are used as parameters.
List<string>	targetNames	The names of the controls whose data-source parameters are updated.

AddEventSetIsRequired(EventCondition, List<string>, List<string>)

Adds an event that controls the required state of one or more target controls based on a condition evaluated against this control's value.

Declaration

public void AddEventSetIsRequired(EventCondition condition, List<string> referenceValues, List<string> targetNames)

Parameters

Type	Name	Description
EventCondition	condition	The EventCondition that triggers the required-state change.
List<string>	referenceValues	The values against which the condition is evaluated.
List<string>	targetNames	The names of the controls whose required state is affected.

AddEventSetIsVisible(EventCondition, List<string>, List<string>, bool)

Adds an event that controls the visibility of one or more target controls based on a condition evaluated against this control's value.

Declaration

public void AddEventSetIsVisible(EventCondition condition, List<string> referenceValues, List<string> targetNames, bool isKeepValueOnHidden = true)

Parameters

Type	Name	Description
EventCondition	condition	The EventCondition that triggers the visibility change.
List<string>	referenceValues	The values against which the condition is evaluated.
List<string>	targetNames	The names of the controls whose visibility is affected.
bool	isKeepValueOnHidden	When true, the target controls retain their current value when hidden. Defaults to true.

GetControlDefaultValue()

Resolves the default value for this control based on DefaultValueMode and DefaultValue. When DataType is "Boolean" and no explicit default is set, returns false.

Declaration

public object GetControlDefaultValue()

Returns

Type	Description
object	The resolved default value, or null if no default applies.

GetDefaultValueAsync(IUser, string, NavigationContext, CancellationToken)

Gets the default value for the control asynchronously. The base implementation delegates to GetControlDefaultValue().

Declaration

public virtual Task<object> GetDefaultValueAsync(IUser user, string itemId = null, NavigationContext navigationContext = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IUser	user	The IUser for whom to get the default value.
string	itemId	The Id of the item to which the default value is associated, if applicable.
NavigationContext	navigationContext	The NavigationContext, if applicable.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<object>	A task that represents the asynchronous operation and returns the default value for the control.

GetListValuesAsync(Dictionary<string, object>, IUser, string, NavigationContext, CancellationToken)

Gets the selectable list items for the control asynchronously. When DataSourceMode is "List", the items are loaded from the list identified by DataSource. Override to provide a custom data source.

Declaration

public virtual Task<IEnumerable<List.ListItem>> GetListValuesAsync(Dictionary<string, object> parameters, IUser user, string itemId = null, NavigationContext navigationContext = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Dictionary<string, object>	parameters	Optional parameters forwarded to the data source.
IUser	user	The IUser requesting the list values.
string	itemId	The Id of the item for which the list values are requested, if applicable.
NavigationContext	navigationContext	The NavigationContext, if applicable.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<IEnumerable<List.ListItem>>	A task that represents the asynchronous operation and returns the list items for the control.

InitAsync(CancellationToken)

Initializes the control asynchronously. Override to register actions and events.

Declaration

public virtual Task InitAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

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

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

Determines whether the submitted value for this control should be persisted. Returns true by default; override to conditionally skip persistence (e.g. for read-only or computed controls).

Declaration

public virtual Task<bool> IsUpdateDataAsync(object value, List<Form.ProvidedValue> providedValues, Dictionary<string, object> sectionData, IUser user, string itemId = null, NavigationContext navigationContext = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
object	value	The submitted value of the control.
List<Form.ProvidedValue>	providedValues	All values provided for the form submission.
Dictionary<string, object>	sectionData	The section data associated with the current item.
IUser	user	The IUser saving the form.
string	itemId	The Id of the item being edited, or null when adding a new item.
NavigationContext	navigationContext	The NavigationContext of the form, if applicable.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<bool>	A task that returns true if the value should be persisted; otherwise false.

ProcessActionAsync(ContextAction, IUser, string, object, List<ProvidedValue>, NavigationContext, CancellationToken)

Processes a ContextAction triggered on this control. The base implementation returns a successful result without performing any operation. Override to handle control-specific actions.

Declaration

public virtual Task<ContextAction.Result> ProcessActionAsync(ContextAction action, IUser user, string itemId = null, object value = null, List<Form.ProvidedValue> controlValues = null, NavigationContext navigationContext = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ContextAction	action	The action to perform.
IUser	user	The IUser performing the action.
string	itemId	The Id of the item being edited, or null when adding a new item.
object	value	The current value of the control at the time the action is triggered, if applicable.
List<Form.ProvidedValue>	controlValues	The values of all controls on the form at the time the action is triggered, if applicable.
NavigationContext	navigationContext	The NavigationContext of the form, if applicable.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<ContextAction.Result>	A task that represents the asynchronous operation and returns the action result.

ProcessOnGetValueAsync(object, Dictionary<string, object>, IUser, string, NavigationContext, CancellationToken)

Processes the raw stored value before it is returned to the client. Override to apply transformations such as parsing, formatting, or enrichment. The base implementation returns the value unchanged.

Declaration

public virtual Task<object> ProcessOnGetValueAsync(object value, Dictionary<string, object> sectionData, IUser user, string itemId = null, NavigationContext navigationContext = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
object	value	The raw value retrieved from the data store.
Dictionary<string, object>	sectionData	The section data associated with the current item.
IUser	user	The IUser requesting the value.
string	itemId	The Id of the item to which the value belongs, if applicable.
NavigationContext	navigationContext	The NavigationContext, if applicable.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<object>	A task that represents the asynchronous operation and returns the processed value.

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

Processes and sanitizes the control value before it is persisted. Override to apply transformations such as parsing, formatting, or storage-specific encoding. The base implementation strips HTML from String values via SanitizeControlValue(object).

Declaration

public virtual Task<object> ProcessOnSaveDataAsync(object value, List<Form.ProvidedValue> providedValues, Dictionary<string, object> sectionData, IUser user, string itemId = null, NavigationContext navigationContext = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
object	value	The value submitted for this control.
List<Form.ProvidedValue>	providedValues	All values provided for the form submission.
Dictionary<string, object>	sectionData	The section data associated with the current item.
IUser	user	The IUser saving the form.
string	itemId	The Id of the item being edited, or null when adding a new item.
NavigationContext	navigationContext	The NavigationContext of the form, if applicable.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<object>	A task that represents the asynchronous operation and returns the processed value to persist.

ProcessOnTranslateAsync(object, Dictionary<string, string>, Dictionary<string, object>, string, string, IUser, string, NavigationContext, CancellationToken)

Processes the control value during a translation operation. Override to apply culture-specific transformations. The base implementation returns the value unchanged.

Declaration

public virtual Task<object> ProcessOnTranslateAsync(object value, Dictionary<string, string> translatedValues, Dictionary<string, object> sectionData, string culture, string sourceCulture, IUser user, string itemId = null, NavigationContext navigationContext = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
object	value	The value to process.
Dictionary<string, string>	translatedValues	A dictionary of already-translated values keyed by field name.
Dictionary<string, object>	sectionData	The section data associated with the current item.
string	culture	The target culture (e.g. it-IT).
string	sourceCulture	The source culture from which the translation originates.
IUser	user	The IUser performing the translation.
string	itemId	The Id of the item being translated, if applicable.
NavigationContext	navigationContext	The NavigationContext, if applicable.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<object>	A task that represents the asynchronous operation and returns the processed value.

SanitizeControlValue(object)

Sanitizes the control value by stripping HTML tags when DataType is "String". Values of other data types are returned unchanged.

Declaration

public object SanitizeControlValue(object value)

Parameters

Type	Name	Description
object	value	The raw control value to sanitize.

Returns

Type	Description
object	The sanitized value, with HTML stripped for string data types.

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

Validates the control value asynchronously. The base implementation checks whether the control is required (via ValidateControlIsRequired(object)) and whether the value matches the declared DataType (via ValidateControlDataType(object)).

Declaration

public virtual Task<List<ValidationError>> ValidateAsync(object value, List<Form.ProvidedValue> providedValues, Dictionary<string, object> sectionData, IUser user, string itemId = null, NavigationContext navigationContext = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
object	value	The value of the control to validate.
List<Form.ProvidedValue>	providedValues	All values provided for the form submission.
Dictionary<string, object>	sectionData	The section data associated with the current item.
IUser	user	The IUser submitting the form.
string	itemId	The Id of the item being edited, or null when adding a new item.
NavigationContext	navigationContext	The NavigationContext of the form, if applicable.
CancellationToken	cancellationToken	A token to monitor for cancellation requests.

Returns

Type	Description
Task<List<ValidationError>>	A task that represents the asynchronous operation and returns the list of validation errors, if any.

ValidateControlDataType(object)

Validates whether the value of a control matches its data type. Decimal values are parsed using invariant culture. String values are checked against MaxLength and RegularExpression when set; the regex match is evaluated with a 1-second timeout to prevent ReDoS attacks.

Declaration

public List<ValidationError> ValidateControlDataType(object value)

Parameters

Type	Name	Description
object	value	The value of the control.

Returns

Type	Description
List<ValidationError>	A list of validation errors.

ValidateControlIsRequired(object)

Validates whether a required control has a non-empty value. The check is data-type aware: String uses IsNullOrEmpty(string), Boolean requires true, and all other types require a non-null value. Returns an empty list when IsRequired is false.

Declaration

public List<ValidationError> ValidateControlIsRequired(object value)

Parameters

Type	Name	Description
object	value	The value of the control to check.

Returns

Type	Description
List<ValidationError>	A list containing a ValidationError if the control is required and the value is empty; otherwise an empty list.

Extension Methods

FormMapperExtension.ToControlInfo(Control, Dictionary<string, object>, Dictionary<string, object>)