TopBraid SuiteTopBraid Enterprise Vocabulary NetTopBraid ComposerTopBraid LiveTopBraid Ensemble

TopBraid Suite provides comprehensive support for SPARQL Web Pages (SWP) in both TopBraid Composer and TopBraid Live. SWP is also the implementation language of parts of the TopBraid Enterprise Vocabulary Net (EVN) solution.

The following guided tour shows how to get started with SWP in TopBraid Composer. This assumes you have TopBraid Composer Maestro Edition 3.4 or above.

Exercise: Creating a HTML page for SKOS Concepts

In this exercise we create an HTML page that displays details about instances from the SKOS ontology. You will need any example SKOS file to follow this exercise, or create instance data on the fly.

Note that SPARQL Web Pages was developed with the name UISPIN, and older versions of TopBraid use the term UISPIN interchangeably with SPARQL Web Pages. In particular, UISPIN refers to the RDF namespaces and files.

Step 1: Create a new SWP File

We create an empty file that will contain the user interface descriptions to render arbitrary SKOS concepts. In the New File wizard we check SKOS as one of the initial imports, so that we have the SKOS namespace available.

We should remove the default namespace and introduce a prefix skos.ui for later. Then we import the SWP namespace(s). A good place to start is to import http://uispin.org/tui which is part of the TopBraid Composer default workspace as TopBraid/SWP/tui.rdf. We locate this file and drag it into the Imports view of TBC.

The tui namespace imports support for HTML and the core SWP vocabulary, which is all we need to get started. At some later stage we could add additional namespaces such as the support for charts or SVG.

Step 2: Define and Test an Instance View

With the SWP namespace in place, the form of every class will now show a property ui:instanceView which can be used to define a visualization for all instances of a class. TopBraid Composer has a built-in editor component that makes it easy to enter XML (XHTML) directly on the form. We select the class skos:Concept and locate the property ui:instanceView on the form. If this property is not visible, make sure that the button "Show widgets for all matching properties" is checked on the top of the form. Now click on Add empty row in the context menu behind the ui:instanceView property, and enter the HTML snippet as shown below. Note that if you want to insert a line break, you need to press SHIFT+ENTER.

By this time we assume that you are familiar with HTML source code, so that the snippet above should be easy to comprehend. SWP makes it possible to associate classes with such HTML snippets. The HTML snippets may contain SPARQL expressions or SELECT queries to dynamically create content based on the underlying RDF model. In those expressions, the variable ?this will point to the current instance that is being displayed. The example above contains two SPARQL expressions, which are embedded into the HTML code surrounded by {= ... } markers. The first expression ui:label(?this) calls a built-in SPARQL function to create a human-readable label for the resource ?this (which is the currently selected instance). The second expression just applies a type cast to turn the URI resource ?this into a URI string. You can place any SPARQL expression in those places, i.e. anything that would otherwise appear in FILTER and LET statements.

We are now ready to try how the resulting HTML rendering would look like. In this example, we are loading an existing SKOS file (here, the Agrovoc example with a classification of animals). In order to instruct TopBraid to use our new SWP rendering, we just need to import the newly created SWP file into the SKOS file. Then, we can navigate to any SKOS concept (instance of skos:Concept). TopBraid Composer will display a tab called Browser at the bottom of the main editor area. Click on this tab to see the current UISPIN rendering inside an embedded web browser.

Whenever the system renders a resource using SWP, it will look at the available instanceViews and apply a recursive substitution algorithm over them to create HTML output. TopBraid Composer allows you to trace this SWP engine and its intermediate variable bindings etc using a built-in SWP Debugger. Press the green bug button on the top of the Browser, and then step through the execution, or just run the engine to completion to explore the resulting HTML source code.

In addition to the Browser tab, you can also open a stand-alone browser for any instance that has a visualization associated with it, using the Resource context menu. This makes it sometimes easier to develop a SWP structure without losing context.

Step 3: Refine and Generalize the Instance View

The HTML rendering above is not terribly exiting yet - it only shows the name and the URI of a concept. But we will make it more interesting, and introduce some basics of SWP along the way. Going back to the SWP file, we extend the ui:instanceView as shown below.

Here we are using the control element ui:forEach to iterate through the collection of those concepts that are associated with the current concept (?this) via the skos:narrower relationship. Whenever SELECT queries are embedded into the document, they must be surrounded by {# ... }. For each row of the ui:resultSet query, the block inside of the ui:forEach will be repeated. The result variables of the query (here: ?child) will be visible inside of that block, and we can use them to populate an HTML list. Going back to the SKOS file, we can refresh the Browser to see the new rendering:

This HTML list looks nice, but we may want to have a similar list for all concepts that are skos:broader than the current concept. One way of achieving this is to copy and paste the ui:forEach construct, but this is rather verbose and not very maintainable. Instead, we introduce a new SWP element class that we can then use to display either narrower or broader relationships.

Back in the SWP file, we locate ui:Element under ui:Node in the class tree, and create a subclass of it, called skos.ui:ConceptList. This class will take two arguments: a concept and a predicate. Those arguments are defined in the same way like arguments of SPIN and SPARQLMotion modules: using the spl:Argument template at spin:constraint. Let's walk through one, and you do the other. First we need to have a property that actually holds the value of the argument in the underlying RDF model. Here, let's create a new property skos.ui:concept and drag it from the Properties view on spin:constraint on the form. This will open a SPIN Template dialog in which we should fill in a comment, and the spl:valueType of the argument. The resulting argument declaration can be opened up on the form using the small plus button over the icon, as shown below.

After having declared the other argument with a property skos.ui:predicate we can fill in the prototype of our new class as shown below:

The property ui:prototype links a user-defined SwP class with an (HTML) snippet. Whenever the new element type is used, it will be substituted with the prototype by the SWP engine. The arguments of the class (above, skos.ui:concept and skos.ui:predicate) will be accessible through variables with matching local names (above, ?concept and ?predicate) in the prototype block.

Now that we have generalized the HTML list into a reuseable element, we can use it on the ui:instanceView of the class skos:Concept as shown next:

The HTML snippet above contains the new user-defined class in the XML element skos.ui:ConceptList, and the arguments are passed into the argument by the engine. (Note that the property names such as skos:broader above will be interpreted as resources only if the value type of the argument is a resource - otherwise it will be stored as a plain string, leading the SWP rendering to fail.) The resulting page now displays both broader and narrower relationships for the selected concept:

Step 4: Use the SWP Visualization from a Web Browser

TopBraid Composer Maestro Edition comes with a built-in Jetty web server, and this server can be used to return HTML pages based on SWP definitions. Run locally, this personal web server can be called using a REST-based API from an external web browser such as shown in the screenshot below.