Interface DataBoundComponent
- All Superinterfaces:
HasDragCompleteHandlers,HasDropCompleteHandlers,HasFetchDataHandlers,HasHandlers
- All Known Implementing Classes:
Calendar,CalendarView,ColumnTree,CubeGrid,DateGrid,DetailViewer,DynamicForm,EditTree,FacetChart,ListGrid,ListPalette,Menu,MenuPalette,PickListMenu,PropertySheet,RecordEditor,SearchForm,SelectionTreeMenu,TableView,TileGrid,TilePalette,Timeline,TreeGrid,TreePalette
A schema (or DataSource) describes an object as consisting of a set of properties (or "fields").
DataBoundComponents have a dataSource for dealing with binding to DataSources, fields
the schema information provided by a DataSource, and manipulating objects or sets of object from the DataSource.
The following visual components currently support databinding:
The following non-visual components also support databinding:DynamicFormDetailViewerListGridTreeGridTileGridColumnTreeCubeGrid
ValuesManagerResultSetResultTree
-
Method Summary
Modifier and TypeMethodDescriptionvoidConvenience method to display a {@link com.smartgwt.client..FormulaBuilder} to create a new Formula Field.voidConvenience method to display a {@link com.smartgwt.client..SummaryBuilder} to create a new Summary Field.Whether at least one item is selected
void
 Deselect all records

voiddeselectRecord(int record) Deselect aRecordpassed in explicitly, or by index.voiddeselectRecord(Record record) Deselect aRecordpassed in explicitly, or by index.voiddeselectRecords(int[] records) Deselect a list ofRecords passed in explicitly, or by index.voiddeselectRecords(Record[] records) Deselect a list ofRecords passed in explicitly, or by index.voiddisableHilite(String hiliteID) Disable a hilite

voidDisable all hilites.

voidShows a HiliteEditor interface allowing end-users to edit the data-hilites currently in use by this DataBoundComponent.voidenableHilite(String hiliteID) Enable / disable ahilites

voidenableHilite(String hiliteID, boolean enable) Enable / disable ahilites

voidEnable all hilites.

voidenableHiliting(boolean enable) Enable all hilites.

voidvoidexportData(DSRequest requestProperties) voidexportData(DSRequest requestProperties, RPCCallback callback) Uses a "fetch" operation on the currentDataSourceto retrieve data that matches the current filter and sort criteria for this component, then exports the resulting data to a file or window in the requested format.voidRetrieves data from the DataSource that matches the specified criteria.voidRetrieves data from the DataSource that matches the specified criteria.voidfetchData(Criteria criteria, DSCallback callback) Retrieves data from the DataSource that matches the specified criteria.voidfetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties) Retrieves data from the DataSource that matches the specified criteria.voidRetrieves data that matches the provided criteria and displays the matching data in this component.voidfilterData(Criteria criteria) Retrieves data that matches the provided criteria and displays the matching data in this component.voidfilterData(Criteria criteria, DSCallback callback) Retrieves data that matches the provided criteria and displays the matching data in this component.voidfilterData(Criteria criteria, DSCallback callback, DSRequest requestProperties) Retrieves data that matches the provided criteria and displays the matching data in this component.Indicates whether to add "drop values" to items dropped on this component, if both the source and target widgets are databound, either to the same DataSource or to different DataSources that are related via a foreign key.Text for a menu item allowing users to add a formula fieldoperationIdthis component should use when performing add operations.Text for a menu item allowing users to add a formula fieldIfsetAutoFetchData(Boolean)is true, this attribute determines whether the initial fetch operation should be performed viafetchData()orfilterData()If true, when this component is first drawn, automatically callfetchData()orfilterData()depending ongetAutoFetchAsFilter().IfautoFetchDataistrue, this attribute allows the developer to specify a textMatchStyle for the initialfetchData()call.Adds an item to the header context menu allowing users to launch a dialog to define a new
 field based on values present in other fields, using the {@link com.smartgwt.client..FormulaBuilder}.
Adds an item to the header context menu allowing users to launch a dialog to define a new
 text field that can contain both user-defined text and the formatted values present in other 
 fields, using the {@link com.smartgwt.client..SummaryBuilder}.
