IField Interface

Defines an individual field in a mapper. Mappers implement the IMapper interface and are the platform's implementation of an Object Relational Mapper (ORM). The mapper acts as a sophisticated RecordSet that performs database binding and exposes data from the database for programmatic manipulation and display.

The mapper contains a set of fields in its IMapper.Fields collection (a Fields collection object). Each field typically corresponds to a column in the mapper's underlying view. However multiple fields can be mapped to a single column (using the AliasName property) and a field can be marked as ExcludeFromSelect to indicate that there is no corresponding column in the view.

The field object is used to read, insert, and update column values via the Value property. It is also used to manage presentation layer information and to expose all the field's meta-data settings.

Each field has a specified CellTypes that dictates its basic UI implementation. A set of FieldAttrs provide high-level control over field behaviour.

The Field's Exec(FieldExecCmds, Int32, Object) method exposes additional functionality via FieldExecCmds.

Fields are often referenced in expressions using field references. Field reference expressions are handled by the ExpressionParser class and can be resolve by calling ResolveExpression(IMapper, String, ExpressionResolutionFlags).

Namespace: NetQuarry.Data
Assembly: EAP.Core (in EAP.Core.dll) Version: 2.0.0.0 (4.6.8.0)

Syntax

Copy

public interface IField

Public Interface IField

The IField type exposes the following members.

