Neil's Place

August 9, 2005

8:00 PM How Templates Work XXXIV - Rebuilding Templates

The datasource associated with the template can be retrieved using the element's "database" property. It implements the nsIRDFCompositeDataSource interface. Since this is a composite datasource, it may contain more than one datasource. These may be listed in the datasources attribute separated by spaces. For example:

<vbox datasources="template-guide-photos5.rdf template-guide-streets.rdf">

Sometimes, you will want to calculate the datasource to be used and attach it to the template later. You can do this using the composite datasource's AddDataSource method. You can add as many datasources as you wish, and you can remove them using the RemoveDataSource method. A common pattern is to use the following:

var RDF = Components.classes["@mozilla.org/rdf/rdf-service;1"].
            getService(Components.interfaces.nsIRDFService);
var ds = RDF.GetDataSource("http://www.xulplanet.com/ndeakin/tests/xul/template-guide-streets.rdf");
var tree = document.getElementById("theTree");
tree.database.AddDataSource(ds);
tree.builder.rebuild();

This is the typical way to add a datasource to an element, in this case to the tree with the id "theTree". The datasource is retrieved using the RDF service's GetDataSource method. After adding a datasource, the tree builder's rebuild method is invoked to rebuild the template with the new data. This doesn't happen automatically when you add the datasource, which is useful, since you will often want to add or remove other datasources at the same time.

The composite datasource can only be accessed from privileged code, regardless of what datasources it contains. Fortunately in this situation, you can just set the datasources attribute (or the corresponding property) to the datasources that you want. For instance:

var tree = document.getElementById("theTree");
tree.datasources = "template-guide-photos5.rdf template-guide-streets.rdf";

This will also change the datasources used. In this case, the template will be rebuilt automatically as you can set all of the datasources at once with this method of changing datasources. So you don't need to call the rebuild method. You can also do the same with the ref attribute (or the ref property) and the template will be rebuilt automatically. In the example above, there will be two datasources attached to the tree. They will both be loaded and the template reconstructed. Note that if one of the datasources is already loaded it will not be loaded again. This is convenient when you want to simply add a new datasource to an existing template without reloading existing data. If you do want to reload the data, you can call the builder's refresh method:

tree.builder.refresh();

This will reload the datasource attached to the template. If there is more than one datasource, as above, all of them will be reloaded. Due to the nature of the way templates are updated, you don't usually need to rebuild a template after a refresh call, although there may situtations where this will be necessary.

If you do plan on determining the datasources dynamically, it is common to start with an empty datasource using the special URI "rdf:null".

<tree datasources="rdf:null" ref="http://www.xulplanet.com/rdf/myphotos">

This will create a composite datasource with no datasources in it. This syntax is necessary as otherwise you wouldn't be able to specify a value for the datasources attribute, and a template builder would not be attached to the element. In a chrome context, the datasource rdf:local-store is always included even if you don't specify it. This is something to watch out for if you are going to be manipulating the composite datasource.

One more note: the datasources attribute may use either absolute or relative URLs. Relative URLs are relative to the XUL document the corresponding element is in. The RDF service's GetDataSource method however, only accepts absolute URLs. So you will need to use the full path in this situation.

Comments ( 0 )

August 6, 2005

10:48 AM How Templates Work XXXIII - Attaching the Template Builder

When inserting an element into a XUL document, the element is checked to see if it has a datasources attribute. If so, a template builder will be created for the element and attached to the element. If the element is a <tree> element and has the flags attribute set to "dont-build-content", a tree builder will be created. Otherwise, a content builder will be created. Both types of builder share much of the same code except for how they generate output to be displayed. Both types of builders implement the nsIXULTemplateBuilder interface, while the tree builder also implements the nsIXULTreeBuilder interface.

The builder associated with an element is accessible via the element's "builder" property both for content builders and for tree builders. An element that does not have a builder will have this property set to null. The processes of creating a builder for an element applies both when an element is created when the window is loaded and when an element is inserted dynamically.

Templates can only be used in XUL documents, however, there is no requirement that the templates generate XUL elements. They could also be used, for example, to generate HTML elements. This isn't a very common technique, however, here is an example of how this can be used:

