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.
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).
Thetype exposes the following members.
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.
Gets/sets certain field anomalies. This is primarily intended for internal use.
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.
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:
The name of the field's underlying column in the database. Typically this is the same as the Key.
The width, in approximate characters, to use for the field in datasheets and other dynamically generated UI mappers. When zero the field is hidden.
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.
Internal use only. Sets the index of this field in the DataTable used for binding.
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.
The default Value for the field to use when moving to a new record.
The localized description for the field.
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 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.
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.
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 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.
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.
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:
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).
The live IMapper object owning this field.
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.
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.
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.
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.
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.
The localized tooltip for the field. Note the tooltip use is affected by the field's ToolTipOptions.
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.
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.
Build a filter based on the equality with the field's current rawValue.
Build a filter based on the specified comparison operand and the field's current Value.
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.
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).
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.
Retrieve the value from the field applying any specified transformations. If no transformation is required use Value.
Determines if the field has the specified ObjectPermissions for the current user. If the object has no assigned permisions, the return value is true.
Initializes the control bound to the field.
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).
Get the ObjectPermissions for the field.
Remove the specified ObjectPermissions from the field.
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.
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.
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.
Format the provided value as specified in the IAppContext, , and user preferences. This takes into account the NativeDbType, 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).
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.
Parse the provided text as specified in the IAppContext, , and user preferences. This takes into account the NativeDbType, 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.
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.)
Gets whether or not the field is Dirty allowing for the object being null.(Defined by FieldInterfaceExtensions.)
Gets whether or not a required field has a missing value (thus failing requiredness validation) allowing for the Required attribute is set and it's value is missing (generally this means null or an empty string).(Defined by object being null. True if field is non-null, field's FieldInterfaceExtensions.)
Gets whether or not the field's Required attribute is set allowing for the object being null.(Defined by FieldInterfaceExtensions.)