ReoPath Templates

ReoPath templates are a markup language feature which adds the ability to bind data from an RDF data source onto specific elements within the markup. It is intended to be used with another XML markup language, so some of its features use attributes on elements of other markup languages, such as XHTML and XUL. When the underlying RDF data changes, the binding between the elements is recalculated as necessary.

ReoPath is currently used in Topicalla. Most of the features described below are implemented.

RDF data is bound using a variety of attributes containing ReoPath expressions. The expressions are calculated relative to a context which is determined by the surrounding elements. The result of an expression is used as the context when evaluating the children for which that expression is attached.

An example:

<?xml-stylesheet href="chrome://reopath/content/rpath.css" type="text/css"?>
<window xmlns:rp="http://www.xulplanet.com/ns/rpath-template"
        xmlns:mv="http://www.xulplanet.com/rdf/movies#"
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <rp:template node="content"
                  datasource="http://www.xulplanet.com/ndeakin/arts/reopath/movies-small.rdf"
                  ref="urn:actor:all"/>
  <vbox id="content">
    <listbox id="theList" rp:repeaton="%*">
      <listitem rp:assign="dc:title">
    </listbox>
    <rp:reffromlist on="theList">
      <label value="Birthdate:"/>
      <label rp:assign="mv:brthdate"/>
    </rp:reffromlist>
  </vbox>
</window>

The template element above starts a ReoPath template. It causes a datasource to be loaded and the context node to be set to the resource urn:actor:all. The node attribute specifies the id of the template content to evaluate.

The listbox has a repeaton attribute attached to it. This causes the child of the listbox to be used as a repeat template. The template is repeated for each value in the result of the repeaton expresssion.

The context for the listbox is {urn:actor:all}. The expression %* will return all of the child resources of the context. In the datasource, the context has ten children, so the children will be repeated ten times.

The listitem tag is cloned and added once for each child. The context is adjusted to each successive child when evaluating the items. The assign attribute on the listitem tag causes the title of each child to be assigned as the value of the listitem. The expression dc:title is evaluated using the appropriate context for that element, which will be each actor resource.

The reffromlist element is bound to the list with the id theList. When an item is selected from the list, the context associated with the item is used as the context when evaluating the children. The children of the reffromlist element will be re-evaluated whenever the listbox selection changes.

The first label has no ReoPath attributes associated with it so it becomes a normal label. The second label has a assign attribute which causes the label text to be set to the result of evaluating the expression mv:birthdate using the context. The context is the same as the selected item in the listbox. The 'mv' prefix is declared on the window tag.

The context is adjusted by the ref and assign attributes among others. The children will be evaluated using this new context instead. If there were children inside the second label, they would be evaluated using the value of the birthdate as the context.

Here is an example XHTML fragment:

<table>
  <thead>
    <tr>
      <th>Title</th>
      <th>Cast</th>
    </tr>
  </thead>
  <tbody rp:repeaton="mv:{movie}^rdf:type">
    <tr>
      <td rp:assigncontent="dc:title"/>
      <td rp:repeaton="mv:cast/sort(mv:playedBy*,mv:order)">
        <p rp:assigncontent="dc:title"/>
      </td>
    </tr>
  </tbody>
</table>

The repeaton attribute on the tbody will cause the content to be repeated for each resource that has an 'rdf:type' of 'mv:movie'. The first table cell assigns the title of the movie to the content of the cell. The second cell displays a list of the cast members in the movie. A nested repeat block loops over the cast members sorted by the 'mv:order' predicate.

Elements and Attributes

All ReoPath template elements and attributes are in the namespace 'http://www.xulplanet.com/ns/rpath-template'. The examples in this document will assume that the 'rp' prefix is assigned to this namespace.

Any ReoPath expressions may use namespaces as declared on the element the expression is attached to.

The <template> element

The outermost element is a template element, which is a container for a ReoPath template. Content that is not a descendant of a template element is not parsed as a template. The template element has three possible attributes.

The datasources attribute must be set to a space-separated list of RDF datasources to bind to. Each datasource is identified by a URI, which the user agent is expected to load. One or more datasource URIs may be used. This attribute is not required, but not specifying a datasource would rarely be useful. However, the template must still be parsed in this case.

The ref attribute may be used to specify a ReoPath expression that returns the top-level context node for the template. Child nodes of the template are resolved using this node as the context. If this attribute is not specified, then the context node is an empty value.

The defns attribute specifies the default namespace to be used when evaluating ReoPath expressions. Predicates without namespaces in expressions use this namespace.

An application may imply a template around a document or fragment if the datasource or context can be determined by other means.

The <assign> attribute

The assign attribute is used to assign the result of an expression to an element. The value of the assign attribute should be set to a ReoPath expression. Unless modified with either an assignattr or assignprop attribute, the first result from evaluating the expression is assigned to the value property of the assign attribute's element. If modified by either attribute, the result is assigned to the corresponding attribute or property as described in the following sections.

In addition, the result becomes the context node for the evaluation of expressions of all of the child nodes of the assign attribute's corresponding element. If the expression returns a list of values, only the fist value is used in assignment; the others are ignored, however the entire list is still used as the context.

The <assignattr> attribute

