Class DBCField

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