dijit/tree/ForestStoreModel (version 1.10)

dijit/tree/TreeStoreModel

Summary

Interface between a dijit.Tree and a dojo.data store that doesn't have a root item, a.k.a. a store that has multiple "top level" items.

Use this class to wrap a dojo.data store, making all the items matching the specified query appear as children of a fabricated "root item". If no query is specified then all the items returned by fetch() on the underlying store become children of the root item. This class allows dijit.Tree to assume a single root item, even if the store doesn't have one.

When using this class the developer must override a number of methods according to their app and data, including:

Usage

var foo = new ForestStoreModel(params);
dijit/tree/ForestStoreModel
Parameter Type Description
params undefined

See the dijit/tree/ForestStoreModel reference documentation for more information.

Property Summary

  • childrenAttrsOne or more attribute names (attributes in the dojo.data item) that specify that item's children
  • deferItemLoadingUntilExpandSetting this to true will cause the TreeStoreModel to defer calling loadItem on nodes until they are expanded.
  • labelAttrIf specified, get label for tree node from this attribute, rather than by calling store.getLabel()
  • newItemIdAttrName of attribute in the Object passed to newItem() that specifies the id.
  • querySpecifies the set of children of the root item.
  • rootPointer to the root item (read only, not a parameter)
  • rootIdID of fabricated root item
  • rootLabelLabel of fabricated root item
  • storeUnderlying store

Method Summary

  • _requeryTop()
  • destroy()
  • fetchItemByIdentity(keywordArgs)
  • getChildren(parentItem,callback,onError) Calls onComplete() with array of child items of given parent item, all loaded.
  • getIdentity(item)
  • getLabel(item)
  • getRoot(onItem,onError) Calls onItem with the root item for the tree, possibly a fabricated item.
  • isItem(something)
  • mayHaveChildren(item) Tells if an item has or may have children.
  • newItem(args,parent,insertIndex) Creates a new item.
  • pasteItem(childItem,oldParentItem,newParentItem,bCopy,insertIndex) Move or copy an item from one parent item to another.

Event Summary

  • onAddToRoot(item) Called when item added to root of tree; user must override this method to modify the item so that it matches the query for top level items
  • onChange(item) Callback whenever an item has changed, so that Tree can update the label, icon, etc.
  • onChildrenChange(parent,newChildrenList) Callback to do notifications about new, updated, or deleted items.
  • onDelete(item) Callback when an item has been deleted.
  • onDeleteItem(item) Handler for delete notifications from underlying store
  • onLeaveRoot(item) Called when item removed from root of tree; user must override this method to modify the item so it doesn't match the query for top level items
  • onNewItem(item,parentInfo) Handler for when new items appear in the store.
  • onNewRootItem(args) User can override this method to modify a new element that's being added to the root of the tree, for example to add a flag like root=true
  • onSetItem(item,attribute,oldValue,newValue) Updates the tree view according to changes to an item in the data store.

Properties

childrenAttrs
Defined by: dijit/tree/TreeStoreModel

One or more attribute names (attributes in the dojo.data item) that specify that item's children

deferItemLoadingUntilExpand
Defined by: dijit/tree/TreeStoreModel

Setting this to true will cause the TreeStoreModel to defer calling loadItem on nodes until they are expanded. This allows for lazying loading where only one loadItem (and generally one network call, consequently) per expansion (rather than one for each child). This relies on partial loading of the children items; each children item of a fully loaded item should contain the label and info about having children.

labelAttr
Defined by: dijit/tree/TreeStoreModel

If specified, get label for tree node from this attribute, rather than by calling store.getLabel()

newItemIdAttr
Defined by: dijit/tree/TreeStoreModel

Name of attribute in the Object passed to newItem() that specifies the id.

If newItemIdAttr is set then it's used when newItem() is called to see if an item with the same id already exists, and if so just links to the old item (so that the old item ends up with two parents).

Setting this to null or "" will make every drop create a new item.

query
Defined by: dijit/tree/ForestStoreModel

Specifies the set of children of the root item.

root
Defined by: dijit/tree/TreeStoreModel

Pointer to the root item (read only, not a parameter)

rootId
Defined by: dijit/tree/ForestStoreModel

ID of fabricated root item

rootLabel
Defined by: dijit/tree/ForestStoreModel

Label of fabricated root item

store
Defined by: dijit/tree/TreeStoreModel

Underlying store

Methods

_requeryTop()
Defined by dijit/tree/ForestStoreModel
destroy()
Defined by dijit/tree/TreeStoreModel
fetchItemByIdentity(keywordArgs)
Defined by dijit/tree/ForestStoreModel
Parameter Type Description
keywordArgs object
getChildren(parentItem,callback,onError)
Defined by dijit/tree/ForestStoreModel

Calls onComplete() with array of child items of given parent item, all loaded.

