Tutorial

# This tutorial will explain in detail how to use and configure the Linked Data Theatre. We will start with a most basic configuration (the infamous "hello world" application) and go into more detail from their. Please look at the sidebar if you're more into self-discovery or are in need for information about a particular appearance.

Prerequisites

To use this tutorial, please be sure that you have:

An update version of the Linked Data Theatre, installed as the ROOT application of a Tomcat webserver running at port 8080.
A triple store with a sparql endpoint at http://localhost:8890/sparql, for example a default installation of Virtuoso Open Source.
A version of curl.exe. Downloads are available at https://curl.haxx.se.

Stage and site configuration

Every Linked Data Theatre contains at least one site and one stage. A site corresponds with a particular website (like www.mydoman.com, www.example.org or even localhost). It is important to note that the site also includes the port number (so localhost:8080 is a different site than localhost:8888).

Every site has at least one stage. The mainstage corresponds with the root of a site, any other site correponds with the first part after the domain name (for example: localhost:8080\stage-one or localhost:8080\stage-two).

The file WEB-INF/resource/apps/ld/config.xml contains the configuration of sites and stages. For this tutorial we will use the default config:

<theatre configuration-endpoint="http://localhost:8890/sparql" local-endpoint="http://localhost:8890/sparql" sparql="yes">
	<site domain="http://localhost:8080" backstage="http://localhost:8080>
		<stage /> <!-- mainstage -->
	</site>
</theatre>

The configuration-endpoint and local-endpoint parts refer to the SPARQL endpoint that is used to fetch the configuration of the Linked Data Theatre and as a default endpoint to query for the actual Linked Data that is presented in the Theatre.

Configuration graph

The Linked Data Theatre looks for the configuration of a stage in a particular named graph. The URI of the named graph corresponds to the following structure:

{domain}/{stage}/stage

For example (the first example is a mainstage, the second example is an explicitly named stage at the same site):

http://localhost:8080/stage
http://localhost:8080/stage-one/stage

You can always look at the content of the configuration via the backstage of a particular stage:

Structure: {domain}/{stage}/backstage
Example:   http://localhost:8080/backstage

It is possible to change the configuration via the backstage. And you can even import or export the whole configuration. The easiest way, however, is to upload configuration files directly to the triplestore. We will use this way during the tutorial. Please follow these steps:

Create a folder somewhere on your filesystem.
Create a subfolder within this folder with the name tutorial, go back to the folder created in step 1.
Put a copy of curl.exe in this folder (skip this step if you've already a working version of curl on your system)
Create a new, empty file with the name empty.ttl.

Create a script file upload.bat with the following instructions:

 @echo off
 echo Empty graph
 curl.exe -X PUT -T empty.ttl http://localhost:8890/sparql-graph-crud?graph-uri=http://localhost:8080/stage
 cd tutorial
 for %%y in (*.ttl) do (
 	echo %%~ny
 	curl.exe -X POST -T %%y http://localhost:8890/sparql-graph-crud?graph-uri=http://localhost:8080/stage
 )
 echo Done
 pause

Check if the script works, you should get the result below:
```
 Empty graph
 Done
 Press any key to continue. . .
```

You should store all files created in this tutorial in the subfolder tutorial. The name of the file doesn't matter, as long as it ends with .ttl.

Hello World

Your first try at the Linked Data Theatre would be the infamous hello world application. Please create a file helloWorld.ttl in the tutorial subfolder with the following content:

@prefix elmo: <http://bp4mc2.org/elmo/def#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix stage: <http://localhost:8080/stage#>.

stage:helloWorld a elmo:Representation;
	elmo:url-pattern "query/helloWorld$";
	elmo:appearance elmo:HtmlAppearance;
	elmo:data [
		rdfs:label "Hello World";
		elmo:html '''
			<h3>Hello World!</h3>
			<p>This is the first of the Linked Data Theatre examples.</p>
		''';
	]
.

Execute the upload.bat script and look at the result at http://localhost:8080/query/helloWorld You should get something like the screenshot below. hello world

For every example in the tutorial, please use a different filename (except when instructed otherwise) and execute upload.bat, after you've created the file, so you can look at the result in a browser. We won't mention this any more, but please do!

Visualizing a resource from dbpedia

Wikipedia pages are available as Linked Data via dbpedia. Let's visualize some data from dbpedia. For example: showing all properties from the city of Amersfoort (http://dbpedia.org/resource/Amersfoort):

@prefix elmo: <http://bp4mc2.org/elmo/def#>.
@prefix stage: <http://localhost:8080/stage#>.

stage:amersfoort a elmo:Representation;
	elmo:url-pattern "query/amersfoort$";
	elmo:endpoint <http://nl.dbpedia.org/sparql>;
	elmo:query '''
		CONSTRUCT {
			<http://nl.dbpedia.org/resource/Amersfoort> ?p ?o
		}
		WHERE {
			<http://nl.dbpedia.org/resource/Amersfoort> ?p ?o
		}
	'''
.

As you might notice: we didn't specify a particular elmo:appearance in this example. De LDT will try to figure out which appearance looks best (in this case: an elmo:ContentAppearance.

You probably want to tune the result a bit: this way, it isn't much better than the original page! You can use elmo:fragments to spicy things up, for example (make these changes in the same file you've created above):

