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)
           
 Boolean getCanEdit()
          Whether this field can ever be edited by the user.
 Boolean getCanExport()
          Dictates whether the data in this field be exported.
 Boolean getCanFilter()
          Should the user be able to filter data by this field.
 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 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(com.google.gwt.core.client.JavaScriptObject).
 Boolean getDetail()
          Whether this field should be considered a "detail" field by a DataBoundComponent.
 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.
 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.
 String getJavaClass()
          For use with the Smart GWT server when populating Java Beans / POJOs based on data contained in a DSRequest, javaClass specifies the fully qualified Java className to be created and passed to the setter for the Java Bean Property with the same name as this field.
 String getJavaCollectionClass()
          See javaClass - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of type Collection or Map, javaCollectionClass can be used to specify a particular concrete class to use.
 String getJavaKeyClass()
          See javaClass - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of Map type, javaKeyClass can be used to specify a particular concrete class for the map keys.
 Integer getLength()
          Maximum number of characters allowed.
 Integer getMaxFileSize()
          For fields of a type that are represented by binary data initially uploaded from a file (currently "binary" and "imageFile", see FieldType), this sets the maximum file size allowed, in bytes.
 Boolean getMultiple()
          Indicates that this field should always be Array-valued.
 String getName()
          Name for this field.
static DataSourceField getOrCreateRef(JavaScriptObject jsObj)
           
 String getPluralTitle()
          Return the plural title.
 Boolean getPrimaryKey()
          Whether this field holds a value unique across all records in this DataSource.
 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.
 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.
 HashAlgorithm getStoreWithHash()
          If set, causes the field to be securely hashed before saving on an "add" or "update" operation.
 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 getTitle()
          Default user-visible title for this field.
 FieldType getType()
          Type of this field.
 DataSource getTypeAsDataSource()
          Return the type of the assigned DataSource
 String getValueXPath()
          XPath expression used to retrieve the field's value.
 Boolean getXmlAttribute()
          Indicates that DataSource.xmlSerialize(com.google.gwt.core.client.JavaScriptObject) should serialize this value as an XML attribute.
 void setCanEdit(Boolean canEdit)
          Whether this field can ever be edited by the user.
 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.
 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 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(com.google.gwt.core.client.JavaScriptObject).
 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 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 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 setJavaClass(String javaClass)
          For use with the Smart GWT server when populating Java Beans / POJOs based on data contained in a DSRequest, javaClass specifies the fully qualified Java className to be created and passed to the setter for the Java Bean Property with the same name as this field.
 void setJavaCollectionClass(String javaCollectionClass)
          See javaClass - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of type Collection or Map, javaCollectionClass can be used to specify a particular concrete class to use.
 void setJavaKeyClass(String javaKeyClass)
          See javaClass - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of Map type, javaKeyClass can be used to specify a particular concrete class for the map keys.
 void setLength(Integer length)
          Maximum number of characters allowed.
 void setMaxFileSize(Integer maxFileSize)
          For fields of a type that are represented by binary data initially uploaded from a file (currently "binary" and "imageFile", see FieldType), this sets the maximum file size allowed, in bytes.
 void setMultiple(Boolean multiple)
          Indicates that this field should always be Array-valued.
 void setName(String name)
          Name for this field.
 void setPluralTitle(String pluralTitle)
          Set the plural title.
 void setPrimaryKey(Boolean primaryKey)
          Whether this field holds a value unique across all records in this DataSource.
 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 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(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 setStoreWithHash(HashAlgorithm storeWithHash)
          If set, causes the field to be securely hashed before saving on an "add" or "update" operation.
 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 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 setValidators(Validator... validators)
          Validators to be applied to this field.
 void setValidOperators(OperatorId... operators)
          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(com.google.gwt.core.client.JavaScriptObject) should serialize this value as an XML attribute.
 
Methods inherited from class com.smartgwt.client.core.DataClass
doAddHandler, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsObject, 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
 
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)

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.

Parameters:
name - name Default value is null

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.

Returns:
String

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

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

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

setLength

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

Parameters:
length - length Default value is null

getLength

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

Returns:
Integer

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(java.lang.Object, java.lang.String) passing the selected XML element. For JSON data ('dataFormat:"json"'), this means a call to XMLTools.selectObjects(java.lang.Object, java.lang.String) 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 - valueXPath Default value is null

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(java.lang.Object, java.lang.String) passing the selected XML element. For JSON data ('dataFormat:"json"'), this means a call to XMLTools.selectObjects(java.lang.Object, java.lang.String) 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:
String

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.

Parameters:
title - title Default value is null

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.

Returns:
String

setCanEdit

public void setCanEdit(Boolean canEdit)
Whether this field can ever be edited by the user. If set to false, no DataBound component will ever try to offer an editing interface for this field.

Parameters:
canEdit - canEdit Default value is null

getCanEdit

