Compare Revisions

Building Trees

Change Revisions

Revision 75751:

Revision 75751 by Marienz on

Revision 75752:

Revision 75752 by Zearin on

Title:
Building Trees
Building Trees
Slug:
XUL/Template_Guide/Building_Trees
XUL/Template_Guide/Building_Trees
Tags:
XUL, XUL_Template_Guide
XUL, XUL_Template_Guide
Content:

Revision 75751
Revision 75752
n11      The most common element to use with a template is the tree.n11      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 w 
>ith large amounts of data, the template system supports a special 
> builder just for creating trees. Rather than generate content fo 
>r each row in the tree, the results are just stored in a list ins 
>ide the builder. This means that DOM nodes are not constructed fo 
>r any of the items. This is much more efficient as creating a lot 
> of DOM nodes would add a lot of additional overhead. This perfor 
>mance advantage is possible since trees can only display text so  
>the builder only has a few pieces of information to keep track of 
>. 
12    </p>
13    <p>
14      You can use a template with a tree just like any other temp
 >late. However, since templates are often used with trees—especial
 >ly with large amounts of data—the template system supports a spec
 >ial builder just for creating trees. Rather than generate content
 > for every row in the tree, the results are stored in a list insi
 >de the builder. This means that DOM nodes are not constructed for
 > any of the items. This is much more efficient; creating large nu
 >mbers of DOM nodes adds a lot of overhead. The performance advant
 >age is possible since trees only display text. &nbsp;As a result,
 > the builder only has a few pieces of information to keep track o
 >f.
n22      The "dont-build-content" flag causes no content to be builtn25      The <code>dont-build-content</code> flag causes no content 
> for the template. However, what it really does is use a subtype >to be built for the template. But moreover, it uses a subtype of 
>of the main builder specific to trees, called the tree builder. W>the main builder called the <strong>tree builder</strong>. Withou
>ithout this flag, the template will be handled using the other ty>t this flag, the template will be handled by the <strong>content 
>pe of builder, which is called a content builder, as it generates>builder</strong>.
> content. Note that while a tree builder can only be used with tr 
>ees, 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 wis 
>h. There may be uses for this, especially for small amounts of da 
>ta. However, you will find that the content builder will be slowe 
>r as the amount of data to display gets larger. 
23    </p>
24    <p>26    </p>
25      Apart from the flags attribute, the template syntax is exac27    <div class="note">
>tly the same for the tree builder as with the content builder. On 
>e 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 usin 
>g an RDF source: 
28      <strong>Note:</strong> While a tree builder can only be use
 >d with trees, a content builder can be used with any type of cont
 >ent. If you wish, you can also use the content builder for a tree
 >. There may be situations that call for this, typically when hand
 >ling smaller amounts of data. However, the content builder become
 >s slower as the amount of data increases.
29    </div>
30    <p>
31      Apart from the <code>flags</code> attribute, the template s
 >yntax for the tree builder and the content builder are identical.
 > However, the tree builder requires a very specific form to the a
 >ction body. &nbsp;Specifically, the action body should be a singl
 >e <code>treeitem</code> with its rows and cells.
