Neil's Place

June 11, 2005

11:10 AM How Templates Work IX

The previous example generated only a set of buttons, but the action body may contain additional content. For instance, you might want to add a label to each item.

<action>
  <hbox uri="?relateditem">
    <label value="Related Item:"/>
    <button label="?relateditem"/>
  </hbox>
</action>

In this example, the <hbox> will be generated for each result, assigned an id of the value of the ?relateditem, and the label and button will be added inside it. The button's label will be the value of the ?relateditem variable. You would only use the uri attribute on a single element since only one of the generated elements should be given a particular id.

Although the uri attribute should only be on one element, it does not have to be the outermost element in the action body. You can place other elements outside this to serve as containers for all the results. One difference is that this content is only generated once, not for every result. Only the content at the element with the uri attribute and below is copied for each result. For example, if the example was modified to the following:

<action>
  <toolbar>
    <button uri="?relateditem" label="?relateditem"/>
  </toolbar>
</action>

Here, only the button would be repeated for each result; the toolbar will only be generated once. The toolbar is created just before the content for the first result is generated. The effect will be a toolbar with a set of three buttons inside it. Of course, in this simple example you would really just make the toolbar the outer element with the datasources attribute rather than placing inside the action.

So far we have only be using the ?relateditem variable since that is really the only useful variable that is available. We could also use the ?start variable. Recall the results:

