Field Class

Constructor.

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 whether or not the F8 info page is allowed according to the application's DebugAttrs.NoF8 attribute.

Gets/sets certain field anomalies. This is primarily intended for internal use.

The field's application object. The application is obtained from the mapper if there is a mapper, else from the current application context.

Gets the DateTime value from the date-only IField associated with this field, if any, (via the TimePicker_DateField property). When using separate date-only and time-only controls, e.g. DatePicker and TimePicker fields, in conjunction with one another, the two fields must be associated in order to perform proper TimeZone conversion with regard to daylight savings time. This gets this field's DateTime value safely even if there is no such association (in which case DateTime.MinValue.Date is used). Note that GetAssociatedDate is now preferred because it return null when there is no such date.

Gets the IField associated with this field, if any, (via the TimePicker_DateField property). When using separate date-only and time-only controls, e.g. DatePicker and TimePicker fields, in conjunction with one another, the two fields must be associated in order to perform proper TimeZone conversion with regard to daylight savings time. Use AssociatedDate to get the field's DateTime value safely even if there is no such association (in which case DateTime.MinValue.Date is used).

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.

The WebControl bound to this field. The field may also have a LabelControl associated with it.

Gets the BrowserInfo object for the current request. Note: This object will be null in non-browser contexts.

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.

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.

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

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.

The data IDatabase used by the field. The data database holds the field's operational data. Meta-data is stored in the Repository.

The DBMSType of the field's data source. Normally this is the DBMSType of the DataDB, but if the mapper is using a live DataTable as its data source then DBMSType.DotNet will be returned.

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.

Gets whether or not filterering on the field should default to "contains" filtering instead of "starts with".

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.

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.

Gets the FieldBehaviorOptions for this field.

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.

Gets the LabelOptions for this field.

Gets the FilterOptions property for this field.

Get the field's FindPageInstanceValues (PIVs) property removing any optional field markers (surrounding angle brackets).

The field's flavor (obtained from its mapper if any, else zero).

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

Returns true if this field has a picklist.

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.

Gets whether or not this field is a big (64-bit) integer field.

Is this field button-like in behaviour?

Is this field data-driven (based primarly on CellType)?

Is the field on a mapper being used for filtering (vs. manipulating data)?

Is the field on a mapper being used for finding (vs. manipulating data)?

Gets whether or not the current browser is for a mobile or table device.

Is the host page a subform?

Gets whether or not this field has a timezone spec of the form "0,." meaning store the date in the database in UTC and display in the user's local timezone.

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.

The Label control bound to this field based on AssociatedControlID. The field may also have a BaseControl.

Indicates whether the field should be locked. The property evaluates to true if the column locked due to a number of reasons:

• The field's Locked attribute is set.
• The field is locked due to permission reasons.
• The field's table does not have a primary key defined.

You can set Locked programmatically if desired.

The live IMapper object owning this field.

Gets the unique name for the current mapper and field (currently in the format MapperKey.FieldKey).

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.

Determines if, when locked, this field should be displayed without a border.

The original value as loaded by the mapper. The OldValue is set automatically from Value when Value is set to a new value.

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.

Gets the PageElementInfo associated with this field's mapper.

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.

The ID of the Picklist associated with this field and available through the field's Picklist property.

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.

The repository IDatabase used by the field. The repository holds the field's meta-data. Operational data is stored in the Database.

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.

Gets the FieldSecurityAttrs for this field.

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 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.

The localized tooltip for the field. Note the tooltip use is affected by the field's ToolTipOptions.

Gets whether or not to render for a Boostrap-base application.

Gets whether or not to use a lightbox for inplace Find/MultiFind and similar popups.

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 column width is set to 0 or the field is hidden due to permissioning or other reasons. You can set Visible programmatically if desired. Programmatically setting the field visible will override all other visibility logic except permissioning.

Gets the field's watermark string, if any and if appropriate (e.g. not if filtering). Null is returned if watermark is not present, or not in use, or blank.

Get the field's aggregate query expression for use in an aggregate query SQL statement. The field's "AggregateType" property is used to ascertain any specific setting and if there is none, then the aggregate type is determined based on the field characteristics.

Bind the control to this field and set it up appropriately. Note that if the ControlBindingFlags.NoFieldBind is specified, the control is not bound, but it is set up as it would be if bound.

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.

Build a filter based on the specified comparison operand, the specified value, and the specified FieldFilterFlags filter building options.

Build a filter based on the specified comparison operand, the specified value, and the specified FieldFilterFlags filter building options, description provided.

Determine whether this field can be saved to an underlying column.

Create a WebControl for the field based on CellType, flags, and other settings.

Create a control for the field for use in filtering (vs. manipulating data).

Create a label control for the field.

Generate the currency locale spec expected by the currency formatting/deformatting functions in EAPUtils js.

Generate the currency locale spec expected by the currency formatting/deformatting functions in EAPUtils js.

Defines how DateTime values are formatted and displayed, depending on the DateCulture defined.

Generate the locale-neutral string for a date/time value (form is yyyy-MM-dd HH:mm:ss).

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.

Determines whether the specified Object is equal to the current Object.

The Exec method provide extended functionality for fields. See FieldExecCmds for the enumerated list of commands.

The Exec method provide extended functionality for fields. See FieldExecCmds for the enumerated list of commands.

Extracts a file from the database via the provided reader.

Extracts a file from the database. No data reader is provided, so one is created that points to the data needed to be saved to file

Devlog an entry using caller as source with mapper.field identified.

Devlog an entry using caller as source with mapper.field identified.

Delete the file associated with this FilePath cell-type field (per flags).

Fills a ListControl (DropDownList)

Fills a ListControl (DropDownList)

Builds a filter for this field as a GUID.

Generate a SQL filter clause for a field with a picklist. Note that if the filter is a NULL or NOT NULL filter, that is handled elsewhere and this method not called.

Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection.

Case-insensitive replacement for ListItemCollection.FindByValue().

Fire a field extension event for this field.

Format a value for use in a SQL filter clause.

Format the provide values as specified in flags.

Generate a SQL filter clause for this field based on the specified value, operand, and filter flags.

Get a SQL filter clause, and its corresponding natural language description, for this field based on the specified value, operand, and filter flags.

Get a natural language description for a filter built per the passed parameters. The parameters are identical to GenFilterClause();

Generate a SQL sort (ORDER BY) clause to use to sort on this field. The ORDER BY keywords are not included.

Get the date value associated with this time field, if any. If no such association exists via the field's DateField property or if the value of the DateField is null or blank, then null is returned. If a DateField is specified and it has a valid date/time value then the date portion of that date/time value is returned.

Get the specified localized text for this field. Obtaining the text is a cascading process from most specific to least specific always using the IDS as the id: 1) Look for the text item in the field's TextItems collection, 2) If not found, look for the item in the locale resource file, 3) If not found, use the provided defaultText.

Returns this field's CSS class(es) to use.

Get the value from the control bound to this field.

Get the value from the control bound to this field.

Get the currency culture for the current field.

Get the currency culture for the current field.

Get the currency culture for the current field.

Returns the TimeZone to be used for display purposes.

Get the specified localized text for the specified field. Obtaining the text is a three step process: 1) Look for the text item specified by name in the field's TextItems collection, 2) if not found, look for the item specified by ids in the locale resource file, 3) if not found, use the provided defaultText.

Get the javascript to use for file browsing for a FilePath cell.

Get the view link for a FilePath cell.

Get the view link for a FileUploader cell.

Get the navigation link for a Find cell.

Serves as a hash function for a particular type.

Get Navigation info for this field from cache, if cached, else generate it, cache it and return it.

Calculates and returns the link for this field.

Calculates and returns the link for this field.

Returns the TimeZone to be used for storage purposes.

Returns the TimeZone at the specified index. Use timezoneID -1 to get the user's current timezone and timezoneID -2 to get the server's current timezone. If requesting the user's current timezone and it is not known then the server's current timezone is returned instead. This behaviour matches that used to resolve !fnNow().

Returns the TimeZone at the specified index.

Returns the TimeZone at the specified index.

Gets the Type of the current instance.

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.

Determines if the specified date/time has a non-zero time component.

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).

Determines if the specified CellTypeAttribute is set. Since a CellTypeAttribute is valid only for a particular CellType (since the bits are reused for other CellTypes), we must check both the CellType and CellTypeAttributes.

Determine whether or not the field should be considered "checked" based on the provided value.

Determine if field is read-only.

Determine if field is read-only and get the WhyLocked text.

Determine if the specified word matches against a word in a keyword list.

Get the field's label text.

Get the field's label text.

Creates a shallow copy of the current Object.

Generate the number locale spec expected by the numeric formatting/deformatting functions in EAPUtils js per the current session number culture.

Get the ObjectPermissions for the field.

Get the picklist object, if any, for the field and cache it in _picklist.

Get a delimited list of item DisplayText from the field's picklist, if any.

Pre-process Find cell fields into a form easily handled in javascript. The FindField Find cell-type specific property is a semi-colon separated list of dst=src values (where dst=src can be abbreviated to src when src and dst are the same). The result is a string of semi-colon separated sets of dst=src FindFields where each destination name is converted from a IField.Key to its IField.ControlName (generally identical), each source name is the IField.Key, and abbreviated pairs are fully expanded.

Register DevLog information for logging if and only if the field's mapper's operational query fails.

Remove the specified ObjectPermissions from the field.

Resolve an expression optionally having embedded functions and/or field references.

Resolve an expression optionally having embedded functions and/or field references.

Set the value of the control specified control using this field's current value.

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.

Get the specified sibling field in the mapper.

Return the current field value formatted for use in a SQL clause.

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.

Determines whether the specified field supports vertical sizing.

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).

Override the generic ToString method to warn if the ToString is called directly on the Field object This is a warning agains a fairly common mistake where a developer thinks they are accessing the field's value property by default, when in fact they are not. I've seen this type of problem cause errors when setting parameters in SQL statements

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.

Convert a DisplayText value, that is a value as it would be displayed to the user, to a raw value of the appropriate type.

Convert a DisplayText value, that is a value as it would be displayed to the user, to a raw value of the appropriate type.

Convert a text string into a currency value using the appropriate culture.

Convert a raw value to a value of the expected type for this field.

Returns the value as a DateTime object using the specified TimeZone information.

Get the WindowOpenOptions as a hex string. Note that this method enforces certain application-wide features, in particular ForcePopupScrollbars which forces scrollbars on popup windows.

Specifies whether or not to render in RevealText mode to show developer the source of customizeable text.

Determines if the object value is equal to another object. If the two objects are null, then this returns true. There is special handling for guid comparisons (since a guid could be a string formatted in up to 3 different ways). If the special guid handling is not performed, then the object.Equals method is used.