This post is out of date... see the new post instead.

In version 1.1 I've fixed the Tree architecture to be able to handle DnD correctly. I've had to deprecate (not remove) some version 1.0 APIs because they didn't work with DnD, and I've listed them here, along with some general discussion about what it means for a tree to connect to a data store. Hopefully some will find it useful.

Tree/data store connection

Dijit.Tree's connection to dojo.data gives the tree a lot of power, but it's also complicated the API to something more than if the tree simply displayed a read-only collapsible list, and/or had it's own custom data format. That's why various people have asked for a more direct interface to control the nodes in a tree, but at least for now I've decided not to do that, in order to minimize the surface area of our API.

The dijit.Tree widget is a view on a dojo.data store. Tree's job is to display the store data in a hierarchy. This is more complicated then it sounds because a store doesn't represent a tree per-se, but rather it just contains a bunch of items, some of which contain references to other items. For example, an item might have multiple children attributes, each of which points to other items. Multiple parent items could point to the same child item, or there could even be loops.

Consider this store:

If we represented that data in ItemFileWriteStore, it might look like the JSON below, although it's important to realize that Tree can interface to any store, so the internals of the store are irrelevant.

We'd like the dijit.Tree widget to display those items above in a hierarchy, like this:

• Fruits
  • Citrus
  • Orange
  • Lemon
  • Tomato
• Vegetables
  • Tomato

A few things to note:

• this is technically a forest, not a tree, since there are multiple top level nodes.
• there's only one 'Tomato' item, but it's referenced as both a Fruit and a Vegetable.

Tree doesn't support multiple-parent items yet but will in the future. The point is to note how a data store represents very general data which we are mapping into a Tree.

Dojo 1.0 Tree API

In the dojo 1.0 release, dijit.Tree featured an API where you specify a query to get the top-level item or items, and then an attribute to query to get children of those top level items. For this data you would want to display all the elements marked as top:true at the top level, and then get children via the "children" attribute.

<div dojoType="dijit.Tree" store="catStore" query="{top: true}"
		labelAttr="name" childrenAttr="children"></div>

Tree also provided an option to create a root level node to tie 'Fruits' and 'Vegetables' together without any such item existing in the data store, by specifying a label to the Tree:

<div dojoType="dijit.Tree" store="catStore" query="{top: true}" label="Food"
		labelAttr="name" childrenAttr="children"></div>

• Food
  • Fruits
    • Citrus
    • Orange
    • Lemon
    • Tomato
  • Vegetables
    • Tomato

This is a convenient feature, although it causes some confusion since there's no data store item associated with the top level node in the tree, and thus clicking it will produce an onClick(null) rather than onClick(item). Of course you could add a "Food" item to your data store but it may not be convenient to change your data model just to affect the view (the Tree).

The problem with DnD and data store notification

Given that a dijit.Tree is just a view onto a dojo.data store, any updates to the tree (ie, moving a node via DnD) have to be reflected to the store, and conversly any updates to the store need to be reflected in the tree.

As a matter of fact, dragging-and-dropping (ie, moving) an item in the Tree doesn't update the tree directly, but rather just updates the data store, and then Tree responds to that update just like any update to the store (from an external source). So, there are two issues involved with a tree:

1. notifying the data store about updates
2. responding to changes in the store

If you move an item (for example, deciding that a lettuce is a fruit rather than a vegetable), the DnD code tells the data store that Vegetable's children attribute changed from [Tomato, Lettuce] to just [Tomato], and that 'Fruits' children attribute changed from [Citrus, Apple, Banana] to [Citrus, Apple, Banana, Lettuce] (or perhaps a different order). The data store then notifies tree of the updates to 'Fruits' and 'Vegetables' children attributes, and tree updates it's display.

If, however, you decided that a 'Tomato' was neither a 'Fruit' nor a 'Vegetable', but rather just a type of food, you would want to somehow make it a top level item in the tree so that myStore.fetch({ query: {top: true} }) returns 'Tomato' in it's query. We have two issues here, namely that:

1. dijit.Tree doesn't know how to mark the element as "top level". In this case, it's simply setting the top attribute to true, but there may be more complicated cases.
2. The data store notifies the Tree that an item has changed (namely that the item's "top" attribute has been set), but there's no way for Tree to know whether that item now matches the "top level items" query specified to Tree without rerunning the query. And even if it new an item was top level, it wouldn't know the order of the new item relative to the other items. This is because Tree can connect to any data store and thus the query format is a black box.

ForestDecorator

In short, all of these problems are caused by allowing a query which lists a set of top level children, and whose results can change over time. If we assume that there's a single root item, specified when the Tree is constructed, everything is simplified. All changes to/from the tree are specified as changes to some item's children attribute.

However, in order to support data stores which don't match this pattern, I've created dijit._tree.ForestStoreDecorator, which wraps another store and just adds a fake root item.

The decorated store just has a root item, but is otherwise the same:

Then you simply create the tree off of the decorated store:

It also has a number of hooks to handle changes to elements when they are added/removed from the root node, such as setting top: true. But the important thing is that it presents a consistent interface to dijit.Tree such that every time an item is moved, it's reflected by changes to two other items' children attributes.

Note that the top level item doesn't actually have to be displayed. The showRoot parameter controls whether the tree shows up as a true tree, like:

• Food
  • Fruits
    • Citrus
    • Orange
    • Lemon
    • Tomato
  • Vegetables
    • Tomato

Or just as a forest:

• Fruits
  • Citrus
  • Orange
  • Lemon
  • Tomato
• Vegetables
  • Tomato

So, in summary, dijit.Tree still takes a query parameter, but that query should only return one item (the root item). And if (as for the case of ForestStoreDecorator) store.fetch() only returns a single item, then no query is needed.

Other deprecated APIs

getItemChildren() was a convenient abstraction for non-standard ways of mapping parents items to child items, but it doesn't handle updates to the data store. The user can write decorator store like dijit._tree.ForestStoreDecorator.

getItemParentIdentity() falls into the same category.

Nested ItemFileReadStore problems

Let's look at ItemFileWriteStore with nested elements since that's often used. Consider a data file like this:

{ 
	identifier: 'id',
	label: 'name',
	items: [
		{ id: '0', name: 'Fruits', children: [
			{ id: '1', name: 'Citrus', items: [
				{ id: '2', name: 'Orange'}
				{ id: '3', name: 'Lemon'}
				...
			]},
			{ id: '4', name: 'Apple'},
			{ id: '5', name: 'Banana'}
			...
		]},
		{ id: '6', name:'Vegetables', children:[
			{ id: '7', name: 'Tomato'},
			{ id: '8', name: 'Lettuce'}
			...
		]},
		...
	]
}

How do we mark 'Tomato' as a "top level" item, so that ItemFileReadStore.fetch() will return that item? Short of actually deleting and recreating the item, which is bad for a number of reasons, there's no way to do that with ItemFileReadStore and nested data. The best we can do is switch to a referenced layout like at the beginning of this article. Although there's a special API to create an item as a child of another item, there's no API to move it to be top level.

Actually, the nested ItemFileReadStore has another limitation that you can't multi-parent an item, such as marking 'Tomato' as both a fruit and a vegatable.