<html:div id="photosList" datasources="template-guide-photos5.rdf"
          ref="http://www.xulplanet.com/rdf/myphotos"
          xmlns:html="http://www.w3.org/1999/xhtml">
  <html:h1>My Photos</html:h1>
  <template>
    <html:p uri="rdf:*"><textnode value="rdf:http://purl.org/dc/elements/1.1/title"/></html:p>
  </template>
</html:div>

This example generates three paragraphs. Some static content before the <template> element displays a <h1> header. Since templates were designed for creating XUL content, sometimes there can be unusual results when using HTML. Sometimes this is due to different whitespace handling for HTML and XUL, which is why the content to generate in the above example is all on one line. If you do plan on generating non-XUL content with a template, just watch out for issues like this. Note that this particular whitespace issue has been fixed in later Mozilla builds.

Note also that the datasources attribute has been placed on a non-HTML element. This is also allowed. However, one thing to watch out for is that non-XUL elements do not have their content generated lazily so all of the content will be generated at once. Be careful that your templates do not recurse to deep levels.

The builder property is a property of the nsIDOMXULElement interface, so all XUL elements will have this property, although, as mentioned earlier, is will be set to null for most elements. For non-XUL elements, the template builder will be assigned to a builder property on the element using a custom JavaScript property instead.

The main purpose of accessing the builder for an element is to call its "rebuild" method. This method removes any existing generated content and deletes all data in the rule network. Then, the method recompiles the rules and regenerates the content. Essentially, the rebuild method instructs the builder to remove any existing information and reconstruct it from the beginning. The only difference is that the datasource has already loaded so the data will be the same. However, this is often used if you modify the datasource or modify the rules.

The builder's refresh method, however, will reload the datasources. It will not rebuild the template, but we'll see in a later section why this is not usually necessary. To summarize, the refresh method reloads the data, whereas the rebuild method reconstructs the content.

The builder is accessible to unprivileged code, so the rebuild and refresh methods may be called by remote code.

We'll see some examples of rebuilding templates next.

Comments ( 2 )

August 1, 2005

9:09 PM How Templates Work XXXII - Hierarchical Trees

A template may be used to generate hierarchical trees. This works just like with recursive generation using the content builder. Each level of the tree is created using a successive iteration of the template build process. If the items are containers, the tree builder will mark the right rows as containers, so that they can be opened and closed with the small icon twisties on the left of the column. Remember to make the left column the primary column for these to appear.

To be able to do this, the tree builder must know that an item is a container. Usually you would display a tree from data in an RDF container such as a Seq. In this case, determining that the node is a container is easy. If a node is a RDF container, the tree item becomes a container, and the user may open the row by double-clicking it. Note that this test is done on the member value not the reference value. For instance, in the photo example, we have a container "http://www.xulplanet.com/rdf/myphotos" with three photos. Three results will be generated from a simple rule with no extra conditions. It is the result, or the photo, that will be checked, not the container of photos. Since a photo isn't a container, the tree rows will not become containers, so you will not be able to open them. As the rows are not containers, the tree builder does not recurse to find additional data. The tree builder creates rows lazily, so a closed container will not have any data generated inside in it until the row is opened. When the user opens the tree row, the next level of rows are generated from the template and displayed in the tree. Similarly, when the user closes a tree row, the rows inside it are removed, such that they will have to be generated again the next time the row is opened.

If you want to put rows inside the photo rows, you will either need to make each photo resource an RDF container, or use the containment attribute to specify additional properties that indicate containership. If a particular photo had a value for one of the properties listed in the containment attribute, it would be accepted as a container, and the user could open the row. When the user opens the row, the template will be re-examined for results using the photo as the starting point instead of the top level ref value.

Here is an example for the streets datasource:

