Tree: provide method to set top level children

It's impractical for Tree to tell if a new item or changed item in the data store should appear at the tree top level.

Assume a tree like

+ root
- top 1
- top 2
- top 3

"Root" is an optionally displayed node that doesn't correspond to any item in the data store. The list of top* items is determined by Tree's query parameter.

When a new item is added to the data store, Tree has no way of knowing if it matches the query or not, without rerunning the query. It also doesn't know the sort order of the item, relative to it's siblings.

Similarly, any change to an item's attributes could potentially change it's status, so we need to rerun the query in that case too.

However, rerunning the query on every new or changed node is impractical because it's too slow. Imagine a Tree of users and groups. Since users are never top level elements in the tree, it's silly to rerun the query every time a new user is added.

Since it's impractical for Tree to solve this problem, provide method for the user to notify the tree whenever the top level children have changed, by giving the new list of children. Tree will compare the current list to the new list and add/delete nodes as necessary.

Something like setTopLevelChildren( /* dojo.data.Item[] */ items );

Oldest firstNewest firstThreaded

Show commentsShow property changes

Change History (7)

(In [11998]) Provide user level hooks onNewTopItem() and onNewChildItem() to handle messages from data store about new items.
Make public setChildItems() call to manually manipulate tree in response to said data store updates.
Fixes #5536.
DND seems to be working now (except for clicking the icon, see #5558).
!strict

Refactor Tree to take a single item as the root node, rather than a set of items specified by a query. The root node of the tree can be hidden via the showRoot parameter. Query and label parameters deprecated; will be removed in v2.

implemented ForestStoreDecorator? which wraps a given store, mapping all items matching a given query as children of a synthesized root item. Use this to connect Tree to stores that don't have a single root item.

Reason for changes: The old tree design worked for simple cases but broke down for DnD. Refactoring let's users define handlers for when a node is added/removed from the top of the tree (ie, when it changes between a top level item and a child of another item, or vice-versa), and for efficiently detecting changes to the list/order of top level items (and then notifying Tree).