DataSourceField (Smart GWT LGPL Edition API 6.1p (2024-07-30))

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

```
public class DataSourceField
extends java.lang.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 and Description
`java.lang.Boolean`	`allowClientRequestedSummaries` Affects whether client dsRequests can request summaries for this field.
`boolean`	`audit` Setting `audit` to `false` explicitly indicates that this field will not be saved to the audit DataSource when `auditing` is enabled.
`java.lang.Boolean`	`autoGenerated` Indicates that values for this field are automatically generated by the database or ORM provider.
`java.lang.String`	`batchUploadOperationId` Used to look up key values for fields with `importStrategy.display` while importing data using `BatchUploader` or `DataImport` server-side API.
`java.lang.Boolean`	`canEdit` Controls whether, by default, DataBoundComponents consider this field editable.
`java.lang.Boolean`	`canExport` Dictates whether the data in this field be exported.
`java.lang.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.
`java.lang.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.
`java.lang.Boolean`	`canView` If false, this property indicates that this field is considered "server only".
`java.lang.Boolean`	`childrenProperty` If true, this property indicates that this field will hold an explicit array of child nodes for the current node.
`java.lang.String`	`childTagName` For a field that is `multiple:"true"`, controls the name of the XML tag used for each subelement during `DataSource.xmlSerialize()`.
`java.lang.String`	`columnCode` See `DataSource.tableCode`.
`java.lang.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`.
`java.lang.Integer`	`decimalPad` Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.
`java.lang.Integer`	`decimalPrecision` Applies only to fields of type "float" and affects how many significant digits are shown.
`boolean`	`detail` Whether this field should be considered a "detail" field by a `DataBoundComponent`.
`java.lang.String`	`displayField` Name of another field in this DataSource that should be used as the display value for this field.
`DateDisplayFormat`	`displayFormat` The default date formatter to use for displaying this field.
`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.
`java.lang.Boolean`	`editRequiresAuthentication` Whether a user must be authenticated in order to write to this field.
`java.lang.String`	`editRequiresRole` Comma-separated list of user roles that are allowed to write to this field.
`HTMLString`	`emptyDisplayValue` Text to be used for display by client-side components when this field has a null or undefined value.
`java.lang.Boolean`	`encodeInResponse` When set for a field with binary data, binary data will be delivered as a Base64 encoded string.
`java.lang.Boolean`	`escapeHTML` When data values are displayed in DataBound components, by default strings will be interpreted as HTML by the browser in most cases.
`FormatString`	`exportFormat` An optional `FormatString` for this field, for use when `exporting` data to spreadsheet formats (XLS and OOXML/XLSX), XML, JSON or CSV.
`java.lang.String`	`exportTitle` Optional different field-title used for exports.
`FormItem`	`filterEditorType` Sets the default FormItem to be used for this field if it appears in a filter row, and `canFilter` is not false.
`java.lang.String`	`fkColumnCode` See `DataSource.tableCode`.
`java.lang.String`	`fkTableCode` See `DataSource.tableCode`.
`java.lang.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.
`java.lang.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()`.
`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.
`java.lang.String`	`group` For use in `ComponentSchema`, indicates what group to place the property in when editing in Visual Builder.
`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.
`java.lang.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.
`java.lang.Integer`	`imageHeight` Height of the image-content of this field.
`java.lang.Integer`	`imageSize` Width and height of the image-content of this field.
`java.lang.Integer`	`imageWidth` Width of the image-content of this field.
`java.lang.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.
`java.lang.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.
`java.lang.String`	`includeFrom` Indicates 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.
`java.lang.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.
`java.lang.Boolean`	`initRequiresAuthentication` Whether a user must be authenticated in order to initialize to this field.
`java.lang.String`	`initRequiresRole` Comma-separated list of user roles that are allowed to initialize this field.
`java.lang.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()`.
`java.lang.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.
`java.lang.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.
`java.lang.Integer`	`length` Maximum number of characters allowed.
`java.lang.Boolean`	`lenientXPath` Indicates that getting `valueXPath` for this field should not perform any validation at all and will return null for non existing XPaths.
`java.lang.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.
`java.lang.String`	`mimeType` For a `binary field`, sets a fixed mime type for all files stored to this field.
`java.lang.Boolean`	`multiple` Indicates that this field should always be Array-valued.
`MultipleFieldStorage`	`multipleStorage` How values for a `multiple:true` field should be stored.
`java.lang.String`	`multipleStorageSeparator` For fields that are `multiple:true` and use `multipleStorage`, the separator used in the "simpleString" `MultipleFieldStorage` mode.
`java.lang.String`	`multipleValueSeparator` For fields that are `multiple:true`, the separator used between values when they are displayed.
`FieldName`	`name` Name for this field.
`java.lang.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:
`java.lang.Integer`	`precision` Applies only to fields of type "float" or "integer" and affects how many significant digits are shown.
`boolean`	`primaryKey` Indicates either that this field holds a value unique across all records in this DataSource, 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 DataSource.
`java.lang.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.
`java.lang.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.
`java.lang.Object`	`rootValue` For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
`java.lang.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.
`java.lang.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.
`java.lang.String`	`sortByField` Causes values for this field to be sorted according to values for another field, for both client- and server-side sorting.
`java.lang.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.
`java.lang.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.
`java.lang.String`	`title` Default user-visible title for this field.
`FieldType`	`type` Type of this field.
`VelocityExpression`	`updateRequires` Indicates that the specified `VelocityExpression` must evaluate to true if updates to this field are to be allowed.
`java.lang.Boolean`	`updateRequiresAuthentication` Whether a user must be authenticated in order to update to this field.
`java.lang.String`	`updateRequiresRole` Comma-separated list of user roles that are allowed to update this field.
`java.lang.String`	`uploadFieldName` Used by the `BatchUploader` to map a field in an upload file to this dataSourceField.
`java.lang.Boolean`	`useLocalDisplayFieldValue` If this field has a specified `displayField`, this attribute allows you to explicitly tell editor components to pick up the display-field value from the record currently being edited, rather than fetching against a specified `FormItem.optionDataSource`.
`Validator[]`	`validators` Validators to be applied to this field.
`OperatorId[]`	`validOperators` List of operators valid on this field.
`java.util.Map`	`valueMap` A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.
`java.lang.String`	`valueMapEnum` Fully qualified Java className of an Enum that should be used to derive this field's `com.smartgwt.client.types.ValueMap`.
`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.
`java.lang.Boolean`	`viewRequiresAuthentication` Whether a user must be authenticated in order to fetch this field.
`java.lang.String`	`viewRequiresRole` Comma-separated list of user roles that are allowed to fetch this field.
`java.lang.Boolean`	`xmlAttribute` Indicates that `DataSource.xmlSerialize()` should serialize this value as an XML attribute.

