tw-sparql and using the <sparql> tag

Printer-friendly version

NOTE: This page applies to the TWC Drupal module known as tw-sparql or twsparql...

Prerequisites

Infrastructure:

  • Drupal version 6 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:

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

Sample XSL to transform the SPARQL XML bindings to some HTML

  1. <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
  2.  
  3. <xsl:template match="/">
  4. <div>This template matches the root of an XML document and then outputs an XHTML div with this sentence in it.</div>
  5. </xsl:template>
  6.  
  7. </xsl:stylesheet>
  8.  
  9. If you want to match a SPARQL document you would do something like this:
  10.  
  11. <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
  12.  
  13. <xsl:template match="sparql">
  14. <div>I found a &lt;sparql&gt; tag!</div>
  15. </xsl:template>
  16.  
  17. <xsl:template match="/">
  18. <xsl:apply-templates select="sparql"/>
  19. </xsl:template>
  20.  
  21. </xsl:stylesheet>
  22.  
  23. XSL operates using two different languages: XPath and XQuery. This allows you to combine things:
  24.  
  25. <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
  26.  
  27. <xsl:template match="foo[@bar='baz']">
  28. <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>
  29. </xsl:template>
  30.  
  31. <xsl:template match="/">
  32. <xsl:apply-templates select="foo"/>
  33. </xsl:template>
  34.  
  35. </xsl:stylesheet>
  36.  
  37. So I could match a particular SPARQL result like so:
  38.  
  39. <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
  40.  
  41. <xsl:template match="result">
  42. <!-- xsl:value-of takes the concatenation of the text of all descendants -->
  43. <b><xsl:value-of select="binding[@name='triples']"/></b>
  44. </xsl:template>
  45.  
  46. <xsl:template match="/">
  47. <!-- Double slashes mean find all descendants of the current node -->
  48. <!-- '..' works in the same sense as its filesystem counterpart, getting the parent node of the one we're interested in -->
  49. <xsl:apply-templates select="//binding[@name='project' and text()='my-datagov-project']/.." />
  50. </xsl:template>
  51.  
  52. </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:

  1. <sparql query="http://logd.tw.rpi.edu/query/logd-stat-as-of.sparql"
  2. endpoint="http://logd.tw.rpi.edu/sparql"
  3. 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:

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