32    </p>
33    <p>
34      Here is an example (using an RDF source):
n46    <p>n55    <div class="note">
47      The tree columns are declared outside the template as stati56      <strong>Note:</strong>&nbsp;The tree columns (<code>treecol
>c content since we only want to declare them once. This template >s</code>) are declared outside the template as static content, si
>uses the simple rule syntax, although the extended syntax could a>nce they only need to be declared once.
>lso be used. When using the tree builder, the {{ XULAttr("uri") } 
>} attribute must be declared on the {{ XULElem("treeitem") }} ele 
>ment. Here, the simple RDF query syntax is used, so the membr var 
>iable is 'rdf:*'. The remaining tags are like the syntax of a tre 
>e with a single row. This row will be used as the template data b 
>y the tree builder. Instead of generating content, the builder wi 
>ll use the cell attributes to determine what to display. The tree 
> builder implements the <a class="external" href="http://www.xulp 
>lanet.com/references/xpcomref/ifaces/nsITreeView.html">nsITreeVie 
>w</a> 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 tre 
>e is displayed, it asks the view for the contents of each cell. T 
>he builder looks at the label for the corresponding cell, transla 
>tes any variables or predicates into values, and returns the valu 
>e. 
57    </div>
48    </p>58    <p>
59      This template uses the simple rule syntax. The extended syn
 >tax could also be used. When using the tree builder, the {{ XULAt
 >tr("uri") }} attribute must be declared on the {{ XULElem("treeit
 >em") }} element.
49    <p>60    </p>
50      In the example above, the first cell should display the tit
>le. The builder doesn't compute any labels until the view asks fo 
>r them. When the view does request a label for the first cell, th 
>e builder looks up the '<span class="nowiki">http://purl.org/dc/e 
>lements/1.1/title</span>' predicate for the row in question and r 
>eturns it. 
51    </p>61    <p>
62      Here, the simple RDF query syntax is used, so the member va
 >riable is <code>rdf:*</code>. The remaining tags have a similar s
 >yntax to a tree, but have only a single row. This row is used as 
 >the template data by the tree builder. Instead of generating cont
 >ent, the builder uses the cell attributes to determine what to di
 >splay. The tree builder implements the <a class="external" href="
 >http://www.xulplanet.com/references/xpcomref/ifaces/nsITreeView.h
 >tml">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 cont
 >ents of each cell. The builder looks at the label for the corresp
 >onding cell, translates any variables or predicates into values, 
 >and returns the value.
52    <p>63    </p>
53      The content builder will generate the content in the templa
>te body and do substitution of the 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 cla 
>ss="external" href="http://developer.mozilla.org/samples/xultemp/ 
>template-guide-ex30.xul">tree builder</a> and the same example us 
>ing a <a class="external" href="http://developer.mozilla.org/samp 
>les/xultemp/template-guide-ex30b.xul">content builder</a>. 
54    </p>64    <p>
65      In the example above, the first cell should display the tit
 >le. The builder doesn’t compute any labels until the view asks fo
 >r them. When the view requests a label for the first cell, the bu
 >ilder looks up the ‘<span class="nowiki">http://purl.org/dc/eleme
 >nts/1.1/title</span>’ predicate for the row in question and retur
 >ns it.
55    <p>66    </p>
67    <p>
68      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 t
 >ree 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="ext
 >ernal" href="http://developer.mozilla.org/samples/xultemp/templat
 >e-guide-ex30b.xul">content builder</a>.
69    </p>
70    <p>
56      Here is an example of a tree using an Sqlite datasource:71      Here is an example of a tree using an SQLite datasource:
n88      Besides the label of a cell, there are several other cell pn103      Besides the label of a cell, there are several other cell p
>roperties you can set when using the tree builder. The supported >roperties you can set when using the tree builder. The supported 
>properties are: label, mode, properties, src and value. The label>properties are: <code>label</code>, <code>mode</code>, <code>prop
> attribute is used to set the label for a cell. The mode is used >erties</code>, <code>src</code> and <code>value</code>. The <code
>for progress meter columns. It may be set to either 'normal' for >>label</code> attribute is used to set the label for a cell. The 
>a normal progress meter or 'undetermined' for an undetermined pro><code>mode</code> is used for progress meter columns. It may be s
>gress meter. The value attribute is used to set the current progr>et to either “normal” for a normal progress meter or “undetermine
>ess value for normal progress meters. The value attribute may als>d” for an undetermined progress meter. The <code>value</code> att
>o be used for checkbox columns by setting it to either true or fa>ribute is used to set the current progress value for normal progr
>lse. Whether a cell is a normal labeled value, a progress meter o>ess meters. The <code>value</code> attribute may also be used for
>r a checkbox is determined by the type attribute on the column th> checkbox columns by setting it to either <code>true</code> or <c
>e cell is in.>ode>false</code>. Whether a cell is a normal labeled value, a pro
 >gress meter or a checkbox is determined by the <code>type</code> 
 >attribute on the column the cell is in.
89    </p>
90    <p>104    </p>
91      For cells in normal columns, you can use the value attribut
>e to store some other value and you can use the view's getCellVal 
>ue method to retrieve it. Naturally, this will retrieve the value 
> after any variables have been substituted. Besides the attribute 
>s mentioned above, any other attributes specified on the tree row 
>s and cells are ignored. Since no elements are generated, you won 
>'t be able to retrieve the values for them either. Thus, the valu 
>e attribute may be useful to associate an additional value with a 
> row since it will be easier to retrieve. 
92    </p>105    <p>
106      For cells in normal columns, you can use the <code>value</c
 >ode> 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 substi
 >tuted.
93    <p>107    </p>
108    <p>
109      Besides the attributes mentioned above, any other attribute
 >s specified on the tree rows and cells are ignored. Since no elem
 >ents 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 eas
 >ier to retrieve.
110    </p>
111    <p>
94      The src attribute may be used to set an image to appear in 112      The <code>src</code> attribute may be used to set an image 
>a cell. For example:>to appear in a cell. For example:
n114      This <a class="external" href="http://developer.mozilla.orgn132      This <a class="external" href="http://developer.mozilla.org
>/samples/xultemp/template-guide-ex31.xul">tree</a> displays each >/samples/xultemp/template-guide-ex31.xul">tree</a> displays each 
>photo in the tree cells. In this case, the member resource is use>photo in the tree cells. In this case, the member resource is use
>d since that holds the photo's URL, however it could be any other>d since that holds the photo’s URL. &nbsp;Howeverit could be an
> variable, a static value, or a combination of both.>y other variable, a static value, or a combination of both.
n120      Of course, we can't really see the photos, since the tree'sn138      Of course, we can’t really see the photos, since the tree’s
> rows are too small. Normally, you wouldn't put photos in a tree > rows are too small! It’s not normal to put photos in a tree like
>like this; instead the images would be used for icons. However, y> this—instead, the images would be used for icons. On the other h
>ou could use a stylesheet to change the default height of the tre>and, you could use a stylesheet to change the default height of t
>e rows. You cannot make each row a different height, but you can >he tree rows. You cannot make each row a different height, but yo
>change the height of all rows with some CSS:>u can change the height of all rows with some CSS:
n128      Since no elements are constructed by the tree builder, you n146      Since no elements are constructed by the tree builder, you 
>cannot use the style or class attributes to change the style of a>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> cell (This is the case with all trees). You must use syntax like
> that above to change the appearance. In the example above, it ch> that above to change the appearance. In the example above, it ch
>anges the height of a row to 150 pixels. You may want to change t>anges the height of a row to 150 pixels. You may want to change t
>he syntax to refer to a specific &lt;treechildren&gt; element rat>he syntax to refer to a specific&nbsp;{{ XULElem("treechildren") 
>her than all of them. Once the row height is changed, we can see >}}&nbsp;element rather than all of them. Once the row height is c
>the <a class="external" href="http://developer.mozilla.org/sample>hanged, we can see the <a class="external" href="http://developer
>s/xultemp/template-guide-ex31b.xul">entirety of the photos</a>.>.mozilla.org/samples/xultemp/template-guide-ex31b.xul">full photo
 >s</a>.
n134      Since we need to use special CSS for trees, the properties n152      Since we need to use special CSS for trees, the <code>prope
>attribute on a cell becomes useful. It can be used to define extr>rties</code> attribute on a cell becomes extremely useful. &nbsp;
>a properties that can be refered to in a stylesheet. For example,>It can be used to define extra properties for reference later in 
> if the properties attribute was set to the value "?creator", you>a stylesheet.
> could style the photos created by different people differently.  
>You can also use static values in addition to variables in the pr 
>operties attribute. For instance, consider the following CSS: 
153    </p>
154    <p>
155      For example, if the properties attribute was set to the val
 >ue "?creator", you could style the photos created by different pe
 >ople differently. Alternatively, you could also use static values
 > (in addition to variables) in the <code>properties</code> attrib
 >ute. For instance, consider the following CSS:
n142      This would set the background colour of a cell to green forn163      This would set the background color of a cell to green for 
> any cell with the "Dave" property. You can also use the properti>any cell with the “Dave” property. You can also use the propertie
>es attribute on the &lt;treerow&gt; to change the style for an en>s attribute on the&nbsp;{{ XULElem("treerow") }}&nbsp;to change t
>tire row. This example sets the country associated with a photo a>he style for an entire row. This example sets the country associa
>s a property of a tree's rows. We can use that property to change>ted with a photo as a property of a tree’s rows. We can use that 
> the appearance of each row.>property to change the appearance of each row.
t168      You might use the following CSS to change the border aroundt189      You might use the following CSS to change the border around
> rows with a particular country:> rows listing a particular country:

Back to History