A XUL template is made up of series of rules. Each rule contains two things, a set of instructions for navigating through an RDF graph and some XUL content to generate. Given a starting point, the template builder will evaluate the navigation instructions for each rule and will generate a series of endpoints matching that rule. The corresponding content will then be generated. It's actually more complicated than that but this is the basic idea.

There are two syntaxes for declaring the rules, the simplified syntax and the extended (or full) syntax. As its name implies, the simplified syntax is simpler but is limited in the type of data that it can iterate over. It may be used to iterate over one and only one arc (or arrow) in the RDF graph. The extended syntax may navigate anywhere in the graph. Almost always, the simplified syntax will be used to iterate over a set of children of an RDF container like a Seq. An RDF Seq is a container that contains children in a specific order. The template will generate these results in that order.

The simplified syntax is a subset of the extended syntax, that is, it is possible to rewrite a rule that uses the simplified syntax using the extended syntax. In fact, the template builder will internally convert the simpler rule into an extended syntax rule for use. Neither syntax is preferred; you may use the extended syntax exclusively if it feels more natural to you. Note however, that the simplified syntax uses a slight optimization when using more than one rule which the extended syntax does not use. Well look at this in more detail as we look more at rules.

Each rule is declared using the <rule> tag, which you would place directly inside the <template> element. You may have as many rules as you wish, or you may have only one. When using the simplified syntax, you may omit the <rule> element when you have only one rule as its usage will be implied. The extended syntax, however, always requires the <rule> element.

Here is the outline of the template syntax so far.

<vbox datasources="http://www.xulplanet.com/ds/sample.rdf"
         ref="http://www.xulplanet.com/rdf/A" flex="1">
  <template>
    <rule>
      -- rule content goes here --
    </rule>
    <rule>
      -- rule content goes here --
    </rule>
  </template>
</vbox>

When the template builder starts processing, and after it has started the datasource loading, it first must compile the rules. This step involves working through the rules and processing them into internal structures. Thus, changing the rule elements around dynamically doesn't affect anything. However, rebuilding the template (using the builder.rebuild method) will recompile the rules and reapply the template again. This means that you can change the rules using DOM methods, rebuild the template, and get different results.