Package com.smartgwt.client.data

# Class DBCField

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

All Implemented Interfaces:
  `HasHandlers`

Direct Known Subclasses:
  `DetailViewerField`, `ListGridField`

public class DBCField extends Field
Represents a field in a `DataBoundComponent`.

See Also:
  - `ListGridField`
  - `DetailViewerField`

- ## Field Summary

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

  `id`

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

  `factoryCreated, factoryProperties`

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

  `jsObj`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DBCField()`
  `DBCField(JavaScriptObject jsObj)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DateDisplayFormat`
  `getDateFormatter()`
  Preferred display format to use for date type values within this field.
  `String`
  `getDisplayField()`
  When records from this dataSource are displayed in a dataBoundComponent such as a `ListGrid`, the `displayField` attribute may be used to cause some field to display a value from another field in the record.
  `String`
  `getName()`
  Name of this field.
  `static DBCField`
  `getOrCreateRef(JavaScriptObject jsObj)`
  `TimeDisplayFormat`
  `getTimeFormatter()`
  Preferred time-format to apply to date type values within this field.
  `Map`
  `getValueMap()`
  A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.
  `DBCField`
  `setDateFormatter(DateDisplayFormat dateFormatter)`
  Preferred display format to use for date type values within this field.
  `DBCField`
  `setDisplayField(String displayField)`
  When records from this dataSource are displayed in a dataBoundComponent such as a `ListGrid`, the `displayField` attribute may be used to cause some field to display a value from another field in the record.
  `DBCField`
  `setName(String name)`
  Name of this field.
  `DBCField`
  `setTimeFormatter(TimeDisplayFormat timeFormatter)`
  Preferred time-format to apply to date type values within this field.
  `DBCField`
  `setValueMap(Map valueMap)`
  A `com.smartgwt.client.types.ValueMap` is a set of legal values for a field.

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

  `getCanEdit, getCanExport, getEscapeHTML, getExportTitle, getMultiple, getPrimaryKey, getSortByField, getTitle, setCanEdit, setCanExport, setEscapeHTML, setExportTitle, setMultiple, setPrimaryKey, setRequired, setSortByField, setTitle`

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

  `getRef, getRef, internalSetID`

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

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

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

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

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

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

- ## Constructor Details

  - ### DBCField

    public DBCField()

  - ### DBCField

    public DBCField(JavaScriptObject jsObj)

- ## Method Details

  - ### getOrCreateRef

    public static DBCField getOrCreateRef(JavaScriptObject jsObj)

  - ### setDateFormatter

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

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

    Note : This is an advanced setting

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

  - ### getDateFormatter

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

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

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

  - ### setDisplayField

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

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

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

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

  - ### getDisplayField

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

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

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

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

  - ### setName

    public DBCField setName(String name)
    Name of this field. Must be unique within the `DataBoundComponent` as well as a valid JavaScript identifier. See `FieldName` for details and how to check for validity.

    The name of the field is usually also the property in each record which holds the record's value for the field.

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

  - ### getName

    public String getName()
    Name of this field. Must be unique within the `DataBoundComponent` as well as a valid JavaScript identifier. See `FieldName` for details and how to check for validity.

    The name of the field is usually also the property in each record which holds the record's value for the field.

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

  - ### setTimeFormatter

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

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

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

    Note : This is an advanced setting

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

  - ### getTimeFormatter

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

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

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

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

  - ### setValueMap

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

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

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

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

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

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

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

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

  - ### getValueMap

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

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

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

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

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

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

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

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