Package com.smartgwt.client.data

# Class DataSourceField

java.lang.Object
com.smartgwt.client.core.JsObject
com.smartgwt.client.core.DataClass
com.smartgwt.client.core.RefDataClass
com.smartgwt.client.data.Field
com.smartgwt.client.data.DataSourceField

All Implemented Interfaces:
  `HasHandlers`

Direct Known Subclasses:
  `DataSourceBinaryField`, `DataSourceBooleanField`, `DataSourceDateField`, `DataSourceDateTimeField`, `DataSourceEnumField`, `DataSourceFloatField`, `DataSourceImageField`, `DataSourceImageFileField`, `DataSourceIntegerField`, `DataSourceIntEnumField`, `DataSourceLinkField`, `DataSourcePasswordField`, `DataSourceSequenceField`, `DataSourceSimpleTypeField`, `DataSourceTextField`, `DataSourceTimeField`

public class DataSourceField extends Field
Metadata about a DataSourceField, including its type and validators.

- ## Field Summary

  ### Fields inherited from class com.smartgwt.client.core.RefDataClass

  `id`

  ### Fields inherited from class com.smartgwt.client.core.DataClass

  `factoryCreated, factoryProperties`

  ### Fields inherited from class com.smartgwt.client.core.JsObject

  `jsObj`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DataSourceField()`
  `DataSourceField(JavaScriptObject jsObj)`
  `DataSourceField(String name, FieldType type)`
  `DataSourceField(String name, FieldType type, String title)`
  `DataSourceField(String name, FieldType type, String title, int length)`
  `DataSourceField(String name, FieldType type, String title, int length, boolean required)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Boolean`
  `getCalculated()`
  Boolean flag to indicate that a dataSource field has its values dynamically calculated rather than being populated in permanent storage.
  `Boolean`
  `getCanEdit()`
  Controls whether, by default, dataBoundComponents consider this field editable.
  `Boolean`
  `getCanExport()`
  Dictates whether the data in this field be exported.
  `Boolean`
  `getCanFilter()`
  Should the user be able to filter data by this field? Affects whether this field will show up in dataBoundComponents with UI for filtering data.
  `Boolean`
  `getCanSave()`
  Whether values in this field can be updated and saved to the dataSource.
  `boolean`
  `getCanSortClientOnly()`
  When true, this field can only be used for sorting if the data is entirely client-side.
  `Boolean`
  `getCanView()`
  If false, this property indicates that this field is considered "server only".
  `Boolean`
  `getChildrenProperty()`
  If true, this property indicates that this field will hold an explicit array of child nodes for the current node.
  `String`
  `getChildTagName()`
  For a field that is `multiple:true`, controls the name of the XML tag used for each subelement during `DataSource.xmlSerialize()`.
  `DateDisplayFormat`
  `getDateFormatter()`
  Preferred display format to use for date type values within this field.
  `Integer`
  `getDecimalPad()`
  Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.
  `Integer`
  `getDecimalPrecision()`
  Applies only to fields of type "float" and affects how many significant digits are shown.
  `Boolean`
  `getDeepCloneOnEdit()`
  Before we start editing this field in a DataBoundComponent, should we perform a deep clone of the underlying field value.
  `OperatorId`
  `getDefaultOperator()`
  The default search-operator for this field.
  `String`
  `getDescription()`
  An optional description of the DataSourceField's meaning.
  `boolean`
  `getDetail()`
  Whether this field should be considered a "detail" field by a `DataBoundComponent`.
  `String`
  `getDisplayField()`
  When records from this dataSource are displayed in a dataBoundComponent such as a `ListGrid`, the `displayField` attribute may be used to cause some field to display a value from another field in the record.
  `AdvancedCriteria`
  `getEditWhen()`
  Criteria-based editability control.
  `String`
  `getEmptyDisplayValue()`
  Text to be used for display by client-side components when this field has a null or undefined value.
  `Boolean`
  `getEscapeHTML()`
  When data values are displayed in DataBound components, by default strings will be interpreted as HTML by the browser in most cases.
  `Boolean`
  `getExcludeFromState()`
  If true, then this field is excluded from the bound component's view state.
  `boolean`
  `getExportForceText()`
  When using `DataSource.recordsAsText()`, determines what approach (if any) should be used to force values to be intepreted as text instead of heuristically parsed as dates, times or other structured types.
  `String`
  `getExportFormat()`
  An optional `FormatString` for this field, for use when `exporting` data to spreadsheet formats (XLS and OOXML/XLSX), XML, JSON or CSV.
  `String`
  `getExportTitle()`
  Optional different field-title used for exports.
  `FieldFilterMode`
  `getFilterOn()`
  This property limits where criteria for this field can be applied.
  `String`
  `getForeignDisplayField()`
  Name of another field in a separate dataSource that should be used as the display value for this field in the case where a `foreignKey` relationship exists.
  `String`
  `getForeignKey()`
  Declares that this field holds values that can be matched to values from another DataSource field, to create a relationship between records from different DataSources or even records within the same DataSource.
  `String`
  `getFormat()`
  Format string to use when rendering the value in any `DataBoundComponent` or when exporting via `DataSource.exportData()` or `ListGrid.exportData()` or `ListGrid.exportClientData()`.
  `String`
  `getFormula()`
  If `field.formula` is set, this field's value in records will be calculated dynamically.
  `String`
  `getGroup()`
  For use in `ComponentSchema`, indicates what group to place the property in when editing in Reify.
  `boolean`
  `getHidden()`
  Whether this field should be hidden from users by default within a DataBound component.
  `Boolean`
  `getIgnoreTextMatchStyle()`
  NOTE: Only applicable to `clientOnly` DataSources and the built-in `SQL`, `JPA` and `Hibernate` DataSources available in Pro, Power and Enterprise versions of Smart GWT.
  `Integer`
  `getImageHeight()`
  Height of the image-content of this field.
  `String`
  `getImageHeightAsString()`
  Height of the image-content of this field.
  `Integer`
  `getImageSize()`
  Width and height of the image-content of this field.
  `String`
  `getImageSizeAsString()`
  Width and height of the image-content of this field.
  `Integer`
  `getImageWidth()`
  Width of the image-content of this field.
  `String`
  `getImageWidthAsString()`
  Width of the image-content of this field.
  `Boolean`
  `getInapplicable()`
  For use in `ComponentSchema`, a field `inherited` from another schema can be redeclared with this property set in order to indicate that the property should not be used.
  `AdvancedCriteria`
  `getInitWhen()`
  Criteria-based control for field settability on add operations.
  `String`
  `getJoinPrefix()`
  Defines prefix before concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat".
  `String`
  `getJoinString()`
  Defines the delimiter between concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat".
  `String`
  `getJoinSuffix()`
  Defines suffix after concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat".
  `Integer`
  `getLength()`
  Maximum number of characters allowed.
  `Boolean`
  `getLenientXPath()`
  Deprecated.
  No longer needs to be set since the framework now defaults to suppressing errors for null values in the middle of Xpath, and only invalid XPath will cause warning be logged.
  `Boolean`
  `getMultiple()`
  Indicates that this field should always be Array-valued.
  `String`
  `getMultipleValueSeparator()`
  For fields that are `multiple:true`, the separator used between values when they are displayed.
  `String`
  `getName()`
  Name for this field.
  `Boolean`
  `getNillable()`
  Controls whether an explicit null-valued Record attribute for this field should result in `xsi:nil` being used to transmit the value when serializing to XML, like so:
  `static DataSourceField`
  `getOrCreateRef(JavaScriptObject jsObj)`
  `String`
  `getPluralTitle()`
  User-visible plural name for this field.
  `Integer`
  `getPrecision()`
  Applies only to fields of type "float" or "integer" and affects how many significant digits are shown.
  `boolean`
  `getPrimaryKey()`
  If set to `true`, indicates either that this field holds a value unique across all records in this data source, or that it is one of a number of fields marked as primary keys, and the combination of the values held in all of those fields is unique across all records in the data source.
  `String`
  `getPrompt()`
  Causes a tooltip hover to appear on the header generated for this field (effectively sets `prompt` for the header).
  `Boolean`
  `getPropertiesOnly()`
  For use in `ComponentSchema` for fields that contain other components, this flag suppresses auto-construction for subcomponents that appear under this field.
  `AdvancedCriteria`
  `getReadOnlyWhen()`
  Criteria-based version of `canEdit:false`.
  `Boolean`
  `getRecreateOnChange()`
  For use in `ComponentSchema` for fields that, when changed in `Reify`, should discard the current live component and recreate it with the current configured properties.
  `boolean`
  `getRequired()`
  Indicates this field must be non-null in order for a record to pass validation.
  `String`
  `getRequiredMessage()`
  The required message when a field that has been marked as `required` is not filled in by the user.
  `AdvancedCriteria`
  `getRequiredWhen()`
  Criteria to be evaluated to determine whether this field is `required`.
  `Object`
  `getRootValue()`
  For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
  `String`
  `getSequenceName()`
  For a DataSource with `serverType:"sql"` with a field of type "sequence", the name of the SQL sequence that should be used when inserting new records into this table.
  `Boolean`
  `getShowFileInline()`
  For a field of type:"imageFile", indicates whether to stream the image and display it inline or to display the View and Download icons.
  `String`
  `getSortByField()`
  Causes values for this field to be sorted according to values for another field, for both client- and server-side sorting.
  `Boolean`
  `getStringInBrowser()`
  Server-side setting that causes values for fields of type "integer" or "float" to be represented as Strings when delivered to a web browser, in order to avoid mangling values which cannot be represented faithfully in JavaScript.
  `SummaryFunctionType`
  `getSummaryFunction()`
  If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an explicit `SummaryFunction` for calculating the summary value to display.
  `String`
  `getSummaryValueTitle()`
  Title to show in a `Summary of type "title"` for this field.
  `String`
  `getTarget()`
  For fields of `type` "link", specifies the target window for the link.
  `String`
  `getTemplate()`
  If `field.template` is set, this field's value in records will be calculated dynamically via the specified `template`.
  `TimeDisplayFormat`
  `getTimeFormatter()`
  Preferred time-format to apply to date type values within this field.
  `String`
  `getTitle()`
  Default user-visible title for this field.
  `FieldType`
  `getType()`
  Type of this field.
  `DataSource`
  `getTypeAsDataSource()`
  Return the type of the assigned DataSource
  `SimpleType`
  `getTypeAsSimpleType()`
  Returns the type of this field as a SimpleType.
  `String`
  `getTypeDiscriminator()`
  For use in `ComponentSchema`, names another field on the same schema whose current value determines the effective type/schema of this field.
  `AdvancedCriteria`
  `getUpdateWhen()`
  Criteria-based control for field settability on update operations.
  `String`
  `getUploadFieldName()`
  Used by the `BatchUploader` to map a field in an upload file to this dataSourceField.
  `Boolean`
  `getUseLocalDisplayFieldValue()`
  The `FormItem.useLocalDisplayFieldValue` attribute may be specified within a dataSource configuration.
  `Boolean`
  `getValidationCheckClientCaches()`
  Per-field control for client-side cache lookup when evaluating ServerDynamicCriteria references (relational and aggregation).
  `Validator[]`
  `getValidators()`
  Validators to be applied to this field.
  `OperatorId[]`
  `getValidOperators()`
  Set of search-operators valid for this field.
  `Map`
  `getValueMap()`
  A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.
  `String`
  `getValueOperation()`
  Note: Currently, this feature only works with `SQL DataSources`
  `String`
  `getValueXPath()`
  XPath expression used to retrieve the field's value.
  `AdvancedCriteria`
  `getVisibleWhen()`
  Criteria-based field visibility for server responses.
  `Boolean`
  `getXmlAttribute()`
  Indicates that `DataSource.xmlSerialize()` should serialize this value as an XML attribute.
  `DataSourceField`
  `setCalculated(Boolean calculated)`
  Boolean flag to indicate that a dataSource field has its values dynamically calculated rather than being populated in permanent storage.
  `DataSourceField`
  `setCanEdit(Boolean canEdit)`
  Controls whether, by default, dataBoundComponents consider this field editable.
  `DataSourceField`
  `setCanExport(Boolean canExport)`
  Dictates whether the data in this field be exported.
  `DataSourceField`
  `setCanFilter(Boolean canFilter)`
  Should the user be able to filter data by this field? Affects whether this field will show up in dataBoundComponents with UI for filtering data.
  `DataSourceField`
  `setCanSave(Boolean canSave)`
  Whether values in this field can be updated and saved to the dataSource.
  `DataSourceField`
  `setCanSortClientOnly(boolean canSortClientOnly)`
  When true, this field can only be used for sorting if the data is entirely client-side.
  `DataSourceField`
  `setCanView(Boolean canView)`
  If false, this property indicates that this field is considered "server only".
  `DataSourceField`
  `setChildrenProperty(Boolean childrenProperty)`
  If true, this property indicates that this field will hold an explicit array of child nodes for the current node.
  `DataSourceField`
  `setChildTagName(String childTagName)`
  For a field that is `multiple:true`, controls the name of the XML tag used for each subelement during `DataSource.xmlSerialize()`.
  `DataSourceField`
  `setDateFormatter(DateDisplayFormat dateFormatter)`
  Preferred display format to use for date type values within this field.
  `DataSourceField`
  `setDecimalPad(Integer decimalPad)`
  Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.
  `DataSourceField`
  `setDecimalPrecision(Integer decimalPrecision)`
  Applies only to fields of type "float" and affects how many significant digits are shown.
  `DataSourceField`
  `setDeepCloneOnEdit(Boolean deepCloneOnEdit)`
  Before we start editing this field in a DataBoundComponent, should we perform a deep clone of the underlying field value.
  `DataSourceField`
  `setDefaultOperator(OperatorId defaultOperator)`
  The default search-operator for this field.
  `DataSourceField`
  `setDescription(String description)`
  An optional description of the DataSourceField's meaning.
  `DataSourceField`
  `setDetail(boolean detail)`
  Whether this field should be considered a "detail" field by a `DataBoundComponent`.
  `DataSourceField`
  `setDisplayField(String displayField)`
  When records from this dataSource are displayed in a dataBoundComponent such as a `ListGrid`, the `displayField` attribute may be used to cause some field to display a value from another field in the record.
  `void`
  `setEditorProperties(FormItem editorProperties)`
  Set the default `FormItem` properties to be used whenever this field is edited (whether in a grid, form, or other component).
  `void`
  `setEditorType(FormItem editorType)`
  Deprecated.
  Renamed to `setEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`.
  `void`
  `setEditorType(Class<? extends FormItem> editorType)`
  Set the default `FormItem` class to be used whenever this field is edited (whether in a grid, form, or other component).
  `void`
  `setEditorType(String editorType)`
  Set the default `FormItem` class to be used whenever this field is edited (whether in a grid, form, or other component).
  `DataSourceField`
  `setEditWhen(AdvancedCriteria editWhen)`
  Criteria-based editability control.
  `DataSourceField`
  `setEmptyDisplayValue(String emptyDisplayValue)`
  Text to be used for display by client-side components when this field has a null or undefined value.
  `DataSourceField`
  `setEscapeHTML(Boolean escapeHTML)`
  When data values are displayed in DataBound components, by default strings will be interpreted as HTML by the browser in most cases.
  `DataSourceField`
  `setExcludeFromState(Boolean excludeFromState)`
  If true, then this field is excluded from the bound component's view state.
  `DataSourceField`
  `setExportForceText(boolean exportForceText)`
  When using `DataSource.recordsAsText()`, determines what approach (if any) should be used to force values to be intepreted as text instead of heuristically parsed as dates, times or other structured types.
  `DataSourceField`
  `setExportFormat(String exportFormat)`
  An optional `FormatString` for this field, for use when `exporting` data to spreadsheet formats (XLS and OOXML/XLSX), XML, JSON or CSV.
  `DataSourceField`
  `setExportTitle(String exportTitle)`
  Optional different field-title used for exports.
  `void`
  `setFieldValueExtractor(FieldValueExtractor extractor)`
  Function to retrieve the field's value from the XML element or JSON record returned from a web service.
  `void`
  `setFilterEditorProperties(FormItem filterEditorProperties)`
  Set the default `FormItem` properties to be used whenever this field if it appears in a `ListGrid` filter row, and `canFilter` is not false.
  `void`
  `setFilterEditorType(Class<? extends FormItem> filterEditorType)`
  Set the default `FormItem` class to be used whenever this field appears in a `ListGrid` filter row or `SearchForm`.
  `void`
  `setFilterEditorType(String filterEditorType)`
  Set the default `FormItem` class to be used whenever this field appears in a `ListGrid` filter row or `SearchForm`.
  `DataSourceField`
  `setFilterOn(FieldFilterMode filterOn)`
  This property limits where criteria for this field can be applied.
  `DataSourceField`
  `setForeignDisplayField(String foreignDisplayField)`
  Name of another field in a separate dataSource that should be used as the display value for this field in the case where a `foreignKey` relationship exists.
  `DataSourceField`
  `setForeignKey(String foreignKey)`
  Declares that this field holds values that can be matched to values from another DataSource field, to create a relationship between records from different DataSources or even records within the same DataSource.
  `DataSourceField`
  `setFormat(String format)`
  Format string to use when rendering the value in any `DataBoundComponent` or when exporting via `DataSource.exportData()` or `ListGrid.exportData()` or `ListGrid.exportClientData()`.
  `DataSourceField`
  `setFormula(String formula)`
  If `field.formula` is set, this field's value in records will be calculated dynamically.
  `DataSourceField`
  `setGroup(String group)`
  For use in `ComponentSchema`, indicates what group to place the property in when editing in Reify.
  `DataSourceField`
  `setHidden(boolean hidden)`
  Whether this field should be hidden from users by default within a DataBound component.
  `DataSourceField`
  `setIgnoreTextMatchStyle(Boolean ignoreTextMatchStyle)`
  NOTE: Only applicable to `clientOnly` DataSources and the built-in `SQL`, `JPA` and `Hibernate` DataSources available in Pro, Power and Enterprise versions of Smart GWT.
  `void`
  `setImageHeight(Integer imageHeight)`
  Height of the image-content of this field.
  `void`
  `setImageHeight(String imageHeight)`
  Height of the image-content of this field.
  `void`
  `setImageSize(Integer imageSize)`
  Width and height of the image-content of this field.
  `void`
  `setImageSize(String imageSize)`
  Width and height of the image-content of this field.
  `void`
  `setImageWidth(Integer imageWidth)`
  Width of the image-content of this field.
  `void`
  `setImageWidth(String imageWidth)`
  Width of the image-content of this field.
  `DataSourceField`
  `setInapplicable(Boolean inapplicable)`
  For use in `ComponentSchema`, a field `inherited` from another schema can be redeclared with this property set in order to indicate that the property should not be used.
  `DataSourceField`
  `setInitWhen(AdvancedCriteria initWhen)`
  Criteria-based control for field settability on add operations.
  `DataSourceField`
  `setJoinPrefix(String joinPrefix)`
  Defines prefix before concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat".
  `DataSourceField`
  `setJoinString(String joinString)`
  Defines the delimiter between concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat".
  `DataSourceField`
  `setJoinSuffix(String joinSuffix)`
  Defines suffix after concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat".
  `DataSourceField`
  `setLength(Integer length)`
  Maximum number of characters allowed.
  `DataSourceField`
  `setLenientXPath(Boolean lenientXPath)`
  Deprecated.
  No longer needs to be set since the framework now defaults to suppressing errors for null values in the middle of Xpath, and only invalid XPath will cause warning be logged.
  `DataSourceField`
  `setMultiple(Boolean multiple)`
  Indicates that this field should always be Array-valued.
  `DataSourceField`
  `setMultipleValueSeparator(String multipleValueSeparator)`
  For fields that are `multiple:true`, the separator used between values when they are displayed.
  `DataSourceField`
  `setName(String name)`
  Name for this field.
  `DataSourceField`
  `setNillable(Boolean nillable)`
  Controls whether an explicit null-valued Record attribute for this field should result in `xsi:nil` being used to transmit the value when serializing to XML, like so:
  `DataSourceField`
  `setPluralTitle(String pluralTitle)`
  User-visible plural name for this field.
  `DataSourceField`
  `setPrecision(Integer precision)`
  Applies only to fields of type "float" or "integer" and affects how many significant digits are shown.
  `DataSourceField`
  `setPrimaryKey(boolean primaryKey)`
  If set to `true`, indicates either that this field holds a value unique across all records in this data source, or that it is one of a number of fields marked as primary keys, and the combination of the values held in all of those fields is unique across all records in the data source.
  `void`
  `setPrompt(String prompt)`
  Causes a tooltip hover to appear on the header generated for this data source field (effectively sets `prompt` for the header).
  `DataSourceField`
  `setPropertiesOnly(Boolean propertiesOnly)`
  For use in `ComponentSchema` for fields that contain other components, this flag suppresses auto-construction for subcomponents that appear under this field.
  `void`
  `setReadOnlyEditorProperties(FormItem editorProperties)`
  Sets the default FormItem properties to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.
  `void`
  `setReadOnlyEditorType(FormItem editorType)`
  Deprecated.
  Renamed to `setReadOnlyEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`.
  `void`
  `setReadOnlyEditorType(Class<? extends FormItem> editorType)`
  Sets the default `FormItem` class to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.
  `void`
  `setReadOnlyEditorType(String editorType)`
  Sets the default FormItem class to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.
  `DataSourceField`
  `setReadOnlyWhen(AdvancedCriteria readOnlyWhen)`
  Criteria-based version of `canEdit:false`.
  `DataSourceField`
  `setRecreateOnChange(Boolean recreateOnChange)`
  For use in `ComponentSchema` for fields that, when changed in `Reify`, should discard the current live component and recreate it with the current configured properties.
  `DataSourceField`
  `setRequired(boolean required)`
  Indicates this field must be non-null in order for a record to pass validation.
  `DataSourceField`
  `setRequiredMessage(String requiredMessage)`
  The required message when a field that has been marked as `required` is not filled in by the user.
  `DataSourceField`
  `setRequiredWhen(AdvancedCriteria requiredWhen)`
  Criteria to be evaluated to determine whether this field is `required`.
  `void`
  `setRootValue(Float rootValue)`
  For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
  `void`
  `setRootValue(Integer rootValue)`
  For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
  `DataSourceField`
  `setRootValue(Object rootValue)`
  For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
  `void`
  `setRootValue(String rootValue)`
  For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
  `DataSourceField`
  `setSequenceName(String sequenceName)`
  For a DataSource with `serverType:"sql"` with a field of type "sequence", the name of the SQL sequence that should be used when inserting new records into this table.
  `DataSourceField`
  `setShowFileInline(Boolean showFileInline)`
  For a field of type:"imageFile", indicates whether to stream the image and display it inline or to display the View and Download icons.
  `DataSourceField`
  `setSortByField(String sortByField)`
  Causes values for this field to be sorted according to values for another field, for both client- and server-side sorting.
  `DataSourceField`
  `setStringInBrowser(Boolean stringInBrowser)`
  Server-side setting that causes values for fields of type "integer" or "float" to be represented as Strings when delivered to a web browser, in order to avoid mangling values which cannot be represented faithfully in JavaScript.
  `void`
  `setSummaryFunction(SummaryFunctionType summaryFunction)`
  If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an explicit `SummaryFunction` for calculating the summary value to display.
  `void`
  `setSummaryFunction(SummaryFunction summaryFunction)`
  If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an explicit `SummaryFunction` for calculating the summary value to display.
  `void`
  `setSummaryFunction(String summaryFunction)`
  If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an summary function registered via `com.smartgwt.client.data.SimpleType#registerSummaryFunction()` for calculating the summary value to display.
  `DataSourceField`
  `setSummaryValueTitle(String summaryValueTitle)`
  Title to show in a `Summary of type "title"` for this field.
  `DataSourceField`
  `setTarget(String target)`
  For fields of `type` "link", specifies the target window for the link.
  `DataSourceField`
  `setTemplate(String template)`
  If `field.template` is set, this field's value in records will be calculated dynamically via the specified `template`.
  `DataSourceField`
  `setTimeFormatter(TimeDisplayFormat timeFormatter)`
  Preferred time-format to apply to date type values within this field.
  `DataSourceField`
  `setTitle(String title)`
  Default user-visible title for this field.
  `void`
  `setType(DataSource dataSource)`
  Deprecated.
  use #setTypeAsDataSource
  `void`
  `setType(SimpleType type)`
  Set the type directly to a defined SimpleType.
  `DataSourceField`
  `setType(FieldType type)`
  Type of this field.
  `void`
  `setTypeAsDataSource(DataSource dataSource)`
  The type can also be the another DataSource, which allows you to model nested structures such as XML documents (in fact, XMLTools.loadXMLSchema() models XML schema in this way).
  `DataSourceField`
  `setTypeDiscriminator(String typeDiscriminator)`
  For use in `ComponentSchema`, names another field on the same schema whose current value determines the effective type/schema of this field.
  `DataSourceField`
  `setUpdateWhen(AdvancedCriteria updateWhen)`
  Criteria-based control for field settability on update operations.
  `DataSourceField`
  `setUploadFieldName(String uploadFieldName)`
  Used by the `BatchUploader` to map a field in an upload file to this dataSourceField.
  `DataSourceField`
  `setUseLocalDisplayFieldValue(Boolean useLocalDisplayFieldValue)`
  The `FormItem.useLocalDisplayFieldValue` attribute may be specified within a dataSource configuration.
  `DataSourceField`
  `setValidationCheckClientCaches(Boolean validationCheckClientCaches)`
  Per-field control for client-side cache lookup when evaluating ServerDynamicCriteria references (relational and aggregation).
  `DataSourceField`
  `setValidators(Validator... validators)`
  Validators to be applied to this field.
  `DataSourceField`
  `setValidOperators(OperatorId... validOperators)`
  Set of search-operators valid for this field.
  `DataSourceField`
  `setValueMap(String... valueMap)`
  A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.
  `DataSourceField`
  `setValueMap(Map valueMap)`
  A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.
  `DataSourceField`
  `setValueOperation(String valueOperation)`
  Note: Currently, this feature only works with `SQL DataSources`
  `DataSourceField`
  `setValueXPath(String valueXPath)`
  XPath expression used to retrieve the field's value.
  `DataSourceField`
  `setVisibleWhen(AdvancedCriteria visibleWhen)`
  Criteria-based field visibility for server responses.
  `DataSourceField`
  `setXmlAttribute(Boolean xmlAttribute)`
  Indicates that `DataSource.xmlSerialize()` should serialize this value as an XML attribute.

  ### Methods inherited from class com.smartgwt.client.data.Field

  `setRequired`

  ### Methods inherited from class com.smartgwt.client.core.RefDataClass

  `getRef, getRef, internalSetID`

  ### Methods inherited from class com.smartgwt.client.core.DataClass

  `applyFactoryProperties, doAddHandler, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsDoubleArray, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsJavaScriptObject, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsString, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated`

  ### Methods inherited from class com.smartgwt.client.core.JsObject

  `equals, getJsObj, hashCode, isCreated, setJavaScriptObject, setJsObj`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### DataSourceField

    public DataSourceField()

  - ### DataSourceField

    public DataSourceField(JavaScriptObject jsObj)

  - ### DataSourceField

    public DataSourceField(String name, FieldType type)

  - ### DataSourceField

    public DataSourceField(String name, FieldType type, String title)

  - ### DataSourceField

    public DataSourceField(String name, FieldType type, String title, int length)

  - ### DataSourceField

    public DataSourceField(String name, FieldType type, String title, int length, boolean required)