<tree id="photosList" flex="1" datasources="template-guide-streets.rdf"
      ref="http://www.xulplanet.com/rdf/myneighbourhood" flags="dont-build-content"
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
  <treecols>
    <treecol id="address" primary="true" label="Address" flex="1"/>
    <treecol id="floors" label="Floors" flex="1"/>
  </treecols>
  <template>
    <rule rdf:type="http://www.xulplanet.com/rdf/House">
      <treechildren>
        <treeitem uri="rdf:*">
          <treerow>
            <treecell label="rdf:http://www.xulplanet.com/rdf/address"/>
            <treecell label="rdf:http://www.xulplanet.com/rdf/floors"/>
          </treerow>
        </treeitem>
      </treechildren>
    </rule>
    <rule>
      <treechildren>
        <treeitem uri="rdf:*">
          <treerow>
            <treecell label="rdf:http://purl.org/dc/elements/1.1/title"/>
          </treerow>
        </treeitem>
      </treechildren>
    </rule>
  </template>
</tree>

This is similar to a previous example except that it uses a tree. The first rule is for the houses as indicated by the rule's condition and the second rule is for the streets. As shown in the snippet of the data below, the street is a Seq, so it will become a container. The houses are not containers, so they will not have children in the tree.

<rdf:Bag rdf:about="http://www.xulplanet.com/rdf/myneighbourhood">
  <rdf:li>
    <rdf:Seq rdf:about="http://www.xulplanet.com/rdf/marion"
               dc:title="Marion Street">

The result is a two level tree with two columns.

Comments ( 0 )

July 31, 2005

8:23 PM How Templates Work XXXI - Tree Builder Features

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.

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 like this; instead the images would be used for icons. However, 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 <treechildren> element rather than all of them. Once the row height is changed, we can see the entirety of the photos.

Since we need to use special CSS for trees, the properties attribute on a cell becomes useful. It can be used to define extra properties that can be refered to 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. You can 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 colour of a cell to green for any cell with the "Dave" property. You can also use the properties attribute on the <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>
  <conditions>
    <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"/>
  </conditions>
  <action>
    <treechildren>
      <treeitem uri="?photo">
        <treerow properties="?countrytitle">
          <treecell src="?photo" label="Cat"/>
        </treerow>
      </treeitem>
    </treechildren>
  </action>
</rule>

You might use the following CSS to change the border around rows with 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.

Comments ( 0 )

July 27, 2005

7:21 PM How Templates Work XXX - Building 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 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.

Comments ( 0 )

July 23, 2005

10:42 PM How Templates Work XXIX - Using Multiple Rules to Generate More Results

One interesting technique is to use several rules to combine two sets of unrelated data together. To do this, we create one rule to generate one set of results and a second rule to generate another set of results. If a result from the second rule wasn't also matched by the first rule, it will have content created for it. Recall that when the member resource for a rule matches several rules, only the earliest rule that matches will have content generated for it. If resources don't overlap, we can generate content for two different parts of the RDF data. This technique isn't commonly used. Usually, all of the rules will be similar but just have different filters to match based on different criteria.

If we add the following data about people to the neighbourhood datasource:

  <rdf:Description rdf:about="http://www.xulplanet.com/rdf/myneighbourhood">
    <r:people>
      <rdf:Seq>
        <rdf:li rdf:resource="http://www.xulplanet.com/rdf/person/1"/>
        <rdf:li rdf:resource="http://www.xulplanet.com/rdf/person/2"/>
      </rdf:Seq>
    </r:people>
  </rdf:Description>
  <rdf:Description rdf:about="http://www.xulplanet.com/rdf/person/1"
                   dc:title="Nathan"/>
  <rdf:Description rdf:about="http://www.xulplanet.com/rdf/person/2"
                   dc:title="Karen"/>

We can then use two rules to generate results from different parts of the datasource. The first rule will match the streets as before, but the second rule will generate a result for each person. A header class is used to distinguish the content, although you could use exactly the same content if you wish.

<template>
  <rule>
    <conditions>
      <content uri="?start"/>
      <member container="?start" child="?item"/>
    </conditions>
    <bindings>
      <binding subject="?item" predicate="http://purl.org/dc/elements/1.1/title" object="?title"/>
    </bindings>
    <action>
      <label uri="?item" value="?title" class="header"/>
    </action>
  </rule>
  <rule>
    <conditions>
      <content uri="?start"/>
      <triple subject="?start" predicate="http://www.xulplanet.com/rdf/people" object="?people"/>
      <member container="?people" child="?item"/>
    </conditions>
    <bindings>
      <binding subject="?item" predicate="http://purl.org/dc/elements/1.1/title" object="?title"/>
    </bindings>
    <action>
      <label uri="?item" value="?title"/>
    </action>
  </rule>
