Neil's Place

June 16, 2005

7:04 PM How Templates Work XI

Let's look a more useful example, this time for a template that will show a list of photos. In this situation, an RDF container will be used to hold the list of images.

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:dc="http://purl.org/dc/elements/1.1/">
  <rdf:Seq rdf:about="http://www.xulplanet.com/rdf/myphotos">
    <rdf:li rdf:resource="http://www.xulplanet.com/ndeakin/images/t/palace.jpg"/>
    <rdf:li rdf:resource="http://www.xulplanet.com/ndeakin/images/t/canal.jpg"/>
    <rdf:li rdf:resource="http://www.xulplanet.com/ndeakin/images/t/obelisk.jpg"/>
  </rdf:Seq>
  <rdf:Description rdf:about="http://www.xulplanet.com/ndeakin/images/t/palace.jpg"
                   dc:title="Palace from Above"/>
  <rdf:Description rdf:about="http://www.xulplanet.com/ndeakin/images/t/canal.jpg"
                   dc:title="Canal"/>
  <rdf:Description rdf:about="http://www.xulplanet.com/ndeakin/images/t/obelisk.jpg"
                   dc:title="Obelisk"/>
</rdf:RDF>

In this example, we have three images, which can be identified by urls. The resource uris correspond to their actual urls although this isn't necessary. Each image also has one property, the image's title. A template which displays this information is very simple to create. Unlike previous examples where we iterated over a property to navigate the graph, here we want to iterate over the children of an RDF container. The container, an RDF Seq, has the uri 'http://www.xulplanet.com/rdf/myphotos'. This will be the starting point of the navigation. We want the endpoints to be the three images. First, we set the datasources and ref attributes as needed:

<vbox datasources="template-guide-ex11.xul"
      ref="http://www.xulplanet.com/rdf/myphotos">

This time, we need to use a new condition, the <member> condition as well as a <triple>.

<conditions>
  <content uri="?start"/>
  <member container="?start" child="?photo"/>
  <triple subject="?photo"
          predicate="http://purl.org/dc/elements/1.1/title"
          object="?title"/>
  </conditions>

The seed is set in a similar manner as the previous examples, effectively creating a single result with the ?start variable set to the reference resource 'http://www.xulplanet.com/rdf/myphotos'. The same starting variable is used in this example, but you can of course use any variable you wish.

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

The <member> condition is used to iterate over the children of a container (or the reverse). First, any known variables are filled into the member condition for the current result. There's only one result so far; the member element's container attribute is set to value of the ?start variable of this result. This will result in the following:

<member container="http://www.xulplanet.com/rdf/myphotos" child="?photo"/>

As with processing a triple, the builder will now try to find as many values for the ?photo variable as possible and create potential results using them. The container attribute specifies the container and the child attribute specifies the children. In the RDF data, the container "http://www.xulplanet.com/rdf/myphotos" has three children, so there are three possible values for the ?photo variable. If that node had no children or wasn't a container, there would be no possible results. The data network will now look like this:

(?start = http://www.xulplanet.com/rdf/myphotos,
 ?photo = http://www.xulplanet.com/ndeakin/images/t/palace.jpg)
(?start = http://www.xulplanet.com/rdf/myphotos,
 ?photo = http://www.xulplanet.com/ndeakin/images/t/canal.jpg)
(?start = http://www.xulplanet.com/rdf/myphotos,
 ?photo = http://www.xulplanet.com/ndeakin/images/t/obselisk.jpg)

The <triple> is evaluated next, and it will be examined for each potential result found so far. The builder will first fill in as many variables as it can. For the first result, the value of the ?photo variable is known, so the triple will be evaluated like so:

<triple subject="http://www.xulplanet.com/ndeakin/images/t/palace.jpg"
        predicate="http://purl.org/dc/elements/1.1/title"
        object="?title"/>

The builder next calculates the value for ?title using the predicate 'http://purl.org/dc/elements/1.1/title'. In the RDF, the 'palace' resource has a value 'Palace from Above', so it will be added to the data network, assigned to the ?title variable. Note that this value is a literal rather than a resource.

(?start = http://www.xulplanet.com/rdf/myphotos,
 ?photo = http://www.xulplanet.com/ndeakin/images/t/palace.jpg)
 ?title = 'Palace from Above')

The process continues in a similar manner for the other two results. In the end, the network will contain the following data:

(?start = http://www.xulplanet.com/rdf/myphotos,
 ?photo = http://www.xulplanet.com/ndeakin/images/t/palace.jpg)
 ?title = 'Palace from Above')
(?start = http://www.xulplanet.com/rdf/myphotos,
 ?photo = http://www.xulplanet.com/ndeakin/images/t/canal.jpg)
 ?title = 'Canal')
(?start = http://www.xulplanet.com/rdf/myphotos,
 ?photo = http://www.xulplanet.com/ndeakin/images/t/obelisk.jpg)
 ?title = 'Obelisk')

Since the <triple> is the last condition, three matches have been found. The action body might look like the following, which displays the image using its url and title in a label. You might note that the image's src attribute uses the member variable ?photo

<action>
  <vbox uri="?photo" align="start">
    <image src="?photo"/>
    <label value="?title"/>
  </vbox>
</action>

It shouldn't be too difficult to tell what would appear in the window in this example. You can see if you guessed correctly by viewing the example.

Comments ( 8 )

June 13, 2005

7:28 PM How Templates Work X

In the previous example, the template builder generated an extra set of two buttons for the second row. However, the labels on the second set of buttons are different than the first set. If you look at the graph again, you might begin to see why. In the graph, item C has a relatedItem arrow pointing out of it to item D. This extra arrow which neither B or D have causes an extra set of buttons to be created.

After generating content, the template builder always repeats the generation for inner levels as far as it can go. Thus, the builder can be said to generate content from the graph recursively. After generating a result's content, the builder starts again using a new parent and starting point. Naturally, the parent will be the new result's content, rather than the outer containing element, and the starting point will be the endpoint of the previous iteration. In this example, for the top level generation the parent insertion point is the element with the datasources attribute, a <vbox>. For nested results, the insertion point is the generated element. Here is the content that was generated after one iteration:

<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>
        <hbox uri="?relateditem">
          <button label="?start"/>
          <button label="?relateditem"/>
        </hbox>
      </action>
    </rule>
  </template>
  <hbox id="http://www.xulplanet.com/rdf/B">
    <button label="http://www.xulplanet.com/rdf/A"/>
    <button label="http://www.xulplanet.com/rdf/B"/>
  </hbox>
  <hbox id="http://www.xulplanet.com/rdf/C">
    <button label="http://www.xulplanet.com/rdf/A"/>
    <button label="http://www.xulplanet.com/rdf/C"/>
  </hbox>
  <hbox id="http://www.xulplanet.com/rdf/D">
    <button label="http://www.xulplanet.com/rdf/A"/>
    <button label="http://www.xulplanet.com/rdf/D"/>
  </hbox>
</vbox>

For the next iteration, the insertion point will be the three <hbox> elements. However, since C is the only element that will end up having any additional content, only the second <hbox> element will have additional children added to it.

For a nested item, the builder processes the rules in the same way as usual, however instead of using the ref attribute as the seed starting point, the end point or member is used instead. This will correspond to the id on the appropriate element in the generated content above. To begin, B is evaluated and seeded with the right value:

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

The <triple> condition is then examined, however, item B doesn't have a relatedItem arc out of it, so the result is rejected. Since there are no potential results, the builder doesn't generate anything. A similar situation will occur for item D. However, for item C, the triple does match an item, so the data will be added to the potential result:

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

A match has occured, so the content within the action body will be created and added inside item C. Since the ?start variable points to item C and the ?relateditem variable points to D, the buttons will be created with these labels. If you look at the image of the example, you will see that the buttons do have these labels. The resulting content for row C will look like this:

<hbox id="http://www.xulplanet.com/rdf/C">
  <button label="http://www.xulplanet.com/rdf/A"/>
  <button label="http://www.xulplanet.com/rdf/C"/>
  <hbox id="http://www.xulplanet.com/rdf/D">
    <button label="http://www.xulplanet.com/rdf/C"/>
    <button label="http://www.xulplanet.com/rdf/D"/>
  </hbox>
</hbox>

The recursive nature of templates has useful applications in menus and trees so that sets of iterative content can be generated automatically. We'll look more at recursive templates later, but next, let's look at a more practical example.

Comments ( 5 )

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 )