@prefix elmo: <http://bp4mc2.org/elmo/def#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix stage: <http://localhost:8080/stage#>.

stage:amersfoort2 a elmo:Representation;
	elmo:fragment [
		elmo:applies-to elmo:Fragment;
		elmo:appearance elmo:HiddenAppearance;
	];
	elmo:fragment [
		elmo:applies-to rdfs:comment;
		rdfs:label "discription"@en;
		rdfs:label "omschrijving"@nl;
	];
	elmo:url-pattern "query/amersfoort2$";
	elmo:endpoint <http://nl.dbpedia.org/sparql>;
	elmo:query '''
		CONSTRUCT {
			<http://nl.dbpedia.org/resource/Amersfoort> ?p ?o
		}
		WHERE {
			<http://nl.dbpedia.org/resource/Amersfoort> ?p ?o
		}
	'''
.

The first fragment is a special one: it defines the default for any fragment. In this case: we don't want to show any properties, instead the ones we explicitly define. The second one specifies how to show the property rdfs:comment.

Because we want to look into a lot more dbpedia resources, we might want to generalize from the first example. We can do this by using a elmo:uri-pattern instead of a elmo:url-pattern. This will tell the LDT to use this specific representation whenever the URI of the resource itself corresponds to the uri-pattern:

@prefix elmo: <http://bp4mc2.org/elmo/def#>.
@prefix stage: <http://localhost:8080/stage#>.

stage:dbpediaNLResource a elmo:Representation;
	elmo:uri-pattern "^http://nl.dbpedia.org/";
	elmo:endpoint <http://nl.dbpedia.org/sparql>;
	elmo:query stage:ResourceQuery;
.
stage:dbpediaResource a elmo:Representation;
	elmo:uri-pattern "^http://dbpedia.org/";
	elmo:endpoint <http://dbpedia.org/sparql>;
	elmo:query stage:ResourceQuery;
.
stage:ResourceQuery a elmo:Query;
	elmo:query '''
	CONSTRUCT {
			<@SUBJECT@> ?p ?o.
			?o rdfs:label ?olabel
		}
		WHERE {
			<@SUBJECT@> ?p ?o
			FILTER (isIri(?o) or lang(?o)="" or lang(?o)="@LANGUAGE@")
			OPTIONAL {
				?o rdfs:label ?olabel.
				FILTER (lang(?olabel) or lang(?olabel)="@LANGUAGE@")
			}
		}
	'''
.

Let's try it out: http://localhost:8080/resource?subject=http://nl.dbpedia.org/resource/Amersfoort. Please don't hesistate to follow the links. You will notice that all dbpedia links will actually work! Data is fetched from two different SPARQL endpoints: at nl.dbpedia.org for the dutch resources, and dbpedia.org for the regular resources (like vocabularies).

You might notice that the're something going on here. Both representations refer to the same query (stage:ResourceQuery). This is a way of reusing SPARQL statements that you use often for different situations. This query also uses an open parameter: @SUBJECT@ this is replaced by the actual URI of the subject resource.

The Graph appearance

Wouldn't it be cool if we could show the Linked Data actually in a graph? And maybe we want to show links going in both directions (for example: what kind of information is available about Amersfoort). This can be done with the elmo:GraphAppearance. Remember that this graph appearance will only work if and only if a @SUBJECT@ is available. So we might append the resource configuration we've create above. Please change this configuration so it looks like the one below:

@prefix elmo: <http://bp4mc2.org/elmo/def#>.
@prefix stage: <http://localhost:8080/stage#>.

stage:dbpediaNLResource a elmo:Representation;
	elmo:uri-pattern "^http://nl.dbpedia.org/";
	elmo:endpoint <http://nl.dbpedia.org/sparql>;
	elmo:query stage:ResourceQuery;
	elmo:index "1";
	elmo:contains stage:dbpediaNLResourceGraph;