How to fetch and manage records retrieved from the server.intWhen usingdata paging, how many records to fetch at a time.The DataSource that this component should bind to for default fields and for performingDataSource requests.Before we start editing values in this DataBoundComponent, should we perform a deep clone of the underlying values.Record[]During a drag-and-drop interaction, this method returns the set of records being dragged out of the component.Indicates what to do with data dragged into another DataBoundComponent.CSS Style to apply to the drag tracker when dragging occurs on this component.When an item is dropped on this component, andaddDropValuesis true and both the source and target widgets are databound, either to the same DataSource or to different DataSources that are related via a foreign key, this object provides the "drop values" that Smart GWT will apply to the dropped object before updating it.Message to show when a user attempts to transfer duplicate records into this component, and
preventDuplicatesis enabled.Text for a menu item allowing users to edit a formula fieldText for a menu item allowing users to edit the formatter for a fieldSetting exportAll to true prevents the component from passing its list of fields to the 
 export call.String[]The list of field-names to export.If Summary rows exist for this component, whether to include them when exporting client data.Operation ID this component should use when performing fetch operations.Returna an array of field alignments for this gridintReturn the number of fields.Return the fields as JavaScriptObjects rather than as SmartGWT Java wrappers of the field class type (e.g.Marker that can be set on a record to flag that record as hilited.Hilite[]Return the set of hilite-objects currently applied to this DataBoundComponent.Get the current hilites encoded as a String, for saving.Criteria that are never shown to or edited by the user and are cumulative with any criteria provided viaDataBoundComponent.initialCriteria,DataBoundComponent.setCriteria()etc.Criteria to use whensetAutoFetchData(Boolean)is used.If set, detect and prevent duplicate records from being transferred to this component, either via
 drag and drop or viatransferSelectedData(com.smartgwt.client.widgets.DataBoundComponent).intgetRecordIndex(Record record) Get the index of the provided record.
Return the underlying data of this DataBoundComponent as aRecordList.operationIdthis component should use when performing remove operations.Return the underlying data of this DataBoundComponent as aResultSet.Optional identifier for saved searches that should be applied to this component.Whether to show fields of non-atomic types when a DataBoundComponent is given a
 DataSource but nocomponent.fields.
Whether to show fields markeddetail:truewhen a DataBoundComponent is 
 given a DataSource but nocomponent.fields.
Whether to show fields markedhidden:truewhen a DataBoundComponent is given a
 DataSource but nocomponent.fields.
booleanWhether to associate saved searches by default with the currentDataSourceof a component when asavedSearchIdis not provided.getSort()Returns the currentSortSpecifiersfor this component.If true,ListGrid.getFieldState()andListGrid.setFieldState(java.lang.String)will omit state information for hidden fields by default.Method to return the fieldName which represents the "title" for records in this
 Component.

 If this.titleField is explicitly specified it will always be used.
 Otherwise, default implementation will checktitleFieldfor databound
 components.

 For non databound components returns the first defined field name of"title", 
"name", or"id".getTitleFieldValue(Record record) Get the value of the titleField for the passed record
operationIdthis component should use when performing update operations.If true, the set of fields given by the "default binding" (see 
fields) is used, with any fields specified in
component.fieldsacting as overrides that can suppress or modify the
 display of individual fields, without having to list the entire set of fields that
 should be shown.
TheuseFlatFieldsflag causes all simple type fields anywhere in a nested
 set of DataSources to be exposed as a flat list for form binding.voidInvalidate the current data cache for this databound component via a call to the dataset'sinvalidateCache()method, for example,ResultSet.invalidateCache().voidSelect all records

voidselectRecord(int record) Select/deselect aRecordpassed in explicitly, or by index.voidselectRecord(int record, boolean newState) Select/deselect aRecordpassed in explicitly, or by index.voidselectRecord(Record record) Select/deselect aRecordpassed in explicitly, or by index.voidselectRecord(Record record, boolean newState) Select/deselect aRecordpassed in explicitly, or by index.voidselectRecords(int[] records) Select/deselect a list ofRecords passed in explicitly, or by index.voidselectRecords(int[] records, boolean newState) Select/deselect a list ofRecords passed in explicitly, or by index.voidselectRecords(Record[] records) Select/deselect a list ofRecords passed in explicitly, or by index.voidselectRecords(Record[] records, boolean newState) Select/deselect a list ofRecords passed in explicitly, or by index.setAddDropValues(Boolean addDropValues) Indicates whether to add "drop values" to items dropped on this component, if both the source and target widgets are databound, either to the same DataSource or to different DataSources that are related via a foreign key.setAddFormulaFieldText(String addFormulaFieldText) Text for a menu item allowing users to add a formula fieldsetAddOperation(String addOperation) operationIdthis component should use when performing add operations.setAddSummaryFieldText(String addSummaryFieldText) Text for a menu item allowing users to add a formula fieldsetAutoFetchAsFilter(Boolean autoFetchAsFilter) IfsetAutoFetchData(Boolean)is true, this attribute determines whether the initial fetch operation should be performed viafetchData()orfilterData()setAutoFetchData(Boolean autoFetchData) If true, when this component is first drawn, automatically callfetchData()orfilterData()depending ongetAutoFetchAsFilter().setAutoFetchTextMatchStyle(TextMatchStyle autoFetchAsFilter) IfautoFetchDataistrue, this attribute allows the developer to specify a textMatchStyle for the initialfetchData()call.setCanAddFormulaFields(Boolean canAddFormulaFields) Adds an item to the header context menu allowing users to launch a dialog to define a new
 field based on values present in other fields, using the {@link com.smartgwt.client..FormulaBuilder}.
setCanAddSummaryFields(Boolean canAddSummaryFields) Adds an item to the header context menu allowing users to launch a dialog to define a new
 text field that can contain both user-defined text and the formatted values present in other 
 fields, using the {@link com.smartgwt.client..SummaryBuilder}.
setDataFetchMode(FetchMode fetchMode) How to fetch and manage records retrieved from the server.setDataPageSize(int dataPageSize) When usingdata paging, how many records to fetch at a time.setDataSource(DataSource dataSource) Bind to a DataSource.setDataSource(String dataSource) Bind to a DataSource.setDeepCloneOnEdit(Boolean deepCloneOnEdit) Before we start editing values in this DataBoundComponent, should we perform a deep clone of the underlying values.setDragDataAction(DragDataAction dragDataAction) Indicates what to do with data dragged into another DataBoundComponent.setDragTrackerStyle(String dragTrackerStyle) CSS Style to apply to the drag tracker when dragging occurs on this component.setDropValues(Map dropValues) When an item is dropped on this component, andaddDropValuesis true and both the source and target widgets are databound, either to the same DataSource or to different DataSources that are related via a foreign key, this object provides the "drop values" that Smart GWT will apply to the dropped object before updating it.setDuplicateDragMessage(String duplicateDragMessage) Message to show when a user attempts to transfer duplicate records into this component, and
preventDuplicatesis enabled.setEditFormulaFieldText(String editFormulaFieldText) Text for a menu item allowing users to edit a formula fieldsetEditSummaryFieldText(String editSummaryFieldText) Text for a menu item allowing users to edit the formatter for a fieldsetExportAll(Boolean exportAll) Setting exportAll to true prevents the component from passing its list of fields to the 
 export call.setExportFields(String[] exportFields) The list of field-names to export.setExportIncludeSummaries(Boolean exportIncludeSummaries) If Summary rows exist for this component, whether to include them when exporting client data.setFetchOperation(String fetchOperation) Operation ID this component should use when performing fetch operations.setFields(JavaScriptObject... fields) Field setter variant (alternative tosetFields(FormItem...),setFields(ListGridField...), etc.) that will accept an array of JavaScriptObject, rather than an array of SmartGWT Java wrappers of the field class type (e.g.setHiliteProperty(String hiliteProperty) Marker that can be set on a record to flag that record as hilited.setHilites(Hilite[] hilites) Accepts an array of hilite objects and applies them to this DataBoundComponent.setHiliteState(String hiliteState) Set the current hilites based on a hiliteState String previously returned from getHilitesState.setImplicitCriteria(Criteria implicitCriteria) Criteria that are never shown to or edited by the user and are cumulative with any criteria provided viaDataBoundComponent.initialCriteria,DataBoundComponent.setCriteria()etc.setInitialCriteria(Criteria initialCriteria) Criteria to use whensetAutoFetchData(Boolean)is used.setPreventDuplicates(Boolean preventDuplicates) If set, detect and prevent duplicate records from being transferred to this component, either via
 drag and drop or viatransferSelectedData(com.smartgwt.client.widgets.DataBoundComponent).setRemoveOperation(String removeOperation) operationIdthis component should use when performing remove operations.setSavedSearchId(String savedSearchId) Optional identifier for saved searches that should be applied to this component.setShowComplexFields(Boolean showComplexFields) Whether to show fields of non-atomic types when a DataBoundComponent is given a
 DataSource but nocomponent.fields.
setShowDetailFields(Boolean showDetailFields) Whether to show fields markeddetail:truewhen a DataBoundComponent is 
 given a DataSource but nocomponent.fields.
setShowHiddenFields(Boolean showHiddenFields) Whether to show fields markedhidden:truewhen a DataBoundComponent is given a
 DataSource but nocomponent.fields.
setShowSavedSearchesByDS(boolean showSavedSearchesByDS) Whether to associate saved searches by default with the currentDataSourceof a component when asavedSearchIdis not provided.setSort(SortSpecifier... sortSpecifiers) Sort the component on one or more fields.setSparseFieldState(Boolean sparseFieldState) If true,ListGrid.getFieldState()andListGrid.setFieldState(java.lang.String)will omit state information for hidden fields by default.setTitleField(String titleField) Sets the best field to use for a user-visible title for an individual record from this component.setUpdateOperation(String updateOperation) operationIdthis component should use when performing update operations.setUseAllDataSourceFields(Boolean useAllDataSourceFields) If true, the set of fields given by the "default binding" (see 
fields) is used, with any fields specified in
component.fieldsacting as overrides that can suppress or modify the
 display of individual fields, without having to list the entire set of fields that
 should be shown.
setUseFlatFields(Boolean useFlatFields) TheuseFlatFieldsflag causes all simple type fields anywhere in a nested
 set of DataSources to be exposed as a flat list for form binding.voidtransferRecords(Record[] records, Record targetRecord, Integer index, Canvas sourceWidget, TransferRecordsCallback callback) Transfer a list ofRecords from another component (does not have to be a databound component) into this component.voidSimulates a drag / drop type transfer of the selected records in some other component to this component, without requiring any user interaction.voidtransferSelectedData(DataBoundComponent source, int index) Simulates a drag / drop type transfer of the selected records in some other component to this component, without requiring any user interaction.Methods inherited from interface com.smartgwt.client.widgets.events.HasDragCompleteHandlers
addDragCompleteHandlerMethods inherited from interface com.smartgwt.client.widgets.events.HasDropCompleteHandlers
addDropCompleteHandlerMethods inherited from interface com.smartgwt.client.widgets.events.HasFetchDataHandlers
addFetchDataHandlerMethods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
-
Method Details
-
getOrCreateJsObj
JavaScriptObject getOrCreateJsObj() -
setDataFetchMode
How to fetch and manage records retrieved from the server. SeeFetchMode.This setting only applies to the
ResultSetautomatically created by callingfetchData. If a pre-existing ResultSet is passed tosetData()instead, its existing setting forfetchModeapplies.- Parameters:
fetchMode- the fetch mode- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getDataFetchMode
FetchMode getDataFetchMode()How to fetch and manage records retrieved from the server. SeeFetchMode.This setting only applies to the
ResultSetautomatically created by callingfetchData. If a pre-existing ResultSet is passed tosetData()instead, its existing setting forfetchModeapplies.- Returns:
- the fetch mode
-
setDataPageSize
When usingdata paging, how many records to fetch at a time. If set to a positive integer,dataPageSizewill override the defaultresultSizefor ResultSets automatically created when you callfetchData()(and similarly for theresultSizeof ResultTrees). The default of 0 means to just use the default page size of the data container.Note that regardless of the
dataPageSizesetting, a component will always fetch all of data that it needs to draw. Settings such asshowAllRecords:true,drawAllMaxCellsanddrawAheadRatiocan cause more rows than the configureddataPageSizeto be fetched.- Parameters:
dataPageSize- dataPageSize Default value is 0- Returns:
DataBoundComponentinstance, for chaining setter calls- See Also:
-
getDataPageSize
int getDataPageSize()When usingdata paging, how many records to fetch at a time. If set to a positive integer,dataPageSizewill override the defaultresultSizefor ResultSets automatically created when you callfetchData()(and similarly for theresultSizeof ResultTrees). The default of 0 means to just use the default page size of the data container.Note that regardless of the
dataPageSizesetting, a component will always fetch all of data that it needs to draw. Settings such asshowAllRecords:true,drawAllMaxCellsanddrawAheadRatiocan cause more rows than the configureddataPageSizeto be fetched.- Returns:
- int
- See Also:
-
setUseAllDataSourceFields
If true, the set of fields given by the "default binding" (see 
fields) is used, with any fields specified in
component.fieldsacting as overrides that can suppress or modify the
 display of individual fields, without having to list the entire set of fields that
 should be shown.

 If
component.fieldscontains fields that are not found in the DataSource,
 they will be shown after the most recently referred to DataSource field. If the new
 fields appear first, they will be shown first.- Parameters:
useAllDataSourceFields- useAllDataSourceFields Default value is false- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getUseAllDataSourceFields
Boolean getUseAllDataSourceFields()If true, the set of fields given by the "default binding" (see 
fields) is used, with any fields specified in
component.fieldsacting as overrides that can suppress or modify the
 display of individual fields, without having to list the entire set of fields that
 should be shown.

 If
component.fieldscontains fields that are not found in the DataSource,
 they will be shown after the most recently referred to DataSource field. If the new
 fields appear first, they will be shown first.- Returns:
- Boolean
-
setSparseFieldState
If true,ListGrid.getFieldState()andListGrid.setFieldState(java.lang.String)will omit state information for hidden fields by default.- Parameters:
sparseFieldState- sparseFieldState Default value is false- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getSparseFieldState
Boolean getSparseFieldState()If true,ListGrid.getFieldState()andListGrid.setFieldState(java.lang.String)will omit state information for hidden fields by default.- Returns:
- Boolean
-
setShowHiddenFields
Whether to show fields markedhidden:truewhen a DataBoundComponent is given a
 DataSource but nocomponent.fields.

 The
hiddenproperty is used on DataSource fields to mark fields that are
 never of meaning to an end user.- Parameters:
showHiddenFields- showHiddenFields Default value is false- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getShowHiddenFields
Boolean getShowHiddenFields()Whether to show fields markedhidden:truewhen a DataBoundComponent is given a
 DataSource but nocomponent.fields.

 The
hiddenproperty is used on DataSource fields to mark fields that are
 never of meaning to an end user.- Returns:
- Boolean
-
setShowDetailFields
Whether to show fields markeddetail:truewhen a DataBoundComponent is 
 given a DataSource but nocomponent.fields.

 The
detailproperty is used on DataSource fields to mark fields that 
 shouldn't appear by default in a view that tries to show many records in a small space.- Parameters:
showDetailFields- showDetailFields Default value is false- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getShowDetailFields
Boolean getShowDetailFields()Whether to show fields markeddetail:truewhen a DataBoundComponent is 
 given a DataSource but nocomponent.fields.

 The
detailproperty is used on DataSource fields to mark fields that 
 shouldn't appear by default in a view that tries to show many records in a small space.- Returns:
- Boolean
-
setShowComplexFields
Whether to show fields of non-atomic types when a DataBoundComponent is given a
 DataSource but nocomponent.fields.

 If true, the component will show fields that declare a complex type, for example, a
 field 'shippingAddress' that declares type 'Address', where 'Address' is the ID of a
 DataSource that declares the fields of a shipping address (city, street name, etc).


 Such fields may need custom formatters or editors in order to create a usable interface,
 for example, an Address field in a ListGrid might use a custom formatter to combine the
 relevant fields of an address into one column, and might use a pop-up dialog for
 editing.
Note : This is an advanced setting
- Parameters:
showComplexFields- showComplexFields Default value is true- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getShowComplexFields
Boolean getShowComplexFields()Whether to show fields of non-atomic types when a DataBoundComponent is given a
 DataSource but nocomponent.fields.

 If true, the component will show fields that declare a complex type, for example, a
 field 'shippingAddress' that declares type 'Address', where 'Address' is the ID of a
 DataSource that declares the fields of a shipping address (city, street name, etc).


 Such fields may need custom formatters or editors in order to create a usable interface,
 for example, an Address field in a ListGrid might use a custom formatter to combine the
 relevant fields of an address into one column, and might use a pop-up dialog for
 editing.
- Returns:
- Boolean
-
setFetchOperation
Operation ID this component should use when performing fetch operations.- Parameters:
fetchOperation- fetchOperation Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getFetchOperation
String getFetchOperation()Operation ID this component should use when performing fetch operations.- Returns:
- String
-
setUpdateOperation
operationIdthis component should use when performing update operations.- Parameters:
updateOperation- Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls- See Also:
-
getUpdateOperation
String getUpdateOperation()operationIdthis component should use when performing update operations.- Returns:
- String
- See Also:
-
setAddOperation
operationIdthis component should use when performing add operations.- Parameters:
addOperation- Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls- See Also:
-
getAddOperation
String getAddOperation()operationIdthis component should use when performing add operations.- Returns:
- String
- See Also:
-
setRemoveOperation
operationIdthis component should use when performing remove operations.- Parameters:
removeOperation- Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls- See Also:
-
getRemoveOperation
String getRemoveOperation()operationIdthis component should use when performing remove operations.- Returns:
- String
- See Also:
-
setExportFields
The list of field-names to export. If provided, the field-list in the exported output is 
 limited and sorted as per the list.

 If exportFields is not provided, the exported output includes all visible fields 
 from this component, sorted as they appear.
- Parameters:
exportFields- exportFields Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getExportFields
String[] getExportFields()The list of field-names to export. If provided, the field-list in the exported output is 
 limited and sorted as per the list.

 If exportFields is not provided, the exported output includes all visible fields 
 from this component, sorted as they appear.
- Returns:
- the list of field-names to export.
-
setExportAll
Setting exportAll to true prevents the component from passing its list of fields to the 
 export call. The result is the export of all visible fields fromfields.

 If exportAll is false, an export operation will first consider 

exportFields, if it's set, and fall back on all visible fields from
fieldsotherwise.- Parameters:
exportAll- exportAll Default value is false- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getExportAll
Boolean getExportAll()Setting exportAll to true prevents the component from passing its list of fields to the 
 export call. The result is the export of all visible fields fromfields.

 If exportAll is false, an export operation will first consider 

exportFields, if it's set, and fall back on all visible fields from
fieldsotherwise.- Returns:
- Boolean
-
setExportIncludeSummaries
If Summary rows exist for this component, whether to include them when exporting client data. Defaults to true if not set- Parameters:
exportIncludeSummaries- exportIncludeSummaries Default value is true- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getExportIncludeSummaries
Boolean getExportIncludeSummaries()If Summary rows exist for this component, whether to include them when exporting client data. Defaults to true if not set- Returns:
- Boolean
-
setPreventDuplicates
If set, detect and prevent duplicate records from being transferred to this component, either via
 drag and drop or viatransferSelectedData(com.smartgwt.client.widgets.DataBoundComponent). When a duplicate transfer is detected,
 a dialog will appear showing theduplicateDragMessage.

 If the component either does not have a
DataSourceor has a DataSource with no
primaryKeydeclared, duplicate checking is off by
 default. If duplicate checking is enabled, it looks for an existing record in the dataset
 that has all of the properties of the dragged record, and considers that a duplicate.

 For
DragDataAction:"copy" where the target DataSource is related to the source
 DataSource by foreignKey, a duplicate means that the target list, as filtered by the current
 criteria, already has a record whose value for the foreignKey field matches the
 primaryKey of the record being transferred.

 For example, consider dragging "employees" to "teams", where "teams" has a field
 "teams.employeeId" which is a foreignKey pointing to "employees.id", and the target
 grid has search criteria causing it to show all the members of one team. A duplicate -
 adding an employee to the same team twice - is when the target grid's dataset contains an
 record with "employeeId" matching the "id" field of the dropped employee.
- Parameters:
preventDuplicates- preventDuplicates Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the component has been created
-
getPreventDuplicates
Boolean getPreventDuplicates()If set, detect and prevent duplicate records from being transferred to this component, either via
 drag and drop or viatransferSelectedData(com.smartgwt.client.widgets.DataBoundComponent). When a duplicate transfer is detected,
 a dialog will appear showing theduplicateDragMessage.

 If the component either does not have a
DataSourceor has a DataSource with no
primaryKeydeclared, duplicate checking is off by
 default. If duplicate checking is enabled, it looks for an existing record in the dataset
 that has all of the properties of the dragged record, and considers that a duplicate.

 For
DragDataAction:"copy" where the target DataSource is related to the source
 DataSource by foreignKey, a duplicate means that the target list, as filtered by the current
 criteria, already has a record whose value for the foreignKey field matches the
 primaryKey of the record being transferred.

 For example, consider dragging "employees" to "teams", where "teams" has a field
 "teams.employeeId" which is a foreignKey pointing to "employees.id", and the target
 grid has search criteria causing it to show all the members of one team. A duplicate -
 adding an employee to the same team twice - is when the target grid's dataset contains an
 record with "employeeId" matching the "id" field of the dropped employee.
- Returns:
- Boolean
-
setDuplicateDragMessage
DataBoundComponent setDuplicateDragMessage(String duplicateDragMessage) throws IllegalStateException Message to show when a user attempts to transfer duplicate records into this component, and
preventDuplicatesis enabled. If set to null, duplicates will not be reported and the dragged duplicates will not be saved.- Parameters:
duplicateDragMessage- duplicateDragMessage Default value is "Duplicates not allowed"- Returns:
DataBoundComponentinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the component has been created
-
getDuplicateDragMessage
String getDuplicateDragMessage()Message to show when a user attempts to transfer duplicate records into this component, and
preventDuplicatesis enabled. If set to null, duplicates will not be reported and the dragged duplicates will not be saved.- Returns:
- String
-
setAddDropValues
Indicates whether to add "drop values" to items dropped on this component, if both the source and target widgets are databound, either to the same DataSource or to different DataSources that are related via a foreign key. "Drop values" are properties of the dropped item that you wish to change (and persist) as a result of the item being dropped on this grid.If this value is true and this component is databound,
getDropValues()will be called for every databound item dropped on this grid, and an update performed on the item- Parameters:
addDropValues- addDropValues Default value is true- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getAddDropValues
Boolean getAddDropValues()Indicates whether to add "drop values" to items dropped on this component, if both the source and target widgets are databound, either to the same DataSource or to different DataSources that are related via a foreign key. "Drop values" are properties of the dropped item that you wish to change (and persist) as a result of the item being dropped on this grid.If this value is true and this component is databound,
getDropValues()will be called for every databound item dropped on this grid, and an update performed on the item- Returns:
- Boolean
-
setDropValues
When an item is dropped on this component, andaddDropValuesis true and both the source and target widgets are databound, either to the same DataSource or to different DataSources that are related via a foreign key, this object provides the "drop values" that Smart GWT will apply to the dropped object before updating it.If this property is not defined, Smart GWT defaults to returning the selection criteria currently in place for this component. Thus, any databound items (for example, rows from other grids bound to the same DataSource) dropped on the grid will, by default, be subjected to an update that makes them conform to the grid's current filter criteria.
Note : This is an advanced setting
- Parameters:
dropValues- dropValues Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getDropValues
Map getDropValues()When an item is dropped on this component, andaddDropValuesis true and both the source and target widgets are databound, either to the same DataSource or to different DataSources that are related via a foreign key, this object provides the "drop values" that Smart GWT will apply to the dropped object before updating it.If this property is not defined, Smart GWT defaults to returning the selection criteria currently in place for this component. Thus, any databound items (for example, rows from other grids bound to the same DataSource) dropped on the grid will, by default, be subjected to an update that makes them conform to the grid's current filter criteria.
Note : This is an advanced setting
- Returns:
- Returns the "drop values" to apply to a record dropped on this component prior to update. Only
 applicable to databound components - see
dropValuesfor more details. If multiple records 
 are being dropped, this method is called for each of them in turn.

 This method returns the following:

- 

- Nothing, if
addDropValuesis false 
 - dropValues, if that property is set. If the component's criteria object is applicable (as explained
 in the next item), it is merged into dropValues, with properties in dropValues taking precedence. 

- The component's criteria object, if the most recent textMatchStyle for the component was "exact" 
 and it is simple criteria (ie, not an AdvancedCriteria object) 

- Otherwise nothing 


 You can override this method if you need more complex setting of drop values than can be 
 provided by simply supplying a dropValues object.
 

- Nothing, if
-
setUseFlatFields
TheuseFlatFieldsflag causes all simple type fields anywhere in a nested
 set of DataSources to be exposed as a flat list for form binding. 


useFlatFieldsis typically used with imported metadata, such as 
XMLTools.loadXMLSchema(java.lang.String, com.smartgwt.client.data.XSDLoadCallback)from a 
XMLTools.loadWSDL(java.lang.String, com.smartgwt.client.data.WSDLLoadCallback), as a means of eliminating levels of XML
 nesting that aren't meaningful in a user interface, without the cumbersome and fragile
 process of mapping form fields to XML structures.

 For example, having called
WebService.getInputDS(java.lang.String)to retrieve the input message
 schema for a web service operation whose input message looks like this:

 <FindServices>
 <searchFor>search text</searchFor>
 <Options>
 <caseSensitive>false</caseSensitive>
 </Options>
 <IncludeInSearch>
 <serviceName>true</serviceName>
 <documentation>true</documentation>
 <keywords>true</keywords>
 </IncludeInSearch>
 </FindServices>


 SettinguseFlatFieldson aDynamicFormthat is bound to this input
 message schema would result in 5FormItemreflecting the 5 simple type
 fields in the message.

 For this form, the result of
DynamicForm.getValues()might look
 like:


{
 searchFor: "search text",
 caseSensitive: false,
 serviceName: true,
 documentation : true,
 keywords : true
 }
 When contacting aWebService, these values can be automatically
 mapped to the structure of the input message for a web service operation by setting
 {@link com.smartgwt.client..WSRequest#getUseFlatFields useFlatFields} (for use withWebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)) or by setting
useFlatFields(for use with aDataSourcethat is
'bound to a WSDL web service'via
wsOperation). 

 Using these two facilities in conjunction (component.useFlatFields and
 request.useFlatFields) allows gratuitous nesting to be consistently bypassed in both the user
 presentation and when providing the data for XML messages.


 You can also set
useFlatFieldsto automatically enable 
 "flattened" XML serialization (request.useFlatFields) for all DataSource requests of a
 particular operationType.

 Note that
useFlatFieldsis not generally recommended for use with structures
 where multiple simple type fields exist with the same name, however if used with such a
 structure, the first field to use a given name wins. "first" means the first field
 encountered in a depth first search. "wins" means only the first field will be present as a
 field when data binding.- Parameters:
useFlatFields- useFlatFields Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the component has been created
-
getUseFlatFields
Boolean getUseFlatFields()TheuseFlatFieldsflag causes all simple type fields anywhere in a nested
 set of DataSources to be exposed as a flat list for form binding. 


useFlatFieldsis typically used with imported metadata, such as 
XMLTools.loadXMLSchema(java.lang.String, com.smartgwt.client.data.XSDLoadCallback)from a 
XMLTools.loadWSDL(java.lang.String, com.smartgwt.client.data.WSDLLoadCallback), as a means of eliminating levels of XML
 nesting that aren't meaningful in a user interface, without the cumbersome and fragile
 process of mapping form fields to XML structures.

 For example, having called
WebService.getInputDS(java.lang.String)to retrieve the input message
 schema for a web service operation whose input message looks like this:

 <FindServices>
 <searchFor>search text</searchFor>
 <Options>
 <caseSensitive>false</caseSensitive>
 </Options>
 <IncludeInSearch>
 <serviceName>true</serviceName>
 <documentation>true</documentation>
 <keywords>true</keywords>
 </IncludeInSearch>
 </FindServices>


 SettinguseFlatFieldson aDynamicFormthat is bound to this input
 message schema would result in 5FormItemreflecting the 5 simple type
 fields in the message.

 For this form, the result of
DynamicForm.getValues()might look
 like:


{
 searchFor: "search text",
 caseSensitive: false,
 serviceName: true,
 documentation : true,
 keywords : true
 }
 When contacting aWebService, these values can be automatically
 mapped to the structure of the input message for a web service operation by setting
 {@link com.smartgwt.client..WSRequest#getUseFlatFields useFlatFields} (for use withWebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)) or by setting
useFlatFields(for use with aDataSourcethat is
'bound to a WSDL web service'via
wsOperation). 

 Using these two facilities in conjunction (component.useFlatFields and
 request.useFlatFields) allows gratuitous nesting to be consistently bypassed in both the user
 presentation and when providing the data for XML messages.


 You can also set
useFlatFieldsto automatically enable 
 "flattened" XML serialization (request.useFlatFields) for all DataSource requests of a
 particular operationType.

 Note that
useFlatFieldsis not generally recommended for use with structures
 where multiple simple type fields exist with the same name, however if used with such a
 structure, the first field to use a given name wins. "first" means the first field
 encountered in a depth first search. "wins" means only the first field will be present as a
 field when data binding.- Returns:
- Boolean
-
setHiliteProperty
Marker that can be set on a record to flag that record as hilited. Should be set to a value
 that matches {@link com.smartgwt.client..Hilite#getId id} for a hilite defined on this component.- Parameters:
hiliteProperty- hiliteProperty Default value is "_hilite"- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getHiliteProperty
String getHiliteProperty()Marker that can be set on a record to flag that record as hilited. Should be set to a value
 that matches {@link com.smartgwt.client..Hilite#getId id} for a hilite defined on this component.- Returns:
- String
-
setDragDataAction
Indicates what to do with data dragged into another DataBoundComponent. See
 DragDataAction type for details.- Parameters:
dragDataAction- dragDataAction Default value is Canvas.MOVE- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getDragDataAction
DragDataAction getDragDataAction()Indicates what to do with data dragged into another DataBoundComponent. See
 DragDataAction type for details.- Returns:
- DragDataAction
-
setDragTrackerStyle
CSS Style to apply to the drag tracker when dragging occurs on this component.- Parameters:
dragTrackerStyle- dragTrackerStyle Default value is "gridDragTracker"- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getDragTrackerStyle
String getDragTrackerStyle()CSS Style to apply to the drag tracker when dragging occurs on this component.- Returns:
- String
-
setCanAddFormulaFields
Adds an item to the header context menu allowing users to launch a dialog to define a new
 field based on values present in other fields, using the {@link com.smartgwt.client..FormulaBuilder}.

 User-added formula fields can be persisted via
ListGrid.getFieldState()and 
ListGrid.setFieldState(java.lang.String).- Parameters:
canAddFormulaFields- canAddFormulaFields Default value is false- Returns:
DataBoundComponentinstance, for chaining setter calls
-
addSummaryField
void addSummaryField()Convenience method to display a {@link com.smartgwt.client..SummaryBuilder} to create a new Summary Field. This 
 is equivalent to callingDataBoundComponentGen#editSummaryFieldwith 
 no parameter.

 -
addFormulaField
void addFormulaField()Convenience method to display a {@link com.smartgwt.client..FormulaBuilder} to create a new Formula Field. This 
 is equivalent to callingDataBoundComponentGen#editFormulaFieldwith 
 no parameter.

 -
getCanAddFormulaFields
Boolean getCanAddFormulaFields()Adds an item to the header context menu allowing users to launch a dialog to define a new
 field based on values present in other fields, using the {@link com.smartgwt.client..FormulaBuilder}.

 User-added formula fields can be persisted via
ListGrid.getFieldState()and 
ListGrid.setFieldState(java.lang.String).- Returns:
- Boolean
-
setAddFormulaFieldText
Text for a menu item allowing users to add a formula field- Parameters:
addFormulaFieldText- addFormulaFieldText Default value is "Add formula column..."- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getAddFormulaFieldText
String getAddFormulaFieldText()Text for a menu item allowing users to add a formula field- Returns:
- String
-
setEditFormulaFieldText
Text for a menu item allowing users to edit a formula field- Parameters:
editFormulaFieldText- editFormulaFieldText Default value is "Edit formula..."- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getEditFormulaFieldText
String getEditFormulaFieldText()Text for a menu item allowing users to edit a formula field- Returns:
- String
-
setCanAddSummaryFields
Adds an item to the header context menu allowing users to launch a dialog to define a new
 text field that can contain both user-defined text and the formatted values present in other 
 fields, using the {@link com.smartgwt.client..SummaryBuilder}.

 User-added summary fields can be persisted via
ListGrid.getFieldState()and 
ListGrid.setFieldState(java.lang.String).- Parameters:
canAddSummaryFields- canAddSummaryFields Default value is false- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getCanAddSummaryFields
Boolean getCanAddSummaryFields()Adds an item to the header context menu allowing users to launch a dialog to define a new
 text field that can contain both user-defined text and the formatted values present in other 
 fields, using the {@link com.smartgwt.client..SummaryBuilder}.

 User-added summary fields can be persisted via
ListGrid.getFieldState()and 
ListGrid.setFieldState(java.lang.String).- Returns:
- Boolean
-
setAddSummaryFieldText
Text for a menu item allowing users to add a formula field- Parameters:
addSummaryFieldText- addSummaryFieldText Default value is "Add summary column..."- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getAddSummaryFieldText
String getAddSummaryFieldText()Text for a menu item allowing users to add a formula field- Returns:
- String
-
setEditSummaryFieldText
Text for a menu item allowing users to edit the formatter for a field- Parameters:
editSummaryFieldText- editSummaryFieldText Default value is "Edit summary format..."- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getEditSummaryFieldText
String getEditSummaryFieldText()Text for a menu item allowing users to edit the formatter for a field- Returns:
- String
-
selectRecord
Select/deselect aRecordpassed in explicitly, or by index.- Parameters:
record- record (or row number) to select
-
selectRecord
void selectRecord(int record) Select/deselect aRecordpassed in explicitly, or by index.- Parameters:
record- record (or row number) to select
-
selectRecord
void selectRecord(int record, boolean newState) Select/deselect aRecordpassed in explicitly, or by index.- Parameters:
record- record (or row number) to selectnewState- new selection state (if null, defaults to true)
-
selectRecord
Select/deselect aRecordpassed in explicitly, or by index.- Parameters:
record- record (or row number) to selectnewState- new selection state (if null, defaults to true)
-
selectRecords
void selectRecords(int[] records) Select/deselect a list ofRecords passed in explicitly, or by index.- Parameters:
records- records (or row numbers) to select
-
selectRecords
void selectRecords(int[] records, boolean newState) Select/deselect a list ofRecords passed in explicitly, or by index.- Parameters:
records- records (or row numbers) to selectnewState- new selection state
-
selectRecords
Select/deselect a list ofRecords passed in explicitly, or by index.- Parameters:
records- records (or row numbers) to select
-
selectRecords
Select/deselect a list ofRecords passed in explicitly, or by index.- Parameters:
records- records (or row numbers) to selectnewState- new selection state (if null, defaults to true)
-
deselectRecord
Deselect aRecordpassed in explicitly, or by index.Synonym for
selectRecord(record, false)- Parameters:
record- record (or row number) to deselect
-
deselectRecord
void deselectRecord(int record) Deselect aRecordpassed in explicitly, or by index.Synonym for
selectRecord(record, false)- Parameters:
record- record (or row number) to deselect
-
deselectRecords
void deselectRecords(int[] records) Deselect a list ofRecords passed in explicitly, or by index.Synonym for
selectRecords(records, false)- Parameters:
records- records (or row numbers) to deselect
-
deselectRecords
Deselect a list ofRecords passed in explicitly, or by index.Synonym for
selectRecords(records, false)- Parameters:
records- records (or row numbers) to deselect
-
selectAllRecords
void selectAllRecords()Select all records

 -
deselectAllRecords
void deselectAllRecords()
 Deselect all records

 -
anySelected
Boolean anySelected()Whether at least one item is selected
- Returns:
- true == at least one item is selected false == nothing at all is selected
-
enableHilite
Enable / disable ahilites

- Parameters:
hiliteID- ID of hilite to enable
-
enableHilite
Enable / disable ahilites

- Parameters:
hiliteID- ID of hilite to enableenable- new enabled state to apply - if null, defaults to true
-
disableHilite
Disable a hilite

- Parameters:
hiliteID- ID of hilite to disable
-
enableHiliting
void enableHiliting()Enable all hilites.

 -
enableHiliting
void enableHiliting(boolean enable) Enable all hilites.

- Parameters:
enable- new enabled state to apply - if null, defaults to true
-
disableHiliting
void disableHiliting()Disable all hilites.

 -
getDragData
Record[] getDragData()During a drag-and-drop interaction, this method returns the set of records being dragged out of the component. In the default implementation, this is the list of currently selected records.This method is consulted by

ListGrid.willAcceptDrop().- Returns:
- Array of
Records that are currently selected.
-
transferSelectedData
Simulates a drag / drop type transfer of the selected records in some other component to this component, without requiring any user interaction. This method acts on the dropped records exactly as if they had been dropped in an actual drag / drop interaction, including any special databound behavior invoked by callinggetDropValues()for each dropped record.To transfer all data in, for example, a
ListGrid, call grid.selection.selectAll() first.Note that drag/drop type transfers of records between components are asynchronous operations: Smart GWT may need to perform server turnarounds to establish whether dropped records already exist in the target component. Therefore, it is possible to issue a call to
transferSelectedData()and/or thedrop()method of a databound component whilst a transfer is still active. When this happens, Smart GWT adds the second and subsequent transfer requests to a queue and runs them one after the other. If you want to be notified when a transfer process has actually completed, useHasDropCompleteHandlers.addDropCompleteHandler(com.smartgwt.client.widgets.events.DropCompleteHandler). See theDraggingdocumentation for an overview of list grid drag/drop data transfer.- Parameters:
source- source component from which the records will be tranferred
-
transferSelectedData
Simulates a drag / drop type transfer of the selected records in some other component to this component, without requiring any user interaction. This method acts on the dropped records exactly as if they had been dropped in an actual drag / drop interaction, including any special databound behavior invoked by callinggetDropValues()for each dropped record.To transfer all data in, for example, a
ListGrid, call grid.selection.selectAll() first.Note that drag/drop type transfers of records between components are asynchronous operations: Smart GWT may need to perform server turnarounds to establish whether dropped records already exist in the target component. Therefore, it is possible to issue a call to
transferSelectedData()and/or thedrop()method of a databound component whilst a transfer is still active. When this happens, Smart GWT adds the second and subsequent transfer requests to a queue and runs them one after the other. If you want to be notified when a transfer process has actually completed, useHasDropCompleteHandlers.addDropCompleteHandler(com.smartgwt.client.widgets.events.DropCompleteHandler). See theDraggingdocumentation for an overview of list grid drag/drop data transfer.- Parameters:
source- source component from which the records will be transferredindex- target index (drop position) of the rows within this grid.
-
getRecordIndex
Get the index of the provided record.

 Override in subclasses to provide more specific behaviour, for instance, when data holds a
 large number of records


- Parameters:
record- the record whose index is to be retrieved- Returns:
- indexindex of the record, or -1 if not found
-
getTitleFieldValue
Get the value of the titleField for the passed record

 Override in subclasses 


- Parameters:
record- the record whose index is to be retrieved- Returns:
- valuethe value of the titleField for the passed record
-
getTitleField
String getTitleField()Method to return the fieldName which represents the "title" for records in this
 Component.

 If this.titleField is explicitly specified it will always be used.
 Otherwise, default implementation will checktitleFieldfor databound
 components.

 For non databound components returns the first defined field name of"title", 
"name", or"id". If we dont find any field-names that match these
 titles, the first field in the component will be used instead.
- Returns:
- fieldName the title field for this component.
-
setTitleField
Sets the best field to use for a user-visible title for an individual record from this component.- Parameters:
fieldName- the title field for this component.- Returns:
DataBoundComponentinstance, for chaining setter calls
-
setDataSource
Bind to a DataSource. Binding to a DataSource means that the component will use the DataSource to provide default data for its fields.When binding a previously-bound component to a new DataSource, if the component has any existing "fields" or has a dataset, these will be discarded by default, since it is assumed the new DataSource may represent a completely unrelated set of objects. If the old "fields" are still relevant, you may be able to refer to setDataSource(dataSource, fields) as an alternative method if the widget has an implementation of it.
- Parameters:
dataSource- DataSource to bind to. Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls
-
setDataSource
Bind to a DataSource. Binding to a DataSource means that the component will use the DataSource to provide default data for its fields.When binding a previously-bound component to a new DataSource, if the component has any existing "fields" or has a dataset, these will be discarded by default, since it is assumed the new DataSource may represent a completely unrelated set of objects. If the old "fields" are still relevant, you may be able to refer to setDataSource(dataSource, fields) as an alternative method if the widget has an implementation of it.
- Parameters:
dataSource- name of DataSource to bind to- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getDataSource
DataSource getDataSource()The DataSource that this component should bind to for default fields and for performingDataSource requests.- Returns:
- DataSource
-
fetchData
void fetchData()Retrieves data from the DataSource that matches the specified criteria.When
fetchData()is first called, if data has not already been provided viasetData(), this method will create aResultSet, which will be configured based on component settings such asfetchOperationanddataPageSize, as well as the general purposedataProperties. The created ResultSet will automatically send a DSRequest to retrieve data from the dataSource, and from then on will automatically manage paging through large datasets, as well as performing filtering and sorting operations inside the browser when possible - see the ResultSet docs for details.NOTE: do not use both
autoFetchDataand a call tofetchData()- this may result in two DSRequests to fetch data. Use eitherautoFetchDataandsetAutoFetchCriteria()or a manual call to fetchData() passing criteria.Whether a ResultSet was automatically created or provided via
setData(), subsequent calls to fetchData() will simply callresultSet.setCriteria().Changes to criteria may or may not result in a DSRequest to the server due to client-side filtering. You can call
willFetchData(criteria)to determine if new criteria will result in a server fetch.If you need to force data to be re-fetched, you can call
invalidateCache()and new data will automatically be fetched from the server using the current criteria and sort direction. NOTE: when usinginvalidateCache()there is no need to also callfetchData()and in fact this could produce unexpected results.This method takes an optional callback parameter (set to a
DSCallback) to fire when the fetch completes. Note that this callback will not fire if no server fetch is performed. In this case the data is updated synchronously, so as soon as this method completes you can interact with the new data. If necessary, you can useresultSet.willFetchData()to determine whether or not a server fetch will occur whenfetchData()is called with new criteria.In addition to the callback parameter for this method, developers can use
resultSet.addDataArrivedHandlerto be notified every time data is loaded. -
fetchData
Retrieves data from the DataSource that matches the specified criteria.When
fetchData()is first called, if data has not already been provided viasetData(), this method will create aResultSet, which will be configured based on component settings such asfetchOperationanddataPageSize, as well as the general purposedataProperties. The created ResultSet will automatically send a DSRequest to retrieve data from the dataSource, and from then on will automatically manage paging through large datasets, as well as performing filtering and sorting operations inside the browser when possible - see the ResultSet docs for details.NOTE: do not use both
autoFetchDataand a call tofetchData()- this may result in two DSRequests to fetch data. Use eitherautoFetchDataandsetAutoFetchCriteria()or a manual call to fetchData() passing criteria.Whether a ResultSet was automatically created or provided via
setData(), subsequent calls to fetchData() will simply callresultSet.setCriteria().Changes to criteria may or may not result in a DSRequest to the server due to client-side filtering. You can call
willFetchData(criteria)to determine if new criteria will result in a server fetch.If you need to force data to be re-fetched, you can call
invalidateCache()and new data will automatically be fetched from the server using the current criteria and sort direction. NOTE: when usinginvalidateCache()there is no need to also callfetchData()and in fact this could produce unexpected results.This method takes an optional callback parameter (set to a
DSCallback) to fire when the fetch completes. Note that this callback will not fire if no server fetch is performed. In this case the data is updated synchronously, so as soon as this method completes you can interact with the new data. If necessary, you can useresultSet.willFetchData()to determine whether or not a server fetch will occur whenfetchData()is called with new criteria.In addition to the callback parameter for this method, developers can use
resultSet.addDataArrivedHandlerto be notified every time data is loaded.- Parameters:
criteria- Search criteria. If aDynamicFormis passed in as this argument instead of a raw criteria object, will be derived by callingDynamicForm.getValuesAsCriteria()
-
fetchData
Retrieves data from the DataSource that matches the specified criteria.When
fetchData()is first called, if data has not already been provided viasetData(), this method will create aResultSet, which will be configured based on component settings such asfetchOperationanddataPageSize, as well as the general purposedataProperties. The created ResultSet will automatically send a DSRequest to retrieve data from the dataSource, and from then on will automatically manage paging through large datasets, as well as performing filtering and sorting operations inside the browser when possible - see the ResultSet docs for details.NOTE: do not use both
autoFetchDataand a call tofetchData()- this may result in two DSRequests to fetch data. Use eitherautoFetchDataandsetAutoFetchCriteria()or a manual call to fetchData() passing criteria.Whether a ResultSet was automatically created or provided via
setData(), subsequent calls to fetchData() will simply callresultSet.setCriteria().Changes to criteria may or may not result in a DSRequest to the server due to client-side filtering. You can call
willFetchData(criteria)to determine if new criteria will result in a server fetch.If you need to force data to be re-fetched, you can call
invalidateCache()and new data will automatically be fetched from the server using the current criteria and sort direction. NOTE: when usinginvalidateCache()there is no need to also callfetchData()and in fact this could produce unexpected results.This method takes an optional callback parameter (set to a
DSCallback) to fire when the fetch completes. Note that this callback will not fire if no server fetch is performed. In this case the data is updated synchronously, so as soon as this method completes you can interact with the new data. If necessary, you can useresultSet.willFetchData()to determine whether or not a server fetch will occur whenfetchData()is called with new criteria.In addition to the callback parameter for this method, developers can use
resultSet.addDataArrivedHandlerto be notified every time data is loaded.- Parameters:
criteria- Search criteria. If aDynamicFormis passed in as this argument instead of a raw criteria object, will be derived by callingDynamicForm.getValuesAsCriteria()callback- callback to invoke when a fetch is complete. Fires only if server contact was required
-
fetchData
Retrieves data from the DataSource that matches the specified criteria.When
fetchData()is first called, if data has not already been provided viasetData(), this method will create aResultSet, which will be configured based on component settings such asfetchOperationanddataPageSize, as well as the general purposedataProperties. The created ResultSet will automatically send a DSRequest to retrieve data from the dataSource, and from then on will automatically manage paging through large datasets, as well as performing filtering and sorting operations inside the browser when possible - see the ResultSet docs for details.NOTE: do not use both
autoFetchDataand a call tofetchData()- this may result in two DSRequests to fetch data. Use eitherautoFetchDataandsetAutoFetchCriteria()or a manual call to fetchData() passing criteria.Whether a ResultSet was automatically created or provided via
setData(), subsequent calls to fetchData() will simply callresultSet.setCriteria().Changes to criteria may or may not result in a DSRequest to the server due to client-side filtering. You can call
willFetchData(criteria)to determine if new criteria will result in a server fetch.If you need to force data to be re-fetched, you can call
invalidateCache()and new data will automatically be fetched from the server using the current criteria and sort direction. NOTE: when usinginvalidateCache()there is no need to also callfetchData()and in fact this could produce unexpected results.This method takes an optional callback parameter (set to a
DSCallback) to fire when the fetch completes. Note that this callback will not fire if no server fetch is performed. In this case the data is updated synchronously, so as soon as this method completes you can interact with the new data. If necessary, you can useresultSet.willFetchData()to determine whether or not a server fetch will occur whenfetchData()is called with new criteria.In addition to the callback parameter for this method, developers can use
resultSet.addDataArrivedHandlerto be notified every time data is loaded.- Parameters:
criteria- Search criteria. If aDynamicFormis passed in as this argument instead of a raw criteria object, will be derived by callingDynamicForm.getValuesAsCriteria()callback- callback to invoke when a fetch is complete. Fires only if server contact was requiredrequestProperties- additional properties to set on the DSRequest that will be issued
-
filterData
void filterData()Retrieves data that matches the provided criteria and displays the matching data in this component.This method behaves exactly like
ListGrid.fetchData()except thattextMatchStyleis automatically set to "substring" so that String-valued fields are matched by case-insensitive substring comparison.- Parameters:
criteria- Search criteria. If aDynamicFormis passed in as this argument instead of a raw criteria object, will be derived by callingDynamicForm.getValuesAsCriteria()
-
filterData
Retrieves data that matches the provided criteria and displays the matching data in this component.This method behaves exactly like
ListGrid.fetchData()except thattextMatchStyleis automatically set to "substring" so that String-valued fields are matched by case-insensitive substring comparison.- Parameters:
criteria- Search criteria. If aDynamicFormis passed in as this argument instead of a raw criteria object, will be derived by callingDynamicForm.getValuesAsCriteria()callback- callback to invoke when a fetch is complete. Fires only if server contact was required; seefetchData()for details
-
filterData
Retrieves data that matches the provided criteria and displays the matching data in this component.This method behaves exactly like
ListGrid.fetchData()except thattextMatchStyleis automatically set to "substring" so that String-valued fields are matched by case-insensitive substring comparison.- Parameters:
criteria- Search criteria. If aDynamicFormis passed in as this argument instead of a raw criteria object, will be derived by callingDynamicForm.getValuesAsCriteria()callback- callback to invoke when a fetch is complete. Fires only if server contact was required; seefetchData()for details
-
filterData
Retrieves data that matches the provided criteria and displays the matching data in this component.This method behaves exactly like
ListGrid.fetchData()except thattextMatchStyleis automatically set to "substring" so that String-valued fields are matched by case-insensitive substring comparison.- Parameters:
criteria- Search criteria. If aDynamicFormis passed in as this argument instead of a raw criteria object, will be derived by callingDynamicForm.getValuesAsCriteria()callback- callback to invoke when a fetch is complete. Fires only if server contact was required; seefetchData()for detailsrequestProperties- for databound components only - optional additional properties to set on the DSRequest that will be issued
-
setAutoFetchData
If true, when this component is first drawn, automatically callfetchData()orfilterData()depending ongetAutoFetchAsFilter(). Criteria for this fetch may be picked up frominitialCriteriaand textMatchStyle may be specified viagetAutoFetchTextMatchStyle().NOTE: If autoFetchData is set, calling ListGrid.fetchData() before draw will cause two requests to be issued, one from the manual call to fetchData() and one from the autoFetchData setting. The second request will use only
initialCriteriaand not any other criteria or settings from the first request. Generally, turn off autoFetchData if you are going to manually call fetchData() at any time.- Parameters:
autoFetchData- autoFetchData- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getAutoFetchData
Boolean getAutoFetchData()If true, when this component is first drawn, automatically callfetchData()orfilterData()depending ongetAutoFetchAsFilter(). Criteria for this fetch may be picked up frominitialCriteriaand textMatchStyle may be specified viagetAutoFetchTextMatchStyle().NOTE: If autoFetchData is set, calling ListGrid.fetchData() before draw will cause two requests to be issued, one from the manual call to fetchData() and one from the autoFetchData setting. The second request will use only
initialCriteriaand not any other criteria or settings from the first request. Generally, turn off autoFetchData if you are going to manually call fetchData() at any time.- Returns:
- autoFetchData autoFetchData
-
setAutoFetchAsFilter
IfsetAutoFetchData(Boolean)is true, this attribute determines whether the initial fetch operation should be performed viafetchData()orfilterData()- Parameters:
autoFetchAsFilter- autoFetchAsFilter- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getAutoFetchAsFilter
Boolean getAutoFetchAsFilter()IfsetAutoFetchData(Boolean)is true, this attribute determines whether the initial fetch operation should be performed viafetchData()orfilterData()- Returns:
- auto fetch as filter
-
setAutoFetchTextMatchStyle
IfautoFetchDataistrue, this attribute allows the developer to specify a textMatchStyle for the initialfetchData()call.- Parameters:
autoFetchTextMatchStyle- autoFetchTextMatchStyle- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getAutoFetchTextMatchStyle
TextMatchStyle getAutoFetchTextMatchStyle()IfautoFetchDataistrue, this attribute allows the developer to specify a textMatchStyle for the initialfetchData()call.- Returns:
- autoFetchTextMatchStyle autoFetchTextMatchStyle
-
setInitialCriteria
Criteria to use whensetAutoFetchData(Boolean)is used.- Parameters:
initialCriteria- the initial criteria- Returns:
DataBoundComponentinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the component has been created
-
getInitialCriteria
Criteria getInitialCriteria()Criteria to use whensetAutoFetchData(Boolean)is used.- Returns:
- the criteria
-
setImplicitCriteria
Criteria that are never shown to or edited by the user and are cumulative with any criteria provided viaDataBoundComponent.initialCriteria,DataBoundComponent.setCriteria()etc.- Parameters:
implicitCriteria- New implicitCriteria value. Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getImplicitCriteria
Criteria getImplicitCriteria()Criteria that are never shown to or edited by the user and are cumulative with any criteria provided viaDataBoundComponent.initialCriteria,DataBoundComponent.setCriteria()etc.- Returns:
- Current implicitCriteria value. Default value is null
-
invalidateCache
void invalidateCache()Invalidate the current data cache for this databound component via a call to the dataset'sinvalidateCache()method, for example,ResultSet.invalidateCache().NOTE: there is no need to call
invalidateCache()when a save operation is performed on a DataSource. Automatic cache synchronization features will automatically update caches - seeResultSetfor details. If automatic cache synchronization isn't working, troubleshoot the problem using the steps suggested in the FAQ rather than just calling invalidateCache(). CallinginvalidateCache()unnecessarily causes extra server load and added code complexity.Calling
invalidateCache()will automatically cause a new fetch to be performed with the current set of criteria if data had been previously fetched and the component is currently drawn with data visible - there is no need to manually call fetchData() after invalidateCache() and this could result in duplicate fetches.While data is being re-loaded after a call to
invalidateCache(), the widget is in a state similar to initial data load - it doesn't know the total length of the dataset and any APIs that act on records or row indices will necessarily fail and should not be called. To detect that the widget is in this state, callResultSet.lengthIsKnown().invalidateCache()only has an effect if this component's dataset is a data manager class that manages a cache (eg ResultSet or ResultTree). If data was provided as a simple Array or List, invalidateCache() does nothing. -
getResultSet
ResultSet getResultSet()Return the underlying data of this DataBoundComponent as aResultSet.Note that this method should only be called after initial data has been fetched by this DataBoundComponent.
- Returns:
- ResultSet, or null if the underlying data is not a ResultSet
- See Also:
-
getRecordList
RecordList getRecordList()Return the underlying data of this DataBoundComponent as aRecordList.Depending on the component configuration, the actual JavaScript instance of the returned RecordList may be one of several types:
- If the component is not bound to a
DataSource, the instance is generally an Array ofRecord. - If the component is bound to a DataSource, the instance is a
ResultSet. - If the component is a grouped ListGrid, the instance is a
Tree. To access the ungrouped record list regardless of grouping status, useisGrouped() ? getOriginalRecordList() : getRecordList()
- If the component is a
TreeGrid, the instance is a ResultTree.
- Returns:
- the RecordList
- If the component is not bound to a
-
getDataAsJSList
JavaScriptObject getDataAsJSList() -
exportData
void exportData() -
exportData
-
exportData
Uses a "fetch" operation on the currentDataSourceto retrieve data that matches the current filter and sort criteria for this component, then exports the resulting data to a file or window in the requested format.A variety of DSRequest settings, such as
exportAsandexportFilename, affect the exporting process: seeexportResultsfor further detail.Note that data exported via this method does not include any client-side formatting and relies on both the Smart GWT server and server-side DataSources. To export client-data with formatters applied, see
exportClientData, which still requires the Smart GWT server but does not rely on server-side DataSources.For more information on exporting data, see
DataSource.exportData.- Parameters:
requestProperties- additional properties to set on DSRequest that will be issuedcallback- Optional callback. Note that this parameter only applies if you specifyexportToClient: false in the request properties, because file downloads don't provide ordinary framework callbacks- See Also:
-
editHilites
void editHilites()Shows a HiliteEditor interface allowing end-users to edit the data-hilites currently in use by this DataBoundComponent. -
getHiliteState
String getHiliteState()Get the current hilites encoded as a String, for saving.- Returns:
- the hilite state
-
setHiliteState
Set the current hilites based on a hiliteState String previously returned from getHilitesState.- Parameters:
hiliteState- hilites state encoded as a String- Returns:
DataBoundComponentinstance, for chaining setter calls
-
setHilites
Accepts an array of hilite objects and applies them to this DataBoundComponent. See alsogetHilitesfor a method of retrieving the hilite array for storage, including hilites manually added by the user.NOTE: This is only supported on
ListGridfor now.- Parameters:
hilites- array of hilite objects- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getHilites
Hilite[] getHilites()Return the set of hilite-objects currently applied to this DataBoundComponent. These can be saved for storage and then restored to a component later via setHilites().- Returns:
- array of hilite objects
-
getFieldAlignments
Alignment[] getFieldAlignments()Returna an array of field alignments for this grid- Returns:
- array of Alignments
-
getDeepCloneOnEdit
Boolean getDeepCloneOnEdit()Before we start editing values in this DataBoundComponent, should we perform a deep clone of the underlying values. SeeDataSource.getDeepCloneOnEdit()for details of what this means.If this value is not explicitly set, it defaults to the DataSource
deepCloneOnEditvalue. This value can also be overridden per-field withDataSourceField.setDeepCloneOnEdit(java.lang.Boolean).Like the other
deepCloneOnEditsettings, this flag only has an effect if you are editing a values object that contains nested objects or arrays, usingCanvas.setDataPath(java.lang.String) -
setDeepCloneOnEdit
Before we start editing values in this DataBoundComponent, should we perform a deep clone of the underlying values. SeeDataSource.getDeepCloneOnEdit()for details of what this means.If this value is not explicitly set, it defaults to the DataSource
deepCloneOnEditvalue. This value can also be overridden per-field withDataSourceField.setDeepCloneOnEdit(java.lang.Boolean).Like the other
deepCloneOnEditsettings, this flag only has an effect if you are editing a values object that contains nested objects or arrays, usingCanvas.setDataPath(java.lang.String)- Returns:
DataBoundComponentinstance, for chaining setter calls
-
setFields
Field setter variant (alternative tosetFields(FormItem...),setFields(ListGridField...), etc.) that will accept an array of JavaScriptObject, rather than an array of SmartGWT Java wrappers of the field class type (e.g.FormItem,ListGridField, etc.) This is an advanced method and only for cases where you have the JavaScriptObject for each field but want to avoid having to create each associated SmartGWT Java wrapper.Note: use
toArray()to create a Java array of JavaScriptObject if you only have the array itself as a single JavaScriptObject.- Parameters:
fields- the component fields- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getFieldsAsJavaScriptObjects
JavaScriptObject[] getFieldsAsJavaScriptObjects()Return the fields as JavaScriptObjects rather than as SmartGWT Java wrappers of the field class type (e.g.FormItem,ListGridField, etc.) This avoids building the SmartGWT Java wrappers for the fields in situations where they aren't needed - and for FormItems in particular - where there may not be enough information to determine the correct subclass, such as before the SmartClient instance underlying theDynamicFormhas been created.- Returns:
- the component fields
-
getFieldCount
int getFieldCount()Return the number of fields.- Returns:
- the number of fields
-
transferRecords
void transferRecords(Record[] records, Record targetRecord, Integer index, Canvas sourceWidget, TransferRecordsCallback callback) Transfer a list ofRecords from another component (does not have to be a databound component) into this component. This method is only applicable to list-type components, such asListGridorcom.smartgwt.client.widgets.tile.TileGridTileGrid. Notably, it does not apply toTreeGrid; the equivalent for treeGrids istransferNodes.This method implements the automatic drag-copy and drag-move behaviors of components like
ListGrid, and calling it is equivalent to completing a drag and drop of thedropRecords(the default record drop behavior is simply to calltransferRecords(), passing in the dropped nodes)Note that this method is asynchronous - it may need to perform server turnarounds to prevent duplicates in the target component's data. If you wish to be notified when the transfer process has completed, you can either pass a non-null callback to this method or add a
DropCompleteHandlerto this component.See also
transferSelectedData()- Parameters:
records- Recordss to transfer to this componenttargetRecord- The target record (eg, of a drop interaction), for contextindex- Insert point relative to the target record for the transferred recordssourceWidget- The databound or non-databound component from which the records are to be transferred.callback- optional TransferRecordsCallback to be fired when the transfer process has completed (pass null if your code does not need to be called back). The callback will be passed the list of records actually transferred to this component
-
getSort
SortSpecifier[] getSort()Returns the currentSortSpecifiersfor this component. Will return null if this component has never been sorted, or the underlying SmartClient widget does not exist.- Returns:
- current sort specifiers for this component (null if unsorted or no SC widget)
-
setSort
Sort the component on one or more fields.Pass in an array of
SortSpecifiers to have the component's data sorted by the fields in eachspecifier.propertyand in the directions specified. The component can be sorted by any combination of fields, including fields specified in the fields array andunused fields from the underlying dataSource, if there is one.If setSort() is called on a component which doesn't yet have a SmartClient widget, the widget will be created. If
autoFetchDatais set and aDataSourcehas been set, this will result in data being fetched.- Parameters:
sortSpecifiers- Array ofSortSpecifierobjects
-
setSavedSearchId
Optional identifier for saved searches that should be applied to this component.By default
SavedSearchesare associated with a component via itslocal IDandDataSource ID. This property allows developers to override this behavior and explicitly associate a component with a set of saved searches. This can provide a couple of benefits:
Firstly this ensures that saved searches will be unambiguously associated with the particular component even if the page changes such that a stored minimal locator would no longer applied to the component, without requiring an explicitCanvas.ID.
Secondly this allows the same set of saved searches to be applied to more than one component on a page. This may be valueable for cases where the same information from the same dataSource is presented to users in multiple places.Note: This is an advanced setting.
- Parameters:
savedSearchId- New savedSearchId value. Default value is null- Returns:
DataBoundComponentinstance, for chaining setter calls
-
getSavedSearchId
String getSavedSearchId()Optional identifier for saved searches that should be applied to this component.By default
SavedSearchesare associated with a component via itslocal IDandDataSource ID. This property allows developers to override this behavior and explicitly associate a component with a set of saved searches. This can provide a couple of benefits:
Firstly this ensures that saved searches will be unambiguously associated with the particular component even if the page changes such that a stored minimal locator would no longer applied to the component, without requiring an explicitCanvas.ID.
Secondly this allows the same set of saved searches to be applied to more than one component on a page. This may be valueable for cases where the same information from the same dataSource is presented to users in multiple places.- Returns:
- Current savedSearchId value. Default value is null
-
setShowSavedSearchesByDS
Whether to associate saved searches by default with the currentDataSourceof a component when asavedSearchIdis not provided. If this property is true, then when the DataSource is changed, existing saved searches will disappear and only be available if the DataSource is set back to its original value.If this property is false, saved searches will persist across DataSource changes so that searches that aren't applicable to the current DataSource might still be shown.
Note: This is an advanced setting
- Parameters:
showSavedSearchesByDS- New showSavedSearchesByDS value. Default value is true- Returns:
DataBoundComponentinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the component has been created
-
getShowSavedSearchesByDS
boolean getShowSavedSearchesByDS()Whether to associate saved searches by default with the currentDataSourceof a component when asavedSearchIdis not provided. If this property is true, then when the DataSource is changed, existing saved searches will disappear and only be available if the DataSource is set back to its original value.If this property is false, saved searches will persist across DataSource changes so that searches that aren't applicable to the current DataSource might still be shown.
- Returns:
- Current showSavedSearchesByDS value. Default value is true
-