Class ResultTree
- All Implemented Interfaces:
HasHandlers,HasDataChangedHandlers,HasDataChangedHandlers
Tree API, used to handle hierarchical
data, whose nodes are DataSource records which are retrieved from a server. Modifying ResultTrees
ResultTree nodes cannot be directly added or removed from a paged ResultTree via Tree APIs such as Tree.add() or
Tree.remove(), since such trees are considered to be read-only by
virtue of containing ResultSets, which are read-only data structures. Even in other
FetchModes, calling such APIs will only update the local cache of the ResultTree,
rather than triggering any server traffict to update the DataSource.
Use DataSource.addData()/removeData() to add/remove rows from the DataSource, and the ResultTree
will reflect the changes automatically. Alternatively, the DataSource.updateCaches() method may be called to only update local caches of the DataSource in question, without
generating any server traffic.
To create a locally modifiable cache of records from a DataSource, you can use DataSource.fetchData() to retrieve a List of records which can be
modified directly, or you can create a client-only DataSource from the retrieved data
to share a modifiable cache between several DataBoundComponents.
-
Nested Class Summary
Nested classes/interfaces inherited from class com.smartgwt.client.data.RecordList
RecordList.SortNormalizer -
Field Summary
Fields inherited from class com.smartgwt.client.data.RecordList
jsObjFields inherited from class com.smartgwt.client.core.BaseClass
config, configOnly, factoryCreated, factoryProperties, id, scClassName -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionapplyFilter(Tree tree, Criteria criteria, TreeFilterMode filterMode, DataSource dataSource) The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.applyFilter(Tree tree, Criteria criteria, TreeFilterMode filterMode, DataSource dataSource, DSRequest requestProperties) The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.intcompareCriteria(Criteria newCriteria, Criteria oldCriteria) Default behavior is to callDataSource.compareCriteria()to determine whether new criteria is equivalent to the old criteria (returns 0) or not.intcompareCriteria(Criteria newCriteria, Criteria oldCriteria, DSRequest requestProperties) Default behavior is to callDataSource.compareCriteria()to determine whether new criteria is equivalent to the old criteria (returns 0) or not.create()voiddataArrived(TreeNode parentNode) This callback fires whenever the resultTree receives new nodes from the server, after the new nodes have been integrated into the tree.get(int pos) Get the item in the openList at a particular position.Which nodes should be opened automatically - applied wheneversetRoot()is called, including during initialization and as part of a re-fetch caused, for example, byduplicate()orinvalidateCache().Controls what happens to the"open state"- the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of callinginvalidateCache()or of changing criteria such that the current cache of nodes is dropped.Formulti-link trees, indicates that we should automatically update thepositionvalues of old and new sibling records after a drag reparent or reposition-within-parent operation.booleanWhen usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for thecanReturnOpenSubfoldersPropertywhen no value for that property is provided for a node.When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse,canReturnOpenSubfoldersPropertymay be set on any folder to indicate whether child folders might be returned by the server already open.When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse,childCountPropertymust be set for any folders that include only a partial list of children.The filter criteria to use when fetching rows.TreeNode[]getData()Optional initial data for the tree.WhatDataSourceis this resultTree associated with?Controls whether nodes are assumed to be folders or leaves by default.This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes.When data is loaded from the server, should nodes with an explicit value for theTree.parentIdFieldwhich doesn't map to a valid parent node be dropped? If set to false, forTreeGrid.loadDataOnDemand:false trees, parentless nodes will be added as children of the root node - forTreeGrid.loadDataOnDemand:true, they will be added as children of the folder currently requesting children.Mode of fetching records from server.IfautoUpdateSiblingNodesOnDragis in force, this is the value we will use to auto-update the position of a node when we cannot derive that value from the existing value of a neighbor.Criteria that are never shown to or edited by the user and are cumulative with any criteria provided viaDataBoundComponent.initialCriteria,setCriteria()etc.If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria.When a tree specifies the combination ofkeepParentsOnFilterandloadDataOnDemand, Smart GWT by default automatically fetches the "skeleton" of the filtered tree - see thekeepParentsOnFilteroverview for details, including the definition of "skeleton" and other relevant terminologyThe fetch mode for this tree's link data; ignored if this is not amulti-link treeThis property allows you to specify the dataSource to be used for fetching link information in a databound multilink tree.This property allows you to specify the dataSource to be used for fetching link information in a databound multilink tree.Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request? Must be true iffetchModeis "paged"This property allows you to specify the number of ancestor levels Smart GWT attempts to retrieve with each request, when using the built-in support forkeepParentsOnFilteronloadDataOnDemandtrees.Selects the model used to construct the tree representation.Returns a snapshot of the current open state of this tree's data as aTreeGridOpenStateobject.static ResultTreegetOrCreateRef(JavaScriptObject jsObj) This method returns a Map of config properties suitable for use as the "defaults" attribute of aPaletteNode.Setsprogressive loading modefor this ResultTree.TreeNode[]getRange(int start, int end) Get a range of items from the open listHow many tree nodes to retrieve at once from each large set of children in the tree.This attribute may be used to specify a root value for the parentIdField of this resultTree.Formulti-link trees only, should we send up theparentIdin fetch criteria if the criteria value is null? If false, we remove theparentIdfrom the criteria whenfetching link data, if the criteria value is null (as it will be by default when fetching the direct child nodes of the tree's root).String[]ForfetchMode:"local"ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.If true, indicates that your own server code will handle the complexities associated with the combination ofkeepParentsOnFilterandloadDataOnDemand.When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, ifDSResponse.datais unset, should we integrate the submitted data values (from the request) into our data-set?booleanWhether or not we should skip promotion of a simple criteria to anAdvancedCriteriawhen sending theDSRequestto load the children of a node in aloadDataOnDemandorfetchMode:"paged"ResultTree.voidManually invalidate this ResultTree's cache.setAutoOpen(String autoOpen) Which nodes should be opened automatically - applied wheneversetRoot()is called, including during initialization and as part of a re-fetch caused, for example, byduplicate()orinvalidateCache().setAutoPreserveOpenState(PreserveOpenState autoPreserveOpenState) Controls what happens to the"open state"- the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of callinginvalidateCache()or of changing criteria such that the current cache of nodes is dropped.setAutoUpdateSiblingNodesOnDrag(Boolean autoUpdateSiblingNodesOnDrag) Formulti-link trees, indicates that we should automatically update thepositionvalues of old and new sibling records after a drag reparent or reposition-within-parent operation.setCanReturnOpenFolders(boolean canReturnOpenFolders) When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for thecanReturnOpenSubfoldersPropertywhen no value for that property is provided for a node.setCanReturnOpenSubfoldersProperty(String canReturnOpenSubfoldersProperty) When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse,canReturnOpenSubfoldersPropertymay be set on any folder to indicate whether child folders might be returned by the server already open.setChildCountProperty(String childCountProperty) When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse,childCountPropertymust be set for any folders that include only a partial list of children.voidsetChildren(TreeNode parent, List newChildren) Replaces the existing children of a parent node.voidsetChildren(TreeNode parent, List newChildren, Integer totalChildren) Replaces the existing children of a parent node.setCriteria(Criteria criteria) The filter criteria to use when fetching rows.Optional initial data for the tree.setDataSource(DataSource dataSource) WhatDataSourceis this resultTree associated with?setDefaultIsFolder(Boolean defaultIsFolder) Controls whether nodes are assumed to be folders or leaves by default.setDefaultNewNodesToRoot(Boolean defaultNewNodesToRoot) This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.static voidsetDefaultProperties(ResultTree resultTreeProperties) Class level method to set the default properties of this class.setDisableCacheSync(Boolean disableCacheSync) By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes.setDiscardParentlessNodes(Boolean discardParentlessNodes) When data is loaded from the server, should nodes with an explicit value for theTree.parentIdFieldwhich doesn't map to a valid parent node be dropped? If set to false, forTreeGrid.loadDataOnDemand:false trees, parentless nodes will be added as children of the root node - forTreeGrid.loadDataOnDemand:true, they will be added as children of the folder currently requesting children.setFetchMode(FetchMode fetchMode) Mode of fetching records from server.setFirstPositionValue(Integer firstPositionValue) IfautoUpdateSiblingNodesOnDragis in force, this is the value we will use to auto-update the position of a node when we cannot derive that value from the existing value of a neighbor.setImplicitCriteria(Criteria implicitCriteria) Criteria that are never shown to or edited by the user and are cumulative with any criteria provided viaDataBoundComponent.initialCriteria,setCriteria()etc.setKeepParentsOnFilter(Boolean keepParentsOnFilter) If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria.setKeepParentsOnFilterMaxNodes(Integer keepParentsOnFilterMaxNodes) When a tree specifies the combination ofkeepParentsOnFilterandloadDataOnDemand, Smart GWT by default automatically fetches the "skeleton" of the filtered tree - see thekeepParentsOnFilteroverview for details, including the definition of "skeleton" and other relevant terminologysetLinkDataAddOperation(String linkDataAddOperation) setLinkDataFetchMode(LinkDataFetchMode linkDataFetchMode) The fetch mode for this tree's link data; ignored if this is not amulti-link treesetLinkDataFetchOperation(String linkDataFetchOperation) setLinkDataRemoveOperation(String linkDataRemoveOperation) setLinkDataSource(DataSource linkDataSource) This property allows you to specify the dataSource to be used for fetching link information in a databound multilink tree.setLinkDataSource(String linkDataSource) This property allows you to specify the dataSource to be used for fetching link information in a databound multilink tree.setLoadDataOnDemand(Boolean loadDataOnDemand) Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request? Must be true iffetchModeis "paged"setMatchingLeafJoinDepth(Integer matchingLeafJoinDepth) This property allows you to specify the number of ancestor levels Smart GWT attempts to retrieve with each request, when using the built-in support forkeepParentsOnFilteronloadDataOnDemandtrees.setModelType(TreeModelType modelType) Selects the model used to construct the tree representation.voidsetOpenState(String openState) Reset the set of open folders within this tree's data to match theTreeGridOpenStateobject passed in.setProgressiveLoading(Boolean progressiveLoading) Setsprogressive loading modefor this ResultTree.setResultSize(Integer resultSize) How many tree nodes to retrieve at once from each large set of children in the tree.voidsetRootNode(JavaScriptObject rootNode) This attribute may be used to specify a root value for the parentIdField of this resultTree.setSendNullParentInLinkDataCriteria(Boolean sendNullParentInLinkDataCriteria) Formulti-link trees only, should we send up theparentIdin fetch criteria if the criteria value is null? If false, we remove theparentIdfrom the criteria whenfetching link data, if the criteria value is null (as it will be by default when fetching the direct child nodes of the tree's root).setServerFilterFields(String... serverFilterFields) ForfetchMode:"local"ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.setServerKeepParentsOnFilter(Boolean serverKeepParentsOnFilter) If true, indicates that your own server code will handle the complexities associated with the combination ofkeepParentsOnFilterandloadDataOnDemand.setUpdateCacheFromRequest(Boolean updateCacheFromRequest) When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, ifDSResponse.datais unset, should we integrate the submitted data values (from the request) into our data-set?setUseSimpleCriteriaLOD(boolean useSimpleCriteriaLOD) Whether or not we should skip promotion of a simple criteria to anAdvancedCriteriawhen sending theDSRequestto load the children of a node in aloadDataOnDemandorfetchMode:"paged"ResultTree.voidunloadChildren(TreeNode node) Deprecated.willFetchData(Criteria newCriteria) Will changing the criteria for this resultTree require fetching new data from the server or can the new criteria be satisfied from data already cached on the client?Methods inherited from class com.smartgwt.client.widgets.tree.Tree
add, add, add, add, addDataChangedHandler, addList, addList, addList, addList, allChildrenLoaded, closeAll, closeAll, closeAll, closeFolder, closeFolder, closeFolder, closeFolder, closeFolders, createNodeLocator, createNodeLocator, discoverTree, find, find, find, findById, findChildrenProperty, findIndex, findIndex, findIndex, findIndex, findNextIndex, findNextIndex, findNextIndex, findNextNodeIndex, findNextNodeIndex, findNextNodeIndex, findNodeIndex, findNodeIndex, findNodeIndex, findNodeIndex, getAllNodes, getAllNodes, getAllowFilterOnLinkFields, getAutoOpenRoot, getChildren, getChildrenProperty, getChildrenResultSet, getDataSourceAsString, getDefaultNodeTitle, getDescendantFolders, getDescendantFolders, getDescendantLeaves, getDescendantLeaves, getDescendantNodeLocators, getDescendantNodeLocators, getDescendants, getDescendants, getFilteredTree, getFilteredTree, getFolders, getIdField, getIsFolderProperty, getLeaves, getLength, getLevel, getLevel, getLinkData, getLinkPositionField, getLoadState, getMultiLinkParents, getName, getName, getNameProperty, getNodeLocator, getOpenList, getOpenProperty, getParent, getParentIdField, getParentPath, getParents, getParentsAndPositions, getPath, getPathDelim, getPathForOpenListIndex, getReportCollisions, getRoot, getRootValue, getSeparateFolders, getShowRoot, getSortFoldersBeforeLeaves, getTitle, getTitleProperty, hasChildren, hasFolders, hasLeaves, isDescendantOf, isFolder, isInAncestorChain, isLeaf, isLoaded, isMultiLinkTree, isOpen, isOpen, isOpen, isOpen, isParent, isRoot, linkDataChanged, linkNodes, loadChildren, loadChildren, move, move, nodeForRecord, openAll, openAll, openAll, openAll, openAll, openFolder, openFolders, reloadChildren, remove, remove, remove, remove, removeChildren, removeList, setAllowFilterOnLinkFields, setAutoOpenRoot, setChildrenProperty, setDataSource, setDefaultNodeTitle, setDefaultProperties, setIdField, setIsFolderProperty, setJavaScriptObject, setLinkData, setLinkPositionField, setMultiLinkTree, setNameProperty, setOpenProperty, setParentIdField, setPathDelim, setReportCollisions, setRoot, setRootValue, setRootValue, setSeparateFolders, setShowRoot, setSortFoldersBeforeLeaves, setTitlePropertyMethods inherited from class com.smartgwt.client.data.RecordList
add, addAt, addDataChangedHandler, addList, addList, addListAt, contains, contains, containsAll, duplicate, equals, find, find, find, findAll, findAll, findAll, findAll, findAll, findAll, findAll, findAll, findIndex, findIndex, findIndex, findIndex, findIndex, findIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, findNextIndex, first, getItems, getJsObj, getOrCreateJsObj, getProperty, getRangeList, getValueMap, indexOf, indexOf, intersect, isARecordList, isCreated, isEmpty, last, lastIndexOf, lastIndexOf, remove, removeAt, removeList, set, setLength, setSort, sort, sort, sortByProperty, sortByProperty, toArrayMethods inherited from class com.smartgwt.client.core.BaseClass
addDynamicProperty, addDynamicProperty, addDynamicProperty, addDynamicProperty, applyFactoryProperties, asSGWTComponent, clearDynamicProperty, createJsObj, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getID, getRef, getRuleScope, getScClassName, getTestInstance, hasAutoAssignedID, hasDynamicProperty, internalSetID, internalSetID, isConfigOnly, isFactoryCreated, onBind, onInit, registerID, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setConfig, setConfigOnly, setFactoryCreated, setID, setProperty, setProperty, setProperty, setProperty, setRuleScope, setScClassNameMethods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
-
Constructor Details
-
ResultTree
public ResultTree() -
ResultTree
-
-
Method Details
-
getOrCreateRef
-
getPaletteDefaults
This method returns a Map of config properties suitable for use as the "defaults" attribute of aPaletteNode. Use it when you need to work with PaletteNodes indirectly, such when setting upTileRecords that will be used in aTilePalette. Seethe dev tools overviewfor examples of how to assemble and acquire a suitable defaults object when you are creating a PaletteNode indirectly -
create
-
setAutoOpen
Which nodes should be opened automatically - applied wheneversetRoot()is called, including during initialization and as part of a re-fetch caused, for example, byduplicate()orinvalidateCache().Options are:
- "none" - no nodes are opened automatically
- "root" - opens the
top-level node- in databound trees, this node is always hidden - "all" - when
loading data on demand, opens thetop-level nodeand all of it's direct descendants - otherwise, opens all loaded nodes
- Parameters:
autoOpen- New autoOpen value. Default value is "none"- Returns:
ResultTreeinstance, for chaining setter calls
-
getAutoOpen
Which nodes should be opened automatically - applied wheneversetRoot()is called, including during initialization and as part of a re-fetch caused, for example, byduplicate()orinvalidateCache().Options are:
- "none" - no nodes are opened automatically
- "root" - opens the
top-level node- in databound trees, this node is always hidden - "all" - when
loading data on demand, opens thetop-level nodeand all of it's direct descendants - otherwise, opens all loaded nodes
- Returns:
- Current autoOpen value. Default value is "none"
-
setAutoPreserveOpenState
Controls what happens to the"open state"- the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of callinginvalidateCache()or of changing criteria such that the current cache of nodes is dropped.- Parameters:
autoPreserveOpenState- New autoPreserveOpenState value. Default value is "whenUnique"- Returns:
ResultTreeinstance, for chaining setter calls
-
getAutoPreserveOpenState
Controls what happens to the"open state"- the set of nodes opened or closed by the end user after tree data is loaded - when an entirely new tree of nodes is loaded from the server, as a consequence of callinginvalidateCache()or of changing criteria such that the current cache of nodes is dropped.- Returns:
- Current autoPreserveOpenState value. Default value is "whenUnique"
-
setAutoUpdateSiblingNodesOnDrag
public ResultTree setAutoUpdateSiblingNodesOnDrag(Boolean autoUpdateSiblingNodesOnDrag) throws IllegalStateException Formulti-link trees, indicates that we should automatically update thepositionvalues of old and new sibling records after a drag reparent or reposition-within-parent operation. For example, say you have a tree like this (where the number in parentheses indicates the node'spositionvalue):A - B (1) - C (2) - D (3) E - F (1) - G (2)and you drag node C out and drop it between nodes F and G. This drag operation will spawn two update operations to the server: a "remove" to delete node C from parent A, and an "add" to re-add it under parent E. WithautoUpdateSiblingNodesOnDragin force, we also automatically issue two "update" operations to the server - one to change the position on node D to 2, and another to change the position on node G to 3. The end result of this is that node position values are kept correct.Please note the following:
- As noted above, these automatic updates are persistent - we send a queue of actual update requests to the server. This is convenient, but it may not be terribly efficient, particularly if you have just dropped a node at the head of a list of several hundred siblings. This is why we do not default this setting to true
- The automatic updates work by applying an integer delta value to the existing position
value. So in the above example, we would compute a delta of negative 1 for node D and
positive 1 for node G. The upshot of this is that
autoUpdateSiblingNodesOnDragonly works well if your position values are consecutive integers
- Parameters:
autoUpdateSiblingNodesOnDrag- New autoUpdateSiblingNodesOnDrag value. Default value is (see below)- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getAutoUpdateSiblingNodesOnDrag
Formulti-link trees, indicates that we should automatically update thepositionvalues of old and new sibling records after a drag reparent or reposition-within-parent operation. For example, say you have a tree like this (where the number in parentheses indicates the node'spositionvalue):A - B (1) - C (2) - D (3) E - F (1) - G (2)and you drag node C out and drop it between nodes F and G. This drag operation will spawn two update operations to the server: a "remove" to delete node C from parent A, and an "add" to re-add it under parent E. WithautoUpdateSiblingNodesOnDragin force, we also automatically issue two "update" operations to the server - one to change the position on node D to 2, and another to change the position on node G to 3. The end result of this is that node position values are kept correct.Please note the following:
- As noted above, these automatic updates are persistent - we send a queue of actual update requests to the server. This is convenient, but it may not be terribly efficient, particularly if you have just dropped a node at the head of a list of several hundred siblings. This is why we do not default this setting to true
- The automatic updates work by applying an integer delta value to the existing position
value. So in the above example, we would compute a delta of negative 1 for node D and
positive 1 for node G. The upshot of this is that
autoUpdateSiblingNodesOnDragonly works well if your position values are consecutive integers
- Returns:
- Current autoUpdateSiblingNodesOnDrag value. Default value is (see below)
-
setCanReturnOpenFolders
public ResultTree setCanReturnOpenFolders(boolean canReturnOpenFolders) throws IllegalStateException When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for thecanReturnOpenSubfoldersPropertywhen no value for that property is provided for a node.- Parameters:
canReturnOpenFolders- New canReturnOpenFolders value. Default value is false- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getCanReturnOpenFolders
public boolean getCanReturnOpenFolders()When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse, this property specifies the default value assumed for thecanReturnOpenSubfoldersPropertywhen no value for that property is provided for a node.- Returns:
- Current canReturnOpenFolders value. Default value is false
-
setCanReturnOpenSubfoldersProperty
public ResultTree setCanReturnOpenSubfoldersProperty(String canReturnOpenSubfoldersProperty) throws IllegalStateException When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse,canReturnOpenSubfoldersPropertymay be set on any folder to indicate whether child folders might be returned by the server already open. If the property is set to false on a folder then subfolders of that folder are never allowed to be returned already open. This enables the paging mechanism to be more efficient in the amount of data that it requests from the server.For example, setting the
canReturnOpenSubfoldersPropertyvalue tofalseon a node is appropriate if the server-side code determines that the the node's children consist of entirely leaf nodes.- Parameters:
canReturnOpenSubfoldersProperty- New canReturnOpenSubfoldersProperty value. Default value is "canReturnOpenSubfolders"- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
-
getCanReturnOpenSubfoldersProperty
When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse,canReturnOpenSubfoldersPropertymay be set on any folder to indicate whether child folders might be returned by the server already open. If the property is set to false on a folder then subfolders of that folder are never allowed to be returned already open. This enables the paging mechanism to be more efficient in the amount of data that it requests from the server.For example, setting the
canReturnOpenSubfoldersPropertyvalue tofalseon a node is appropriate if the server-side code determines that the the node's children consist of entirely leaf nodes.- Returns:
- Current canReturnOpenSubfoldersProperty value. Default value is "canReturnOpenSubfolders"
- See Also:
-
setChildCountProperty
When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse,childCountPropertymust be set for any folders that include only a partial list of children. For a deeper discussion see the Paging large sets of children section of theTreeDataBindingoverview.- Parameters:
childCountProperty- New childCountProperty value. Default value is "childCount"- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
-
getChildCountProperty
When usingfetchMode:"paged"and providing multiple levels of the tree in one DSResponse,childCountPropertymust be set for any folders that include only a partial list of children. For a deeper discussion see the Paging large sets of children section of theTreeDataBindingoverview.- Returns:
- Current childCountProperty value. Default value is "childCount"
- See Also:
-
setCriteria
The filter criteria to use when fetching rows. For usage seesetCriteria().
If this method is called after the component has been drawn/initialized: Set the filter criteria to use when fetching rows.Depending on the result of
compareCriteria()and setting forfetchMode, setting criteria may cause a trip to the server to get a new set of nodes, or may simply cause already-fetched nodes to be re-filtered according to the new criteria.For a basic overview on when server fetches are generally performed, see
fetchMode. However, this is not the final determination of when server fetches occur. Criteria can be split into local criteria and server criteria by specifyingserverFilterFields. Thus, even when using fetchMode:"local" a new server fetch will occur if the server criteria changes. For details on how the criteria is split, seeDataSource.splitCriteria().Note: if criteria is being split to retrieve server criteria portion and the criteria is an
AdvancedCriteria, the criteria must consist of a single "and" operator and one or more simple criteria below it. No other logical operators may be used. In other words, theAdvancedCriteriaprovided must be exactly representable by a simple criteria.- Parameters:
criteria- the filter criteria. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls
-
getCriteria
The filter criteria to use when fetching rows. For usage seesetCriteria().- Returns:
- Current criteria value. Default value is null
-
setData
Optional initial data for the tree. If thefetchModeis"basic"or"local"then the format of this data is exactly the sameparentId-linked list of tree nodes as documented onTree.data(when themodelTypeis set to"parent"). If thefetchModeis"paged"then the format is extended to allow thechildCountPropertyto be set on folder nodes.Providing an initial set of nodes in this way does not affect the behavior of the ResultTree in its loading of unloaded folders. An equivalent result is achieved if the first fetch from the server returns this same data.
If
fetchModeis"paged"then you may make folder-by-folder choices as to whether to use paging for the childen of each folder. If you would like to use paging in a folder then you may include a partial list of that folder's children with the data, provided that you set thechildCountPropertyto the total number of children. Otherwise you will need to include either all children of the folder or none of the children. Open folders without any children provided will cause immediate, new fetches for the children, as usual.Because the initial data is treated exactly as though it were returned from the tree's first server fetch, the order of the initial data must match the initial sort order of the TreeGrid displaying the data or, if no such sort is specified, the native storage order on the server. For example, consider initial data containing
nrecords having theparentId"X", meaning they are all in the same folder. Thesenrecords are the records at indices0through(n - 1)that are stored on the server under the parent node. If thechildCountPropertyset on the parent node indicates that there arem > ntotal rows under the parent node then the records at indicesnto(m - 1)will be fetched from the server as the user scrolls the additional rows into view.Note : This is an advanced setting
- Overrides:
setDatain classTree- Parameters:
data- New data value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
-
getData
Optional initial data for the tree. If thefetchModeis"basic"or"local"then the format of this data is exactly the sameparentId-linked list of tree nodes as documented onTree.data(when themodelTypeis set to"parent"). If thefetchModeis"paged"then the format is extended to allow thechildCountPropertyto be set on folder nodes.Providing an initial set of nodes in this way does not affect the behavior of the ResultTree in its loading of unloaded folders. An equivalent result is achieved if the first fetch from the server returns this same data.
If
fetchModeis"paged"then you may make folder-by-folder choices as to whether to use paging for the childen of each folder. If you would like to use paging in a folder then you may include a partial list of that folder's children with the data, provided that you set thechildCountPropertyto the total number of children. Otherwise you will need to include either all children of the folder or none of the children. Open folders without any children provided will cause immediate, new fetches for the children, as usual.Because the initial data is treated exactly as though it were returned from the tree's first server fetch, the order of the initial data must match the initial sort order of the TreeGrid displaying the data or, if no such sort is specified, the native storage order on the server. For example, consider initial data containing
nrecords having theparentId"X", meaning they are all in the same folder. Thesenrecords are the records at indices0through(n - 1)that are stored on the server under the parent node. If thechildCountPropertyset on the parent node indicates that there arem > ntotal rows under the parent node then the records at indicesnto(m - 1)will be fetched from the server as the user scrolls the additional rows into view. -
setDefaultIsFolder
Controls whether nodes are assumed to be folders or leaves by default.Nodes that have children or have the
isFolderPropertyset to true will always be considered folders. Other nodes will be considered folders or leaves by default according to this setting.If
defaultIsFolderis unset, the ResultTree will automatically set it to match the value ofloadDataOnDemand. This means that, when using folder-by-folder load on demand (loadDataOnDemand:true), by default a newly loaded node will be considered to be a folder that has not loaded its children yet.When not using folder-by-folder load on demand, by default a newly loaded node is considered a leaf. If you set
defaultIsFolder:trueexplicitly, by default a newly loaded node is considered to be a folder with no children.See
Tree.isFolder()for details on how to explicitly mark nodes as folders or leaves.- Overrides:
setDefaultIsFolderin classTree- Parameters:
defaultIsFolder- New defaultIsFolder value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
-
getDefaultIsFolder
Controls whether nodes are assumed to be folders or leaves by default.Nodes that have children or have the
isFolderPropertyset to true will always be considered folders. Other nodes will be considered folders or leaves by default according to this setting.If
defaultIsFolderis unset, the ResultTree will automatically set it to match the value ofloadDataOnDemand. This means that, when using folder-by-folder load on demand (loadDataOnDemand:true), by default a newly loaded node will be considered to be a folder that has not loaded its children yet.When not using folder-by-folder load on demand, by default a newly loaded node is considered a leaf. If you set
defaultIsFolder:trueexplicitly, by default a newly loaded node is considered to be a folder with no children.See
Tree.isFolder()for details on how to explicitly mark nodes as folders or leaves.- Overrides:
getDefaultIsFolderin classTree- Returns:
- Current defaultIsFolder value. Default value is null
- See Also:
-
setDefaultNewNodesToRoot
This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.If set to
true, when a new node is added to this dataSource viaDataSource.addData(), with no explicit parentId, the node will be added as a child of the root node of this result tree. Otherwise it will be ignored.Similar logic applies to
updated nodes- if this property is true and the parentId of an updated node is cleared, it will be moved to become a child of root, otherwise it will be dropped from the tree.Note : This is an advanced setting
- Parameters:
defaultNewNodesToRoot- New defaultNewNodesToRoot value. Default value is false- Returns:
ResultTreeinstance, for chaining setter calls
-
getDefaultNewNodesToRoot
This attribute governs how to handle cache-synch when a new node is added to this dataSource with no explicit parentId.If set to
true, when a new node is added to this dataSource viaDataSource.addData(), with no explicit parentId, the node will be added as a child of the root node of this result tree. Otherwise it will be ignored.Similar logic applies to
updated nodes- if this property is true and the parentId of an updated node is cleared, it will be moved to become a child of root, otherwise it will be dropped from the tree.- Returns:
- Current defaultNewNodesToRoot value. Default value is false
-
setDisableCacheSync
By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes. Set this flag to true to disable this behavior.Note : This is an advanced setting
- Parameters:
disableCacheSync- New disableCacheSync value. Default value is false- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getDisableCacheSync
By default when the data of this ResultTree's dataSource is modified, the ResultTree will be updated to display these changes. Set this flag to true to disable this behavior.- Returns:
- Current disableCacheSync value. Default value is false
-
setDiscardParentlessNodes
public ResultTree setDiscardParentlessNodes(Boolean discardParentlessNodes) throws IllegalStateException When data is loaded from the server, should nodes with an explicit value for theTree.parentIdFieldwhich doesn't map to a valid parent node be dropped? If set to false, forTreeGrid.loadDataOnDemand:false trees, parentless nodes will be added as children of the root node - forTreeGrid.loadDataOnDemand:true, they will be added as children of the folder currently requesting children.This effectively allows nodes to be loaded into the current (or root) folder without needing an explicit
parentIdField valuethat matches the folder's ID orrootValuefor the resultTree.Note: For
loadDataOnDemand:falsetrees, if this property is unset at init time, it will default totrueif an explicitrootNodehas been specified. This ensures that if the data tree retrieved from the server includes ancestors of the desired root-node we don't display them. Otherwise this property always defaults to false.Note : This is an advanced setting
- Overrides:
setDiscardParentlessNodesin classTree- Parameters:
discardParentlessNodes- New discardParentlessNodes value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getDiscardParentlessNodes
When data is loaded from the server, should nodes with an explicit value for theTree.parentIdFieldwhich doesn't map to a valid parent node be dropped? If set to false, forTreeGrid.loadDataOnDemand:false trees, parentless nodes will be added as children of the root node - forTreeGrid.loadDataOnDemand:true, they will be added as children of the folder currently requesting children.This effectively allows nodes to be loaded into the current (or root) folder without needing an explicit
parentIdField valuethat matches the folder's ID orrootValuefor the resultTree.Note: For
loadDataOnDemand:falsetrees, if this property is unset at init time, it will default totrueif an explicitrootNodehas been specified. This ensures that if the data tree retrieved from the server includes ancestors of the desired root-node we don't display them. Otherwise this property always defaults to false.- Overrides:
getDiscardParentlessNodesin classTree- Returns:
- Current discardParentlessNodes value. Default value is null
-
setFetchMode
Mode of fetching records from server.fetchMode:"local" implies that local filtering will always be performed. See
keepParentsOnFilterfor additional filtering details.fetchMode:"basic" or "paged" implies that if search criteria change, the entire tree will be discarded and re-fetched from the server. When retrieving the replacement tree data, the default behavior will be to preserve the
openStatefor any nodes that the server returns which were previously opened by the user. Note that this implies that ifloadDataOnDemandis enabled and the server returns only root-level nodes, open state will be preserved only for root-level nodes, and children of open root-level nodes will be immediately fetched from the server if they are not included in the server's initial response.fetchMode:"paged" enables paging for nodes that have very large numbers of children. Whenever the children of a folder are loaded, the
resultTreewill setDSRequest.startRowandendRowwhen requesting children from the DataSource, and will manage loading of further children on demand, similar to how aResultSetmanages paging for lists. For a deeper discussion see the Paging large sets of children section of theTreeDataBindingoverview.- Parameters:
fetchMode- New fetchMode value. Default value is "basic"- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
-
getFetchMode
Mode of fetching records from server.fetchMode:"local" implies that local filtering will always be performed. See
keepParentsOnFilterfor additional filtering details.fetchMode:"basic" or "paged" implies that if search criteria change, the entire tree will be discarded and re-fetched from the server. When retrieving the replacement tree data, the default behavior will be to preserve the
openStatefor any nodes that the server returns which were previously opened by the user. Note that this implies that ifloadDataOnDemandis enabled and the server returns only root-level nodes, open state will be preserved only for root-level nodes, and children of open root-level nodes will be immediately fetched from the server if they are not included in the server's initial response.fetchMode:"paged" enables paging for nodes that have very large numbers of children. Whenever the children of a folder are loaded, the
resultTreewill setDSRequest.startRowandendRowwhen requesting children from the DataSource, and will manage loading of further children on demand, similar to how aResultSetmanages paging for lists. For a deeper discussion see the Paging large sets of children section of theTreeDataBindingoverview.- Returns:
- Current fetchMode value. Default value is "basic"
- See Also:
-
setFirstPositionValue
IfautoUpdateSiblingNodesOnDragis in force, this is the value we will use to auto-update the position of a node when we cannot derive that value from the existing value of a neighbor. This happens when a node is dropped into the very first position below a parent (including the special case of the parent being previously empty)- Parameters:
firstPositionValue- New firstPositionValue value. Default value is 1- Returns:
ResultTreeinstance, for chaining setter calls
-
getFirstPositionValue
IfautoUpdateSiblingNodesOnDragis in force, this is the value we will use to auto-update the position of a node when we cannot derive that value from the existing value of a neighbor. This happens when a node is dropped into the very first position below a parent (including the special case of the parent being previously empty)- Returns:
- Current firstPositionValue value. Default value is 1
-
setImplicitCriteria
Criteria that are never shown to or edited by the user and are cumulative with any criteria provided viaDataBoundComponent.initialCriteria,setCriteria()etc.- Parameters:
implicitCriteria- New implicitCriteria value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls
-
getImplicitCriteria
Criteria that are never shown to or edited by the user and are cumulative with any criteria provided viaDataBoundComponent.initialCriteria,setCriteria()etc.- Returns:
- Current implicitCriteria value. Default value is null
-
setKeepParentsOnFilter
If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria. If not set, filtering will exclude parent nodes not matching the criteria, and all nodes below them in the tree.ResultTrees will default to If some criteria must be sent to the server in order to produce a valid tree of data, butfetchMode:"local"wheneverkeepParentsOnFilteris true, unless fetchMode was explicitly set to "paged" (see below). This allows the filtering logic to fetch a complete tree of nodes from the DataSource (or if loadDataOnDemand:true, a complete set of nodes under a given parent) and then filter the resulting data locally on the client.This means that the server does not need to implement special tree filtering logic to support looking up nodes that match the specified criteria as well as ancestor nodes that may not.
keepParentsOnFilteris also required, theserverFilterFieldsattribute may be used to specify a list of field names that will be sent to the server whenever they are present in the criteria. Note that for the subset of criteria applied to these fields,keepParentsInFilterbehavior will not occur without custom logic in the DataSource fetch operation.If
FetchModeis explicitly set to"paged", it is not possible to implementkeepParentsOnFilter, either by local filteringor with the automatic client-driven handling mentioned below . Support forkeepParentsOnFilterfor a paged ResultTree therefore also requires custom logic in the DataSource fetch operation. To support this a developer must ensure that their fetch operation returns the appropriate set of nodes - all nodes that match the specified criteria plus their ancestor nodes even if they do not match the specified criteria.keepParentsOnFilter with load-on-demand trees
The combination ofkeepParentsOnFilterandloadDataOnDemandpresents additional difficulties that require special handling. The problem is that in order to determine even the top-level folders, you have to examine every node in the entire tree. For example, say there is one top-level folder that has thousands of folders and nodes underneath it, and there is just one leaf node, 6 levels deep, that matches the filter criteria. You have to find out about that node, because it implies the top-level folder must be retained.So the server basically has to examine every node in the dataset to determine even what shows up at the top level of the tree. If it does not do this, parent nodes that don't match the filter criteria will be excluded from the tree, with the upshot that the child nodes that do match the criteria will be inaccessible because nodes in load-on-demand trees are only loaded when their parent node is opened
By default, Smart GWT solves this with a client-driven implementation of this special handling. This algorithm involves finding the nodes that match the filter criteria - which we term matching leaves - and then recursively travelling back up the tree, determining the ancestors of the matching leaves - the so-called dangling parents. When we have traversed all the way back to the root node from every matching leaf, we have recorded every dangling parent and have what we term the skeleton of the tree. The skeleton is then added to fetch criteria whenever a load-on-demand fetch request is made, ensuring that we fetch both dangling parents and matching leaves.
There are three ways this recursive traversal can be implemented:
- For dataSources that
support dynamic tree joins, we use theadditionalOutputsfeature to declare self-joins that fetch multiple levels of parent in one query (the number of levels is configurable, seematchingLeafJoinDepth). Of Smart GWT's built-in DataSource types, only SQLDataSource is currently capable of this approach - For server-side dataSources that do
not support self-joins, we combine individual single-level fetches into a
queue, usingfieldValueExpressionswithresponseData "allRecords"so that each fetch in the queue uses the output of the previous fetch as its criteria (so the first fetch returns the parents of the matching nodes, the second fetch returns the parents of those nodes, and so on). Again, the number of fetches per queue can be configured with thematchingLeafJoinDepthproperty. This approach works for any server-side DataSource implementation, including your own custom implementations - For
client-sidedataSources, which support neither self-joins not queueing, the algorithm simply makes as many single-level requests as necessary to build the entire skeleton. Note, this is exactly what would happen with previously-mentioned queueing approach, if you setmatchingLeafJoinDepthto 1
keepParentsOnFilteron load-on-demand trees, seeserverKeepParentsOnFilter- Parameters:
keepParentsOnFilter- New keepParentsOnFilter value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
- For dataSources that
-
getKeepParentsOnFilter
If set, tree-based filtering is performed such that parent nodes are kept as long as they have children that match the filter criteria, even if the parents themselves do not match the filter criteria. If not set, filtering will exclude parent nodes not matching the criteria, and all nodes below them in the tree.ResultTrees will default to If some criteria must be sent to the server in order to produce a valid tree of data, butfetchMode:"local"wheneverkeepParentsOnFilteris true, unless fetchMode was explicitly set to "paged" (see below). This allows the filtering logic to fetch a complete tree of nodes from the DataSource (or if loadDataOnDemand:true, a complete set of nodes under a given parent) and then filter the resulting data locally on the client.This means that the server does not need to implement special tree filtering logic to support looking up nodes that match the specified criteria as well as ancestor nodes that may not.
keepParentsOnFilteris also required, theserverFilterFieldsattribute may be used to specify a list of field names that will be sent to the server whenever they are present in the criteria. Note that for the subset of criteria applied to these fields,keepParentsInFilterbehavior will not occur without custom logic in the DataSource fetch operation.If
FetchModeis explicitly set to"paged", it is not possible to implementkeepParentsOnFilter, either by local filteringor with the automatic client-driven handling mentioned below . Support forkeepParentsOnFilterfor a paged ResultTree therefore also requires custom logic in the DataSource fetch operation. To support this a developer must ensure that their fetch operation returns the appropriate set of nodes - all nodes that match the specified criteria plus their ancestor nodes even if they do not match the specified criteria.keepParentsOnFilter with load-on-demand trees
The combination ofkeepParentsOnFilterandloadDataOnDemandpresents additional difficulties that require special handling. The problem is that in order to determine even the top-level folders, you have to examine every node in the entire tree. For example, say there is one top-level folder that has thousands of folders and nodes underneath it, and there is just one leaf node, 6 levels deep, that matches the filter criteria. You have to find out about that node, because it implies the top-level folder must be retained.So the server basically has to examine every node in the dataset to determine even what shows up at the top level of the tree. If it does not do this, parent nodes that don't match the filter criteria will be excluded from the tree, with the upshot that the child nodes that do match the criteria will be inaccessible because nodes in load-on-demand trees are only loaded when their parent node is opened
By default, Smart GWT solves this with a client-driven implementation of this special handling. This algorithm involves finding the nodes that match the filter criteria - which we term matching leaves - and then recursively travelling back up the tree, determining the ancestors of the matching leaves - the so-called dangling parents. When we have traversed all the way back to the root node from every matching leaf, we have recorded every dangling parent and have what we term the skeleton of the tree. The skeleton is then added to fetch criteria whenever a load-on-demand fetch request is made, ensuring that we fetch both dangling parents and matching leaves.
There are three ways this recursive traversal can be implemented:
- For dataSources that
support dynamic tree joins, we use theadditionalOutputsfeature to declare self-joins that fetch multiple levels of parent in one query (the number of levels is configurable, seematchingLeafJoinDepth). Of Smart GWT's built-in DataSource types, only SQLDataSource is currently capable of this approach - For server-side dataSources that do
not support self-joins, we combine individual single-level fetches into a
queue, usingfieldValueExpressionswithresponseData "allRecords"so that each fetch in the queue uses the output of the previous fetch as its criteria (so the first fetch returns the parents of the matching nodes, the second fetch returns the parents of those nodes, and so on). Again, the number of fetches per queue can be configured with thematchingLeafJoinDepthproperty. This approach works for any server-side DataSource implementation, including your own custom implementations - For
client-sidedataSources, which support neither self-joins not queueing, the algorithm simply makes as many single-level requests as necessary to build the entire skeleton. Note, this is exactly what would happen with previously-mentioned queueing approach, if you setmatchingLeafJoinDepthto 1
keepParentsOnFilteron load-on-demand trees, seeserverKeepParentsOnFilter- Returns:
- Current keepParentsOnFilter value. Default value is null
- See Also:
- For dataSources that
-
setKeepParentsOnFilterMaxNodes
When a tree specifies the combination ofkeepParentsOnFilterandloadDataOnDemand, Smart GWT by default automatically fetches the "skeleton" of the filtered tree - see thekeepParentsOnFilteroverview for details, including the definition of "skeleton" and other relevant terminologyA problem can arise with this approach if the user enters overly inclusive filter criteria. For example, say you have a 200,000 row dataset and the user chooses to apply a filter of "a". Chances are that is going to include the majority of the nodes in the tree, which would be OK because this is a load-on-demand tree. However, because we will build, cache and then pass around the list of id's of the dangling parents, this may become a performance issue. A lot depends on the nature of your data - this will be much less of an issue for shallow trees with lots of leaf nodes relative to parents, compared to deep trees with a lot of dangling parents to record.
If the user tries to filter the TreeGrid such that there are more matching nodes than is allowed by this setting, the system will truncate the fetch and show the warning message defined in
keepParentsOnFilterMaxNodesExceededMessage. Since the cached node-list is derived from bottom to top, this truncation of the fetch process will usually mean we have not yet derived any top-level nodes. This in turn means that the tree will appear to be empty.Setting this property to a suitable value for your specific use case is an application tuning exercise, finding the right balance between usability and performance. To remove the node limit altogether, set this property to -1. However, if you have a load-on-demand tree over a large dataset, we do not recommend that you remove the limit completely, as it can lead to serious problems on both the client and server, as the application tries to cope with criteria that contains huge numbers of id's.
- Parameters:
keepParentsOnFilterMaxNodes- New keepParentsOnFilterMaxNodes value. Default value is 8000- Returns:
ResultTreeinstance, for chaining setter calls
-
getKeepParentsOnFilterMaxNodes
When a tree specifies the combination ofkeepParentsOnFilterandloadDataOnDemand, Smart GWT by default automatically fetches the "skeleton" of the filtered tree - see thekeepParentsOnFilteroverview for details, including the definition of "skeleton" and other relevant terminologyA problem can arise with this approach if the user enters overly inclusive filter criteria. For example, say you have a 200,000 row dataset and the user chooses to apply a filter of "a". Chances are that is going to include the majority of the nodes in the tree, which would be OK because this is a load-on-demand tree. However, because we will build, cache and then pass around the list of id's of the dangling parents, this may become a performance issue. A lot depends on the nature of your data - this will be much less of an issue for shallow trees with lots of leaf nodes relative to parents, compared to deep trees with a lot of dangling parents to record.
If the user tries to filter the TreeGrid such that there are more matching nodes than is allowed by this setting, the system will truncate the fetch and show the warning message defined in
keepParentsOnFilterMaxNodesExceededMessage. Since the cached node-list is derived from bottom to top, this truncation of the fetch process will usually mean we have not yet derived any top-level nodes. This in turn means that the tree will appear to be empty.Setting this property to a suitable value for your specific use case is an application tuning exercise, finding the right balance between usability and performance. To remove the node limit altogether, set this property to -1. However, if you have a load-on-demand tree over a large dataset, we do not recommend that you remove the limit completely, as it can lead to serious problems on both the client and server, as the application tries to cope with criteria that contains huge numbers of id's.
- Returns:
- Current keepParentsOnFilterMaxNodes value. Default value is 8000
-
setLinkDataAddOperation
TheoperationIdthisResultTreeshould use when performing add operations on itslinkDataSource. Has no effect if this is not amulti-link tree.Note, this property wll be used by internal update operations when you drag-move or drag-reparent nodes in a multi-link tree. Do not use it when adding records from application code by directly calling
addData()on thelinkDataSource; instead just use the regularoperationIdproperty in your add request. Also note, because this property is intended to allow your code to influence the operationId used by internal methods, and those methods never directly update link data (moved and re-parented links are always removed and then re-added), there is no correspondinglinkDataUpdateOperationproperty.- Parameters:
linkDataAddOperation- New linkDataAddOperation value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls
-
getLinkDataAddOperation
TheoperationIdthisResultTreeshould use when performing add operations on itslinkDataSource. Has no effect if this is not amulti-link tree.Note, this property wll be used by internal update operations when you drag-move or drag-reparent nodes in a multi-link tree. Do not use it when adding records from application code by directly calling
addData()on thelinkDataSource; instead just use the regularoperationIdproperty in your add request. Also note, because this property is intended to allow your code to influence the operationId used by internal methods, and those methods never directly update link data (moved and re-parented links are always removed and then re-added), there is no correspondinglinkDataUpdateOperationproperty.- Returns:
- Current linkDataAddOperation value. Default value is null
-
setLinkDataFetchMode
public ResultTree setLinkDataFetchMode(LinkDataFetchMode linkDataFetchMode) throws IllegalStateException The fetch mode for this tree's link data; ignored if this is not amulti-link tree- Parameters:
linkDataFetchMode- New linkDataFetchMode value. Default value is "separate"- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getLinkDataFetchMode
The fetch mode for this tree's link data; ignored if this is not amulti-link tree- Returns:
- Current linkDataFetchMode value. Default value is "separate"
-
setLinkDataFetchOperation
TheoperationIdthisResultTreeshould use when performing fetch operations on itslinkDataSource. Has no effect if this is not amulti-link treeNote, this value can be overridden by
DSRequest.linkDataFetchOperationwhen callingfetchData()on the component (e.g.TreeGrid.fetchData) directly from application code.- Parameters:
linkDataFetchOperation- New linkDataFetchOperation value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls
-
getLinkDataFetchOperation
TheoperationIdthisResultTreeshould use when performing fetch operations on itslinkDataSource. Has no effect if this is not amulti-link treeNote, this value can be overridden by
DSRequest.linkDataFetchOperationwhen callingfetchData()on the component (e.g.TreeGrid.fetchData) directly from application code.- Returns:
- Current linkDataFetchOperation value. Default value is null
-
setLinkDataRemoveOperation
TheoperationIdthisResultTreeshould use when performing remove operations on itslinkDataSource. Has no effect if this is not amulti-link tree.See
linkDataAddOperationfor more information on how this property is intended to be used.- Parameters:
linkDataRemoveOperation- New linkDataRemoveOperation value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls
-
getLinkDataRemoveOperation
TheoperationIdthisResultTreeshould use when performing remove operations on itslinkDataSource. Has no effect if this is not amulti-link tree.See
linkDataAddOperationfor more information on how this property is intended to be used.- Returns:
- Current linkDataRemoveOperation value. Default value is null
-
setLinkDataSource
This property allows you to specify the dataSource to be used for fetching link information in a databound multilink tree. A multilink tree is one where the same node is allowed to appear in multiple places in the tree, and it is achieved by providing the node data and the link data separately. Nodes are provided via the normaldataSource;linkDataSourceis only used for fetching and updating link information.The
linkDataSourceis an ordinaryDataSourcethat you implement just like any other. However, for correct operation as alinkDataSource, it must have the following:- A
primaryKey field. Like any dataSource, alinkDataSourceis not fully functional without aprimaryKeyfield - A field named the same as the
Tree.parentIdField - A field named the same as the
Tree.idField - Optionally, a field named the same as the
Tree.linkPositionField - Fields for other values you may wish to store with the link, if any
Providing node data and link data
Consider a structure for the components of a bicycle, greatly simplified:Frame / \ Wheel Wheel / \ / \ Hub Tire Hub TireHere, the two wheels are the same assembly, so really it should look like this:Frame | | Wheel / \ Hub TireNormal Smart GWT trees cannot model this arrangement accurately because this is not really a tree, it is a graph; trees do not contain multiple paths to a given node. The only way to handle this arrangement of nodes in a formal tree would be to make two copies of the "Wheel" node, at which point they are no longer the same thing. Either way, in aTreeGrid, we would have to visualise it like this:Frame Wheel Hub Tire Wheel Hub TireBut if we use copies so that the the two wheels are no longer the same thing, changing one of them will no longer change the other, which is a fundamental problem because in this scenario, the two wheels really are the same thing. Now, changing the name of the "Hub" in one "Wheel" would not change it in the other; adding a "Spokes" node to the second item would not also add it to the first. Drag-reordering child nodes in one "Wheel" would not re-order them in the other. All of these things are incorrect, because the two wheels are the same thing.Multilink trees provide a way to handle this arrangement without physical copying of the duplicate nodes, preserving the sameness of them and thus fixing all the problems described above.
The node data for the above tree, simplified, would be a flat list something like this:
[ { id: 1, description: "Frame" }, { id: 2, description: "Wheel" }, { id: 3, description: "Hub" }, { id: 4, description: "Tire" } ]The link data would look like this:[ { linkId: 1, parentId: 1, id: 2, position: 1 }, { linkId: 2, parentId: 2, id: 3, position: 1 }, { linkId: 3, parentId: 2, id: 4, position: 2 }, { linkId: 4, parentId: 1, id: 2, position: 2 } ]Or, if you were usinglinkDataFetchMode"single", you would combine the node and link data into a single dataset like this:[ { id: 1, position: 0, description: "Frame" }, { parentId: 1, id: 2, position: 1, description: "Wheel", linkId: 1 }, { parentId: 2, id: 3, position: 1, description: "Hub", linkId: 2 }, { parentId: 2, id: 4, position: 2, description: "Tire", linkId: 3 }, { parentId: 1, id: 2, position: 2, description: "Wheel", linkId: 4 } ]NOTE: It is also possible to create an unbound multilink tree - see
Tree.linkData.- Parameters:
linkDataSource- New linkDataSource value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
- A
-
getLinkDataSource
This property allows you to specify the dataSource to be used for fetching link information in a databound multilink tree. A multilink tree is one where the same node is allowed to appear in multiple places in the tree, and it is achieved by providing the node data and the link data separately. Nodes are provided via the normaldataSource;linkDataSourceis only used for fetching and updating link information.The
linkDataSourceis an ordinaryDataSourcethat you implement just like any other. However, for correct operation as alinkDataSource, it must have the following:- A
primaryKey field. Like any dataSource, alinkDataSourceis not fully functional without aprimaryKeyfield - A field named the same as the
Tree.parentIdField - A field named the same as the
Tree.idField - Optionally, a field named the same as the
Tree.linkPositionField - Fields for other values you may wish to store with the link, if any
Providing node data and link data
Consider a structure for the components of a bicycle, greatly simplified:Frame / \ Wheel Wheel / \ / \ Hub Tire Hub TireHere, the two wheels are the same assembly, so really it should look like this:Frame | | Wheel / \ Hub TireNormal Smart GWT trees cannot model this arrangement accurately because this is not really a tree, it is a graph; trees do not contain multiple paths to a given node. The only way to handle this arrangement of nodes in a formal tree would be to make two copies of the "Wheel" node, at which point they are no longer the same thing. Either way, in aTreeGrid, we would have to visualise it like this:Frame Wheel Hub Tire Wheel Hub TireBut if we use copies so that the the two wheels are no longer the same thing, changing one of them will no longer change the other, which is a fundamental problem because in this scenario, the two wheels really are the same thing. Now, changing the name of the "Hub" in one "Wheel" would not change it in the other; adding a "Spokes" node to the second item would not also add it to the first. Drag-reordering child nodes in one "Wheel" would not re-order them in the other. All of these things are incorrect, because the two wheels are the same thing.Multilink trees provide a way to handle this arrangement without physical copying of the duplicate nodes, preserving the sameness of them and thus fixing all the problems described above.
The node data for the above tree, simplified, would be a flat list something like this:
[ { id: 1, description: "Frame" }, { id: 2, description: "Wheel" }, { id: 3, description: "Hub" }, { id: 4, description: "Tire" } ]The link data would look like this:[ { linkId: 1, parentId: 1, id: 2, position: 1 }, { linkId: 2, parentId: 2, id: 3, position: 1 }, { linkId: 3, parentId: 2, id: 4, position: 2 }, { linkId: 4, parentId: 1, id: 2, position: 2 } ]Or, if you were usinglinkDataFetchMode"single", you would combine the node and link data into a single dataset like this:[ { id: 1, position: 0, description: "Frame" }, { parentId: 1, id: 2, position: 1, description: "Wheel", linkId: 1 }, { parentId: 2, id: 3, position: 1, description: "Hub", linkId: 2 }, { parentId: 2, id: 4, position: 2, description: "Tire", linkId: 3 }, { parentId: 1, id: 2, position: 2, description: "Wheel", linkId: 4 } ]NOTE: It is also possible to create an unbound multilink tree - see
Tree.linkData.- Returns:
- Current linkDataSource value. Default value is null
- A
-
setLinkDataSource
This property allows you to specify the dataSource to be used for fetching link information in a databound multilink tree. A multilink tree is one where the same node is allowed to appear in multiple places in the tree, and it is achieved by providing the node data and the link data separately. Nodes are provided via the normaldataSource;linkDataSourceis only used for fetching and updating link information.The
linkDataSourceis an ordinaryDataSourcethat you implement just like any other. However, for correct operation as alinkDataSource, it must have the following:- A
primaryKey field. Like any dataSource, alinkDataSourceis not fully functional without aprimaryKeyfield - A field named the same as the
Tree.parentIdField - A field named the same as the
Tree.idField - Optionally, a field named the same as the
Tree.linkPositionField - Fields for other values you may wish to store with the link, if any
Providing node data and link data
Consider a structure for the components of a bicycle, greatly simplified:Frame / \ Wheel Wheel / \ / \ Hub Tire Hub TireHere, the two wheels are the same assembly, so really it should look like this:Frame | | Wheel / \ Hub TireNormal Smart GWT trees cannot model this arrangement accurately because this is not really a tree, it is a graph; trees do not contain multiple paths to a given node. The only way to handle this arrangement of nodes in a formal tree would be to make two copies of the "Wheel" node, at which point they are no longer the same thing. Either way, in aTreeGrid, we would have to visualise it like this:Frame Wheel Hub Tire Wheel Hub TireBut if we use copies so that the the two wheels are no longer the same thing, changing one of them will no longer change the other, which is a fundamental problem because in this scenario, the two wheels really are the same thing. Now, changing the name of the "Hub" in one "Wheel" would not change it in the other; adding a "Spokes" node to the second item would not also add it to the first. Drag-reordering child nodes in one "Wheel" would not re-order them in the other. All of these things are incorrect, because the two wheels are the same thing.Multilink trees provide a way to handle this arrangement without physical copying of the duplicate nodes, preserving the sameness of them and thus fixing all the problems described above.
The node data for the above tree, simplified, would be a flat list something like this:
[ { id: 1, description: "Frame" }, { id: 2, description: "Wheel" }, { id: 3, description: "Hub" }, { id: 4, description: "Tire" } ]The link data would look like this:[ { linkId: 1, parentId: 1, id: 2, position: 1 }, { linkId: 2, parentId: 2, id: 3, position: 1 }, { linkId: 3, parentId: 2, id: 4, position: 2 }, { linkId: 4, parentId: 1, id: 2, position: 2 } ]Or, if you were usinglinkDataFetchMode"single", you would combine the node and link data into a single dataset like this:[ { id: 1, position: 0, description: "Frame" }, { parentId: 1, id: 2, position: 1, description: "Wheel", linkId: 1 }, { parentId: 2, id: 3, position: 1, description: "Hub", linkId: 2 }, { parentId: 2, id: 4, position: 2, description: "Tire", linkId: 3 }, { parentId: 1, id: 2, position: 2, description: "Wheel", linkId: 4 } ]NOTE: It is also possible to create an unbound multilink tree - see
Tree.linkData.- Parameters:
linkDataSource- New linkDataSource value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
- A
-
getLinkDataSourceAsString
This property allows you to specify the dataSource to be used for fetching link information in a databound multilink tree. A multilink tree is one where the same node is allowed to appear in multiple places in the tree, and it is achieved by providing the node data and the link data separately. Nodes are provided via the normaldataSource;linkDataSourceis only used for fetching and updating link information.The
linkDataSourceis an ordinaryDataSourcethat you implement just like any other. However, for correct operation as alinkDataSource, it must have the following:- A
primaryKey field. Like any dataSource, alinkDataSourceis not fully functional without aprimaryKeyfield - A field named the same as the
Tree.parentIdField - A field named the same as the
Tree.idField - Optionally, a field named the same as the
Tree.linkPositionField - Fields for other values you may wish to store with the link, if any
Providing node data and link data
Consider a structure for the components of a bicycle, greatly simplified:Frame / \ Wheel Wheel / \ / \ Hub Tire Hub TireHere, the two wheels are the same assembly, so really it should look like this:Frame | | Wheel / \ Hub TireNormal Smart GWT trees cannot model this arrangement accurately because this is not really a tree, it is a graph; trees do not contain multiple paths to a given node. The only way to handle this arrangement of nodes in a formal tree would be to make two copies of the "Wheel" node, at which point they are no longer the same thing. Either way, in aTreeGrid, we would have to visualise it like this:Frame Wheel Hub Tire Wheel Hub TireBut if we use copies so that the the two wheels are no longer the same thing, changing one of them will no longer change the other, which is a fundamental problem because in this scenario, the two wheels really are the same thing. Now, changing the name of the "Hub" in one "Wheel" would not change it in the other; adding a "Spokes" node to the second item would not also add it to the first. Drag-reordering child nodes in one "Wheel" would not re-order them in the other. All of these things are incorrect, because the two wheels are the same thing.Multilink trees provide a way to handle this arrangement without physical copying of the duplicate nodes, preserving the sameness of them and thus fixing all the problems described above.
The node data for the above tree, simplified, would be a flat list something like this:
[ { id: 1, description: "Frame" }, { id: 2, description: "Wheel" }, { id: 3, description: "Hub" }, { id: 4, description: "Tire" } ]The link data would look like this:[ { linkId: 1, parentId: 1, id: 2, position: 1 }, { linkId: 2, parentId: 2, id: 3, position: 1 }, { linkId: 3, parentId: 2, id: 4, position: 2 }, { linkId: 4, parentId: 1, id: 2, position: 2 } ]Or, if you were usinglinkDataFetchMode"single", you would combine the node and link data into a single dataset like this:[ { id: 1, position: 0, description: "Frame" }, { parentId: 1, id: 2, position: 1, description: "Wheel", linkId: 1 }, { parentId: 2, id: 3, position: 1, description: "Hub", linkId: 2 }, { parentId: 2, id: 4, position: 2, description: "Tire", linkId: 3 }, { parentId: 1, id: 2, position: 2, description: "Wheel", linkId: 4 } ]NOTE: It is also possible to create an unbound multilink tree - see
Tree.linkData.- Returns:
- Current linkDataSource value. Default value is null
- A
-
setLoadDataOnDemand
Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request? Must be true iffetchModeis "paged"See the
keepParentsOnFilteroverview for special considerations when filtering a load-on-demand tree- Parameters:
loadDataOnDemand- New loadDataOnDemand value. Default value is true- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
-
getLoadDataOnDemand
Does this resultTree load data incrementally as folders within the tree are opened, or is it all loaded in a single request? Must be true iffetchModeis "paged"See the
keepParentsOnFilteroverview for special considerations when filtering a load-on-demand tree- Returns:
- Current loadDataOnDemand value. Default value is true
- See Also:
-
setMatchingLeafJoinDepth
This property allows you to specify the number of ancestor levels Smart GWT attempts to retrieve with each request, when using the built-in support forkeepParentsOnFilteronloadDataOnDemandtrees. See thekeepParentsOnFilteroverview for details.- Parameters:
matchingLeafJoinDepth- New matchingLeafJoinDepth value. Default value is 3- Returns:
ResultTreeinstance, for chaining setter calls
-
getMatchingLeafJoinDepth
This property allows you to specify the number of ancestor levels Smart GWT attempts to retrieve with each request, when using the built-in support forkeepParentsOnFilteronloadDataOnDemandtrees. See thekeepParentsOnFilteroverview for details.- Returns:
- Current matchingLeafJoinDepth value. Default value is 3
-
setModelType
Selects the model used to construct the tree representation. SeeTreeModelTypefor the available options and their implications.If the "parent" modelType is used, you can provide the initial parent-linked data set to the tree via the
Tree.dataattribute. If the "children" modelType is used, you can provide the initial tree structure to the Tree via theTree.rootattribute.Note : This is an advanced setting
- Overrides:
setModelTypein classTree- Parameters:
modelType- New modelType value. Default value is "parent"- Returns:
ResultTreeinstance, for chaining setter calls- See Also:
-
getModelType
Selects the model used to construct the tree representation. SeeTreeModelTypefor the available options and their implications.If the "parent" modelType is used, you can provide the initial parent-linked data set to the tree via the
Tree.dataattribute. If the "children" modelType is used, you can provide the initial tree structure to the Tree via theTree.rootattribute.- Overrides:
getModelTypein classTree- Returns:
- Current modelType value. Default value is "parent"
- See Also:
-
setProgressiveLoading
Setsprogressive loading modefor this ResultTree. The ResultTree will copy this setting onto theDSRequests that it issues, overriding the OperationBinding- and DataSource-level settings, in cases where the use of progressive loading does not affect the correctness of the tree's paging algorithm.This setting is applied automatically by
DataBoundComponents that have their own explicit setting forprogressiveLoading.Note: This property only has an effect for
fetchMode:"paged"ResultTrees.- Parameters:
progressiveLoading- New progressiveLoading value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls- See Also:
-
getProgressiveLoading
Setsprogressive loading modefor this ResultTree. The ResultTree will copy this setting onto theDSRequests that it issues, overriding the OperationBinding- and DataSource-level settings, in cases where the use of progressive loading does not affect the correctness of the tree's paging algorithm.This setting is applied automatically by
DataBoundComponents that have their own explicit setting forprogressiveLoading.Note: This property only has an effect for
fetchMode:"paged"ResultTrees.- Returns:
- Current progressiveLoading value. Default value is null
- See Also:
-
setResultSize
How many tree nodes to retrieve at once from each large set of children in the tree.Applicable only with
fetchMode: "paged". When a paged ResultTree is asked for rows that have not yet been loaded, it will fetch adjacent rows that are likely to be required soon, in batches of this size.Note : This is an advanced setting
- Parameters:
resultSize- New resultSize value. Default value is 75- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
-
getResultSize
How many tree nodes to retrieve at once from each large set of children in the tree.Applicable only with
fetchMode: "paged". When a paged ResultTree is asked for rows that have not yet been loaded, it will fetch adjacent rows that are likely to be required soon, in batches of this size.- Returns:
- Current resultSize value. Default value is 75
- See Also:
-
setSendNullParentInLinkDataCriteria
public ResultTree setSendNullParentInLinkDataCriteria(Boolean sendNullParentInLinkDataCriteria) throws IllegalStateException Formulti-link trees only, should we send up theparentIdin fetch criteria if the criteria value is null? If false, we remove theparentIdfrom the criteria whenfetching link data, if the criteria value is null (as it will be by default when fetching the direct child nodes of the tree's root).Ignored for non-multiLink trees.
- Parameters:
sendNullParentInLinkDataCriteria- New sendNullParentInLinkDataCriteria value. Default value is true- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getSendNullParentInLinkDataCriteria
Formulti-link trees only, should we send up theparentIdin fetch criteria if the criteria value is null? If false, we remove theparentIdfrom the criteria whenfetching link data, if the criteria value is null (as it will be by default when fetching the direct child nodes of the tree's root).Ignored for non-multiLink trees.
- Returns:
- Current sendNullParentInLinkDataCriteria value. Default value is true
-
setServerFilterFields
ForfetchMode:"local"ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.This property may be used to ensure a dataSource receives the necessary criteria to populate a ResultTree's data, and also support
keepParentsOnFilter.Note that for some AdvancedCriteria it will not be possible to extract the subcriteria that apply to certain fields. See
DataSource.splitCriteria()for details on how serverFilterFields-applicable subcriteria are extracted from the specified criteria for the tree.- Parameters:
serverFilterFields- New serverFilterFields value. Default value is null- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getServerFilterFields
ForfetchMode:"local"ResultTrees, this property lists field names that will be sent to the server if they are present in the criteria.This property may be used to ensure a dataSource receives the necessary criteria to populate a ResultTree's data, and also support
keepParentsOnFilter.Note that for some AdvancedCriteria it will not be possible to extract the subcriteria that apply to certain fields. See
DataSource.splitCriteria()for details on how serverFilterFields-applicable subcriteria are extracted from the specified criteria for the tree.- Returns:
- Current serverFilterFields value. Default value is null
-
setServerKeepParentsOnFilter
If true, indicates that your own server code will handle the complexities associated with the combination ofkeepParentsOnFilterandloadDataOnDemand. If this flag is true and your server code does not handle those complexities, the results are undefined, but most likely you will simply exclude non-matching parents if your tree is load-on-demand, which effectively means that filtering will be broken.If this flag is not set, Smart GWT will use its own automatic client-driven algorithm to ensure that
keepParentsOnFilteris honored on load-on-demand trees. See thekeepParentsOnFilteroverview for details- Parameters:
serverKeepParentsOnFilter- New serverKeepParentsOnFilter value. Default value is See Below- Returns:
ResultTreeinstance, for chaining setter calls
-
getServerKeepParentsOnFilter
If true, indicates that your own server code will handle the complexities associated with the combination ofkeepParentsOnFilterandloadDataOnDemand. If this flag is true and your server code does not handle those complexities, the results are undefined, but most likely you will simply exclude non-matching parents if your tree is load-on-demand, which effectively means that filtering will be broken.If this flag is not set, Smart GWT will use its own automatic client-driven algorithm to ensure that
keepParentsOnFilteris honored on load-on-demand trees. See thekeepParentsOnFilteroverview for details- Returns:
- Current serverKeepParentsOnFilter value. Default value is See Below
-
setUpdateCacheFromRequest
public ResultTree setUpdateCacheFromRequest(Boolean updateCacheFromRequest) throws IllegalStateException When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, ifDSResponse.datais unset, should we integrate the submitted data values (from the request) into our data-set?Note : This is an advanced setting
- Parameters:
updateCacheFromRequest- New updateCacheFromRequest value. Default value is true- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getUpdateCacheFromRequest
When a successful Add, Update or Remove type operation fires on this ResultTree's dataSource, ifDSResponse.datais unset, should we integrate the submitted data values (from the request) into our data-set?- Returns:
- Current updateCacheFromRequest value. Default value is true
-
setUseSimpleCriteriaLOD
Whether or not we should skip promotion of a simple criteria to anAdvancedCriteriawhen sending theDSRequestto load the children of a node in aloadDataOnDemandorfetchMode:"paged"ResultTree. If theDSRequest.textMatchStyleis not "exact", we normally convert the simple criteria to anAdvancedCriteriafor correctness in matching the node name, but setting this property totruewill allow that to be skipped for backcompat with older releases.Note : This is an advanced setting
- Parameters:
useSimpleCriteriaLOD- New useSimpleCriteriaLOD value. Default value is false- Returns:
ResultTreeinstance, for chaining setter calls- See Also:
-
getUseSimpleCriteriaLOD
public boolean getUseSimpleCriteriaLOD()Whether or not we should skip promotion of a simple criteria to anAdvancedCriteriawhen sending theDSRequestto load the children of a node in aloadDataOnDemandorfetchMode:"paged"ResultTree. If theDSRequest.textMatchStyleis not "exact", we normally convert the simple criteria to anAdvancedCriteriafor correctness in matching the node name, but setting this property totruewill allow that to be skipped for backcompat with older releases.- Returns:
- Current useSimpleCriteriaLOD value. Default value is false
- See Also:
-
applyFilter
public Tree applyFilter(Tree tree, Criteria criteria, TreeFilterMode filterMode, DataSource dataSource) The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.Default behavior is to call
Tree.getFilteredTree()to obtain a new, filtered tree.Override this method or
Tree.getFilteredTree()to implement your own client-side filtering behavior. Note that the original tree should not be affected.- Parameters:
tree- the source tree to be filteredcriteria- the filter criteriafilterMode- mode to use for filteringdataSource- dataSource for filtering if the Tree does not already have one- Returns:
- the filtered tree (copy)
-
applyFilter
public Tree applyFilter(Tree tree, Criteria criteria, TreeFilterMode filterMode, DataSource dataSource, DSRequest requestProperties) The ResultTree will call applyFilter() when it needs to locally filter the tree using the current filter criteria.Default behavior is to call
Tree.getFilteredTree()to obtain a new, filtered tree.Override this method or
Tree.getFilteredTree()to implement your own client-side filtering behavior. Note that the original tree should not be affected.- Parameters:
tree- the source tree to be filteredcriteria- the filter criteriafilterMode- mode to use for filteringdataSource- dataSource for filtering if the Tree does not already have onerequestProperties- Request properties block. This allows developers to specify properties that would impact the filter such asDSRequest.textMatchStyle- Returns:
- the filtered tree (copy)
-
compareCriteria
Default behavior is to callDataSource.compareCriteria()to determine whether new criteria is equivalent to the old criteria (returns 0) or not.See
DataSource.compareCriteria()for a full explanation of the default behavior. TheCriteriaPolicyused is "dropOnChange".Override this method or
DataSource.compareCriteria()to implement your own client-side filtering behavior.- Parameters:
newCriteria- new filter criteriaoldCriteria- old filter criteria- Returns:
- 0 if the criteria are equivalent, -1 if the criteria are different
- See Also:
-
compareCriteria
Default behavior is to callDataSource.compareCriteria()to determine whether new criteria is equivalent to the old criteria (returns 0) or not.See
DataSource.compareCriteria()for a full explanation of the default behavior. TheCriteriaPolicyused is "dropOnChange".Override this method or
DataSource.compareCriteria()to implement your own client-side filtering behavior.- Parameters:
newCriteria- new filter criteriaoldCriteria- old filter criteriarequestProperties- dataSource request properties- Returns:
- 0 if the criteria are equivalent, -1 if the criteria are different
- See Also:
-
dataArrived
This callback fires whenever the resultTree receives new nodes from the server, after the new nodes have been integrated into the tree.- Parameters:
parentNode- The parentNode for which children were just loaded
-
get
Get the item in the openList at a particular position.- Overrides:
getin classRecordList- Parameters:
pos- position of the node to get- Returns:
- node at that position
-
getCombinedCriteria
- Returns:
- combined criteria
-
getCombinedCriteriaAsAdvancedCriteria
- Returns:
- combined criteria
-
getOpenState
Returns a snapshot of the current open state of this tree's data as aTreeGridOpenStateobject.This object can be passed to
setOpenState()orTreeGrid.setOpenState()to open the same set of folders within the tree's data (assuming the nodes are still present in the data).- Returns:
- current open state for the grid.
See
TreeGridOpenState - See Also:
-
getRange
Get a range of items from the open list- Overrides:
getRangein classRecordList- Parameters:
start- start positionend- end position (NOT inclusive)- Returns:
- list of nodes in the open list
-
invalidateCache
public void invalidateCache()Manually invalidate this ResultTree's cache.Generally a ResultTree will detect and incorporate updates to the DataSource that provides its records, but when this is not possible,
invalidateCache()allows manual cache invalidation.Components bound to this ResultTree will typically re-request the currently visible portion of the dataset, causing the ResultTree to re-fetch data from the server.
-
setChildren
Replaces the existing children of a parent node. This leaves the node in the loaded state (unless a partially loaded set of children is specified using the optionaltotalChildrenargument). The supplied array of children may be null or empty to indicate there are none, but if present must be in the standard format as would be sent from the server, as described byTreeDataBinding.In particular, note that for a
pagedResultTree, each child node:- :
- can
have nested children spcified under the
Tree.childrenProperty(but not viaTreeNode.id/TreeNode.parentIdlinking) - cannot be open unless it includes either a complete set of children, or partial set of children and a childCount
- Overrides:
setChildrenin classTree- Parameters:
parent- parent of childrennewChildren- children to be set- See Also:
- can
have nested children spcified under the
-
setChildren
Replaces the existing children of a parent node. This leaves the node in the loaded state (unless a partially loaded set of children is specified using the optionaltotalChildrenargument). The supplied array of children may be null or empty to indicate there are none, but if present must be in the standard format as would be sent from the server, as described byTreeDataBinding.In particular, note that for a
pagedResultTree, each child node:- :
- can
have nested children spcified under the
Tree.childrenProperty(but not viaTreeNode.id/TreeNode.parentIdlinking) - cannot be open unless it includes either a complete set of children, or partial set of children and a childCount
- Parameters:
parent- parent of childrennewChildren- children to be settotalChildren- number of total children (if not all have been provided as newChildren); only allowed if paging- See Also:
- can
have nested children spcified under the
-
setOpenState
Reset the set of open folders within this tree's data to match theTreeGridOpenStateobject passed in.Used to restore previous state retrieved from the tree by a call to
getOpenState().- Parameters:
openState- Object describing the desired set of open folders. SeeTreeGridOpenState- See Also:
-
unloadChildren
Deprecated.It's recommended that you instead useTree.reloadChildren()to reload the children of a folder, orTree.removeChildren()if you need to clear the cached children of a folder to add specific local data.Unload the children of a folder, returning the folder to the "unloaded" state.- Overrides:
unloadChildrenin classTree- Parameters:
node- folder in question
-
willFetchData
Will changing the criteria for this resultTree require fetching new data from the server or can the new criteria be satisfied from data already cached on the client?This method can be used to determine whether
TreeGrid.fetchData()orTreeGrid.filterData()will cause a server side fetch when passed a certain set of criteria.- Parameters:
newCriteria- new criteria to test.- Returns:
- true if server fetch would be required to satisfy new criteria.
-
setDefaultProperties
Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties set on the SmartGWT class instance passed to this function before its underlying SmartClient JS object was created. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.
- Parameters:
resultTreeProperties- properties that should be used as new defaults when instances of this class are created- See Also:
-
setDataSource
WhatDataSourceis this resultTree associated with?- Overrides:
setDataSourcein classTree- Parameters:
dataSource- dataSource Default value is null- Returns:
ResultTreeinstance, for chaining setter calls- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created- See Also:
-
getDataSource
WhatDataSourceis this resultTree associated with?- Overrides:
getDataSourcein classTree- Returns:
- DataSource
- See Also:
-
setRootNode
This attribute may be used to specify a root value for the parentIdField of this resultTree. This overrides the defaultrootValuefor this tree, allowing a component to navigate a tree starting at a specific node.May be overridden via
treeRootValuefor ResultTrees generated by a TreeGrid component.- Parameters:
rootNode- rootNode Default value is null- Throws:
IllegalStateException- this property cannot be changed after the underlying component has been created
-
getRootNode
This attribute may be used to specify a root value for the parentIdField of this resultTree. This overrides the defaultrootValuefor this tree, allowing a component to navigate a tree starting at a specific node.May be overridden via
treeRootValuefor ResultTrees generated by a TreeGrid component.- Returns:
- Object
-
Tree.reloadChildren()to reload the children of a folder, orTree.removeChildren()if you need to clear the cached children of a folder to add specific local data.