Neil's Place

July 1, 2005

8:08 PM How Templates Work XVIII - Static Content

Creating an menuitem in the filter list to show all items is fairly easy. This item doesn't need to be generated from the datasource. Instead it will be what is called static content in a template. The static content is any content that is a sibling of the <template> element. This content is displayed as is without affecting the generated content from the template.

<menulist datasources="template-guide-photos4.rdf"
           ref="http://www.daml.org/2001/09/countries/country-ont#Country"
           oncommand="applyFilter(event.target.value);">
  <menupopup>
     <menuitem label="All"/>
  </menupopup>
  <template>
    <rule>
      <conditions>
        <content uri="?start"/>
        <triple subject="?country"
                predicate="http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
                object="?start"/>
        <triple subject="?country"
                predicate="http://purl.org/dc/elements/1.1/title"
                object="?countrytitle"/>
      </conditions>
      <action>
        <menupopup>
          <menuitem uri="?country" label="?countrytitle" value="?country"/>
        </menupopup>
      </action>
    </rule>
  </template>
</menulist>

The only difference between the previous example and this one is that the <menulist> element has some additional content added before the template. The content will be displayed just like it would be as if the template wasn't present. That is, before the template is examined, the menulist would have one item in it, with the label 'All'. The template generates two results as before, one for each country, and appends a <menuitem> for each one.

One interesting thing about this example is that only one <menupopup> will be created, even though there are two in the code, one outside the template and another one inside the action body. This demonstrates how the template builder generates content, and the specifics of how this is done become important when dealing with recursive content and multiple rules.

What's going on here is that the XUL parser first creates the outer <menulist> element. The static content outside the template will also be created. The result will be a XUL display that looks just like the code above, except that the template and its content is hidden. At this point, the menulist will have a menupopup as a child, and the menupopup will in turn have one menuitem child. Next, the template is examined and two results are generated. Remember that only the content at the uri attribute or below inside the action are copied for each result.

When processing the action body, the builder looks at the first element inside the <action>, in this case, the <menupopup>. This element doesn't have a uri attribute, so the builder knows that this element should only be created once. You might think that the builder would then just create a <menupopup>, but it doesn't. Instead, it looks to see if a <menupopup> already exists in the location where it would be generated. In this case, there is one, the static menupopup defined outside the template. Instead of creating another menupopup, the builder uses the existing one. This is convenient since it makes it easy to combine static results and template generated results into one list.

The builder then switches where generated content would be generated to inside to existing menupopup and moves onto the next part of the action, the <menuitem>. This element has the uri attribute so this content will be duplicated for each result.

The technique of looking for an existing element applies to any type of content. The builder will treat the element as already present as long as some element with the same tag name exists. If you were to change the static content to be some other element besides a <menupopup>, it won't match, so the builder will create a new one when handling the action. This becomes useful when using multiple rules and we'll see some examples of this later.

Here is the example to try. Note that the workaround of loading the datasource beforehand as mentioned for the last example isn't necessary, as the existence of the static content is another effective workaround. So, if you're using menulists with templates and the data isn't displaying properly when the data hasn't loaded, try using a static <menupopup>. It doesn't even need to have any items in it.

The static content may be placed before or after the template, although usually you would place it first. Note that the static content is always placed before the generated content, so the 'All' item will always be the first item in the menu.

Let's look at another example, involving radio buttons. Actually, this example is similar, it just uses a radigroup instead of a menulist to display the list of countries.

<radiogroup datasources="template-guide-photos4.rdf"
            ref="http://www.daml.org/2001/09/countries/country-ont#Country"
            onselect="applyFilter(event.target.value);">
  <radio label="All" selected="true"/>
  <template>
    <rule>
      <conditions>
        <content uri="?start"/>
        <triple subject="?country"
                predicate="http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
                object="?start"/>
        <triple subject="?country"
                predicate="http://purl.org/dc/elements/1.1/title"
                object="?countrytitle"/>
      </conditions>
      <action>
        <radio uri="?country" label="?countrytitle" value="?country"/>
      </action>
    </rule>
  </template>