</template>

You can view the example.

Comments ( 2 )

July 21, 2005

6:34 PM How Templates Work XXVIII - Parent Conditions

Sometimes you want to simply generate one block of content at the top level and different content at the recurisive level. For example, the bookmarks toolbar in Firefox displays buttons at the first level, but menus and submenus for content below that. The entire bookmarks toolbar is generated by a XUL template.

Templates have a means of allowing a rule to match only if the generated content would be inserted inside an element with a particular tag name. For instance, if the container was a <vbox>, a rule could be created that would only match a <vbox> element. This is useful for recursive templates, since the inner iterations may use different content. It's most useful to distinguish between the outer and inner levels during template generation. For the bookmarks toolbar, the outer content is inserted into an <hbox>, but at lower levels, the content will be inserted into a <menu>

In case you aren't clear, the tag that must match for the outer iteration is the root element, the one with the datasources attribute on it. For inner iterations, it will be the element with the uri attribute from the previous iteration.

To do this kind of matching for the simple template syntax, you place a parent attribute on the rule, set to the tag to match. For instance, we might use the following:

<vbox datasources="template-guide-streets.rdf"
            ref="http://www.xulplanet.com/rdf/myneighbourhood">
  <template>
    <rule parent="vbox">
      <groupbox uri="rdf:*">
        <caption label="rdf:http://purl.org/dc/elements/1.1/title"/>
      </groupbox>
    </rule>
    <rule>
      <label uri="rdf:*" value="rdf:http://www.xulplanet.com/rdf/address"/>
    </rule>
  </template>
</vbox>

On the first pass, the container where generated content would be inserted is a <vbox>, so the first rule will match and a captioned <groupbox> will be created. On the next pass, the parent container will be the element with the uri attribute from the previous pass, in this case, the <groupbox> The first rule will not match in this case, but the second rule will match and a label will be created. The result can be seen in you try the example.

A tag test can also be used with the extended syntax, although the syntax for using it is different. Instead of placing a parent attribute on the <rule>, you place a tag attribute on the <content> tag in the conditions. For instance, the equivalent tag test using the extended syntax for the previous example is the following:

<content uri="?start" tag="vbox">

This example generates the same output content as when using the simple template syntax.

As we've seen in the past few examples, there are many different ways of structuring the two rules to match differently at different levels. General triple tests, tests on an RDF type, container tests and parent tag tests all provide a wide variety of ways to match in very specific ways. Of course, in the simple examples we've been using, the advantages of one kind of condition test over another are not obvious. In more complex examples however, you will see the benefit of one test over others depending on the structure of the data and the UI that you wish to create. By combining the different types of conditions together, more complex interfaces can be created just with templates.

Comments ( 0 )

July 18, 2005

8:18 PM XUL Tutorial Now Part of the Mozilla Developer Documentation

In case you haven't noticed, the XUL tutorial is now available as part of the Mozilla Developer Documentation site. An advantage of this is that errors can be corrected quickly and by anyone who spots them. The user notes created by users haven't been transfered though. I'm not sure if that's a good thing or not.

The user notes include a number of useful tips that people have written relating to a particular page. Currently the user notes aren't posted until I actually read them. This is a good thing since half of the notes are either questions (which I usually just ignore), or are misleading or incorrect. On one hand, I don't want to discourage someone by not accepting a comment they've made, but on the other hand, I feel that if a comment is misleading or uses, for example, some code that is a bad way of doing something, I don't want to post it, since the point of the user notes is to improve the documentation.

Anyway, I think there are plans on posting some other XULPlanet stuff, and I also plan on posting the template guide I've been writing on here. The Aaron countdown timer seems to have disappeared recently perhaps indicating his return a few days early so maybe the App tutorial or Prefbar will get updated also.

In other news, I've been hacking a bit at templates using XML data. Here's the first ever image of a XUL template fed with only XML input. It doesn't look very exciting but that's because the excitment is in disguise. Vlad's just reviewed the main part of the code for this, so we could very well see this stuff early in the 1.9 timeframe.

Comments ( 3 )