SWP in TopBraid

[four_fifth]

Getting Started with SPARQL Web Pages (Part 1)

This two-part guided example will shows how to get started with SWP. The first part will introduce basic concepts of creating model-driven SWP instance views and displaying the resulting HTML in a browser. The second part will show how to create parameterized tags for building custom tagging frameworks for Web pages and Web-based applications.

TopBraid Composer Maestro Edition 4.0 or above is required for developing SWP solutions. TBC-ME also includes a localhost server that allows testing of the solution on a desktop. The example will also show how the solution can be deployed to any TopBraid server in a simple project deploy step.

SWP can be used with any RDFS model. The overall approach is model-driven, meaning that views are defined for a class and applied to all instances, executed at run-time. In this example, a SKOS ontology is used to demonstrate some features of SWP.

Step 1: Create a SWP File

Create a SWP file by right-clicking on the target project or folder in the TopBraid Composer Navigator view and choosing New > RDF/SWP File. We will be developing HTML pages, so make sure HTML namespace is checked in the Initial Imports field.

This will create a RDF text serialization file SkosExplorer.ui.ttlx (.ttlx is an extension of Turtle that supports SWP text formatting) that includes classes to define HTML tags, SWP instance views, and prototypes. The Imports View in TBC-ME will show that http://uispin.org/html is imported along with some files it imports. These define the features of SWP that will be used in this example.

Step 2: Import the SKOS Model

Since we are interested in creating a browser for SKOS models, import the SKOS vocabulary. Locate SKOS-core.ttl in TBC-ME’s Navigator view in the project TopBraid/SKOS. Drag-and-drop the file name into the Imports View.

In the Classes View, navigate to the skos:Concept class and double-click on the name to view the class properties in the middle Class Form. We will use this to define a view that is applicable for any member (instance) of the class.

Step 3: Define an Instance View

With the SWP namespace in place, the form of every class will now show a property named ui:instanceView. This is used to define a view that is applied to any instance of the class. TBC-ME has a built-in XML (XHTML) editor component for defining SWP snippets. Note that well-formed XML is required in the snippet. Specifically, a root element is always needed.

Select the class skos:Concept and locate the property ui:instanceView on the form. Click on Add empty row in the context menu triangle to the right of the ui:instanceView name, and enter the following HTML. To insert a line break, press SHIFT+<return>. The SWP editor will automatically format the snippet.

<div ui:id="SkosExplorer"> <h1>Concept: {= ui:label(?this) }</h1>    <h2>Broader Concepts</h2>    <ul>       <ui:forEach ui:resultSet="{#          SELECT ?child          WHERE          { ?this skos:broader ?child .          } ORDER BY (ui:label(?child)) }">            <li>{= ui:label(?child) }</li>       </ui:forEach>    </ul> </div>

Figure 2: ui:instance view for skos:Concept.

The HTML snippet defines the tags that will be placed in the output stream.  The <div> element defines the XML root element and provides a name in the ui:id attribute that is used by SWP to distinguish this view from others that have been defined for skos:Concept.

When a processing directive is encountered, the expression embedded within the “{= … }” markers is executed on the server side and the result is passed into the output stream. Any SPARQL expression can be placed in a “=” processing directive, i.e. anything that can appear in FILTER and BIND statements. The second line shows a SPARQL expression that calls the function ui:label(), a SWP function that returns the rdfs:label (or any sub-property thereof) for the resource. The reserved variable ?this refers to the current instance that is being displayed. In the Figure 4 below, g:London was chosen.

When a control element is encountered, such as ui:forEach, the SWP engine will process attributes and sub-tags and place the result into the output stream.  In this example, the ui:forEach element will execute the query, then execute the sub-tags of ui:forEach for each match found in the SPARQL query. Note that in the query the reserved variable ?this is used. When executing the query, ?this is pre-bound to the current instance before executing the query.

 