Properties

	Name	Description
	AliasName	The name of the field in the mapper's view/table. Typically this is the same as the Key. One use of alias is to map two fields to the same column in the view/table. Obviously in such a case care must be taken to ensure that there is no data loss due to a user setting both fields to different values. Typically one or both are locked.
	Anomalies	Gets/sets certain field anomalies. This is primarily intended for internal use.
	Attributes	FieldAttrs flags specifying various behaviour of the field and apply to all fields. Additional CellType-specific attributes, per the CellTypes specified in the field's CellType property, are available via CellTypeAttributes. Both Attributes and CellTypeAttributes are normally loaded from meta-data during Load and can be set or altered programmatically.
	BaseControl	The WebControl bound to this field. The field may also have a LabelControl associated with it.
	Caption	The localized caption for the field. The Caption is typically used for field label text. For retrieving a caption for the field with additional options, use LabelText providing LabelFlags.
	CellType	The type of control or use for the field. The CellTypes dictates much of the behaviour of the field in the UI. Note that CellType determines the enumeration represented by CellTypeAttributes.
	CellTypeAttributes	CellType-specific attributes dictating the behaviour for the field in a manner specific to the field's CellType. In addition to these CellType-specific attributes, Attributes contains FieldAttrs that apply to all fields regardless of CellType. Depending on the CellType this property's value will represent attributes from the following enums: Button - CellButtonAttrs CheckBox - CellCheckBoxAttrs Chooser - CellChooserAttrs ComboBox - CellComboBoxAttrs Currency - CellCurrencyAttrs DatePicker - CellDatePickerAttrs DateTimePicker - CellDateTimePickerAttrs Dynamic - No CellTypeAttributes are defined for this CellType. EmailAddr - CellEmailAddrAttrs FilePath - CellFilePathAttrs FileUploader - CellFileUploaderAttrs Find - CellFindAttrs GroupBox - CellGroupBoxAttrs Html - CellHtmlAttrs HtmlEditor - No CellTypeAttributes are defined for this CellType. Icon - CellIconAttrs Label - CellLabelAttrs Link - CellLinkAttrs ListBox - CellListBoxAttrs MapperSummary - CellMapperSummaryAttrs MultiSelect - CellMultiSelectAttrs Password - CellPasswordAttrs Picture - CellPictureAttrs RadioButtons - CellRadioButtonsAttrs RatingIcon - CellRatingIconAttrs SecureText - CellSecureTextAttrs ShadowColumn - No CellTypeAttributes are defined for this CellType. Signature - CellSignatureAttrs Sorter - No CellTypeAttributes are defined for this CellType. TabStrip - No CellTypeAttributes are defined for this CellType. TextBox - CellTextBoxAttrs TextWithWidget - CellTextWithWidgetAttrs TimeDuration - CellTimeDurationAttrs TimePicker - CellTimePickerAttrs Tree - CellTreeAttrs Unknown - No CellTypeAttributes are defined for this CellType. Url - CellUrlAttrs WebSite - CellWebSiteAttrs
	ColumnName	The name of the field's underlying column in the database. Typically this is the same as the Key.
	ColWidth	The width, in approximate characters, to use for the field in datasheets and other dynamically generated UI mappers. When zero the field is hidden.
	ControlName	The name of the control to which this field should bind. This is generally the same as the Key. In dynamically generated pages the ControlName is used as the ID of the dynamically generated control. In custom contols (ascx) used bound to a mapper, the ControlName may vary from the Key in order to match the ID of the control on the page.
	Database	The data IDatabase used by the field. The data database holds the field's operational data. Meta-data is stored in the Repository.
	DataTableColIndex	Internal use only. Sets the index of this field in the DataTable used for binding.
	DataType	The .Net data type of the field. For example, a string would have a DataType of "System.String". Note that there is not a one-to-one mapping of .Net data types to DBMS data types. For example, SQL-Server char, nchar, varchar, nvarchar, text, and ntext all map to System.String.
	DefaultValue	The default Value for the field to use when moving to a new record. The DefaultValue may take the form of an embedded function such as !fnUserID() or !fnNow() to be evaluated when the default is set. See EmbeddedParser for more information on embedded functions. A field initialized from its DefaultValue will not be made Dirty unless DefaultMakesDirty is set. You can handle the RowSetDefaults event to set a field's DefaultValue programmatically just prior to its being applied to a new record. If DefaultFromParent is set, the mapper will attempt to default the field's value from the corresponding field in any parent IMapper. Set UseDefaultOnUpdate to use the field's DefaultValue to set the field's Value (if field is not Dirty) on every update. This is commonly used to maintain updated_dt and updated_by fields.
	Description	The localized description for the field.
	Dirty	Indicates whether the field's value has changed since loaded by its mapper. Normally the Dirty flag is set automatically when Value is set programmatically or due to user action in the UI. You can set Dirty programmatically if desired. The Dirty flag is used by the mapper when determining which fields to write during an UPDATE operation. To set a field value without making it dirty, use SetValue(Object, SetValFlags, Object).
	ExcludeFlavor	ExcludeFlavor is used indicate that a field should be included from any mapper if a corresponding Flavor is set. Fields that are excluded are not hidden; they are never loaded into the mapper's Fields collection. A zero ExcludeFlavor indicates that the field should not be omitted from any mappers (unless specifically marked for limited inclusion using IncludeFlavor). If a field is marked as both included and excluded for a particular Flavor then the exclude bit is favored.
	FieldID	The primary key for the field record in the database. This is unique across all fields in all mappers. The Key is only unique within a single mapper. FieldID is a GUID.
	Format	Data type-specific format specification instructing the field on how to display its data and how to parse a value out of user entered text. Most standard .Net formatting is supported and formatting is locale-appropriate. Additional formatting specifications are provided to extend those provided by .Net. Examples Here
	IncludeFlavor	IncludeFlavor is used indicate that a field should only be included in a mapper if a corresponding Flavor is set. Fields that are note included are not hidden; they are never loaded into the mapper's Fields collection. A zero IncludeFlavor indicates that the field should be loaded into all mappers (unless specifically for exclusions using ExcludeFlavor). If a field is marked as both included and excluded for a particular Flavor then the exclude bit is favored.
	Key	The unique ID for this field in its mapper. Generally the Key corresponds to the column name in the mapper's view or table, to the column name in the underlying table, and the ID of bound controls. These correlations can be overridden by the field's AliasName, ColumnName, and ControlName properties respectively.
	LabelControl	The Label control bound to this field based on AssociatedControlID. The field may also have a BaseControl.
	Locked	Indicates whether the field should be locked. The property evaluates to true if the column is locked due to any of a number of reasons, including: The field's Locked attribute is set. The field is locked due to ObjectPermissions reasons. The field's table does not have a primary key identified or the field is marked ExcludeFromSelect. The field's mapper does not allow insert/update (as applies to the current record state), e.g. the mapper's DenyInsert and/or DenyUpdate is set. The field is an identity column. The field is RowLocked. Locked was set programmatically. You can set Locked programmatically if desired. Note that a locked field will be locked in the application UI, but may still be set programmatically (that is, it is not locked against programmers).
	Mapper	The live IMapper object owning this field.
	NativeDbType	The native data type name for the field's column in the database. For example, SQL-Server supports the following string data types: char, nchar, varchar, nvarchar, text, and ntext.
	OldValue	The original value as loaded by the mapper. The OldValue is set automatically from Value when Value is set to a new value.
	OleDbType	The field's column's data type in the underlying database as mapped to OleDbType. The OleDbType is used to determine the way the column can be set, read, filtered and sorted. For example, the SQL-Server text and ntext data types are mapped to the corresponding LongVarChar and LongVarWChar, respectively and in SQL-Server have limited filtering capability and cannot be used to sort.
	Picklist	The live Picklist object associated with this field. Picklists are sophisticated vocabulary lists that are used to resolved underlying values to their display equivalents (e.g. 1=California, 2=New York, 3=Texas, etc.). Picklists values can be specified using SQL queries, meta-data specified lists, numeric ranges and other platform-provided mechanisms and even populated programmatically.
	PicklistID	The ID of the Picklist associated with this field and available through the field's Picklist property.
	Properties	The field's Properties collection. Properties can be specified in meta-data using the field's property sheet, or programmatically. Properties are used to specify many aspects of field appearance and behaviour. The Properties collection is loaded by Load.
	Repository	The repository IDatabase used by the field. The repository holds the field's meta-data. Operational data is stored in the Database.
	RowLocked	Specifies whether or not the field should be locked for the current row only. This property is cleared by the mapper immediately prior to the RowCurrent event. An extension can then set the property to true to lock this field for that row only. To perform row locking on the entire row set the RowLocked property. The field will be locked for all the static reasons (e.g. if the Locked attribute is set), or if the field is row-locked, or if the mapper is row-locked and the field's IgnoreRowLock behaviour is not set. Note that the IgnoreRowLock behaviour applies only to mapper-level row locking and has no impact on field-level row locking. For row-specific delete control, DeleteLocked.
	Table	The underlying table in which this field's data is stored. By default this is the owner mapper's View unless the field's Table property overrides that. In addition, there are two "special" tables, "+" and "-". The "+" and "-" are used to signify a field that has no table (e.g. is ExcludeFromSelect), or for which it is desirable to disassociate the field from its table (e.g. to prevent a dirty value from being saved to the database). The "+" table causes the field to be editable in the UI, assuming the field is not otherwise locked. The "-" table causes the field to be Locked in the UI.
	TextItems	The field's localized TextItem collection. For a particular instance of a field only the locale (language) for the current user is loaded. The text is loaded by Load.
	ToolTip	The localized tooltip for the field. Note the tooltip use is affected by the field's ToolTipOptions.
	Value	The current value of the field. Setting the Value will set the field's Dirty flag and cause the previous Value to be copied to the field's OldValue. The Value is the underlying value of the field as stored (or to be stored) in the database. In many cases this is the same as the DisplayText. However, in some cases (e.g. when a Picklist is specified) the Value may not be the DisplayText. Use the DisplayTextGet(DispTextFlags) and DisplayTextSet(String) methods to obtain and set the DisplayText. You can use the SetValue(Object, SetValFlags, Object) for lower-level control when setting the field Value.
	Visible	Indicates whether the field should be visible. The property evaluates to true if the ColWidth is set to 0 or the field is hidden due to permission reasons. You can set Visible programmatically if desired.

