mozilla

Revision 313585 of Building Trees

  • Revision slug: XUL/Template_Guide/Building_Trees
  • Revision title: Building Trees
  • Revision id: 313585
  • Created:
  • Creator: trevorh
  • Is current revision? No
  • Comment Fix Previous Next links

Revision Content

{{ PreviousNext("XUL/Template Guide/Using Multiple Queries to Generate More Results", "XUL/Template Guide/Building Hierarchical Trees") }}

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 every row in the tree, the results are 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; creating large numbers of DOM nodes adds a lot of overhead. The performance advantage is possible since trees only display text.  As a result, 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 causes no content to be built for the template. But moreover, it uses a subtype of the main builder called the tree builder. Without this flag, the template will be handled by the content builder.

Note: While a tree builder can only be used with trees, a content builder can be used with any type of content. If you wish, you can also use the content builder for a tree. There may be situations that call for this, typically when handling smaller amounts of data. However, the content builder becomes slower as the amount of data increases.

Apart from the flags attribute, the template syntax for the tree builder and the content builder are identical. However, the tree builder requires a very specific form to the action body.  Specifically, the action body should be a single treeitem with its rows and cells.

Here is an example (using an RDF source):

<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>
Note: The tree columns (treecols) are declared outside the template as static content, since they only need to be declared once.

This template uses the simple rule syntax. The extended syntax could also be used. When using the tree builder, the {{ XULAttr("uri") }} attribute must be declared on the {{ XULElem("treeitem") }} element.

Here, the simple RDF query syntax is used, so the member variable is rdf:*. The remaining tags have a similar syntax to a tree, but have only a single row. This row is used as the template data by the tree builder. Instead of generating content, the builder uses the cell attributes to determine what to display. The tree builder implements the nsITreeView interface, so it becomes the tree’s view—in other words, 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 requests 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 generates content in the template body and substitutes data from the datasource 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.

Here is an example of a tree using an SQLite datasource:

<tree datasources="profile:messages.sqlite" ref="*"
      querytype="storage" flags="dont-build-content">
  <treecols>
    <treecol id="subject" label="Subject" flex="3"/>
    <treecol id="sender" label="Sender" flex="2"/>
    <treecol id="date" label="Date" flex="1"/>
  </treecols>
  <template>
    <query>
      select subject, sender, date from messages
    </query>
    <action>
      <treechildren>
        <treeitem uri="?">
          <treerow>
            <treecell label="?subject"/>
            <treecell label="?sender"/>
            <treecell label="?date"/>
          </treerow>
        </treeitem>
      </treechildren>
    </action>
  </template>
</tree>

Features of the Tree Builder

Besides the label of a cell, there are several other cell properties you can set when using the tree builder. The supported properties are: label, mode, properties, src and value. The label attribute is used to set the label for a cell. The mode is used for progress meter columns. It may be set to either “normal” for a normal progress meter or “undetermined” for an undetermined progress meter. The value attribute is used to set the current progress value for normal progress meters. The value attribute may also be used for checkbox columns by setting it to either true or false. Whether a cell is a normal labeled value, a progress meter or a checkbox is determined by the type attribute on the column the cell is in.

For cells in normal columns, you can use the value attribute to store some other value and you can use the view’s getCellValue() method to retrieve it. Naturally, this will retrieve the value after any variables have been substituted.

Besides the attributes mentioned above, any other attributes specified on the tree rows and cells are ignored. Since no elements are generated, you won’t be able to retrieve the values for them either. Thus, the value attribute may be useful to associate an additional value with a row since it will be easier to retrieve.

The src attribute may be used to set an image to appear in a cell. For 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="photo" label="Photo" flex="1"/>
  </treecols>
  <template>
    <treechildren>
      <treeitem uri="rdf:*">
        <treerow>
          <treecell src="rdf:*"/>
        </treerow>
      </treeitem>
    </treechildren>
  </template>
</tree>

This tree displays each photo in the tree cells. In this case, the member resource is used since that holds the photo’s URL.  However, it could be any other variable, a static value, or a combination of both.

Image:Template-guide-p31.png

Of course, we can’t really see the photos, since the tree’s rows are too small! It’s not normal to put photos in a tree like this—instead, the images would be used for icons. On the other hand, you could use a stylesheet to change the default height of the tree rows. You cannot make each row a different height, but you can change the height of all rows with some CSS:

treechildren::-moz-tree-row {
  height: 150px;
}

