Prerequisites

Infrastructure:

• Drupal version ??? installed
• Drupal <sparql> module installed
• Somewhere to host files on the web (.sparql/.rq and .xsl)
• SPARQL endpoint available and populated with the data to query

Skills:

• Editing a Drupal page
• Writing a SPARQL query
• Writing XSLT 1.0 (2.0 is not supported)
• Writing HTML
• Publishing files on the web

Introduction

The Drupal <sparql> module allows Drupal editors to populate a Drupal page with results from a SPARQL query by inserting a <sparql> tag in the body of a Drupal page.

The module was created by TWC's Evan Patton.

Installation

The Drupal <sparql> module is implemented in PHP and requires installation as a Drupal module.

Overview: Using <sparql>

To use the SPARQL module, following these steps:

• Have a SPARQL endpoint available and populated with the data you would like to query.
• Write a SPARQL query to select the data that you would want.
• Write an XSL 1.0 stylesheet that inputs the query's XML binding results and outputs HTML.
• Save the SPARQL query and the stylesheet on the web.
• Edit the Body of a Drupal page to include the <sparql> element with attributes query=, endpoint=, and xslt= pointing to the corresponding files placed on the web.

After performing these steps, when a user requests the Drupal page, the <sparql> module searches the Drupal body text for the <sparql> element (a.k.a "tag") and uses the following attributes to execute the SPARQL query, style its results, and replace the <sparql> element with the output of the XSL stylesheet.

Parameters

• query= Optional. Specifies the URI of a file containing a SPARQL query. If omitted, the last query= used on the page will be reused
• • At most, one of the following 3 items should be specified. Most of the queries living at http://tw.rpi.edu/queries/ are actually PHP scripts that take the uri, i, and s parameters. For i and s, the text is prepended by http://tw.rpi.edu/instances/ and http://tw.rpi.edu/schema/, respectively, to create a full URI.
• • • uri= Optional. Specifies a URI to send to the query in the URI querystring: ?uri=<uri-encoded parameter>
• • • i= Optional. Specifies an instance name to send to the query in the URI querystring: ?i=<uri-encoded parameter>
• • • s= Optional. Specifies a schema name to send to the query in the URI querystring: ?s=<uri-encoded parameter>
• endpoint= Optional. Specifies the endpoint to query. If omitted, uses the default endpoint specified by the site administrator
• xslt= The XSLT file used to transform the SPARQL results into an XHTML fragment
• form= "The form thing is nothing" - Eric. Obsolete.

The rest of this tutorial will describe the steps listed above in the order that they are processed by the SPARQL module.

Edit the Body of a Drupal page to include the <sparql> element

With the SPARQL endpoint already up, a SPARQL query already written (and on the web), and an XSL stylesheet already written (and on the web), edit the Drupal page to include the <sparql> element listing them:

<sparql    query="http://logd.tw.rpi.edu/query/logd-stat-as-of.sparql" 
        endpoint="http://logd.tw.rpi.edu/sparql"
            xslt="http://logd.tw.rpi.edu/query/xslt/single-value-modified.xsl"></sparql>

Sample XSL to transform the SPARQL XML bindings to some HTML

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
 
 <xsl:template match="/">
   <div>This template matches the root of an XML document and then outputs an XHTML div with this sentence in it.</div>
 </xsl:template>
 
</xsl:stylesheet>
 
If you want to match a SPARQL document you would do something like this:
 
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
 
 <xsl:template match="sparql">
   <div>I found a &lt;sparql&gt; tag!</div>
 </xsl:template>
 
 <xsl:template match="/">
   <xsl:apply-templates select="sparql"/>
 </xsl:template>
 
</xsl:stylesheet>
 
XSL operates using two different languages: XPath and XQuery. This allows you to combine things:
 
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
 
 <xsl:template match="foo[@bar='baz']">
   <div>This template matches an item with tag foo if and only if it has an attribute (@) named bar that has the value &quot;baz&quot;</div>
 </xsl:template>
 
 <xsl:template match="/">
   <xsl:apply-templates select="foo"/>
 </xsl:template>
 
</xsl:stylesheet>
 
So I could match a particular SPARQL result like so:
 
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
 
 <xsl:template match="result">
   <!-- xsl:value-of takes the concatenation of the text of all descendants -->
   <b><xsl:value-of select="binding[@name='triples']"/></b>
 </xsl:template>
 
 <xsl:template match="/">
   <!-- Double slashes mean find all descendants of the current node -->
   <!-- '..' works in the same sense as its filesystem counterpart, getting the parent node of the one we're interested in -->
   <xsl:apply-templates select="//binding[@name='project' and text()='my-datagov-project']/.." />
 </xsl:template>
 
</xsl:stylesheet>

How to use cached query results

Submit the query in @query to the SPARQL endpoint at @endpoint and process the results with the XSL Transform at @xslt:

<sparql query="http://logd.tw.rpi.edu/query/logd-stat-as-of.sparql" 
            endpoint="http://logd.tw.rpi.edu/sparql" 
            xslt="http://logd.tw.rpi.edu/query/xslt/single-value-modified.xsl"></sparql>

The above example performs a live query whenever the page is loaded by a user. Although this provides the latest information, it may be unnecessary to query every time if the results are not changing. csv2rdf4lod's cache-queries.sh can be used to submit a set of SPARQL queries to an endpoint and store the results to disk, which can then be available on a web server. The <sparql endpoint> attribute can then point to this file to obtain a cached version of the query results.

Cached:

<sparql query="http://logd.tw.rpi.edu/query/logd-stat-as-of.sparql" 
            endpoint="http://logd.tw.rpi.edu/query/results/logd-stat-as-of.sparql.xml" 
            xslt="http://logd.tw.rpi.edu/query/xslt/single-value-modified.xsl"></sparql>