Constructor Summary

Constructors
Constructor and Description

DataSourceField()

Constructors
Constructor and Description
`DataSourceField()`

Method Summary
- Methods inherited from class java.lang.Object
  clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

maxFileSize
```
public java.lang.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

autoGenerated
```
public java.lang.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 java.lang.String columnCode
```
See DataSource.tableCode.
Default value is null

valueMap
```
public java.util.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 java.lang.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, FieldLevelAuth overview and related methods

includeFrom
```
public java.lang.String includeFrom
```
Indicates this field should be fetched from another, related DataSource.
The incluedFrom 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. For including from a related DataSource where there are multiple related records, see includeSummaryFunction.
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).
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. Setting useLocalDisplayFieldValue to true will ensure the display field value is picked up from the record currently being edited:
```
  <field name="managerId" foreignKey="employee.id" displayField="managerName"  useLocalDisplayFieldValue="true"/> 
  <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.
- 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.
Default value is null
See Also:

DataSourceRelations overview and related methods

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:

ClientDataIntegration overview and related methods

displayFormat
```
public DateDisplayFormat displayFormat
```
The default date formatter to use for displaying this field. Only applicable to fields of type "date" and "datetime". Note that this property is honored when exporting directly to Excel spreadsheets (ie, when using XLS or XLSX/OOXML form, not CSV); "date" and "datetime" fields with this property set will deliver real dates and formatting information to Excel, rather than formatted strings or unformatted dates.
Default value is null

relatedTableAlias
```
public java.lang.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. This is 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.
Default value is null

See Also:

includeVia, DataSourceRelations overview and related methods

useLocalDisplayFieldValue
```
public java.lang.Boolean useLocalDisplayFieldValue
```
If this field has a specified displayField, this attribute allows you to explicitly tell editor components to pick up the display-field value from the record currently being edited, rather than fetching against a specified FormItem.optionDataSource.
See FormItem.useLocalDisplayFieldValue for more detail.
Note that for the common pattern described here of having an editable foreignKey field with a static display value (derived from a displayField with 'includeFrom' set), the framework will automatically default this property to true if not explicitly specified in the dataSource configuration file.
Default value is null

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 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 java.lang.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:

SqlDataSource overview and related methods

escapeHTML
```
public java.lang.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 java.lang.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, FieldLevelAuth overview and related methods

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.
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. 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 "¤" (¤) 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.
Default value is null
See Also:

format

title
```
public java.lang.String title
```
Default user-visible title for this field.
This will be picked up by DataBound components and other views over this DataSource.
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 dataSource, the ListGridField.headerTitle attribute may be used to specify a different string for display in the listGrid column header.
Default value is null

See Also:

ComponentBinding overview and related methods

multipleStorageSeparator
```
public java.lang.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.
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.
Default value is null