Since no elements are constructed by the tree builder, you cannot use the style or class attributes to change the style of a cell (This is the case with all trees). You must use syntax like that above to change the appearance. In the example above, it changes the height of a row to 150 pixels. You may want to change the syntax to refer to a specific {{ XULElem("treechildren") }} element rather than all of them. Once the row height is changed, we can see the full photos.

Note: If you want to have the state of the disclosure triangles ("twisties") be persistent, be sure to give each node a unique "id" attribute. These are used to track the current state of the disclosure triangles. Support for this was introduced in Gecko 7.0 {{ geckoRelease("7.0") }}.

Using Tree Properties

Since we need to use special CSS for trees, the properties attribute on a cell becomes extremely useful.  It can be used to define extra properties for reference later in a stylesheet.

For example, if the properties attribute was set to the value "?creator", you could style the photos created by different people differently. Alternatively, you could also use static values (in addition to variables) in the properties attribute. For instance, consider the following CSS:

treechildren::-moz-tree-cell(Dave) {
  background-color: lightgreen;
}

This would set the background color of a cell to green for any cell with the “Dave” property. You can also use the properties attribute on the {{ XULElem("treerow") }} to change the style for an entire row. This example sets the country associated with a photo as a property of a tree’s rows. We can use that property to change the appearance of each row.

<rule>
  <query>
    <content uri="?start"/>
    <member container="?start" child="?photo"/>
    <triple subject="?photo"
            predicate="http://www.xulplanet.com/rdf/country"
            object="?country"/>
    <triple subject="?country"
            predicate="http://purl.org/dc/elements/1.1/title"
            object="?countrytitle"/>
  </query>
  <action>
    <treechildren>
      <treeitem uri="?photo">
        <treerow properties="?countrytitle">
          <treecell src="?photo"/>
        </treerow>
      </treeitem>
    </treechildren>
  </action>
</rule>

You might use the following CSS to change the border around rows listing a particular country:

treechildren::-moz-tree-row(Netherlands) {
  border: green 1px solid;
}

The result of this example is a tree where one row has a green border around it.

{{ PreviousNext("XUL/Template Guide/Using Multiple Queries to Generate More Results", "XUL/Template Guide/Building Hierarchical Trees") }}

Revision Source

<p>{{ PreviousNext("XUL/Template Guide/Using Multiple Queries to Generate More Results", "XUL/Template Guide/Building Hierarchical Trees") }}</p>
<p>The most common element to use with a template is the tree.</p>
<p>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 every row in the tree, the results are 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; creating large numbers of DOM nodes adds a lot of overhead. The performance advantage is possible since trees only display text. &nbsp;As a result, the builder only has a few pieces of information to keep track of.</p>
<p>To use the tree builder, you need to add a flags attribute to the root node:</p>
<pre>
&lt;tree datasources="template-guide-streets.rdf"
      ref="http://www.xulplanet.com/rdf/myneighbourhood"
      flags="dont-build-content"&gt;
</pre>
<p>The <code>dont-build-content</code> flag causes no content to be built for the template. But moreover, it uses a subtype of the main builder called the <strong>tree builder</strong>. Without this flag, the template will be handled by the <strong>content builder</strong>.</p>
<div class="note">
  <strong>Note:</strong> While a tree builder can only be used with trees, a content builder can be used with any type of content. If you wish, you can also use the content builder for a tree. There may be situations that call for this, typically when handling smaller amounts of data. However, the content builder becomes slower as the amount of data increases.</div>
<p>Apart from the <code>flags</code> attribute, the template syntax for the tree builder and the content builder are identical. However, the tree builder requires a very specific form to the action body. &nbsp;Specifically, the action body should be a single <code>treeitem</code> with its rows and cells.</p>
<p>Here is an example (using an RDF source):</p>
<pre>
&lt;tree id="photosList" flex="1" datasources="template-guide-photos5.rdf"
      ref="http://www.xulplanet.com/rdf/myphotos" flags="dont-build-content"&gt;
  &lt;treecols&gt;
    &lt;treecol id="name" label="Name" flex="1"/&gt;
    &lt;treecol id="date" label="Date" flex="1"/&gt;
  &lt;/treecols&gt;
  &lt;template&gt;
    &lt;treechildren&gt;
      &lt;treeitem uri="rdf:*"&gt;
        &lt;treerow&gt;
          &lt;treecell label="rdf:http://purl.org/dc/elements/1.1/title"/&gt;
          &lt;treecell label="rdf:http://purl.org/dc/elements/1.1/date"/&gt;
        &lt;/treerow&gt;
      &lt;/treeitem&gt;
    &lt;/treechildren&gt;
  &lt;/template&gt;