.
stage:dbpediaResource a elmo:Representation;
	elmo:uri-pattern "^http://dbpedia.org/";
	elmo:endpoint <http://dbpedia.org/sparql>;
	elmo:query stage:ResourceQuery;
.
stage:ResourceQuery a elmo:Query;
	elmo:query '''
	CONSTRUCT {
			<@SUBJECT@> ?p ?o.
			?o rdfs:label ?olabel
		}
		WHERE {
			<@SUBJECT@> ?p ?o
			FILTER (isIri(?o) or lang(?o)="" or lang(?o)="@LANGUAGE@")
			OPTIONAL {
				?o rdfs:label ?olabel.
				FILTER (lang(?olabel) or lang(?olabel)="@LANGUAGE@")
			}
		}
	'''
.

stage:dbpediaNLResourceGraph a elmo:Part;
	elmo:appearance elmo:GraphAppearance;
	elmo:index "2";
	elmo:endpoint <http://nl.dbpedia.org/sparql>;
	elmo:query '''
		CONSTRUCT {
			<@SUBJECT@> ?p ?o.
			<@SUBJECT@> rdfs:label ?slabel.
			?o rdfs:label ?olabel
		}
		WHERE {
			<@SUBJECT@> ?p ?o.
			<@SUBJECT@> rdfs:label ?slabel.
			?o rdfs:label ?olabel
			FILTER (?p!=<http://dbpedia.org/ontology/wikiPageWikiLink>)
		}
	''';
.

The extra property elmo:contains directs the theatre to present a second appearance on the same page. This is our graph appearance. You might notice the use of elmo:index to define the order of the specific appearances.

Table appearance

Up to this point, we've only used CONSTRUCT queries to fetch data from a sparql endpoint. But we can also use a SELECT query. Because the result is more suited for a table, the LDT will present the result using a table appearance.

@prefix elmo: <http://bp4mc2.org/elmo/def#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix stage: <http://localhost:8080/stage#>.

stage:dbpedia a elmo:Representation;
	elmo:url-pattern "/query/dbpedia$";
	elmo:endpoint <http://nl.dbpedia.org/sparql>;
	elmo:fragment [
		elmo:applies-to "type";
		rdfs:label "Classes at nl.dbpedia"@en;
		rdfs:label "Aanwezige klassen in nl.dbpedia"@nl;
	];
	elmo:query '''
		SELECT DISTINCT ?type ?type_label (count(?s) as ?type_count)
		WHERE {
			?s rdf:type ?type.
			OPTIONAL {?type rdfs:label ?type_label}
		}
		LIMIT 100
	''';
.

The ?type_label and ?type_count will trigger specific behaviour: instead of an extra column, the _label is used for the actual label of the original variable, and _count is used to create an annotation in the same column.

Geospatial appearance

Geospatial information and Linked Data work very well together. So it would be fun to plot some Linked Data on a map. The GeoAppearance is well suited for this goal. We will use some Linked Data from a dutch Geospatial Linked Data endpoint, https://data.pdok.nl.

Warning: using the pdok endpoint is a bit more complicated than the dbpedia endpoint, because the pdok endpoint is a secure (https) endpoint with a certificate that is not present in the default java keystore. If you experience the error "(xxforms-internal-error)", you have to perform the following steps:

Download the files properties-local.xml and ldt.jks

Put these files in the `D:/Tomcat/webapps/ROOT/WEB-INF/resources/config directory.

If the installation of tomcat is in a different place, please update the file properties-local.xml accordingly.

Restart Tomcat.

We can show the borders of the city of Amersfoort via:

@prefix elmo: <http://bp4mc2.org/elmo/def#>.
@prefix stage: <http://localhost:8080/stage#>.

stage:geo a elmo:Representation;
	elmo:url-pattern "query/geo$";
	elmo:appearance elmo:GeoAppearance;
	elmo:endpoint <https://data.pdok.nl/sparql>;
	elmo:query '''
		prefix geosparql: <http://www.opengis.net/ont/geosparql#>
		prefix geo: <http://www.w3.org/2003/01/geo/wgs84_pos#>
		construct {
			?city geo:geometry ?wkt.
			?city rdfs:label ?cityname.
		}
		WHERE {
			select *
			where {
				?city rdfs:label ?cityname.
				?city geosparql:hasGeometry ?geo.
				?geo geosparql:asWKT ?wkt.
				FILTER (?city = <http://bag.basisregistraties.overheid.nl/bag/id/woonplaats/1664>)
			}
			limit 1
		}
	'''
.

Tutorial

Prerequisites

Stage and site configuration

Configuration graph

Hello World

Visualizing a resource from dbpedia

The Graph appearance

Table appearance

Geospatial appearance

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally