Package com.smartgwt.client.docs.serverds

# Class DataSourceField

java.lang.Object
com.smartgwt.client.docs.serverds.DataSourceField

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

This class is not meant to be created and used, it is actually documentation of settings allowed in a DataSource descriptor (.ds.xml file), for use with Smart GWT Pro Edition and above. See `com.smartgwt.client.docs.serverds` for how to use this documentation.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `Boolean`
  `allowClientRequestedSummaries`
  Affects whether client dsRequests can request summaries for this field.
  `FieldAuditMode`
  `audit`
  Determines when the field value should be saved to the audit DataSource when `auditing` is enabled.
  `Boolean`
  `autoGenerated`
  Indicates that values for this field are automatically generated by the database or ORM provider.
  `boolean`
  `autoQuoteCustomExpressions`
  If explicitly set to false, switches off automatic quoting and escaping of values in custom expressions that are derived from Velocity evaluations.
  `Boolean`
  `batchUploadCaseSensitive`
  Applies to the "fetch" operation that is used to look up key values for fields with `importStrategy.display` while importing data using `BatchUploader` or `DataImport` server-side API.
  `String`
  `batchUploadOperationId`
  Used to look up key values for fields with `importStrategy.display` while importing data using `BatchUploader` or `DataImport` server-side API.
  `Boolean`
  `canEdit`
  Controls whether, by default, DataBoundComponents consider this field editable.
  `Boolean`
  `canExport`
  Dictates whether the data in this field be exported.
  `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.
  `Boolean`
  `canSave`
  Whether values in this field can be updated and saved to the dataSource.
  `boolean`
  `canSortClientOnly`
  When true, this field can only be used for sorting if the data is entirely client-side.
  `Boolean`
  `canView`
  If false, this property indicates that this field is considered "server only".
  `Boolean`
  `childrenProperty`
  If true, this property indicates that this field will hold an explicit array of child nodes for the current node.
  `String`
  `childTagName`
  For a field that is `multiple:true`, controls the name of the XML tag used for each subelement during `DataSource.xmlSerialize()`.
  `String`
  `columnCode`
  See `DataSource.tableCode`.
  `Boolean`
  `creatorOverrides`
  Indicates that normal declarative security rules specified on this field are waived for rows that were created by the current user, as described in the discussion of `dataSource.creatorOverrides`.
  `VelocityExpression`
  `customCriteriaExpression`
  This property indicates that this field should be represented by a custom expression embedded in the WHERE clause of the generated SQL, instead of the generated expression containing this field name that would ordinarily be used.
  `VelocityExpression`
  `customInsertExpression`
  This property is similar to `customUpdateExpression`; its value is used during "add" operations.
  `VelocityExpression`
  `customJoinExpression`
  For fields with `includeFrom`, allows customization of the SQL JOIN condition used to retrieve this field's value from the related DataSource.
  `VelocityExpression`
  `customSelectExpression`
  This property indicates that this field represents a custom expression that should be embedded in the generated SQL instead of a reference to this field.
  `Boolean`
  `customSQL`
  For a DataSource with `serverType` "sql", "hibernate", or "jpa", indicates that this field should be omitted by default from all SQL operations, and will only be used with `custom queries`.
  `VelocityExpression`
  `customUpdateExpression`
  This property specifies the value to use to update this column on "update" operations.
  `Integer`
  `decimalPad`
  Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.
  `Integer`
  `decimalPrecision`
  Applies only to fields of type "float" and affects how many significant digits are shown.
  `OperatorId`
  `defaultOperator`
  The default search-operator for this field.
  `String`
  `description`
  An optional description of the DataSourceField's meaning.
  `boolean`
  `detail`
  Whether this field should be considered a "detail" field by a `DataBoundComponent`.
  `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.
  `FormItem`
  `editorType`
  Sets the default FormItem to be used whenever this field is edited (whether in a grid, form, or other component).
  `VelocityExpression`
  `editRequires`
  Indicates that the specified `VelocityExpression` must evaluate to true if writes to this field are to be allowed.
  `Boolean`
  `editRequiresAuthentication`
  Whether a user must be authenticated in order to write to this field.
  `String`
  `editRequiresRole`
  Comma-separated list of user roles that are allowed to write to this field.
  `AdvancedCriteria`
  `editWhen`
  Criteria-based editability control.
  `HTMLString`
  `emptyDisplayValue`
  Text to be used for display by client-side components when this field has a null or undefined value.
  `Boolean`
  `encodeInResponse`
  When set for a field with binary data, binary data will be delivered as a Base64 encoded string.
  `Boolean`
  `escapeHTML`
  When data values are displayed in DataBound components, by default strings will be interpreted as HTML by the browser in most cases.
  `Boolean`
  `expensive`
  Explicitly marks a field as expensive or inexpensive to fetch, overriding the default heuristics used by the server-side `DataSource.isExpensive()` method.
  `FormatString`
  `exportFormat`
  An optional `FormatString` for this field, for use when `exporting` data to spreadsheet formats (XLS and OOXML/XLSX), XML, JSON or CSV.
  `String`
  `exportTitle`
  Optional different field-title used for exports.
  `String`
  `fieldValueScript`
  A scriptlet to be executed on the server when deriving values for this field.
  `FormItem`
  `filterEditorType`
  Sets the default FormItem to be used for this field if it appears in a filter row, and `canFilter` is not false.
  `FieldFilterMode`
  `filterOn`
  This property limits where criteria for this field can be applied.
  `String`
  `fkColumnCode`
  See `DataSource.tableCode`.
  `String`
  `fkTableCode`
  See `DataSource.tableCode`.
  `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.
  `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.
  `FormatString`
  `format`
  Format string to use when rendering the value in any `DataBoundComponent` or when exporting via `DataSource.exportData()` or `ListGrid.exportData()` or `ListGrid.exportClientData()`.
  `String`
  `formula`
  If `field.formula` is set, this field's value in records will be calculated dynamically.
  `GetFieldValueCallback`
  `getFieldValue`
  A `Callback`, function, or JavaScript expression used to retrieve the field's value from the XML element or JSON record returned from a web service.
  `String`
  `group`
  For use in `ComponentSchema`, indicates what group to place the property in when editing in Reify.
  `boolean`
  `hidden`
  Whether this field should be hidden from users by default within a DataBound component.
  `boolean`
  `ignore`
  Whether this field should be completely excluded from this dataSource, as if it had never been defined.
  `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.
  `Integer`
  `imageHeight`
  Height of the image-content of this field.
  `Integer`
  `imageSize`
  Width and height of the image-content of this field.
  `Integer`
  `imageWidth`
  Width of the image-content of this field.
  `Boolean`
  `implicitSequence`
  For a field of `type` "sequence" on a DataSource with `serverType:"sql"`, this flag indicates that the field is implicitly bound to a sequence.
  `FieldImportStrategy`
  `importStrategy`
  Declares the `FieldImportStrategy` for this field.
  `String`
  `importStrategyFailedErrorMessage`
  Customizable and `localizable` error message to use when "displayRequired" `importStrategy` fails to find corresponding key value.
  `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.
  `String`
  `includeFrom`
  Indicates that this field should be fetched from another, related DataSource.
  `SummaryFunctionType`
  `includeSummaryFunction`
  When `field.includeFrom` is specified and multiple records exist in the related DataSource per record in the including DataSource, `includeSummaryFunction` indicates which `SummaryFunctionType` is used to produce the field value.
  `String`
  `includeVia`
  For a field that uses `includeFrom`, specifies which `foreignKey` field should be used to find records in the related DataSource.
  `VelocityExpression`
  `initRequires`
  Indicates that the specified `VelocityExpression` must evaluate to true if initializations of this field are to be allowed.
  `Boolean`
  `initRequiresAuthentication`
  Whether a user must be authenticated in order to initialize to this field.
  `String`
  `initRequiresRole`
  Comma-separated list of user roles that are allowed to initialize this field.
  `AdvancedCriteria`
  `initWhen`
  Criteria-based control for field settability on add operations.
  `String`
  `javaClass`
  Explicitly declares the Java class that should be used when data from the client is validated by the Smart GWT server and/or applied to Java Beans / POJOs via the server-side API `com.isomorphic.datasource.DataSource.setProperties()`.
  `String`
  `javaCollectionClass`
  See `javaClass` - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of type Collection or Map, `javaCollectionClass` can be used to specify a particular concrete class to use.
  `String`
  `javaKeyClass`
  See `javaClass` - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of Map type, `javaKeyClass` can be used to specify a particular concrete class for the map keys.
  `JoinType`
  `joinType`
  This property is only applicable to fields of SQL DataSources that also specify a `foreignKey` property; it is ignored for all other fields.
  `Integer`
  `length`
  Maximum number of characters allowed.
  `Boolean`
  `lenientXPath`
  Indicates that getting `valueXPath` for this field should not perform any validation at all and will return null for non existing XPaths.
  `Integer`
  `maxFileSize`
  For fields of a type that are represented by binary data initially uploaded from a file (currently "binary" and "imageFile", see `FieldType`), this sets the maximum file size allowed, in bytes.
  `String`
  `mimeType`
  For a `binary field`, sets a fixed mime type for all files stored to this field.
  `Boolean`
  `multiple`
  Indicates that this field should always be Array-valued.
  `MultipleFieldStorage`
  `multipleStorage`
  How values for a `multiple:true` field should be stored.
  `String`
  `multipleStorageSeparator`
  For fields that are `multiple:true` and use `multipleStorage`, the separator used in the "simpleString" `MultipleFieldStorage` mode.
  `String`
  `multipleValueSeparator`
  For fields that are `multiple:true`, the separator used between values when they are displayed.
  `FieldName`
  `name`
  Name for this field.
  `String`
  `nativeName`
  Only applicable to "sql" dataSources.
  `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:
  `String`
  `otherFKs`
  In addition to regular `foreignKey` this property allows defining multiple foreign keys if the field is related to more than one DataSource.
  `OutputWhen`
  `outputWhen`
  Specifies, for this field only, the type of condition field must match to be fetched from underlying source of data and delivered to the client.
  `String`
  `pluralTitle`
  User-visible plural name for this field.
  `Integer`
  `precision`
  Applies only to fields of type "float" or "integer" and affects how many significant digits are shown.
  `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.
  `Boolean`
  `propertiesOnly`
  For use in `ComponentSchema` for fields that contain other components, this flag suppresses auto-construction for subcomponents that appear under this field.
  `FormItem`
  `readOnlyEditorType`
  Sets the default FormItem to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.
  `AdvancedCriteria`
  `readOnlyWhen`
  Criteria-based version of `canEdit:false`.
  `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.
  `String`
  `relatedTableAlias`
  For a `SQL DataSource` field that specifies a `foreignKey`, this property defines the table alias name to use in generated SQL.
  `boolean`
  `required`
  Indicates this field must be non-null in order for a record to pass validation.
  `AdvancedCriteria`
  `requiredWhen`
  Criteria to be evaluated to determine whether this field is `required`.
  `Object`
  `rootValue`
  For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
  `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.
  `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.
  `Boolean`
  `skipTypeCoercion`
  Ordinarily, Smart GWT server runs `DSResponse` values through type validation logic in order to ensure that values are of the correct type.
  `String`
  `sortByField`
  Causes values for this field to be sorted according to values for another field, for both client- and server-side sorting.
  `String`
  `sqlDateFormat`
  For fields of type "date", "time", and "datetime" that specify an `sqlStorageStrategy` of "number" or "text", this property allows you to specify the format Smart GWT should use to map to/from the underlying value stored in the database.
  `String`
  `sqlFalseValue`
  For fields of type "boolean" that specify a `sqlStorageStrategy` of "singleChar", this is the value to persist for false values.
  `Boolean`
  `sqlForceInsensitive`
  This property is only applicable to fields of SQL DataSources, it overrides default behavior of `iContains` case insensitive operator on the server-side.
  `String`
  `sqlStorageStrategy`
  For certain field types, indicates the strategy to be used to store values to the underlying SQL column.
  `String`
  `sqlTrueValue`
  For fields of type "boolean" that specify a `sqlStorageStrategy` of "singleChar", this is the value to persist for true values.
  `Boolean`
  `storeMilliseconds`
  For fields of type "datetime", indicates whether the framework should attempt to preserve the millisecond part when persisting to native SQL datetime-type columns.
  `HashAlgorithm`
  `storeWithHash`
  If set, causes the field to be securely hashed before saving on an "add" or "update" operation.
  `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.
  `String`
  `tableName`
  Only applicable to "sql" dataSources, setting `tableName` indicates that this field will be coming from another table by way of a `customized SQL query`.
  `String`
  `target`
  For fields of `type` "link", specifies the target window for the link.
  `HTMLString`
  `title`
  Default user-visible title for this field.
  `String`
  `translatorClassName`
  The fully-qualified name of a Java class that implements the `com.isomorphic.datasource.DataTranslator` interface.
  `FieldType`
  `type`
  Type of this field.
  `String`
  `typeDiscriminator`
  For use in `ComponentSchema`, names another field on the same schema whose current value determines the effective type/schema of this field.
  `String`
  `unionOf`
  Only applicable to "union" dataSources, this is a comma-separated list of qualified field names, specifying how this unioned field is to be derived.
  `VelocityExpression`
  `updateRequires`
  Indicates that the specified `VelocityExpression` must evaluate to true if updates to this field are to be allowed.
  `Boolean`
  `updateRequiresAuthentication`
  Whether a user must be authenticated in order to update to this field.
  `String`
  `updateRequiresRole`
  Comma-separated list of user roles that are allowed to update this field.
  `AdvancedCriteria`
  `updateWhen`
  Criteria-based control for field settability on update operations.
  `String`
  `uploadFieldName`
  Used by the `BatchUploader` to map a field in an upload file to this dataSourceField.
  `Boolean`
  `useLocalDisplayFieldValue`
  The `FormItem.useLocalDisplayFieldValue` attribute may be specified within a dataSource configuration.
  `Validator[]`
  `validators`
  Validators to be applied to this field.
  `OperatorId[]`
  `validOperators`
  Set of search-operators valid for this field.
  `Map`
  `valueMap`
  A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.
  `String`
  `valueMapEnum`
  Fully qualified Java className of an Enum that should be used to derive this field's `com.smartgwt.client.types.ValueMap`.
  `String`
  `valueOperation`
  Note: Currently, this feature only works with `SQL DataSources`
  `XPathExpression`
  `valueWriteXPath`
  Alternative XPath expression used to set the field's value.
  `XPathExpression`
  `valueXPath`
  XPath expression used to retrieve the field's value.
  `VelocityExpression`
  `viewRequires`
  Indicates that the specified `VelocityExpression` must evaluate to true if values for the field are to be fetched.
  `Boolean`
  `viewRequiresAuthentication`
  Whether a user must be authenticated in order to fetch this field.
  `String`
  `viewRequiresRole`
  Comma-separated list of user roles that are allowed to fetch this field.
  `AdvancedCriteria`
  `visibleWhen`
  Criteria-based field visibility for server responses.
  `Boolean`
  `xmlAttribute`
  Indicates that `DataSource.xmlSerialize()` should serialize this value as an XML attribute.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DataSourceField()`

- ## Method Summary

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

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

- ## Field Details

  - ### autoGenerated

    public Boolean autoGenerated
    Indicates that values for this field are automatically generated by the database or ORM provider. Setting this flag makes the field behave somewhat like a `sequence field`, in that server-side logic does not expect client code to provide values for the field on "add" operations. However, it is not entirely the same as a sequence:
    - Sequences must be integers, whereas autoGenerated fields can be of any type
    - Smart GWT Server's DataSource implementations are capable of discovering the value that was generated by the database for sequence fields, which may not be possible with an autoGenerated field. See the docs for `customInsertExpression` for a discussion of this
    Unrelated to the `autoGenerated` flag, you have a general ability for field values to be generated by application code (as opposed to being generated by the database or ORM provider). For example, you can use `DMI methods`, `server scripts`, or `custom SQL`. (Note, if you want to have application code generate values for primaryKey fields, you may need to use an `operationBinding` that specifies `providesMissingKeys`).

    Default value is null

    See Also:
      - `sequenceName`
      - `FieldType`
      - `SequenceMode`

  - ### canSortClientOnly

    public boolean canSortClientOnly
    When true, this field can only be used for sorting if the data is entirely client-side.

    Default value is false

  - ### columnCode

    public String columnCode
    See `DataSource.tableCode`.

    Default value is null

  - ### valueMap

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

    Default value is null

  - ### initRequiresAuthentication

    public Boolean initRequiresAuthentication
    Whether a user must be authenticated in order to initialize to this field. If this property is set and the user is not authenticated, the Smart GWT Server will not allow this field to be initialized.

    Default value is null

    See Also:
      - `editRequiresAuthentication`
      - `Field-Level Security`

  - ### includeFrom

    public String includeFrom
    Indicates that this field should be fetched from another, related DataSource.

    The `includeFrom` attribute should be of the form "dataSourceId.fieldName", for example:

             <field includeFrom="supplyItem.itemName"/>

    A `foreignKey` declaration must exist between the two DataSources, establishing either a 1-to-1 relationship or a many-to-1 relationship from this DataSource to the related DataSource. The inclusion can be indirect (traverse multiple DataSources) so long as there is a chain of `foreignKey` declarations from the target DataSource to the DataSource where the `includeFrom` field is declared. You may use dot-notation to provide an explicit path between DataSources, or provide the name of only the last DataSource in the chain to have the complete path calculated for you at runtime. i.e., either of the following are acceptable forms, where foreign keys are defined to link records in the current DataSource to Employee records and in turn to Office records:

            <field includeFrom="Employee.Office.territory"/>
            <!-- OR -->
            <field includeFrom="Office.territory"/>

    Note that when using the shorthand form, there is potential ambiguity: there could be multiple ways in which two DataSources are related via different intervening DataSources, so the auto-discovered relation may be different depending on which other DataSources are loaded in the page. For this reason, explicitly spelling out the inclusion path is preferred.

    Nested inclusions, where an included field is itself an included field, are also supported - for details on this and other complex scenarios see `includeVia` docs.

    In all cases, `name` will default to the name of the included field, or you can specify a different name.

    If both DataSources are SQLDataSources, HibernateDataSources or JPADataSources (with Hibernate as the provider) the related data will be retrieved via a SQL join and criteria and sort directions applied to the field work normally (they become part of the generated SQL query).

    Note that includeFrom is also supported between two clientOnly or MockDataSources, but not for any other combination (for example, a RestDataSource cannot use includeFrom with a clientOnly DataSource). Here, the related data (including any values derived via `includeSummaryFunction`) will be retrieved from cacheData after the primary (fetch, add, or update) operation has returned its response.

    Otherwise, the related data will be retrieved via performing a DSRequest against the related DataSource once the data from the primary DataSource has been retrieved. In this case, criteria or sorting directions applied to the included field are only allowed if data paging is not in use (for example `ListGrid.dataFetchMode`:"basic"); otherwise, criteria and sort direction are ignored for the included field and a warning is logged on the server.

    Editing included fields

    An included field is `canEdit:false` by default. Note that included fields are not updatable, even if you set canEdit:true; the server will simply drop values for included fields if client code sends them.

    When thinking about editing an included field value, typically what is really intended is to edit the value of the `foreignKey` field. For example, take the scenario of a system that tracks accounts and the employees assigned to manage them. Given a DataSource "account" related one-to-one with DataSource "employee" by a "managerId" foreignKey field, we might declare an `includeFrom` so that the name of the account manager can be shown with each "account" record.

    Editing the manager's name while viewing the account would be intended to pick a new account manager, and not to change the legal name of the employee who happens to be the current account manager.

    To correctly set up this scenario, declare an `includeFrom` field that is hidden, but is used as the `displayField` for the foreign key field:

          <field name="managerId" foreignKey="employee.id" displayField="managerName" />
          <field name="managerName" includeFrom="employee.name" hidden="true"/>

    Now:
    - the "managerId" foreignKey field is shown in grids and forms, but takes its displayed value from the hidden `includeFrom` field. Note that when the `foreignKey` and `displayField` are specified, the framework automatically defaults `useLocalDisplayFieldValue` to true to ensure the displayed value is picked up from the record being edited.
    - the automatically chosen editor will be a SelectItem with `optionDataSource` set to "employees": it will allow picking a different "employee" record from the "employee" DataSource.
    - saving will save the ID of a new "employee" record to the "managerId" foreign key field, as intended
    You can alternatively set `editorType="ComboBoxItem"` on the "managerId" field to allow typeahead search of the "employee" DataSource. Note that the `foreignDisplayField` attribute allows developers to have a different fieldName be used locally as a displayField from the field name for the display field in the foreign dataSource.

    Including fields that use summary functions

    The `Include Summary Function` feature is used for including from a related DataSource where there are multiple related records. It applies a `SummaryFunctionType` to the related records aggregating them into single value. It is regularly used on directly included fields, but it supports indirect inclusions as well, when entire `includeFrom`+`includeSummaryFunction` setup is included from another DataSource. See `includeSummaryFunction` docs for more details.

    For best results, ensure that the field with `includeFrom` has its `type` explicitly set to the included field's `type`.

    `includeFrom` combined with ``multiple`:true`

    If you specify ``multiple`:true` on an `includeFrom` field, it has one of two quite different meanings:

    1. It is including a field which is itself marked `multiple:true`, across a regular many-to-one or one-to-one `relation`. In this case, the value of the included field is likely to be a flattened list of text values stored in a regular text field - see `multipleStorage`
    2. It is including multiple related values across a one-to-many or many-to-many relation
    The first of these is exactly the same as any other regular `includeFrom`, except that it will have normal `multiple:true` processing applied to the included value, so the client sees a true list of values rather than a flat string of text.

    The second is more involved. With this type of `includeFrom` we will actually fetch multiple records from the included DataSource. You should read the One-to-many and Many-to-many sections of the `relations overview` to make sure you understand how these relation types work, but essentially you declare a `foreignKey` on a field that is also marked `multiple:true`, and this causes Smart GWT to return a list of key values that your client-side code can use to obtain the related records (some Smart GWT UI components will do this automatically).

    Once one of these relation types is in place, it is also possible to declare `includeFrom` fields that make use of the relation to include fields other than the identifying key field, for convenience. For example, if a Country dataSource declared a one-to-many relation to a City dataSource, like this:

              <field name="majorCities" multiple="true" foreignKey="City.cityId" />

    The same dataSource could make use of that relation to include the names of all related cities for convenience, so you can show a list of "Major Cities" against each country without having to go back to the server and fetch the actual City records. The declaration would look like this:

              <field name="cityNames" multiple="true" includeFrom="City.cityName" />

    With Many-to-many related includeFroms - which require a "middle" dataSource, and thus a three-part `foreignKey` declaration - you may specify either the entire inclusion path, or just the endpoint. For example, if your Country dataSource has a many-to-many relation with a River dataSource - necessary, because most countries contain more than one river, and many rivers flow through more than one country - via the following `foreignKey` definition:

              <field name="rivers" multiple="true" foreignKey="CountryRivers.Rivers.riverId" />

    you could `includeFrom` the list of related river names with either this:

              <field name="riverNames" multiple="true" includeFrom="CountryRivers.Rivers.name" />

    or slightly simpler, this:

              <field name="riverNames" multiple="true" includeFrom="Rivers.name" />

    If just the endpoint is specified, Smart GWT will figure out the remainder of the path based on the available `foreignKey`s; if there is ambiguity that makes this impossible - ie, two `foreignKey` fields that target the same endpoint via different paths - you can either specify the entire include path in the `includeFrom` definition, or declare an `includeVia` setting on the field.

    Default value is null

    See Also:
      - `Relations`

  - ### relatedTableAlias

    public String relatedTableAlias
    For a `SQL DataSource` field that specifies a `foreignKey`, this property defines the table alias name to use in generated SQL.

    Aliasing is necessary when the same table appears more than once in a query. This can happen when using `Multiple `includeFrom` \n fields referring to the same related DataSource`. It can also happen when a `foreignKey` definition references the same dataSource that the field is defined in; this happens with hierarchical structures, for example where every Employee reports to another Employee, a so-called "self join", and it always requires `relatedTableAlias` to be specified; failure to do so will result in invalid SQL.

    In case of indirect relationship, when more than single join is needed to join the target table, and `includeVia` is missing, generated alias is a concatenation of `relatedTableAlias` and FK field names starting with the first `relatedTableAlias` met in chain of relations leading to the target table.

    See the "Automatically generated table aliases" section of the `SQL Templating` for more details.

    Default value is null

    See Also:
      - `DataSource.relatedTableAlias`
      - `includeVia`
      - `Relations`

  - ### required

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

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

    Default value is false

    See Also:
      - `Validator.applyWhen`

  - ### sequenceName

    public 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

    Default value is null

    See Also:
      - `SQL DataSources`

  - ### escapeHTML

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

    Default value is null

    See Also:
      - `ListGridField.getEscapeHTML()`

  - ### updateRequiresAuthentication

    public Boolean updateRequiresAuthentication
    Whether a user must be authenticated in order to update to this field. If this property is set and the user is not authenticated, the Smart GWT Server will not allow this field to be updated.

    Default value is null

    See Also:
      - `editRequiresAuthentication`
      - `Field-Level Security`

  - ### exportFormat

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

    Default value is null

    See Also:
      - `format`

  - ### description

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

    Default value is null

    See Also:
      - `DataSource.description`

  - ### title

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

    Default value is null

    See Also:
      - `Field.getExportTitle()`
      - `Component Binding`

  - ### multipleStorageSeparator

    public String multipleStorageSeparator
    For fields that are `multiple:true` and use `multipleStorage`, the separator used in the "simpleString" `MultipleFieldStorage` mode.

    Default value of null means the `multipleValueSeparator` is used instead.

    NOTE: "simpleString" storage concatenates the stringified forms of each of the multiple values together, delimited with the `multipleStorageSeparator` character(s). If you use this storage mode with String values that themselves contain the `multipleStorageSeparator`, they will not be correctly retrieved. To avoid this, use a multi-character delimiter that is not likely to occur in regular text, or switch to "json" storage

    Default value is null

  - ### javaCollectionClass

    public String javaCollectionClass
    See `javaClass` - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of type Collection or Map, `javaCollectionClass` can be used to specify a particular concrete class to use. If not specified, and a concrete Collection or Map class cannot be discovered using Java Reflection, the following concrete classes are used:
    - `java.util.ArrayList` is used for fields of type `List`
    - `java.util.HashSet` is used for fields of type `Set`
    - `java.util.LinkedList` is used for fields of type `Queue`
    - `java.util.LinkedHashMap` is used for fields of type `Map`
    - `java.util.ArrayList` is used for fields that are otherwise of type `Collection`
    Note that this value is used even if the target Collection or Map is declared as a concrete class. So, for example, if you set `javaCollectionClass` to `java.util.LinkedList` but your setter method accepts a `java.util.ArrayList`, you will get a ClassCastException.

    Default value is null

  - ### creatorOverrides

    public Boolean creatorOverrides
    Indicates that normal declarative security rules specified on this field are waived for rows that were created by the current user, as described in the discussion of `dataSource.creatorOverrides`. This setting overrides `dataSource.creatorOverrides`, for this field only.

    Note that field-level `creatorOverrides` is conceptually slightly different to the setting at DataSource and OperationBinding levels. To give the example of a fetch operation, at the other two levels, it results in a limited set of rows being returned, rather than a security exception being thrown. At the field-level, it results in values for individual fields being present in those rows, rather than them being stripped out on the server.

    Default value is null

    See Also:
      - `editRequires`
      - `viewRequires`
      - `DataSource.creatorOverrides`
      - `Field-Level Security`

  - ### typeDiscriminator

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

    Default value is null

    See Also:
      - `Component Schema`

  - ### filterEditorType

    public FormItem filterEditorType
    Sets the default FormItem to be used for this field if it appears in a filter row, and `canFilter` is not false.

    Note: If this is not specified, the edit-formItem type may be derived from the `editorType` property, or from the field's `type`.

    Default value is null

    See Also:
      - `Component Binding`

  - ### editRequiresRole

    public String editRequiresRole
    Comma-separated list of user roles that are allowed to write to this field. If the current user does not have any of the roles listed, the system will not allow this field to be initialized or updated. Please see `OperationBinding.requiresRole` for further details of Smart GWT's declarative role-based security. Please see `editRequiresAuthentication` [or `viewRequiresAuthentication` for viewRequiresRole] for the UI consequences if the user does not have the required roles, as well as for information on customizing field-level security.

    NOTE: This property prevents both initialization and updates for a field. If you have a need to prevent just initialization or just updates, you can use `initRequiresRole` or `updateRequiresRole`.

    Default value is null

    See Also:
      - `editRequiresAuthentication`
      - `viewRequiresRole`
      - `initRequiresRole`
      - `updateRequiresRole`
      - `Field-Level Security`

  - ### batchUploadCaseSensitive

    public Boolean batchUploadCaseSensitive
    Applies to the "fetch" operation that is used to look up key values for fields with `importStrategy.display` while importing data using `BatchUploader` or `DataImport` server-side API. Controls whether look up for key values is case sensitive or not. Default value is "false".

    Default value is false

  - ### canExport

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

    Default value is null

  - ### imageWidth

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

    Default value is null

  - ### viewRequiresRole

    public String viewRequiresRole
    Comma-separated list of user roles that are allowed to fetch this field. If the current user has any of the roles listed, values for the field will be fetched. Please see `OperationBinding.requiresRole` for further details of Smart GWT's declarative role-based security. Please see `editRequiresAuthentication` [or `viewRequiresAuthentication` for viewRequiresRole] for the UI consequences if the user does not have the required roles, as well as for information on customizing field-level security.

    Default value is null

    See Also:
      - `viewRequiresAuthentication`
      - `editRequiresRole`
      - `Field-Level Security`

  - ### sqlForceInsensitive

    public Boolean sqlForceInsensitive
    This property is only applicable to fields of SQL DataSources, it overrides default behavior of `iContains` case insensitive operator on the server-side. Set to `true` to force case insensitivity by changing case of both comparison expression sides or `false` to rely on database `LIKE` operator directly.
    See `SqlSettings` for more details including database specific defaults and other configuration options.

    Default value is null

    See Also:
      - `SQL Database Settings in `server.properties``

  - ### mimeType

    public String mimeType
    For a `binary field`, sets a fixed mime type for all files stored to this field. Should be set to a standard mime type string, for example, "text/plain" for a .txt file.

    This is useful if a binary field only stored one type of file and you chose not to store filenames, since the extension of the file name is normally used to determine the mime type.

    Default value is null

  - ### valueXPath

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

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### initRequires

    public VelocityExpression initRequires
    Indicates that the specified `VelocityExpression` must evaluate to true if initializations of this field are to be allowed. If the specified expression does not evaluate to true, the field will be removed from the request as described for `editRequiresAuthentication`.

    In addition to the normal context variables available to Velocity expressions in Smart GWT, expressions you write for field-level `requires` clauses - `initRequires`, `viewRequires`, `editRequires` and `updateRequires` - can reference two additional variables: `$fieldName` and `$dsName`. These are the names of the dataSource and field currently undergoing `requires` checks. They are helpful because they allow you to write a generic checker function that can be used to handle `requires` checks for multiple fields and dataSources.

    NOTE: This property only prevents initialization of a field; updates will still be allowed. You should only use this property if you have a special requirement; ordinarily, use `editRequires`, which applies security for both types of write.

    Default value is null

    See Also:
      - `editRequiresAuthentication`
      - `editRequiresRole`
      - `viewRequires`
      - `Field-Level Security`

  - ### sortByField

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

    Default value is null

  - ### translatorClassName

    public String translatorClassName
    The fully-qualified name of a Java class that implements the `com.isomorphic.datasource.DataTranslator` interface. If a field declares this attribute, Smart GWT Server will create an instance of the translator class and call its `translate()` method for that field value on every record in the response data during `DSResponse` creation.

    Translators were originally provided as a mechanism for translating a plain text value of a field - for example, as provided in a CSV file or CSV REST server response - into a type-correct value. Now, however, they are integrated into the general response flow and are one of many ways in which you can modify response data; see also Direct Method Invocation, `custom dataSources`, `transformResponseScript` and `fieldValueScript`.

    Because the orignal translator implementation was intended to derive type-correct values from plain text CSV values, the `DataTranslator` interface only specifies a single `translate()` method, that accepts a String and returns an Object. For reasons of backwards compatibility, this has been left in place, but we have implemented an additional subinterface, `com.isomorphic.datasource.FieldDataTranslator`. If your translator implements `FieldDataTranslator`, the framework will call that interface's two-parameter `translate()` method, passing in both the raw text value and a type-correct object coerced from the raw value by Smart GWT's type validation subsystem (though this automatic type coercion can be switched off with the `skipTypeCoercion flag`). Hence, `FieldDataTranslator`s are intended for more sophisticated value manipulations than simple type coercion.

    The following example shows a simple translator that parses a datetime using a non-standard format into a Java Date object and then alters that date to represent the first day of the month:

          package com.mycompany;

          import java.util.Date;
          import java.text.ParseException;
          import java.text.SimpleDateFormat;
          import com.isomorphic.datasource.FieldDataTranslator;
          import com.isomorphic.datasource.TranslaterException;

          public class FirstDayOfTheMonthTranslator implements FieldDataTranslator {
            static SimpleDateFormat sdf = new SimpleDateFormat("MM/d/yyyy hh:mm:ss a z");

            public Object translate(String raw, Object coerced) throws TranslaterException {
             if (object == null) return null;

                   // Because the raw text is in a weird format, standard type coercion will not have
                   // been able to derive a real datetime, so we need to do that first
             try {
              Date theDate = sdf.parse(raw);
                       // This API was deprecated a long time ago, but is still the easiest way to do this!
                       theDate.setDate(1);
                       return theDate;
             } catch (ParseException e) {
              // Exception handling code goes here
              return null;
             }
            }
          }

    To make use of this translator, you would use a field definition like this:

              <field name="myDateField" type="datetime" translatorClassName="com.mycompany.FirstDayOfTheMonthTranslator" />

    Default value is null

  - ### storeMilliseconds

    public Boolean storeMilliseconds
    For fields of type "datetime", indicates whether the framework should attempt to preserve the millisecond part when persisting to native SQL datetime-type columns. Whether this is possible depends on the type and version of the underlying database product; some databases - for example SQL Server earlier than 2008 and MySQL versions earlier than 5.6 - do not provide fractional seconds support. If you set this flag when your underlying database cannot support fractional seconds, it will be ignored.

    Other than the two cases just mentioned which are known to fail, `storeMilliseconds` has been tested and is officially supported with the following products and minimum versions:

    - Oracle 10g
    - Microsoft SQL Server 2008
    - MySQL 5.6
    - MariaDB 5.3
    - PostgreSQL 9.1
    - HSQLDB 2.2
    - DB2 for Unix/Linux 9.7
    - Firebird 11.2
    - Informix IDS 11.5
    Note that you can use `sqlStorageStrategy` to store a datetime value with sub-second precision in any database - see below.

    When the system generates SQL to insert or update datetime values including a millisecond element, it does so using a database-specific format string specified in property `defaultDateTimeFormatWithMilliseconds` in your `server.properties` file. These format strings should conform to the rules of the Java SimpleDateFormat class. Suitable format strings are provided for all default databases out of the box; if you need to override one or provide a new one, you do so as shown in this example:

            sql.MyNewDatabase.defaultDateTimeFormatWithMilliseconds: yy-MM-dd'T'hh.mm.ss.SSS

    Note that this property only controls the persistence of milliseconds into the database; there is no built-in support for sub-second elements of datetimes in any Smart GWT visual components. See also the documentation for `DataSource.trimMilliseconds` for more details of how sub-second datetime elements are handled in the client-server flow.

    This property is only applicable to DataSources of `serverType` "sql" and fields of `type` "datetime". It is ignored in all other cases. However, note that the built-in JPA and Hibernate dataSources will always persist millisecond values automatically if the underlying Java type, database and column support it.

    Finally, note that this property only has an effect on native datetime-type fields. When you use `sqlStorageStrategy` to store a temporal value in a text or number column, it is the `sqlDateFormat` you use that dictates the precision. For example, a field with `sqlStorageStrategy:"text"` and `sqlDateFormat:"yyyy-MM-dd hh:mm:ss.SSS"` would store and retrieve with millisecond precsion; the same field with `sqlDateFormat:"yyyy-MM-dd hh:mm"` would store and retrieve with precision to the nearest minute only.

    Default value is null

    See Also:
      - `DataSource.trimMilliseconds`

  - ### canEdit

    public Boolean canEdit
    Controls whether, by default, DataBoundComponents consider this field editable. Set to `false` to draw this field read-only.

    For a field that should never be changed from the UI, consider using `canSave` instead, which will both mark a field as non-editable and reject any attempt to programmatically change the value on the server (when using the Smart GWT Server).

    This attribute may not effect all dataBoundComponents - the `DataBoundComponent.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 `ListGridField.canEdit`. `FormItem.canEdit` for example).

    Default value is null

    See Also:
      - `canFilter`
      - `canSave`
      - `Component Binding`

  - ### showFileInline

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

    Default value is null

  - ### javaKeyClass

    public String javaKeyClass
    See `javaClass` - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of Map type, `javaKeyClass` can be used to specify a particular concrete class for the map keys. If not specified, and a concrete type cannot be discovered using Java Reflection, `java.lang.Object` is used. Note that `javaKeyClass` take precedence over generics if both are used.

    Default value is null

  - ### fkColumnCode

    public String fkColumnCode
    See `DataSource.tableCode`.

    Default value is null

  - ### updateWhen

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

    Default value is null

    See Also:
      - `initWhen`
      - `Component Binding`

  - ### recreateOnChange

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

    Default value is null

    See Also:
      - `PaletteNode.getRecreateOnChange()`
      - `Component Schema`

  - ### childTagName

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

    Default value is null

    See Also:
      - `Component Schema`

  - ### canView

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

    Default value is null

    See Also:
      - `Component Binding`

  - ### viewRequiresAuthentication

    public Boolean viewRequiresAuthentication
    Whether a user must be authenticated in order to fetch this field. If this property is set and the user is not authenticated, Smart GWT Server will not return values for this field to the client.

    The way this behavior works is to remove the field from the expressed or implied list of fields to return (note, this means the field is removed from the list of fields returned in data records; the actual field definition in the dataSource is still returned, but in a stripped-down state, as described below). A list of fields can be expressed using `OperationBinding.outputs` or `DSRequest.outputs`; in the absence of those, the entire set of fields defined in the DataSource is implied. You can override this behavior on a per-request basis by providing a DMI that just re-adds the names of the fields you want for that particular request to the "consolidated outputs". See the server-side Javadoc for `DSRequest.getConsolidatedOutputs()`.

    In addition to this behavior of trimming off values in fetched records, a field that fails a field-level security check (either this one or one of the two more specific checks, `viewRequiresRole` and `viewRequires`) will be altered in the version of the dataSource returned to the client by the `<loadDS> JSP tag` or `DataSourceLoader servlet`.

    - If the field is also not editable (see the discussion of this below), it will be marked `canView`:false, and thus effectively be inert and unusable on the client
    - If the field is editable, it will be marked `hidden`. By default, this means that `DataBoundComponent`s will not show the field, though this can be overridden for individual components. If you do choose to unhide the field, bear in mind that it will never actually show any data, because the underlying security test has still failed
    By default, view constraints automatically imply edit constraints - almost all of the time, if a user is not allowed to view a field, he should not be allowed to update it either. If you specify a view constraint, the system behaves as if you had also specified the corresponding edit constraint - so `viewRequiresAuthentication` on a field implies ``editRequiresAuthentication``. You override this behavior simply by specifying some kind of edit constraint for the field, either a different one (eg, "users" can view a field, but only "managers" can update it) or a blank one (if you have some unusual requirement whereby users are not allowed to view a field, but they can update it).

    Default value is null

    See Also:
      - `editRequiresAuthentication`
      - `Field-Level Security`

  - ### foreignKey

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

    Default value is false

    See Also:
      - `joinType`
      - `Relations`

  - ### validOperators

    public OperatorId[] validOperators
    Set of search-operators valid for this field.

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

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### customSQL

    public Boolean customSQL
    For a DataSource with `serverType` "sql", "hibernate", or "jpa", indicates that this field should be omitted by default from all SQL operations, and will only be used with `custom queries`.

    Having marked a field as `customSQL` you can refer to it via $criteria.fieldName or $values.fieldName in customized queries.

    The following are situations where you would not use `customSQL`:

    - simple joins where you want to enable users to see and search on a field from another table; consider `includeFrom` instead
    - fields where you want to calculate or transform values in SQL on load or save, but always perform the same calculation for each operationType; consider instead `sqlStorageStrategy` for some common cases, or `customSelectExpression`, `customUpdateExpression` and `customInsertExpression` for full customization
    - a special fetch is needed where the field needs to be excluded from the $defaultWhereClause so that it can be used in a custom <whereClause> - consider `OperationBinding.excludeCriteriaFields` instead

    Use customSQL in situations like:

    - there are multiple variations of the "fetch" operation with different `operationIds`, and the field is only used in some of them; in that case, consider using `OperationBinding.customFields` to selectively re-introduce SQL generation for the field only in operations where it's used.
    - the field represents hidden criteria on a field in another table where the field is never shown to the user
    - the field is a write-only value only saved in some operations
    - more than one data access strategy is in use (eg direct SQL for fetch and bean-based persistence accessed via DMI for saves) and certain fields are not available in SQL

    Default value is null

  - ### hidden

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

    Default value is false

    See Also:
      - `Component Binding`

  - ### inapplicable

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

    Default value is null

    See Also:
      - `Component Schema`

  - ### decimalPrecision

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

    Default value is null

    See Also:
      - `Appearance overview and related methods`

  - ### primaryKey

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

    Default value is false

    See Also:
      - `Relations`

  - ### allowClientRequestedSummaries

    public Boolean allowClientRequestedSummaries
    Affects whether client dsRequests can request summaries for this field.

    Default setting of null means that the DataSource-wide default setting `DataSource.allowClientRequestedSummaries` is used for this field.

    Default value is null

    See Also:
      - `DataSource.allowClientRequestedSummaries`
      - `Server Summaries`

  - ### updateRequires

    public VelocityExpression updateRequires
    Indicates that the specified `VelocityExpression` must evaluate to true if updates to this field are to be allowed. If the specified expression does not evaluate to true, the field will be removed from the request as described for `editRequiresAuthentication`.

    In addition to the normal context variables available to Velocity expressions in Smart GWT, expressions you write for field-level `requires` clauses - `updateRequires`, `viewRequires`, `editRequires` and `initRequires` - can reference two additional variables: `$fieldName` and `$dsName`. These are the names of the dataSource and field currently undergoing `requires` checks. They are helpful because they allow you to write a generic checker function that can be used to handle `requires` checks for multiple fields and dataSources.

    NOTE: This property only prevents update of a field; initialization will still be allowed. You should only use this property if you have a special requirement; ordinarily, use `editRequires`, which applies security for both types of write.

    Default value is null

    See Also:
      - `editRequiresAuthentication`
      - `editRequiresRole`
      - `viewRequires`
      - `Field-Level Security`

  - ### visibleWhen

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

    Criteria can reference the current user (`auth.userId`, `auth.roles`), the current operation type (`context.operationType`), and fields on related DataSources via dot notation (`Order.Customer.tier`). See ServerDynamicCriteria for the full syntax.

    Example — salary visible only to HR users:

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

    Default value is null

    See Also:
      - `viewRequiresRole`
      - `Component Binding`

  - ### validators

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

    Default value is null

    See Also:
      - `Validator`
      - `Validation overview and related methods`

  - ### editorType

    public FormItem editorType
    Sets the default FormItem 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 the rules explained `here`.

    Default value is null

    See Also:
      - `Component Binding`

  - ### autoQuoteCustomExpressions

    public boolean autoQuoteCustomExpressions
    If explicitly set to false, switches off automatic quoting and escaping of values in custom expressions that are derived from Velocity evaluations.

    By default, any part of a `customSelectExpression`, `customCriteriaExpression`, `customUpdateExpression` or `customInsertExpression` that comes ultimately from evaluating a Velocity expression, will be automatically quoted and escaped according to the syntax of the underlying database. We do this because "raw" values are vulnerable to SQL injection attacks.

    However, it is possible that the exact SQL logic you desire for a custom expression cannot be expressed without access to the raw, unquoted value. To work around this, you can either use the special `$rawValue` context variable, or you can set this property to false to switch off auto-quoting completely for all custom expressions on this field.

    Warning: Bear in mind that it is dangerous to use raw values. There are some cases where using the raw value is necessary, but even so, all such cases are likely to be vulnerable to injection attacks. Generally, the presence of `$rawValue` in a custom expression, or any fields with `autoQuoteCustomExpressions: false` specified, should be viewed as a red flag.

    Default value is true

    See Also:
      - `customSelectExpression`
      - `customUpdateExpression`
      - `customInsertExpression`
      - `customCriteriaExpression`

  - ### xmlAttribute

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

    Default value is null

    See Also:
      - `Component Schema`

  - ### fieldValueScript

    public String fieldValueScript
    A scriptlet to be executed on the server when deriving values for this field. The script will run after the main operation (eg, SQL fetch) and after any `transformResponseScript`. It is intended to be used for fine-grained transformation at the field level, in cases where declarative approaches such as `customSelectExpression` are insufficient.

    The script will be provided with the following variables:

    - dsRequest The current `DSRequest`
    - field The current field, as an instance of `com.isomorphic.datasource.DSField`
    - record The record containing the current field value, as either a Map or a Javabean, depending on your data model. See `beanClassName`
    - value The untransformed field value. Note, this will only be provided if the containing record is a Map; if it is a Javabean, your script is expected to derive the value itself, and to apply the transformed value directly to the bean
    Before the `fieldValueScript` is called, Smart GWT will run type validations on the untransformed field value, to either confirm that the value is a valid one for the `declared field type`, or to attempt to coerce it into such a valid value (for example, by parsing a number or date out of a string). Note, this validation/coercion step can be disabled - see `skipTypeCoercion` - but whether or not this step runs, and whether or not coercion was required, if the resulting value is valid for the declared field type, an additional variable of the appropriate type will be made available to your script
    - valueString, an instance of String
    - valueInteger, an instance of Long
    - valueFloat, an instance of Double
    - valueBoolean, an instance of Boolean
    - valueDate/Time/Datetime, an instance of java.util.Date
    Your script can either manipulate the value directly in the record (if your record is a Javabean, this is the only supported option), or it can return the transformed value and Smart GWT will apply it to the response data. If you change the value in the record directly, you should ensure that your script explicitly returns null.

    PERFORMANCE NOTE: JSR223 script calls can involve an overhead, and since `fieldValueScript` will be called for every field that declares one, for every record in a resultset, that overhead can easily multiply to become a performance issue. For this reason, Smart GWT implements script caching for any JSR223 script language that support pre-compilation, and we also recommend the use of Groovy as a scripting language when you are creating `fieldValueScript`s. See the "Caching" and "Relative Performance" sections of the `server scripting article` for more details.

    Default value is null

    See Also:
      - `DataSource.script`
      - `DataSource.transformRequestScript`
      - `DataSource.transformResponseScript`
      - `Server Scripting`

  - ### initRequiresRole

    public String initRequiresRole
    Comma-separated list of user roles that are allowed to initialize this field. If the current user does not have any of the roles listed, the system will not allow this field to be initialized.

    NOTE: This property only prevents initialization of a field; updates will still be allowed. You should only use this property if you have a special requirement; ordinarily, use `editRequiresRole`, which applies security for both types of write.

    Default value is null

    See Also:
      - `editRequiresAuthentication`
      - `editRequiresRole`
      - `updateRequiresRole`
      - `initRequires`
      - `Field-Level Security`

  - ### importStrategyFailedErrorMessage

    public String importStrategyFailedErrorMessage
    Customizable and `localizable` error message to use when "displayRequired" `importStrategy` fails to find corresponding key value. Default message: Key mapping for display value is required, but was not found.

    Default value is null

    See Also:
      - `importStrategy`

  - ### length

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

    Default value is null

    See Also:
      - `ListGridField.getWidth()`

  - ### target

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

    Default value is "_blank"

    See Also:
      - `type`
      - `ListGridField.getTarget()`
      - `DetailViewerField.getTarget()`

  - ### valueOperation

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

    Default value is null

    See Also:
      - `AdvancedCriterionSubquery`
      - `includeFrom`
      - `OperationBinding.summaryFunctions`

  - ### initWhen

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

    Default value is null

    See Also:
      - `updateWhen`
      - `Component Binding`

  - ### valueMapEnum

    public String valueMapEnum
    Fully qualified Java className of an Enum that should be used to derive this field's `com.smartgwt.client.types.ValueMap`.

    This has the same behavior of auto-deriving a `valueMap` from a Java Enum as `DataSource.autoDeriveSchema` except it applies only to one field.

    If you enable `autoDeriveSchema` there is no need to set `valueMapEnum` for Enum fields unless you want to actually override the behavior to use a different Enum for the field (eg, a superclass Enum that is more restrictive).

    Default value is null

  - ### readOnlyEditorType

    public FormItem readOnlyEditorType
    Sets the default FormItem 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.readOnlyEditorType`.

    Default value is null

    See Also:
      - `Component Binding`

  - ### ignore

    public boolean ignore
    Whether this field should be completely excluded from this dataSource, as if it had never been defined.

    If set to true, the field will be entirely omitted when serving a DataSource derived from a server-side definition (typically a .ds.xml file) to the client.

    Default value is false

    See Also:
      - `Component Binding`

  - ### canSave

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

    Default value is null

    See Also:
      - `Component Binding`

  - ### editRequiresAuthentication

    public Boolean editRequiresAuthentication
    Whether a user must be authenticated in order to write to this field. If this property is set and the user is not authenticated, the Smart GWT Server will not allow this field to be updated or initialized.

    This property affects two things. Firstly, the server determines when the DataSource is first loaded if we have an authenticated user; if we don't, the field is marked `canEdit: false`. Secondly, when an insert or update request is received from the client, the server removes the field from the `values` clause before the request is processed.

    Note that you can override this behavior. The `canEdit` setting can be overridden on the client-side DataSource like any other client-side property. The value-removing behavior can be overridden on a per-request basis by providing a DMI that re-adds values for the fields you want for that particular request to the values object (the values originally sent up by the client are available on the DSRequest). See the server-side Javadocs for `DSRequest.getValues()` and `DSRequest.getClientSuppliedValues()`.

    Default value is null

    See Also:
      - `viewRequiresAuthentication`
      - `Field-Level Security`

  - ### emptyDisplayValue

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

    Default value is null

    See Also:
      - `FormItem.getEmptyDisplayValue()`
      - `ListGridField.getEmptyCellValue()`
      - `DetailViewerField.getEmptyCellValue()`
      - `Appearance overview and related methods`

  - ### maxFileSize

    public Integer maxFileSize
    For fields of a type that are represented by binary data initially uploaded from a file (currently "binary" and "imageFile", see `FieldType`), this sets the maximum file size allowed, in bytes.

    Default value is null

    See Also:
      - `com.smartgwt.client.data.DataSource#maxFileSizeExceededMessage`

  - ### nativeName

    public String nativeName
    Only applicable to "sql" dataSources. If set, this property indicates that the field is bound to the column named in the property. It is used to bind a DataSourceField to a database column with a different name.

    `nativeName` is useful for disambiguating in cases where you have customized SQL. For example, assume you are joining two tables - call them `product` and `supplier` - that both contain a column called "name". Only one field in the DataSource can be called "name"; to disambiguate, we need to specify both `tableName` and `nativeName`. A field declaration like this would be needed:

            <field name="supplierName" type="text" tableName="supplier" nativeName="name" />

    You may also wish to use this property to map legacy column names to more meaningful field names in the DataSource. For example:

            <field name="productName" type="text" nativeName="PRDNM" />

    Note that it is not allowed to have multiple fields with the same `nativeName` bound to the same database table.

    Default value is null

    See Also:
      - `tableName`

  - ### getFieldValue

    public GetFieldValueCallback getFieldValue
    A `Callback`, function, or JavaScript expression used to retrieve the field's value from the XML element or JSON record returned from a web service.

    This is an advanced attribute for use when a `valueXPath` setting is insufficient to derive a field's value, yet an implementation of `DataSource.transformResponse()` is overkill.

    For the required parameters, see the documentation for GetFieldValueCallback.

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### useLocalDisplayFieldValue

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

    Default value is null

  - ### customUpdateExpression

    public VelocityExpression customUpdateExpression
    This property specifies the value to use to update this column on "update" operations. The value of this property will be passed through Velocity evaluation and then embedded directly in the SQL generated to perform the update. It can be used in conjunction with `customSelectExpression` to provide bi-directional mapping between application data formats and persisted data formats. Or, it can be used unilaterally as a means of silently enforcing data rules - for example, ensuring that all values for a given field are in upper case.

    You can use Velocity expressions in your `customUpdateExpression`s, and the `usual context variables` are available. Note that the results of Velocity evaluations are automatically quoted and escaped by default; this behavior can be switched off - see `autoQuoteCustomExpressions`, and particularly note the warnings about its use.

    The value must be a string that will end up as a valid SQL snippet after Velocity evaluation. The following examples are valid:

    - `"SUBSTR(ANOTHER_COLUMN, 1, 10)"`
    - `"SUBSTR($values.someTextField.toUpperCase(), 1, 10)"`
    - `"SOME_NUMERIC_COLUMN * 1000"`
    - `"$values.someTextField.toUpperCase()"` (this is a technically valid but incorrect usage - see below)
    NOTE: although all these examples are valid, `customUpdateExpression` is intended to be used when you have a need to customize the actual SQL. If you simply want to use a server-derived value in the query (as is the case with the last of these examples), you should use `Transaction Chaining`, `DMI`, or a `server script` instead.

    In the examples above, the first is an actual SQL snippet and must not be enclosed in quotes. The second shows an SQL snippet containing a literal - because the literal is the result of a Velocity evaluation, it will be automatically quoted so there is no need to do so manually. The third example yields a number, so it must not be quoted. The last example is also the result of a Velocity evaluation and thus does not need to be quoted. Note, however, that this example involves no SQL customization - this kind of usage should be avoided, as noted above.

    When an "update" operation runs, any fields that specify `customSelectExpression` but do not specify customUpdateExpression will be ignored. When an "add" operation runs, this property acts as a default for any fields that do not specify a `customInsertExpression`; similar to update, any fields that specify a customSelectExpression but do not specify either a customUpdateExpression or customInsertExpression, will be ignored when "add" operations run.

    Note that this property only applies to users of the Smart GWT server using dataSources of type "sql".

    Default value is null

    See Also:
      - `customSelectExpression`
      - `customInsertExpression`
      - `customCriteriaExpression`
      - `autoQuoteCustomExpressions`

  - ### skipTypeCoercion

    public Boolean skipTypeCoercion
    Ordinarily, Smart GWT server runs `DSResponse` values through type validation logic in order to ensure that values are of the correct type. Eg, for a field declared to be type "date", type validation will ensure that the value is an instance of `java.util.Date`; if it isn't, the server will attempt to coerce it into an instance of that class - for a date, this coercion attempt would take the form of trying to parse the `toString()` form of the raw value.

    If `skipTypeCoercion` is true, the server skips this step. You may wish to do this if you have other value manipulation logic in place - for example in a `translator` or `fieldValueScript` - so you do not need the automatic type coercion, or don't want it for some other reason, such as performance. It may also be that you know the data is already in a correctly-typed form, so there is no point in running the type validation/coercion step. For example, data fetched by an `SQLDataSource` will have already been converted to the correct type in advance; similarly, data values coming out of Javabeans with strongly-typed accessor methods cannot help but be the correct type.

    Default value is null

  - ### customSelectExpression

    public VelocityExpression customSelectExpression
    This property indicates that this field represents a custom expression that should be embedded in the generated SQL instead of a reference to this field. For example, if you have a field `partialName` where this value is set to `SUBSTR(surname, 2)`, the generated SQL would look similar to this:

            SELECT ... SUBSTR(surname, 2) AS partialName ...

    Note that adding "AS partialName" as shown above is required - this is how the framework identifies the expression as producing a value for this particular DataSourceField when results are received from the database.

    Fields with `customSelectExpression` set can be used for sorting and filtering in the normal way, but they are only applicable to update-type operations if you also provide a corresponding `customUpdateExpression` and/or `customInsertExpression`. See the documentation for those methods for the rules of how they are applied.

    You can use Velocity expressions in your `customSelectExpression`s, and the `usual context variables` are available. Note that the results of Velocity evaluations are automatically quoted and escaped by default; this behavior can be switched off - see `autoQuoteCustomExpressions`, and particularly note the warnings about its use.

    Note that this property only applies to users of the Smart GWT server using dataSources of type "sql".

    Default value is null

    See Also:
      - `customUpdateExpression`
      - `customInsertExpression`
      - `customCriteriaExpression`
      - `autoQuoteCustomExpressions`

  - ### customJoinExpression

    public VelocityExpression customJoinExpression
    For fields with `includeFrom`, allows customization of the SQL JOIN condition used to retrieve this field's value from the related DataSource.

    The value is a Velocity expression used as the ON clause of the generated JOIN. The variable `$defaultJoinExpression` (alias `$defaultJoin`) contains the auto-generated join condition (the equality test on foreign key columns), allowing you to extend the default condition rather than replace it entirely.

    For example, to add an additional constraint to the join:

            <field name="capital" includeFrom="cityDS.name"
                   customJoinExpression="$defaultJoinExpression
                                         AND cityDS.isActive = 1" />

    This generates SQL like:

            JOIN cityDS ON countryDS.capitalId = cityDS.id AND cityDS.isActive = 1

    instead of:

            JOIN cityDS ON countryDS.capitalId = cityDS.id

    The `standard Velocity context variables` are available. Unlike `customSelectExpression`, values in `customJoinExpression` are not automatically quoted, because this expression represents a SQL condition rather than a value.

    In addition, the following variables are available for building or extending the join condition:

    - `$defaultJoinExpression` (shortcut `$defaultJoin`) — the auto-generated join condition (equality test on foreign key columns). This is typically used as a base and extended with additional constraints, as shown in the example above.
    - `$fromTable` (shortcut `$from`) — table name or alias of the DataSource that declares the foreign key (the "from" side)
    - `$toTable` (shortcut `$to`) — table name or alias of the related DataSource (the "to" side)
    These support Velocity dot-syntax for qualified column references: `$from.columnName` resolves to `tableName.columnName` (or `alias.columnName` when `relatedTableAlias` is set).

    Using `$from/$to` instead of hardcoded table names is strongly recommended. When a field with `customJoinExpression` is reached via chained `includeFrom` (for example, DS_A includes from DS_B, which includes from DS_C), the actual table names or aliases depend on the query context and may differ from those declared in the DataSource. Hardcoded names can produce incorrect SQL in such cases, while `$from/$to` always resolve to the correct table or alias. As a secondary benefit, the expression becomes resilient to table renames and compatible with `relatedTableAlias`.

            <field name="capital" includeFrom="cityDS.name"
                   customJoinExpression="$from.capitalId = $to.id
                                         AND $to.isActive = 1" />

    Applies to SQL DataSources only. Works with both ANSI joins (`useAnsiJoins:true`) and non-ANSI WHERE-clause joins.

    Default value is null

    See Also:
      - `includeFrom`
      - `customSelectExpression`
      - `DataSource.useAnsiJoins`

  - ### sqlDateFormat

    public String sqlDateFormat
    For fields of type "date", "time", and "datetime" that specify an `sqlStorageStrategy` of "number" or "text", this property allows you to specify the format Smart GWT should use to map to/from the underlying value stored in the database. The string provided must be a valid SimpleDateFormat pattern string.

    For fields of type "datetime" and "time" that specify an `sqlStorageStrategy` of "number", two special sqlDateFormat values are supported:

    - "epoch" - The datetime or time value is stored as the number of full seconds that have elapsed since January 1, 1970, 00:00:00 GMT.
    - "epochms" - The datetime or time value is stored as the number of milliseconds that have elapsed since January 1, 1970, 00:00:00 GMT. Millisecond precision is preserved through database roundtrips with this setting

    This property and the "number" and "text" strategies for date/datetime fields are provided to allow transparent two-way mapping of legacy date values that are stored in numeric or text columns respectively rather than a true "date" column. You would not ordinarily use them in the absence of a legacy database.

    Note that this property only applies to users of Smart GWT server and data sources of type "sql".

    Default value is null

  - ### name

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

    Default value is null

  - ### rootValue

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

    Default value is null

    See Also:
      - `Relations`

  - ### storeWithHash

    public HashAlgorithm storeWithHash
    If set, causes the field to be securely hashed before saving on an "add" or "update" operation.

    The default is null except for fields of `type`: "password", for which the default is "bcrypt". To disable hashing for password fields, you must set this property to "none".

    Default value is varies

  - ### audit

    public FieldAuditMode audit
    Determines when the field value should be saved to the audit DataSource when `auditing` is enabled. Setting the property to "change" will conserve storage by only saving out the value when it's changed, and setting it to "never" will exclude the field values from ever being saved during auditing.

    #### Binary fields

    Because binary data can be very large compared to other data types, and in many use cases does not typically change (for example, an application that stores scanned documents), binary fields are treated specially for auditing purposes:
    - The default `audit` setting is "change"
    - The implied `_filename`, `_filesize` and `_date_created` metadata fields inherit their `audit` setting from the associated binary field, if no explicit setting is provided for the metadata field. This includes inheriting the the implicit "change" default. See the `binary fields overview` for more details about the binary metadata fields, including how to provide explicit properties for them
    - By default, we determine if the binary content has changed by comparing the `_filename` and `_filesize` metadata values. If both those values are unchanged, we assume the content is also unchanged. If you want to compare the actual binary content instead, set `DataSource` property `DataSource.compareMetadataForAuditChangeStatus` to false, but bear in mind this may have performance implications, as described in the documentation for that property

    Default value is "always"

  - ### valueWriteXPath

    public XPathExpression valueWriteXPath
    Alternative XPath expression used to set the field's value.

    If is not set, then `dataSourceField.valueXPath` is used, see its description for details.

    See also Smart GWT server java APIs `DataSource.setProperties()` and `DSResponse.setData()`.

    Default value is null

    See Also:
      - `Client-side Data Integration`

  - ### includeVia

    public String includeVia
    For a field that uses `includeFrom`, specifies which `foreignKey` field should be used to find records in the related DataSource.

    `includeVia` only needs to be set when you have more than one `foreignKey` to the same related DataSource. If you have multiple foreignKeys to multiple different DataSources, there is no need to set `includeVia`.

    For example, perhaps you have a DataSource "moneyTransfer" where each record represents a money transfer, where the source and payment currencies are different, and the list of currencies is stored in a related DataSource "currency". Each "moneyTransfer" record is linked to 2 "currency" records, through two different foreignKey fields, "sourceCurrencyId" and "paymentCurrencyId".

    The following declarations would be required to use `includeFrom` to get a include the field "currencySymbol" from each of the two related "currency" records.

            <field name="sourceCurrencyId" foreignKey="currency.id"/>
            <field name="paymentCurrencyId" foreignKey="currency.id"/>
            <field name="sourceCurrencySymbol" includeFrom="currency.currencySymbol" includeVia="sourceCurrencyId"/>
            <field name="paymentCurrencySymbol" includeFrom="currency.currencySymbol" includeVia="paymentCurrencyId"/>

    ### SQL Templating and `includeVia`

    The `includeVia` feature uses SQL table aliases in the generated SQL when generating multiple SQL joins to the same SQL table. When using `SQL Templating`, it's sometimes necessary to know the names of the aliases in the generated SQL. The table alias used can be configured via setting `relatedTableAlias` on the `foreignKey` field, for example, using the declarations below, aliases "source" and "payment" would be used for the two "currency" tables.

            <field name="sourceCurrencyId" foreignKey="currency.id" relatedTableAlias="source"/>
            <field name="paymentCurrencyId" foreignKey="currency.id" relatedTableAlias="payment"/>
            <field name="sourceCurrencySymbol" includeFrom="currency.currencySymbol" includeVia="sourceCurrencyId"/>
            <field name="paymentCurrencySymbol" includeFrom="currency.currencySymbol" includeVia="paymentCurrencyId"/>

    ### Multiple indirection and `relatedTableAlias`

    General rule is that if `relatedTableAlias` is present it is used as alias or its segment, otherwise `foreignKey` field name linked by `includeVia` is used instead. See the "Automatically generated table aliases" section of the `SQL Templating` for the complete set of general rules how aliases are generated. Also, see some samples below.

    Sometimes you may have two `includeFrom` fields that include a field which is itself included from another DataSource, for example:

            <field name="sourceCurId" nativeName="sourceCurrencyId" foreignKey="currency.id" relatedTableAlias="source"/>
            <field name="sourceCurrencySymbol" includeFrom="currency.currencySymbol" includeVia="sourceCurId"/>
            <field name="sourceCurrencyGroup" includeFrom="currency.groupName" includeVia="sourceCurId"/>
            <field name="paymentCurId" nativeName="paymentCurrencyId" foreignKey="currency.id" relatedTableAlias="payment"/>
            <field name="paymentCurrencySymbol" includeFrom="currency.currencySymbol" includeVia="paymentCurId"/>
            <field name="paymentCurrencyGroup" includeFrom="currency.groupName" includeVia="paymentCurId"/>

    .. where the "currency" DataSource used above is related to the "currencyGroup" DataSource via fields:

            <field name="groupId" type="integer" foreignKey="currencyGroup.id" relatedTableAlias="group"/>
            <field name="groupName" type="text" includeFrom="currencyGroup.groupName"/>

    Fields "sourceCurrencyGroup" and "paymentCurrencyGroup" include a field that is itself an included field. In this case "currencyGroup" table will be referenced two times, and its `relatedTableAlias` defined in "currency" DataSource will be prefixed with the referenced by `includeVia` field's `relatedTableAlias` value to make aliases unique in generated SQL: "source_group" and "payment_group".

    The same aliases would be used if "sourceCurrencyGroup" and "paymentCurrencyGroup" fields were to include "currencyGroup.groupName" indirectly:

            <field name="sourceCurrencyGroup" includeFrom="currency.currencyGroup.groupName" includeVia="sourceCurId"/>
            <field name="paymentCurrencyGroup" includeFrom="currency.currencyGroup.groupName" includeVia="paymentCurId"/>

    This works the same for more complex relationships. If we add a "moneyTransferDetail" DataSource to the sample above which has multiple references to "moneyTransfer" DataSource and would include fields from "currency" and "currencyGroup" DataSources:

            <field name="mtId" nativeName="moneyTransferId" type="integer" foreignKey="moneyTransfer.id" relatedTableAlias="main" />
            <field name="mainTransferName" includeFrom="moneyTransfer.name" includeVia="mtId" />
            <field name="mainSourceSymbol" includeFrom="moneyTransfer.sourceCurrencySymbol" includeVia="mtId" />
            <field name="mainSourceGroup" includeFrom="moneyTransfer.sourceCurrencyGroup" includeVia="mtId" />
            <field name="mainPaymentSymbol" includeFrom="moneyTransfer.paymentCurrencySymbol" includeVia="mtId" />
            <field name="mainPaymentGroup" includeFrom="moneyTransfer.paymentCurrencyGroup" includeVia="mtId" />
            <field name="mtPrevId" nativeName="moneyTransferPreviousId" type="integer" foreignKey="moneyTransfer.id" relatedTableAlias="prev" />
            <field name="previousTransferName" includeFrom="moneyTransfer.name" includeVia="mtPrevId" />
            <field name="previousSourceSymbol" includeFrom="moneyTransfer.sourceCurrencySymbol" includeVia="mtPrevId" />
            <field name="previousSourceGroup" includeFrom="moneyTransfer.sourceCurrencyGroup" includeVia="mtPrevId" />
            <field name="previousPaymentSymbol" includeFrom="moneyTransfer.paymentCurrencySymbol" includeVia="mtPrevId" />
            <field name="previousPaymentGroup" includeFrom="moneyTransfer.paymentCurrencyGroup" includeVia="mtPrevId" />

    In this scenario the "currencyGroup" table will be joined 4 times - for all main/prev transfer and payment/source currency combinations. So, aliases will be prefixed with both intermediate `relatedTableAlias` values: "main_source_group", "main_payment_group", "prev_source_group", "prev_payment_group".

    It is also allowed to specify a series of FK fields in `includeVia`, for example "moneyTransferDetail" could declare:

            <field name="mainSourceCurrencyGroup" includeFrom="moneyTransfer.currency.currencyGroup.groupName" includeVia="mtId.sourceCurId"/>
            <field name="mainPaymentCurrencyGroup" includeFrom="moneyTransfer.currency.currencyGroup.groupName" includeVia="mtId.paymentCurId"/>

    In this case the prefix used for table aliases will be the same, cause relations referenced in `includeVia` are the same as in previous example: "main_source_group" and "main_payment_group".

    Note that if `related table alias` are completely missing then, according to general rule, `foreignKey` field names will be used in aliases: "mtId_sourceCurId_groupId" and "mtId_paymentCurId_groupId".

    ### Ambiguous `includeFrom` definitions and logging

    Considering the flexibility and complexity of configuring relationships between Datasources, it is important to be aware of certain limitations. Specifically, when multiple fields attempt to include the same field from the same related Datasource via the same (default or specified) foreign key, such configurations are not permitted and may result in unpredictable behavior. This scenario is detected and reported as a warning in the server logs during both DataSource loading and DSRequest execution.

    In example below, fields "sourceCurrencySymbol", "currency" and "currencySymbol" include the same "currencySymbol" field from the same "currency" DataSource via the same "currencyId" foreign key field. So, for the fields "currency" and "currencySymbol" warnings will be logged as they include the same value as does the "sourceCurrencySymbol" field.

            <field name="currencyId" foreignKey="currency.id"/>
            <field name="sourceCurrencySymbol" includeFrom="currency.currencySymbol" />
            <field name="currency" includeFrom="currency.currencySymbol" />
            <field includeFrom="currency.currencySymbol" />

    Additionally there are two server logging categories that may be set to DEBUG level to log details of the entire `includeFrom` setup. Specifically `com.isomorphic.sql.SQLDataSource.Alias` category enables logging for all fields with `includeFrom`, exact direct or indirect include path to the target field, includeVia/aliases used and `com.isomorphic.sql.SQLDataSource.FK` category additionally enables logging for the foreign key fields relations are based on.

    ### Extended `includeVia` syntax

    In complex cases involving composite foreign keys or indirect relation chains (multi-step paths across multiple DataSources), `includeVia` supports an extended syntax that allows explicit control over how relationships are resolved. See `IncludeViaSyntax` for more details.

    Default value is null

    See Also:
      - `relatedTableAlias`
      - `Relations`

  - ### stringInBrowser

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

    Default value is null

  - ### joinType

    public JoinType joinType
    This property is only applicable to fields of SQL DataSources that also specify a `foreignKey` property; it is ignored for all other fields. Indicates the type of join to make between the tables underlying this DataSource and the other DataSource referred to in the `foreignKey` property, when resolving `includeFrom` fields. The default value of null is the same as specifying "inner".

    Note, outer joins are allowed for all supported database products only if you are using `ANSI-style joins`. If you are using the older strategy of additional join expressions in the WHERE clause, outer joins are only supported for database products that provide a proprietary native syntax for expressing outer joins. Those products are:

    - Oracle
    - Versions of Microsoft SQL Server earlier than 2012, and running in compatibility mode 80

    Default value is null

    See Also:
      - `Relations`

  - ### group

    public String group
    For use in `ComponentSchema`, indicates what group to place the property in when editing in Reify.

    Default value is null

    See Also:
      - `Component Schema`

  - ### canFilter

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

    Default value is null

    See Also:
      - `SearchForm.getShowFilterFieldsOnly()`
      - `SearchForm.getCanEditFieldAttribute()`

  - ### ignoreTextMatchStyle

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

    Default value is null

  - ### includeSummaryFunction

    public SummaryFunctionType includeSummaryFunction
    When `field.includeFrom` is specified and multiple records exist in the related DataSource per record in the including DataSource, `includeSummaryFunction` indicates which `SummaryFunctionType` is used to produce the field value.

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

    For example, given a DataSource "order" and related DataSource "orderItem", the "itemCount" field below will show the total number of items in each order.

           <DataSource ID="order">
              <fields>
                 <field name="orderID" type="integer" primaryKey="true" foreignKey="orderItem.orderID" />
                 <field name="customerName" type="text" />
                 <field name="orderDate" type="date" />
                 <field name="itemsCount" includeFrom="orderItem.quantity" includeSummaryFunction="sum" />
              </fields>
           </DataSource>

    This is analogous to the following SQL statement:

          SELECT
               order.orderID,
               order.customerName,
               order.orderDate,
               (select sum(_itemsCount.quantity)
                   from orderItem _itemsCount
                   where _itemsCount.orderID = order.orderID) as itemsCount
          FROM
               order

    The `includeSummaryFunction` feature supports indirect inclusion as well, when the field using it is included from the other DataSource via regular `includeFrom`. For example, given the "order" DataSource above and related "orderItem" DataSource, the "orderItemsCount" field below will show the total number of items in the order each order item record belongs to:

           <DataSource ID="orderItem">
              <fields>
                 <field name="id" type="integer" primaryKey="true" />
                 <field name="orderID" type="integer" foreignKey="order.orderID"/>
                 <field name="quantity" type="integer" />
                 <field name="unitPrice" type="float" />
                 <field name="orderItemsCount" includeFrom="order.itemsCount" />
              </fields>
           </DataSource>

    This is analogous to the following SQL statement:

          SELECT
               orderItem.id,
               orderItem.orderID,
               orderItem.quantity,
               orderItem.unitPrice,
               (select sum(_orderItemsCount_orderID.quantity) AS itemsCount
                  from order _orderItemsCount
                           join orderItem _orderItemsCount_orderID
                               on _orderItemsCount.orderID = _orderItemsCount_orderID.orderID
                  where orderItem.orderID = _orderItemsCount.orderID) as orderItemsCount
          FROM
               orderItem

    Note that tables in sub-select will always use `relatedTableAlias` if set or automatically generated aliases. Automatic aliases are generated according to the rule: first table in possible chain of relations being the name of the field sub-select is getting value for (with underscore "_" in front) and the rest aliases are built up using foreign key field names in the chained relations leading to the target table. This allows to avoid any conflicts with the tables/aliases from the main query. Like in the second example table "orderItem" is used in both main query without alias and sub-select under `_orderItemsCount_orderID` alias.

    Some other common uses:

    - using "max" to show the most recent "order" for a "customer"
    - using "avg" to show the average order size for a "customer"
    - using "concat" to show the names of all "salesReps" involved in an "order" (note: "concat" has limited support - see `SummaryFunctionType`).

    NOTE: `includeSummaryFunction` and `Server Summaries` cannot be used in the same `DSRequest`. If both configurations are present, Server Summaries settings always take priority.

    Default value is null

    See Also:
      - `Server Summaries`

  - ### filterOn

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

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### customCriteriaExpression

    public VelocityExpression customCriteriaExpression
    This property indicates that this field should be represented by a custom expression embedded in the WHERE clause of the generated SQL, instead of the generated expression containing this field name that would ordinarily be used. You use this property when you have to accommodate some special way of using a field's value in criteria, other than by directly comparing it to the criteria. For example, if you have a column that contains bit-packed information you will generally need to perform a bitwise AND to filter on that column, rather than an equality check. In this case, you would use a `customCriteriaExpression` something like this (in Oracle):

    `BITAND(myField, $criteria.myField)+0 = $criteria.myField`

    Or this (in MySQL or SQL Server):

    `myField & $criteria.myField = $criteria.myField`

    As this example shows, a `customCriteriaExpression` is expected to be a complete logical expression that provides both sides of the comparison. After Velocity processing, this example would result in SQL similar to this (for the MySQL case); the colored part comes entirely from the `customCriteriaExpression`:

    `SELECT myField, myOtherField FROM myTable WHERE myField & 32 = 32`

    `customCriteriaExpression` can also be used with `AdvancedCriteria`. Note that the point mentioned above, about a `customCriteriaExpression` being a complete logical expression that provides both sides of the comparison still applies. This means that when you use `customCriteriaExpression` in conjunction with `AdvancedCriteria`, you effectively switch off support for different `OperatorId`s to be used on that field, unless you use Velocity expressions containing the special `$criteriaOperator` variable (see below).

    When you use `customCriteriaExpression` with `AdvancedCriteria`, the way you access criteria values differs slightly. One option is to use the `$advancedCriteria` Velocity variable, as described in the "Using AdvancedCriteria" section of the `custom querying overview`. However, this variable only returns the value from the first `Criterion` that uses the field, as found by depth-first search. If your `AdvancedCriteria` contains multiple references to this field, this will not be satisfactory. Therefore, specifically for `customCriteriaExpression`, we provide another Velocity variable, `$criteriaValue`. This variable means "the value on a Criterion referencing this field". An example may serve to clarify this:

    Assume you need to extend the above example to filter records where a certain bit is set OR a certain other bit is set. An `AdvancedCriteria` like this would be required (note that the choice of "equals" as the operator in these clauses is completely arbitrary - as discussed above, the operator is ignored when we have a `customCriteriaExpression`, so it would make no difference to the end product if we had used different operators here):

            { _constructor: "AdvancedCriteria", operator: "or", criteria: [
                { fieldName: "myField", operator: "equals", value: 32 },
                { fieldName: "myField", operator: "equals", value: 64 },
              ]
            }

    If you used the `customCriteriaExpression` from above unchanged with this criteria, the following SQL would be generated (in the MySQL case):

    `SELECT myField, myOtherField FROM myTable WHERE myField & null = null OR myField & null = null`

    This is because `$criteria` is a variable that only works correctly with simple criteria. If you changed the `$criteria` references in the expression to `$advancedCriteria`, the generated SQL would be:

    `SELECT myField, myOtherField FROM myTable WHERE myField & 32 = 32 OR myField & 32 = 32`

    This is because `$advancedCriteria` always returns the first value it finds for a particular field, as described above. However, if you change the expression so it reads:

    `myField & $criteriaValue = $criteriaValue`

    you will now get the correct SQL generated:

    `SELECT myField, myOtherField FROM myTable WHERE myField & 32 = 32 OR myField & 64 = 64`

    Similar to `$criteriaValue`, we provide a special variable, `$criteriaOperator`. This is intended for use in Velocity expressions, so that your `customCriteriaExpression` can process different operators in different ways. How you choose to interpret an operator is entirely up to you; this variable is both advanced and rarely used. This example is contrived and does not show a usage that would be remotely likely in a real application, but it does show how to use the variable in a Velocity expression:

    `myField #if ($criteriaOperator == "greaterThan") & #else | #end $criteriaValue = $criteriaValue`

    For simple criteria, note that `$criteriaOperator` will vary depending on field type and the `textMatchStyle` in force, as follows:

    - Text fields with textMatchStyle "substring" - "iContains"
    - Text fields with textMatchStyle "startsWith" - "iStartsWith"
    - Text fields with textMatchStyle "exact" - "iEquals"
    - All other cases (including text fields with textMatchStyle "exactCase") - "equals"
    You can use Velocity expressions in your `customCriteriaExpression`s, and the `usual context variables` are available. Note that the results of Velocity evaluations are automatically quoted and escaped by default; this behavior can be switched off - see `autoQuoteCustomExpressions`, and particularly note the warnings about its use.

    Note that this property only applies to users of the Smart GWT server using dataSources of type "sql".

    Default value is null

    See Also:
      - `customSelectExpression`
      - `customUpdateExpression`
      - `customInsertExpression`
      - `autoQuoteCustomExpressions`

  - ### imageHeight

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

    Default value is null

  - ### javaClass

    public String javaClass
    Explicitly declares the Java class that should be used when data from the client is validated by the Smart GWT server and/or applied to Java Beans / POJOs via the server-side API `com.isomorphic.datasource.DataSource.setProperties()`. This includes auto-populating POJO arguments of a `DMI` method, or populating JPA/Hibernate beans with data when using the built-in JPA and Hibernate DataSources.

    For DataSources that do not use Java Beans, `javaClass` can be used to force a particular representation for validated DSRequest data (e.g. data passed to a DMI):

    - for fields declared to be of type "integer" or "float" valid settings include "BigInteger", "Long", "Integer", "Short", "Byte", "AtomicInteger", "AtomicLong", "BigDecimal", "Double"and "Float" (or rather, the fully-qualified versions of those classes, such as "java.lang.Integer" and "java.math.BigDecimal")
    - for fields declared to be of type "date" valid settings include basic "java.util.Date", "java.sql.Date" and "java.sql.Time" types as well as Joda-Time types "DateTime", "DateMidnight", "LocalDateTime", "LocalDate", "LocalTime" and Java 8 Date/Time API types "LocalDate", "LocalDateTime", "LocalTime".
    When populating Java Beans/ POJOs, `javaClass` does not normally have to be specified: Smart GWT will use Java reflection to inspect the type of argument expected by a setter method and will attempt conversion of inbound data to that type. As described in the documentation for `DataTools.setProperties()`, this works for almost all typical cases. However `field.javaClass` is useful for:
    - subobject of abstract or interface type: in this case Java Reflection is not sufficient to discover the concrete type that should be instantiated, and `javaClass` should be set instead.
    - subobject of Collection or Map type, when Java generics are not used or the Collection member type or Map value type is abstract. When Java generics are used (for example the setter takes an argument is of type Collection<SomePOJO> or Map<KeyType,SomePOJO>, Smart GWT will automatically attempt to convert inbound data to the type of the members of the Collection or values of the Map. Without generics, `javaClass` needs to be specified. Note that `javaClass` will take precedence over generics if both are used. Also note that `javaCollectionClass` can be specified if a particular Collection or Map type is needed, and `javaKeyClass` can be specified for a field of type `java.util.Map`.
    NOTE: It is also possible to make Smart GWT Server determine the javaClass to use dynamically at runtime. See the description of `DataSource.getPropertyJavaClass()` in the server documentation for details.

    Default value is null

  - ### requiredWhen

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

    On the client, criteria are evaluated against the form's current values and the current `rule context`. On the server, criteria are evaluated with full ServerDynamicCriteria support, including references to the current user and operation type (`auth.*`, `context.*`) 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>

    Default value is null

    See Also:
      - `required`
      - `Validator.applyWhen`

  - ### sqlFalseValue

    public String sqlFalseValue
    For fields of type "boolean" that specify a `sqlStorageStrategy` of "singleChar", this is the value to persist for false values. Note that the common use cases of storing booleans as T/F, Y/N and 1/0 are already catered for without the need for this property.
    For fields of type "boolean" that specify a `sqlStorageStrategy` of "string", this is the value to persist for false values that require using the entire value.

    You can specify NULL as a valid value for sqlFalseValue, using this XML notation:

          <sqlFalseValue xsi:nil="true"></sqlFalseValue>

    Default value is null

    See Also:
      - `sqlStorageStrategy`
      - `sqlTrueValue`

  - ### sqlStorageStrategy

    public String sqlStorageStrategy
    For certain field types, indicates the strategy to be used to store values to the underlying SQL column.

    Fields of type "boolean"
    The default strategy for boolean fields is to assume the underlying type of the field is text and store boolean true and false values as the character strings "true" and "false". The following additional strategies are available:

    - "number" or "integer": store true as 1, false as 0
    - "singleChar10": store true as "1", false as "0"
    - "singleCharYN": store true as "Y", false as "N"
    - "singleCharTF": store true as "T", false as "F"
    - "singleChar": store as a single character, using the values defined by `sqlTrueValue` and `sqlFalseValue`
    - "string": store the entire values defined by `sqlTrueValue` and `sqlFalseValue`

    Fields of type "date", "time", and "datetime"
    The default strategy for these types is to use a native type that supports date and time values to the nearest second; the actual type used varies by database. The following additional strategies are available:

    - "nativeDate": Use a native SQL DATE type
    - "number" or "integer": Store the value as a plain numeric value
    - "text": Store the value as a plain text value
    The "number" and "text" strategies for date/time/datetime fields are provided to allow transparent two-way mapping of legacy date values; you would not ordinarily use them in the absence of a legacy database. In both cases, the actual format of the number or text string is determined by specifying a `sqlDateFormat` on the field; if no format is specified, the framework defaults to "yyyyMMdd".

    Fields of type "text"

    NOTE: This section is only applicable for users of Microsoft SQL Server. The "ntext" strategy is ignored for all other databases.

    If you are integrating with Microsoft SQL Server, you may run into an issue with that database and double-byte character sets. Although the documentation indicates that string values are sent to the database as Unicode by default, they may undergo conversion at the database end, depending on the collation settings of the database. This Microsoft support article describes the situation, which is that Unicode is converted to the code page of the database before being used, in order to "provide backward compatibility with existing applications".

    To work around this, we provide an `sqlStorageStrategy` of "ntext". Fields that declare this strategy are inserted into queries using the "N syntax", like so:
    `UPDATE MyTable SET MyTextColumn = N'some text' WHERE MyPK = N'some key'`

    This syntax overrides defaults and forces the database to treat strings as Unicode.

    Note that declaring a field to be of `type` "ntext" is exactly equivalent to specifying type "text" and an `sqlStorageStrategy` of "ntext". If you declare a field of type "ntext" when the back-end database is something other than SQL Server, it will be treated as a normal field of type "text".

    This property only applies to users of the Smart GWT server using dataSources of type "sql".

    Default value is null

  - ### unionOf

    public String unionOf
    Only applicable to "union" dataSources, this is a comma-separated list of qualified field names, specifying how this unioned field is to be derived. This setting allows full control of the union process for fields that only exist on certain member dataSources, or that are not named in the same way on member dataSources. Consider this example:

            <DataSource type="union" unionOf="ds1,ds2,ds3">
              <fields>
                <field name="myRenamedField" unionOf="ds1.someField,ds2.someOtherField" />
              </fields>
            </DataSource>

    This field definition states that field `someField` from dataSource `ds1` should be unioned with field `someOtherField` from dataSource `ds2`, and call the resulting bonded field `myRenamedField`. Note that no reference to a field in dataSource `ds3` is provided: this means that the value of `myRenamedField` will be null for any records contributed by `ds3`.

    Also note that the above example does not provide a DataSource-level `unionFields` setting. This means that we will derive a list of fields to union by inspecting every member dataSource and unioning fields with matching names and data types (see `defaultUnionFieldsStrategy` for more details of how this is done). However, fields `ds1.someField` and `ds2.someOtherField` will not be part of the auto-derivation, because the system will see that they are being explicitly referenced in a field's `unionOf` property.

    Default value is null

    See Also:
      - `DataSource.unionFields`
      - `Union DataSources`

  - ### multipleStorage

    public MultipleFieldStorage multipleStorage
    How values for a `multiple:true` field should be stored.

    On the server, field values for `multiple:true` fields are represented as Java Lists in DSRequest and DSResponse objects, but when `multipleStorage` is used, are ultimately stored as Strings.

    This storage mechanism is "denormalized" in the sense of database normalization because the field contains a compound value rather than an atomic value. Specifically, this makes the field harder to use with database features like SQL joins, since its value cannot be directly compared to other, singular fields. For this reason, there's really only a narrow set of cases where it makes sense to use this storage mechanism, consider it if:

    - the values don't appear in any other tables or columns elsewhere in your database (so joins and other comparisons wouldn't be possible anyway)
    - there is no authoritative list of all possible values, or even of popular values; it's basically freeform, like arbitrary, uncurated "tags" applied to photos or links

    A `multiple:true` field can be of any `SimpleType`, including "date", "time", "datetime", "float", "int" etc. Type will be preserved across a store and reload cycle, so for example a List of values for a field of type "int" will arrive at the server in a DSRequest as a List of Integer, be stored as a String, but appear again as a List of Integer inside a DSResponse. When storing "date", "time" or "datetime" values as Strings, XML schema formats are used - the same that are used for transmission in XML or JSON (see `Date and Time Format and Storage overview` for details).

    The `multipleStorage` feature works by transforming from List to String and back inside the server-side DataSource.execute() method. Specifically, inbound DSRequests are transformed before methods that perform actual storage are called (executeUpdate() et al), and DSResponses received from these methods have `multiple:true` field values transformed back into Lists before DataSource.execute() returns the DSResponse.

    This transformation approach means that the built-in SQL, JPA and Hibernate connectors all support `multipleStorage`, and `multipleStorage` is also automatically available for any custom DataSource that is capable of storing String values, and implements its storage methods via overrides of executeUpdate(), executeAdd() et al as described in the `custom DataSource overview`.

    Note that when using the built-in SQL, JPA and Hibernate connectors, the underlying SQL column should be of 'text' type. The `Database Configuration Tool` will automatically generate columns of the correct type for a SQLDataSource. For JPA or Hibernate DataSources, just ensure the type of the Java bean property on your Java object is String.

    The default `multipleStorage` setting of null means that the "simpleString" `MultipleFieldStorage` approach will be used if:

    - the field is of a known `SimpleType`
    - the field is not a `foreignKey`
    Otherwise, `MultipleFieldStorage` "none" will be used.

    #### Criteria and AdvancedCriteria handling

    For the built-in SQL, JPA and Hibernate connectors, when `multipleStorage`:"simpleString" or "json" is used, criteria are transformed to replicate the client-side filtering behavior for multiple:true fields, where possible. The following operators are supported with the same behavior as client-side filtering:

    - all String-oriented operators including `pattern operators`
    - regexp / iRegexp (built-in SQL only, JPA and Hibernate do not support these. Additionally, when using PostgreSQL, regexp operators are supported only starting from PostgreSQL version 9.3)
    - isBlank / notBlank
    - isNull / notNull
    - inSet / notInSet
    - equalsField / notEqualsField / iEqualsField / iNotEqualsField
    The following operators, which are supported for client-side filtering of multiple:true fields, are not supported for server filtering when using `multipleStorage`:
    - greaterThan/lessThan(OrEqual)
    - "between" and all other operators with `OperatorValueType` of "valueRange"
    - regexp / iRegexp as noted above
    Note that for string-based filtering operators such as "equals", no characters which are part of the `multipleStorageSeparator` may be used in the filter string. If any characters from the `multipleStorageSeparator` are present in the filter value, it will always fail to match. For "json" mode, the `multipleStorageSeparator` is effectively the String '","'.

    Default value is null

  - ### otherFKs

    public String otherFKs
    In addition to regular `foreignKey` this property allows defining multiple foreign keys if the field is related to more than one DataSource.

    The format of the `otherFKs` is coma separated foreign key sets, for example: `"<firstDS>.<fieldName>,<secondDS>.<fieldName>"`. Note that this property works only in addition to the regular FK, i.e. if `foreignKey` is not set, then foreign keys defined in `otherFKs` will be completely ignored. If `otherFKs` is specified, it can include the value of the `foreignKey` attribute or it can omit it, listing only additional foreignKeys. There is no impact on functionality from doing it either way.

    For example, perhaps you have a `moneyTransfer` DataSource where each record represents a money transfer, which has `receipt` and `invoice` information stored in `receiptDS` and `receiverDS` DataSources. Each money transfer is linked to a receipt and an invoice records through the same `transferDS.id` field via the foreign keys defined in `foreignKey` and `otherFKs` properties:

          <DataSource ID="moneyTransfer" ... >
               <field name="id" primaryKey="true"
                   foreignKey="receiptDS.id"
                   otherFKs="invoiceDS.id"/>
               <field name="receiptInfo" includeFrom="receiptDS.info"/>
               <field name="invoiceInfo" includeFrom="invoiceDS.info"/>
          </DataSource>

    Here, we are including from two different related `DataSources` using the same `foreignKey` field.

    Note that `otherFKs` feature is meant to be used in more complex scenarios (see below), so if the example above is all that's needed, then there's no need to use `otherFKs` feature. The result would be the same as if foreign keys would be declared at the "other side", i.e. in `receiptDS` and `invoiceDS` DataSources via regular `foreignKey` property.

    If we extend the sample above with a `parentId` joining the `moneyTransfer` DataSource (so called "self-join" relation) and include from `receiptDS` and `invoiceDS` for the "parent" money transfer as well, then `otherFKs` feature must be used. The following declarations would be required to get receipt and invoice information for both the original money transfer and its "parent":

          <field name="id" primaryKey="true" foreignKey="receiptDS.id" otherFKs="invoiceDS.id"/>
          <field name="receiptInfo" includeFrom="receiptDS.info"/>
          <field name="invoiceInfo" includeFrom="invoiceDS.info"/>
          <field name="parentId" foreignKey="moneyTransfer.id" relatedTableAlias="parent"/>
          <field name="parentReceiptInfo" includeFrom="moneyTransfer.receiptDS.info"/>
          <field name="parentInvoiceInfo" includeFrom="moneyTransfer.invoiceDS.info"/>

    ### SQL Templating and `otherFKs`

    Similar to the `includeVia`, `otherFKs` feature uses SQL table aliases in the generated SQL when generating multiple SQL joins to the same SQL table. When using `SQL Templating`, it's sometimes necessary to know the names of the aliases in the generated SQL. See the "Automatically generated table aliases" section of the `SQL Templating` for the complete set of general rules how aliases are generated.

    The `otherFKs` feature uses aliases constructed from two parts:
    - the `field name`, which otherFKs property is defined on;
    - the related `DataSource ID` or the `DataSource.relatedTableAlias` if set.

    So, in the extended sample above the aliases for the "parent" money transfer related tables would be "parent_id" (regular FK) and "parent_id_invoiceDS" (other FK).

    See below the same sample extended with the `detailDS` DataSource storing multiple records per money transfer, joined to `moneyTransfer` DataSource on a one-to-many basis, and include receipt and invoice information for money transfer and its "parent". Also, we'll add `relatedTableAliases` to the invoice DataSource, see all related declarations below:

          <DataSource ID="detailDS" ... >
               <field name="id" type="integer" primaryKey="true" >
               <field name="name"/>
               <field name="mtId" foreignKey="moneyTransfer.id" relatedTableAlias="main"/>
               <field name="mainReceipt" includeFrom="moneyTransfer.receiptInfo" includeVia="mtId"/>
               <field name="mainInvoice" includeFrom="moneyTransfer.invoiceInfo" includeVia="mtId"/>
               <field name="mainParentReceipt" includeFrom="moneyTransfer.parentReceiptInfo" includeVia="mtId"/>
               <field name="mainParentInvoice" includeFrom="moneyTransfer.parentInvoiceInfo" includeVia="mtId"/>
          </DataSource>

          <DataSource ID="receiptDS" ... >
               <fields>
                   <field name="id" primaryKey="true"/>
                   <field name="info"/>
               </fields>
          </DataSource>

          <DataSource ID="invoiceDS" relatedTableAlias="invoice" ... >
               <fields>
                   <field name="id" primaryKey="true"/>
                   <field name="info"/>
               </fields>
          </DataSource>

    Generated aliases for the receipt/invoice tables will be `main_id`, `main_id_invoice` for the money transfer and `main_parent_id`, `main_parent_id_invoice` for the "parent" money transfer.

    ### `otherFKs` + `includeVia`

    The `otherFKs` and the `includeVia` features may be used together in even more complex scenarios. In the example below we extend `detailDS` DataSource with a link to the "previous" money transfer and include all of its receipt/invoice information:

          <field name="mtPrevId" foreignKey="moneyTransfer.id" relatedTableAlias="prev"/>
          <field name="prevReceipt" includeFrom="moneyTransfer.receiptInfo" includeVia="mtPrevId"/>
          <field name="prevInvoice" includeFrom="moneyTransfer.invoiceInfo" includeVia="mtPrevId"/>
          <field name="prevParentReceipt" includeFrom="moneyTransfer.parentReceiptInfo" includeVia="mtPrevId"/>
          <field name="prevParentInvoice" includeFrom="moneyTransfer.parentInvoiceInfo" includeVia="mtPrevId"/>

    Additionally generated aliases will be `prev_id`, `prev_id_invoice` for the money transfer and `prev_parent_id`, `prev_parent_id_invoice` for the "parent" money transfer.

    The inclusions may as well be indirect like shown below and they would produce same chains of relations, so the generated SQL and table aliases will be the same as above.

          <field name="mtPrevId" foreignKey="moneyTransfer.id" relatedTableAlias="prev"/>
          <field name="prevReceipt" includeFrom="moneyTransfer.receiptDS.info" includeVia="mtPrevId"/>
          <field name="prevInvoice" includeFrom="moneyTransfer.invoiceDS.info" includeVia="mtPrevId"/>
          <field name="prevParentReceipt" includeFrom="moneyTransfer.moneyTransfer.receiptDS.info" includeVia="mtPrevId"/>
          <field name="prevParentInvoice" includeFrom="moneyTransfer.moneyTransfer.invoiceDS.info" includeVia="mtPrevId"/>

    Default value is null

    See Also:
      - `otherFKs`
      - `DataSource.relatedTableAlias`
      - `includeVia`
      - `Relations`

  - ### editWhen

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

    Default value is null

    See Also:
      - `readOnlyWhen`
      - `Component Binding`

  - ### implicitSequence

    public Boolean implicitSequence
    For a field of `type` "sequence" on a DataSource with `serverType:"sql"`, this flag indicates that the field is implicitly bound to a sequence. This setting means that Smart GWT does not expect to find a value for the field in "add" operations, even if it is marked as a `primaryKey`, as such fields usually are. It also means that Smart GWT does not attempt to retrieve the field value from an actual database sequence, instead relying on the JDBC driver to return the generated value (see the note on `sequenceMode` below).

    Implicitly bound columns are a syntactic convenience provided by some databases to simulate the "auto-increment" or "identity" columns available natively in other products, without the underlying sequence having to be explicitly referenced in SQL queries. Currently, these database products support this idea:

    - PostgreSQL has had a "serial" column type for a long time - http://www.postgresql.org/docs/9.3/static/datatype-numeric.html#DATATYPE-SERIAL
    - DB2 has long supported a "GENERATED AS IDENTITY" notation for numeric fields. This may or may not be implemented with a sequence - the documentation does not specify - but we support it via the implicitSequence mechanism because it is so similar to the implicit sequence approach in Oracle. http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/index.jsp?topic=%2Fcom.ibm.db2z10.doc.apsg%2Fsrc%2Ftpc%2Fdb2z_identitycols.htm
    - Oracle introduced a "GENERATED AS IDENTITY" notation for numeric fields in version 12c - http://www.oracle-base.com/articles/12c/identity-columns-in-oracle-12cr1.php
    If you have columns like these in your database, declare them as type "sequence" and mark them with the `implicitSequence` flag.

    NOTE: If you use this property, you should also set the `DataSource sequenceMode` to "jdbcDriver". This is necessary because Smart GWT cannot directly query the implicit sequence that is being used behind the scenes, so we must rely on the JDBC driver to do that.

    If you use `autoDeriveSchema` to automatically derive a dataSource from table metadata, Smart GWT attempts to identify these special Oracle and Postgres columns by heuristic examination of the metadata. When it identifies such a column, it marks the corresponding dataSourceField `implicitSequence: true`, and changes the sequenceMode on the DataSource to "jdbcDriver". If your table contains one of these columns and Smart GWT does not automatically identify it, bear in mind that you can always set this flag manually, even if you are using `autoDeriveSchema`.

    This setting has no effect for non-SQL dataSources, or for databases other than those mentioned above.

    Default value is null

    See Also:
      - `DataSource.sequenceMode`
      - `SQL DataSources`

  - ### decimalPad

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

    Default value is null

    See Also:
      - `Appearance overview and related methods`

  - ### customInsertExpression

    public VelocityExpression customInsertExpression
    This property is similar to `customUpdateExpression`; its value is used during "add" operations. If you do not specify this property, but do specify a `customUpdateExpression`, the `customUpdateExpression` is used instead.

    Everything that applies to `customUpdateExpression` also applies to this property, including the observation that fields which specify a `customSelectExpression` but no corresponding `customUpdateExpression` or `customInsertExpression`, will be ignored when adding new records.

    As with `customUpdateExpression`, this property is only intended to be used when you have a need to customize the actual SQL. If you simply want to use a server-derived value in the query, you should use `Transaction Chaining`, `DMI`, or a `server script` instead.

    ### `customInsertExpression` with `primaryKey` fields

    if you use `customInsertExpression` to derive a value for a `primaryKey` field, the key value will not by default be available to the framework, so the built-in cache synchronization system will not work. It may be possible to to work around this with the `autoGenerated` flag, as described below, but otherwise you must also create a `cacheSyncOperation` which can retrieve the record just added to the database. Please also see the documentation for `SequenceMode "none"`, which talks further about cacheSyncOperation.

    Typically, `primaryKey` fields that need to be auto-generated are implemented using a sequence field, which at the database level translates to either an actual sequence, or an auto-increment or "identity" column. JDBC drivers have special support for such columns, so we are able to determine the generated value. This is important for primaryKey fields because, without it, we cannot re-fetch the record just inserted for cache synchronization purposes, as described above. Where a value is generated by something other than a sequence field, this special ability is lost - or at least, it is no longer guaranteed to be present.

    There are use cases where this may seem to be a restriction. A common case would be where you wish to use a generated UUID as primaryKey value, rather than an ordinary ascending sequence. If you had intended to do this using the database itself - for example, specifying a `customInsertExpression` that calls something like MySQL's `UUID()` built-in function - this is potentially a problem. What we would recommend in this case and anything similar, is to use the general ability for field values to be generated by application code, as described above. (Note, if you want to have application code generate values for primaryKey fields, you may need to use an `operationBinding` that specifies `providesMissingKeys`).

    That said, different database vendors implement their JDBC drivers in different ways, and with the SQLDataSource and certain database products it is possible to retrieve values that were generated at the database level by a `customInsertExpression` that expresses either a user-defined function call or an inline subselect, as long as the field is marked with the `autoGenerated` flag. Because this behavior is potentially useful, we do not inhibit it; however, we also do not recommend that you make use of it, because the behavior is not portable across databases, and may also not be portable across JDBC driver versions (because the behavior is unspecified and undocumented, and relies on implementation details that may change). Databases where this behavior has been observed to work include Oracle, Postgres and HSQLDB; databases where this behavior is known not to work include MySQL, SQL Server, DB2 and Firebird (the latter because its JDBC driver does not support the `getGeneratedKeys()` API). Note that in order to retrieve values that were generated at database level `SequenceMode` needs to be set to "jdbcDriver" via `DataSource.sequenceMode` or via "sql.MyDatabase.sequence.mode" `SQL setting`.

    Note that this property only applies to users of the Smart GWT server using dataSources of type "sql".

    Default value is null

    See Also:
      - `customUpdateExpression`
      - `customSelectExpression`
      - `customCriteriaExpression`
      - `autoQuoteCustomExpressions`

  - ### readOnlyWhen

    public 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 on the server, including references to the current user, operation type, and fields on related DataSources.

    Default value is null

    See Also:
      - `editWhen`
      - `canEdit`
      - `Component Binding`

  - ### sqlTrueValue

    public String sqlTrueValue
    For fields of type "boolean" that specify a `sqlStorageStrategy` of "singleChar", this is the value to persist for true values. Note that the common use cases of storing booleans as T/F, Y/N and 1/0 are already catered for without the need for this property.
    For fields of type "boolean" that specify a `sqlStorageStrategy` of "string", this is the value to persist for true values that require using the entire value.

    Default value is null

    See Also:
      - `sqlStorageStrategy`
      - `sqlFalseValue`

  - ### pluralTitle

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

    Default value is null

    See Also:
      - `DataSource.pluralTitle`

  - ### expensive

    public Boolean expensive
    Explicitly marks a field as expensive or inexpensive to fetch, overriding the default heuristics used by the server-side `DataSource.isExpensive()` method.

    When `DSRequest.addInexpensiveFields` is active, the server automatically expands the requested `DSRequest.outputs` to include all fields not considered expensive. By default, the following types of fields are considered expensive:

    - `Binary` fields with `encodeInResponse` set
    - Text fields with a declared `length` exceeding the server threshold (default 255; configurable via `sql.expensiveFieldLengthThreshold` in `server.properties`)
    - Fields with a `outputWhen` setting
    - Fields marked `detail:true`
    - `includeFrom` fields whose SQL join is not already required by other requested fields

    Setting `expensive:true` forces a field to be treated as expensive even if no default heuristic applies ? for example, a field with a costly `customSelectExpression` or one that triggers an expensive database operation.

    Setting `expensive:false` forces a field to be treated as inexpensive even if a heuristic would otherwise flag it ? for example, an `includeFrom` field that is always needed regardless of whether its join is required by other fields.

    When this property is unset (the default), the server's `isExpensive()` method applies its default heuristics.

    Default value is null

    See Also:
      - `com.smartgwt.client.data.DSRequest#getAddInexpensiveFields`
      - `outputWhen`
      - `ListGrid.getFetchFields()`

  - ### multipleValueSeparator

    public String multipleValueSeparator
    For fields that are `multiple:true`, the separator used between values when they are displayed.

    Default value is ", "

  - ### updateRequiresRole

    public String updateRequiresRole
    Comma-separated list of user roles that are allowed to update this field. If the current user does not have any of the roles listed, the system will not allow this field to be updated.

    NOTE: This property only prevents a field from being updated; initialization will still be allowed. You should only use this property if you have a special requirement; ordinarily, use `editRequiresRole`, which applies security for both types of write.

    Default value is null

    See Also:
      - `editRequiresAuthentication`
      - `editRequiresRole`
      - `initRequires`
      - `Field-Level Security`

  - ### formula

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

    Default value is null

  - ### editRequires

    public VelocityExpression editRequires
    Indicates that the specified `VelocityExpression` must evaluate to true if writes to this field are to be allowed. If the specified expression does not evaluate to true, the field will be removed from the request as described for `editRequiresAuthentication`.

    In addition to the normal context variables available to Velocity expressions in Smart GWT, expressions you write for field-level `requires` clauses - `editRequires`, `viewRequires`, `initRequires` and `updateRequires` - can reference two additional variables: `$fieldName` and `$dsName`. These are the names of the dataSource and field currently undergoing `requires` checks. They are helpful because they allow you to write a generic checker function that can be used to handle `requires` checks for multiple fields and dataSources.

    NOTE: This property prevents both initialization and updates for a field. If you have a need to prevent just initialization or just updates, you can use `initRequires` or `updateRequires`.

    Default value is null

    See Also:
      - `editRequiresAuthentication`
      - `editRequiresRole`
      - `viewRequires`
      - `Field-Level Security`

  - ### foreignDisplayField

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

    Default value is null

    See Also:
      - `Relations`

  - ### batchUploadOperationId

    public String batchUploadOperationId
    Used to look up key values for fields with `importStrategy.display` while importing data using `BatchUploader` or `DataImport` server-side API.

    Normally key values are looked up performing "fetch" operation on related data source, but setting `batchUploadOperationId` allows to control which operation will be performed. This can be useful to avoid unnecessary load when importing big data sets, if default "fetch" operation is too heavy.

    By default the look up is not case sensitive but this can be controlled through the `batchUploadCaseSensitive` attribute.

    Default value is null

  - ### exportTitle

    public String exportTitle
    Optional different field-title used for exports.

    Default value is null

  - ### displayField

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

    Default value is null

    See Also:
      - `Relations`

  - ### nillable

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

    Default value is null

  - ### uploadFieldName

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

    Default value is null

  - ### encodeInResponse

    public Boolean encodeInResponse
    When set for a field with binary data, binary data will be delivered as a Base64 encoded string.

    When `encodeInResponse` is not set normal responses will not contain values for binary fields at all. Instead, UI components, such as `TileGrid` issue a second binary fetch for binary data when appropriate, and APIs such as `downloadFile()` and `viewFile()` can be used to programmatically trigger downloads.

    Only applicable to fields of a type that are represented by binary data (currently "binary" and "imageFile", see `FieldType`).

    Default value is null

  - ### imageSize

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

    Default value is null

  - ### defaultOperator

    public OperatorId defaultOperator
    The default search-operator for this field.

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

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### precision

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

    Default value is null

    See Also:
      - `Appearance overview and related methods`

  - ### importStrategy

    public FieldImportStrategy importStrategy
    Declares the `FieldImportStrategy` for this field. The default setting of null has the same meaning as "auto". Note, this attribute only has an effect if all of the following are true:
    - The field declares a `foreignKey`
    - The field declares a `displayField`
    - The displayField so declared is `included from` the same DataSource that the `foreignKey` declaration refers to
    In any other circumstances, this attribute is ignored.

    `importStrategy` is applied by the server-side `DataImport.importToRows()` method, which is in turn used by `BatchUploader` and several other DataImport APIs such as `importToDataSource()`, `importDataSourceRecords()` and `importAndValidateDSRows()`. See the server-side documentation for details of these APIs. The actual data transformation is carried out by the server-side API `DataSource.transformImportValue()`; this method can be overridden to carry out any other transformation you may require.

    Default value is null

    See Also:
      - `batchUploadOperationId`

  - ### childrenProperty

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

    Default value is false

    See Also:
      - `DataSource.childrenField`
      - `Relations`

  - ### multiple

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

    Default value is false

    See Also:
      - `Component Schema`

  - ### outputWhen

    public OutputWhen outputWhen
    Specifies, for this field only, the type of condition field must match to be fetched from underlying source of data and delivered to the client.

    This setting overrides the `DSRequest.outputs`, meaning that if field is included in request.outputs, but does not match outputWhen condition, it won't be fetched and delivered to the client.

    This setting does not affect `OperationBinding.outputs`, meaning that if field is explicitly listed in operationBinding.outputs, then it will be fetched and delivered to the client regardless of outputWhen condition.

    Note that `binary field` values (InputStream, byte[], Blob) are automatically omitted from normal fetch responses even when this setting allows the field to be delivered. See the `Binary Fields overview` for details and the `encodeInResponse` option for delivering binary data as Base64.

    Note that fields with an `outputWhen` setting are also considered `expensive` by default when `DSRequest.addInexpensiveFields` is active, since the presence of conditional output logic implies the field has a cost concern.

    Default value is null

    See Also:
      - `OperationBinding.outputs`
      - `DSRequest.getOutputs()`
      - `expensive`

  - ### lenientXPath

    public Boolean lenientXPath
    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.

    Default value is null

  - ### tableName

    public String tableName
    Only applicable to "sql" dataSources, setting `tableName` indicates that this field will be coming from another table by way of a `customized SQL query`.

    By default, the SQL generator will not include this field in generated SQL for "add" or "update" operations. It will include the field in the SELECT clause and WHERE clause of customized "fetch" operations, where it is expected that you will make the table available via a custom <tableClause> as shown in this sample.

    The table name will also be used to qualifying the column name unless `DataSource.qualifyColumnNames` or `OperationBinding.qualifyColumnNames` has been disabled.

    Note: This property is only required when including fields from tables other than the default table specified by `DataSource.tableName`.

    Default value is null

    See Also:
      - `nativeName`

  - ### type

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

    Default value is null

  - ### viewRequires

    public VelocityExpression viewRequires
    Indicates that the specified `VelocityExpression` must evaluate to true if values for the field are to be fetched. If the specified expression does not evaluate to true, the field will be dropped as described for `viewRequiresAuthentication`.

    In addition to the normal context variables available to Velocity expressions in Smart GWT, expressions you write for field-level `requires` clauses - `viewRequires`, `editRequires`, `initRequires` and `updateRequires` - can reference two additional variables: `$fieldName` and `$dsName`. These are the names of the dataSource and field currently undergoing `requires` checks. They are helpful because they allow you to write a generic checker function that can be used to handle `requires` checks for multiple fields and dataSources.

    Default value is null

    See Also:
      - `viewRequiresAuthentication`
      - `viewRequiresRole`
      - `editRequires`
      - `Field-Level Security`

  - ### detail

    public 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()`).

    Default value is false

    See Also:
      - `Component Binding`

  - ### fkTableCode

    public String fkTableCode
    See `DataSource.tableCode`.

    Default value is null

  - ### propertiesOnly

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

    Default value is null

    See Also:
      - `Component Schema`

  - ### format

    public FormatString 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()`.

    Default value is null

    See Also:
      - `exportFormat`

- ## Constructor Details

  - ### DataSourceField

    public DataSourceField()