&lt;/tree&gt;
</pre>
<div class="note">
  <strong>Note:</strong>&nbsp;The tree columns (<code>treecols</code>) are declared outside the template as static content, since they only need to be declared once.</div>
<p>This template uses the simple rule syntax. The extended syntax could also be used. When using the tree builder, the {{ XULAttr("uri") }} attribute must be declared on the {{ XULElem("treeitem") }} element.</p>
<p>Here, the simple RDF query syntax is used, so the member variable is <code>rdf:*</code>. The remaining tags have a similar syntax to a tree, but have only a single row. This row is used as the template data by the tree builder. Instead of generating content, the builder uses the cell attributes to determine what to display. The tree builder implements the <a class="external" href="http://www.xulplanet.com/references/xpcomref/ifaces/nsITreeView.html">nsITreeView</a> interface, so it becomes the tree’s view—in other words, 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.</p>
<p>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 requests a label for the first cell, the builder looks up the ‘<span class="nowiki">http://purl.org/dc/elements/1.1/title</span>’ predicate for the row in question and returns it.</p>
<p>The content builder generates content in the template body and substitutes data from the datasource right away. However, it will generate the same result on screen to the user as with the tree builder. Compare the example with a <a class="external" href="http://developer.mozilla.org/samples/xultemp/template-guide-ex30.xul">tree builder</a> and the same example using a <a class="external" href="http://developer.mozilla.org/samples/xultemp/template-guide-ex30b.xul">content builder</a>.</p>
<p>Here is an example of a tree using an SQLite datasource:</p>
<pre>
&lt;tree datasources="profile:messages.sqlite" ref="*"
      querytype="storage" flags="dont-build-content"&gt;
  &lt;treecols&gt;
    &lt;treecol id="subject" label="Subject" flex="3"/&gt;
    &lt;treecol id="sender" label="Sender" flex="2"/&gt;
    &lt;treecol id="date" label="Date" flex="1"/&gt;
  &lt;/treecols&gt;
  &lt;template&gt;
    &lt;query&gt;
      select subject, sender, date from messages
    &lt;/query&gt;
    &lt;action&gt;
      &lt;treechildren&gt;
        &lt;treeitem uri="?"&gt;
          &lt;treerow&gt;
            &lt;treecell label="?subject"/&gt;
            &lt;treecell label="?sender"/&gt;
            &lt;treecell label="?date"/&gt;
          &lt;/treerow&gt;
        &lt;/treeitem&gt;
      &lt;/treechildren&gt;
    &lt;/action&gt;
  &lt;/template&gt;
&lt;/tree&gt;
</pre>
<h3 id="Features_of_the_Tree_Builder" name="Features_of_the_Tree_Builder">Features of the Tree Builder</h3>
<p>Besides the label of a cell, there are several other cell properties you can set when using the tree builder. The supported properties are: <code>label</code>, <code>mode</code>, <code>properties</code>, <code>src</code> and <code>value</code>. The <code>label</code> attribute is used to set the label for a cell. The <code>mode</code> is used for progress meter columns. It may be set to either “normal” for a normal progress meter or “undetermined” for an undetermined progress meter. The <code>value</code> attribute is used to set the current progress value for normal progress meters. The <code>value</code> attribute may also be used for checkbox columns by setting it to either <code>true</code> or <code>false</code>. Whether a cell is a normal labeled value, a progress meter or a checkbox is determined by the <code>type</code> attribute on the column the cell is in.</p>
<p>For cells in normal columns, you can use the <code>value</code> attribute to store some other value and you can use the view’s <code>getCellValue()</code> method to retrieve it. Naturally, this will retrieve the value after any variables have been substituted.</p>
<p>Besides the attributes mentioned above, any other attributes specified on the tree rows and cells are ignored. Since no elements are generated, you won’t be able to retrieve the values for them either. Thus, the <code>value</code> attribute may be useful to associate an additional value with a row since it will be easier to retrieve.</p>
<p>The <code>src</code> attribute may be used to set an image to appear in a cell. For example:</p>
<pre>
&lt;tree id="photosList" flex="1" datasources="template-guide-photos5.rdf"
      ref="http://www.xulplanet.com/rdf/myphotos" flags="dont-build-content"&gt;
  &lt;treecols&gt;
    &lt;treecol id="photo" label="Photo" flex="1"/&gt;
  &lt;/treecols&gt;
  &lt;template&gt;
    &lt;treechildren&gt;
      &lt;treeitem uri="rdf:*"&gt;
        &lt;treerow&gt;
          &lt;treecell src="rdf:*"/&gt;
        &lt;/treerow&gt;
      &lt;/treeitem&gt;
    &lt;/treechildren&gt;
  &lt;/template&gt;