The assignattr attribute is used to modify which attribute the result of an assign attribute expression is assigned to. If an assignattr attribute is specified, it must be set to the name of a valid attribute for the element. If the element does not also have an assign attribute, the assignattr attribute is ignored.

The assignattr attribute overrides the default behaviour of assigning an expression result to the value property and instead assigns the result to the attribute specified by the assignattr attribute. If that attribute is also specified on the element, it's value will be replaced.

The <assignprop> attribute

The assignprop attribute is used to modify which property the result of an assign attribute expression is assigned to. If an assignprop attribute is specified, it must be set to the name of a valid DOM property for the element. If the element does not also have an assign attribute, the assignprop attribute is ignored.

The assignprop attribute overrides the default behaviour of assigning an expression result to the value property and instead assigns the result to the property specified by the assignprop attribute.

If both an assignattr and an assignprop attribute are present on an element, the assignprop attribute is ignored.

The <assigncontent> attribute

The assigncontent attribute is used to assign the result of an expression to the content of a node. The value of the assigncontent attribute should be set to a ReoPath expression. If either the assign attribute or ref attribute is present on the element, the assigncontent attribute is ignored.

The string value of the first result of the expression is added as a single text child of the element. Any existing children of the element are first removed.

The <ref> attribute

The ref attribute is used to set the context for evaluating the children of an element. The value of the ref attribute should be set to a ReoPath expression. The result of this expression is used as the context when evaluating the children of the element. If the assign attribute is present on the element, the ref attribute is ignored.

This attribute functions similar to the assign attribute, except that the result is not assigned to an attribute or property of the element.

The <bind> tag

The bind tag is not displayed. It accepts the assign, assignattr assignprop and ref attributes. The resulting value is assigned to the relevant attribute or property of the parent of the bind element, instead of the bind element itself. This allows multiple attributes of properties to be bound to expressions.

The <repeat> element

The repeat tag is used to create a block of content that is repeated for each context in a list. This element should have at least an on attribute, which should be set to a ReoPath expression. The expression is evaluated, and for each value in the result list, the first child of the repeat element is cloned and added as a sibling of the repeat element. The elements are added as immediate siblings in sequence. Any siblings that were present at the time when the template was initially parsed are not removed. These nodes are referred to as the header and footer nodes, corresponding to the nodes before and after the repeat element respectively. The content of the repeat element itself is hidden.

The added content is evaluated using the corresponding result as the context. Thus, the first cloned and inserted content block is evaluated using the first result as the context. The header and footer nodes are evaluated using the same context as the repeat element.

The <repeaton> attribute

The repeaton attribute is an alternate form of creating a repeat block. The attribute should be set to the ReoPath expression which returns the results to be used for repeat block generation. The last child of the element which the repeaton attribute is placed on is used as the node to be cloned. The cloned content is added after the last child in sequence, such that that node is no longer the last child. The node used as the repeat template is not displayed. Nodes before it become the header nodes.

The added content is evaluated using the corresponding result as the context. Thus, the first cloned and inserted content block is evaluated using the first result as the context. The header nodes are evaluating using the same context as the element with the repeaton attribute.

Note that unlike the repeat tag where content is added as siblings, content added using the repeaton attribute is added as children.

The <reffromelement> tag

The reffromelement sets the context used for evaluating its children to the result of the expression attached to the element in the same document with the id corresponding to the on attribute.

The <reffromlist> tag

The reffromlist tag is used to bind a block of content to the selection of a list. The element should have an on attribute which should be set to the id of a list in the same document. The list element should be able to fire the select event.

The context used when evaluating expressions attached to the children of the reffromlist element is originally an empty value. When an item is selected from the list, the context changes to the context of the selected item in the list. The children of the reffromlist are then re-evaluated.

The <reffromvalue> tag

The reffromvalue tag is used to bind a block of content to the value of an element. The element should have an on attribute which should be set to the id of an element in the same document. The element bound to should be able to fire the change event.

The context used when evaluating expressions attached to the children of the reffromvalue element is originally an empty value. When the change event fires, the context changes to the result of the expression attached to the element. If there is no expression attached to the element, it's context is used instead. The children of the reffromvalue element are then re-evaluated.

The <subblock> attribute

The subblock attribute is used to indicate the location where a block of additional nodes may be added by an application. The context may be adjusted using the ref attribute. The application should be informed that it should create nodes inside the subblock element based on the context. The manner in which the new content is determined is application-specific.

The value of the subblock attribute is used to provide a hint to the application as to how to determine the nodes to add. Typically, this will be used as a key in a table.

The type attribute may be used to specify a type in RDF terms. Usually, it specifies the expected RDF type of the context. The property attribute may be used to specify an RDF predicate. The application may use this information in addition to available RDF Schema information to aid in determining the nodes to add.

Some subblock examples:

<box rp:subblock="compact" rp:ref="dc:title"/>
<box rp:subblock="normal" rp:ref="%1/description || 'No Description'"
     rp:property="http://purl.org/rss/1.0/description">

In the first example, the author wishes the title of the context to be displayed in a compact form. Since the title is likely plain text, it might be rendered in this form.

The second example will have the description of the first child context displayed in a normal form. Since the expression invloves several sub-expressions, it isn't clear what kind of result is expected, so the application may use the property attribute to determine this.

Copyright © 1999 - 2005 XULPlanet.com