See Also:

Basics overview and related methods

javaCollectionClass
```
public java.lang.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
- org.apache.commons.collections.map.LinkedMap 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

rootValue
```
public java.lang.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:

DataSourceRelations overview and related methods

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

creatorOverrides
```
public java.lang.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, FieldLevelAuth overview and related methods

audit
```
public boolean audit
```
Setting audit to false explicitly indicates that this field will not be saved to the audit DataSource when auditing is enabled.
Default value is true

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:

ComponentBinding overview and related methods

editRequiresRole
```
public java.lang.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 also see editRequiresAuthentication for details of how declarative field-level security settings can be overridden per-request.
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, FieldLevelAuth overview and related methods

canExport
```
public java.lang.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 java.lang.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 java.lang.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 also see viewRequiresAuthentication for details of how declarative field-level security settings can be overridden per-request.
Default value is null

See Also:

viewRequiresAuthentication, editRequiresRole, FieldLevelAuth overview and related methods

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.
Default value is null

See Also:

ClientDataIntegration overview and related methods

includeVia
```
public java.lang.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 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".
Note that Oracle has a limit of 30 characters on identifier names. We limit table aliases to 30 characters all databases despite actual database in use to support portability across databases. If the generated table alias would exceed 30 chars, we instead use a generated and unpredictable value like "a123". To avoid hitting this limit for the advanced cases discussed above:
- use relatively short strings for relatedTableAlias
- for rare, multi-step inclusion scenarios where multiple field names are used as a prefix, if field names are very long in order to match database column names, you can use a shorter field name and use nativeName to specify the underlying column name (this is demonstrated in samples above - note field "mtPrevId")
Default value is null
See Also:

relatedTableAlias, DataSourceRelations overview and related methods

stringInBrowser
```
public java.lang.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 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 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, which is not the case by default. 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:

DataSourceRelations overview and related methods

group
```
public java.lang.String group
```
For use in ComponentSchema, indicates what group to place the property in when editing in Visual Builder.
Default value is null

See Also:

ComponentSchema overview and related methods

mimeType
```
public java.lang.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.
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:

ClientDataIntegration overview and related methods

canFilter
```
public java.lang.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.

Default value is null

See Also:

SearchForm.getShowFilterFieldsOnly(), SearchForm.getCanEditFieldAttribute()

ignoreTextMatchStyle
```
public java.lang.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

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, FieldLevelAuth overview and related methods

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, give 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(orderItem.quantity)
           from orderItem
           where orderItem.orderID = order.orderID) as itemsCount
  FROM
       order
  
```
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:

com.smartgwt.client.types.SummaryFunction, ServerSummaries overview and related methods

sortByField
```
public java.lang.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

storeMilliseconds
```
public java.lang.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
- 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 java.lang.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, ComponentBinding overview and related methods

imageHeight
```
public java.lang.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

showFileInline
```
public java.lang.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

javaClass
```
public java.lang.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, fields declared to be of type "integer" or "float" can use javaClass to force a particular numeric representation for validated DSRequest data (e.g. data passed to a DMI). Valid settings include "BigInteger", "Long", "Integer", "Short", "Byte", "AtomicInteger", "AtomicLong", "BigDecimal", "Double", "Float".
When populating Java Beans/ POJOs, javaClass does not normally have to 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

javaKeyClass
```
public java.lang.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 java.lang.String fkColumnCode
```
See DataSource.tableCode.
Default value is null

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, but not regexp/iRegexp
- 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

childTagName
```
public java.lang.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:

ComponentSchema overview and related methods

canView
```
public java.lang.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:

ComponentBinding overview and related methods

implicitSequence
```
public java.lang.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, SqlDataSource overview and related methods

viewRequiresAuthentication
```
public java.lang.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. 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 DataBoundComponents 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, FieldLevelAuth overview and related methods

decimalPad
```
public java.lang.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

foreignKey
```
public java.lang.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.
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:
```
    isc.DataSource.create({
      ID:"supplyItem",
      fields : [
        {name:"itemId", type:"sequence", primaryKey:true},
        {name:"parentId", type:"integer", foreignKey:"itemId"},
        ...
      ]
    });
  
```
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, DataSourceRelations overview and related methods

validOperators
```
public OperatorId[] validOperators
```
List of operators valid on this field.
If not specified, all operators that are valid for the field type are allowed.
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:

ComponentBinding overview and related methods

inapplicable
```
public java.lang.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 VisualBuilder. 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:

ComponentSchema overview and related methods

decimalPrecision
```
public java.lang.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
```
Indicates either that this field holds a value unique across all records in this DataSource, 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 DataSource. 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 DataSource, 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:

DataSourceRelations overview and related methods

allowClientRequestedSummaries
```
public java.lang.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, ServerSummaries overview and related methods

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, FieldLevelAuth overview and related methods

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:

ComponentBinding overview and related methods

multipleValueSeparator
```
public java.lang.String multipleValueSeparator
```
For fields that are multiple:true, the separator used between values when they are displayed.
Default value is ", "

xmlAttribute
```
public java.lang.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:

ComponentSchema overview and related methods

updateRequiresRole
```
public java.lang.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, FieldLevelAuth overview and related methods

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, FieldLevelAuth overview and related methods

foreignDisplayField
```
public java.lang.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.
This property is useful for fields being edited in a FormItem where options are being retrieved from an FormItem.optionDataSource, for the case where a separate displayField name is used within the local dataSource than the field name for the display field within the foreign dataSource.
See FormItem.foreignDisplayField for more on this, and see includeFrom for a discussion about picking up dataSource field values from a related dataSource.
Default value is null

See Also:

DataSourceRelations overview and related methods

batchUploadOperationId
```
public java.lang.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.
Default value is null

exportTitle
```
public java.lang.String exportTitle
```
Optional different field-title used for exports.
Default value is null

displayField
```
public java.lang.String displayField
```
Name of another field in this DataSource that should be used as the display value for this field.
Typically used for editable foreignKey fields: the foreignKey field stores an ID value, and this ID value is the right value to use when editing (typically by a SelectItem with optionDataSource set). However, when the foreignKey field is viewed read-only, it should display a name, title or other friendly value from the related record. In order to accomplish this, a second, hidden field carries the display value, and the foreignKey field has displayField set to this second, hidden field.
For a more in-depth discussion, see includeFrom.
Default value is null

See Also:

DataSourceRelations overview and related methods

initRequiresRole
```
public java.lang.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, FieldLevelAuth overview and related methods

nillable
```
public java.lang.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.
Default value is null

uploadFieldName
```
public java.lang.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

length

public java.lang.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 ***
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()

encodeInResponse
```
public java.lang.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 java.lang.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

precision
```
public java.lang.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

valueMapEnum
```
public java.lang.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:

ComponentBinding overview and related methods

childrenProperty
```
public java.lang.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, DataSourceRelations overview and related methods

multiple
```
public java.lang.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.

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 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 "isBlank", "notBlank", "isNull" and "notNull", an empty Array is considered non-null. For example, if you use dataFormat:"json" and the field value is provided to the browser as [] (JSON for an empty Array), the field is considered non-null.

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

ComponentSchema overview and related methods

lenientXPath
```
public java.lang.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

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:

ComponentBinding overview and related methods

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

See Also:

Basics overview and related methods

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, FieldLevelAuth overview and related methods

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:

ComponentBinding overview and related methods

fkTableCode
```
public java.lang.String fkTableCode
```
See DataSource.tableCode.
Default value is null

canSave
```
public java.lang.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:

ComponentBinding overview and related methods

editRequiresAuthentication
```
public java.lang.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 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, FieldLevelAuth overview and related methods

propertiesOnly
```
public java.lang.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:

ComponentSchema overview and related methods

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

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

Constructor Detail
- DataSourceField
```
public DataSourceField()
```

Class DataSourceField

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

maxFileSize

autoGenerated

canSortClientOnly

columnCode

valueMap

initRequiresAuthentication

includeFrom

getFieldValue

displayFormat

relatedTableAlias

useLocalDisplayFieldValue

required

Conditionally required fields

sequenceName

escapeHTML

updateRequiresAuthentication

exportFormat

Excel cannot handle dates prior to January 1st 1900

Currency symbols become fixed to the current locale at export time

Rounding differences

Different treatment of '#'

Miscellaneous edge cases

Date format functionality not supported by Excel

Number format functionality not supported by Excel

Limit on number of custom Excel formats

title

multipleStorageSeparator

name

javaCollectionClass

rootValue

storeWithHash

creatorOverrides

audit

filterEditorType

editRequiresRole

canExport

imageWidth

viewRequiresRole

valueWriteXPath

includeVia

SQL Templating and includeVia

Multiple indirection and relatedTableAlias

stringInBrowser

joinType

group

mimeType

valueXPath

canFilter

ignoreTextMatchStyle

initRequires

includeSummaryFunction

sortByField

storeMilliseconds

canEdit

imageHeight

showFileInline

javaClass

javaKeyClass

fkColumnCode

multipleStorage

Criteria and AdvancedCriteria handling

childTagName

canView

implicitSequence

viewRequiresAuthentication

decimalPad

foreignKey

validOperators

hidden

inapplicable

decimalPrecision

primaryKey

allowClientRequestedSummaries

updateRequires

SQL Templating and `includeVia`

Multiple indirection and `relatedTableAlias`