|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface DataBoundComponent
A DataBoundComponent is a widget that can configure itself for viewing or editing objects which share a certain schema by "binding" to the schema for that object (called a "DataSource").
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:DynamicForm
DetailViewer
ListGrid
TreeGrid
TileGrid
ColumnTree
com.smartgwt.client..CubeGrid
ValuesManager
ResultSet
com.smartgwt.client..ResultTree
Method Summary | |
---|---|
void |
addFormulaField()
Convenience method to display a com.smartgwt.client..FormulaBuilder to create a new Formula Field. |
void |
addSummaryField()
Convenience method to display a com.smartgwt.client..SummaryBuilder to create a new Summary Field. |
Boolean |
anySelected()
Whether at least one item is selected |
void |
deselectAllRecords()
Deselect all records |
void |
deselectRecord(int record)
Deselect a Record passed in explicitly, or by index. |
void |
deselectRecord(Record record)
Deselect a Record passed in explicitly, or by index. |
void |
deselectRecords(int[] records)
Deselect a list of Record s passed in explicitly, or by index. |
void |
deselectRecords(Record[] records)
Deselect a list of Record s passed in explicitly, or by index. |
void |
disableHilite(String hiliteID)
Disable a hilite |
void |
disableHiliting()
Disable all hilites. |
void |
enableHilite(String hiliteID)
Enable / disable a hilites
|
void |
enableHilite(String hiliteID,
boolean enable)
Enable / disable a hilites
|
void |
enableHiliting()
Enable all hilites. |
void |
enableHiliting(boolean enable)
Enable all hilites. |
void |
fetchData()
Uses a "fetch" operation on the current DataSource to retrieve data that matches
the provided criteria, and displays the matching data in this component. |
void |
fetchData(Criteria criteria)
Uses a "fetch" operation on the current DataSource to retrieve data that matches
the provided criteria, and displays the matching data in this component. |
void |
fetchData(Criteria criteria,
DSCallback callback)
Uses a "fetch" operation on the current DataSource to retrieve data that matches
the provided criteria, and displays the matching data in this component. |
void |
fetchData(Criteria criteria,
DSCallback callback,
DSRequest requestProperties)
Uses a "fetch" operation on the current DataSource to retrieve data that matches
the provided criteria, and displays the matching data in this component. |
void |
filterData()
Retrieves data that matches the provided criteria and displays the matching data in this component. |
void |
filterData(Criteria criteria)
Retrieves data that matches the provided criteria and displays the matching data in this component. |
void |
filterData(Criteria criteria,
DSCallback callback)
Retrieves data that matches the provided criteria and displays the matching data in this component. |
void |
filterData(Criteria criteria,
DSCallback callback,
DSRequest requestProperties)
Retrieves data that matches the provided criteria and displays the matching data in this component. |
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. |
String |
getAddFormulaFieldText()
Text for a menu item allowing users to add a formula field |
String |
getAddOperation()
Operation ID this component should use when performing add operations. |
String |
getAddSummaryFieldText()
Text for a menu item allowing users to add a formula field |
Boolean |
getAutoFetchAsFilter()
If setAutoFetchData(Boolean) is true, this attribute determines whether the initial fetch operation should be
performed via fetchData() or filterData() |
Boolean |
getAutoFetchData()
If true, when this component is first drawn, automatically call fetchData() or filterData() depending on
getAutoFetchAsFilter() . |
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 com.smartgwt.client..FormulaBuilder .
|
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 com.smartgwt.client..SummaryBuilder .
|
FetchMode |
getDataFetchMode()
How to fetch and manage records retrieve from the server. |
int |
getDataPageSize()
When using data paging, how many records to fetch at a time. |
DataSource |
getDataSource()
The DataSource that this component should bind to for default fields and for performing DSRequest .
|
Record[] |
getDragData()
During a drag-and-drop interaction, this method returns the set of records being dragged out of the component. |
DragDataAction |
getDragDataAction()
Indicates what to do with data dragged into another DataBoundComponent. |
String |
getDragTrackerStyle()
CSS Style to apply to the drag tracker when dragging occurs on this component. |
Map |
getDropValues()
When an item is dropped on this component, and addDropValues is 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 SmartGWT will apply to the dropped object
before updating it.
|
String |
getDuplicateDragMessage()
Message to show when a user attempts to transfer duplicate records into this component, and preventDuplicates is enabled. |
String |
getEditFormulaFieldText()
Text for a menu item allowing users to edit a formula field |
String |
getEditSummaryFieldText()
Text for a menu item allowing users to edit the formatter for a field |
Boolean |
getExportAll()
Setting exportAll to true prevents the component from passing it's list of fields to the export call. |
String[] |
getExportFields()
The list of field-names to export. |
String |
getFetchOperation()
Operation ID this component should use when performing fetch operations. |
String |
getHiliteProperty()
Marker that can be set on a record to flag that record as hilited. |
Criteria |
getInitialCriteria()
Criteria to use when setAutoFetchData(Boolean) is used. |
JavaScriptObject |
getOrCreateJsObj()
|
Boolean |
getPreventDuplicates()
If set, detect and prevent duplicate records from being transferred to this component, either via drag and drop or via transferSelectedData(com.smartgwt.client.widgets.DataBoundComponent) . |
int |
getRecordIndex(Record record)
Get the index of the provided record. |
RecordList |
getRecordList()
Return the underlying data of this DataBoundComponent as a RecordList . |
String |
getRemoveOperation()
Operation ID this component should use when performing remove operations. |
ResultSet |
getResultSet()
Return the underlying data of this DataBoundComponent as a ResultSet . |
Boolean |
getShowComplexFields()
Whether to show fields of non-atomic types when a DataBoundComponent is given a DataSource but no component.fields .
|
Boolean |
getShowDetailFields()
Whether to show fields marked detail:true when a DataBoundComponent is
given a DataSource but no component.fields .
|
Boolean |
getShowHiddenFields()
Whether to show fields marked hidden:true when a DataBoundComponent is given a
DataSource but no component.fields .
|
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 check titleField for databound
compounds.For non databound components returns the first defined field name of "title" ,
"name" , or "id" . |
String |
getTitleFieldValue(Record record)
Get the value of the titleField for the passed record |
String |
getUpdateOperation()
Operation ID this component should use when performing update operations. |
Boolean |
getUseAllDataSourceFields()
If true, the set of fields given by the "default binding" (see fields ) is used, with any fields specified in
component.fields acting 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.
|
Boolean |
getUseFlatFields()
The useFlatFields flag causes all simple type fields anywhere in a nested
set of DataSources to be exposed as a flat list for form binding. |
void |
invalidateCache()
Invalidate the current data cache for this databound component via a call to this.data.invalidateCache() . |
void |
selectAllRecords()
Select all records |
void |
selectRecord(int record)
Select/deselect a Record passed in explicitly, or by index. |
void |
selectRecord(int record,
boolean newState)
Select/deselect a Record passed in explicitly, or by index. |
void |
selectRecord(Record record)
Select/deselect a Record passed in explicitly, or by index. |
void |
selectRecord(Record record,
boolean newState)
Select/deselect a Record passed in explicitly, or by index. |
void |
selectRecords(int[] records)
Select/deselect a list of Record s passed in explicitly, or by index. |
void |
selectRecords(int[] records,
boolean newState)
Select/deselect a list of Record s passed in explicitly, or by index. |
void |
selectRecords(Record[] records)
Select/deselect a list of Record s passed in explicitly, or by index. |
void |
selectRecords(Record[] records,
boolean newState)
Select/deselect a list of Record s passed in explicitly, or by index. |
void |
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. |
void |
setAddFormulaFieldText(String addFormulaFieldText)
Text for a menu item allowing users to add a formula field |
void |
setAddOperation(String addOperation)
Operation ID this component should use when performing add operations. |
void |
setAddSummaryFieldText(String addSummaryFieldText)
Text for a menu item allowing users to add a formula field |
void |
setAutoFetchAsFilter(Boolean autoFetchAsFilter)
If setAutoFetchData(Boolean) is true, this attribute determines whether the initial fetch operation should be
performed via fetchData() or filterData() |
void |
setAutoFetchData(Boolean autoFetchData)
If true, when this component is first drawn, automatically call fetchData() or filterData() depending on
getAutoFetchAsFilter() . |
void |
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 com.smartgwt.client..FormulaBuilder .
|
void |
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 com.smartgwt.client..SummaryBuilder .
|
void |
setDataFetchMode(FetchMode fetchMode)
How to fetch and manage records retrieve from the server. |
void |
setDataPageSize(int dataPageSize)
When using data paging, how many records to fetch at a time. |
void |
setDataSource(DataSource dataSource)
The DataSource that this component should bind to for default fields and for performing DSRequest .
|
void |
setDragDataAction(DragDataAction dragDataAction)
Indicates what to do with data dragged into another DataBoundComponent. |
void |
setDragTrackerStyle(String dragTrackerStyle)
CSS Style to apply to the drag tracker when dragging occurs on this component. |
void |
setDropValues(Map dropValues)
When an item is dropped on this component, and addDropValues is 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 SmartGWT will apply to the dropped object
before updating it.
|
void |
setDuplicateDragMessage(String duplicateDragMessage)
Message to show when a user attempts to transfer duplicate records into this component, and preventDuplicates is enabled. |
void |
setEditFormulaFieldText(String editFormulaFieldText)
Text for a menu item allowing users to edit a formula field |
void |
setEditSummaryFieldText(String editSummaryFieldText)
Text for a menu item allowing users to edit the formatter for a field |
void |
setExportAll(Boolean exportAll)
Setting exportAll to true prevents the component from passing it's list of fields to the export call. |
void |
setExportFields(String[] exportFields)
The list of field-names to export. |
void |
setFetchOperation(String fetchOperation)
Operation ID this component should use when performing fetch operations. |
void |
setHiliteProperty(String hiliteProperty)
Marker that can be set on a record to flag that record as hilited. |
void |
setInitialCriteria(Criteria initialCriteria)
Criteria to use when setAutoFetchData(Boolean) is used. |
void |
setPreventDuplicates(Boolean preventDuplicates)
If set, detect and prevent duplicate records from being transferred to this component, either via drag and drop or via transferSelectedData(com.smartgwt.client.widgets.DataBoundComponent) . |
void |
setRemoveOperation(String removeOperation)
Operation ID this component should use when performing remove operations. |
void |
setShowComplexFields(Boolean showComplexFields)
Whether to show fields of non-atomic types when a DataBoundComponent is given a DataSource but no component.fields .
|
void |
setShowDetailFields(Boolean showDetailFields)
Whether to show fields marked detail:true when a DataBoundComponent is
given a DataSource but no component.fields .
|
void |
setShowHiddenFields(Boolean showHiddenFields)
Whether to show fields marked hidden:true when a DataBoundComponent is given a
DataSource but no component.fields .
|
void |
setTitleField(String titleField)
|
void |
setUpdateOperation(String updateOperation)
Operation ID this component should use when performing update operations. |
void |
setUseAllDataSourceFields(Boolean useAllDataSourceFields)
If true, the set of fields given by the "default binding" (see fields ) is used, with any fields specified in
component.fields acting 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.
|
void |
setUseFlatFields(Boolean useFlatFields)
The useFlatFields flag causes all simple type fields anywhere in a nested
set of DataSources to be exposed as a flat list for form binding. |
void |
transferSelectedData(DataBoundComponent source)
Simulates a drag / drop type transfer of the selected records in some other component to this component, without requiring any user interaction. |
void |
transferSelectedData(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. |
Method Detail |
---|
JavaScriptObject getOrCreateJsObj()
void setDataFetchMode(FetchMode fetchMode)
FetchMode
.
This setting only applies to the ResultSet
automatically created by calling fetchData
.
If a pre-existing ResultSet is passed to setData() instead, it's existing setting for fetchMode
applies.
fetchMode
- the fetch modeFetchMode getDataFetchMode()
FetchMode
.
This setting only applies to the ResultSet
automatically created by calling fetchData
.
If a pre-existing ResultSet is passed to setData() instead, it's existing setting for fetchMode
applies.
void setDataPageSize(int dataPageSize)
ResultSet
object for this
component. In effect, this gives you control over the resultSize
attribute for this component.
Note that regardless of the dataPageSize
setting, a component will always fetch
all of data that it needs to draw. Settings such as
showAllRecords
,
drawAllMaxCells
and
drawAheadRatio
can cause more rows than the configured
dataPageSize
to be fetched.
dataPageSize
- dataPageSize Default value is 75int getDataPageSize()
ResultSet
object for this
component. In effect, this gives you control over the resultSize
attribute for this component.
Note that regardless of the dataPageSize
setting, a component will always fetch
all of data that it needs to draw. Settings such as
showAllRecords
,
drawAllMaxCells
and
drawAheadRatio
can cause more rows than the configured
dataPageSize
to be fetched.
void setUseAllDataSourceFields(Boolean useAllDataSourceFields)
fields
) is used, with any fields specified in
component.fields
acting 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.fields
contains 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.
${isc.DocUtils.linkForExampleId('validationFieldBinding', 'This example')} shows a mixture of component fields and DataSource fields, and how they interact for validation.
useAllDataSourceFields
- useAllDataSourceFields Default value is falseBoolean getUseAllDataSourceFields()
fields
) is used, with any fields specified in
component.fields
acting 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.fields
contains 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.
${isc.DocUtils.linkForExampleId('validationFieldBinding', 'This example')} shows a mixture of component fields and DataSource fields, and how they interact for validation.
void setShowHiddenFields(Boolean showHiddenFields)
hidden:true
when a DataBoundComponent is given a
DataSource but no component.fields
.
The hidden
property is used on DataSource fields to mark fields that are
never of meaning to an end user.
showHiddenFields
- showHiddenFields Default value is falseBoolean getShowHiddenFields()
hidden:true
when a DataBoundComponent is given a
DataSource but no component.fields
.
The hidden
property is used on DataSource fields to mark fields that are
never of meaning to an end user.
void setShowDetailFields(Boolean showDetailFields)
detail:true
when a DataBoundComponent is
given a DataSource but no component.fields
.
The detail
property 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.
showDetailFields
- showDetailFields Default value is falseBoolean getShowDetailFields()
detail:true
when a DataBoundComponent is
given a DataSource but no component.fields
.
The detail
property 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.
void setShowComplexFields(Boolean showComplexFields)
component.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
showComplexFields
- showComplexFields Default value is trueBoolean getShowComplexFields()
component.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.
void setFetchOperation(String fetchOperation)
fetchOperation
- fetchOperation Default value is nullString getFetchOperation()
void setUpdateOperation(String updateOperation)
updateOperation
- updateOperation Default value is nullString getUpdateOperation()
void setAddOperation(String addOperation)
addOperation
- addOperation Default value is nullString getAddOperation()
void setRemoveOperation(String removeOperation)
removeOperation
- removeOperation Default value is nullString getRemoveOperation()
void setExportFields(String[] exportFields)
If exportFields is not provided, the exported output includes all visible fields from this component, sorted as they appear.
exportFields
- exportFields Default value is nullString[] getExportFields()
If exportFields is not provided, the exported output includes all visible fields from this component, sorted as they appear.
void setExportAll(Boolean exportAll)
fields
.
If exportAll is false, an export operation will first consider
exportFields
, if it's set, and fall back on all visible fields from
fields
otherwise.
exportAll
- exportAll Default value is falseBoolean getExportAll()
fields
.
If exportAll is false, an export operation will first consider
exportFields
, if it's set, and fall back on all visible fields from
fields
otherwise.
void setPreventDuplicates(Boolean preventDuplicates) throws IllegalStateException
transferSelectedData(com.smartgwt.client.widgets.DataBoundComponent)
. When a duplicate transfer is detected,
a dialog will appear showing the duplicateDragMessage
.
If the component either does not have a DataSource
or has a DataSource with no
primaryKey
declared, 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.
preventDuplicates
- preventDuplicates Default value is null
IllegalStateException
- this property cannot be changed after the component has been createdBoolean getPreventDuplicates()
transferSelectedData(com.smartgwt.client.widgets.DataBoundComponent)
. When a duplicate transfer is detected,
a dialog will appear showing the duplicateDragMessage
.
If the component either does not have a DataSource
or has a DataSource with no
primaryKey
declared, 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.
void setDuplicateDragMessage(String duplicateDragMessage) throws IllegalStateException
preventDuplicates
is enabled.
duplicateDragMessage
- duplicateDragMessage Default value is "Duplicates not allowed"
IllegalStateException
- this property cannot be changed after the component has been createdString getDuplicateDragMessage()
preventDuplicates
is enabled.
void setAddDropValues(Boolean addDropValues)
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
addDropValues
- addDropValues Default value is trueBoolean getAddDropValues()
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
void setDropValues(Map dropValues)
addDropValues
is 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 SmartGWT will apply to the dropped object
before updating it.
If this property is not defined, SmartGWT 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
dropValues
- dropValues Default value is nullMap getDropValues()
addDropValues
is 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 SmartGWT will apply to the dropped object
before updating it.
If this property is not defined, SmartGWT 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.
dropValues
for more details. If multiple records
are being dropped, this method is called for each of them in turn.
This method returns the following:
addDropValues
is falseYou can override this method if you need more complex setting of drop values than can be provided by simply supplying a dropValues object.
void setUseFlatFields(Boolean useFlatFields) throws IllegalStateException
useFlatFields
flag causes all simple type fields anywhere in a nested
set of DataSources to be exposed as a flat list for form binding.
useFlatFields
is 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>Setting
useFlatFields
on a DynamicForm
that is bound to this input
message schema would result in 5 FormItem
reflecting 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 a
WebService
, these values can be automatically
mapped to the structure of the input message for a web service operation by setting
useFlatFields
(for use with WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)
) or by setting
useFlatFields
(for use with a DataSource
that 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 useFlatFields
to automatically enable
"flattened" XML serialization (request.useFlatFields) for all DataSource requests of a
particular operationType.
Note that useFlatFields
is 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.
useFlatFields
- useFlatFields Default value is null
IllegalStateException
- this property cannot be changed after the component has been createdBoolean getUseFlatFields()
useFlatFields
flag causes all simple type fields anywhere in a nested
set of DataSources to be exposed as a flat list for form binding.
useFlatFields
is 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>Setting
useFlatFields
on a DynamicForm
that is bound to this input
message schema would result in 5 FormItem
reflecting 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 a
WebService
, these values can be automatically
mapped to the structure of the input message for a web service operation by setting
useFlatFields
(for use with WebService.callOperation(java.lang.String, java.util.Map, java.lang.String, com.smartgwt.client.data.WebServiceCallback)
) or by setting
useFlatFields
(for use with a DataSource
that 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 useFlatFields
to automatically enable
"flattened" XML serialization (request.useFlatFields) for all DataSource requests of a
particular operationType.
Note that useFlatFields
is 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.
void setHiliteProperty(String hiliteProperty)
id
for a hilite defined on this component.
hiliteProperty
- hiliteProperty Default value is "_hilite"String getHiliteProperty()
id
for a hilite defined on this component.
void setDragDataAction(DragDataAction dragDataAction)
dragDataAction
- dragDataAction Default value is Canvas.MOVEDragDataAction getDragDataAction()
void setDragTrackerStyle(String dragTrackerStyle)
dragTrackerStyle
- dragTrackerStyle Default value is "gridDragTracker"String getDragTrackerStyle()
void setCanAddFormulaFields(Boolean canAddFormulaFields)
com.smartgwt.client..FormulaBuilder
.
User-added formula fields can be persisted via ListGrid.getFieldState()
and
ListGrid.setFieldState(java.lang.String)
.
canAddFormulaFields
- canAddFormulaFields Default value is falsevoid addSummaryField()
com.smartgwt.client..SummaryBuilder
to create a new Summary Field. This
is equivalent to calling DataBoundComponentGen#editSummaryField
with
no paramater.
void addFormulaField()
com.smartgwt.client..FormulaBuilder
to create a new Formula Field. This
is equivalent to calling DataBoundComponentGen#editFormulaField
with
no paramater.
Boolean getCanAddFormulaFields()
com.smartgwt.client..FormulaBuilder
.
User-added formula fields can be persisted via ListGrid.getFieldState()
and
ListGrid.setFieldState(java.lang.String)
.
void setAddFormulaFieldText(String addFormulaFieldText)
addFormulaFieldText
- addFormulaFieldText Default value is "Add formula column..."String getAddFormulaFieldText()
void setEditFormulaFieldText(String editFormulaFieldText)
editFormulaFieldText
- editFormulaFieldText Default value is "Edit formula..."String getEditFormulaFieldText()
void setCanAddSummaryFields(Boolean canAddSummaryFields)
com.smartgwt.client..SummaryBuilder
.
User-added summary fields can be persisted via ListGrid.getFieldState()
and
ListGrid.setFieldState(java.lang.String)
.
canAddSummaryFields
- canAddSummaryFields Default value is falseBoolean getCanAddSummaryFields()
com.smartgwt.client..SummaryBuilder
.
User-added summary fields can be persisted via ListGrid.getFieldState()
and
ListGrid.setFieldState(java.lang.String)
.
void setAddSummaryFieldText(String addSummaryFieldText)
addSummaryFieldText
- addSummaryFieldText Default value is "Add summary column..."String getAddSummaryFieldText()
void setEditSummaryFieldText(String editSummaryFieldText)
editSummaryFieldText
- editSummaryFieldText Default value is "Edit summary format..."String getEditSummaryFieldText()
void selectRecord(Record record)
Record
passed in explicitly, or by index.
record
- record (or row number) to selectvoid selectRecord(int record)
Record
passed in explicitly, or by index.
record
- record (or row number) to selectvoid selectRecord(int record, boolean newState)
Record
passed in explicitly, or by index.
record
- record (or row number) to selectnewState
- new selection state (if null, defaults to true)void selectRecord(Record record, boolean newState)
Record
passed in explicitly, or by index.
record
- record (or row number) to selectnewState
- new selection state (if null, defaults to true)void selectRecords(int[] records)
Record
s passed in explicitly, or by index.
records
- records (or row numbers) to selectvoid selectRecords(int[] records, boolean newState)
Record
s passed in explicitly, or by index.
records
- records (or row numbers) to selectnewState
- new selection statevoid selectRecords(Record[] records)
Record
s passed in explicitly, or by index.
records
- records (or row numbers) to selectvoid selectRecords(Record[] records, boolean newState)
Record
s passed in explicitly, or by index.
records
- records (or row numbers) to selectnewState
- new selection state (if null, defaults to true)void deselectRecord(Record record)
Record
passed in explicitly, or by index. Synonym for
selectRecord(record, false)
record
- record (or row number) to deselectvoid deselectRecord(int record)
Record
passed in explicitly, or by index. Synonym for
selectRecord(record, false)
record
- record (or row number) to deselectvoid deselectRecords(int[] records)
Record
s passed in explicitly, or by index. Synonym
for selectRecords(records, false)
records
- records (or row numbers) to deselectvoid deselectRecords(Record[] records)
Record
s passed in explicitly, or by index. Synonym
for selectRecords(records, false)
records
- records (or row numbers) to deselectvoid selectAllRecords()
void deselectAllRecords()
Boolean anySelected()
void enableHilite(String hiliteID)
hilites
hiliteID
- ID of hilite to enablevoid enableHilite(String hiliteID, boolean enable)
hilites
hiliteID
- ID of hilite to enableenable
- new enabled state to apply - if null, defaults to truevoid disableHilite(String hiliteID)
hiliteID
- ID of hilite to disablevoid enableHiliting()
void enableHiliting(boolean enable)
enable
- new enabled state to apply - if null, defaults to truevoid disableHiliting()
Record[] getDragData()
This method is generally called by com.smartgwt.client.widgets.DataBoundComponent#transferDragData
and is consulted by
ListGrid.willAcceptDrop()
.
Record
s that are currently selected.void transferSelectedData(DataBoundComponent source)
getDropValues()
for each dropped record.
To transfer all data in, for example, a ListGrid
, call grid.selection.selectAll() first.
See the Dragging
documentation for an overview of list grid drag/drop data
transfer.
source
- source component from which the records will be tranferredvoid transferSelectedData(DataBoundComponent source, int index)
getDropValues()
for each dropped record.
To transfer all data in, for example, a ListGrid
, call grid.selection.selectAll() first.
See the Dragging
documentation for an overview of list grid drag/drop data
transfer.
source
- source component from which the records will be tranferredindex
- target index (drop position) of the rows within this grid.int getRecordIndex(Record record)
Override in subclasses to provide more specific behaviour, for instance, when data holds a large number of records
record
- the record whose index is to be retrieved
String getTitleFieldValue(Record record)
Override in subclasses
record
- the record whose index is to be retrieved
String getTitleField()
titleField
for databound
compounds."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.
void setTitleField(String titleField)
void setDataSource(DataSource dataSource)
DSRequest
.
Can be specified as either a DataSource instance or the String ID of a DataSource. Bind to a new DataSource.
Like passing the "dataSource" property on creation, binding to a DataSource means that the component will use the DataSource to provide default data for its fields.
When binding 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, pass them to setDataSource().
dataSource
- DataSource to bind to. Default value is nullDataSource getDataSource()
DSRequest
.
Can be specified as either a DataSource instance or the String ID of a DataSource.
void fetchData()
DataSource
to retrieve data that matches
the provided criteria, and displays the matching data in this component. If there are a large number of matching records, paging will automatically be enabled, so that initially a smaller number of records will be retrieved and further records will be fetched as the user navigates the dataset.
When first called, this
method will create a ResultSet
, which will be configured based on component
settings such as fetchOperation
and dataPageSize
, as well as the general purpose dataProperties
. The ResultSet is then available as
component.data
.
Subsequent calls to fetchData() will simply call ResultSet.setCriteria(com.smartgwt.client.data.Criteria)
on the created ResultSet with the passed criteria.
In some
cases fetchData() will not need to context the server as the new criteria can be satisfied by performing a
client-side filter against the currently cached set of data. You can determine whether criteria will cause a
fetch by calling ResultSet.willFetchData(com.smartgwt.client.data.Criteria)
.
If you need to force a server
fetch, you can call ResultSet.invalidateCache()
via
component.data.invalidateCache()
to do so.
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 we recomment using ResultSet.willFetchData(com.smartgwt.client.data.Criteria)
before calling this method to determine whether or not a server
fetch will occur.
In addition to the callback parameter for this method, developers can use ResultSet.dataArrived(int, int)
to be notified every time ResultSet data is loaded. A
dataArrived
method can be installed in the automatically created ResultSet by adding it to dataProperties
.
void fetchData(Criteria criteria)
DataSource
to retrieve data that matches
the provided criteria, and displays the matching data in this component. If there are a large number of matching records, paging will automatically be enabled, so that initially a smaller number of records will be retrieved and further records will be fetched as the user navigates the dataset.
When first called, this
method will create a ResultSet
, which will be configured based on component
settings such as fetchOperation
and dataPageSize
, as well as the general purpose dataProperties
. The ResultSet is then available as
component.data
.
Subsequent calls to fetchData() will simply call ResultSet.setCriteria(com.smartgwt.client.data.Criteria)
on the created ResultSet with the passed criteria.
In some
cases fetchData() will not need to context the server as the new criteria can be satisfied by performing a
client-side filter against the currently cached set of data. You can determine whether criteria will cause a
fetch by calling ResultSet.willFetchData(com.smartgwt.client.data.Criteria)
.
If you need to force a server
fetch, you can call ResultSet.invalidateCache()
via
component.data.invalidateCache()
to do so.
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 we recomment using ResultSet.willFetchData(com.smartgwt.client.data.Criteria)
before calling this method to determine whether or not a server
fetch will occur.
In addition to the callback parameter for this method, developers can use ResultSet.dataArrived(int, int)
to be notified every time ResultSet data is loaded. A
dataArrived
method can be installed in the automatically created ResultSet by adding it to dataProperties
.
criteria
- Search criteria. If a DynamicForm
is passed in as this argument instead of a raw criteria object, will be
derived by calling DynamicForm.getValuesAsCriteria()
void fetchData(Criteria criteria, DSCallback callback)
DataSource
to retrieve data that matches
the provided criteria, and displays the matching data in this component. If there are a large number of matching records, paging will automatically be enabled, so that initially a smaller number of records will be retrieved and further records will be fetched as the user navigates the dataset.
When first called, this
method will create a ResultSet
, which will be configured based on component
settings such as fetchOperation
and dataPageSize
, as well as the general purpose dataProperties
. The ResultSet is then available as
component.data
.
Subsequent calls to fetchData() will simply call ResultSet.setCriteria(com.smartgwt.client.data.Criteria)
on the created ResultSet with the passed criteria.
In some
cases fetchData() will not need to context the server as the new criteria can be satisfied by performing a
client-side filter against the currently cached set of data. You can determine whether criteria will cause a
fetch by calling ResultSet.willFetchData(com.smartgwt.client.data.Criteria)
.
If you need to force a server
fetch, you can call ResultSet.invalidateCache()
via
component.data.invalidateCache()
to do so.
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 we recomment using ResultSet.willFetchData(com.smartgwt.client.data.Criteria)
before calling this method to determine whether or not a server
fetch will occur.
In addition to the callback parameter for this method, developers can use ResultSet.dataArrived(int, int)
to be notified every time ResultSet data is loaded. A
dataArrived
method can be installed in the automatically created ResultSet by adding it to dataProperties
.
criteria
- Search criteria. If a DynamicForm
is passed in as this argument instead of a raw criteria object, will be
derived by calling DynamicForm.getValuesAsCriteria()
callback
- callback to invoke when a fetch is complete. Fires only
if server contact was requiredvoid fetchData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
DataSource
to retrieve data that matches
the provided criteria, and displays the matching data in this component. If there are a large number of matching records, paging will automatically be enabled, so that initially a smaller number of records will be retrieved and further records will be fetched as the user navigates the dataset.
When first called, this
method will create a ResultSet
, which will be configured based on component
settings such as fetchOperation
and dataPageSize
, as well as the general purpose dataProperties
. The ResultSet is then available as
component.data
.
Subsequent calls to fetchData() will simply call ResultSet.setCriteria(com.smartgwt.client.data.Criteria)
on the created ResultSet with the passed criteria.
In some
cases fetchData() will not need to context the server as the new criteria can be satisfied by performing a
client-side filter against the currently cached set of data. You can determine whether criteria will cause a
fetch by calling ResultSet.willFetchData(com.smartgwt.client.data.Criteria)
.
If you need to force a server
fetch, you can call ResultSet.invalidateCache()
via
component.data.invalidateCache()
to do so.
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 we recomment using ResultSet.willFetchData(com.smartgwt.client.data.Criteria)
before calling this method to determine whether or not a server
fetch will occur.
In addition to the callback parameter for this method, developers can use ResultSet.dataArrived(int, int)
to be notified every time ResultSet data is loaded. A
dataArrived
method can be installed in the automatically created ResultSet by adding it to dataProperties
.
criteria
- Search criteria. If a DynamicForm
is passed in as this argument instead of a raw criteria object,
will be derived by calling DynamicForm.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 issuedvoid filterData()
This
method behaves exactly like ListGrid.fetchData()
except that textMatchStyle
is automatically set to "substring" so that
String-valued fields are matched by case-insensitive substring comparison.
criteria
- Search criteria. If a DynamicForm
is passed in as this argument instead of a raw criteria object, will be
derived by calling DynamicForm.getValuesAsCriteria()
void filterData(Criteria criteria)
This
method behaves exactly like ListGrid.fetchData()
except that textMatchStyle
is automatically set to "substring" so that
String-valued fields are matched by case-insensitive substring comparison.
criteria
- Search criteria. If a DynamicForm
is passed in as this argument instead of a raw criteria object, will be
derived by calling DynamicForm.getValuesAsCriteria()
callback
- callback to invoke when a fetch is complete. Fires only
if server contact was required; see fetchData()
for detailsvoid filterData(Criteria criteria, DSCallback callback)
This
method behaves exactly like ListGrid.fetchData()
except that textMatchStyle
is automatically set to "substring" so that
String-valued fields are matched by case-insensitive substring comparison.
criteria
- Search criteria. If a DynamicForm
is passed in as this argument instead of a raw criteria object,
will be derived by calling DynamicForm.getValuesAsCriteria()
callback
- callback to invoke when a fetch is complete. Fires
only if server contact was required; see
fetchData()
for detailsvoid filterData(Criteria criteria, DSCallback callback, DSRequest requestProperties)
This
method behaves exactly like ListGrid.fetchData()
except that textMatchStyle
is automatically set to "substring" so that
String-valued fields are matched by case-insensitive substring comparison.
criteria
- Search criteria. If a DynamicForm
is passed in as this argument instead of a raw criteria object,
will be derived by calling DynamicForm.getValuesAsCriteria()
callback
- callback to invoke when a fetch is complete. Fires
only if server contact was required; see
fetchData()
for detailsrequestProperties
- for databound components only - optional additional
properties to set on the DSRequest that will be issuedvoid setAutoFetchData(Boolean autoFetchData)
fetchData()
or filterData()
depending on
getAutoFetchAsFilter()
. Criteria for this fetch may be picked up from initialCriteria
.
autoFetchData
- autoFetchDataBoolean getAutoFetchData()
fetchData()
or filterData()
depending on
getAutoFetchAsFilter()
. Criteria for this fetch may be picked up from initialCriteria
.
void setAutoFetchAsFilter(Boolean autoFetchAsFilter)
setAutoFetchData(Boolean)
is true, this attribute determines whether the initial fetch operation should be
performed via fetchData()
or filterData()
autoFetchAsFilter
- autoFetchAsFilterBoolean getAutoFetchAsFilter()
setAutoFetchData(Boolean)
is true, this attribute determines whether the initial fetch operation should be
performed via fetchData()
or filterData()
void setInitialCriteria(Criteria initialCriteria) throws IllegalStateException
setAutoFetchData(Boolean)
is used.
initialCriteria
- the initial criteria
IllegalStateException
- this property cannot be changed after the component has been createdCriteria getInitialCriteria()
setAutoFetchData(Boolean)
is used.
void invalidateCache()
this.data.invalidateCache()
. If necessary, this will cause a new fetch to
be performed with the current set of criteria for this component.
Has no effect if this component is not showing a set of filtered data.
ResultSet getResultSet() throws IllegalStateException
ResultSet
.
Note that this method should only be called after initial data has been fetched by this DataBoundComponent.
IllegalStateException
- if called on a component with local array data, or a DataBoundComponent before the
initial data is fetched.fetchData()
RecordList getRecordList()
RecordList
.
If the underlying data in not local data, and the component is bound to a DataSource
,
then the actual instance of the RecordList will be of type ResultSet
.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |