The most common element to use with a template is the tree. You can use a template with a tree just like any other template. However, since templates are often used with trees, especially with large amounts of data, the template system supports a special builder just for creating trees. Rather than generate content for each row in the tree, the results are just stored in a list inside the builder. This means that DOM nodes are not constructed for any of the items. This is much more efficient as creating a lot of DOM nodes would add a lot of additional overhead. This performance advantage is possible since trees can only display text so the builder only has a few pieces of information to keep track of.
To use the tree builder, you need to add a flags attribute to the root node:
<tree datasources="template-guide-streets.rdf" ref="http://www.xulplanet.com/rdf/myneighbourhood" flags="dont-build-content">
The "dont-build-content" flag is descriptive in that it doesn't cause any content to be built. However, what it really does is use a subtype of the main builder specific to trees, called the tree builder. Without this flag, the template will be handled using the other type of builder, which is called a content builder, as it generates content. Note that while a tree builder can only be used with trees, a content builder can be used with any type of content. You can also choose to use the content builder for a tree, if you wish. There may be uses for this, especially for small amounts of data. However, you will find that the content builder will be slower as the amount of data to display gets larger.
Apart from the flags attribute, the template syntax is exactly the same for the tree builder as with the content builder. One thing though is that the tree builder requires a very specific form to the action body, specifically, the action body should be a single treeitem with its row and cells. Here is an example:
<tree id="photosList" flex="1" datasources="template-guide-photos5.rdf" ref="http://www.xulplanet.com/rdf/myphotos" flags="dont-build-content"> <treecols> <treecol id="name" label="Name" flex="1"/> <treecol id="date" label="Date" flex="1"/> </treecols> <template> <treechildren> <treeitem uri="rdf:*"> <treerow> <treecell label="rdf:http://purl.org/dc/elements/1.1/title"/> <treecell label="rdf:http://purl.org/dc/elements/1.1/date"/> </treerow> </treeitem> </treechildren> </template> </tree>
The tree columns are declared as static content since we only want to declare them once. This template uses the simple rule syntax, although the extended syntax could also be used. The uri attribute must be declared on the <treeitem> element set to either "rdf:*" for the simple syntax or the member variable for the extended syntax. The remaining tags are like the syntax of a tree with a single row. This row will be used as the template data by the tree builder. Instead of generating content, the builder will use the cell attributes to determine what to display. The tree builder implements the nsITreeView interface so it becomes the tree's view. (That is, the tree's view and the tree's builder are the same object.) When the tree is displayed, it asks the view for the contents of each cell. The builder looks at the label for the corresponding cell, translates any variables or predicates into values, and returns the value.
In the example above, the first cell should display the title. The builder doesn't compute any labels until the view asks for them. When the view does request a label for the first cell, the builder looks up the "http://purl.org/dc/elements/1.1/title" predicate for the row in question and returns it.
The content builder will generate the content in the template body and do substitution of the RDF predicates right away. However, it will generate the same result on screen to the user as with the tree builder. Compare the example with a tree builder and the same example using a content builder.