&lt;/tree&gt;
</pre>
<p>This <a class="external" href="http://developer.mozilla.org/samples/xultemp/template-guide-ex31.xul">tree</a> displays each photo in the tree cells. In this case, the member resource is used since that holds the photo’s URL. &nbsp;However, it could be any other variable, a static value, or a combination of both.</p>
<p><img alt="Image:Template-guide-p31.png" class="internal" src="/@api/deki/files/396/=Template-guide-p31.png" /></p>
<p>Of course, we can’t really see the photos, since the tree’s rows are too small! It’s not normal to put photos in a tree like this—instead, the images would be used for icons. On the other hand, you could use a stylesheet to change the default height of the tree rows. You cannot make each row a different height, but you can change the height of all rows with some CSS:</p>
<pre>
treechildren::-moz-tree-row {
  height: 150px;
}
</pre>
<p>Since no elements are constructed by the tree builder, you cannot use the style or class attributes to change the style of a cell (This is the case with all trees). You must use syntax like that above to change the appearance. In the example above, it changes the height of a row to 150 pixels. You may want to change the syntax to refer to a specific&nbsp;{{ XULElem("treechildren") }}&nbsp;element rather than all of them. Once the row height is changed, we can see the <a class="external" href="http://developer.mozilla.org/samples/xultemp/template-guide-ex31b.xul">full photos</a>.</p>
<div class="note">
  <strong>Note:</strong> If you want to have the state of the disclosure triangles ("twisties") be persistent, be sure to give each node a unique "id" attribute. These are used to track the current state of the disclosure triangles. Support for this was introduced in Gecko 7.0 {{ geckoRelease("7.0") }}.</div>
<h3 id="Using_Tree_Properties" name="Using_Tree_Properties">Using Tree Properties</h3>
<p>Since we need to use special CSS for trees, the <code>properties</code> attribute on a cell becomes extremely useful. &nbsp;It can be used to define extra properties for reference later in a stylesheet.</p>
<p>For example, if the properties attribute was set to the value "?creator", you could style the photos created by different people differently. Alternatively, you could also use static values (in addition to variables) in the <code>properties</code> attribute. For instance, consider the following CSS:</p>
<pre>
treechildren::-moz-tree-cell(Dave) {
  background-color: lightgreen;
}
</pre>
<p>This would set the background color of a cell to green for any cell with the “Dave” property. You can also use the properties attribute on the&nbsp;{{ XULElem("treerow") }}&nbsp;to change the style for an entire row. This example sets the country associated with a photo as a property of a tree’s rows. We can use that property to change the appearance of each row.</p>
<pre>
&lt;rule&gt;
  &lt;query&gt;
    &lt;content uri="?start"/&gt;
    &lt;member container="?start" child="?photo"/&gt;
    &lt;triple subject="?photo"
            predicate="http://www.xulplanet.com/rdf/country"
            object="?country"/&gt;
    &lt;triple subject="?country"
            predicate="http://purl.org/dc/elements/1.1/title"
            object="?countrytitle"/&gt;
  &lt;/query&gt;
  &lt;action&gt;
    &lt;treechildren&gt;
      &lt;treeitem uri="?photo"&gt;
        &lt;treerow properties="?countrytitle"&gt;
          &lt;treecell src="?photo"/&gt;
        &lt;/treerow&gt;
      &lt;/treeitem&gt;
    &lt;/treechildren&gt;
  &lt;/action&gt;
&lt;/rule&gt;
</pre>
<p>You might use the following CSS to change the border around rows listing a particular country:</p>
<pre>
treechildren::-moz-tree-row(Netherlands) {
  border: green 1px solid;
}
</pre>
<p>The result of this <a class="external" href="http://developer.mozilla.org/samples/xultemp/template-guide-ex31c.xul">example</a> is a tree where one row has a green border around it.</p>
<p>{{ PreviousNext("XUL/Template Guide/Using Multiple Queries to Generate More Results", "XUL/Template Guide/Building Hierarchical Trees") }}</p>
Revert to this revision