</radiogroup>

This example doesn't have any other content to generate outside the radio element with the uri attribute, so it will just be copied as is. The static 'All' radio button will be left as the first radio item.

Comments ( 4 )

June 30, 2005

8:06 PM How Templates Work XVII - Generating a Filter Menu

Templates may be used to generate any type of content. It is common to use a template to generate the items on a menu or in a listbox or tree. The syntax is the same regardless of what type of content is being created. In the previous example, we hard-coded a menulist with the list of countries, but we could also generate this list from the datasource. The same datasource may used for both the photos list and the menulist. Even though the same datasource is used, it will only be loaded once and both templates will be notified when the data has loaded.

We will need to add some information to the datasource in order to specify the list of countries that are available. There are two possibilities. First, a separate Seq could be added listing the countries. Then, a simple <member> condition can be used to iterate over it. Or, we could use an RDF type to specify the countries. Then, we could just look for all resources that were of the 'Country' type. We'll use this method here since we've already seen examples of generating results from a container.

An RDF type can be assigned to a node by using the predicate 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type' set to a resource for that type. In RDF/XML, a syntax shortcut may be used which involves replacing the Description tag with the type. We need to add the type to the two countries in the datasource, as well as ensure that the namespace is declared on the root RDF tag:

<nso:Country about="http://www.daml.org/2001/09/countries/iso#IT"
             dc:title="Italy"/>
<nso:Country about="http://www.daml.org/2001/09/countries/iso#NL"
             dc:title="Netherlands"/>

The type of these two resources, when expanded with the namespace (not shown here), will be 'http://www.daml.org/2001/09/countries/country-ont#Country'. The resulting RDF triples for the first country will be:

http://www.daml.org/2001/09/countries/iso#IT
  -> http://www.w3.org/1999/02/22-rdf-syntax-ns#type
  -> http://www.daml.org/2001/09/countries/country-ont#Country
http://www.daml.org/2001/09/countries/iso#IT
  -> http://purl.org/dc/elements/1.1/title
  -> Italy
The type is just like any other triple in the datasource, so we don't need any special syntax to navigate over it. We just need to use the right predicate to look for all the countries. You might wonder what the ref attribute or starting point should be set to since there is no container for the countries. Actually, we can just use the type as the starting point.

<menulist datasources="template-guide-photos4.rdf"
          ref="http://www.daml.org/2001/09/countries/country-ont#Country">

Remember that the only requirement is that the starting point be a resource, but it doesn't matter what resource is used. The conditions will need to iterate over the arcs pointing into the type resource. Since we want the arcs pointing into the type, we need to determine the source or subject of a triple. Look at the resulting RDF triples above again if this is unclear. The starting node is 'http://www.daml.org/2001/09/countries/country-ont#Country'. We need to iterate over the 'type' predicate to find the individual countries. A second triple is used to get the title for the country.

<conditions>
  <content uri="?start"/>
  <triple subject="?country"
          predicate="http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
          object="?start"/>
  <triple subject="?country"
          predicate="http://purl.org/dc/elements/1.1/title"
          object="?countrytitle"/>
</conditions>

The action body will need to generate a <menuitem> for each result. It will also need to include a <menupopup> around all of the items. Since we only want to generate a single menupopup, it should go outside of the element with the uri attribute. Only the contents at the element with the uri attribute and below are copied for each result. The elements above are not.

<action>
  <menupopup>
    <menuitem uri="?country" label="?countrytitle" value="?country"/>
  </menupopup>
</action>

The result will be two generated menuitems, one for each country, inside a menupopup. The value attribute is assigned the ?country variable so that the applyFilter function can use this value easily for filtering. The complete example shows this working. Note that due to a bug with template generation in menulists when the datasource hasn't loaded yet, you may have to load the example twice to get it work. This issue only affects the menulist element. Several workarounds can be used in this simple example. First, you could move the <menupopup> element outside of the template and put the datasources attribute on it instead of the <menulist> element. This will work in this simple example, but has the disadvantage that the builder won't be able to generate the content lazily only when the popup is opened. Another workaround is to just rebuild the template once the data has been loaded.

Next, we will look at how to add the All choice to the menu, which won't be generated from the datasource.

Comments ( 8 )

June 29, 2005

7:28 PM How Templates Work XVI - Additional Navigation and Filtering

The last example showed how to navigate 'upwards' in the RDF graph. By carefully defining the RDF graph and using the right triples we can usually navigate to any part of the RDF data that is necessary in order to get the right results. Usually, however you will want to iterate only over the children of a node using a <member> tag and use a <triple> or <binding> for each predicate of each child that you wish to display. This is the way that the template system was originaly designed to be used and many of the datasources used by Firefox and other Mozilla products work with datasources in this way.

A very uncommon form of navigation you can also do is to navigate upwards using a <member> tag, that is to get all the parents of a node, as in this example:

<conditions>
  <content uri="?start"/>
  <member container="?parent" child="?start"/>
</conditions>

This might be used, for instance, to start at a particular photo and find all of the containers that it is inside.

Sometimes you may wish to change the conditions at a later time. For example, you wish to user to be able to select a value from a list, and the template results should be filtered based on that value. This can be done by modifying the DOM nodes inside the conditions and rebuilding the template. For instance, to apply a filter, you might add a new <triple> element. To remove the filter, the <triple> should be removed again. Let's assume that we've given an id of 'cond' to the <conditions> tag.

function applyFilter(country)
{
  var cond = document.getElementById("cond");
  var triple = document.getElementById("filterTriple");
  if (country) {
    if (!triple) {
      triple = document.createElement("triple");
      triple.id = "filterTriple";
      triple.setAttribute("subject", "?photo");
      triple.setAttribute("predicate", "http://www.daml.org/2001/09/countries/iso-3166-ont#Country");
    }
    triple.setAttribute("object", country);
    cond.appendChild(triple);
  }
  else if (triple) {
    cond.removeChild(triple);
  }
  document.getElementById("photosList").builder.rebuild();
}

The 'country' argument to the applyFilter function holds the value to filter by. If this is set, we add a filter, otherwise we remove it. The code is fairly straightforward. A new <triple> element is created and the object attribute is set to the value to filter by. For example, the resulting triple for the Netherlands might be:

<triple subject="?photo"
        predicate="http://www.daml.org/2001/09/countries/iso-3166-ont#Country"
        object="http://www.daml.org/2001/09/countries/iso#NL"/>

This triple is then appended to the conditions. The triple is given an id so that it can be found later if a different filter is applied. Naturally, we only want to apply one filter at a time, so we can just reuse the same triple for each filter. When removing the filter, we only need to remove the triple from the conditions. This example only adds one triple, but you could add others, or add <member> elements. Whether a triple or member is added or removed, the template must be rebuilt by calling the rebuild method. This method will remove all of the existing generated content, delete all of the internal information pertaining to the results, and start again as if the template was just being examined for the first time. The template will be parsed again and the data examined for new results.

You can view a complete example of this in action. A menulist is used to allow one to select either a specific country, or select All to show all of the photos. When a choice is made, the applyFilter function as shown above is called and the template content gets rebuilt with the desired filter applied.

In this example, the menulist is hard-coded to contain the items that we know are in the datasource. Next, we'll look at also generating this list using a template.

Comments ( 8 )

June 26, 2005

3:53 PM How Templates Work XV - Source Navigation

Triples may also be used to navigate up the graph as well as downwards, following the graph arrows in the reverse direction. For instance, in the original example, we could start at node D and navigate upwards to A and C. The syntax for the triple is the same except that the known variable should be placed in the triple's object attribute and the unknown variable should be placed in the triple's subject variable.

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

The triple is evaluated in the same manner except that the value of the object can be filled in with the value of the ?start variable. The RDF graph is examined for an arrow pointing in to the node instead of out. In the photos example, we might wish to categorize each photo into several categories. One possibility is to just add another predicate for each photo with a literal value set to the category. Or, we could use a resource for each category. This will allow us to associate additional properties to each category and more easily navigate the graph in a template. In this case, we will categorize each photo by country where the photo was taken using a country predicate.