(?start = http://www.xulplanet.com/rdf/A, ?relateditem = http://www.xulplanet.com/rdf/B)
(?start = http://www.xulplanet.com/rdf/A, ?relateditem = http://www.xulplanet.com/rdf/C)
(?start = http://www.xulplanet.com/rdf/A, ?relateditem = http://www.xulplanet.com/rdf/D)

We could display the value of the ?start variable in the results if desired:

<action>
  <hbox uri="?relateditem">
    <button label="?start"/>
    <button label="?relateditem"/>
  </hbox>
</action>

For the first button, the value of the variable ?start will be looked up in the result data while the second button will use the ?relateditem variable. Since all three results have the same value for the ?start variable, the result will be that the first buttons in each row will all have the same label. Here is an image of this example

You'll notice that the second row has an extra two buttons. We'll see why next.

Comments ( 6 )

June 9, 2005

6:58 PM How Templates Work VIII

The content to generate in a template is specified using the <action> element which should be a direct child of a <rule> element. The content goes directly inside the <action> element. This content will be copied for each matching result and inserted into the document. Let's look at a simple example first.

<vbox datasources="http://www.xulplanet.com/ds/sample.rdf"
         ref="http://www.xulplanet.com/rdf/A">
  <template>
    <rule>
      <conditions>
        <content uri="?start"/>
        <triple subject="?start"
                predicate="http://www.xulplanet.com/rdf/relatedItem"
                object="?relateditem"/>
      </conditions>
      <action>
        <button uri="?relateditem" label="?relateditem"/>
      </action>
    </rule>
  </template>
</vbox>

This action contains only one element, but you can put as many or as few elements as you need. In this case, a button will be created for each result. There are three results, so three buttons will be created. Here is the example, and an image of what it looks like:

The template builder iterates through the three results, processesing the body of the action for each one in turn. The uri attribute on the button is used to specify the ending or member variable. In this example, there's only one variable to use, ?relateditem, since ?start is the starting point and the start and end points cannot be the same. There are a number of things that will happen for each result. Let's look at the results again:

(?start = http://www.xulplanet.com/rdf/A, ?relateditem = http://www.xulplanet.com/rdf/B)
(?start = http://www.xulplanet.com/rdf/A, ?relateditem = http://www.xulplanet.com/rdf/C)
(?start = http://www.xulplanet.com/rdf/A, ?relateditem = http://www.xulplanet.com/rdf/D)

The builder will start with the first result. The <button> element will be copied and inserted into the document after the template. The id attribute of the new element will be set to the same value of the member variable, ?relateditem. You could think of this as changing the uri attribute to the id attribute, and replacing the variable. Since the first result has a value of "http://www.xulplanet.com/rdf/B" for the ?relateditem variable, the id will be set to this value.

Then, the remaining attributes on the element are examined and any variables are replaced in place. That is, the text ?relateditem in the label attribute will be replaced with the string "http://www.xulplanet.com/rdf/B" for the first result. In the image, you can see that the label for the first button does indeed have this value. Processing is now complete for the first result, so the builder moves on to the next result. For result B, the builder would have generated the following content:

<button id="http://www.xulplanet.com/rdf/B" label="http://www.xulplanet.com/rdf/B"/>

Naturally, you wouldn't use an id attribute inside a template action since the id would be replaced anyway. In fact, any ids you put inside a template action will be ignored. However, you may use ids on the other parts of the template, such as within the conditions, if you wish to change the conditions and rebuild the template. You can use getElementById to get at particular results, for instance document.getElementById("http://www.xulplanet.com/rdf/C") would retrieve the second generated button.

After all the results have been examined, the DOM tree will look like the following:

<vbox datasources="http://www.xulplanet.com/ds/sample.rdf"
         ref="http://www.xulplanet.com/rdf/A">
  <template>
    <rule>
      <conditions>
        <content uri="?start"/>
        <triple subject="?start"
                predicate="http://www.xulplanet.com/rdf/relatedItem"
                object="?relateditem"/>
      </conditions>
      <action>
        <button uri="?relateditem" label="?relateditem"/>
      </action>
    </rule>
  </template>
  <button id="http://www.xulplanet.com/rdf/B" label="http://www.xulplanet.com/rdf/B"/>
  <button id="http://www.xulplanet.com/rdf/C" label="http://www.xulplanet.com/rdf/C"/>
  <button id="http://www.xulplanet.com/rdf/D" label="http://www.xulplanet.com/rdf/D"/>
</vbox>

Since the <template> tag is hidden, the effect will be like in the image, three buttons with the labels of the data in the datasource.

Next, we will look at a more complex example.

Comments ( 7 )

June 8, 2005

6:59 PM How Templates Work VII

After, the <content> tag has been examined, the builder moves on to the next condition, the <triple> which looks like this:

<triple subject="?start"
        predicate="http://www.xulplanet.com/rdf/relatedItem"
        object="?relateditem"/>

The <triple> condition is used to follow arcs or arrows in the RDF graph. The predicate attribute specifies the labels of the arrows to follow. In the triple used here, the predicate is "http://www.xulplanet.com/rdf/relatedItem", so we know that the builder will look for arrows with that label. The builder can either follow the arrows in a forward or backward direction, but only one direction per condition. It determines which direction to use by examining which data is known and which data is not known yet. Recall the data in the potential results set:

(?start = http://www.xulplanet.com/rdf/A)

This was the seed data created by the <content> condition. You might be able to guess that the builder fills in the value of the ?start variable as the triple's subject, giving something like this:

<triple subject="http://www.xulplanet.com/rdf/A"
        predicate="http://www.xulplanet.com/rdf/relatedItem"
        object="?relateditem"/>

The builder doesn't actually change the triple, but this might clarify how the builder is working. The builder looks at both the subject and object of the triple and tries to resolve any of the variables using the known data. The ?start variable has a value "http://www.xulplanet.com/rdf/A", so that is filled in. The ?relateditem variable doesn't have any known value, so it will be left as is. Once the variables are filled in, the builder can query the RDF graph.

The query will look for all arrows that start at the node "http://www.xulplanet.com/rdf/A" with the predicate, or arrow label "http://www.xulplanet.com/rdf/relatedItem". Since ?relateditem isn't known, the builder will allow any value for the node the arrow points to, and will look in the datasource for all possible values. In a <triple> condition, the subject is always the start of an arc, while the object is what it points to. For this triple, the builder will follow the arrows in the forward direction. Here is the RDF graph again:

Starting at node A and following the relatedItem arcs, we can see that there are three possible values for the ?relateditem variable, B, C and D. This is new data, so the builder adds it to the graph. Since three values have been found, the network will now have three potential results:

(?start = http://www.xulplanet.com/rdf/A, ?relateditem = http://www.xulplanet.com/rdf/B)
(?start = http://www.xulplanet.com/rdf/A, ?relateditem = http://www.xulplanet.com/rdf/C)
(?start = http://www.xulplanet.com/rdf/A, ?relateditem = http://www.xulplanet.com/rdf/D)

You may note that the ?start variable is repeated for each result. This is because the builder copies the existing data for each new potential result and adds the new data. Internally, this isn't quite true; the builder actually maintains only one copy of the similar data but uses data structures in such a way which make it appear as if it is duplicated.

You may find this a bit confusing, but this should become clearer later with more specific and practical examples.

Since the <triple> was the last condition, the builder moves on to the content generation phase, creating matches out of the three potential results.

Comments ( 7 )

June 6, 2005

3:22 PM How Templates Work VI

Let's look at a simple rule with two conditions. The conditions are enclosed in a <conditions> tag which is placed directly inside the <rule> tag. Each condition is placed inside the <conditions> tag.

<vbox datasources="http://www.xulplanet.com/ds/sample.rdf"
         ref="http://www.xulplanet.com/rdf/A" hidden="true">
  <template>
    <rule>
      <conditions>
        <content uri="?start"/>
        <triple subject="?start"/>
                predicate="http://www.xulplanet.com/rdf/relatedItem"/>
                object="?relateditem"/>
      </conditions>
      ...
    </rule>
  </template>
</vbox>

This rule has two conditions, each specified with a different tag. The template won't generate anything yet since we still need to fill in the content to be generated which goes in the missing part after the conditions. However, the template builder will be able to compile the rules and examine them as described earlier.

The builder needs to start with a single result as the seed result. This is done with the <content> tag. It indicates that we are going to use a starting point when navigating the graph. Obviously, since you need to start somewhere, you will have to use a <content> tag and it should be the first condition. Also, because we can only have one starting point, only one <content> tag can be used. The seed result will be created like this:

(?start = http://www.xulplanet.com/rdf/A)

The variable ?start is determined from the tag's 'uri' attribute. You can use any variable you want; it's common to use the variable ?uri. However, all rules must use the same starting point variable. So if a second rule were used, it would also need to use the ?start variable. The value of ?start is set to 'http://www.xulplanet.com/rdf/A'. You'll notice that this is the value of the ref attribute which is the desired starting node in the RDF graph. Thus, the ?start variable becomes the container or reference variable.

The <content> tag doesn't do anything else at this point, meaning it doesn't add anything else to the network of potential results, so processing continues on to the next condition, the <triple>

Actually, in the current templates implmentation, the above description isn't quite correct. The seed is a actually an internal variable set to the container, in this case, the <vbox>, and the ?start variable is set to the ref later, but that is a minor detail that doesn't make templates more understandable. For this discussion, assume that so far we have a single potential result as above.

Comments ( 9 )

June 4, 2005

8:07 PM How Templates Work V

During rule processing, the template builder builds up a network of information such as what possible results are available, where content should be generated, and information that indicates what to do when the RDF datasource changes. This network of information remains for the lifetime of the template, or until it is rebuilt. The template builder uses an method based on the RETE algorithm to match data. This allows for a fairly efficient means of updating results when, for instance, a new statement is added to the RDF graph. Rather than rebuild the entire template, the algorithm allows only specific parts of the network of information to be re-examined. A similar method can be used when removing RDF statements.

While the information network created by the template builder contains a number of different pieces of necessary information, for the purposes of this discussion, we will only be interested in the list of possible results. The builder begins with a single possible result, called the seed. The builder processes each of a rule's conditions in sequence. To do this for a particular condition, it iterates over the possible results found so far and either accepts each result or rejects each result. For the first condition, only the seed will be available as a possible result. At each step, new possible results may be added, or more information pertaining to an existing result may be added to the network. Naturally, a rejected result will be removed. Once all results have been examined, the builder moves on to the next condition. Once all conditions have been analyzed, any results which still remain go on to become matches. The matches are the endpoints and will cause content to be generated. So, to summarize:

  1. Start out with a one possible result as the seed
  2. Iterate over the results determined so far and augment them with additional data
  3. Add any new possible results
  4. Remove any rejected results
  5. Repeat steps 2 to 4 for each rule condition
  6. Once done, all remaining results become matches

Each possible result is made up of a set of variable-value pairs. For instance, a result would look something like the following:

(?name = Fred, ?age = 5)

This result has two variables, ?name with the value 'Fred' and ?age with the value 5. Variables begin with a question mark, and values are RDF resources or literals. Here we will use strings for the values so they are easier to read. If we had two results, they might look like this:

(?name = Fred, ?age = 5)
(?name = Mary, ?age = 12)

This is how we'll represent the potential results in this and the following discussions.

Later, we might have a condition which removes all Male results. So, our results after this might look like the following:

(?name = Mary, ?age = 12, ?gender = Female)

This condition has removed Fred from the potential results and added the ?gender variable for Mary. This is typical of how a rule condition works, by adding additional variables to a result and filtering out those that don't match a particular value. If this was the last condition, Mary would go on to become a match to be displayed.

Comments ( 5 )

June 3, 2005

4:10 PM How Templates Work IV

Once the template builder has compiled the rules, rule processing and content generation can begin. The template builder generates content lazily, that is, it processes as little as need, and only continues when necessary. For instance, consider the example below:

<vbox datasources="http://www.xulplanet.com/ds/sample.rdf"
         ref="http://www.xulplanet.com/rdf/A" hidden="true">
  <template>
    ...
  </template>
</vbox>

The <vbox> is hidden as indicated by the 'hidden' attribute. Since any content that would be generated wouldn't be displayed anyway, the template builder doesn't do anything, putting off work until later. If you show the vbox by setting the hidden state to false, the template builder will be invoked and the content will be generated.

Does this mean that templates cannot be used inside hidden areas of the UI? No, you can still do that. Changing the hidden state of an element isn't the only way to cause content to be generated. Calling a DOM API which needs to get at the generated content will cause the template builder to generate output. For example, just calling the code like the following on the hidden vbox above will start off the template builder.

var length = vbox.childNodes.length;

This request to return the number of children of the vbox will make the template builder process the rules and output content. Once done, the correct length can be returned.

All of this is transparent to the XUL developer. When the template builder decides to start generation is determined automatically and you don't need to do anything special to get this to happen. However, there are two cases where content is not generated automatically: menus and child tree items.

Content inside a menu is not generated until the menu is opened. This makes sense since the user can't see the contents of the menu until it is open. However, it also means that the DOM API usage, such as an attempt to get the number of child nodes as above, will also not include generated items until the menu is opened. This is an important distinction. That means that you will not be able to rely on being able to retrieve the generated menu items until the menu is opened. A similar rule applies for child tree items. The children are not generated until the user presses the twisty to open the container, or a script opens a row.

Lazy generation comes in handy for menus and trees especially when dealing with recursive items. It would be rather time consuming to generate output for every item in a tree, even for those not displayed, so the template builder doesn't do so.

The template builder is even lazier. If the generated content itself contains hidden elements, those child elements will not be generated until necessary. When building content, the builder iterates down the node tree, copying and building only when needed.

Next, we'll look into how the template builder processes the rules.

Comments ( 9 )

June 2, 2005

6:26 PM How Templates Work III

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.

Comments ( 7 )

June 1, 2005

2:45 PM How Templates Work II

RDF is, in mathematical terms, a labeled directed graph. That means that RDF is a graph of nodes and arrows between them where each node and arrow has some label. Since it's a graph, arrows can point all over the place and nodes can have any number of arrows pointing out of them and pointing at them. And also because it is a graph, there is no real starting point or root node so you can just start anywhere. In the picture below, you can see that node A at the top has arcs pointing to B, C and D. As well, C has an arc pointing to D. You could have arcs pointing elsewhere, for example node D could have an arc pointing back to A. To navigate around, you could start at node A and navigate around the graph following the arrows to B, C or D. Or you could start at B and go to A and then go to C and D. No requirement exists to follow the arrows in the direction they point; you can easily go the other way. The picture was generated from the W3C's RDF validator, a good place to go to check if your RDF is valid.

The text in red are the labels for the arrows, called predicates. In this example, all the arrows have the same label. Usually, this won't be the case. Templates provide a means of navigating around using only arrows with specific labels. Here is the serialized RDF/XML for this graph.

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:rel="http://www.xulplanet.com/rdf/">
  <rdf:Description rdf:about="http://www.xulplanet.com/rdf/A">
    <rel:relatedItem rdf:resource="http://www.xulplanet.com/rdf/B"/>
    <rel:relatedItem rdf:resource="http://www.xulplanet.com/rdf/C"/>
    <rel:relatedItem rdf:resource="http://www.xulplanet.com/rdf/D"/>
  </rdf:Description>
  <rdf:Description rdf:about="http://www.xulplanet.com/rdf/C">
    <rel:relatedItem rdf:resource="http://www.xulplanet.com/rdf/D"/>
  </rdf:Description>
</rdf:RDF>

For a XUL template query, you first need to select a starting point in the RDF graph. Once you have selected a starting point, you use a number of statements which indicate where to go next when navigating the graph. Eventually, you will end up with a set of nodes you consider the endpoints of your query. These become the results and content would be generated for each of these results. Say you start at A. You could navigate to B, C and D and generate three blocks of output. Or, you could start at D and follow two arrows back. This will get two results, A and B. Look at the graph to see if you can see why two results would be generated in this case.

In XUL template terminology, the starting point is called the container or reference point and the endpoint is called the member. It is so called because it is most common to gather the list of the members, or children, of a container. But this doesn't have to be the case. Any starting point and ending points will do.

Nodes in RDF are identified by a string value. There are two types of nodes in RDF, resources which usually represent 'things', and literals which are values like the names of things, the dates of things, the sizes of things, and so on. A literal's value is, for example, the name of the thing, such as 'Fred'. A resource's value is a URI which for your own RDF data you can just make up. We'll use the URI of the resource nodes in a template. In the image, the resource URI's are the blue labels of each node. There are no literals in this example, but we'll see some later.

Let's say we want the starting point to be A from the above example graph. We will use A's URI (http://www.xulplanet.com/rdf/A) as the reference starting point. In a XUL template, you specify the starting point using the 'ref' attribute. Here is an example:

<vbox datasources="http://www.xulplanet.com/ds/sample.rdf"
      ref="http://www.xulplanet.com/rdf/A" flex="1">

This is an indicator that we want to construct a XUL template using the reference point with the URI 'http://www.xulplanet.com/rdf/A'. Next, we'll see how to construct the template.

Comments ( 9 )