public Boolean getCanEdit()
Whether this field can ever be edited by the user. If set to false, no DataBound component will ever try to offer an editing interface for this field.

Returns:
Boolean

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

Note: if canEdit is explicitly specified it will take precedence over this behavior.

Parameters:
canSave - canSave Default value is null

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

Note: if canEdit is explicitly specified it will take precedence over this behavior.

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

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

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.

Parameters:
hidden - hidden Default value is false

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.

Returns:
Boolean

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

getIgnore

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

Returns:
Boolean

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 com.smartgwt.client.widgets.form.fields.FormItem#showIf property is supported in multiple components for conditional visibility - see for example com.smartgwt.client.widgets.grid.ListGridField#showIf and com.smartgwt.client.widgets.form.fields.FormItem#showIf).

Parameters:
detail - detail Default value is false

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 com.smartgwt.client.widgets.form.fields.FormItem#showIf property is supported in multiple components for conditional visibility - see for example com.smartgwt.client.widgets.grid.ListGridField#showIf and com.smartgwt.client.widgets.form.fields.FormItem#showIf).

Returns:
Boolean

setPrimaryKey

public void setPrimaryKey(Boolean primaryKey)
Whether this field holds a value unique across all records in this DataSource.

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, exactly one field 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. The only requirement is that values of the primaryKey field be unique for a given browser instance for the lifetime of the page.

If your underlying data model has no primaryKey or has multiple primaryKey(s), you can generate unique values or combine multiple values into a single field that serves as a unique key, and declare that field as the single primary key instead. For example, if your underlying data model has two primary keys "firstName" and "lastName", you can use DataSource.transformResponse(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest, java.lang.Object) to combine them to into a new field "name_key":

 isc.DataSource.create({
    fields:[
        {name:"name_key",
 primaryKey:true},
        {name:"firstName"},
        {name:"lastName"},
        ... other fields ...
  
 ],
    transformResponse : function (dsResponse) {
        var data = dsResponse.data;
        for (var i =
 0 ; i < data.length; i++) {
            data[i].name_key = data[i].firstName + ":" +
                        
 data[i].lastName;
        }
    }
 });
 

Here it is assumed that ":" is not a legal character in either the firstName or lastName field. Updates to records from this DataSource will then be sent with name_key as the primary key value, and the server can split the value to obtain the separate key values.

If using ISC's 'SQL engine' and generating SQL tables using the "Databases" tab of the Developer Console, the table column generated from a primaryKey field will have a unique constraint applied in the database table.

Parameters:
primaryKey - primaryKey Default value is false

getPrimaryKey

public Boolean getPrimaryKey()
Whether this field holds a value unique across all records in this DataSource.

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, exactly one field 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. The only requirement is that values of the primaryKey field be unique for a given browser instance for the lifetime of the page.

If your underlying data model has no primaryKey or has multiple primaryKey(s), you can generate unique values or combine multiple values into a single field that serves as a unique key, and declare that field as the single primary key instead. For example, if your underlying data model has two primary keys "firstName" and "lastName", you can use DataSource.transformResponse(com.smartgwt.client.data.DSResponse, com.smartgwt.client.data.DSRequest, java.lang.Object) to combine them to into a new field "name_key":

 isc.DataSource.create({
    fields:[
        {name:"name_key",
 primaryKey:true},
        {name:"firstName"},
        {name:"lastName"},
        ... other fields ...
  
 ],
    transformResponse : function (dsResponse) {
        var data = dsResponse.data;
        for (var i =
 0 ; i < data.length; i++) {
            data[i].name_key = data[i].firstName + ":" +
                        
 data[i].lastName;
        }
    }
 });
 

Here it is assumed that ":" is not a legal character in either the firstName or lastName field. Updates to records from this DataSource will then be sent with name_key as the primary key value, and the server can split the value to obtain the separate key values.

If using ISC's 'SQL engine' and generating SQL tables using the "Databases" tab of the Developer Console, the table column generated from a primaryKey field will have a unique constraint applied in the database table.

Returns:
Boolean

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 DataBoundComponent, such as ListGrid.fetchRelatedData(com.smartgwt.client.data.Record, com.smartgwt.client.data.DataSource).

Parameters:
foreignKey - foreignKey Default value is false

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 DataBoundComponent, such as ListGrid.fetchRelatedData(com.smartgwt.client.data.Record, com.smartgwt.client.data.DataSource).

Returns:
String

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

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

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) OR you are trying to use the same sequence across multiple DataSources.

Parameters:
sequenceName - sequenceName Default value is null

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) OR you are trying to use the same sequence across multiple DataSources.

Returns:
String

setXmlAttribute

public void setXmlAttribute(Boolean xmlAttribute)
Indicates that DataSource.xmlSerialize(com.google.gwt.core.client.JavaScriptObject) 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

getXmlAttribute