- ## Method Details

  - ### getOrCreateRef

    public static DataSourceField getOrCreateRef(JavaScriptObject jsObj)

  - ### setCalculated

    public DataSourceField setCalculated(Boolean calculated)
    Boolean flag to indicate that a dataSource field has its values dynamically calculated rather than being populated in permanent storage.

    If explicitly set, this property will be respected by `DataSource.isCalculated()`

    Note : This is an advanced setting

    Parameters:
      `calculated` - New calculated value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getCalculated

    public Boolean getCalculated()
    Boolean flag to indicate that a dataSource field has its values dynamically calculated rather than being populated in permanent storage.

    If explicitly set, this property will be respected by `DataSource.isCalculated()`

    Returns:
      Current calculated value. Default value is null

  - ### setCanExport

    public DataSourceField setCanExport(Boolean canExport)
    Dictates whether the data in this field be exported. Explicitly setting canExport to false overrides the setting on any component-fields, such as `ListGrid fields`.
    Overrides:
      `setCanExport` in class `Field`
    Parameters:
      `canExport` - New canExport value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getCanExport

    public Boolean getCanExport()
    Dictates whether the data in this field be exported. Explicitly setting canExport to false overrides the setting on any component-fields, such as `ListGrid fields`.
    Overrides:
      `getCanExport` in class `Field`
    Returns:
      Current canExport value. Default value is null

  - ### setCanFilter

    public DataSourceField setCanFilter(Boolean canFilter)
    Should the user be able to filter data by this field? Affects whether this field will show up in dataBoundComponents with UI for filtering data.

    Note that setting `canFilter:false` only affects UI and is not a security feature. Enforcing that filtering cannot be performed server side does not meaningfully increase security, since as long as a field can be viewed by an end user, they can effectively search the field themselves even if the UI doesn't offer a means to do so. If a field should be unable to be viewed entirely by some users, use `viewRequiresRole` and related settings.

    Rather than a security setting, `canFilter:false` is intended for situations where it would be redundant or nonsensical to be able to search on a field, or where searching isn't implemented for that field.

    Parameters:
      `canFilter` - New canFilter value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `SearchForm.setShowFilterFieldsOnly(java.lang.Boolean)`
      - `SearchForm.setCanEditFieldAttribute(java.lang.String)`

  - ### getCanFilter

    public Boolean getCanFilter()
    Should the user be able to filter data by this field? Affects whether this field will show up in dataBoundComponents with UI for filtering data.

    Note that setting `canFilter:false` only affects UI and is not a security feature. Enforcing that filtering cannot be performed server side does not meaningfully increase security, since as long as a field can be viewed by an end user, they can effectively search the field themselves even if the UI doesn't offer a means to do so. If a field should be unable to be viewed entirely by some users, use `viewRequiresRole` and related settings.

    Rather than a security setting, `canFilter:false` is intended for situations where it would be redundant or nonsensical to be able to search on a field, or where searching isn't implemented for that field.

    Returns:
      Current canFilter value. Default value is null
    See Also:
      - `SearchForm.getShowFilterFieldsOnly()`
      - `SearchForm.getCanEditFieldAttribute()`

  - ### setCanSave

    public DataSourceField setCanSave(Boolean canSave)
    Whether values in this field can be updated and saved to the dataSource.

    If set to `false`, this field will default to being non-editable in standard editing components (`DynamicForm`, editable `ListGrid`), but will be editable when displayed for filtering purposes only (in a `SearchForm` or `ListGrid\n filter editor`. If `canEdit` is explicitly specified it will take precedence over this client-side behavior, but the server will still enforce the no-save policy (described below).

    NOTE: If you are using Smart GWT Server and have specified `canSave: false` for a field in a DataSource definition (`.ds.xml` file), this is enforced on the server. This means that we will strip out any attempt to set the value of such a field before trying to process any update or add request, similar to what happens when a `field-level declarative security check` fails.

    Parameters:
      `canSave` - New canSave value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Binding`

  - ### getCanSave

    public Boolean getCanSave()
    Whether values in this field can be updated and saved to the dataSource.

    If set to `false`, this field will default to being non-editable in standard editing components (`DynamicForm`, editable `ListGrid`), but will be editable when displayed for filtering purposes only (in a `SearchForm` or `ListGrid\n filter editor`. If `canEdit` is explicitly specified it will take precedence over this client-side behavior, but the server will still enforce the no-save policy (described below).

    NOTE: If you are using Smart GWT Server and have specified `canSave: false` for a field in a DataSource definition (`.ds.xml` file), this is enforced on the server. This means that we will strip out any attempt to set the value of such a field before trying to process any update or add request, similar to what happens when a `field-level declarative security check` fails.

    Returns:
      Current canSave value. Default value is null
    See Also:
      - `Component Binding`

  - ### setCanSortClientOnly

    public DataSourceField setCanSortClientOnly(boolean canSortClientOnly)
    When true, this field can only be used for sorting if the data is entirely client-side.
    Parameters:
      `canSortClientOnly` - New canSortClientOnly value. Default value is false
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getCanSortClientOnly

    public boolean getCanSortClientOnly()
    When true, this field can only be used for sorting if the data is entirely client-side.
    Returns:
      Current canSortClientOnly value. Default value is false

  - ### setCanView

    public DataSourceField setCanView(Boolean canView)
    If false, this property indicates that this field is considered "server only". This means:
    - Components cannot bind to the field; even if you explicitly add a field with the same name to your `dataBoundComponent`, it will be dropped
    - If you are using Smart GWT Server, the client will never be sent a value for the field
    - If you are using Smart GWT Server, then similar to `canEdit`, no updates to the field are allowed from the client. If you explicitly add a value for the field to, eg, a record you are passing to `DataSource.updateData()`, the server will strip the value out of the record before processing the update request.
    `canView:false` is not the same thing as `hidden`. Use `canView:false` when you want to prevent the client from ever seeing a field's definition or values; use `hidden:true` if it is fine from a security perspective that a field's definition and values are sent to the browser, but the field should not by default appear in user interface elements (but could do in some cases, like a special screen for advanced users or administrators, for example).

    Note that this property must be set explicitly to false to have an effect; a null or undefined setting is treated the same as true.

    This property is used to implement field-level view security: failing a `viewRequiresAuthentication`, `viewRequiresRole` or `viewRequires` test is equivalent to setting `canView:false` on the field (and, indeed, from the client's perspective, the field has had `canView:false` set).

    Parameters:
      `canView` - New canView value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Binding`

  - ### getCanView

    public Boolean getCanView()
    If false, this property indicates that this field is considered "server only". This means:
    - Components cannot bind to the field; even if you explicitly add a field with the same name to your `dataBoundComponent`, it will be dropped
    - If you are using Smart GWT Server, the client will never be sent a value for the field
    - If you are using Smart GWT Server, then similar to `canEdit`, no updates to the field are allowed from the client. If you explicitly add a value for the field to, eg, a record you are passing to `DataSource.updateData()`, the server will strip the value out of the record before processing the update request.
    `canView:false` is not the same thing as `hidden`. Use `canView:false` when you want to prevent the client from ever seeing a field's definition or values; use `hidden:true` if it is fine from a security perspective that a field's definition and values are sent to the browser, but the field should not by default appear in user interface elements (but could do in some cases, like a special screen for advanced users or administrators, for example).

    Note that this property must be set explicitly to false to have an effect; a null or undefined setting is treated the same as true.

    This property is used to implement field-level view security: failing a `viewRequiresAuthentication`, `viewRequiresRole` or `viewRequires` test is equivalent to setting `canView:false` on the field (and, indeed, from the client's perspective, the field has had `canView:false` set).

    Returns:
      Current canView value. Default value is null
    See Also:
      - `Component Binding`

  - ### setChildrenProperty

    public DataSourceField setChildrenProperty(Boolean childrenProperty)
    If true, this property indicates that this field will hold an explicit array of child nodes for the current node. This has the same effect as specifying `DataSource.childrenField` to this field's name.
    Parameters:
      `childrenProperty` - New childrenProperty value. Default value is false
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `DataSource.setChildrenField(java.lang.String)`
      - `Relations`

  - ### getChildrenProperty

    public Boolean getChildrenProperty()
    If true, this property indicates that this field will hold an explicit array of child nodes for the current node. This has the same effect as specifying `DataSource.childrenField` to this field's name.
    Returns:
      Current childrenProperty value. Default value is false
    See Also:
      - `DataSource.getChildrenField()`
      - `Relations`

  - ### setChildTagName

    public DataSourceField setChildTagName(String childTagName)
    For a field that is `multiple:true`, controls the name of the XML tag used for each subelement during `DataSource.xmlSerialize()`.

    If unset, the default tag name is "value" for a field of simple type, and for a field of DataSource type, is the tagName or ID of the DataSource (as though `xmlSerialize()` were called on the child DataSource).

    Parameters:
      `childTagName` - New childTagName value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Schema`

  - ### getChildTagName

    public String getChildTagName()
    For a field that is `multiple:true`, controls the name of the XML tag used for each subelement during `DataSource.xmlSerialize()`.

    If unset, the default tag name is "value" for a field of simple type, and for a field of DataSource type, is the tagName or ID of the DataSource (as though `xmlSerialize()` were called on the child DataSource).

    Returns:
      Current childTagName value. Default value is null
    See Also:
      - `Component Schema`

  - ### setDateFormatter

    public DataSourceField setDateFormatter(DateDisplayFormat dateFormatter)
    Preferred display format to use for date type values within this field. If this property is set on a field displayed in a databound component such as a `DynamicForm` or `ListGrid` it will be respected (See `FormItem.dateFormatter` and `ListGridField.dateFormatter`).

    Note that this property is also honored when exporting directly to Excel spreadsheets (ie, when using XLS or XLSX/OOXML form, not CSV); "date" and "datetime" fields with this property set will deliver real dates and formatting information to Excel, rather than formatted strings or unformatted dates.

    Note : This is an advanced setting

    Parameters:
      `dateFormatter` - New dateFormatter value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Appearance overview and related methods`

  - ### getDateFormatter

    public DateDisplayFormat getDateFormatter()
    Preferred display format to use for date type values within this field. If this property is set on a field displayed in a databound component such as a `DynamicForm` or `ListGrid` it will be respected (See `FormItem.dateFormatter` and `ListGridField.dateFormatter`).

    Note that this property is also honored when exporting directly to Excel spreadsheets (ie, when using XLS or XLSX/OOXML form, not CSV); "date" and "datetime" fields with this property set will deliver real dates and formatting information to Excel, rather than formatted strings or unformatted dates.

    Returns:
      Current dateFormatter value. Default value is null
    See Also:
      - `Appearance overview and related methods`

  - ### setDecimalPad

    public DataSourceField setDecimalPad(Integer decimalPad)
    Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.

    For example, a field value of 343.1, 343.104 and 343.09872677 would all be shown as 343.10 if decimalPad is 2.

    The original unpadded value is always shown when the value is edited.

    Parameters:
      `decimalPad` - New decimalPad value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Appearance overview and related methods`

  - ### getDecimalPad

    public Integer getDecimalPad()
    Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.

    For example, a field value of 343.1, 343.104 and 343.09872677 would all be shown as 343.10 if decimalPad is 2.

    The original unpadded value is always shown when the value is edited.

    Returns:
      Current decimalPad value. Default value is null
    See Also:
      - `Appearance overview and related methods`

  - ### setDecimalPrecision

    public DataSourceField setDecimalPrecision(Integer decimalPrecision)
    Applies only to fields of type "float" and affects how many significant digits are shown.

    For example, with decimalPrecision 3, if the field value is 343.672677, 343.673 is shown.

    If the value is 125.2, 125.2 is shown - decimalPrecision will not cause extra zeros to be added. Use `decimalPad` for this.

    A number is always shown with its original precision when edited.

    Parameters:
      `decimalPrecision` - New decimalPrecision value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Appearance overview and related methods`

  - ### getDecimalPrecision

    public Integer getDecimalPrecision()
    Applies only to fields of type "float" and affects how many significant digits are shown.

    For example, with decimalPrecision 3, if the field value is 343.672677, 343.673 is shown.

    If the value is 125.2, 125.2 is shown - decimalPrecision will not cause extra zeros to be added. Use `decimalPad` for this.

    A number is always shown with its original precision when edited.

    Returns:
      Current decimalPrecision value. Default value is null
    See Also:
      - `Appearance overview and related methods`

  - ### setDeepCloneOnEdit

    public DataSourceField setDeepCloneOnEdit(Boolean deepCloneOnEdit)
    Before we start editing this field in a DataBoundComponent, should we perform a deep clone of the underlying field value. See `DataSource.deepCloneOnEdit` for details of what this means.

    If this value is not explicitly set, it defaults first to the value of `DataBoundComponent.deepCloneOnEdit`, then to the value of `DataSource.deepCloneOnEdit`.

    Like the other `deepCloneOnEdit` settings, this flag only has an effect if you are editing a values object that contains nested objects or arrays, using `dataPath`s.

    Note : This is an advanced setting

    Parameters:
      `deepCloneOnEdit` - New deepCloneOnEdit value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Canvas.setDataPath(java.lang.String)`
      - `FormItem.setDataPath(java.lang.String)`
      - `DataSource.setDeepCloneOnEdit(java.lang.Boolean)`

  - ### getDeepCloneOnEdit

    public Boolean getDeepCloneOnEdit()
    Before we start editing this field in a DataBoundComponent, should we perform a deep clone of the underlying field value. See `DataSource.deepCloneOnEdit` for details of what this means.

    If this value is not explicitly set, it defaults first to the value of `DataBoundComponent.deepCloneOnEdit`, then to the value of `DataSource.deepCloneOnEdit`.

    Like the other `deepCloneOnEdit` settings, this flag only has an effect if you are editing a values object that contains nested objects or arrays, using `dataPath`s.

    Returns:
      Current deepCloneOnEdit value. Default value is null
    See Also:
      - `Canvas.getDataPath()`
      - `FormItem.getDataPath()`
      - `DataSource.getDeepCloneOnEdit()`

  - ### setDefaultOperator

    public DataSourceField setDefaultOperator(OperatorId defaultOperator)
    The default search-operator for this field.

    If not specified, falls back to the default specified for the field's `data-type`.

    Parameters:
      `defaultOperator` - New defaultOperator value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Advanced Filtering`

  - ### getDefaultOperator

    public OperatorId getDefaultOperator()
    The default search-operator for this field.

    If not specified, falls back to the default specified for the field's `data-type`.

    Returns:
      Current defaultOperator value. Default value is null
    See Also:
      - `Advanced Filtering`

  - ### setDescription

    public DataSourceField setDescription(String description)
    An optional description of the DataSourceField's meaning. It is not automatically exposed on any component, but it is useful for developer documentation, and as such it is included on any `OpenAPI specification` generated by the framework. Markdown is a commonly-used syntax, but you may also embed HTML content. When embedding HTML in the description in a .ds.xml file (see `DataSourceDeclaration`), it is recommended to wrap the HTML in a CDATA tag.

    This description is also provided to AI when AI is asked to work with the field. Best practices for the description are:

    - Start with a plain language explanation of what the field represents in the real world, its business concept or core purpose. For example: `order_subtotal` might be "Total price of the customer's order before tax and shipping."
    - If the field involves time, clarify what moment in time the value applies to, and how the value relates to other timestamps in the record. For example: `updated_timestamp` might be "The last time when any value of the record was updated. Always greater or equal to 'created_timestamp'."
    - If a numeric field, clearly identify the units if there are any.
    - When not `required` (i.e. the value may be `NULL`), describe the interpretation of a `NULL` value. Does the absence of a value have a specific meaning, or does it mean that the data is not available, unknown, or pending?
    - If values are constrained within a certain range or domain, identify the bounds or possible values.
    - If values take a certain format, identify this format and fully describe each part.
    - Include descriptions of how the field relates to or depends on others.
    - Give a brief note about how the field is populated. This might include the source of the data, formula(s) used to calculate the value, and the frequency and timing of updates.

    Sample values in the description may be appropriate, but a better practice is to provide `sampleData` on the data source, which show AI sample values in the context of complete record(s) from the data source.

    Parameters:
      `description` - New description value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `DataSource.setDescription(java.lang.String)`

  - ### getDescription

    public String getDescription()
    An optional description of the DataSourceField's meaning. It is not automatically exposed on any component, but it is useful for developer documentation, and as such it is included on any `OpenAPI specification` generated by the framework. Markdown is a commonly-used syntax, but you may also embed HTML content. When embedding HTML in the description in a .ds.xml file (see `DataSourceDeclaration`), it is recommended to wrap the HTML in a CDATA tag.

    This description is also provided to AI when AI is asked to work with the field. Best practices for the description are:

    - Start with a plain language explanation of what the field represents in the real world, its business concept or core purpose. For example: `order_subtotal` might be "Total price of the customer's order before tax and shipping."
    - If the field involves time, clarify what moment in time the value applies to, and how the value relates to other timestamps in the record. For example: `updated_timestamp` might be "The last time when any value of the record was updated. Always greater or equal to 'created_timestamp'."
    - If a numeric field, clearly identify the units if there are any.
    - When not `required` (i.e. the value may be `NULL`), describe the interpretation of a `NULL` value. Does the absence of a value have a specific meaning, or does it mean that the data is not available, unknown, or pending?
    - If values are constrained within a certain range or domain, identify the bounds or possible values.
    - If values take a certain format, identify this format and fully describe each part.
    - Include descriptions of how the field relates to or depends on others.
    - Give a brief note about how the field is populated. This might include the source of the data, formula(s) used to calculate the value, and the frequency and timing of updates.

    Sample values in the description may be appropriate, but a better practice is to provide `sampleData` on the data source, which show AI sample values in the context of complete record(s) from the data source.

    Returns:
      Current description value. Default value is null
    See Also:
      - `DataSource.getDescription()`

  - ### setDetail

    public DataSourceField setDetail(boolean detail)
    Whether this field should be considered a "detail" field by a `DataBoundComponent`.

    Detail fields won't be shown by default in a DataBoundComponent where `DataBoundComponent.showDetailFields` is false. This allows for some DataBound components, like a `ListGrid`, to show a summary view of records which displays only the most commonly viewed fields by default, while other DataBoundComponents, like a `DetailViewer`, show all fields by default.

    In addition, the `formItem.showIf` property is supported in multiple components for conditional visibility - see for example `ListGridField.showIf()` and `FormItem.showIf()`).

    Parameters:
      `detail` - New detail value. Default value is false
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Binding`

  - ### getDetail

    public boolean getDetail()
    Whether this field should be considered a "detail" field by a `DataBoundComponent`.

    Detail fields won't be shown by default in a DataBoundComponent where `DataBoundComponent.showDetailFields` is false. This allows for some DataBound components, like a `ListGrid`, to show a summary view of records which displays only the most commonly viewed fields by default, while other DataBoundComponents, like a `DetailViewer`, show all fields by default.

    In addition, the `formItem.showIf` property is supported in multiple components for conditional visibility - see for example `ListGridField.showIf()` and `FormItem.showIf()`).

    Returns:
      Current detail value. Default value is false
    See Also:
      - `Component Binding`

  - ### setDisplayField

    public DataSourceField setDisplayField(String displayField)
    When records from this dataSource are displayed in a dataBoundComponent such as a `ListGrid`, the `displayField` attribute may be used to cause some field to display a value from another field in the record.

    This is typically used for editable `foreignKey` fields. In this scenario, a dataSource field has a foreignKey field which stores an ID value used to identify records in another, related dataSource. Rather than display this ID to users, developers may wish to display another, user-friendly field from the related record. This is easy to achieve by having a second field on the dataSource which will be populated with the "display value" from this related dataSource, and using `dataSourceField.displayField` to show this value. The `includeFrom` feature handles populating this field automatically for dataSources backed by the `Smart GWT Server`. See the "Editing included fields" section of the `includeFrom` documentation for more on editing included foreignKey fields.

    Editable dataSourceFields with a specified `displayField` and `foreignKey` will typically be edited using a `SelectItem` or `ComboBoxItem`. In this case, in addition to identifying the field to use as a static display value within the record being edited, `displayField` will also identify which field on the related dataSource to use as a display field when showing a set of options to the user. This behavior may be modified in a couple of ways:

    - The `foreignDisplayField` attribute may be used to handle the case where the name of the field used as a displayField within the dataSource is different from the name of the included/equivalent field in the related dataSource.
    - The `useLocalDisplayFieldValue` attribute may be explicitly set to false to avoid picking up a display value from the local record altogether. Instead the displayField will be used only to derive the display value from a related record from the optionDataSource
    For more on how FormItems use the displayField property, see `FormItem.displayField`.
    Parameters:
      `displayField` - New displayField value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Relations`

  - ### getDisplayField

    public String getDisplayField()
    When records from this dataSource are displayed in a dataBoundComponent such as a `ListGrid`, the `displayField` attribute may be used to cause some field to display a value from another field in the record.

    This is typically used for editable `foreignKey` fields. In this scenario, a dataSource field has a foreignKey field which stores an ID value used to identify records in another, related dataSource. Rather than display this ID to users, developers may wish to display another, user-friendly field from the related record. This is easy to achieve by having a second field on the dataSource which will be populated with the "display value" from this related dataSource, and using `dataSourceField.displayField` to show this value. The `includeFrom` feature handles populating this field automatically for dataSources backed by the `Smart GWT Server`. See the "Editing included fields" section of the `includeFrom` documentation for more on editing included foreignKey fields.

    Editable dataSourceFields with a specified `displayField` and `foreignKey` will typically be edited using a `SelectItem` or `ComboBoxItem`. In this case, in addition to identifying the field to use as a static display value within the record being edited, `displayField` will also identify which field on the related dataSource to use as a display field when showing a set of options to the user. This behavior may be modified in a couple of ways:

    - The `foreignDisplayField` attribute may be used to handle the case where the name of the field used as a displayField within the dataSource is different from the name of the included/equivalent field in the related dataSource.
    - The `useLocalDisplayFieldValue` attribute may be explicitly set to false to avoid picking up a display value from the local record altogether. Instead the displayField will be used only to derive the display value from a related record from the optionDataSource
    For more on how FormItems use the displayField property, see `FormItem.displayField`.
    Returns:
      Current displayField value. Default value is null
    See Also:
      - `Relations`

  - ### setEditWhen

    public DataSourceField setEditWhen(AdvancedCriteria editWhen)
    Criteria-based editability control. The field is editable when criteria match, read-only otherwise. Inverse of `readOnlyWhen`.

    On the server, if the criteria do NOT match, the field value is stripped from add/update operations.

    Parameters:
      `editWhen` - New editWhen value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setReadOnlyWhen(com.smartgwt.client.data.AdvancedCriteria)`
      - `Component Binding`

  - ### getEditWhen

    public AdvancedCriteria getEditWhen()
    Criteria-based editability control. The field is editable when criteria match, read-only otherwise. Inverse of `readOnlyWhen`.

    On the server, if the criteria do NOT match, the field value is stripped from add/update operations.

    Returns:
      Current editWhen value. Default value is null
    See Also:
      - `getReadOnlyWhen()`
      - `Component Binding`

  - ### setEmptyDisplayValue

    public DataSourceField setEmptyDisplayValue(String emptyDisplayValue)
    Text to be used for display by client-side components when this field has a null or undefined value. This value will be overridden by a component's emptyCellValue, if set.
    Parameters:
      `emptyDisplayValue` - New emptyDisplayValue value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `FormItem.setEmptyDisplayValue(java.lang.String)`
      - `ListGridField.setEmptyCellValue(java.lang.String)`
      - `DetailViewerField.setEmptyCellValue(java.lang.String)`
      - `HTMLString`
      - `Appearance overview and related methods`

  - ### getEmptyDisplayValue

    public String getEmptyDisplayValue()
    Text to be used for display by client-side components when this field has a null or undefined value. This value will be overridden by a component's emptyCellValue, if set.
    Returns:
      Current emptyDisplayValue value. Default value is null
    See Also:
      - `FormItem.getEmptyDisplayValue()`
      - `ListGridField.getEmptyCellValue()`
      - `DetailViewerField.getEmptyCellValue()`
      - `HTMLString`
      - `Appearance overview and related methods`

  - ### setEscapeHTML

    public DataSourceField setEscapeHTML(Boolean escapeHTML)
    When data values are displayed in DataBound components, by default strings will be interpreted as HTML by the browser in most cases.

    If set, this property will be picked up by components bound to this dataSource, notifying them that any HTML characters should be escaped when displaying values for this field.

    Overrides:
      `setEscapeHTML` in class `Field`
    Parameters:
      `escapeHTML` - New escapeHTML value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `ListGridField.setEscapeHTML(java.lang.Boolean)`

  - ### getEscapeHTML

    public Boolean getEscapeHTML()
    When data values are displayed in DataBound components, by default strings will be interpreted as HTML by the browser in most cases.

    If set, this property will be picked up by components bound to this dataSource, notifying them that any HTML characters should be escaped when displaying values for this field.

    Overrides:
      `getEscapeHTML` in class `Field`
    Returns:
      Current escapeHTML value. Default value is null
    See Also:
      - `ListGridField.getEscapeHTML()`

  - ### setExcludeFromState

    public DataSourceField setExcludeFromState(Boolean excludeFromState)
    If true, then this field is excluded from the bound component's view state. In addition, the field will not be selected as the default title field by `DataBoundComponent.getTitleField()` if `DataBoundComponent.titleField` is not provided.
    Parameters:
      `excludeFromState` - New excludeFromState value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getExcludeFromState

    public Boolean getExcludeFromState()
    If true, then this field is excluded from the bound component's view state. In addition, the field will not be selected as the default title field by `DataBoundComponent.getTitleField()` if `DataBoundComponent.titleField` is not provided.
    Returns:
      Current excludeFromState value. Default value is null

  - ### setExportForceText

    public DataSourceField setExportForceText(boolean exportForceText)
    When using `DataSource.recordsAsText()`, determines what approach (if any) should be used to force values to be intepreted as text instead of heuristically parsed as dates, times or other structured types.
    Parameters:
      `exportForceText` - New exportForceText value. Default value is false
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `TextExportSettings.setForceText(com.smartgwt.client.types.ForceTextApproach)`

  - ### getExportForceText

    public boolean getExportForceText()
    When using `DataSource.recordsAsText()`, determines what approach (if any) should be used to force values to be intepreted as text instead of heuristically parsed as dates, times or other structured types.
    Returns:
      Current exportForceText value. Default value is false
    See Also:
      - `TextExportSettings.getForceText()`

  - ### setExportFormat

    public DataSourceField setExportFormat(String exportFormat)
    An optional `FormatString` for this field, for use when `exporting` data to spreadsheet formats (XLS and OOXML/XLSX), XML, JSON or CSV. You can use this property to override the normal `format` of this field, if any, specifically for exports, for both server-based and client-driven exports.

    Note, for server-driven exports you can specify default formats for date, time and datetime fields by specifying properties `export.format.default.date`, `export.format.default.time` and `export.format.default.datetime` in your `server.properties` file. Similarly, default formats for float and integer fields can be specified with `export.format.default.float` and `export.format.default.integer`, respectively. These formats will be used for fields that do not have a "format" or "exportFormat" property specified in the `.ds.xml` file.

    Specifically when exporting to spreadsheet formats, the `FormatString` is translated to the type of format string used by spreadsheet programs like Excel. A handful of features are not present in Excel format strings, and some features behave slightly differently. These differences are explained below.

    ### Excel cannot handle dates prior to January 1st 1900

    This is a well-known limitation of Excel dates; it is not a formatting issue as such.

    ### Currency symbols become fixed to the current locale at export time

    The placeholder currency symbol "&#x00A4" (¤) in a numeric format string is rendered as the localized currency symbol returned by GWT's built-in NumberFormat class. When exporting, the format string provided to Excel contains the currency symbol for the current locale of the Smart GWT application, and not a placeholder currency symbol that would make Excel pick up a currency symbol based on the operating system locale. We do this to ensure that the spreadsheet reflects the application's localization, rather than the localization of the current user's computer, because they may be different.

    ### Rounding differences

    The approach to rounding a positive number to a set number of decimal places is fairly universally agreed upon for non-specialized requirements: add 0.5 (or 0.05, or 0.005, or whatever) to the number and then truncate. This leads to the well understood convention that numbers exactly halfway between two possible rounding outcomes, go to the larger one. So 7.5 becomes 8 and 7.15 becomes 7.2.

    However, there is no such universal agreement when it come to rounding negative numbers. Some take the view that you should round by taking the number to the larger absolute value, so -7.15 becomes -7.2. Others feel that you should round by taking the number to the larger value in the sense of it being "less negative", so -7.15 becomes -7.1.

    Smart GWT formatting takes the first approach and rounds negative numbers away from zero. We do this simply because that is what Java DecimalFormat does. Unfortunately, Excel does the opposite. Therefore, you will see rounding differences on negative numbers on exact 50% boundaries: Smart GWT will format -7.15 as -7.2, while Excel will format the same value as -7.1.

    ### Different treatment of '#'

    Both Smart GWT and Excel use '#' to mean "digit, do not show zeroes". However, Excel does not implement this strictly in the integer part when the number it is formatting has a value of 0 in the integer part. So, with a format of "#.##", the value 0.25 is formatted as "0.25". Smart GWT (like Java DecimalFormat) is strict: with that format, 0.25 is formatted as ".25"; if you want to match Excel's output, you must use the format "0.##".

    ### Miscellaneous edge cases

    There is quite a lot of variation in behavior between Java DecimalFormat and Excel around the edges. For actual error cases - for example, a format string that just contains nonsense - it is normal and expected that the Smart GWT behavior and the Excel behavior do not match - this is just two systems producing different garbage out for the same garbage in, which is to be expected. For valid but weird usages - for example, a format with multiple percent signs - Smart GWT's formatting is in line with what DecimalFormat does, unless DecimalFormat throws an Exception, in which case we just do the thing that seems most sensible, or the thing that was easiest to implement.

    Known differences in behavior in edge cases include:

    - Smart GWT ignores formatting characters in the number part of the format string, whereas Excel rejects the format (this behavior may vary with different releases of Excel and supposedly compatible libraries: POI, for example, will accept such format strings). If you attempt to format 5.175 with the format string "#b0.#a#", Smart GWT will return "5.72", and Excel will reject the format
    - Smart GWT ignores quoted characters in the number part of the format string, whereas Excel preserves them. If you attempt to format 5.175 with the format string "#'b'0.#'a'#", Smart GWT will return "5.72", and Excel will return "b5.7a2"
    - If you specify the empty string as a format string, Smart GWT returns the result of calling toString() on the number; Excel uses the built-in "General" format. These two approaches will generally give the same or very similar results, but that is really a coincidence: the correct way to obtain matching results in the browser and the spreadsheet is to specify a valid format string
    - If you specify a format string that contains no number part (ie, no '#' or '0' characters), Smart GWT does what DecimalFormat does, which is to output the integer part of the number alongside the fixed part of the format. Excel just outputs the fixed part. So, if you attempt to format -5.3 with the format string "'Hello world'", Smart GWT will output "-Hello world5", whereas Excel will output just "Hello world"
    - If you specify multiple percent signs in the format, Smart GWT treats all but the first one as static text, so 0.5 formatted with "#%%%" is "50%%%" (ie, all the signs are preserved but there is only one multiplcation by 100). Excel multiplies for each percent sign, so 0.5 formatted with "#%%%" is "500000%%%"

    ### Date format functionality not supported by Excel

    The following date/time/datetime functionality is not supported by Excel; if you use formatters that use any of this functionality, your values will be exported to Excel incorrectly formatted. In cases like this, we recommend that you use a separate `exportFormat`, with the intent of exporting your values in a way that is similar to your application formatting (which would be specified with the `format` property), but within the confines of what Excel supports.
    - Fiscal year, week and day (LL, LLLL, C, CC, c, cc)
    - Week in year (w, ww)
    - Day in year (D, DD)
    - Day number in week (u)
    - Explicit control over whether to use 12- or 24-hour notation. In Excel, this is implied by the presence or absence of the AM/PM designator
    - If the user's operating system locale is different to the locale in use in the Smart GWT application, day and month names may be different in the spreadsheet

    ### Number format functionality not supported by Excel

    The only Smart GWT number-formatting functionality not supported for export to Excel is "multiply by 1000 and show as per mille".

    ### Limit on number of custom Excel formats

    Excel limits the number of custom format strings in a single spreadsheet to somewhere between 200 and 250, depending on your locale and language. Hitting this limit in an export would require hundreds of field definitions, each defining unique `FormatStrings`. If you do hit the limit, the only workaround is to use fewer unique `FormatStrings`.

    ### Controlling number format

    If we give Excel a formatted number like "500,000" it will not treat that value as a number, so sums and other basic spreadsheet features won't work. So we use the heuristic that if your formatted value parses as a number, you probably want it treated as a number in the spreadsheet, so we give Excel the unformatted numeric value and tell Excel it's a numeric data value.

    You might expect that we would give Excel both the formatted value and the numeric value, but this is only possible by creating what's called a "custom format" for that cell, which as the section above mentions, is limited in that only a few hundred can be created.

    With this Excel limitation in mind, it makes sense to just go with the default behavior. If you decide otherwise, one option is to use `exportNumbersAsFormattedString`, but see the docs for that property for the drawbacks of doing this.

    Parameters:
      `exportFormat` - New exportFormat value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setFormat(java.lang.String)`
      - `FormatString`

  - ### getExportFormat

    public String getExportFormat()
    An optional `FormatString` for this field, for use when `exporting` data to spreadsheet formats (XLS and OOXML/XLSX), XML, JSON or CSV. You can use this property to override the normal `format` of this field, if any, specifically for exports, for both server-based and client-driven exports.

    Note, for server-driven exports you can specify default formats for date, time and datetime fields by specifying properties `export.format.default.date`, `export.format.default.time` and `export.format.default.datetime` in your `server.properties` file. Similarly, default formats for float and integer fields can be specified with `export.format.default.float` and `export.format.default.integer`, respectively. These formats will be used for fields that do not have a "format" or "exportFormat" property specified in the `.ds.xml` file.

    Specifically when exporting to spreadsheet formats, the `FormatString` is translated to the type of format string used by spreadsheet programs like Excel. A handful of features are not present in Excel format strings, and some features behave slightly differently. These differences are explained below.

    ### Excel cannot handle dates prior to January 1st 1900

    This is a well-known limitation of Excel dates; it is not a formatting issue as such.

    ### Currency symbols become fixed to the current locale at export time

    The placeholder currency symbol "&#x00A4" (¤) in a numeric format string is rendered as the localized currency symbol returned by GWT's built-in NumberFormat class. When exporting, the format string provided to Excel contains the currency symbol for the current locale of the Smart GWT application, and not a placeholder currency symbol that would make Excel pick up a currency symbol based on the operating system locale. We do this to ensure that the spreadsheet reflects the application's localization, rather than the localization of the current user's computer, because they may be different.

    ### Rounding differences

    The approach to rounding a positive number to a set number of decimal places is fairly universally agreed upon for non-specialized requirements: add 0.5 (or 0.05, or 0.005, or whatever) to the number and then truncate. This leads to the well understood convention that numbers exactly halfway between two possible rounding outcomes, go to the larger one. So 7.5 becomes 8 and 7.15 becomes 7.2.

    However, there is no such universal agreement when it come to rounding negative numbers. Some take the view that you should round by taking the number to the larger absolute value, so -7.15 becomes -7.2. Others feel that you should round by taking the number to the larger value in the sense of it being "less negative", so -7.15 becomes -7.1.

    Smart GWT formatting takes the first approach and rounds negative numbers away from zero. We do this simply because that is what Java DecimalFormat does. Unfortunately, Excel does the opposite. Therefore, you will see rounding differences on negative numbers on exact 50% boundaries: Smart GWT will format -7.15 as -7.2, while Excel will format the same value as -7.1.

    ### Different treatment of '#'

    Both Smart GWT and Excel use '#' to mean "digit, do not show zeroes". However, Excel does not implement this strictly in the integer part when the number it is formatting has a value of 0 in the integer part. So, with a format of "#.##", the value 0.25 is formatted as "0.25". Smart GWT (like Java DecimalFormat) is strict: with that format, 0.25 is formatted as ".25"; if you want to match Excel's output, you must use the format "0.##".

    ### Miscellaneous edge cases

    There is quite a lot of variation in behavior between Java DecimalFormat and Excel around the edges. For actual error cases - for example, a format string that just contains nonsense - it is normal and expected that the Smart GWT behavior and the Excel behavior do not match - this is just two systems producing different garbage out for the same garbage in, which is to be expected. For valid but weird usages - for example, a format with multiple percent signs - Smart GWT's formatting is in line with what DecimalFormat does, unless DecimalFormat throws an Exception, in which case we just do the thing that seems most sensible, or the thing that was easiest to implement.

    Known differences in behavior in edge cases include:

    - Smart GWT ignores formatting characters in the number part of the format string, whereas Excel rejects the format (this behavior may vary with different releases of Excel and supposedly compatible libraries: POI, for example, will accept such format strings). If you attempt to format 5.175 with the format string "#b0.#a#", Smart GWT will return "5.72", and Excel will reject the format
    - Smart GWT ignores quoted characters in the number part of the format string, whereas Excel preserves them. If you attempt to format 5.175 with the format string "#'b'0.#'a'#", Smart GWT will return "5.72", and Excel will return "b5.7a2"
    - If you specify the empty string as a format string, Smart GWT returns the result of calling toString() on the number; Excel uses the built-in "General" format. These two approaches will generally give the same or very similar results, but that is really a coincidence: the correct way to obtain matching results in the browser and the spreadsheet is to specify a valid format string
    - If you specify a format string that contains no number part (ie, no '#' or '0' characters), Smart GWT does what DecimalFormat does, which is to output the integer part of the number alongside the fixed part of the format. Excel just outputs the fixed part. So, if you attempt to format -5.3 with the format string "'Hello world'", Smart GWT will output "-Hello world5", whereas Excel will output just "Hello world"
    - If you specify multiple percent signs in the format, Smart GWT treats all but the first one as static text, so 0.5 formatted with "#%%%" is "50%%%" (ie, all the signs are preserved but there is only one multiplcation by 100). Excel multiplies for each percent sign, so 0.5 formatted with "#%%%" is "500000%%%"

    ### Date format functionality not supported by Excel

    The following date/time/datetime functionality is not supported by Excel; if you use formatters that use any of this functionality, your values will be exported to Excel incorrectly formatted. In cases like this, we recommend that you use a separate `exportFormat`, with the intent of exporting your values in a way that is similar to your application formatting (which would be specified with the `format` property), but within the confines of what Excel supports.
    - Fiscal year, week and day (LL, LLLL, C, CC, c, cc)
    - Week in year (w, ww)
    - Day in year (D, DD)
    - Day number in week (u)
    - Explicit control over whether to use 12- or 24-hour notation. In Excel, this is implied by the presence or absence of the AM/PM designator
    - If the user's operating system locale is different to the locale in use in the Smart GWT application, day and month names may be different in the spreadsheet

    ### Number format functionality not supported by Excel

    The only Smart GWT number-formatting functionality not supported for export to Excel is "multiply by 1000 and show as per mille".

    ### Limit on number of custom Excel formats

    Excel limits the number of custom format strings in a single spreadsheet to somewhere between 200 and 250, depending on your locale and language. Hitting this limit in an export would require hundreds of field definitions, each defining unique `FormatStrings`. If you do hit the limit, the only workaround is to use fewer unique `FormatStrings`.

    ### Controlling number format

    If we give Excel a formatted number like "500,000" it will not treat that value as a number, so sums and other basic spreadsheet features won't work. So we use the heuristic that if your formatted value parses as a number, you probably want it treated as a number in the spreadsheet, so we give Excel the unformatted numeric value and tell Excel it's a numeric data value.

    You might expect that we would give Excel both the formatted value and the numeric value, but this is only possible by creating what's called a "custom format" for that cell, which as the section above mentions, is limited in that only a few hundred can be created.

    With this Excel limitation in mind, it makes sense to just go with the default behavior. If you decide otherwise, one option is to use `exportNumbersAsFormattedString`, but see the docs for that property for the drawbacks of doing this.

    Returns:
      Current exportFormat value. Default value is null
    See Also:
      - `getFormat()`
      - `FormatString`

  - ### setExportTitle

    public DataSourceField setExportTitle(String exportTitle)
    Optional different field-title used for exports.
    Overrides:
      `setExportTitle` in class `Field`
    Parameters:
      `exportTitle` - New exportTitle value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `HTMLString`

  - ### getExportTitle

    public String getExportTitle()
    Optional different field-title used for exports.
    Overrides:
      `getExportTitle` in class `Field`
    Returns:
      Current exportTitle value. Default value is null
    See Also:
      - `HTMLString`

  - ### setFilterOn

    public DataSourceField setFilterOn(FieldFilterMode filterOn)
    This property limits where criteria for this field can be applied. By default, criteria can be applied either at the server, or at the `client` where possible, to avoid server round-trips.

    When this property is set to `serverOnly`, any change to criteria for this field causes cache-invalidation and a trip to the server.

    Parameters:
      `filterOn` - New filterOn value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Advanced Filtering`

  - ### getFilterOn

    public FieldFilterMode getFilterOn()
    This property limits where criteria for this field can be applied. By default, criteria can be applied either at the server, or at the `client` where possible, to avoid server round-trips.

    When this property is set to `serverOnly`, any change to criteria for this field causes cache-invalidation and a trip to the server.

    Returns:
      Current filterOn value. Default value is null
    See Also:
      - `Advanced Filtering`

  - ### setForeignDisplayField

    public DataSourceField setForeignDisplayField(String foreignDisplayField)
    Name of another field in a separate dataSource that should be used as the display value for this field in the case where a `foreignKey` relationship exists. Derived automatically when using the displayField / includeFrom pattern as illustrated in the following example.

    For a general overview on picking up display values from a separate field, see `displayField` property.

    The `foreignDisplayField` property is useful for editable fields, where the name of the display field within the record being edited differs from the display field for related records in the option dataSource.
    For example consider a "countryDS" dataSource with the following fields:

           <field name="id"     type="sequence"   hidden="true"     primaryKey="true" />
           <field name="name"   type="text"       title="Country"   required="true" />

    ...and a "city" dataSource which uses a foreignKey relationship identify associated country records:

           <field name="id"        type="sequence" hidden="true"   primaryKey="true" />
           <field name="name"      type="text"     title="City"    required="true" />
           <field name="countryId" type="integer"  editorType="SelectItem"
                      foreignKey="countryDS.id"
                      displayField="countryName" foreignDisplayField="name" title="Country" />
           <field name="countryName" includeFrom="countryDS.name"  hidden="true"   />

    A DynamicForm bound to this "city" dataSource would display a SelectItem editor by default for the country field. The initial display value would be the local value from the "countryName" field, populated from the related countryDS automatically via the `includeFrom` feature.
    If the user showed the drop-down list of options for this field, the display values within that list would be picked up from the "name" field values for the related "countryDS" records. Again, note that the foreignDisplayField would have been derived in this case, and need not be specified explicitly.

    Note that when specified, `foreignDisplayField` is always expected to be set to the related dataSource field containing equivalent values to the `displayField` in the local dataSource. This is important as, when editing the field, foreignDisplayField values from the related dataSource will be displayed to the user, and when a value is selected the local record's `displayField` value will be updated to match the selected `foreignDisplayField` value from the related dataSource's record. This behavior is documented under `FormItem.displayField`.

    Parameters:
      `foreignDisplayField` - New foreignDisplayField value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Relations`

  - ### getForeignDisplayField

    public String getForeignDisplayField()
    Name of another field in a separate dataSource that should be used as the display value for this field in the case where a `foreignKey` relationship exists. Derived automatically when using the displayField / includeFrom pattern as illustrated in the following example.

    For a general overview on picking up display values from a separate field, see `displayField` property.

    The `foreignDisplayField` property is useful for editable fields, where the name of the display field within the record being edited differs from the display field for related records in the option dataSource.
    For example consider a "countryDS" dataSource with the following fields:

           <field name="id"     type="sequence"   hidden="true"     primaryKey="true" />
           <field name="name"   type="text"       title="Country"   required="true" />

    ...and a "city" dataSource which uses a foreignKey relationship identify associated country records:

           <field name="id"        type="sequence" hidden="true"   primaryKey="true" />
           <field name="name"      type="text"     title="City"    required="true" />
           <field name="countryId" type="integer"  editorType="SelectItem"
                      foreignKey="countryDS.id"
                      displayField="countryName" foreignDisplayField="name" title="Country" />
           <field name="countryName" includeFrom="countryDS.name"  hidden="true"   />

    A DynamicForm bound to this "city" dataSource would display a SelectItem editor by default for the country field. The initial display value would be the local value from the "countryName" field, populated from the related countryDS automatically via the `includeFrom` feature.
    If the user showed the drop-down list of options for this field, the display values within that list would be picked up from the "name" field values for the related "countryDS" records. Again, note that the foreignDisplayField would have been derived in this case, and need not be specified explicitly.

    Note that when specified, `foreignDisplayField` is always expected to be set to the related dataSource field containing equivalent values to the `displayField` in the local dataSource. This is important as, when editing the field, foreignDisplayField values from the related dataSource will be displayed to the user, and when a value is selected the local record's `displayField` value will be updated to match the selected `foreignDisplayField` value from the related dataSource's record. This behavior is documented under `FormItem.displayField`.

    Returns:
      Current foreignDisplayField value. Default value is null
    See Also:
      - `Relations`

  - ### setForeignKey

    public DataSourceField setForeignKey(String foreignKey)
    Declares that this field holds values that can be matched to values from another DataSource field, to create a relationship between records from different DataSources or even records within the same DataSource. Ordinarily, the relation to the other dataSource is a many-to-one relation, where multiple records on this dataSource refer to a single record on the other dataSource. To declare a one-to-many or many-to-many relation, specify `multiple`:true as well as `foreignKey`. See `the Relations overview` for more details

    The format of `foreignKey` is `dataSourceId.fieldName`.

    For a foreignKey within the same dataSource, you can omit the `dataSourceId` and just specify `fieldName`. For example, to create a tree relationship within a DataSource:

               DataSource supplyItem = new DataSource();
               DataSourceField itemId = new DataSourceField();
               itemId.setType(FieldType.SEQUENCE);
               itemId.setPrimaryKey(true);
               DataSourceField parentId = new DataSourceField();
               parentId.setType(FieldType.INTEGER);
               parentId.setForeignKey("itemId");
               supplyItem.setFields(itemId, parentId);

    `foreignKey` declarations also allow other automatic behaviors by `DataBoundComponents`, such as `ListGrid.fetchRelatedData()`.

    For SQLDataSources foreign keys can be automatically discovered from SQL tables if `autoDeriveSchema` is set.

    Parameters:
      `foreignKey` - New foreignKey value. Default value is false
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `DataSourceField.joinType`
      - `Relations`

  - ### getForeignKey

    public String getForeignKey()
    Declares that this field holds values that can be matched to values from another DataSource field, to create a relationship between records from different DataSources or even records within the same DataSource. Ordinarily, the relation to the other dataSource is a many-to-one relation, where multiple records on this dataSource refer to a single record on the other dataSource. To declare a one-to-many or many-to-many relation, specify `multiple`:true as well as `foreignKey`. See `the Relations overview` for more details

    The format of `foreignKey` is `dataSourceId.fieldName`.

    For a foreignKey within the same dataSource, you can omit the `dataSourceId` and just specify `fieldName`. For example, to create a tree relationship within a DataSource:

               DataSource supplyItem = new DataSource();
               DataSourceField itemId = new DataSourceField();
               itemId.setType(FieldType.SEQUENCE);
               itemId.setPrimaryKey(true);
               DataSourceField parentId = new DataSourceField();
               parentId.setType(FieldType.INTEGER);
               parentId.setForeignKey("itemId");
               supplyItem.setFields(itemId, parentId);

    `foreignKey` declarations also allow other automatic behaviors by `DataBoundComponents`, such as `ListGrid.fetchRelatedData()`.

    For SQLDataSources foreign keys can be automatically discovered from SQL tables if `autoDeriveSchema` is set.

    Returns:
      Current foreignKey value. Default value is false
    See Also:
      - `DataSourceField.joinType`
      - `Relations`

  - ### setFormat

    public DataSourceField setFormat(String format)
    Format string to use when rendering the value in any `DataBoundComponent` or when exporting via `DataSource.exportData()` or `ListGrid.exportData()` or `ListGrid.exportClientData()`.

    Supported for fields of type "date", "time", "datetime", "int", "float" or any derived `SimpleType`.

    To configure a different format for export, use `exportFormat`.

    This is a per-field setting; you can alternatively set a default format for all "date", "time" or "datetime" fields via `DateUtil.setNormalDatetimeDisplayFormat()` and related methods on `com.smartgwt.client.util.Date`. See also `LocalizedNumberFormatting` for built-in `FieldTypes` that handle localized currency formatting.

    Also note, this property takes precedence over any specified `dateFormatter`, but can be overridden on a per-component basis by providing a formatter directly on the component, for example, via `ListGrid.setCellFormatter()` or `FormItem.formatValue()`.

    Parameters:
      `format` - New format value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setExportFormat(java.lang.String)`
      - `FormatString`

  - ### getFormat

    public String getFormat()
    Format string to use when rendering the value in any `DataBoundComponent` or when exporting via `DataSource.exportData()` or `ListGrid.exportData()` or `ListGrid.exportClientData()`.

    Supported for fields of type "date", "time", "datetime", "int", "float" or any derived `SimpleType`.

    To configure a different format for export, use `exportFormat`.

    This is a per-field setting; you can alternatively set a default format for all "date", "time" or "datetime" fields via `DateUtil.setNormalDatetimeDisplayFormat()` and related methods on `com.smartgwt.client.util.Date`. See also `LocalizedNumberFormatting` for built-in `FieldTypes` that handle localized currency formatting.

    Also note, this property takes precedence over any specified `dateFormatter`, but can be overridden on a per-component basis by providing a formatter directly on the component, for example, via `ListGrid.setCellFormatter()` or `FormItem.formatValue()`.

    Returns:
      Current format value. Default value is null
    See Also:
      - `getExportFormat()`
      - `FormatString`

  - ### setFormula

    public DataSourceField setFormula(String formula)
    If `field.formula` is set, this field's value in records will be calculated dynamically.

    `DataSourceField.formula` is supported for `SQL DataSources` and for `clientOnly dataSources` only.

    Valid formula expressions may reference other field values directly by field name, or may reference the record object itself. Formula expressions may make use of standard `FormulaFunctions`.

    For example, given a dataSource with two numeric fields "population" and "area" you could easily add a "populationDensity" field with the following formula:

          <field name="populationDensity" type="float">
               <formula>round(population/area)</formula>
          </field>

    For SQL DataSources, values are calculated on the server by modifying the generated SQL request as appropriate. For clientOnly dataSources, values are calculated as part of the `standard fetch response flow`. Since the field values are calculated in the data source layer, standard capbilities like server side sorting of paged data sets are supported for these fields. This would not be the case for formula field values calculated `at the component level`.

    As with other `dynamically calculated` fields, fields with a specified formula are non editable.
    When records are displayed in `dataBoundComponents that support editing`, formula field values will be re-calculated dynamically on the client as the user edits a record, so a user may preview the result of their changes.

    Note that `formula` fields may not make use of `fields included from related dataSources`. DataSourceField.formula is available with Power or better licenses only. See smartclient.com/product for details.

    Parameters:
      `formula` - New formula value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getFormula

    public String getFormula()
    If `field.formula` is set, this field's value in records will be calculated dynamically.

    `DataSourceField.formula` is supported for `SQL DataSources` and for `clientOnly dataSources` only.

    Valid formula expressions may reference other field values directly by field name, or may reference the record object itself. Formula expressions may make use of standard `FormulaFunctions`.

    For example, given a dataSource with two numeric fields "population" and "area" you could easily add a "populationDensity" field with the following formula:

          <field name="populationDensity" type="float">
               <formula>round(population/area)</formula>
          </field>

    For SQL DataSources, values are calculated on the server by modifying the generated SQL request as appropriate. For clientOnly dataSources, values are calculated as part of the `standard fetch response flow`. Since the field values are calculated in the data source layer, standard capbilities like server side sorting of paged data sets are supported for these fields. This would not be the case for formula field values calculated `at the component level`.

    As with other `dynamically calculated` fields, fields with a specified formula are non editable.
    When records are displayed in `dataBoundComponents that support editing`, formula field values will be re-calculated dynamically on the client as the user edits a record, so a user may preview the result of their changes.

    Note that `formula` fields may not make use of `fields included from related dataSources`. DataSourceField.formula is available with Power or better licenses only. See smartclient.com/product for details.

    Returns:
      Current formula value. Default value is null

  - ### setGroup

    public DataSourceField setGroup(String group)
    For use in `ComponentSchema`, indicates what group to place the property in when editing in Reify.
    Parameters:
      `group` - New group value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Schema`

  - ### getGroup

    public String getGroup()
    For use in `ComponentSchema`, indicates what group to place the property in when editing in Reify.
    Returns:
      Current group value. Default value is null
    See Also:
      - `Component Schema`

  - ### setHidden

    public DataSourceField setHidden(boolean hidden)
    Whether this field should be hidden from users by default within a DataBound component. This is generally used for internal IDs and other fields not meaningful to users.

    See `detail` for fields that should be hidden in a summary view such as a `ListGrid`, but still available to the user.

    NOTE: This property is not a security setting - data for hidden fields is still delivered to the client, it just isn't shown to the user. If you wish to make sure that only appropriate data reaches the client, use `OperationBinding.outputs`, `canView`:false on the field, or a field-level declarative security setting like `viewRequiresRole`.

    Parameters:
      `hidden` - New hidden value. Default value is false
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Binding`

  - ### getHidden

    public boolean getHidden()
    Whether this field should be hidden from users by default within a DataBound component. This is generally used for internal IDs and other fields not meaningful to users.

    See `detail` for fields that should be hidden in a summary view such as a `ListGrid`, but still available to the user.

    NOTE: This property is not a security setting - data for hidden fields is still delivered to the client, it just isn't shown to the user. If you wish to make sure that only appropriate data reaches the client, use `OperationBinding.outputs`, `canView`:false on the field, or a field-level declarative security setting like `viewRequiresRole`.

    Returns:
      Current hidden value. Default value is false
    See Also:
      - `Component Binding`

  - ### setIgnoreTextMatchStyle

    public DataSourceField setIgnoreTextMatchStyle(Boolean ignoreTextMatchStyle)
    NOTE: Only applicable to `clientOnly` DataSources and the built-in `SQL`, `JPA` and `Hibernate` DataSources available in Pro, Power and Enterprise versions of Smart GWT.

    Use this flag to inhibit the normal use of `TextMatchStyle` for this field. A field with this flag set will always be tested for exact equality in generated queries, even for filter-style queries where normal behavior would be to use a substring match or similar.

    Whether or not the exact match is case-sensitive is determined by the DataSource's `ignoreTextMatchStyleCaseSensitive` setting.

    Parameters:
      `ignoreTextMatchStyle` - New ignoreTextMatchStyle value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getIgnoreTextMatchStyle

    public Boolean getIgnoreTextMatchStyle()
    NOTE: Only applicable to `clientOnly` DataSources and the built-in `SQL`, `JPA` and `Hibernate` DataSources available in Pro, Power and Enterprise versions of Smart GWT.

    Use this flag to inhibit the normal use of `TextMatchStyle` for this field. A field with this flag set will always be tested for exact equality in generated queries, even for filter-style queries where normal behavior would be to use a substring match or similar.

    Whether or not the exact match is case-sensitive is determined by the DataSource's `ignoreTextMatchStyleCaseSensitive` setting.

    Returns:
      Current ignoreTextMatchStyle value. Default value is null

  - ### setInapplicable

    public DataSourceField setInapplicable(Boolean inapplicable)
    For use in `ComponentSchema`, a field `inherited` from another schema can be redeclared with this property set in order to indicate that the property should not be used.

    This is primarily used to influence `Reify`. For simple type properties, this avoids the property appearing in the Component Editor.

    For fields that hold subcomponents, this prevents inappropriate drag and drop. For example, a custom class called `MyDialog` may automatically create a series of children, and not allow arbitrary other children to be added. In this case, the inherited property `Canvas.children` should be marked inapplicable in order to prevent arbitrary components being dropped onto a `MyDialog` instance.

    Parameters:
      `inapplicable` - New inapplicable value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Schema`

  - ### getInapplicable

    public Boolean getInapplicable()
    For use in `ComponentSchema`, a field `inherited` from another schema can be redeclared with this property set in order to indicate that the property should not be used.

    This is primarily used to influence `Reify`. For simple type properties, this avoids the property appearing in the Component Editor.

    For fields that hold subcomponents, this prevents inappropriate drag and drop. For example, a custom class called `MyDialog` may automatically create a series of children, and not allow arbitrary other children to be added. In this case, the inherited property `Canvas.children` should be marked inapplicable in order to prevent arbitrary components being dropped onto a `MyDialog` instance.

    Returns:
      Current inapplicable value. Default value is null
    See Also:
      - `Component Schema`

  - ### setInitWhen

    public DataSourceField setInitWhen(AdvancedCriteria initWhen)
    Criteria-based control for field settability on add operations. The field can be set during an add when criteria match. On update operations, the field is always read-only (like `canInit:false`).

    On the server, if the operation is an update, or the criteria do not match on an add, the field value is stripped.

    Parameters:
      `initWhen` - New initWhen value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setUpdateWhen(com.smartgwt.client.data.AdvancedCriteria)`
      - `Component Binding`

  - ### getInitWhen

    public AdvancedCriteria getInitWhen()
    Criteria-based control for field settability on add operations. The field can be set during an add when criteria match. On update operations, the field is always read-only (like `canInit:false`).

    On the server, if the operation is an update, or the criteria do not match on an add, the field value is stripped.

    Returns:
      Current initWhen value. Default value is null
    See Also:
      - `getUpdateWhen()`
      - `Component Binding`

  - ### setJoinPrefix

    public DataSourceField setJoinPrefix(String joinPrefix)
    Defines prefix before concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat".
    Parameters:
      `joinPrefix` - New joinPrefix value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setJoinString(java.lang.String)`
      - `setJoinSuffix(java.lang.String)`
      - `com.smartgwt.client.types.SummaryFunction`
      - `Server Summaries`

  - ### getJoinPrefix

    public String getJoinPrefix()
    Defines prefix before concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat".
    Returns:
      Current joinPrefix value. Default value is null
    See Also:
      - `getJoinString()`
      - `getJoinSuffix()`
      - `com.smartgwt.client.types.SummaryFunction`
      - `Server Summaries`

  - ### setJoinString

    public DataSourceField setJoinString(String joinString)
    Defines the delimiter between concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat". The default value is ", ".
    Parameters:
      `joinString` - New joinString value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setJoinPrefix(java.lang.String)`
      - `setJoinSuffix(java.lang.String)`
      - `com.smartgwt.client.types.SummaryFunction`
      - `Server Summaries`

  - ### getJoinString

    public String getJoinString()
    Defines the delimiter between concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat". The default value is ", ".
    Returns:
      Current joinString value. Default value is null
    See Also:
      - `getJoinPrefix()`
      - `getJoinSuffix()`
      - `com.smartgwt.client.types.SummaryFunction`
      - `Server Summaries`

  - ### setJoinSuffix

    public DataSourceField setJoinSuffix(String joinSuffix)
    Defines suffix after concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat".
    Parameters:
      `joinSuffix` - New joinSuffix value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setJoinPrefix(java.lang.String)`
      - `setJoinString(java.lang.String)`
      - `com.smartgwt.client.types.SummaryFunction`
      - `Server Summaries`

  - ### getJoinSuffix

    public String getJoinSuffix()
    Defines suffix after concatenated values if field is used with `Server summaries` feature and the `summary function` is "concat".
    Returns:
      Current joinSuffix value. Default value is null
    See Also:
      - `getJoinPrefix()`
      - `getJoinString()`
      - `com.smartgwt.client.types.SummaryFunction`
      - `Server Summaries`

  - ### setLength

    public DataSourceField setLength(Integer length)
    Maximum number of characters allowed. Applicable only to fields of text type. For fields of this type a `length range validator` will be automatically generated on both the client and server side to enforce this maximum length (unless such a validator is explicitly present for the field already).

    The `TextItem.enforceLength` attribute can also explicitly limit user input for freeform text items editing fields with an explicit length specified.

    NOTE: For DataSources of type "sql", this property has a bearing on the type of column we use when the underlying table is created by a DataSource `import` in the `Admin Console`. Below a certain length (which is database-specific, see below), we use standard `VARCHAR` columns; above that length, we use an alternate strategy (again, database-specific). For these long fields, we sometimes also generate different SQL for "update" and "add" operations, using JDBC "?" replacement parameters rather than embedding values directly in the generated SQL; whether or not this is done depends entirely on what the underlying database product and/or JDBC driver will allow.

    Table of field length limits for supported databases:

    Database product | VARCHAR limit * | Type used above limit
    HSQLDB | None | -
    IBM DB2 | 4000 | CLOB
    Firebird | 32767 | BLOB with subtype 1
    Informix | 255 / 32739 | LVARCHAR / TEXT **
    Microsoft SQL Server | 8000 | TEXT
    MySQL | 255 / 65535 / 16M | TEXT / MEDIUMTEXT / LONGTEXT ***
    MariaDB | 255 / 65535 / 16M | TEXT / MEDIUMTEXT / LONGTEXT ***
    Oracle | 4000 | CLOB
    PostgreSQL | 4000 | TEXT

    * The "VARCHAR limit" referred to here is a limit used by the Smart GWT Server; it is not necessarily imposed by the database. For example, DB2's VARCHAR limit is not 4000 characters; it actually varies from about 4K to about 32K, depending on how the server has been configured.

    ** Informix has a limit of just 255 characters for VARCHAR, but has a native LVARCHAR type which supports nearly 32K characters without needing to fall back on long datatypes. Therefore, with that one product, we have two thresholds for a change in storage type.

    *** MySQL has a limit of 255 characters for VARCHAR, 65,535 characters for TEXT and 16,777,215 for MEDIUMTEXT; therefore, with that one product, we have three thresholds for a change in storage type.

    Parameters:
      `length` - New length value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `ListGridField.setWidth(int)`
      - Long Text Example

  - ### getLength

    public Integer getLength()
    Maximum number of characters allowed. Applicable only to fields of text type. For fields of this type a `length range validator` will be automatically generated on both the client and server side to enforce this maximum length (unless such a validator is explicitly present for the field already).

    The `TextItem.enforceLength` attribute can also explicitly limit user input for freeform text items editing fields with an explicit length specified.

    NOTE: For DataSources of type "sql", this property has a bearing on the type of column we use when the underlying table is created by a DataSource `import` in the `Admin Console`. Below a certain length (which is database-specific, see below), we use standard `VARCHAR` columns; above that length, we use an alternate strategy (again, database-specific). For these long fields, we sometimes also generate different SQL for "update" and "add" operations, using JDBC "?" replacement parameters rather than embedding values directly in the generated SQL; whether or not this is done depends entirely on what the underlying database product and/or JDBC driver will allow.

    Table of field length limits for supported databases:

    Database product | VARCHAR limit * | Type used above limit
    HSQLDB | None | -
    IBM DB2 | 4000 | CLOB
    Firebird | 32767 | BLOB with subtype 1
    Informix | 255 / 32739 | LVARCHAR / TEXT **
    Microsoft SQL Server | 8000 | TEXT
    MySQL | 255 / 65535 / 16M | TEXT / MEDIUMTEXT / LONGTEXT ***
    MariaDB | 255 / 65535 / 16M | TEXT / MEDIUMTEXT / LONGTEXT ***
    Oracle | 4000 | CLOB
    PostgreSQL | 4000 | TEXT

    * The "VARCHAR limit" referred to here is a limit used by the Smart GWT Server; it is not necessarily imposed by the database. For example, DB2's VARCHAR limit is not 4000 characters; it actually varies from about 4K to about 32K, depending on how the server has been configured.

    ** Informix has a limit of just 255 characters for VARCHAR, but has a native LVARCHAR type which supports nearly 32K characters without needing to fall back on long datatypes. Therefore, with that one product, we have two thresholds for a change in storage type.

    *** MySQL has a limit of 255 characters for VARCHAR, 65,535 characters for TEXT and 16,777,215 for MEDIUMTEXT; therefore, with that one product, we have three thresholds for a change in storage type.

    Returns:
      Current length value. Default value is null
    See Also:
      - `ListGridField.getWidth()`
      - Long Text Example

  - ### setLenientXPath

    public DataSourceField setLenientXPath(Boolean lenientXPath)
    Deprecated.
    No longer needs to be set since the framework now defaults to suppressing errors for null values in the middle of Xpath, and only invalid XPath will cause warning be logged.
    Indicates that getting `valueXPath` for this field should not perform any validation at all and will return null for non existing XPaths. Otherwise warning message will be logged for non-existing XPath or with null objects in the middle of XPath.

    NOTE: this applies to server-side processing of valueXPath only.

    Parameters:
      `lenientXPath` - New lenientXPath value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getLenientXPath

    public Boolean getLenientXPath()
    Deprecated.
    No longer needs to be set since the framework now defaults to suppressing errors for null values in the middle of Xpath, and only invalid XPath will cause warning be logged.
    Indicates that getting `valueXPath` for this field should not perform any validation at all and will return null for non existing XPaths. Otherwise warning message will be logged for non-existing XPath or with null objects in the middle of XPath.

    NOTE: this applies to server-side processing of valueXPath only.

    Returns:
      Current lenientXPath value. Default value is null

  - ### setMultiple

    public DataSourceField setMultiple(Boolean multiple)
    Indicates that this field should always be Array-valued. If the value derived from `XML or JSON data` is singular, it will be wrapped in an Array.

    JPA and Hibernate DataSources use `multiple:true` as part of the declaration of One-To-Many and Many-to-Many relations - see `JpaHibernateRelations` for details. On fields that also declare a `foreignKey` `multiple:true` also indicates that this field is participating in a one-to-many or many-to-many relation - see `DataSourceRelations` for details.

    #### Criteria on multiple:true fields: client-side filtering

    For simple Criteria, the criteria value is compared to each field value in the `multiple:true` field, according to the `textMatchStyle`. If any field value matches the j filter value, the field is considered to match the criteria.

    For `AdvancedCriteria`, for normal `search operators` the field value is considered as matching the `Criterion` if any of the field values match the Criterion. Specifically, this is true of all operators that have an `operatorValueType` of "fieldType" or "valueRange".

    For operators that compare against other fields in same record, such as "equalsField", if the other field is not `multiple:true`, matching works the same as for normal operators, that is, as if `criterion.value` directly contained the value rather than the name of another field.

    If the other field is also multiple:true, only "equalsField", "notEqualsField", "iEqualsField" and "iNotEqualsField" are allowed (any other `operator` will cause a warning and be ignored) and the set of values in the field must be identical (aside from case, for operators prefixed with "i") and in identical order to match.

    For the `inSet` operator, the field matches if there is any intersection between the field values and the array of values provided in `criterion.value`. `notInSet` is the reverse.

    "Finally, for "isNull" and "notNull", an empty Array is considered non-null, however, for "isBlank" and "notBlank", an empty Array is considered blank, since a control such as a multiple:true SelectItem or MultiComboBoxItem would appear blank to the end user if it had an empty Array as its value.

    #### Server-side Representation and Storage

    Values for multiple:true fields appear as Java Lists when received in server code such as a DMI. The Smart GWT Server supports simple storage of values that are multiple:true, controlled via the `multipleStorage` setting.

    For server-side behavior of relation fields that are multiple:true, see `DataSourceRelations`; for the specifics of JPA and Hibernate relation fields that are multiple:true, see `JpaHibernateRelations`.

    For non-relation fields, the Smart GWT Server supports simple storage of values that are multiple:true, controlled via the `multipleStorage` setting, with some limited support for server-side filtering, as described in the `multipleStorage` docs.

    For the built-in SQL, Hibernate and JPA connectors, if criteria are specified for a multiple:true field where `multipleStorage` is null or "none", the Smart GWT server knows nothing about how the multiple values are stored, so as a fallback the criteria will operate as though the field were a normal, non-multiple "text" field. This will generally not match the client-side filtering behavior described above, so filtering should either be performed entirely on the client (for example, via `dataFetchMode:"local"` or entirely on the server (via `ResultSet.useClientFiltering`:"false")

    The server-side filtering is done through a criteria transform which happens with `transformMultipleFields`.

    #### XML Serialization

    Specifically for XML serialization and deserialization, `multiple:true` behaves similarly to the SOAP array idiom, that is, there will be a "wrapper element" named after the field name, whose contents will be several elements of the specified `field.type`.

    For example, `Layout.members` is declared with `type:"Canvas", multiple:true`. The correct XML format is thus:

          <VLayout>
              <members>
                  <Canvas ID="myCanvas" ... />
                  <ListGrid ID="myGrid" .../>
                  <Toolstrip ID="myToolStrip" ... />
              </members>
          </VLayout>

    See `childTagName` for customizing the tagName used for subelements.

    Overrides:
      `setMultiple` in class `Field`
    Parameters:
      `multiple` - New multiple value. Default value is false
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Schema`

  - ### getMultiple

    public Boolean getMultiple()
    Indicates that this field should always be Array-valued. If the value derived from `XML or JSON data` is singular, it will be wrapped in an Array.

    JPA and Hibernate DataSources use `multiple:true` as part of the declaration of One-To-Many and Many-to-Many relations - see `JpaHibernateRelations` for details. On fields that also declare a `foreignKey` `multiple:true` also indicates that this field is participating in a one-to-many or many-to-many relation - see `DataSourceRelations` for details.

    #### Criteria on multiple:true fields: client-side filtering

    For simple Criteria, the criteria value is compared to each field value in the `multiple:true` field, according to the `textMatchStyle`. If any field value matches the j filter value, the field is considered to match the criteria.

    For `AdvancedCriteria`, for normal `search operators` the field value is considered as matching the `Criterion` if any of the field values match the Criterion. Specifically, this is true of all operators that have an `operatorValueType` of "fieldType" or "valueRange".

    For operators that compare against other fields in same record, such as "equalsField", if the other field is not `multiple:true`, matching works the same as for normal operators, that is, as if `criterion.value` directly contained the value rather than the name of another field.

    If the other field is also multiple:true, only "equalsField", "notEqualsField", "iEqualsField" and "iNotEqualsField" are allowed (any other `operator` will cause a warning and be ignored) and the set of values in the field must be identical (aside from case, for operators prefixed with "i") and in identical order to match.

    For the `inSet` operator, the field matches if there is any intersection between the field values and the array of values provided in `criterion.value`. `notInSet` is the reverse.

    "Finally, for "isNull" and "notNull", an empty Array is considered non-null, however, for "isBlank" and "notBlank", an empty Array is considered blank, since a control such as a multiple:true SelectItem or MultiComboBoxItem would appear blank to the end user if it had an empty Array as its value.

    #### Server-side Representation and Storage

    Values for multiple:true fields appear as Java Lists when received in server code such as a DMI. The Smart GWT Server supports simple storage of values that are multiple:true, controlled via the `multipleStorage` setting.

    For server-side behavior of relation fields that are multiple:true, see `DataSourceRelations`; for the specifics of JPA and Hibernate relation fields that are multiple:true, see `JpaHibernateRelations`.

    For non-relation fields, the Smart GWT Server supports simple storage of values that are multiple:true, controlled via the `multipleStorage` setting, with some limited support for server-side filtering, as described in the `multipleStorage` docs.

    For the built-in SQL, Hibernate and JPA connectors, if criteria are specified for a multiple:true field where `multipleStorage` is null or "none", the Smart GWT server knows nothing about how the multiple values are stored, so as a fallback the criteria will operate as though the field were a normal, non-multiple "text" field. This will generally not match the client-side filtering behavior described above, so filtering should either be performed entirely on the client (for example, via `dataFetchMode:"local"` or entirely on the server (via `ResultSet.useClientFiltering`:"false")

    The server-side filtering is done through a criteria transform which happens with `transformMultipleFields`.

    #### XML Serialization

    Specifically for XML serialization and deserialization, `multiple:true` behaves similarly to the SOAP array idiom, that is, there will be a "wrapper element" named after the field name, whose contents will be several elements of the specified `field.type`.

    For example, `Layout.members` is declared with `type:"Canvas", multiple:true`. The correct XML format is thus:

          <VLayout>
              <members>
                  <Canvas ID="myCanvas" ... />
                  <ListGrid ID="myGrid" .../>
                  <Toolstrip ID="myToolStrip" ... />
              </members>
          </VLayout>

    See `childTagName` for customizing the tagName used for subelements.

    Overrides:
      `getMultiple` in class `Field`
    Returns:
      Current multiple value. Default value is false
    See Also:
      - `Component Schema`

  - ### setMultipleValueSeparator

    public DataSourceField setMultipleValueSeparator(String multipleValueSeparator)
    For fields that are `multiple:true`, the separator used between values when they are displayed.
    Parameters:
      `multipleValueSeparator` - New multipleValueSeparator value. Default value is ", "
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getMultipleValueSeparator

    public String getMultipleValueSeparator()
    For fields that are `multiple:true`, the separator used between values when they are displayed.
    Returns:
      Current multipleValueSeparator value. Default value is ", "

  - ### setName

    public DataSourceField setName(String name)
    Name for this field.

    Must be unique across all fields within the DataSource as well as a valid JavaScript identifier - see `FieldName` for details and how to check for validity.

    The field name is also the property in each DataSource record which holds the value for this field.

    Note: If this is a `SQL-backed` dataSource, the field name should be a valid SQL colmn name, or the `nativeName` property should be set to a valid column name.

    Overrides:
      `setName` in class `Field`
    Parameters:
      `name` - New name value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `FieldName`

  - ### getName

    public String getName()
    Name for this field.

    Must be unique across all fields within the DataSource as well as a valid JavaScript identifier - see `FieldName` for details and how to check for validity.

    The field name is also the property in each DataSource record which holds the value for this field.

    Note: If this is a `SQL-backed` dataSource, the field name should be a valid SQL colmn name, or the `nativeName` property should be set to a valid column name.

    Overrides:
      `getName` in class `Field`
    Returns:
      Current name value. Default value is null
    See Also:
      - `FieldName`

  - ### setNillable

    public DataSourceField setNillable(Boolean nillable)
    Controls whether an explicit null-valued Record attribute for this field should result in `xsi:nil` being used to transmit the value when serializing to XML, like so:

          <book>
              <title>Beowulf</title>
              <author xsi:nil="true"/>
          </book>

    If `nillable` is not set, no XML element will be generated for the explicit null value.

    A DataSourceField that specifies a `foreignKey` is automatically nillable unless this property is explicitly set to `false`.

    Parameters:
      `nillable` - New nillable value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getNillable

    public Boolean getNillable()
    Controls whether an explicit null-valued Record attribute for this field should result in `xsi:nil` being used to transmit the value when serializing to XML, like so:

          <book>
              <title>Beowulf</title>
              <author xsi:nil="true"/>
          </book>

    If `nillable` is not set, no XML element will be generated for the explicit null value.

    A DataSourceField that specifies a `foreignKey` is automatically nillable unless this property is explicitly set to `false`.

    Returns:
      Current nillable value. Default value is null

  - ### setPluralTitle

    public DataSourceField setPluralTitle(String pluralTitle)
    User-visible plural name for this field.

    For example, for an "orderID" field in an "orderItem" DataSource, a plural title of "Orders" may be appropriate.

    Defaults to `field.title` + "s" if not specified.

    This can be set on a field to override the DataSource's `DataSource.pluralTitle` when the field refers to a related DataSource whose pluralTitle is unset or needs a different value in the current context (e.g. a more compact label).

    Parameters:
      `pluralTitle` - New pluralTitle value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `DataSource.setPluralTitle(java.lang.String)`

  - ### getPluralTitle

    public String getPluralTitle()
    User-visible plural name for this field.

    For example, for an "orderID" field in an "orderItem" DataSource, a plural title of "Orders" may be appropriate.

    Defaults to `field.title` + "s" if not specified.

    This can be set on a field to override the DataSource's `DataSource.pluralTitle` when the field refers to a related DataSource whose pluralTitle is unset or needs a different value in the current context (e.g. a more compact label).

    Returns:
      Current pluralTitle value. Default value is null
    See Also:
      - `DataSource.getPluralTitle()`

  - ### setPrecision

    public DataSourceField setPrecision(Integer precision)
    Applies only to fields of type "float" or "integer" and affects how many significant digits are shown.

    For example, a field value of 343.1, 343.104 and 343.09872677 would all be shown as 343.10 if precision is 5.

    The original value is always shown when the value is edited.

    Parameters:
      `precision` - New precision value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Appearance overview and related methods`

  - ### getPrecision

    public Integer getPrecision()
    Applies only to fields of type "float" or "integer" and affects how many significant digits are shown.

    For example, a field value of 343.1, 343.104 and 343.09872677 would all be shown as 343.10 if precision is 5.

    The original value is always shown when the value is edited.

    Returns:
      Current precision value. Default value is null
    See Also:
      - `Appearance overview and related methods`

  - ### setPrimaryKey

    public DataSourceField setPrimaryKey(boolean primaryKey)
    If set to `true`, indicates either that this field holds a value unique across all records in this data source, or that it is one of a number of fields marked as primary keys, and the combination of the values held in all of those fields is unique across all records in the data source. Note that the latter usage - so-called "composite" or "multipart" keys - is intended for support of legacy databases only: if you are able to choose an approach, Isomorphic recommends the use of one `primaryKey` field per data source, and ideally this field should be of `type` SEQUENCE. If you have control of the underlying tables, there is nothing to stop you from adding a field like this (a so-called "synthetic" or "surrogate" key), even for tables that already have a set of columns that could combine to make a composite key (a so-called "natural" key). Also, it is neither necessary nor correct to use a composite primaryKey because you want to enforce uniqueness across that combination of fields. You can achieve that by declaring a unique constraint in the table schema, or use an `isUnique` validator with `validator.criteriaFields`, or both; there is no need to use a composite key to enforce uniqueness.

    Note that composite primaryKeys are not supported in tree-structured datasets (`Tree` and `ResultTree`) or components (`TreeGrid`, `ColumnTree`). Tree-structured data requires that nodes have a unique `idField`, with the parent/child relationship expressed through the `parentIdField`. This implies that binding a Tree to a DataSource requires that the DataSource have a singular primaryKey, and that the primaryKey field is also the idField, as described in the `tree databinding overview`

    A DataSource that can only perform the "fetch" operation does not require a primaryKey unless it contains `binary fields`. If a DataSource allows modification of DataSource records through add, update and remove DataSource operations, or it contains one or more binary fields, one or more fields must be marked as the primary key.

    Smart GWT requires a primary key value to uniquely identify records when communicating updates or deletions to the server. There is no requirement that the primaryKey field be mapped to an actual "primary key" in your object model, web service, or database (though this is the most obvious and natural thing to do, of course). The only requirement is that the combined values of the primaryKey fields be unique for a given browser instance for the lifetime of the page.

    If using Smart GWT's `SQL engine` and generating SQL tables using the `Database Configuration Tool`, the table column generated from a primaryKey field will have a unique constraint applied in the database table and, if the field is of type "sequence", the database column will also be created as an "identity column" in those databases that implement sequence-type handling with identity columns.

    Overrides:
      `setPrimaryKey` in class `Field`
    Parameters:
      `primaryKey` - New primaryKey value. Default value is false
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Relations`

  - ### getPrimaryKey

    public boolean getPrimaryKey()
    If set to `true`, indicates either that this field holds a value unique across all records in this data source, or that it is one of a number of fields marked as primary keys, and the combination of the values held in all of those fields is unique across all records in the data source. Note that the latter usage - so-called "composite" or "multipart" keys - is intended for support of legacy databases only: if you are able to choose an approach, Isomorphic recommends the use of one `primaryKey` field per data source, and ideally this field should be of `type` SEQUENCE. If you have control of the underlying tables, there is nothing to stop you from adding a field like this (a so-called "synthetic" or "surrogate" key), even for tables that already have a set of columns that could combine to make a composite key (a so-called "natural" key). Also, it is neither necessary nor correct to use a composite primaryKey because you want to enforce uniqueness across that combination of fields. You can achieve that by declaring a unique constraint in the table schema, or use an `isUnique` validator with `validator.criteriaFields`, or both; there is no need to use a composite key to enforce uniqueness.

    Note that composite primaryKeys are not supported in tree-structured datasets (`Tree` and `ResultTree`) or components (`TreeGrid`, `ColumnTree`). Tree-structured data requires that nodes have a unique `idField`, with the parent/child relationship expressed through the `parentIdField`. This implies that binding a Tree to a DataSource requires that the DataSource have a singular primaryKey, and that the primaryKey field is also the idField, as described in the `tree databinding overview`

    A DataSource that can only perform the "fetch" operation does not require a primaryKey unless it contains `binary fields`. If a DataSource allows modification of DataSource records through add, update and remove DataSource operations, or it contains one or more binary fields, one or more fields must be marked as the primary key.

    Smart GWT requires a primary key value to uniquely identify records when communicating updates or deletions to the server. There is no requirement that the primaryKey field be mapped to an actual "primary key" in your object model, web service, or database (though this is the most obvious and natural thing to do, of course). The only requirement is that the combined values of the primaryKey fields be unique for a given browser instance for the lifetime of the page.

    If using Smart GWT's `SQL engine` and generating SQL tables using the `Database Configuration Tool`, the table column generated from a primaryKey field will have a unique constraint applied in the database table and, if the field is of type "sequence", the database column will also be created as an "identity column" in those databases that implement sequence-type handling with identity columns.

    Overrides:
      `getPrimaryKey` in class `Field`
    Returns:
      Current primaryKey value. Default value is false
    See Also:
      - `Relations`

  - ### setPropertiesOnly

    public DataSourceField setPropertiesOnly(Boolean propertiesOnly)
    For use in `ComponentSchema` for fields that contain other components, this flag suppresses auto-construction for subcomponents that appear under this field.

    For example, the `VLayout` schema sets this for its `members` property, so that when a VLayout is constructed via XML as follows:

          <VLayout>
              <members>
                  <ListGrid ID="myGrid" .../>
                  <Toolstrip ID="myToolStrip" ... />
              </members>
          </VLayout>

    The ListGrid and ToolStrip do not construct themselves automatically. Instead, the VLayout receives the properties of the ListGrid and ToolStrip as ordinary JavaScript Objects, with the special property `_constructor` set to the name of the class that should be constructed.
    Parameters:
      `propertiesOnly` - New propertiesOnly value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Schema`

  - ### getPropertiesOnly

    public Boolean getPropertiesOnly()
    For use in `ComponentSchema` for fields that contain other components, this flag suppresses auto-construction for subcomponents that appear under this field.

    For example, the `VLayout` schema sets this for its `members` property, so that when a VLayout is constructed via XML as follows:

          <VLayout>
              <members>
                  <ListGrid ID="myGrid" .../>
                  <Toolstrip ID="myToolStrip" ... />
              </members>
          </VLayout>

    The ListGrid and ToolStrip do not construct themselves automatically. Instead, the VLayout receives the properties of the ListGrid and ToolStrip as ordinary JavaScript Objects, with the special property `_constructor` set to the name of the class that should be constructed.
    Returns:
      Current propertiesOnly value. Default value is null
    See Also:
      - `Component Schema`

  - ### setReadOnlyWhen

    public DataSourceField setReadOnlyWhen(AdvancedCriteria readOnlyWhen)
    Criteria-based version of `canEdit:false`. When the criteria match, the field is treated as read-only: the server strips the field value from add/update operations (same as `canSave:false`), and the client makes the field non-editable in forms.

    Supports the full ServerDynamicCriteria syntax, including references to the current user, operation type, and fields on related DataSources.

    For validation that also enforces on the server, use `requiredWhen` in combination with `readOnlyWhen` to both prevent editing and reject values server-side when the criteria match.

    Parameters:
      `readOnlyWhen` - New readOnlyWhen value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setEditWhen(com.smartgwt.client.data.AdvancedCriteria)`
      - `setCanEdit(java.lang.Boolean)`
      - `setRequiredWhen(com.smartgwt.client.data.AdvancedCriteria)`
      - `Component Binding`

  - ### getReadOnlyWhen

    public AdvancedCriteria getReadOnlyWhen()
    Criteria-based version of `canEdit:false`. When the criteria match, the field is treated as read-only: the server strips the field value from add/update operations (same as `canSave:false`), and the client makes the field non-editable in forms.

    Supports the full ServerDynamicCriteria syntax, including references to the current user, operation type, and fields on related DataSources.

    For validation that also enforces on the server, use `requiredWhen` in combination with `readOnlyWhen` to both prevent editing and reject values server-side when the criteria match.

    Returns:
      Current readOnlyWhen value. Default value is null
    See Also:
      - `getEditWhen()`
      - `getCanEdit()`
      - `getRequiredWhen()`
      - `Component Binding`

  - ### setRecreateOnChange

    public DataSourceField setRecreateOnChange(Boolean recreateOnChange)
    For use in `ComponentSchema` for fields that, when changed in `Reify`, should discard the current live component and recreate it with the current configured properties.

    This property is typically set when a custom component is being used that doesn't have a setter for the field.

    Parameters:
      `recreateOnChange` - New recreateOnChange value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `PaletteNode.setRecreateOnChange(java.lang.Boolean)`
      - `Component Schema`

  - ### getRecreateOnChange

    public Boolean getRecreateOnChange()
    For use in `ComponentSchema` for fields that, when changed in `Reify`, should discard the current live component and recreate it with the current configured properties.

    This property is typically set when a custom component is being used that doesn't have a setter for the field.

    Returns:
      Current recreateOnChange value. Default value is null
    See Also:
      - `PaletteNode.getRecreateOnChange()`
      - `Component Schema`

  - ### setRequired

    public DataSourceField setRequired(boolean required)
    Indicates this field must be non-null in order for a record to pass validation. Or, in the case of a "binary" field, a non-empty file must be uploaded. Setting this property has the same effect as giving the field a `"required" validator`.

    Note that `required` should not be set for a server-generated field, such as a sequence, or validation will fail on the client.

    For conditionally required fields, use `requiredWhen` instead of manually adding a `required` validator with `Validator.applyWhen`. `requiredWhen` supports the full ServerDynamicCriteria syntax including references to the current user, operation type, and fields on related DataSources.

    ### Conditionally required fields

    Adding an `applyWhen` condition to a `required` validator introduces subtle complexities to the process of validating an existing record. The client is not guaranteed to know the full and complete state of the record it is editing because it is common for a `DynamicForm` to be editing a subset of fields. When a field is unconditionally required, things are simple: if the DynamicForm has a `FormItem` for that field, then the `required` validation passes if that FormItem has a value, and fails if it does not. If the form has no FormItem for the field, it can assume that the field has a value because otherwise it would have failed validation when we attempted to add it (when we are adding a record, we of course do know the full and complete state of the record - it is whatever we are about to add).

    When a field is conditionally required, the client can no longer assume that all required fields will have a value. It may be the case that the condition of requirement was not met when the record was added, but now it is. For example, consider these field definitions:

             <field name="yearsAtCurrentAddress" type="integer" />
             <field name="previousAddress" type="text" >
               <validator type="required" errorMessage="Previous address is required if you have been at your current address less than three years">
                 <applyWhen operator="and">
                   <criteria>
                     <criterion fieldName="yearsAtCurrentAddress" operator="lessThan" value="3" />
                   </criteria>
                 </applyWhen>
               </validator>
             </field>

    Imagine a record for this DataSource is added where the user has entered a value of "3" for "yearsAtCurrentAddress", and no previous address. Later, the value of that field is changed to "2". If this is done using a form that is also showing the "previousAddress" field, we will know that "previousAddress" has not been provided, so we can fail the validation and the user will get a helpful error message explaining what the problem is.

    However, if the form does not also show the "previousAddress" field, we may choose to use an `OperationBinding` that uses `outputs` to trim the record down to just the fields the form does contain, in the interests of avoiding information leakage. Or perhaps that value is automatically culled from the record before the client sees it by the application of a `declarative security rule`. Whatever the reason, if the client does not have the complete record, it is not possible for the client to sensibly apply this validation. And because the client has no way of knowing if a value is missing because it is genuinely null, or because it has been trimmed away by the server, we must treat any null value with suspicion (unless it has a matching FormItem - the presence of the FormItem means that the user can edit the value, so it would make no sense to pair it with a trimmed record that excludes that field value).

    When this happens, we mark the validation as having passed on the client, but in need of running on the server. The server validation makes use of the "storedRecord" facility (look for the description of $storedRecord in the `Velocity support overview`) to overlay the changed record on top of the existing record as it currently exists in the database. This gives the validator the complete record including both changed and unchanged values, so it is able to carry out the required check in a meaningful way. However, you should be aware that the combination of conditional "required" validators and DynamicForms that edit partial records can result in a validation that cannot run on the client and must do both a server roundtrip and a database fetch.

    Parameters:
      `required` - New required value. Default value is false
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setRequiredWhen(com.smartgwt.client.data.AdvancedCriteria)`
      - `Validator.setApplyWhen(com.smartgwt.client.data.AdvancedCriteria)`

  - ### getRequired

    public boolean getRequired()
    Indicates this field must be non-null in order for a record to pass validation. Or, in the case of a "binary" field, a non-empty file must be uploaded. Setting this property has the same effect as giving the field a `"required" validator`.

    Note that `required` should not be set for a server-generated field, such as a sequence, or validation will fail on the client.

    For conditionally required fields, use `requiredWhen` instead of manually adding a `required` validator with `Validator.applyWhen`. `requiredWhen` supports the full ServerDynamicCriteria syntax including references to the current user, operation type, and fields on related DataSources.

    ### Conditionally required fields

    Adding an `applyWhen` condition to a `required` validator introduces subtle complexities to the process of validating an existing record. The client is not guaranteed to know the full and complete state of the record it is editing because it is common for a `DynamicForm` to be editing a subset of fields. When a field is unconditionally required, things are simple: if the DynamicForm has a `FormItem` for that field, then the `required` validation passes if that FormItem has a value, and fails if it does not. If the form has no FormItem for the field, it can assume that the field has a value because otherwise it would have failed validation when we attempted to add it (when we are adding a record, we of course do know the full and complete state of the record - it is whatever we are about to add).

    When a field is conditionally required, the client can no longer assume that all required fields will have a value. It may be the case that the condition of requirement was not met when the record was added, but now it is. For example, consider these field definitions:

             <field name="yearsAtCurrentAddress" type="integer" />
             <field name="previousAddress" type="text" >
               <validator type="required" errorMessage="Previous address is required if you have been at your current address less than three years">
                 <applyWhen operator="and">
                   <criteria>
                     <criterion fieldName="yearsAtCurrentAddress" operator="lessThan" value="3" />
                   </criteria>
                 </applyWhen>
               </validator>
             </field>

    Imagine a record for this DataSource is added where the user has entered a value of "3" for "yearsAtCurrentAddress", and no previous address. Later, the value of that field is changed to "2". If this is done using a form that is also showing the "previousAddress" field, we will know that "previousAddress" has not been provided, so we can fail the validation and the user will get a helpful error message explaining what the problem is.

    However, if the form does not also show the "previousAddress" field, we may choose to use an `OperationBinding` that uses `outputs` to trim the record down to just the fields the form does contain, in the interests of avoiding information leakage. Or perhaps that value is automatically culled from the record before the client sees it by the application of a `declarative security rule`. Whatever the reason, if the client does not have the complete record, it is not possible for the client to sensibly apply this validation. And because the client has no way of knowing if a value is missing because it is genuinely null, or because it has been trimmed away by the server, we must treat any null value with suspicion (unless it has a matching FormItem - the presence of the FormItem means that the user can edit the value, so it would make no sense to pair it with a trimmed record that excludes that field value).

    When this happens, we mark the validation as having passed on the client, but in need of running on the server. The server validation makes use of the "storedRecord" facility (look for the description of $storedRecord in the `Velocity support overview`) to overlay the changed record on top of the existing record as it currently exists in the database. This gives the validator the complete record including both changed and unchanged values, so it is able to carry out the required check in a meaningful way. However, you should be aware that the combination of conditional "required" validators and DynamicForms that edit partial records can result in a validation that cannot run on the client and must do both a server roundtrip and a database fetch.

    Returns:
      Current required value. Default value is false
    See Also:
      - `getRequiredWhen()`
      - `Validator.getApplyWhen()`

  - ### setRequiredMessage

    public DataSourceField setRequiredMessage(String requiredMessage)
    The required message when a field that has been marked as `required` is not filled in by the user.

    Note that this setting wins over `DataSource.requiredMessage` if both are set.

    Parameters:
      `requiredMessage` - New requiredMessage value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Form Titles`

  - ### getRequiredMessage

    public String getRequiredMessage()
    The required message when a field that has been marked as `required` is not filled in by the user.

    Note that this setting wins over `DataSource.requiredMessage` if both are set.

    Returns:
      Current requiredMessage value. Default value is null
    See Also:
      - `Form Titles`

  - ### setRequiredWhen

    public DataSourceField setRequiredWhen(AdvancedCriteria requiredWhen)
    Criteria to be evaluated to determine whether this field is `required`. Equivalent to adding a `required` validator with `applyWhen` set to these criteria.

    Supports the full ServerDynamicCriteria syntax including references to the current user, operation type, and fields on related DataSources.

    Example — field is required only on add:

          <field name="reason" type="text">
            <requiredWhen fieldName="context.operationType"
                          operator="equals" value="add"/>
          </field>

    Parameters:
      `requiredWhen` - New requiredWhen value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setRequired(boolean)`
      - `Validator.setApplyWhen(com.smartgwt.client.data.AdvancedCriteria)`

  - ### getRequiredWhen

    public AdvancedCriteria getRequiredWhen()
    Criteria to be evaluated to determine whether this field is `required`. Equivalent to adding a `required` validator with `applyWhen` set to these criteria.

    Supports the full ServerDynamicCriteria syntax including references to the current user, operation type, and fields on related DataSources.

    Example — field is required only on add:

          <field name="reason" type="text">
            <requiredWhen fieldName="context.operationType"
                          operator="equals" value="add"/>
          </field>

    Returns:
      Current requiredWhen value. Default value is null
    See Also:
      - `getRequired()`
      - `Validator.getApplyWhen()`

  - ### setRootValue

    public DataSourceField setRootValue(Object rootValue)
    For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node. Defaults to null.

    Note that the rootValue may be overridden on a specific ResultTree instance by setting `ResultTree.rootNode`, or if the ResultTree is auto-generated by a `TreeGrid`, by setting `TreeGrid.treeRootValue`. This allows a component to navigate a subtree of the hierarchical data from this dataSource starting at a particular node.

    Parameters:
      `rootValue` - New rootValue value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Relations`

  - ### getRootValue

    public Object getRootValue()
    For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node. Defaults to null.

    Note that the rootValue may be overridden on a specific ResultTree instance by setting `ResultTree.rootNode`, or if the ResultTree is auto-generated by a `TreeGrid`, by setting `TreeGrid.treeRootValue`. This allows a component to navigate a subtree of the hierarchical data from this dataSource starting at a particular node.

    Returns:
      Current rootValue value. Default value is null
    See Also:
      - `Relations`

  - ### setSequenceName

    public DataSourceField setSequenceName(String sequenceName)
    For a DataSource with `serverType:"sql"` with a field of type "sequence", the name of the SQL sequence that should be used when inserting new records into this table.

    Note that this is never required for SQL tables that are generated from Smart GWT DataSources (a default sequence name of tableName + "_" + columnName is chosen, but see the notes below regarding this), and is never required for databases where inserting null into a sequence column is sufficient (MySQL, SQL Server, DB2 and others).

    You would only need to set sequenceName if you are integrating with a pre-existing table stored in a database where the sequence must be named for insertion to work (Oracle, Postgres, Firebird) OR you are trying to use the same sequence across multiple DataSources.

    Note: If you specify the `sql.{database type}.sequence.name.prefix` and/or `sql.{database type}.sequence.name.suffix` properties in your `server.properties` file,the generated sequence name will include the prefix and/or suffix. For example, with a prefix of "order_system_" and a suffix of "_seq", the sequence generated for column "orderNumber" on table "orders" would be:

              order_system_orders_orderNumber_seq

    Parameters:
      `sequenceName` - New sequenceName value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `SQL DataSources`

  - ### getSequenceName

    public String getSequenceName()
    For a DataSource with `serverType:"sql"` with a field of type "sequence", the name of the SQL sequence that should be used when inserting new records into this table.

    Note that this is never required for SQL tables that are generated from Smart GWT DataSources (a default sequence name of tableName + "_" + columnName is chosen, but see the notes below regarding this), and is never required for databases where inserting null into a sequence column is sufficient (MySQL, SQL Server, DB2 and others).

    You would only need to set sequenceName if you are integrating with a pre-existing table stored in a database where the sequence must be named for insertion to work (Oracle, Postgres, Firebird) OR you are trying to use the same sequence across multiple DataSources.

    Note: If you specify the `sql.{database type}.sequence.name.prefix` and/or `sql.{database type}.sequence.name.suffix` properties in your `server.properties` file,the generated sequence name will include the prefix and/or suffix. For example, with a prefix of "order_system_" and a suffix of "_seq", the sequence generated for column "orderNumber" on table "orders" would be:

              order_system_orders_orderNumber_seq

    Returns:
      Current sequenceName value. Default value is null
    See Also:
      - `SQL DataSources`

  - ### setShowFileInline

    public DataSourceField setShowFileInline(Boolean showFileInline)
    For a field of type:"imageFile", indicates whether to stream the image and display it inline or to display the View and Download icons.
    Parameters:
      `showFileInline` - New showFileInline value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getShowFileInline

    public Boolean getShowFileInline()
    For a field of type:"imageFile", indicates whether to stream the image and display it inline or to display the View and Download icons.
    Returns:
      Current showFileInline value. Default value is null

  - ### setSortByField

    public DataSourceField setSortByField(String sortByField)
    Causes values for this field to be sorted according to values for another field, for both client- and server-side sorting.

    This can be used to establish a sort order for a field that is not the normal sorting order indicated by the field value, typically by having the `sortByField` as a `hidden field`.

    If using SQLDataSource, consider using a `customSelectExpression` as an efficient way to populate the `sortByField` with the results of a SQL expression.

    Overrides:
      `setSortByField` in class `Field`
    Parameters:
      `sortByField` - New sortByField value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `FieldName`

  - ### getSortByField

    public String getSortByField()
    Causes values for this field to be sorted according to values for another field, for both client- and server-side sorting.

    This can be used to establish a sort order for a field that is not the normal sorting order indicated by the field value, typically by having the `sortByField` as a `hidden field`.

    If using SQLDataSource, consider using a `customSelectExpression` as an efficient way to populate the `sortByField` with the results of a SQL expression.

    Overrides:
      `getSortByField` in class `Field`
    Returns:
      Current sortByField value. Default value is null
    See Also:
      - `FieldName`

  - ### setStringInBrowser

    public DataSourceField setStringInBrowser(Boolean stringInBrowser)
    Server-side setting that causes values for fields of type "integer" or "float" to be represented as Strings when delivered to a web browser, in order to avoid mangling values which cannot be represented faithfully in JavaScript.

    JavaScript has a single "Number" type which internally stores numbers in a format equivalent to Java's "Double" - double-precision floating point. This means it cannot represent the full range of Java's Long type: Java Longs can represent integral values between -2^63 to 2^63-1, whereas JavaScript Number can only represent exact integer values between -2^53 and 2^53. Similarly, JavaScript's Number type cannot represent Java's unlimited-size BigInteger or unlimited-precision BigDecimal objects at all.

    The `stringInBrowser` setting can be used to deliver numeric values as Strings to the browser. This is intended to allow read-only display and successful round-tripping of the numeric value, however, it will not cause number-oriented features such as `SpinnerItem`, `Slider`, `ListGrid summaries` or range-checking `validators` or `criteria` to actually work.

    If `stringInBrowser` is not set, the default behavior is configured by `DataSource.stringInBrowser` on the owning DataSource if set, otherwise by the `server.properties` setting `datasource.defaultStringInBrowser`. If this flag is false, numeric values are delivered to the client as numbers, even where this will lead to a loss of precision. If the flag is true (which is the default), the behavior is to prevent range overflow for numeric values:

    - Java values of type Long, BigInteger and BigDecimal will be delivered as String only if they exceed JavaScript's number range.
    - Client-side validation will allow inputs that are outside of JavaScript's normal integer range, and such numbers will remain as Strings after validation, instead of being converted to Numbers
    - Values submitted to the server will be converted to BigInteger if they exceed the range of Java's Long type. This happens during DSRequest validation, before any defined `DMI methods` are called.

    This default set of behaviors is intended to automatically deal with cases like numeric `primaryKey` or `foreignKey` values that are never used as numbers, but happen to use the full Java Long range. To disable the above behaviors, set `stringInBrowser="false"`.

    If `stringInBrowser` is explicitly set to true:

    - the value for the field will always be delivered to the browser as a String (no attempt is made to detect the value as out of range / too high precision)
    - client-side validation will do a check for valid format only, and always leave the value as a String. Numeric range validators are ignored client-side (always pass), but are still active server-side.
    - AdvancedCriteria `operators` that check if values are in a particular range will always pass
    - the field is treated as though `canFilter:false` were set, to avoid showing non-functional search interfaces to the user. Set `canFilter="true"` to avoid this effect

    This setting is recommended for presenting out-of-range issues or precision loss on fields that represent actual quantities (as opposed to primaryKey or foreignKey fields, which really represent IDs). To ensure unlimited-precision BigDecimal values are preserved, you should also set `javaClass`.

    Note that responses delivered as JSON or XML, such as responses from the `RESTHandler servlet`, are not affected. This setting applies only to responses delivered to a web browser.

    The entirety of stringInBrowser processing can be completely disabled by setting `server.properties` flag `datasource.disableStringInBrowser` to true. This will cause all numeric values to be delivered as numbers without even attempting to detect if this will lead to a loss of precision. This setting overrides both the `stringInBrowser` field setting and the `datasource.defaultStringInBrowser server.properties` flag.

    `stringInBrowser` and client-side DataSources

    For DataSources that are not based on the Smart GWT Server, the client-side behaviors described above (such as leaving user input in string form if precision would be lost) are active by default.

    In addition, if `dataSource.dataFormat:"xml"` is used, values that would lose precision remain as strings. For JSON, if behavior similar to `stringInBrowser` is desired, your server response must send the values as JSON strings rather than JSON numeric literals.

    You can use `defaultStringInBrowser` to disable these behaviors. NOTE: don't use this setting if you are using the Smart GWT Server, use the server.properties approach described above instead.

    Parameters:
      `stringInBrowser` - New stringInBrowser value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getStringInBrowser

    public Boolean getStringInBrowser()
    Server-side setting that causes values for fields of type "integer" or "float" to be represented as Strings when delivered to a web browser, in order to avoid mangling values which cannot be represented faithfully in JavaScript.

    JavaScript has a single "Number" type which internally stores numbers in a format equivalent to Java's "Double" - double-precision floating point. This means it cannot represent the full range of Java's Long type: Java Longs can represent integral values between -2^63 to 2^63-1, whereas JavaScript Number can only represent exact integer values between -2^53 and 2^53. Similarly, JavaScript's Number type cannot represent Java's unlimited-size BigInteger or unlimited-precision BigDecimal objects at all.

    The `stringInBrowser` setting can be used to deliver numeric values as Strings to the browser. This is intended to allow read-only display and successful round-tripping of the numeric value, however, it will not cause number-oriented features such as `SpinnerItem`, `Slider`, `ListGrid summaries` or range-checking `validators` or `criteria` to actually work.

    If `stringInBrowser` is not set, the default behavior is configured by `DataSource.stringInBrowser` on the owning DataSource if set, otherwise by the `server.properties` setting `datasource.defaultStringInBrowser`. If this flag is false, numeric values are delivered to the client as numbers, even where this will lead to a loss of precision. If the flag is true (which is the default), the behavior is to prevent range overflow for numeric values:

    - Java values of type Long, BigInteger and BigDecimal will be delivered as String only if they exceed JavaScript's number range.
    - Client-side validation will allow inputs that are outside of JavaScript's normal integer range, and such numbers will remain as Strings after validation, instead of being converted to Numbers
    - Values submitted to the server will be converted to BigInteger if they exceed the range of Java's Long type. This happens during DSRequest validation, before any defined `DMI methods` are called.

    This default set of behaviors is intended to automatically deal with cases like numeric `primaryKey` or `foreignKey` values that are never used as numbers, but happen to use the full Java Long range. To disable the above behaviors, set `stringInBrowser="false"`.

    If `stringInBrowser` is explicitly set to true:

    - the value for the field will always be delivered to the browser as a String (no attempt is made to detect the value as out of range / too high precision)
    - client-side validation will do a check for valid format only, and always leave the value as a String. Numeric range validators are ignored client-side (always pass), but are still active server-side.
    - AdvancedCriteria `operators` that check if values are in a particular range will always pass
    - the field is treated as though `canFilter:false` were set, to avoid showing non-functional search interfaces to the user. Set `canFilter="true"` to avoid this effect

    This setting is recommended for presenting out-of-range issues or precision loss on fields that represent actual quantities (as opposed to primaryKey or foreignKey fields, which really represent IDs). To ensure unlimited-precision BigDecimal values are preserved, you should also set `javaClass`.

    Note that responses delivered as JSON or XML, such as responses from the `RESTHandler servlet`, are not affected. This setting applies only to responses delivered to a web browser.

    The entirety of stringInBrowser processing can be completely disabled by setting `server.properties` flag `datasource.disableStringInBrowser` to true. This will cause all numeric values to be delivered as numbers without even attempting to detect if this will lead to a loss of precision. This setting overrides both the `stringInBrowser` field setting and the `datasource.defaultStringInBrowser server.properties` flag.

    `stringInBrowser` and client-side DataSources

    For DataSources that are not based on the Smart GWT Server, the client-side behaviors described above (such as leaving user input in string form if precision would be lost) are active by default.

    In addition, if `dataSource.dataFormat:"xml"` is used, values that would lose precision remain as strings. For JSON, if behavior similar to `stringInBrowser` is desired, your server response must send the values as JSON strings rather than JSON numeric literals.

    You can use `defaultStringInBrowser` to disable these behaviors. NOTE: don't use this setting if you are using the Smart GWT Server, use the server.properties approach described above instead.

    Returns:
      Current stringInBrowser value. Default value is null

  - ### setSummaryValueTitle

    public DataSourceField setSummaryValueTitle(String summaryValueTitle)
    Title to show in a `Summary of type "title"` for this field. If unspecified `title` summaries will show the `title` for the field.
    Parameters:
      `summaryValueTitle` - New summaryValueTitle value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getSummaryValueTitle

    public String getSummaryValueTitle()
    Title to show in a `Summary of type "title"` for this field. If unspecified `title` summaries will show the `title` for the field.
    Returns:
      Current summaryValueTitle value. Default value is null

  - ### setTarget

    public DataSourceField setTarget(String target)
    For fields of `type` "link", specifies the target window for the link. The value is passed as the `target` attribute of the anchor tag used to render the link. Typical values include "_blank" to open in a new window/tab, "_self" for the current window, or "_parent" for the parent frame.

    This can be overridden at the component level via `ListGridField.target` or `DetailViewerField.target`.

    Parameters:
      `target` - New target value. Default value is "_blank"
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setType(com.smartgwt.client.types.FieldType)`
      - `ListGridField.setTarget(java.lang.String)`
      - `DetailViewerField.setTarget(java.lang.String)`

  - ### getTarget

    public String getTarget()
    For fields of `type` "link", specifies the target window for the link. The value is passed as the `target` attribute of the anchor tag used to render the link. Typical values include "_blank" to open in a new window/tab, "_self" for the current window, or "_parent" for the parent frame.

    This can be overridden at the component level via `ListGridField.target` or `DetailViewerField.target`.

    Returns:
      Current target value. Default value is "_blank"
    See Also:
      - `getType()`
      - `ListGridField.getTarget()`
      - `DetailViewerField.getTarget()`

  - ### setTemplate

    public DataSourceField setTemplate(String template)
    If `field.template` is set, this field's value in records will be calculated dynamically via the specified `template`.

    This property may be set to a valid `template expression`.

    For example a composite field for a dataSource of citation references containing "volume", "issue", and "pages" fields might use the following template:

          <field name="compositeLocation" title="Volume (issue), pages">
               <template>#{volume} (#{issue}), #{pages}</template>
          </field>

    [This example might produce output like `"12 (5), 121-137"`].

    For SQL DataSources, values are calculated on the server by modifying the generated SQL request as appropriate. As with other `dynamically calculated` fields, fields with a specified template are non editable.
    When records are displayed in `dataBoundComponents that support editing`, template field values will be re-calculated dynamically on the client as the user edits a record, so a user may preview the result of their changes.

    Note that `template` fields may make use of `formula fields`, `fields included from related dataSources` `aggregated values from related dataSources`, and `fields derived via customSQL`.

    `DataSourceField.template` is supported for `SQL DataSources`, and for `clientOnly dataSources` only.

    DataSourceField.formula is available with Power or better licenses only. See smartclient.com/product for details.

    Parameters:
      `template` - New template value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getTemplate

    public String getTemplate()
    If `field.template` is set, this field's value in records will be calculated dynamically via the specified `template`.

    This property may be set to a valid `template expression`.

    For example a composite field for a dataSource of citation references containing "volume", "issue", and "pages" fields might use the following template:

          <field name="compositeLocation" title="Volume (issue), pages">
               <template>#{volume} (#{issue}), #{pages}</template>
          </field>

    [This example might produce output like `"12 (5), 121-137"`].

    For SQL DataSources, values are calculated on the server by modifying the generated SQL request as appropriate. As with other `dynamically calculated` fields, fields with a specified template are non editable.
    When records are displayed in `dataBoundComponents that support editing`, template field values will be re-calculated dynamically on the client as the user edits a record, so a user may preview the result of their changes.

    Note that `template` fields may make use of `formula fields`, `fields included from related dataSources` `aggregated values from related dataSources`, and `fields derived via customSQL`.

    `DataSourceField.template` is supported for `SQL DataSources`, and for `clientOnly dataSources` only.

    DataSourceField.formula is available with Power or better licenses only. See smartclient.com/product for details.

    Returns:
      Current template value. Default value is null

  - ### setTimeFormatter

    public DataSourceField setTimeFormatter(TimeDisplayFormat timeFormatter)
    Preferred time-format to apply to date type values within this field. If this property is specified on a field displayed within a dataBound component such as a `ListGrid` or `DynamicForm`, any dates displayed in this field will be formatted as times using the appropriate format.

    This is most commonly only applied to fields specified as type `"time"` though if no explicit `FormItem.dateFormatter` is specified it will be respected for other fields as well.

    See `ListGridField.timeFormatter` and `FormItem.timeFormatter` for more information.

    Note : This is an advanced setting

    Parameters:
      `timeFormatter` - New timeFormatter value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Appearance overview and related methods`

  - ### getTimeFormatter

    public TimeDisplayFormat getTimeFormatter()
    Preferred time-format to apply to date type values within this field. If this property is specified on a field displayed within a dataBound component such as a `ListGrid` or `DynamicForm`, any dates displayed in this field will be formatted as times using the appropriate format.

    This is most commonly only applied to fields specified as type `"time"` though if no explicit `FormItem.dateFormatter` is specified it will be respected for other fields as well.

    See `ListGridField.timeFormatter` and `FormItem.timeFormatter` for more information.

    Returns:
      Current timeFormatter value. Default value is null
    See Also:
      - `Appearance overview and related methods`

  - ### setTitle

    public DataSourceField setTitle(String title)
    Default user-visible title for this field.

    This will be picked up by `DataBoundComponent`s and other views over this data source.

    Note this property frequently does not need to be set since `DataSource.autoDeriveTitles` (on by default) usually picks an appropriate user-visible title if you have a reasonable naming convention for your field names.

    Note that if this field is being displayed in a `ListGrid` bound to this data source, the `ListGridField.headerTitle` attribute may be used to specify a different string for display in the column header.

    Overrides:
      `setTitle` in class `Field`
    Parameters:
      `title` - New title value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Field.setExportTitle(java.lang.String)`
      - `HTMLString`
      - `Component Binding`

  - ### getTitle

    public String getTitle()
    Default user-visible title for this field.

    This will be picked up by `DataBoundComponent`s and other views over this data source.

    Note this property frequently does not need to be set since `DataSource.autoDeriveTitles` (on by default) usually picks an appropriate user-visible title if you have a reasonable naming convention for your field names.

    Note that if this field is being displayed in a `ListGrid` bound to this data source, the `ListGridField.headerTitle` attribute may be used to specify a different string for display in the column header.

    Overrides:
      `getTitle` in class `Field`
    Returns:
      Current title value. Default value is null
    See Also:
      - `Field.getExportTitle()`
      - `HTMLString`
      - `Component Binding`

  - ### setType

    public DataSourceField setType(FieldType type)
    Type of this field. Required for all DataSource fields.

    Field type may imply automatic validators (for example, an integer field cannot accept the value "foo"). Field type also affects the default behaviors of DataBound components, for example, if a field is declared as type "date", components that edit that field will automatically choose a date-editing interface with pop-up date picker.

    Parameters:
      `type` - New type value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### setTypeDiscriminator

    public DataSourceField setTypeDiscriminator(String typeDiscriminator)
    For use in `ComponentSchema`, names another field on the same schema whose current value determines the effective type/schema of this field.

    This is used when a field's shape cannot be fully described until a sibling "selector" field has been assigned - for example, a Workflow step's configuration depends on which operation was chosen for that step, so the configuration field's real schema is only meaningful once the operation field has a value.

    `DataSource.asJSONSchema()` can omit discriminated fields of complex (DataSource) type via `JSONSchemaSettings.omitDiscriminatedFields`, so a consumer that must pick a discriminator value before the discriminated field's schema can be resolved is not shown a combined schema for every possible value at once.

    Parameters:
      `typeDiscriminator` - New typeDiscriminator value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Schema`

  - ### getTypeDiscriminator

    public String getTypeDiscriminator()
    For use in `ComponentSchema`, names another field on the same schema whose current value determines the effective type/schema of this field.

    This is used when a field's shape cannot be fully described until a sibling "selector" field has been assigned - for example, a Workflow step's configuration depends on which operation was chosen for that step, so the configuration field's real schema is only meaningful once the operation field has a value.

    `DataSource.asJSONSchema()` can omit discriminated fields of complex (DataSource) type via `JSONSchemaSettings.omitDiscriminatedFields`, so a consumer that must pick a discriminator value before the discriminated field's schema can be resolved is not shown a combined schema for every possible value at once.

    Returns:
      Current typeDiscriminator value. Default value is null
    See Also:
      - `Component Schema`

  - ### setUpdateWhen

    public DataSourceField setUpdateWhen(AdvancedCriteria updateWhen)
    Criteria-based control for field settability on update operations. The field can be set during an update when criteria match. On add operations, the field is always read-only (like `canUpdate:false`).

    On the server, if the operation is an add, or the criteria do not match on an update, the field value is stripped.

    Parameters:
      `updateWhen` - New updateWhen value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setInitWhen(com.smartgwt.client.data.AdvancedCriteria)`
      - `Component Binding`

  - ### getUpdateWhen

    public AdvancedCriteria getUpdateWhen()
    Criteria-based control for field settability on update operations. The field can be set during an update when criteria match. On add operations, the field is always read-only (like `canUpdate:false`).

    On the server, if the operation is an add, or the criteria do not match on an update, the field value is stripped.

    Returns:
      Current updateWhen value. Default value is null
    See Also:
      - `getInitWhen()`
      - `Component Binding`

  - ### setUploadFieldName

    public DataSourceField setUploadFieldName(String uploadFieldName)
    Used by the `BatchUploader` to map a field in an upload file to this dataSourceField. This is only necessary if the dataSourceField's name and title differ from the name of the field in the upload file (Smart GWT will automatically map upload fields using the dataSourceField's title, if possible, if it does not get a direct match on field name).
    Parameters:
      `uploadFieldName` - New uploadFieldName value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getUploadFieldName

    public String getUploadFieldName()
    Used by the `BatchUploader` to map a field in an upload file to this dataSourceField. This is only necessary if the dataSourceField's name and title differ from the name of the field in the upload file (Smart GWT will automatically map upload fields using the dataSourceField's title, if possible, if it does not get a direct match on field name).
    Returns:
      Current uploadFieldName value. Default value is null

  - ### setUseLocalDisplayFieldValue

    public DataSourceField setUseLocalDisplayFieldValue(Boolean useLocalDisplayFieldValue)
    The `FormItem.useLocalDisplayFieldValue` attribute may be specified within a dataSource configuration.

    This property governs whether, when displaying a record in an editor component, the `displayField` value for this field should be picked up directly from the record value (as opposed to being retrieved via an explicit fetch operation against the `FormItem.optionDataSource`). See `FormItem.useLocalDisplayFieldValue` for further details.

    If not explicitly set, dataSources backed by the `Smart GWT server` will set this property to true automatically for fields where the specified `displayField` values are retrieved from another dataSource using the `includeFrom` feature.

    Parameters:
      `useLocalDisplayFieldValue` - New useLocalDisplayFieldValue value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getUseLocalDisplayFieldValue

    public Boolean getUseLocalDisplayFieldValue()
    The `FormItem.useLocalDisplayFieldValue` attribute may be specified within a dataSource configuration.

    This property governs whether, when displaying a record in an editor component, the `displayField` value for this field should be picked up directly from the record value (as opposed to being retrieved via an explicit fetch operation against the `FormItem.optionDataSource`). See `FormItem.useLocalDisplayFieldValue` for further details.

    If not explicitly set, dataSources backed by the `Smart GWT server` will set this property to true automatically for fields where the specified `displayField` values are retrieved from another dataSource using the `includeFrom` feature.

    Returns:
      Current useLocalDisplayFieldValue value. Default value is null

  - ### setValidationCheckClientCaches

    public DataSourceField setValidationCheckClientCaches(Boolean validationCheckClientCaches)
    Per-field control for client-side cache lookup when evaluating ServerDynamicCriteria references (relational and aggregation). When `false`, the client skips cache lookup for this field's `*When` criteria and defers entirely to the server. When `null` (default), inherits from `DataSource.validationCheckClientCaches`.
    Parameters:
      `validationCheckClientCaches` - New validationCheckClientCaches value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `DataSource.setValidationCheckClientCaches(java.lang.Boolean)`

  - ### getValidationCheckClientCaches

    public Boolean getValidationCheckClientCaches()
    Per-field control for client-side cache lookup when evaluating ServerDynamicCriteria references (relational and aggregation). When `false`, the client skips cache lookup for this field's `*When` criteria and defers entirely to the server. When `null` (default), inherits from `DataSource.validationCheckClientCaches`.
    Returns:
      Current validationCheckClientCaches value. Default value is null
    See Also:
      - `DataSource.getValidationCheckClientCaches()`

  - ### setValidators

    public DataSourceField setValidators(Validator... validators)
    Validators to be applied to this field.

    Validators are applied whenever there is an attempt to save changes to a field.

    For the available set of built-in validators, and how to define a custom validator, see the `Validator` class.

    Parameters:
      `validators` - New validators value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Validator`
      - `Validation overview and related methods`

  - ### getValidators

    public Validator[] getValidators()
    Validators to be applied to this field.

    Validators are applied whenever there is an attempt to save changes to a field.

    For the available set of built-in validators, and how to define a custom validator, see the `Validator` class.

    Returns:
      Current validators value. Default value is null
    See Also:
      - `Validator`
      - `Validation overview and related methods`

  - ### setValidOperators

    public DataSourceField setValidOperators(OperatorId... validOperators)
    Set of search-operators valid for this field.

    If not specified, all operators that are valid for the field type are allowed.

    Parameters:
      `validOperators` - New validOperators value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Advanced Filtering`

  - ### getValidOperators

    public OperatorId[] getValidOperators()
    Set of search-operators valid for this field.

    If not specified, all operators that are valid for the field type are allowed.

    Returns:
      Current validOperators value. Default value is null
    See Also:
      - `Advanced Filtering`

  - ### setValueMap

    public DataSourceField setValueMap(Map valueMap)
    A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.

    The valueMap can be specified as either an Array of legal values, or as an `Object` where each property maps a stored value to a user-displayable value.

    To enforce that a field should be constrained to only the values in the valueMap, either declare `field.type` as "enum", or use a `ValidatorType` of "isOneOf" with explicitly listed values. Otherwise, although a normal `SelectItem` control will only allow values from the valueMap to be entered, other controls such as a `ComboBox` will allow other values to be entered.

    In XML, a valueMap that specifies only a list of legal values is specified as follows:

            <valueMap>
             <value>Pens & Pencils</value>
             <value>Stationery</value>
             <value>Computer Products</value>
             <value>Furniture</value>
             <value>Misc</value>
            </valueMap>

    A ValueMap that specifies stored values mapped to user-visible values is specified as follows:

            <valueMap>
             <value ID="1">Pens & Pencils</value>
             <value ID="2">Stationery</value>
             <value ID="3">Computer Products</value>
             <value ID="4">Furniture</value>
             <value ID="5">Misc</value>
            </valueMap>

    Overrides:
      `setValueMap` in class `Field`
    Parameters:
      `valueMap` - New valueMap value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### getValueMap

    public Map getValueMap()
    A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.

    The valueMap can be specified as either an Array of legal values, or as an `Object` where each property maps a stored value to a user-displayable value.

    To enforce that a field should be constrained to only the values in the valueMap, either declare `field.type` as "enum", or use a `ValidatorType` of "isOneOf" with explicitly listed values. Otherwise, although a normal `SelectItem` control will only allow values from the valueMap to be entered, other controls such as a `ComboBox` will allow other values to be entered.

    In XML, a valueMap that specifies only a list of legal values is specified as follows:

            <valueMap>
             <value>Pens & Pencils</value>
             <value>Stationery</value>
             <value>Computer Products</value>
             <value>Furniture</value>
             <value>Misc</value>
            </valueMap>

    A ValueMap that specifies stored values mapped to user-visible values is specified as follows:

            <valueMap>
             <value ID="1">Pens & Pencils</value>
             <value ID="2">Stationery</value>
             <value ID="3">Computer Products</value>
             <value ID="4">Furniture</value>
             <value ID="5">Misc</value>
            </valueMap>

    Overrides:
      `getValueMap` in class `Field`
    Returns:
      Current valueMap value. Default value is null

  - ### setValueOperation

    public DataSourceField setValueOperation(String valueOperation)
    Note: Currently, this feature only works with `SQL DataSources`

    This property allows you to name an `operationBinding` on a `related DataSource` that should be executed to obtain a value for this field. The format of the property is

               dataSourceId.operationId.fieldName

    The `fieldName` is used to disambiguate in case the operation returns more than one value and it is required, even if the operation only returns a single field

    Typically, `valueOperation` names an operation that uses a `summaryFunction` to produce a single aggregated value from a DataSource with a one-to-many or many-to-many relation with this DataSource. Some examples of when `valueOperation` is appropriate:

    - To obtain a total order value from the OrderLines on an Order
    - To obtain the number of Employees reporting to a given manager
    - To obtain the date of the most recent Order for a given Customer
    - To obtain the average population of all Cities in a given Country
    Note, Smart GWT will convert the sub-operation into inline SQL, for maximum efficiency.

    Because `valueOperations` are deriving a simple field value for a single field, they should return a single scalar value of the same type as the field. Note that the requirement to return a single record is a strict one: with most databases, failing to observe it will result in a SQL error, because most databases do not allow row limiting in the kind of subqueries we generate to implement `valueOperation` - so-called correlated scalar subqueries. MySQL is an exception in this, and with that one database we do limit the subquery to 1 row; but it is still better to ensure that the subquery can only return a single row (note, all `SummaryFunctionType`s automatically return a single value)

    However, we do tolerate data type discrepancies; in cases where the data types do not match, we attempt the most obvious conversion. For example, if the `valueOperation` field is of type "boolean" but the operation returns a number, we will convert 0 to false and any other number to true; this allows you to create boolean "virtual fields" that answer questions like "Has this Employee booked any orders this month?". With other data types, we will stringify the response value (if the field type is `text`), or parse the result of calling `toString()` on the response object (if the field is of a numeric type).

    NOTE: Although `valueOperation` can be used to derive any singular value from any related dataSource, it is intended primarily as a mechanism for including summarized values across one-to-many or many-to-many relations. In cases where you want to go "the other way" and derive a value across a many-to-one or one-to-one relation, you would generally use `includeFrom`, which is conceptually simpler and more direct.

    Note : This is an advanced setting

    Parameters:
      `valueOperation` - New valueOperation value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `AdvancedCriterionSubquery`
      - `DataSourceField.includeFrom`
      - `OperationBinding.summaryFunctions`

  - ### getValueOperation

    public String getValueOperation()
    Note: Currently, this feature only works with `SQL DataSources`

    This property allows you to name an `operationBinding` on a `related DataSource` that should be executed to obtain a value for this field. The format of the property is

               dataSourceId.operationId.fieldName

    The `fieldName` is used to disambiguate in case the operation returns more than one value and it is required, even if the operation only returns a single field

    Typically, `valueOperation` names an operation that uses a `summaryFunction` to produce a single aggregated value from a DataSource with a one-to-many or many-to-many relation with this DataSource. Some examples of when `valueOperation` is appropriate:

    - To obtain a total order value from the OrderLines on an Order
    - To obtain the number of Employees reporting to a given manager
    - To obtain the date of the most recent Order for a given Customer
    - To obtain the average population of all Cities in a given Country
    Note, Smart GWT will convert the sub-operation into inline SQL, for maximum efficiency.

    Because `valueOperations` are deriving a simple field value for a single field, they should return a single scalar value of the same type as the field. Note that the requirement to return a single record is a strict one: with most databases, failing to observe it will result in a SQL error, because most databases do not allow row limiting in the kind of subqueries we generate to implement `valueOperation` - so-called correlated scalar subqueries. MySQL is an exception in this, and with that one database we do limit the subquery to 1 row; but it is still better to ensure that the subquery can only return a single row (note, all `SummaryFunctionType`s automatically return a single value)

    However, we do tolerate data type discrepancies; in cases where the data types do not match, we attempt the most obvious conversion. For example, if the `valueOperation` field is of type "boolean" but the operation returns a number, we will convert 0 to false and any other number to true; this allows you to create boolean "virtual fields" that answer questions like "Has this Employee booked any orders this month?". With other data types, we will stringify the response value (if the field type is `text`), or parse the result of calling `toString()` on the response object (if the field is of a numeric type).

    NOTE: Although `valueOperation` can be used to derive any singular value from any related dataSource, it is intended primarily as a mechanism for including summarized values across one-to-many or many-to-many relations. In cases where you want to go "the other way" and derive a value across a many-to-one or one-to-one relation, you would generally use `includeFrom`, which is conceptually simpler and more direct.

    Returns:
      Current valueOperation value. Default value is null
    See Also:
      - `AdvancedCriterionSubquery`
      - `DataSourceField.includeFrom`
      - `OperationBinding.summaryFunctions`

  - ### setValueXPath

    public DataSourceField setValueXPath(String valueXPath)
    XPath expression used to retrieve the field's value.

    This XPath expression will be evaluated in the scope of the record objects selected by the `DataSource.recordXPath`. For XML data (`dataFormat:"xml"`) this means a call to `XMLTools.selectString()` passing the selected XML element. For JSON data (`dataFormat:"json"`), this means a call to `XMLTools.selectObjects()` passing the selected JSON object.

    In the absence of a `valueXPath`, for JSON data the value for the field will be the value of the same-named property in the record object selected by `recordXPath`.

    For XML data, the value will be the attribute or subelement named after the field name. For example, for a field "author" on a record element <book>, the following structures require no valueXPath:

             <book author="Mark Jones"/>

             <book>
                 <author>Mark Jones</author>
             </book>

    If `valueXPath` is not required for your field because of the default handling described above, don't specify it, as it's slightly slower.

    To learn about XPath, try the following search: http://www.google.com/search?q=xpath+tutorial

    Using valueXPath with the Smart GWT server

    If you're using the Smart GWT server to return data via the DSResponse object (or indirectly doing so using DataSource DMI), the valueXPath you specify on the DataSource fields will be applied to the data you return via the JXPath library.
    See also the server side Java APIs `DataSource.setProperties()` and `DSResponse.setData()`.

    If you are returning Java Beans as your DSResponse data, normally each dataSource field receives the value of the same-named Java Bean property, that is, a field "zipCode" is populated by looking for "getZipCode()" on the objects passed as DSResponse data. You can use `valueXPath` to retrieve properties from subobjects, so long as a chain of getter methods exists that corresponds to the valueXPath. For example, a valueXPath of "address/zipCode" expects to call "getAddress()" on the bean(s) passed to DSResponse.setData(), followed by "getZipCode()" on whatever object "getAddress()" returns.

    When you are saving data, the inbound DSRequest values, available as a Java Map, will use just dataSource field names as Map keys, not the valueXPath used to derive them. However, to achieve bidirectional valueXPath binding, you can use the server-side method dataSource.setProperties() to use the valueXPath when setting properties on your server object model. When applied as a setter, an XPath like "address/zipCode" attempts "getAddress()" followed by "setZipCode()" on the returned object. JXPath also has some ability to auto-create intervening objects if they are missing, such as auto-creating an "address" subobject when applying "address/zipCode" as a valueXPath.

    See the JXPath library documentation for complete details, including other types of server object models supported, such as server-side XML.

    Parameters:
      `valueXPath` - New valueXPath value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `XPathExpression`
      - `Client-side Data Integration`
      - XPath Binding Example

  - ### getValueXPath

    public String getValueXPath()
    XPath expression used to retrieve the field's value.

    This XPath expression will be evaluated in the scope of the record objects selected by the `DataSource.recordXPath`. For XML data (`dataFormat:"xml"`) this means a call to `XMLTools.selectString()` passing the selected XML element. For JSON data (`dataFormat:"json"`), this means a call to `XMLTools.selectObjects()` passing the selected JSON object.

    In the absence of a `valueXPath`, for JSON data the value for the field will be the value of the same-named property in the record object selected by `recordXPath`.

    For XML data, the value will be the attribute or subelement named after the field name. For example, for a field "author" on a record element <book>, the following structures require no valueXPath:

             <book author="Mark Jones"/>

             <book>
                 <author>Mark Jones</author>
             </book>

    If `valueXPath` is not required for your field because of the default handling described above, don't specify it, as it's slightly slower.

    To learn about XPath, try the following search: http://www.google.com/search?q=xpath+tutorial

    Using valueXPath with the Smart GWT server

    If you're using the Smart GWT server to return data via the DSResponse object (or indirectly doing so using DataSource DMI), the valueXPath you specify on the DataSource fields will be applied to the data you return via the JXPath library.
    See also the server side Java APIs `DataSource.setProperties()` and `DSResponse.setData()`.

    If you are returning Java Beans as your DSResponse data, normally each dataSource field receives the value of the same-named Java Bean property, that is, a field "zipCode" is populated by looking for "getZipCode()" on the objects passed as DSResponse data. You can use `valueXPath` to retrieve properties from subobjects, so long as a chain of getter methods exists that corresponds to the valueXPath. For example, a valueXPath of "address/zipCode" expects to call "getAddress()" on the bean(s) passed to DSResponse.setData(), followed by "getZipCode()" on whatever object "getAddress()" returns.

    When you are saving data, the inbound DSRequest values, available as a Java Map, will use just dataSource field names as Map keys, not the valueXPath used to derive them. However, to achieve bidirectional valueXPath binding, you can use the server-side method dataSource.setProperties() to use the valueXPath when setting properties on your server object model. When applied as a setter, an XPath like "address/zipCode" attempts "getAddress()" followed by "setZipCode()" on the returned object. JXPath also has some ability to auto-create intervening objects if they are missing, such as auto-creating an "address" subobject when applying "address/zipCode" as a valueXPath.

    See the JXPath library documentation for complete details, including other types of server object models supported, such as server-side XML.

    Returns:
      Current valueXPath value. Default value is null
    See Also:
      - `XPathExpression`
      - `Client-side Data Integration`
      - XPath Binding Example

  - ### setVisibleWhen

    public DataSourceField setVisibleWhen(AdvancedCriteria visibleWhen)
    Criteria-based field visibility for server responses. When the criteria do not match, the field value is stripped from the server response — the client never receives it. This is the criteria-based equivalent of `viewRequiresRole`.

    On the client, `visibleWhen` already works as a `FormItem` property via the RulesEngine (shows/hides UI). Adding it to DataSourceField extends that behavior to the server: the field is hidden in UI and stripped from data.

    Criteria are evaluated per record in the response, so record-dependent criteria work — for example, showing a field only when the record's department matches the current user's department.

    Supports the full ServerDynamicCriteria syntax, including references to the current user, operation type, and fields on related DataSources.

    Example — salary visible only to HR users:

          <field name="salary" type="float">
            <visibleWhen fieldName="auth.roles" operator="contains"
                         value="HR"/>
          </field>

    Parameters:
      `visibleWhen` - New visibleWhen value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `DataSourceField.viewRequiresRole`
      - `Component Binding`

  - ### getVisibleWhen

    public AdvancedCriteria getVisibleWhen()
    Criteria-based field visibility for server responses. When the criteria do not match, the field value is stripped from the server response — the client never receives it. This is the criteria-based equivalent of `viewRequiresRole`.

    On the client, `visibleWhen` already works as a `FormItem` property via the RulesEngine (shows/hides UI). Adding it to DataSourceField extends that behavior to the server: the field is hidden in UI and stripped from data.

    Criteria are evaluated per record in the response, so record-dependent criteria work — for example, showing a field only when the record's department matches the current user's department.

    Supports the full ServerDynamicCriteria syntax, including references to the current user, operation type, and fields on related DataSources.

    Example — salary visible only to HR users:

          <field name="salary" type="float">
            <visibleWhen fieldName="auth.roles" operator="contains"
                         value="HR"/>
          </field>

    Returns:
      Current visibleWhen value. Default value is null
    See Also:
      - `DataSourceField.viewRequiresRole`
      - `Component Binding`

  - ### setXmlAttribute

    public DataSourceField setXmlAttribute(Boolean xmlAttribute)
    Indicates that `DataSource.xmlSerialize()` should serialize this value as an XML attribute.

    Note this does not need to be declared in order for DataSource records to be derived from XML data: a field will be populated with either an attribute or subelement with matching name.

    Parameters:
      `xmlAttribute` - New xmlAttribute value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `Component Schema`

  - ### getXmlAttribute

    public Boolean getXmlAttribute()
    Indicates that `DataSource.xmlSerialize()` should serialize this value as an XML attribute.

    Note this does not need to be declared in order for DataSource records to be derived from XML data: a field will be populated with either an attribute or subelement with matching name.

    Returns:
      Current xmlAttribute value. Default value is null
    See Also:
      - `Component Schema`

  - ### setType

    public void setType(SimpleType type)
    Set the type directly to a defined SimpleType.
    Parameters:
      `type` - the SimpleType

  - ### setValueMap

    public DataSourceField setValueMap(String... valueMap)
    A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.

    The valueMap can be specified as either an Array of legal values, or as an `Object` where each property maps a stored value to a user-displayable value.

    To enforce that a field should be constrained to only the values in the valueMap, either declare `field.type` as "enum", or use a `ValidatorType` of "isOneOf" with explicitly listed values. Otherwise, although a normal `SelectItem` control will only allow values from the valueMap to be entered, other controls such as a `ComboBox` will allow other values to be entered.

    In XML, a valueMap that specifies only a list of legal values is specified as follows:

            <valueMap>
             <value>Pens & Pencils</value>
             <value>Stationery</value>
             <value>Computer Products</value>
             <value>Furniture</value>
             <value>Misc</value>
            </valueMap>

    A ValueMap that specifies stored values mapped to user-visible values is specified as follows:

            <valueMap>
             <value ID="1">Pens & Pencils</value>
             <value ID="2">Stationery</value>
             <value ID="3">Computer Products</value>
             <value ID="4">Furniture</value>
             <value ID="5">Misc</value>
            </valueMap>

    Parameters:
      `valueMap` - New valueMap value. Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls

  - ### setEditorProperties

    public void setEditorProperties(FormItem editorProperties)
    Set the default `FormItem` properties to be used whenever this field is edited (whether in a grid, form, or other component).

    If unset, a FormItem will be automatically chosen based on the type of the field.

    Methods by this same name are available on `SimpleType`, `FormItem`, and `ListGridField`, where in each case they provide a way to configure the FormItem that will be used to edit the type, or field. If a field is picked up directly from the DataSource, due to a setting like `useAllDataSourceFields`, then the edit FormItem configuration from this method call on the DataSource will be used. However, if a `DataBoundComponent` field is defined, the edit FormItem configuration applied at the `FormItem` or `ListGridField` level will have priority. Otherwise, if none of these have been set, we fall back to the edit FormItem configuration set on the field's `SimpleType`.

    Note: The FormItem passed to setEditorProperties() is used as a "template" to create a FormItem whenever a `DataBoundComponent` needs to show an interface for editing this field. This means you need to follow special rules:

    1. In event handler code, you must obtain the current FormItem instance from the provided Event object via getItem(). You cannot make method calls via "this" or via implicit instance scope: both "clearValue()" and "this.clearValue()" need to be written as "item.clearValue()" instead (where "item" is the result of event.getItem()).
    2. To store custom instance variables, you must use FormItem.getAttribute()/setAttribute() (or their type-specific variants). You cannot store and retrieve instance variables via "this" - "this.someVariable = 5" will not work.
    3. You may not override superclass methods - your behaviors have to be implemented via event handlers
    4. If you create a custom subclass, the FormItem you receive in an event handler will be of a generic type and must be converted before you can call custom methods. Conversion is done via `new MyCustomItem(item.getJsObj());` (complete code sample below).
       Note that this conversion does not actually cause creation or rendering of a new widget and is comparable in cost to a typecast.

    Example code demonstrating using an eventHandler to call a method on custom subclass of TextItem:

         class MyCustomItem extends TextItem {
              MyCustomItem (JavaScriptObject config) {
              }

              MyCustomItem(String name) {
                  setInitHandler(new FormItemInitHandler() {
                      public void onInit(FormItem item) {
                          // correct
                          new MyCustomItem(item.getJsObj()).customMethod();

                          // incorrect, will throw an error
                          // ((MyCustomItem)item).customMethod();
                      }
                  }
              }

              void customMethod() { ... }
          }

          ...

          myDataSourceField.setEditorProperties(new MyCustomItem("field1"));

    As an alternative, you can use `setEditorType(java.lang.String)` or `setEditorType(java.lang.Class<? extends com.smartgwt.client.widgets.form.fields.FormItem>)` to avoid these limitations. The subclass you pass must be a built-in FormItem subclass, unless you've registered it with the `reflection mechanism`.

    Parameters:
      `editorProperties` - FormItem with default properties to be applied when editing

  - ### setEditorType

    public void setEditorType(FormItem editorType)
    Deprecated.
    Renamed to `setEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`. You can also consider using `setEditorType(java.lang.Class<? extends com.smartgwt.client.widgets.form.fields.FormItem>)` or `setEditorType(java.lang.String)` instead.
    Synonym for `setEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`.
    Parameters:
      `editorType` - FormItem with default properties to be applied when editing

  - ### setEditorType

    public void setEditorType(String editorType)
    Set the default `FormItem` class to be used whenever this field is edited (whether in a grid, form, or other component).

    If unset, a FormItem will be automatically chosen based on the type of the field.

    By using the `reflection mechanism`, this method avoids the limitations described in `setEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`. If the editorType cannot be resolved via reflection, this method will still work if editorType refers to a built-in SmartGWT framework class, such as `SetFilterItem`.

    Parameters:
      `editorType` - the fully-qualified class name of a `FormItem` subclass, which must have been registered with the `reflection mechanism` (except for built-in framework classes).
    Throws:
      `IllegalArgumentException` - if the editorType class has not been registered for use with the `reflection mechanism`, and it is not a built-in framework class, or if it does not inherit from `FormItem`.

  - ### setEditorType

    public void setEditorType(Class<? extends FormItem> editorType)
    Set the default `FormItem` class to be used whenever this field is edited (whether in a grid, form, or other component).

    If unset, a FormItem will be automatically chosen based on the type of the field.

    By using the `reflection mechanism`, this method avoids the limitations described in `setEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`. If the editorType cannot be resolved via reflection, this method will still work if editorType refers to a built-in SmartGWT framework class, such as `SetFilterItem`.

    Parameters:
      `editorType` - a `FormItem` subclass, which must have been registered with the `reflection mechanism` (except for built-in framework classes).
    Throws:
      `IllegalArgumentException` - if the editorType class has not been registered for use with the `reflection mechanism`, and it is not a built-in framework class, or if it does not inherit from `FormItem`.

  - ### setReadOnlyEditorType

    public void setReadOnlyEditorType(FormItem editorType)
    Deprecated.
    Renamed to `setReadOnlyEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`. You can also consider using `setReadOnlyEditorType(java.lang.Class<? extends com.smartgwt.client.widgets.form.fields.FormItem>)` or `setReadOnlyEditorType(java.lang.String)` instead.
    Synonym for `setReadOnlyEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`.
    Parameters:
      `editorType` - FormItem with properties to set when editing read-only values.

  - ### setReadOnlyEditorProperties

    public void setReadOnlyEditorProperties(FormItem editorProperties)
    Sets the default FormItem properties to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.

    This property may also be specified at the type level by specifying `SimpleType.setReadOnlyEditorType(FormItem)`.

    Note: The FormItem passed to setReadOnlyEditorProperties() is used as a "template" to create a FormItem whenever a `DataBoundComponent` needs to show an interface for editing this field (and the field is marked read-only).

    For an overview of the template rules, reflection requirements when trying to assign an edit Formitem by type, and an understanding of how the various `setReadOnlyEditorProperties()` calls on different classes relate to each other in determining what configuration ultimately gets applied to the edit FormItem, see `setEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`.

    Parameters:
      `editorProperties` - FormItem with properties to set when editing read-only values.
    See Also:
      - `setReadOnlyEditorType(String)`
      - `setReadOnlyEditorType(Class)`

  - ### setReadOnlyEditorType

    public void setReadOnlyEditorType(String editorType)
    Sets the default FormItem class to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.

    By using the `reflection mechanism`, this method avoids the limitations described in `setReadOnlyEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`. If the editorType cannot be resolved via reflection, this method will still work if editorType refers to a built-in SmartGWT framework class, such as `SetFilterItem`.

    Parameters:
      `editorType` - a `FormItem` subclass, which must have been registered with the `reflection mechanism` (except for built-in framework classes).
    Throws:
      `IllegalArgumentException` - if the editorType class has not been registered for use with the `reflection mechanism`, and it is not a built-in framework class, or if it does not inherit from `FormItem`.

  - ### setReadOnlyEditorType

    public void setReadOnlyEditorType(Class<? extends FormItem> editorType)
    Sets the default `FormItem` class to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.

    By using the `reflection mechanism`, this method avoids the limitations described in `setReadOnlyEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`. If the editorType cannot be resolved via reflection, this method will still work if editorType refers to a built-in SmartGWT framework class, such as `SetFilterItem`.

    Parameters:
      `editorType` - a `FormItem` subclass, which must have been registered with the `reflection mechanism` (except for built-in framework classes).
    Throws:
      `IllegalArgumentException` - if the editorType class has not been registered for use with the `reflection mechanism`, and it is not a built-in framework class, or if it does not inherit from `FormItem`.

  - ### setFilterEditorProperties

    public void setFilterEditorProperties(FormItem filterEditorProperties)
    Set the default `FormItem` properties to be used whenever this field if it appears in a `ListGrid` filter row, and `canFilter` is not false.

    If this is not specified, the formItem type may be derived from the `filterEditorType` property, or from the field's `type`.

    Note: The FormItem passed to `setFilterEditorProperties()` is used as a "template" to create a FormItem.

    For an overview of the template rules, reflection requirements when trying to assign an edit Formitem by type, and an understanding of how the various `setFilterEditorProperties()` calls on different classes relate to each other in determining what configuration ultimately gets applied to the edit FormItem, see `setEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`.

    Parameters:
      `filterEditorProperties` - FormItem with default properties to be applied
    See Also:
      - `setFilterEditorType(String)`
      - `setFilterEditorType(Class)`

  - ### setFilterEditorType

    public void setFilterEditorType(String filterEditorType)
    Set the default `FormItem` class to be used whenever this field appears in a `ListGrid` filter row or `SearchForm`.

    If unset, a FormItem will be automatically chosen based on the type of the field.

    By using the `reflection mechanism`, this method avoids the limitations described in `setFilterEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`. If the filterEditorType cannot be resolved via reflection, this method will still work if filterEditorType refers to a built-in SmartGWT framework class, such as `SetFilterItem`.

    Parameters:
      `filterEditorType` - the fully-qualified class name of a `FormItem` subclass, which must have been registered with the `reflection mechanism` (except for built-in framework classes).
    Throws:
      `IllegalArgumentException` - if the filterEditorType class has not been registered for use with the `reflection mechanism`, and it is not a built-in framework class, or if it does not inherit from `FormItem`.

  - ### setFilterEditorType

    public void setFilterEditorType(Class<? extends FormItem> filterEditorType)
    Set the default `FormItem` class to be used whenever this field appears in a `ListGrid` filter row or `SearchForm`.

    If unset, a FormItem will be automatically chosen based on the type of the field.

    By using the `reflection mechanism`, this method avoids the limitations described in `setFilterEditorProperties(com.smartgwt.client.widgets.form.fields.FormItem)`. If the filterEditorType cannot be resolved via reflection, this method will still work if filterEditorType refers to a built-in SmartGWT framework class, such as `SetFilterItem`.

    Parameters:
      `editorType` - a `FormItem` subclass, which must have been registered with the `reflection mechanism` (except for built-in framework classes).
    Throws:
      `IllegalArgumentException` - if the filterEditorType class has not been registered for use with the `reflection mechanism`, and it is not a built-in framework class, or if it does not inherit from `FormItem`.

  - ### setRootValue

    public void setRootValue(String rootValue)
    For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node. Defaults to null.
    Parameters:
      `rootValue` - rootValue Default value is null

  - ### setRootValue

    public void setRootValue(Integer rootValue)
    For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node. Defaults to null.
    Parameters:
      `rootValue` - rootValue Default value is null

  - ### setRootValue

    public void setRootValue(Float rootValue)
    For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node. Defaults to null.
    Parameters:
      `rootValue` - rootValue Default value is null

  - ### setFieldValueExtractor

    public void setFieldValueExtractor(FieldValueExtractor extractor)
    Function to retrieve the field's value from the XML element or JSON record returned from a web service.

    This is an advanced API for use when a `valueXPath` setting is insufficient to derive a field's value, yet an implementation of `DataSource.transformResponse(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest, java.lang.Object)` is overkill.

    Parameters:
      `extractor` - the field value extractor

  - ### setType

    public void setType(DataSource dataSource)
    Deprecated.
    use #setTypeAsDataSource
    The type can also be the another DataSource, which allows you to model nested structures such as XML documents (in fact, XMLTools.loadXMLSchema() models XML schema in this way). Nested DataSource declarations affect how XML and JSON data is deserialized into JavaScript objects in the client-side integration pipeline, so that you can load complex XML documents and have them deserialized into a correctly typed JavaScript object model.
    Parameters:
      `dataSource` - the data source

  - ### setTypeAsDataSource

    public void setTypeAsDataSource(DataSource dataSource)
    The type can also be the another DataSource, which allows you to model nested structures such as XML documents (in fact, XMLTools.loadXMLSchema() models XML schema in this way). Nested DataSource declarations affect how XML and JSON data is deserialized into JavaScript objects in the client-side integration pipeline, so that you can load complex XML documents and have them deserialized into a correctly typed JavaScript object model.
    Parameters:
      `dataSource` - the data source

  - ### getTypeAsDataSource

    public DataSource getTypeAsDataSource()
    Return the type of the assigned DataSource
    Returns:
      the DataSource

  - ### setSummaryFunction

    public void setSummaryFunction(SummaryFunctionType summaryFunction)
    If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an explicit `SummaryFunction` for calculating the summary value to display.
    Parameters:
      `summaryFunction` - summaryFunction Default value is null

  - ### setSummaryFunction

    public void setSummaryFunction(String summaryFunction)
    If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an summary function registered via `com.smartgwt.client.data.SimpleType#registerSummaryFunction()` for calculating the summary value to display.
    Parameters:
      `summaryFunction` - summaryFunction Default value is null

  - ### getSummaryFunction

    public SummaryFunctionType getSummaryFunction()
    If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an explicit `SummaryFunction` for calculating the summary value to display.
    Returns:
      SummaryFunctionType

  - ### setSummaryFunction

    public void setSummaryFunction(SummaryFunction summaryFunction)
    If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an explicit `SummaryFunction` for calculating the summary value to display.
    Parameters:
      `summaryFunction` - summaryFunction Default value is null

  - ### setImageHeight

    public void setImageHeight(Integer imageHeight)
    Height of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageHeight. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Parameters:
      `imageHeight` - imageHeight Default value is null

  - ### getImageHeight

    public Integer getImageHeight()
    Height of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageHeight. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Returns:
      Integer

  - ### setImageHeight

    public void setImageHeight(String imageHeight)
    Height of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageHeight. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Parameters:
      `imageHeight` - imageHeight Default value is null

  - ### getImageHeightAsString

    public String getImageHeightAsString()
    Height of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageHeight. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Returns:
      String

  - ### setImageSize

    public void setImageSize(Integer imageSize)
    Width and height of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageSize. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Parameters:
      `imageSize` - imageSize Default value is null

  - ### getImageSize

    public Integer getImageSize()
    Width and height of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageSize. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Returns:
      Integer

  - ### setImageSize

    public void setImageSize(String imageSize)
    Width and height of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageSize. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Parameters:
      `imageSize` - imageSize Default value is null

  - ### getImageSizeAsString

    public String getImageSizeAsString()
    Width and height of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageSize. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Returns:
      String

  - ### setImageWidth

    public void setImageWidth(Integer imageWidth)
    Width of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageWidth. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Parameters:
      `imageWidth` - imageWidth Default value is null

  - ### getImageWidth

    public Integer getImageWidth()
    Width of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageWidth. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Returns:
      Integer

  - ### setImageWidth

    public void setImageWidth(String imageWidth)
    Width of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageWidth. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Parameters:
      `imageWidth` - imageWidth Default value is null

  - ### getImageWidthAsString

    public String getImageWidthAsString()
    Width of the image-content of this field. If set as a string, represents the name of another field in the record that holds the imageWidth. Applicable only to fields of image type or fields that use a `ViewFileItem` as an editor.
    Returns:
      String

  - ### setPrompt

    public void setPrompt(String prompt)
    Causes a tooltip hover to appear on the header generated for this data source field (effectively sets `prompt` for the header).
    Parameters:
      `prompt` - prompt Default value is null

  - ### getPrompt

    public String getPrompt()
    Causes a tooltip hover to appear on the header generated for this field (effectively sets `prompt` for the header).
    Returns:
      String

  - ### setCanEdit

    public DataSourceField setCanEdit(Boolean canEdit)
    Controls whether, by default, dataBoundComponents consider this field editable.

    Set to `false` to draw this field read-only.

    This attribute may not effect all dataBoundComponents - the `canEditFieldAttribute` may be set at the component level to look for a different attribute on the dataSourceField, and components allow developers to explicitly override this default (see `canEdit`. `canEdit` for example).

    Note that this setting only prevents the user from modifying the field's value through the UI; the value can still be modified programmatically, and it will still be saved in the normal way. If you wish to prevent a field from being saved, use `canSave`:false instead (or in addition).

    Overrides:
      `setCanEdit` in class `Field`
    Parameters:
      `canEdit` - canEdit Default value is null
    Returns:
      `DataSourceField` instance, for chaining setter calls
    See Also:
      - `setCanFilter(java.lang.Boolean)`
      - `setCanSave(java.lang.Boolean)`
      - `ComponentBinding overview and related methods`

  - ### getCanEdit

    public Boolean getCanEdit()
    Controls whether, by default, dataBoundComponents consider this field editable.

    Set to `false` to draw this field read-only.

    This attribute may not effect all dataBoundComponents - the `canEditFieldAttribute` may be set at the component level to look for a different attribute on the dataSourceField, and components allow developers to explicitly override this default (see `canEdit`. `canEdit` for example).

    Note that this setting only prevents the user from modifying the field's value through the UI; the value can still be modified programmatically, and it will still be saved in the normal way. If you wish to prevent a field from being saved, use `canSave`:false instead (or in addition).

    Overrides:
      `getCanEdit` in class `Field`
    Returns:
      Boolean
    See Also:
      - `getCanFilter()`
      - `getCanSave()`
      - `ComponentBinding overview and related methods`

  - ### getTypeAsSimpleType

    public SimpleType getTypeAsSimpleType()
    Returns the type of this field as a SimpleType. If the type is a built-in type like "float" or "boolean", the returned object will be null.
    Returns:
      SimpleType

  - ### getType

    public FieldType getType()
    Type of this field. Required for all DataSource fields.

    Field type may imply automatic validators (for example, an integer field cannot accept the value "foo"). Field type also affects the default behaviors of DataBound components, for example, if a field is declared as type "date", components that edit that field will automatically choose a date-editing interface with pop-up date picker. If the type of this field is a DataSource type, the returned object will be null.

    Returns:
      FieldType
    See Also:
      - `Basics overview and related methods`