UISPIN Example: Documenting SPIN Functions

The UISPIN framework can be used to create HTML documents from templates that contain embedded SPARQL queries and expressions. You can attach those templates to the classes of your domain model to help the system find the most suitable rendering of the instances. In this blog entry I show how this technique can be applied to create ontology documentation. In particular I create a UISPIN model for rendering SPIN functions, but similar ideas can be applied to other language elements such as OWL classes. This example also demonstrates many key features of UISPIN, including user-defined elements and control structures.

The end result of this example will look like the following. Whenever a user navigates to a SPIN function (here: spl:object), then the Browser will display the HTML shown below.

The resulting HTML page displays the qname of the function in the heading, then the comment of the function, then a section listing all arguments of the function and finally the body query (if one exists).

In order to produce such a rendering, I have created a new file that contains the UISPIN definitions for the SPIN ontology. This file imports the SPIN namespace (http://spinrdf.org/spin) and the TUI namespace (http://uispin.org/tui, which in turn imports the HTML support for UISPIN). Since I want to document all SPIN functions, I have attached the following ui:instanceView to the class spin:Function.

The UISPIN snippet above basically states that all instances of spin:Function shall be rendered as a HTML div element containing a h2 etc. The snippet contains many SPARQL expressions in the {= ... } notation, and those expressions are executed when the page is being rendered. As usual, the variable ?this points to the current instance, i.e. an instance of spin:Function, and functions such as spl:object can be called to conveniently retrieve properties of ?this.

The snippet above also contains the control element ui:if that only inserts its child elements if the ui:condition evaluates to true.

Finally, there is also a user-defined UISPIN element, spin.ui:ArgumentsList, which is defined as shown in the next TopBraid Composer screenshot.

A user-defined UISPIN element has a unique identifier (URI) so that it can be shared and reused on the Semantic Web. Then it can have any number of arguments, using the spl:Argument SPIN template at spin:constraint. By the way this is the same design pattern as for user-defined SPIN functions, templates and SPARQLMotion modules.

The core of any user-defined UISPIN class though is its ui:prototype. This is the snippet that will be inserted into the document where the element is used. In the prototype, the values of the arguments are pre-bound to the variables shown in bold face. In the example above, the value of the spin.ui:module argument will be bound to the variable ?module in the prototype. If you scroll up two screenshots, you can see that the call of the spin.ui:ArgumentsList element includes a value for spin.ui:module. This means that the current value of the variable ?this will be inserted as ?module into the prototype. The prototype itself contains a control element of type ui:forEach that traverses all arguments of the current module, and creates one table row and table data element for each of them.

Finally, the prototype also makes use of the control element ui:resourceView, which will insert the default rendering of the ui:resource into the target document. The values of ui:resource in this case are the arguments (?arg), and those are instances of spl:Argument. This class has the following ui:instanceView attached to it.

While the above snippet may be hard to read due to its formatting, you may see that it will display the predicate's qname, followed by its value type, followed by the word [Optional].

Let's quickly summarize the main concepts from this example:

1. You can attach HTML snippets to classes using the property ui:instanceView.
2. The variable ?this points to the current instance of the class.
3. Views may contain user-defined elements, which have a prototype.
4. In the prototype, the arguments of the element are pre-bound as variables.
5. ui:if can be used to insert an HTML block based on a condition being true.
6. ui:forEach can be used to repeat a block for each row of a SPARQL query.
7. ui:resourceView will insert the default rendering (e.g. ui:instanceView) of a given resoource.

Please give UISPIN a try by downloading TopBraid Composer ME 3.3. and let us know your feedback on the topbraid-users mailing list. Note that UISPIN is still in beta stage, and your input may shape its future.