com.smartgwt.client.data
Class DataSourceField

java.lang.Object
  extended by com.smartgwt.client.core.JsObject
      extended by com.smartgwt.client.core.DataClass
          extended by 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.JsObject
jsObj
 
Constructor Summary
DataSourceField()
           
DataSourceField(JavaScriptObject jsObj)
           
DataSourceField(String name, FieldType type)
           
DataSourceField(String name, FieldType type, String title)
           
DataSourceField(String name, FieldType type, String title, int length)
           
DataSourceField(String name, FieldType type, String title, int length, boolean required)
           
 
Method Summary
static DataSourceField[] convertToDataSourceFieldArray(JavaScriptObject nativeArray)
           
 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.
 Boolean getAutoGenerated()
          Indicates this field value is auto-generated by data base or ORM provider.
 Boolean getCanEdit()
          Controls whether, by default, dataBoundComponents consider this field editable.
 Boolean getCanExport()
          Dictates whether the data in this field be exported.
 Boolean getCanFilter()
          Should the user be able to filter data by this field? Effects whether this field will show up in dataBoundComponents with UI for filtering data.
 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.
 Boolean getCanView()
          If false, this property indicates that this field is considered "server only".
 Boolean getChildrenProperty()
          If true, this property indicates that this field will hold an explicit array of child nodes for the current node.
 String getChildTagName()
          For a field that is multiple:"true", controls the name of the XML tag used for each subelement during DataSource.xmlSerialize.
 Boolean getCustomSQL()
          For a DataSource with serverType "sql" or "hibernate", indicates that this field should be omitted by default from all SQL or Hibernate operations, and will only be used with custom queries.
 DateDisplayFormat getDateFormatter()
          Preferred display format to use for date type values within this field.
 Integer getDecimalPad()
          Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.
 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.
 Boolean getEscapeHTML()
          When data values are displayed in DataBound components, by default strings will be interpreted as HTML by the browser in most cases.
 String getExportTitle()
          Optional different field-title used for exports.
 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.
 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.
 Boolean getIgnore()
          Whether this field should be completely excluded from this dataSource, as if it had never been defined.
 Integer getImageHeight()
          Height of the image-content of this field.
 String getImageHeightAsString()
          Height of the image-content of this field.
 Integer getImageSize()
          Width and height of the image-content of this field.
 String getImageSizeAsString()
          Width and height of the image-content of this field.
 Integer getImageWidth()
          Width of the image-content of this field.
 String getImageWidthAsString()
          Width of the image-content of this field.
 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.
 Integer getLength()
          Maximum number of characters allowed.
 Boolean getMultiple()
          Indicates that this field should always be Array-valued.
 String getName()
          Name for this field.
 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)
           
 String getPluralTitle()
          Return the plural title.
 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.
 String getPrompt()
          Causes a tooltip hover to appear on the header generated for this field (effectively sets prompt for the header).
 Boolean getPropertiesOnly()
          For use in ComponentSchema for fields that contain other components, this flag suppresses auto-construction for subcomponents that appear under this field.
 Boolean getRequired()
          Indicates this field must be non-null in order for a record to pass validation.
 Object getRootValue()
          For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
 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.
 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.
 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.
 String getTitle()
          Default user-visible title for this field.
 FieldType getType()
          Type of this field.
 DataSource getTypeAsDataSource()
          Return the type of the assigned DataSource
 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.
 Map getValueMap()
          A ValueMap is a set of legal values for a field.
 String getValueXPath()
          XPath expression used to retrieve the field's value.
 Boolean getXmlAttribute()
          Indicates that DataSource.xmlSerialize should serialize this value as an XML attribute.
 void setAutoGenerated(Boolean autoGenerated)
          Indicates this field value is auto-generated by data base or ORM provider.
 void setCanEdit(Boolean canEdit)
          Controls whether, by default, dataBoundComponents consider this field editable.
 void setCanExport(Boolean canExport)
          Dictates whether the data in this field be exported.
 void setCanFilter(Boolean canFilter)
          Should the user be able to filter data by this field? Effects whether this field will show up in dataBoundComponents with UI for filtering data.
 void setCanSave(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(Boolean canView)
          If false, this property indicates that this field is considered "server only".
 void setChildrenProperty(Boolean childrenProperty)
          If true, this property indicates that this field will hold an explicit array of child nodes for the current node.
 void setChildTagName(String childTagName)
          For a field that is multiple:"true", controls the name of the XML tag used for each subelement during DataSource.xmlSerialize.
 void setCustomSQL(Boolean customSQL)
          For a DataSource with serverType "sql" or "hibernate", indicates that this field should be omitted by default from all SQL or Hibernate operations, and will only be used with custom queries.
 void setDateFormatter(DateDisplayFormat dateFormatter)
          Preferred display format to use for date type values within this field.
 void setDecimalPad(Integer decimalPad)
          Applies only to fields of type "float" and enforces a minimum number of digits shown after the decimal point.
 void setDecimalPrecision(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 setEditorType(FormItem editorType)
          Sets the default FormItem to be used whenever this field is edited (whether in a grid, form, or other component).
 void setEscapeHTML(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 setExportTitle(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 setForeignKey(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 setGroup(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 setIgnore(Boolean ignore)
          Whether this field should be completely excluded from this dataSource, as if it had never been defined.
 void setImageHeight(Integer imageHeight)
          Height of the image-content of this field.
 void setImageHeight(String imageHeight)
          Height of the image-content of this field.
 void setImageSize(Integer imageSize)
          Width and height of the image-content of this field.
 void setImageSize(String imageSize)
          Width and height of the image-content of this field.
 void setImageWidth(Integer imageWidth)
          Width of the image-content of this field.
 void setImageWidth(String imageWidth)
          Width of the image-content of this field.
 void setInapplicable(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 setJavaScriptObject(JavaScriptObject jsObj)
           
 void setLength(Integer length)
          Maximum number of characters allowed.
 void setMultiple(Boolean multiple)
          Indicates that this field should always be Array-valued.
 void setName(String name)
          Name for this field.
 void setNillable(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(String pluralTitle)
          Set the plural title.
 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(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(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 setReadOnlyEditorType(FormItem editorType)
          Sets the default FormItem to be used if this field is marked as #setCanEdit,canEdit false and displayed in an editor component such as a DynamicForm.
 void setRequired(Boolean required)
          Indicates this field must be non-null in order for a record to pass validation.
 void setRootValue(Float rootValue)
          For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
 void setRootValue(Integer rootValue)
          For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
 void setRootValue(Object rootValue)
          For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
 void setRootValue(String rootValue)
          For a field that is a foreignKey establishing a tree relationship, what value indicates a root-level node.
 void setSequenceName(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(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(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(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(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(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(Map valueMap)
          A ValueMap is a set of legal values for a field.
 void setValueMap(String... valueMap)
          A ValueMap is a set of legal values for a field.
 void setValueXPath(String valueXPath)
          XPath expression used to retrieve the field's value.
 void setXmlAttribute(Boolean xmlAttribute)
          Indicates that DataSource.xmlSerialize should serialize this value as an XML attribute.
 
Methods inherited from class com.smartgwt.client.core.DataClass
doAddHandler, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsDoubleArray, getAttributeAsFloat, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsJavaScriptObject, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsString, getAttributeAsStringArray, getAttributes, getHandlerCount, getJsObj, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute
 
Methods inherited from class com.smartgwt.client.core.JsObject
isCreated, setJsObj
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DataSourceField

public DataSourceField()

DataSourceField

public DataSourceField(JavaScriptObject jsObj)

DataSourceField

public DataSourceField(String name,
                       FieldType type)

DataSourceField

public DataSourceField(String name,
                       FieldType type,
                       String title)

DataSourceField

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

DataSourceField

public DataSourceField(String name,
                       FieldType type,
                       String title,
                       int length,
                       boolean required)
Method Detail

getOrCreateRef

public static DataSourceField getOrCreateRef(JavaScriptObject jsObj)

setJavaScriptObject

public void setJavaScriptObject(JavaScriptObject jsObj)

setAutoGenerated

public void setAutoGenerated(Boolean autoGenerated)
Indicates this field value is auto-generated by data base or ORM provider.

Parameters:
autoGenerated - autoGenerated Default value is null

getAutoGenerated

public Boolean getAutoGenerated()
Indicates this field value is auto-generated by data base or ORM provider.

Returns:
Boolean

setCanExport

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

getCanExport

public 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(Boolean canFilter)
Should the user be able to filter data by this field? Effects whether this field will show up in dataBoundComponents with UI for filtering data.

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

getCanFilter

public Boolean getCanFilter()
Should the user be able to filter data by this field? Effects 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(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 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 - canSave Default value is null
See Also:
ComponentBinding overview and related methods

getCanSave

public 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 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 - 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(Boolean canView)
If false, this property indicates that this field is considered "server only". This means: 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 - canView Default value is null
See Also:
ComponentBinding overview and related methods

getCanView

public Boolean getCanView()
If false, this property indicates that this field is considered "server only". This means: 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(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 - childrenProperty Default value is false
See Also:
DataSource.setChildrenField(java.lang.String), DataSourceRelations overview and related methods

getChildrenProperty

public 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(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 - . See String. Default value is null
See Also:
ComponentSchema overview and related methods

getChildTagName

public 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:
. See String
See Also:
ComponentSchema overview and related methods

setCustomSQL

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

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

The following are situations where you would not use customSQL:

Use customSQL in situations like:

Parameters:
customSQL - customSQL Default value is null

getCustomSQL

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

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

The following are situations where you would not use customSQL:

Use customSQL in situations like:

Returns:
Boolean

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 - 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(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 - decimalPad Default value is null
See Also:
Appearance overview and related methods

getDecimalPad

public 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(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 if always shown with its original precision when edited.

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

getDecimalPrecision

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

setEscapeHTML

public void setEscapeHTML(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 - escapeHTML Default value is null
See Also:
ListGridField.setEscapeHTML(java.lang.Boolean)

getEscapeHTML

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

setExportTitle

public void setExportTitle(String exportTitle)
Optional different field-title used for exports.

Parameters:
exportTitle - . See String. Default value is null

getExportTitle

public String getExportTitle()
Optional different field-title used for exports.

Returns:
. See String

setForeignKey

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

    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 - . See String. Default value is false
See Also:
com.smartgwt.client.docs.serverds.DataSourceField#joinType, DataSourceRelations overview and related methods

getForeignKey

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

    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:
. See String
See Also:
com.smartgwt.client.docs.serverds.DataSourceField#joinType, DataSourceRelations overview and related methods

setGroup

public void setGroup(String group)
For use in ComponentSchema, indicates what group to place the property in when editing in Visual Builder.

Parameters:
group - . See String. Default value is null
See Also:
ComponentSchema overview and related methods

getGroup

public String getGroup()
For use in ComponentSchema, indicates what group to place the property in when editing in Visual Builder.

Returns:
. See 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 outputs, canView:false on the field, or a field-level declarative security setting like viewRequiresRole.

Parameters:
hidden - 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 outputs, canView:false on the field, or a field-level declarative security setting like viewRequiresRole.

Returns:
Boolean
See Also:
ComponentBinding overview and related methods

setIgnore

public void setIgnore(Boolean ignore)
Whether this field should be completely excluded from this dataSource, as if it had never been defined.

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

getIgnore

public Boolean getIgnore()
Whether this field should be completely excluded from this dataSource, as if it had never been defined.

Returns:
Boolean
See Also:
ComponentBinding overview and related methods

setInapplicable

public void setInapplicable(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 - inapplicable Default value is null
See Also:
ComponentSchema overview and related methods

getInapplicable

public 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(Integer length)
Maximum number of characters allowed. Applicable only to fields of text type.

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
HSQLDBNone-
IBM DB24000CLOB
Firebird32767BLOB with subtype 1
Informix255 / 32739LVARCHAR / TEXT **
Microsoft SQL Server 8000TEXT
MySQL 255 / 65535 / 16M TEXT / MEDIUMTEXT / LONGTEXT ***
Oracle4000CLOB
PostgreSQL4000TEXT

* 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 - length Default value is null
See Also:
Long Text Example

getLength

public Integer getLength()
Maximum number of characters allowed. Applicable only to fields of text type.

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
HSQLDBNone-
IBM DB24000CLOB
Firebird32767BLOB with subtype 1
Informix255 / 32739LVARCHAR / TEXT **
Microsoft SQL Server 8000TEXT
MySQL 255 / 65535 / 16M TEXT / MEDIUMTEXT / LONGTEXT ***
Oracle4000CLOB
PostgreSQL4000TEXT

* 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

setMultiple

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

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 - multiple Default value is null
See Also:
ComponentSchema overview and related methods

getMultiple

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

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

setName

public void setName(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 - . See String. Default value is null
See Also:
Basics overview and related methods

getName

public 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:
. See String
See Also:
Basics overview and related methods

setNillable

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

getNillable

public 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

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. If a DataSource allows modification of DataSource records through add, update and remove DataSource operations, 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 - 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. If a DataSource allows modification of DataSource records through add, update and remove DataSource operations, 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(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 - propertiesOnly Default value is null
See Also:
ComponentSchema overview and related methods

getPropertiesOnly

public 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(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 - required Default value is null

getRequired

public 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(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 - rootValue Default value is null
See Also:
DataSourceRelations overview and related methods

getRootValue

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

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

getSequenceName

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

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

setShowFileInline

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

getShowFileInline

public 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(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 - . See String. Default value is null

getSummaryValueTitle

public 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:
. See 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 - 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(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 - . See String. Default value is null
See Also:
ComponentBinding overview and related methods

getTitle

public 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:
. See 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 - type Default value is null
See Also:
Basics overview and related methods

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.

Returns:
FieldType
See Also:
Basics overview and related methods

setUploadFieldName

public void setUploadFieldName(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 - . See String. Default value is null

getUploadFieldName

public 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:
. See 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 - 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 - 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(Map 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

getValueMap

public Map getValueMap()
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>
  

Returns:
Map

setValueXPath

public void setValueXPath(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 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(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 - xmlAttribute Default value is null
See Also:
ComponentSchema overview and related methods

getXmlAttribute

public 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(String pluralTitle)
Set the plural title.

Parameters:
pluralTitle - the plural title

getPluralTitle

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

setEditorType

public void setEditorType(FormItem editorType)
Sets the default FormItem to be used whenever this field is edited (whether in a grid, form, or other component).

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


Note: the FormItem passed to setEditorType() 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() { ... }
  }
  
  ...
  
  myDataSource.setEditorType(new MyCustomItem("field1"));
  

Parameters:
editorType - editorType Default value is null

setReadOnlyEditorType

public void setReadOnlyEditorType(FormItem editorType)
Sets the default FormItem to be used if this field is marked as #setCanEdit,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().

Parameters:
editorType - editorType Default value is null

setRootValue

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

convertToDataSourceFieldArray

public static DataSourceField[] convertToDataSourceFieldArray(JavaScriptObject nativeArray)

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