The “{#…}” processing directive will execute a SPARQL SELECT statement and pass the result set to the ui:resultSet attribute. In this case the SPARQL query is embedded in the ui:forEach directive. Later we will show how to pass results sets to the ui:resultSet attribute.

 

Step 4: Displaying the View in a Browser

 

To test this locally, we will use two techniques. The first is to open the Browser sub-tab in TopBraid Composer. Open the SKOS-based Geography example from sample.evn.topbraidlive.org/geo/geo.tdb, found in TBC-ME’s Navigator View. In the top search box type “london”, or a subset of the word, and choose ctl+<space>. This will invoke an autocomplete for the resource’s qname. Choose g:London, then choose the sub-tab Browser.

 

Because there are a number of SKOS models and features in the out-of-the-box workspace for TBC-ME, a number of views are available from the top drop-down box. Choose the one with ui:id=SkosBrowser as defined above. See Figure 3.

 

The results are displayed in Figure 4. Note how the HTML text text has been rendered and the data queried to display the list of broader concepts. Subsequent steps of the exercise will incrementally modify these definitions to create a browser for any SKOS model.

 

The second technique is to use a browser to render the view. Since a browser is running on a client, it must request the specific view, resource, graph the resources is in, and matching id for the instanceView. Using the localhost server in TBC-ME, open a browser and enter the following URL (without any space or newlines):

The page will render similar to the browser embedded in Composer. Each of these parameters creates the context in which the page is displayed. For details, go to Help > Help Context in TopBraid Composer, and then TopBraid Composer > TopBraid Live Integration > SWP with TopBraid Live.

Step 5: Using Templates and Defining Hyperlinks

The previous example only displayed information about a resource. In this step we will turn these into server-independent hyperlinks. Before taking that step, note the mix of SPARQL code and tags in the example. A better practice would be to separate SPARQL and tagging syntax. This not only provides the means to separate tagging and tag implementation skillsets, but also improves maintainability of the SWP snippets.

Open the SkosBrowser.ui.ttlx file and do the following

1. Create a subclass of spin:SelectTemplates. Name it GetBroaderConcepts (see the circled 1 in Figure 5) .
2. Copy the query from the above SWP snippet – just the SPARQL part of the snippet (see the SWP code snippet above) and replace ?this with ?concept.
3. Define an argument passed to the query by selecting the context menu triangle to the right of the property spin:constraint and choosing Create spl:Argument… . Name the argument “concept” as shown in Figure 6.

The resulting SPIN Template definition should look like Figure 6:

Figure 7: The completed template.

Next, modify the ui:instanceView of the skos:Concept class to use the ui:call control element, with the ui:template attribute pointing to the template just defined and the arg:concept attribute (the same as defined in the :GetBroaderConcepts template) passing the current instance using ?this. By default ui:call binds the SPARQL result set to the variable ?rs, which can be re-named by adding a ui:varName attribute to the ui:call element (not shown here).  The result should look like Figure 8 in the skos:Concept class definition.

Navigating between the instanceView and the template view is accomplished by holding down the <ctl> key and mousing over the template name (SkosExplorer:GetBroderConcepts). The name will turn into a hyperlink that can be clicked to go directly to the template definition.

Test the page again, with either the TBC-ME embedded browser or an external browser service call, to ensure the results are the same as before.

Next modify the instanceView to turn the list of instances into server-independent hyperlinks using ui:createLink.

The attributes of the ui:createLink element define a link that points to the id of this snippet (ui:matchIds). It creates a link for each binding of ?child from the template definition (ui:resource) and passes the graph context (ui:sendQueryGraph). The optional ui:varName is used to define the variable the link is bound to (the default is ?link). Note the list elements have been modified to wrap an anchor tag with the href attribute pointing to the link created ui:createLink. The result is a hyperlinked browser as shown in Figure 9.

Again, test this with either the TBC-ME embedded browser or an external browser service call.  Clicking on a link navigates to another instance of skos:Concept that uses the same view to render its property values.

Step 6: Deploying the Solution to a TopBraid Server

To deploy the SWP definitions to a server, perform a right-click on the project you want to deploy to the server and choose Export… > Deploy Project to TopBraid Live Server.  Deployment requires sending a project (a root folder in TBC-ME’s Navigator View) and its contents to the server.  This allows bundling full solutions in one or more projectsfor deployment to the server.

Fill in the wizard as shown in Figure 10 with your TopBraid server information.  This will add the project to the server and register all services defined in the deployed project, including the SkosBrowser service defined here.  To call the service, use the same Service call URL shown previously, replacing “localhost:8083/…” with “[domain name]:[port]/[web app name]/…” – e.g. “topquadrant.com:8080/tbl/tbl/…” form the setup shown in Figure 10.

The completed example can be downloaded from here.

In Part 2 of this exercise, we will add narrower concepts to this definition to create SKOS browser that is fully navigable.

[/four_fifth]
[one_fifth]

[/one_fifth]