com.smartgwt.client.data

## Class DataSourceField

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

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

      public class DataSourceField
      extends DataClass

  Metadata about a DataSourceField, including its type and validators.

- - ### Field Summary

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

      `factoryCreated, factoryProperties`

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

      `jsObj`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `exportForceText()` When using `DataSource.recordsAsText()`, what approach (if any) should be used to force values to be intepreted as text instead of heuristically parsed as dates, times or other structured types.
    `java.lang.Boolean` | `getCanEdit()` Controls whether, by default, dataBoundComponents consider this field editable.
    `java.lang.Boolean` | `getCanExport()` Dictates whether the data in this field be exported.
    `java.lang.Boolean` | `getCanFilter()` Should the user be able to filter data by this field? Affects whether this field will show up in dataBoundComponents with UI for filtering data.
    `java.lang.Boolean` | `getCanSave()` Whether values in this field can be updated and saved to the dataSource.
    `boolean` | `getCanSortClientOnly()` When true, this field can only be used for sorting if the data is entirely client-side.
    `java.lang.Boolean` | `getCanView()` If false, this property indicates that this field is considered "server only".
    `java.lang.Boolean` | `getChildrenProperty()` If true, this property indicates that this field will hold an explicit array of child nodes for the current node.
    `java.lang.String` | `getChildTagName()` For a field that is `multiple:"true"`, controls the name of the XML tag used for each subelement during `DataSource.xmlSerialize()`.
    `DateDisplayFormat` | `getDateFormatter()` Preferred display format to use for date type values within this field.
    `java.lang.Integer` | `getDecimalPad()` Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.
    `java.lang.Integer` | `getDecimalPrecision()` Applies only to fields of type "float" and affects how many significant digits are shown.
    `boolean` | `getDetail()` Whether this field should be considered a "detail" field by a `DataBoundComponent`.
    `java.lang.String` | `getDisplayField()` Name of another field in this DataSource that should be used as the display value for this field.
    `java.lang.String` | `getEmptyDisplayValue()` Text to be used for display by client-side components when this field has a null or undefined value.
    `java.lang.Boolean` | `getEscapeHTML()` When data values are displayed in DataBound components, by default strings will be interpreted as HTML by the browser in most cases.
    `java.lang.String` | `getExportFormat()` 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` | `getExportTitle()` Optional different field-title used for exports.
    `java.lang.String` | `getForeignDisplayField()` Name of another field in a separate dataSource that should be used as the display value for this field in the case where a `foreignKey` relationship exists.
    `java.lang.String` | `getForeignKey()` Declares that this field holds values that can be matched to values from another DataSource field, to create a relationship between records from different DataSources or even records within the same DataSource.
    `java.lang.String` | `getFormat()` Format string to use when rendering the value in any `DataBoundComponent` or when exporting via `DataSource.exportData()` or `ListGrid.exportData()` or `ListGrid.exportClientData()`.
    `java.lang.String` | `getGroup()` For use in `ComponentSchema`, indicates what group to place the property in when editing in Visual Builder.
    `boolean` | `getHidden()` Whether this field should be hidden from users by default within a DataBound component.
    `java.lang.Boolean` | `getIgnoreTextMatchStyle()` NOTE: Only applicable to `clientOnly` DataSources and the built-in `SQL`, `JPA` and `Hibernate` DataSources available in Pro, Power and Enterprise versions of Smart GWT.
    `java.lang.Integer` | `getImageHeight()` Height of the image-content of this field.
    `java.lang.String` | `getImageHeightAsString()` Height of the image-content of this field.
    `java.lang.Integer` | `getImageSize()` Width and height of the image-content of this field.
    `java.lang.String` | `getImageSizeAsString()` Width and height of the image-content of this field.
    `java.lang.Integer` | `getImageWidth()` Width of the image-content of this field.
    `java.lang.String` | `getImageWidthAsString()` Width of the image-content of this field.
    `java.lang.Boolean` | `getInapplicable()` For use in `ComponentSchema`, a field `inherited` from another schema can be redeclared with this property set in order to indicate that the property should not be used.
    `java.lang.Integer` | `getLength()` Maximum number of characters allowed.
    `java.lang.Boolean` | `getLenientXPath()` Deprecated. No longer needs to be set since the framework now defaults to suppressing errors for null values in the middle of Xpath, and only invalid XPath will cause warning be logged.
    `java.lang.Boolean` | `getMultiple()` Indicates that this field should always be Array-valued.
    `java.lang.String` | `getMultipleValueSeparator()` For fields that are `multiple:true`, the separator used between values when they are displayed.
    `java.lang.String` | `getName()` Name for this field.
    `java.lang.Boolean` | `getNillable()` Controls whether an explicit null-valued Record attribute for this field should result in `xsi:nil` being used to transmit the value when serializing to XML, like so:
    `static DataSourceField` | `getOrCreateRef(JavaScriptObject jsObj)`
    `java.lang.String` | `getPluralTitle()` Return the plural title.
    `java.lang.Integer` | `getPrecision()` Applies only to fields of type "float" or "integer" and affects how many significant digits are shown.
    `boolean` | `getPrimaryKey()` 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.String` | `getPrompt()` Causes a tooltip hover to appear on the header generated for this field (effectively sets `prompt` for the header).
    `java.lang.Boolean` | `getPropertiesOnly()` For use in `ComponentSchema` for fields that contain other components, this flag suppresses auto-construction for subcomponents that appear under this field.
    `java.lang.Boolean` | `getRequired()` Indicates this field must be non-null in order for a record to pass validation.
    `java.lang.Object` | `getRootValue()` For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
    `java.lang.String` | `getSequenceName()` For a DataSource with `serverType:"sql"` with a field of type "sequence", the name of the SQL sequence that should be used when inserting new records into this table.
    `java.lang.Boolean` | `getShowFileInline()` For a field of type:"imageFile", indicates whether to stream the image and display it inline or to display the View and Download icons.
    `SummaryFunctionType` | `getSummaryFunction()` If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an explicit `SummaryFunction` for calculating the summary value to display.
    `java.lang.String` | `getSummaryValueTitle()` Title to show in a `Summary of type "title"` for this field.
    `TimeDisplayFormat` | `getTimeFormatter()` Preferred time-format to apply to date type values within this field.
    `java.lang.String` | `getTitle()` Default user-visible title for this field.
    `FieldType` | `getType()` Type of this field.
    `DataSource` | `getTypeAsDataSource()` Return the type of the assigned DataSource
    `SimpleType` | `getTypeAsSimpleType()` Returns the type of this field as a SimpleType.
    `java.lang.String` | `getUploadFieldName()` Used by the `BatchUploader` to map a field in an upload file to this dataSourceField.
    `Validator[]` | `getValidators()` Validators to be applied to this field.
    `OperatorId[]` | `getValidOperators()` List of operators valid on this field.
    `java.util.Map` | `getValueMap()` A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.
    `java.lang.String` | `getValueXPath()` XPath expression used to retrieve the field's value.
    `java.lang.Boolean` | `getXmlAttribute()` Indicates that `DataSource.xmlSerialize()` should serialize this value as an XML attribute.
    `void` | `setCanEdit(java.lang.Boolean canEdit)` Controls whether, by default, dataBoundComponents consider this field editable.
    `void` | `setCanExport(java.lang.Boolean canExport)` Dictates whether the data in this field be exported.
    `void` | `setCanFilter(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.
    `void` | `setCanSave(java.lang.Boolean canSave)` Whether values in this field can be updated and saved to the dataSource.
    `void` | `setCanSortClientOnly(boolean canSortClientOnly)` When true, this field can only be used for sorting if the data is entirely client-side.
    `void` | `setCanView(java.lang.Boolean canView)` If false, this property indicates that this field is considered "server only".
    `void` | `setChildrenProperty(java.lang.Boolean childrenProperty)` If true, this property indicates that this field will hold an explicit array of child nodes for the current node.
    `void` | `setChildTagName(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()`.
    `void` | `setDateFormatter(DateDisplayFormat dateFormatter)` Preferred display format to use for date type values within this field.
    `void` | `setDecimalPad(java.lang.Integer decimalPad)` Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.
    `void` | `setDecimalPrecision(java.lang.Integer decimalPrecision)` Applies only to fields of type "float" and affects how many significant digits are shown.
    `void` | `setDetail(boolean detail)` Whether this field should be considered a "detail" field by a `DataBoundComponent`.
    `void` | `setDisplayField(java.lang.String displayField)` Name of another field in this DataSource that should be used as the display value for this field.
    `void` | `setEditorProperties(FormItem editorProperties)` Set the default `FormItem` properties to be used whenever this field is edited (whether in a grid, form, or other component).
    `void` | `setEditorType(java.lang.Class<? extends FormItem> editorType)` Set the default `FormItem` class to be used whenever this field is edited (whether in a grid, form, or other component).
    `void` | `setEditorType(FormItem editorType)` Deprecated. Renamed to `setEditorProperties(FormItem)`. You can also consider using `setEditorType(Class)` or `setEditorType(String)` instead.
    `void` | `setEditorType(java.lang.String editorType)` Set the default `FormItem` class to be used whenever this field is edited (whether in a grid, form, or other component).
    `void` | `setEmptyDisplayValue(java.lang.String emptyDisplayValue)` Text to be used for display by client-side components when this field has a null or undefined value.
    `void` | `setEscapeHTML(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.
    `void` | `setExportFormat(java.lang.String exportFormat)` An optional `FormatString` for this field, for use when `exporting` data to spreadsheet formats (XLS and OOXML/XLSX), XML, JSON or CSV.
    `void` | `setExportTitle(java.lang.String exportTitle)` Optional different field-title used for exports.
    `void` | `setFieldValueExtractor(FieldValueExtractor extractor)` Function to retrieve the field's value from the XML element or JSON record returned from a web service.
    `void` | `setForeignDisplayField(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.
    `void` | `setForeignKey(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.
    `void` | `setFormat(java.lang.String format)` Format string to use when rendering the value in any `DataBoundComponent` or when exporting via `DataSource.exportData()` or `ListGrid.exportData()` or `ListGrid.exportClientData()`.
    `void` | `setGroup(java.lang.String group)` For use in `ComponentSchema`, indicates what group to place the property in when editing in Visual Builder.
    `void` | `setHidden(boolean hidden)` Whether this field should be hidden from users by default within a DataBound component.
    `void` | `setIgnoreTextMatchStyle(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.
    `void` | `setImageHeight(java.lang.Integer imageHeight)` Height of the image-content of this field.
    `void` | `setImageHeight(java.lang.String imageHeight)` Height of the image-content of this field.
    `void` | `setImageSize(java.lang.Integer imageSize)` Width and height of the image-content of this field.
    `void` | `setImageSize(java.lang.String imageSize)` Width and height of the image-content of this field.
    `void` | `setImageWidth(java.lang.Integer imageWidth)` Width of the image-content of this field.
    `void` | `setImageWidth(java.lang.String imageWidth)` Width of the image-content of this field.
    `void` | `setInapplicable(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.
    `void` | `setLength(java.lang.Integer length)` Maximum number of characters allowed.
    `void` | `setLenientXPath(java.lang.Boolean lenientXPath)` Deprecated. No longer needs to be set since the framework now defaults to suppressing errors for null values in the middle of Xpath, and only invalid XPath will cause warning be logged.
    `void` | `setMultiple(java.lang.Boolean multiple)` Indicates that this field should always be Array-valued.
    `void` | `setMultipleValueSeparator(java.lang.String multipleValueSeparator)` For fields that are `multiple:true`, the separator used between values when they are displayed.
    `void` | `setName(java.lang.String name)` Name for this field.
    `void` | `setNillable(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:
    `void` | `setPluralTitle(java.lang.String pluralTitle)` Set the plural title.
    `void` | `setPrecision(java.lang.Integer precision)` Applies only to fields of type "float" or "integer" and affects how many significant digits are shown.
    `void` | `setPrimaryKey(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.
    `void` | `setPrompt(java.lang.String prompt)` Causes a tooltip hover to appear on the header generated for this data source field (effectively sets `prompt` for the header).
    `void` | `setPropertiesOnly(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.
    `void` | `setReadOnlyEditorProperties(FormItem editorProperties)` Sets the default FormItem properties to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.
    `void` | `setReadOnlyEditorType(java.lang.Class<? extends FormItem> editorType)` Sets the default `FormItem` class to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.
    `void` | `setReadOnlyEditorType(FormItem editorType)` Deprecated. Renamed to `setReadOnlyEditorProperties(FormItem)`. You can also consider using `setReadOnlyEditorType(Class)` or `setReadOnlyEditorType(String)` instead.
    `void` | `setReadOnlyEditorType(java.lang.String editorType)` Sets the default FormItem class to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.
    `void` | `setRequired(java.lang.Boolean required)` Indicates this field must be non-null in order for a record to pass validation.
    `void` | `setRootValue(java.lang.Float rootValue)` For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
    `void` | `setRootValue(java.lang.Integer rootValue)` For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
    `void` | `setRootValue(java.lang.Object rootValue)` For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
    `void` | `setRootValue(java.lang.String rootValue)` For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
    `void` | `setSequenceName(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.
    `void` | `setShowFileInline(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.
    `void` | `setSummaryFunction(java.lang.String summaryFunction)` If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an summary function registered via `com.smartgwt.client.data.SimpleType#registerSummaryFunction()` for calculating the summary value to display.
    `void` | `setSummaryFunction(SummaryFunction summaryFunction)` If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an explicit `SummaryFunction` for calculating the summary value to display.
    `void` | `setSummaryFunction(SummaryFunctionType summaryFunction)` If `showGridSummary` or `showGroupSummary` is true, this attribute can be used to specify an explicit `SummaryFunction` for calculating the summary value to display.
    `void` | `setSummaryValueTitle(java.lang.String summaryValueTitle)` Title to show in a `Summary of type "title"` for this field.
    `void` | `setTimeFormatter(TimeDisplayFormat timeFormatter)` Preferred time-format to apply to date type values within this field.
    `void` | `setTitle(java.lang.String title)` Default user-visible title for this field.
    `void` | `setType(DataSource dataSource)` Deprecated. use #setTypeAsDataSource
    `void` | `setType(FieldType type)` Type of this field.
    `void` | `setType(SimpleType type)` Set the type directly to a defined SimpleType.
    `void` | `setTypeAsDataSource(DataSource dataSource)` The type can also be the another DataSource, which allows you to model nested structures such as XML documents (in fact, XMLTools.loadXMLSchema() models XML schema in this way).
    `void` | `setUploadFieldName(java.lang.String uploadFieldName)` Used by the `BatchUploader` to map a field in an upload file to this dataSourceField.
    `void` | `setValidators(Validator... validators)` Validators to be applied to this field.
    `void` | `setValidOperators(OperatorId... validOperators)` List of operators valid on this field.
    `void` | `setValueMap(java.util.Map valueMap)` A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.
    `void` | `setValueMap(java.lang.String... valueMap)` A ValueMap is a set of legal values for a field.
    `void` | `setValueXPath(java.lang.String valueXPath)` XPath expression used to retrieve the field's value.
    `void` | `setXmlAttribute(java.lang.Boolean xmlAttribute)` Indicates that `DataSource.xmlSerialize()` should serialize this value as an XML attribute.

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

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

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

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

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

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

- - ### Constructor Detail

    - #### DataSourceField

          public DataSourceField()

    - #### DataSourceField

          public DataSourceField(JavaScriptObject jsObj)

    - #### DataSourceField

          public DataSourceField(java.lang.String name,
                         FieldType type)

    - #### DataSourceField

          public DataSourceField(java.lang.String name,
                         FieldType type,
                         java.lang.String title)

    - #### DataSourceField

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

    - #### DataSourceField

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

  - ### Method Detail

    - #### getOrCreateRef

          public static DataSourceField getOrCreateRef(JavaScriptObject jsObj)

    - #### setCanExport

          public void setCanExport(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`.
      Parameters:
        `canExport` - Default value is null

    - #### getCanExport

          public java.lang.Boolean getCanExport()

      Dictates whether the data in this field be exported. Explicitly setting canExport to false overrides the setting on any component-fields, such as `ListGrid fields`.
      Returns:
        Boolean

    - #### setCanFilter

          public void setCanFilter(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.

      Parameters:
        `canFilter` - Default value is null
      See Also:
        `SearchForm.setShowFilterFieldsOnly(java.lang.Boolean)`, `SearchForm.setCanEditFieldAttribute(java.lang.String)`

    - #### getCanFilter

          public java.lang.Boolean getCanFilter()

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

      Returns:
        Boolean
      See Also:
        `SearchForm.getShowFilterFieldsOnly()`, `SearchForm.getCanEditFieldAttribute()`

    - #### setCanSave

          public void setCanSave(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.

      Parameters:
        `canSave` - Default value is null
      See Also:
        `ComponentBinding overview and related methods`

    - #### getCanSave

          public java.lang.Boolean getCanSave()

      Whether values in this field can be updated and saved to the dataSource.

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

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

      Returns:
        Boolean
      See Also:
        `ComponentBinding overview and related methods`

    - #### setCanSortClientOnly

          public void setCanSortClientOnly(boolean canSortClientOnly)

      When true, this field can only be used for sorting if the data is entirely client-side.
      Parameters:
        `canSortClientOnly` - Default value is false

    - #### getCanSortClientOnly

          public boolean getCanSortClientOnly()

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

    - #### setCanView

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

      Parameters:
        `canView` - Default value is null
      See Also:
        `ComponentBinding overview and related methods`

    - #### getCanView

          public java.lang.Boolean getCanView()

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

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

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

      Returns:
        Boolean
      See Also:
        `ComponentBinding overview and related methods`

    - #### setChildrenProperty

          public void setChildrenProperty(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 `childrenField` to this field's name.
      Parameters:
        `childrenProperty` - Default value is false
      See Also:
        `DataSource.setChildrenField(java.lang.String)`, `DataSourceRelations overview and related methods`

    - #### getChildrenProperty

          public java.lang.Boolean getChildrenProperty()

      If true, this property indicates that this field will hold an explicit array of child nodes for the current node. This has the same effect as specifying `childrenField` to this field's name.
      Returns:
        Boolean
      See Also:
        `DataSource.getChildrenField()`, `DataSourceRelations overview and related methods`

    - #### setChildTagName

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

      Parameters:
        `childTagName` - Default value is null
      See Also:
        `ComponentSchema overview and related methods`

    - #### getChildTagName

          public java.lang.String getChildTagName()

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

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

      Returns:
        String
      See Also:
        `ComponentSchema overview and related methods`

    - #### setDateFormatter

          public void setDateFormatter(DateDisplayFormat dateFormatter)

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

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

      Note : This is an advanced setting

      Parameters:
        `dateFormatter` - Default value is null
      See Also:
        `Appearance overview and related methods`

    - #### getDateFormatter

          public DateDisplayFormat getDateFormatter()

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

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

      Returns:
        DateDisplayFormat
      See Also:
        `Appearance overview and related methods`

    - #### setDecimalPad

          public void setDecimalPad(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.

      Parameters:
        `decimalPad` - Default value is null
      See Also:
        `Appearance overview and related methods`

    - #### getDecimalPad

          public java.lang.Integer getDecimalPad()

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

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

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

      Returns:
        Integer
      See Also:
        `Appearance overview and related methods`

    - #### setDecimalPrecision

          public void setDecimalPrecision(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.

      Parameters:
        `decimalPrecision` - Default value is null
      See Also:
        `Appearance overview and related methods`

    - #### getDecimalPrecision

          public java.lang.Integer getDecimalPrecision()

      Applies only to fields of type "float" and affects how many significant digits are shown.

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

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

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

      Returns:
        Integer
      See Also:
        `Appearance overview and related methods`

    - #### setDetail

          public void setDetail(boolean detail)

      Whether this field should be considered a "detail" field by a `DataBoundComponent`.

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

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

      Parameters:
        `detail` - Default value is false
      See Also:
        `ComponentBinding overview and related methods`

    - #### getDetail

          public boolean getDetail()

      Whether this field should be considered a "detail" field by a `DataBoundComponent`.

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

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

      Returns:
        boolean
      See Also:
        `ComponentBinding overview and related methods`

    - #### setDisplayField

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

      Parameters:
        `displayField` - Default value is null
      See Also:
        `DataSourceRelations overview and related methods`

    - #### getDisplayField

          public java.lang.String getDisplayField()

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

      Returns:
        String
      See Also:
        `DataSourceRelations overview and related methods`

    - #### setEmptyDisplayValue

          public void setEmptyDisplayValue(java.lang.String emptyDisplayValue)

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

    - #### getEmptyDisplayValue

          public java.lang.String getEmptyDisplayValue()

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

    - #### setEscapeHTML

          public void setEscapeHTML(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.

      Parameters:
        `escapeHTML` - Default value is null
      See Also:
        `ListGridField.setEscapeHTML(java.lang.Boolean)`

    - #### getEscapeHTML

          public java.lang.Boolean getEscapeHTML()

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

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

      Returns:
        Boolean
      See Also:
        `ListGridField.getEscapeHTML()`

    - #### setExportFormat

          public void setExportFormat(java.lang.String exportFormat)

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

      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`.
      Parameters:
        `exportFormat` - See `FormatString` . Default value is null
      See Also:
        `setFormat(java.lang.String)`

    - #### getExportFormat

          public java.lang.String getExportFormat()

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

      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`.
      Returns:
        See `FormatString`
      See Also:
        `getFormat()`

    - #### setExportTitle

          public void setExportTitle(java.lang.String exportTitle)

      Optional different field-title used for exports.
      Parameters:
        `exportTitle` - Default value is null

    - #### getExportTitle

          public java.lang.String getExportTitle()

      Optional different field-title used for exports.
      Returns:
        String

    - #### setForeignDisplayField

          public void setForeignDisplayField(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 `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 `foreignDisplayField` for more on this, and see `includeFrom` for a discussion about picking up dataSource field values from a related dataSource.

      Parameters:
        `foreignDisplayField` - Default value is null
      See Also:
        `DataSourceRelations overview and related methods`

    - #### getForeignDisplayField

          public java.lang.String getForeignDisplayField()

      Name of another field in a separate dataSource that should be used as the display value for this field in the case where a `foreignKey` relationship exists.

      This property is useful for fields being edited in a FormItem where options are being retrieved from an `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 `foreignDisplayField` for more on this, and see `includeFrom` for a discussion about picking up dataSource field values from a related dataSource.

      Returns:
        String
      See Also:
        `DataSourceRelations overview and related methods`

    - #### setForeignKey

          public void setForeignKey(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.

      Parameters:
        `foreignKey` - Default value is false
      See Also:
        `com.smartgwt.client.docs.serverds.DataSourceField#joinType`, `DataSourceRelations overview and related methods`

    - #### getForeignKey

          public java.lang.String getForeignKey()

      Declares that this field holds values that can be matched to values from another DataSource field, to create a relationship between records from different DataSources or even records within the same DataSource.

      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.

      Returns:
        String
      See Also:
        `com.smartgwt.client.docs.serverds.DataSourceField#joinType`, `DataSourceRelations overview and related methods`

    - #### setFormat

          public void setFormat(java.lang.String format)

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

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

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

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

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

      Parameters:
        `format` - See `FormatString` . Default value is null
      See Also:
        `setExportFormat(java.lang.String)`

    - #### getFormat

          public java.lang.String getFormat()

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

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

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

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

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

      Returns:
        See `FormatString`
      See Also:
        `getExportFormat()`

    - #### setGroup

          public void setGroup(java.lang.String group)

      For use in `ComponentSchema`, indicates what group to place the property in when editing in Visual Builder.
      Parameters:
        `group` - Default value is null
      See Also:
        `ComponentSchema overview and related methods`

    - #### getGroup

          public java.lang.String getGroup()

      For use in `ComponentSchema`, indicates what group to place the property in when editing in Visual Builder.
      Returns:
        String
      See Also:
        `ComponentSchema overview and related methods`

    - #### setHidden

          public void setHidden(boolean hidden)

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

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

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

      Parameters:
        `hidden` - Default value is false
      See Also:
        `ComponentBinding overview and related methods`

    - #### getHidden

          public boolean getHidden()

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

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

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

      Returns:
        boolean
      See Also:
        `ComponentBinding overview and related methods`

    - #### setIgnoreTextMatchStyle

          public void setIgnoreTextMatchStyle(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.

      Parameters:
        `ignoreTextMatchStyle` - Default value is null

    - #### getIgnoreTextMatchStyle

          public java.lang.Boolean getIgnoreTextMatchStyle()

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

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

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

      Returns:
        Boolean

    - #### setInapplicable

          public void setInapplicable(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 `children` should be marked inapplicable in order to prevent arbitrary components being dropped onto a `MyDialog` instance.

      Parameters:
        `inapplicable` - Default value is null
      See Also:
        `ComponentSchema overview and related methods`

    - #### getInapplicable

          public java.lang.Boolean getInapplicable()

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

      This is primarily used to influence `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 `children` should be marked inapplicable in order to prevent arbitrary components being dropped onto a `MyDialog` instance.

      Returns:
        Boolean
      See Also:
        `ComponentSchema overview and related methods`

    - #### setLength

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

      Parameters:
        `length` - Default value is null
      See Also:
        Long Text Example

    - #### getLength

          public java.lang.Integer getLength()

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

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

      Returns:
        Integer
      See Also:
        Long Text Example

    - #### setLenientXPath

          public void setLenientXPath(java.lang.Boolean lenientXPath)

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

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

      Parameters:
        `lenientXPath` - Default value is null

    - #### getLenientXPath

          public java.lang.Boolean getLenientXPath()

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

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

      Returns:
        Boolean

    - #### setMultiple

          public void setMultiple(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 "isNull" and "isNotNull", 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 `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, `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.

      Parameters:
        `multiple` - Default value is false
      See Also:
        `ComponentSchema overview and related methods`

    - #### getMultiple

          public java.lang.Boolean getMultiple()

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

      JPA and Hibernate DataSources use `multiple:true` as part of the declaration of One-To-Many and Many-to-Many relations - see `JpaHibernateRelations` for details.

      #### 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 "isNull" and "isNotNull", 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 `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, `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.

      Returns:
        Boolean
      See Also:
        `ComponentSchema overview and related methods`

    - #### setMultipleValueSeparator

          public void setMultipleValueSeparator(java.lang.String multipleValueSeparator)

      For fields that are `multiple:true`, the separator used between values when they are displayed.
      Parameters:
        `multipleValueSeparator` - Default value is ", "

    - #### getMultipleValueSeparator

          public java.lang.String getMultipleValueSeparator()

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

    - #### setName

          public void setName(java.lang.String name)

      Name for this field.

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

      Must be unique across all fields within the DataSource as well as a valid JavaScript identifier, as specified by ECMA-262 Section 7.6.

      NOTE: The StringUtil.isValidID() function can be used to test whether a name is a valid JavaScript identifier.

      Parameters:
        `name` - Default value is null
      See Also:
        `Basics overview and related methods`

    - #### getName

          public java.lang.String getName()

      Name for this field.

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

      Must be unique across all fields within the DataSource as well as a valid JavaScript identifier, as specified by ECMA-262 Section 7.6.

      NOTE: The StringUtil.isValidID() function can be used to test whether a name is a valid JavaScript identifier.

      Returns:
        String
      See Also:
        `Basics overview and related methods`

    - #### setNillable

          public void setNillable(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.
      Parameters:
        `nillable` - Default value is null

    - #### getNillable

          public java.lang.Boolean getNillable()

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

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

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

    - #### setPrecision

          public void setPrecision(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.

      Parameters:
        `precision` - Default value is null
      See Also:
        `Appearance overview and related methods`

    - #### getPrecision

          public java.lang.Integer getPrecision()

      Applies only to fields of type "float" or "integer" and affects how many significant digits are shown.

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

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

      Returns:
        Integer
      See Also:
        `Appearance overview and related methods`

    - #### setPrimaryKey

          public void setPrimaryKey(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".

      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 `Admin Console`, 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.

      Parameters:
        `primaryKey` - Default value is false
      See Also:
        `DataSourceRelations overview and related methods`

    - #### getPrimaryKey

          public boolean getPrimaryKey()

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

      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 `Admin Console`, 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.

      Returns:
        boolean
      See Also:
        `DataSourceRelations overview and related methods`

    - #### setPropertiesOnly

          public void setPropertiesOnly(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.
      Parameters:
        `propertiesOnly` - Default value is null
      See Also:
        `ComponentSchema overview and related methods`

    - #### getPropertiesOnly

          public java.lang.Boolean getPropertiesOnly()

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

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

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

      The ListGrid and ToolStrip do not construct themselves automatically. Instead, the VLayout receives the properties of the ListGrid and ToolStrip as ordinary JavaScript Objects, with the special property `_constructor` set to the name of the class that should be constructed.
      Returns:
        Boolean
      See Also:
        `ComponentSchema overview and related methods`

    - #### setRequired

          public void setRequired(java.lang.Boolean required)

      Indicates this field must be non-null in order for a record to pass validation.

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

      Parameters:
        `required` - Default value is false

    - #### getRequired

          public java.lang.Boolean getRequired()

      Indicates this field must be non-null in order for a record to pass validation.

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

      Returns:
        Boolean

    - #### setRootValue

          public void setRootValue(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 `rootNode`, or if the ResultTree is auto-generated by a `TreeGrid`, by setting `treeRootValue`. This allows a component to navigate a subtree of the hierarchical data from this dataSource starting at a particular node.

      Parameters:
        `rootValue` - Default value is null
      See Also:
        `DataSourceRelations overview and related methods`

    - #### getRootValue

          public java.lang.Object getRootValue()

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

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

      Returns:
        Object
      See Also:
        `DataSourceRelations overview and related methods`

    - #### setSequenceName

          public void setSequenceName(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

      Parameters:
        `sequenceName` - Default value is null
      See Also:
        `SqlDataSource overview and related methods`

    - #### getSequenceName

          public java.lang.String getSequenceName()

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

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

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

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

                order_system_orders_orderNumber_seq

      Returns:
        String
      See Also:
        `SqlDataSource overview and related methods`

    - #### setShowFileInline

          public void setShowFileInline(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.
      Parameters:
        `showFileInline` - Default value is null

    - #### getShowFileInline

          public java.lang.Boolean getShowFileInline()

      For a field of type:"imageFile", indicates whether to stream the image and display it inline or to display the View and Download icons.
      Returns:
        Boolean

    - #### setSummaryValueTitle

          public void setSummaryValueTitle(java.lang.String summaryValueTitle)

      Title to show in a `Summary of type "title"` for this field. If unspecified `title` summaries will show the `title` for the field.
      Parameters:
        `summaryValueTitle` - Default value is null

    - #### getSummaryValueTitle

          public java.lang.String getSummaryValueTitle()

      Title to show in a `Summary of type "title"` for this field. If unspecified `title` summaries will show the `title` for the field.
      Returns:
        String

    - #### setTimeFormatter

          public void setTimeFormatter(TimeDisplayFormat timeFormatter)

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

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

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

      Note : This is an advanced setting

      Parameters:
        `timeFormatter` - Default value is null
      See Also:
        `Appearance overview and related methods`

    - #### getTimeFormatter

          public TimeDisplayFormat getTimeFormatter()

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

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

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

      Returns:
        TimeDisplayFormat
      See Also:
        `Appearance overview and related methods`

    - #### setTitle

          public void setTitle(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 `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 `headerTitle` attribute may be used to specify a different string for display in the listGrid column header.

      Parameters:
        `title` - Default value is null
      See Also:
        `ComponentBinding overview and related methods`

    - #### getTitle

          public java.lang.String getTitle()

      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 `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 `headerTitle` attribute may be used to specify a different string for display in the listGrid column header.

      Returns:
        String
      See Also:
        `ComponentBinding overview and related methods`

    - #### setType

          public void setType(FieldType type)

      Type of this field. Required for all DataSource fields.

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

      Parameters:
        `type` - Default value is null
      See Also:
        `Basics overview and related methods`

    - #### setUploadFieldName

          public void setUploadFieldName(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).
      Parameters:
        `uploadFieldName` - Default value is null

    - #### getUploadFieldName

          public java.lang.String getUploadFieldName()

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

    - #### setValidators

          public void setValidators(Validator... validators)

      Validators to be applied to this field.

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

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

      Parameters:
        `validators` - Default value is null
      See Also:
        `Validator`, `Validation overview and related methods`

    - #### getValidators

          public Validator[] getValidators()

      Validators to be applied to this field.

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

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

      Returns:
        Validator...
      See Also:
        `Validator`, `Validation overview and related methods`

    - #### setValidOperators

          public void setValidOperators(OperatorId... validOperators)

      List of operators valid on this field.

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

      Parameters:
        `validOperators` - Default value is null

    - #### getValidOperators

          public OperatorId[] getValidOperators()

      List of operators valid on this field.

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

      Returns:
        OperatorId...

    - #### setValueMap

          public void setValueMap(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>

      Parameters:
        `valueMap` - Default value is null

    - #### getValueMap

          public java.util.Map getValueMap()

      A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.

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

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

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

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

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

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

      Returns:
        Map

    - #### setValueXPath

          public void setValueXPath(java.lang.String valueXPath)

      XPath expression used to retrieve the field's value.

      This XPath expression will be evaluated in the scope of the record objects selected by the `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.

      Parameters:
        `valueXPath` - See `XPathExpression` . Default value is null
      See Also:
        `ClientDataIntegration overview and related methods`, XPath Binding Example

    - #### getValueXPath

          public java.lang.String getValueXPath()

      XPath expression used to retrieve the field's value.

      This XPath expression will be evaluated in the scope of the record objects selected by the `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.

      Returns:
        See `XPathExpression`
      See Also:
        `ClientDataIntegration overview and related methods`, XPath Binding Example

    - #### setXmlAttribute

          public void setXmlAttribute(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.

      Parameters:
        `xmlAttribute` - Default value is null
      See Also:
        `ComponentSchema overview and related methods`

    - #### getXmlAttribute

          public java.lang.Boolean getXmlAttribute()

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

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

      Returns:
        Boolean
      See Also:
        `ComponentSchema overview and related methods`

    - #### exportForceText

          public void exportForceText()

      When using `DataSource.recordsAsText()`, what approach (if any) should be used to force values to be intepreted as text instead of heuristically parsed as dates, times or other structured types.

    - #### setPluralTitle

          public void setPluralTitle(java.lang.String pluralTitle)

      Set the plural title.
      Parameters:
        `pluralTitle` - the plural title

    - #### getPluralTitle

          public java.lang.String getPluralTitle()

      Return the plural title.
      Returns:
        String

    - #### setType

          public void setType(SimpleType type)

      Set the type directly to a defined SimpleType.
      Parameters:
        `type` - the SimpleType

    - #### setValueMap

          public void setValueMap(java.lang.String... valueMap)

      A ValueMap is a set of legal values for a field.

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

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

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

             <valueMap>
              <value>Pens & Pencils</value>

           <value>Stationery</value>
              <value>Computer Products</value>

           <value>Furniture</value>
              <value>Misc</value>
             </valueMap>

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

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

      Parameters:
        `valueMap` - valueMap Default value is null

    - #### setEditorProperties

          public void setEditorProperties(FormItem editorProperties)

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

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

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

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

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

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

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

                void customMethod() { ... }
            }

            ...

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

      As an alternative, you can use `setEditorType(String)` or `setEditorType(Class)` to avoid these limitations, if you register the FormItem subclass with the `reflection mechanism`.

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

    - #### setEditorType

          public void setEditorType(FormItem editorType)

      Deprecated. Renamed to `setEditorProperties(FormItem)`. You can also consider using `setEditorType(Class)` or `setEditorType(String)` instead.
      Synonym for `setEditorProperties(FormItem)`.
      Parameters:
        `editorType` - FormItem with default properties to be applied when editing

    - #### setEditorType

          public void setEditorType(java.lang.String editorType)

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

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

      By using the `reflection mechanism`, this method avoids the limitations described in `setEditorProperties(FormItem)`.

      Parameters:
        `editorType` - the fully-qualified class name of a `FormItem` subclass, which must have been registered with the `reflection mechanism`.
      Throws:
        `java.lang.IllegalArgumentException` - if the editorType class has not beeen registered for use with the `reflection mechanism`, or if it does not inherit from `FormItem`.

    - #### setEditorType

          public void setEditorType(java.lang.Class<? extends FormItem> editorType)

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

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

      By using the `reflection mechanism`, this method avoids the limitations described in `setEditorProperties(FormItem)`.

      Parameters:
        `editorType` - a `FormItem` subclass, which must have been registered with the `reflection mechanism`.
      Throws:
        `java.lang.IllegalArgumentException` - if the editorType class has not beeen registered for use with the `reflection mechanism`, or if it does not inherit from `FormItem`.

    - #### setReadOnlyEditorType

          public void setReadOnlyEditorType(FormItem editorType)

      Deprecated. Renamed to `setReadOnlyEditorProperties(FormItem)`. You can also consider using `setReadOnlyEditorType(Class)` or `setReadOnlyEditorType(String)` instead.
      Synonym for `setReadOnlyEditorProperties(FormItem)`.
      Parameters:
        `editorType` - FormItem with properties to set when editing read-only values.

    - #### setReadOnlyEditorProperties

          public void setReadOnlyEditorProperties(FormItem editorProperties)

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

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

      Note: The FormItem passed to setReadOnlyEditorProperties() is used as a "template" to create a FormItem whenever a `DataBoundComponent` needs to show an interface for editing this field (and the field is marked read-only). This means you need to follow special rules indicated for `setEditorProperties(FormItem)`. As an alternative, you can use `setReadOnlyEditorType(String)` or `setReadOnlyEditorType(Class)` to avoid these limitations, if you register the FormItem subclass with the `reflection mechanism`.

      Parameters:
        `editorProperties` - FormItem with properties to set when editing read-only values.

    - #### setReadOnlyEditorType

          public void setReadOnlyEditorType(java.lang.String editorType)

      Sets the default FormItem class to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.

      By using the `reflection mechanism`, this method avoids the limitations described in `setReadOnlyEditorProperties(FormItem)`.

      Parameters:
        `editorType` - a `FormItem` subclass, which must have been registered with the `reflection mechanism`.
      Throws:
        `java.lang.IllegalArgumentException` - if the editorType class has not beeen registered for use with the `reflection mechanism`, or if it does not inherit from `FormItem`.

    - #### setReadOnlyEditorType

          public void setReadOnlyEditorType(java.lang.Class<? extends FormItem> editorType)

      Sets the default `FormItem` class to be used if this field is marked as `canEdit false` and displayed in an editor component such as a DynamicForm.

      By using the `reflection mechanism`, this method avoids the limitations described in `setReadOnlyEditorProperties(FormItem)`.

      Parameters:
        `editorType` - a `FormItem` subclass, which must have been registered with the `reflection mechanism`.
      Throws:
        `java.lang.IllegalArgumentException` - if the editorType class has not beeen registered for use with the `reflection mechanism`, or if it does not inherit from `FormItem`.

    - #### setRootValue

          public void setRootValue(java.lang.String rootValue)

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

    - #### setRootValue

          public void setRootValue(java.lang.Integer rootValue)

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

    - #### setRootValue

          public void setRootValue(java.lang.Float rootValue)

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

    - #### setFieldValueExtractor

          public void setFieldValueExtractor(FieldValueExtractor extractor)

      Function to retrieve the field's value from the XML element or JSON record returned from a web service.

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

      Parameters:
        `extractor` - the field value extractor

    - #### setType

          public void setType(DataSource dataSource)

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

    - #### setTypeAsDataSource

          public void setTypeAsDataSource(DataSource dataSource)

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

    - #### getTypeAsDataSource

          public DataSource getTypeAsDataSource()

      Return the type of the assigned DataSource
      Returns:
        the DataSource

    - #### setSummaryFunction

          public void setSummaryFunction(SummaryFunctionType summaryFunction)

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

    - #### setSummaryFunction

          public void setSummaryFunction(java.lang.String summaryFunction)

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

    - #### getSummaryFunction

          public SummaryFunctionType getSummaryFunction()

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

    - #### setSummaryFunction

          public void setSummaryFunction(SummaryFunction summaryFunction)

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

    - #### setImageHeight

          public void setImageHeight(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.
      Parameters:
        `imageHeight` - imageHeight Default value is null

    - #### getImageHeight

          public java.lang.Integer getImageHeight()

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

    - #### setImageHeight

          public void setImageHeight(java.lang.String imageHeight)

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

    - #### getImageHeightAsString

          public java.lang.String getImageHeightAsString()

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

    - #### setImageSize

          public void setImageSize(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.
      Parameters:
        `imageSize` - imageSize Default value is null

    - #### getImageSize

          public java.lang.Integer getImageSize()

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

    - #### setImageSize

          public void setImageSize(java.lang.String imageSize)

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

    - #### getImageSizeAsString

          public java.lang.String getImageSizeAsString()

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

    - #### setImageWidth

          public void setImageWidth(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.
      Parameters:
        `imageWidth` - imageWidth Default value is null

    - #### getImageWidth

          public java.lang.Integer getImageWidth()

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

    - #### setImageWidth

          public void setImageWidth(java.lang.String imageWidth)

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

    - #### getImageWidthAsString

          public java.lang.String getImageWidthAsString()

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

    - #### setPrompt

          public void setPrompt(java.lang.String prompt)

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

    - #### getPrompt

          public java.lang.String getPrompt()

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

    - #### setCanEdit

          public void setCanEdit(java.lang.Boolean canEdit)

      Controls whether, by default, dataBoundComponents consider this field editable.

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

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

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

      Parameters:
        `canEdit` - canEdit Default value is null
      See Also:
        `setCanFilter(java.lang.Boolean)`, `setCanSave(java.lang.Boolean)`, `ComponentBinding overview and related methods`

    - #### getCanEdit

          public java.lang.Boolean getCanEdit()

      Controls whether, by default, dataBoundComponents consider this field editable.

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

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

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

      Returns:
        Boolean
      See Also:
        `getCanFilter()`, `getCanSave()`, `ComponentBinding overview and related methods`

    - #### getTypeAsSimpleType

          public SimpleType getTypeAsSimpleType()

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

    - #### getType

          public FieldType getType()

      Type of this field. Required for all DataSource fields.

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

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