Top

Methods

	Name	Description
	BuildFilter	Build a filter based on the equality with the field's current rawValue.
	BuildFilter(String)	Build a filter based on the specified comparison operand and the field's current Value.
	BuildFilter(String, String)	Build a filter based on the specified comparison operand and the specified value.
	BuildFilter(String, String, FieldFilterFlags)	Build a filter based on the specified comparison operand, the specified value, and the specified FieldFilterFlags filter building options.
	BuildFilter(String, String, FieldFilterFlags, String)	Build a filter based on the specified comparison operand, the specified value, and the specified FieldFilterFlags filter building options, description provided.
	DisplayTextGet	Get the display text (vs. the underlying raw data in Value). The display text is generated by applying any picklist and formatting in order to convert the raw value into a string appropriate for presentation in the UI. Use DisplayTextSet(String) to set the field's raw value from a diplay text value. You can use ToDisplayText(Object, ValueConversionFlags) to convert raw value to its display text (with some limitations).
	DisplayTextSet	Sets the field's value from a "pretty" string from the UI applying any picklist and formatting to parse out the underlying Value. You can use SetValue(Object, SetValFlags, Object) with the FromDispText combined with with other SetValFlags for additional control over if and how the value is set. Use DisplayTextGet(DispTextFlags) to get the field's diplay text value. You can use ToValue(String, ValueConversionFlags) to convert a display text value to its raw value (with some limitations) without setting the field value or otherwise affecting the field.
	Exec(FieldExecCmds, Enum, Object)	The Exec method provide extended functionality for fields. See FieldExecCmds for the enumerated list of commands.
	Exec(FieldExecCmds, Int32, Object)	The Exec method provide extended functionality for fields. See FieldExecCmds for the enumerated list of commands.
	GetValue	Retrieve the value from the field applying any specified transformations. If no transformation is required use Value.
	HasPermission	Determines if the field has the specified ObjectPermissions for the current user. If the object has no assigned permisions, the return value is true.
	Init	Initializes the control bound to the field.
	IsAttrSet	Determines if a particular attribute (or any of a set of attributes) is set. Note that this is a shorthand for the expression (0 != (field.Attributes & attributes)) (C#) or (0 <> (field.Attributes Or attributes)) (VB).
	Permissions	Get the ObjectPermissions for the field.
	RemovePermissions	Remove the specified ObjectPermissions from the field.
	SetValue	Set the value of the field. Typically you simply set the field's value by assigning to Value, but you can use this method if finer control is required. For example, in order to set the field's value, but not cause it to be marked Dirty as a result you would call: field.SetValue("the new value", SetValFlags.DoNotMakeDirty, null). Unless this level of control is required it is recommended that Value be assigned directly.
	SQLValue	Generates a SQL clause with the field's current Value. This clause is appropriate for use in assigning a value to the field's underlying column and takes column data type into account including quoting strings and escaping for Unicode on SQL-Server if the underlying column is a wide column.
	Supports	Determines if the field is capable of supporting the specified FieldCapabilities. The type of the field's underlying column in the database and the field's meta-data are used to determine if the field can provide such support.
	ToDisplayText	Format the provided value as specified in the IAppContext, IField, and user preferences. This takes into account the IFieldNativeDbType, OleDbType, CellType, Format, etc. Note that the result will be formatted as it would be if the value were the field's Value and its display text were obtained via DisplayTextGet(DispTextFlags). This method is the inverse of ToValue(String, ValueConversionFlags).
	ToString	Override the generic ToString method to warn if the ToString is called directly on the Field object This is a warning against a fairly common mistake where a developer thinks they are accessing the field's value property by default, when in fact they are not. This type of problem is known to cause errors when setting parameters in SQL statements.
	ToValue	Parse the provided text as specified in the IAppContext, IField, and user preferences. This takes into account the IFieldNativeDbType, OleDbType, CellType, Format, etc. Note that the result will be parsed as it would be if the field's Value were being set via DisplayTextSet(String). This method is the inverse of ToDisplayText(Object, ValueConversionFlags). Note that this method does not set the field's Value. Note also that the method does not use the mapper's operational data from other fields and so, for example, discrim values will not be applied.

Top

Extension Methods

	Name	Description
	IsCellAttrSet	Determines if the specified CellTypeAttribute is set on the field. See CellTypeAttributes for the list of enumerations to use per CellTypes. A CellTypeAttribute is valid only for a particular CellTypes (since the bits are reused for other CellTypes), both the CellType and CellTypeAttributes are checked. (Defined by FieldInterfaceExtensions.)
	IsDirty	Gets whether or not the field is Dirty allowing for the IField object being null. (Defined by FieldInterfaceExtensions.)
	IsMissingRequiredValue	Gets whether or not a required field has a missing value (thus failing requiredness validation) allowing for the IField object being null. True if field is non-null, field's Required attribute is set and it's value is missing (generally this means null or an empty string). (Defined by FieldInterfaceExtensions.)
	IsRequired	Gets whether or not the field's Required attribute is set allowing for the IField object being null. (Defined by FieldInterfaceExtensions.)

Top

Remarks

Generally you will not instantiate IField-implementing objects directly, but will work with existing IField objects obtained from the field's IMapper.Fields collection. In the unusual case where you DO need to instantiate an IField object directly, the Field class is the standard implementation of a field. You may also implement your own IField object (though this is not really recommended) by deriving from FieldKernel which implements virtually all standard field functionality.

Remarks

Generally a field's Key is used for all naming purposes for the field. However, a number of properties are provided for overriding naming in different contexts:

AliasName - The name of the field in the SELECT statement.
ColumnName - The name of the field's underlying column in the database, when writing.
ControlName - The name of the control to which this field should bind.
PropertyName - The name to use for the property element in the generated TypedMapper.
RemotePropertyName - The name to use for the property element in the generated RemoteMapper.
SelectExpr - A SQL expression to use in the mapper's SELECT clause.

Remarks

In addition to class properties on IField objects, a large number of properties are maintained in the NetQuarry Studio and stored in each field's Properties collection. These properties also affect field behaviour and may be set/read programmatically from that collection. Some of the most important of these are:

AggregateType - The aggregate function to use when calculating mapper (datasheet) aggregate row values. If not specified, Sum is used for numeric fields and None for others.
CalculatedValue - Javascript expression that represents the value for this field. (May include field references.)
CssClass - The CssClass to use.
Discrim - The value or field reference to use as the Picklist discriminator.
FieldBehaviorAttributes - Miscellaneous FieldBehaviorOptions options affecting the behaviour of the field.
FieldExportAttrs - FieldExportAttrs attributes specifying how this field should be handled during export processing (e.g. to Excel).
FieldGroupingAttrs - FieldGroupingAttrs attributes specifying how mapper grouping should be performed on a specific field.
FieldImportAttrs - FieldImportAttrs attributes specifying how this field should be handled during import processing.
FieldSecurityAttributes - FieldSecurityAttrs field-level security options.
FilterOptions - FieldFilterOptions options specifying field filtering availability and behaviour.
GroupingSpec - Specifies how rows are to be grouped when grouping in the datasheet. See the Customize Datasheet Grouping wiki article for more information.
HideFlavor - The flavor(s) for which this field should be hidden.
LabelCssClass - The CSS class to use for the field's label.
LabelOptions - LabelOptions options controlling the presention of a field's label.
LinkBehaviorAttributes - LinkBehaviorAttributes options specifying field link behaviour.
ListOptions - FieldListOptions options affecting behaviour of field in list views.
LockFlavor - The flavor(s) for which this field should be locked (additive to other reasons for locking).
Max - Maximum allowed value for the field. (May include field references).
MaxLength - The maxiumn number of characters to accept into the field.
MaxLengthTruncate - If a is specified, the field's value should be truncated to that length automatically.
Min - Minimum allowed value for the field. (May include field references).
OnChange - Javascript placed on the control's onchange event. Note that the script will be resolved for field expressions and embedded functions if, and oly if, wrapped in a !fnResolve().
OnStartup - Javascript registered in the page's StartupScript. Supports field references including the [~.] notation to get a reference to the current field.
SelectExpr - A SQL expression to use in the mapper's SELECT clause. The results will be aliased to the normal field SELECT name using AS.
SourceField - Another field in the mapper from which to copy any non-null value on an insert. Typically used on a foreign key to identify the corresponding join value.
SummaryKey - The RowKey for the HoverSummary related item.
SummaryMOP - The Page to use for HoverSummary information.
Timezone - The timezone format. Leave blank to store as written, use 0,. to store GMT, display local.
ToolTipOptions - ToolTipOptions options specifying how the field's tooltip is to be presented.
ValidationRegEx - A regular expression used to validate the field value. The field will be considered valid if the expression matches.
ValidationScript - A custom javascript validation function for the field of the form func(fld, val, full, caption) returning an error message string if validation failed else a null or blank string.

See FieldProperties for a list of such properties as well as localized text items (indicated with the note This property supports localization) stored in the field's TextItems collection.

Reference

NetQuarry.Data Namespace