<?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/"
         xmlns:nso="http://www.daml.org/2001/09/countries/iso-3166-ont#">
  <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">
    <nso:Country resource="http://www.daml.org/2001/09/countries/iso#IT"/>
  </rdf:Description>
  <rdf:Description rdf:about="http://www.xulplanet.com/ndeakin/images/t/canal.jpg"
                   dc:title="Canal">
    <nso:Country resource="http://www.daml.org/2001/09/countries/iso#NL"/>
  </rdf:Description>
  <rdf:Description rdf:about="http://www.xulplanet.com/ndeakin/images/t/obelisk.jpg"
                   dc:title="Obelisk">
    <nso:Country resource="http://www.daml.org/2001/09/countries/iso#IT"/>
  </rdf:Description>
  <rdf:Description about="http://www.daml.org/2001/09/countries/iso#IT"
                      dc:title="Italy"/>
  <rdf:Description about="http://www.daml.org/2001/09/countries/iso#NL"
                      dc:title="Netherlands"/>
</rdf:RDF>

A new Country predicate has been added to each photo pointing to another resource. Note that this predicate uses a new namespace so it is declared on the root RDF element. The titles of the two countries are defined near the end of the RDF data. Now that we have countries for each photo, instead of starting at the node 'http://www.xulplanet.com/rdf/myphotos', we could start at a country resource and look for all photos that point to that country. The ref attribute will need to changed to point to the country resource rather that the Seq container of photos.

<hbox datasources="template-guide-ex2.rdf"
      ref="http://www.daml.org/2001/09/countries/iso#IT">

In this example, three triples will be used.

<conditions>
  <content uri="?start"/>
  <triple subject="?start"
             predicate="http://purl.org/dc/elements/1.1/title"
             object="?countrytitle"/>
  <triple subject="?photo"
             predicate="http://www.daml.org/2001/09/countries/iso-3166-ont#Country"
             object="?start"/>
  <triple subject="?photo"
             predicate="http://purl.org/dc/elements/1.1/title"
             object="?title"/>
</conditions>

The first triple is used to get the title for the country. There is only one potential result at this point, the starting node which is 'http://www.daml.org/2001/09/countries/iso#IT'. After the first triple is examined, the data network will look like the following:

(?start = http://www.daml.org/2001/09/countries/iso#IT,
 ?countrytitle = Italy)

Only one result is present since there is only one title available. The second triple is the more interesting one. It is used to look up nodes that have a Country predicate pointing in. It may be difficult to tell whether the builder will look for arcs pointing out from a node or into a node just by looking at the <triple> element. The template builder doesn't know this either until the triple is evaluated and variable substitution is done. Here, the value of the ?start variable is already known for the potential result, so it will be filled in. However, the value of the ?photo variable is not known. Since the object is known and the subject is not, the builder knows to look for a predicate pointing in to a node. There are two photos in the RDF datasource that point to the node 'http://www.daml.org/2001/09/countries/iso#IT', so the existing result will be copied for these two photos. The resulting data after the second triple will look like this:

(?start = http://www.daml.org/2001/09/countries/iso#IT,
 ?countrytitle = Italy,
 ?photo = http://www.xulplanet.com/ndeakin/images/t/palace.jpg)
(?start = http://www.daml.org/2001/09/countries/iso#IT,
 ?countrytitle = Italy,
 ?photo = http://www.xulplanet.com/ndeakin/images/t/obselisk.jpg)

The third triple just grabs the title from the photo as previous examples did, adding a value for the ?title variable for each photo. We can then display these results using the following action body.

<vbox uri="?photo" class="box-padded">
  <image src="?photo"/>
  <label value="?title"/>
  <label value="Country: ?countrytitle"/>
</vbox>

A label for the country will be displayed as well. Naturally, it will have the same value for every photo. Some padding has been added around each photo using the 'box-padded' class. Here is the example.

Comments ( 11 )

June 24, 2005

5:48 PM How Templates Work XIV - Literals in Triples

The triples used so far have all had variables in both the subject and object. However, a string value may be used instead. Since the subject of an RDF arc is always a resource, the subject may be a resource URI. The object attribute may be a resource URI or a literal value. Using a literal as the object of a triple is a common way to filter out specific items. For instance, if items were identified with a type, the data could be filtered to include only items of a particular type.

Here is an example triple that we could use in the photos example:

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

This new triple has a static value for the object attribute instead of a variable reference. You might be able to guess that it will cause a match for only one of the photos, the Canal photo. The others won't be able to match when evaluating the triple. To look closer, here is the data network after the member has been evaluated:

(?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)

When evaluating the triple, the template builder will iterate over the three potential results found so far. For the first result, the value of the ?photo variable 'http://www.xulplanet.com/ndeakin/images/t/palace.jpg' will be used as the subject, the predicate will be 'http://purl.org/dc/elements/1.1/title', and the object will be 'Canal'. Since there are no variables to fill into the triple, the builder will just confirm that such an triple exists in the datasource. The triple doesn't exist for the first result since the title for the first photo is 'Palace from Above', so the potential result will be removed from the data. For the second result, such an arc does exist, so the result is kept. Like the first result, there is no arc for the third photo, so it is also removed.

The resulting data will look like the following:

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

Here is the example.

Naturally, we will need to add a binding for the ?title variable if we wish to display it, or we could just hardcode it since we know the value will be 'Canal'. Usually you won't be filtering on a title though, you would instead filter on a value that acts like a type.

There has to be at least one variable used in a triple in either the subject or the object attributes, or both. You can't have a triple with no variables. That's not an issue though, since it wouldn't be particularly useful. Also, you cannot use a variable in the predicate. Only the subject and object attributes may have variables. Another thing that you cannot have is a triple where both variables would be unknown as in the following:

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

In this case when the template builder gets to the triple, neither the ?category nor the ?title variables can be filled in so the builder doesn't know what to generate. The builder won't generate any output in this situation.

The member tag must have variables for both the container and child attributes. It wouldn't be very common to filter for a specific child anyway.

Comments ( 7 )

June 22, 2005

8:48 PM How Templates Work XIII - Other Action Syntax

So far, attribute replacement in an action body has been used to replace an entire attribute with the value of a variable. However, you may also replace only part of attribute's value, or use multiple variables in one attribute. For instance, to include a prefix before a variable value, you can use:

<label value="My name is ?name"/>

The effect will be that the ?name part of the attribute will be replaced by the value of the variable ?name. For instance, if the value of ?name is 'Jake', then the attribute value will be 'My name is Jake'. You can include multiple variables in one attribute if desired:

<label value="My name is ?name and my age is ?age"/>

This technique will work for any variable replacement in the action body, except for the uri attribute since that wouldn't be meaningful. Note that variable names must have a space after them as this is how the end of the variable is determined. That is, '?name?age' is considered to be a single variable with that name, not two variables together. To use two variables, place a space between them. It is sometimes useful though, to concatenate two values together without a space. This can be done by putting two variables next to each other in an attribute value separated by a caret (^).

<label value="?name" class="?gender^?nationality"/>

The caret is considered a separator between variables, however it will not appear in the output. It can also be used to separate a variable with normal text:

<label value="?name" class="?gender^german"/>

These last two examples have been setting the class attribute on a label. The effect will be that a label will have either the 'malegerman' or 'femalegerman' class. In a stylesheet, you could set properties for each of these classes such that different values appear differently without having to use multiple rules.

Although not common, you may also wish to insert a question mark or a caret into an attribute value. To do this, just use two question marks or two carets in a row. For instance:

<label value="What is my name?? My name is ?name"/>

In this example, the label might be 'What is my name? My name is Jake'. Note that a caret only has a special meaning at the end of a variable, thus two in a row are only needed after a variable.

One last thing to point out is that since the only characters that can separate a variable are a caret, a space or the end of the attribute, this means that any other character is valid as a variable name. However, for readability, you should restrict variable names to letters, numbers and perhaps hyphens to separate words.

The description added in the last example might be a long string of text for some of the photos. It may be desirable to have the text wrap by placing it inside a <description> element. This means that we want to do variable replacement as text, not as an attribute value. A special tag is used for this purpose, the <textnode> tag. It has one attribute, the value attribute, which may use variable substitution like other attributes. However, the <textnode> element is not copied into the generated content, but instead a DOM text node is created with the value of the value attribute as its contents. For instance, if the template contained:

<description><textnode value="?description"/></description>

The resulting generated content might be:

<description>View from the top of the tower looking east of the Doges Palace</description>

Note that the <textnode> has been replaced with the substituted value attribute. Unfortunately, a bug can make this appear to not work at times. Recall that the template builder doesn't load the datasource before processing a template. As the datasource loads, the rules are examined with the new data as it arrives. This causes rules to create matches as the data loads. However, variables determined from a binding are evaluated using a much simpler process. The bug is that this code path for bindings doesn't handle the textnode element properly. Thus, if you use a variable set in a binding, you must ensure the datasource is loaded before the template is built, or just rebuild the template. Another possibilty is to rearrange the RDF such that the values, in this example, the descriptions, are specified before the containers. This may seem a bit confusing, but hopefully, this bug, if you do encounter it, should be fixed soon.

Comments ( 3 )

June 19, 2005

4:53 PM How Templates Work XII - Bindings

We can add more triples to the previous example to show more information. For example, a description could be added to a photo. To do this all we need to do is add the necessary data to the RDF datasource and add another <triple> element to the template's conditions.

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

It works similarly to the previous triple. The ?photo variable is filled in with the known value and then the arc is looked up in the datasource, filling in the value for the ?description variable. The ?description variable would then be used in the action body. Let assume though, that we are only going to add a description to one of the photos in the datasource; the other two photos will not have a description. This may mean the description is not known, or that it wasn't filled in by the user.

<rdf:Description rdf:about="http://www.xulplanet.com/ndeakin/images/t/palace.jpg"
  dc:title="Palace from Above"
  dc:description="View from the top of the tower looking east of the Doges Palace"/>

If you try a full example based on this data, you will notice that only one result has been generated. This is because only one item has a description. Here is the data after the first <triple> has been evaluated, but before the description triple has been examined:

(?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')

The second triple will add a ?description for the first photo, adding a fourth variable-value pair to the existing data. However, when the builder doesn't find any value for a condition, the entire potential result is removed. For the second photo, the datasource doesn't have any matches for the description, so that potential result will be removed. The same happens for the third photo. In the end, only one photo remains.

(?start = http://www.xulplanet.com/rdf/myphotos,
 ?photo = http://www.xulplanet.com/ndeakin/images/t/palace.jpg,
 ?title = 'Palace from Above',
 ?description = 'View from the top of the tower looking east of the Doges Palace')

Thus, only one match exists, so only one set of content is generated.

Sometimes, it would be useful to have triples that match conditionally, that is , have a triple that doesn't cause a result to be removed as a possible match. This is done with a <binding> element. This tag doesn't go in the <conditions> block but instead inside a <bindings> element. The syntax is as follows:

<rule>
  <conditions>
    ...
  </conditions>
  <bindings>
    <binding subject="?photo"
             predicate="http://purl.org/dc/elements/1.1/description"
             object="?description"/>
  </bindings>
</rule>

The description triple has been changed to a <binding> element, but the attributes are the same. This allows a match to occur even if the description is not specified in the data. The template builder examines bindings after all the conditions have been applied. It has already determined, in this example, that three matches have been found. The builder continues by filling in the values for any bindings. They are evaluated in a similar although simpler mannner as the triples. The value of the ?photo variable is known for each match, the datasource is examined for the description, and the value of the ?description variable is filled in. The effect is three matches, only one of which will display a description. The photos that don't have a description will be treated as if the description was blank. That is, the ?description variable will be replaced with an empty string when analyzing the attributes in the action body.

Here is this example.

You can have more than one binding if you wish. The others will be evaluated in a similar way. For instance, the title triple could be moved to a binding such that it could be optional also.

Comments ( 9 )

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 )