I've done some work on dijit.Tree since my last blog post. (These changes that went into the 1.1 beta 2 release.) Basically, decided that it was too difficult to force everyone to present a dojo.data model for the tree's data, especially w.r.t how to query the children items (and getting notifications about changes to the children items). For dijit.Tree it really makes to have a getChildren() asynchronous method, rather than the dojo.data model where there's a synchronous call to get children stubs, and then an asynchronous loadItem() call for each stub.

So... I've created an interface layer between the tree and dojo.data. There are two implementations of this model, both at the end of Tree.js, dijit.tree.TreeStoreModel and dijit.tree.ForestStoreModel. dijit.tree.TreeStoreModel connects to a dojo.data store which contains a single root item (see the "Foods" item in the categories.json, and dijit.tree.ForestStoreModel connects to stores with no root item, fabricating a root item for the tree.

Here's a revised version of my original post, reflecting the recent changes:

In version 1.1 I've fixed the Tree architecture to be able to handle DnD correctly. This involved adding an interface layer between dojo.data and the Tree, to handle some impedance mismatches between them, especially for the case where the data store doesn't contain a single root item corresponding to the root node in the tree.

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.

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).

dijit.tree.model

Version 1.1 introduces a model layer between the Tree and dojo.data (or you could write your own model that doesn't even connect to dojo.data). A model is anything that presents this interface:

TreeStoreModel

dijit provides a model called dijit.Tree.TreeStoreModel that connects to any datastore which contains a root item corresponding to the (possibly hidden) root node of the Tree.

To interface to something like QueryReadStore, where there's a non-standard way of getting the children of an item, you would override TreeStoreModel.getChildren(). If your tree supported DnD you would also need to add code to call onChildrenChange() whenever the children of an item changed.

What if I don't have a single root item?

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.

ForestStoreModel

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 there was a single root item, specified when the Tree is constructed, everything would be much simpler.

But In order to support data stores which match this pattern, I've created dijit.tree.ForestStoreModel, which wraps a store and hides that complexity from the tree.

ForestStoreModel has a number of hooks to handle changes to elements when they are added/removed from the root node, such as setting top: true. See these two callbacks that the developer must override:

The important thing is that ForestStoreModel presents a consistent interface to dijit.Tree such that every time an item is moved, onChildrenChange() is called.

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

Deprecated APIs

The store parameter to Tree is deprecated in favor of the model parameter.

getItemChildren() and similar callbacks should now be specified on the model rather than on the Tree itself.

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.