Parameter Type Description
parentItem dojo/data/Item
callback function(items)
onError function
getIdentity(item)
Defined by dijit/tree/ForestStoreModel
Parameter Type Description
item item
Returns:undefined
getLabel(item)
Defined by dijit/tree/ForestStoreModel
Parameter Type Description
item item
Returns:undefined
getRoot(onItem,onError)
Defined by dijit/tree/TreeStoreModel

Calls onItem with the root item for the tree, possibly a fabricated item. Calls onError on error.

Parameter Type Description
onItem undefined
onError undefined
isItem(something)
Defined by dijit/tree/ForestStoreModel
Parameter Type Description
something anything
Returns:boolean
mayHaveChildren(item)
Defined by dijit/tree/ForestStoreModel

Tells if an item has or may have children. Implementing logic here avoids showing +/- expando icon for nodes that we know don't have children. (For efficiency reasons we may not want to check if an element actually has children until user clicks the expando node)

Parameter Type Description
item dojo/data/Item
Returns:boolean
newItem(args,parent,insertIndex)
Defined by dijit/tree/ForestStoreModel

Creates a new item. See dojo/data/api/Write for details on args. Used in drag & drop when item from external source dropped onto tree.

Parameter Type Description
args dijit/tree/dndSource.__Item
parent Item
insertIndex int
Optional
Returns:undefined
pasteItem(childItem,oldParentItem,newParentItem,bCopy,insertIndex)
Defined by dijit/tree/ForestStoreModel

Move or copy an item from one parent item to another. Used in drag & drop

Parameter Type Description
childItem Item
oldParentItem Item
newParentItem Item
bCopy Boolean
insertIndex int
Optional

Events

onAddToRoot(item)
Defined by: dijit/tree/ForestStoreModel

Called when item added to root of tree; user must override this method to modify the item so that it matches the query for top level items

Parameter Type Description
item item

Examples

Example 1

store.setValue(item, "root", true);
onChange(item)
Defined by: dijit/tree/TreeStoreModel

Callback whenever an item has changed, so that Tree can update the label, icon, etc. Note that changes to an item's children or parent(s) will trigger an onChildrenChange() so you can ignore those changes here.

Parameter Type Description
item dojo/data/Item

Examples

Example 1

store.setValue(item, "root", true);
onChildrenChange(parent,newChildrenList)
Defined by: dijit/tree/TreeStoreModel

Callback to do notifications about new, updated, or deleted items.

Parameter Type Description
parent dojo/data/Item
newChildrenList dojo/data/Item[]

Examples

Example 1

store.setValue(item, "root", true);
onDelete(item)
Defined by: dijit/tree/TreeStoreModel

Callback when an item has been deleted.

Note that there will also be an onChildrenChange() callback for the parent of this item.

Parameter Type Description
item dojo/data/Item

Examples

Example 1

store.setValue(item, "root", true);
onDeleteItem(item)
Defined by: dijit/tree/ForestStoreModel

Handler for delete notifications from underlying store

Parameter Type Description
item Object

Examples

Example 1

store.setValue(item, "root", true);
onLeaveRoot(item)
Defined by: dijit/tree/ForestStoreModel

Called when item removed from root of tree; user must override this method to modify the item so it doesn't match the query for top level items

Parameter Type Description
item item

Examples

Example 1

store.unsetAttribute(item, "root");
onNewItem(item,parentInfo)
Defined by: dijit/tree/ForestStoreModel

Handler for when new items appear in the store. Developers should override this method to be more efficient based on their app/data.

Note that the default implementation requeries the top level items every time a new item is created, since any new item could be a top level item (even in addition to being a child of another item, since items can have multiple parents).

If developers can detect which items are possible top level items (based on the item and the parentInfo parameters), they should override this method to only call _requeryTop() for top level items. Often all top level items have parentInfo==null, but that will depend on which store you use and what your data is like.

Parameter Type Description
item dojo/data/api/Item
parentInfo Object

Examples

Example 1

store.unsetAttribute(item, "root");
onNewRootItem(args)
Defined by: dijit/tree/ForestStoreModel

User can override this method to modify a new element that's being added to the root of the tree, for example to add a flag like root=true

Parameter Type Description
args dijit/tree/dndSource.__Item

Examples

Example 1

store.unsetAttribute(item, "root");
onSetItem(item,attribute,oldValue,newValue)
Defined by: dijit/tree/ForestStoreModel

Updates the tree view according to changes to an item in the data store. Developers should override this method to be more efficient based on their app/data.

Handles updates to an item's children by calling onChildrenChange(), and other updates to an item by calling onChange().

Also, any change to any item re-executes the query for the tree's top-level items, since this modified item may have started/stopped matching the query for top level items.

If possible, developers should override this function to only call _requeryTop() when the change to the item has caused it to stop/start being a top level item in the tree.

Parameter Type Description
item item
attribute attribute-name-string
oldValue Object | Array
newValue Object | Array

Examples

Example 1

store.unsetAttribute(item, "root");
Error in the documentation? Can’t find what you are looking for? Let us know!