public Boolean getXmlAttribute()
Indicates that DataSource.xmlSerialize(com.google.gwt.core.client.JavaScriptObject) 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

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

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

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(com.google.gwt.core.client.JavaScriptObject).

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

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(com.google.gwt.core.client.JavaScriptObject).

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

Returns:
String

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

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

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

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

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

getGroup

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

Returns:
String

setJavaClass

public void setJavaClass(String javaClass)
For use with the Smart GWT server when populating Java Beans / POJOs based on data contained in a DSRequest, javaClass specifies the fully qualified Java className to be created and passed to the setter for the Java Bean Property with the same name as this field. javaClass is used both when manually calling DataSource.setProperties() and when auto-populating POJO arguments of a com.smartgwt.client..DMI method.

The Java class to create does not normally have to be specified: Smart GWT will use Java reflection to inspect the type of argument expected by a setter method and will attempt conversion of inbound data to that type. As described in the documentation for DataTools.setProperties(), this works for almost all typical cases. However field.javaClass is useful for:

Parameters:
javaClass - javaClass Default value is null

getJavaClass

public String getJavaClass()
For use with the Smart GWT server when populating Java Beans / POJOs based on data contained in a DSRequest, javaClass specifies the fully qualified Java className to be created and passed to the setter for the Java Bean Property with the same name as this field. javaClass is used both when manually calling DataSource.setProperties() and when auto-populating POJO arguments of a com.smartgwt.client..DMI method.

The Java class to create does not normally have to be specified: Smart GWT will use Java reflection to inspect the type of argument expected by a setter method and will attempt conversion of inbound data to that type. As described in the documentation for DataTools.setProperties(), this works for almost all typical cases. However field.javaClass is useful for:

Returns:
String

setJavaCollectionClass

public void setJavaCollectionClass(String javaCollectionClass)
See javaClass - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of type Collection or Map, javaCollectionClass can be used to specify a particular concrete class to use. If not specified, and a concrete Collection or Map class cannot be discovered using Java Reflection, the following concrete classes are used: Note that this value is used even if the target Collection or Map is declared as a concrete class. So, for example, if you set javaCollectionClass to java.util.LinkedList but your setter method accepts a java.util.ArrayList, you will get a ClassCastException.

Parameters:
javaCollectionClass - javaCollectionClass Default value is null

getJavaCollectionClass

public String getJavaCollectionClass()
See javaClass - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of type Collection or Map, javaCollectionClass can be used to specify a particular concrete class to use. If not specified, and a concrete Collection or Map class cannot be discovered using Java Reflection, the following concrete classes are used: Note that this value is used even if the target Collection or Map is declared as a concrete class. So, for example, if you set javaCollectionClass to java.util.LinkedList but your setter method accepts a java.util.ArrayList, you will get a ClassCastException.

Returns:
String

setJavaKeyClass

public void setJavaKeyClass(String javaKeyClass)
See javaClass - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of Map type, javaKeyClass can be used to specify a particular concrete class for the map keys. If not specified, and a concrete type cannot be discovered using Java Reflection, java.lang.Object is used. Note that javaKeyClass take precedence over generics if both are used.

Parameters:
javaKeyClass - javaKeyClass Default value is null

getJavaKeyClass

public String getJavaKeyClass()
See javaClass - when auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of Map type, javaKeyClass can be used to specify a particular concrete class for the map keys. If not specified, and a concrete type cannot be discovered using Java Reflection, java.lang.Object is used. Note that javaKeyClass take precedence over generics if both are used.

Returns:
String

setExportTitle

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

Parameters:
exportTitle - exportTitle Default value is null

getExportTitle

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

Returns:
String

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

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

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

setStoreWithHash

public void setStoreWithHash(HashAlgorithm storeWithHash)
If set, causes the field to be securely hashed before saving on an "add" or "update" operation.

Parameters:
storeWithHash - storeWithHash Default value is null

getStoreWithHash

public HashAlgorithm getStoreWithHash()
If set, causes the field to be securely hashed before saving on an "add" or "update" operation.

Returns:
HashAlgorithm

setMaxFileSize

public void setMaxFileSize(Integer maxFileSize)
For fields of a type that are represented by binary data initially uploaded from a file (currently "binary" and "imageFile", see FieldType), this sets the maximum file size allowed, in bytes.

Parameters:
maxFileSize - maxFileSize Default value is null

getMaxFileSize

public Integer getMaxFileSize()
For fields of a type that are represented by binary data initially uploaded from a file (currently "binary" and "imageFile", see FieldType), this sets the maximum file size allowed, in bytes.

Returns:
Integer

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

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 - the validators

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 a Map 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 type as "enum", or use an com.smartgwt.client.types.ValidatorTypes#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 ComboBoxItem 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

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 a Map 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 type as "enum", or use an com.smartgwt.client..ValidatorTypes#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 ComboBoxItem will allow other values to be entered.

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

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

setValidOperators

public void setValidOperators(OperatorId... operators)
List of operators valid on this field.

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

Parameters:
operators - validOperators 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

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