How-to adapt the “hello Sparnatural” page to your own Knowledge Graph
Version : 1.0
Last modified on : june 2023
Authors : thomas.francart@sparna.fr, marie.muller@sparna.fr
License : this document is placed under the LGPL 3.0 license, like Sparnatural
Content of the tutorial folder 3
Setup your local working environment 4
Allow loading of local files in your browser 4
Ensure your SPARQL endpoint is CORS-enabled, or use a proxy 6
Allow CORS on your triplestore 6
…or use Sparnatural SPARQL proxy 7
Point the tutorial page to your SPARQL service 7
Create your first Sparnatural configuration 8
Setup your configuration ontology in Protégé 8
Import Sparnatural ontologies 8
Specify your configuration ontology URI 9
Point demo page to your config file 15
Annex : adjust the example queries 17
Welcome to this guide on how to setup the “Hello Sparnatural” page ! “Hello Sparnatural” is the tutorial page released with Sparnatural in each of the releases. This documentation will guide you on the necessary steps to work with this tutorial page, and start adapting it to your own knowledge graph. Once customized you can keep the tutorial page in your local machine or publish it online, provided that your SPARQL endpoint is also publicly available.
At the end of this tutorial, you will have a working HTML page demonstrating the feasibility of plugin Sparnatural on your own data. You can then explore further possibilities of configuring Sparnatural in the other guide “How to configure Sparnatural”, and adapt the look-and-feel of the page to match your website.
In order to follow this guide, you need the following prerequisites:
You need to have your own SPARQL-accessible dataset. If you don’t have any SPARQL-accessible dataset, you can use the DBPedia dataset, accessible at https://dbpedia.org/sparql. GraphDB users can find their active repository SPARQL URL in the home page, in the “link” icon in the “Active repository” section:
You need to have a basic understanding of the structure of your dataset. More specifically you need to know the URI identifiers of 2 classes in your ontology, and one property linking these two classes. If you don’t know this information, try to find the documentation of your dataset, in the form of UML diagrams or documentation tables.
You need to have the Protégé OWL editor installed on your machine. To install Protégé, go to https://protege.stanford.edu/.
You need to have a basic understanding of HTML, and a basic text editor to edit an HTML page.
This guide will explain:
How to setup your local work environment
How to adjust the tutorial page to use your configuration file and your own SPARQL endpoint URL
How to setup a minimal configuration demonstrating how Sparnatural can work on your data
What are the next steps once you completed this tutorial
The “Hello Sparnatural” tutorial page is included with each release of Sparnatural starting from 8.4.0. To get this tutorial page:
go to the latest release of Sparnatural
download the “hello-sparnatural.zip” file from the assets list
unzip it in a local folder on your computer
The tutorial folder is based on a very simple Bootstrap HTML template, in which Sparnatural is inserted and integrated with the YasGUI SPARQL editor and query result viewer. While using YasGUI is an obvious choice, YasGUI is *not* a requirement of Sparnatural. You can choose to present query results differently than in YasGUI, and you may not want to display the raw SPARQL query to the user.
The tutorial folder is composed of the following files:
Files you will edit in this tutorial:
index.html: the main HTML page that you can open in a browser and that includes the Sparnatural component.
config.ttl: a Sparnatural configuration file. In this tutorial you will create your own new config file.
example-queries.js: sample queries that you can change after your configuration has been adapted.
Files you can further customize after this tutorial if you want to enhance your demo:
main.js: the Javascript code executed by index.html, containing Sparnatural event listeners as well as YasGUI initialization code.
styles.css: the specific CSS rules for the index.html page.
Files you will not have to edit:
sparnatural.js and sparnatural.css: the code of the Sparnatural component, with its CSS rules
sparnatural-yasgui-plugins.js: the code of the result table display plugin[1]
fa subfolder: folder containing the Fontawesome free icon set.
Open the file index.html page from the tutorial folder in your browser. You will see a blank page with Sparnatural not loading properly, and and error in your browser console[2]:
This is because browsers, for security reasons, disable by default the dynamic loading of other files from your local directory - in our case the Sparnatural configuration file. In order for this to work, we need to instruct the browser that it is safe to dynamically load local files. This is called “enabling CORS for local files”.
/!\ Don’t worry, changing these settings will not affect the other security restrictions in your browser, in particular related to CORS.
/!\ Of course, this is only in order to work with local files. Once deployed on a web server, this restriction is not applicable anymore, and normal users of your page will not have to set the same settings.
The procedure to enable CORS for local files depends on the browser:
Firefox
To make Firefox CORS-enabled for local files:
Open Firefox
Type “about:config” in the address bar
Accept security warning
Search for the config security.fileuri.strict_origin_policy
Set this config to “false”
Restart your browser to make sure this is taken into account
Chrome, Chromium or Edge
To make Chrome, Chromium or Edge CORS-enabled for local files :
Close Chrome
Open a command-line or a terminal
Re-run chrome with the flag “--allow-file-access-from-files”, e.g. on Ubuntu Linux “chromium --allow-file-access-from-files”
You can create a shortcut with this flag set, for example in Windows, create a shortcut to Chrome and modify the command being run in the shortcut properties:
Once you have configured this setting, try reopening the index.html page. You should see Sparnatural loaded correctly:
CORS stands for Cross-Origin Resource Sharing. It is a mechanism by which a web client can retrieve resources from a different server from the one which it was originally loaded[3]. With CORS, servers can indicate that they allow clients loaded from another domain (or from certain other domains) to send them requests. Note that this restriction applies to client-server interactions, not to server-server interactions.
In the case of Sparnatural, it is the HTML page that sends the SPARQL query directly to a SPARQL service. This SPARQL service thus needs to allow clients/webpages to send queries to it even if they are loaded from another domain, otherwise the query will simply fail with a security warning, and you can see security errors in the requests of your browser console.
You thus need to make sure that the SPARQL endpoint you want to query with Sparnatural is CORS-enabled, unless in your target architecture the Sparnatural page will be served from the same domain as the SPARQL endpoint.
In case the SPARQL endpoint you want to query is public, the website https://www.test-cors.org/ can allow you to check if CORS is enabled. Most of the large SPARQL services already allow CORS, e.g. DBpedia, Wikidata, etc.
The procedure to allow CORS from your triplestore varies depending on the tool.
GraphDB
To enable CORS on GraphDB, you need to set some specific runtime properties. Please refer to the GraphDB documentation at https://graphdb.ontotext.com/documentation/10.2/directories-and-config-properties.html?highlight=cors#workbench-properties
Virtuoso
To enable CORS on Virtuoso, follow the documentation at https://vos.openlinksw.com/owiki/wiki/VOS/VirtTipsAndTricksCORsEnableSPARQLURLs
Sometimes you can’t modify the triplestore parameters, or your security policy would not allow it. In that case we provide a SPARQL proxy that is CORS-enabled and that will forward the request to a target SPARQL endpoint, just acting as a bridge between Sparnatural and the target SPARQL endpoint. This SPARQL proxy is deployed at https://proxy.sparnatural.eu and documented in the Sparnatural documentation.
/!\ Of course this is only a temporary workaround, and you must not use the online proxy server in a production environment. You should deploy your own SPARQL proxy in that case. The code of the SPARQL proxy server is open-source in its own Github repository, just in case.
Now that you have 1. adjusted the security settings of your browser and 2. enabled CORS on your triplestore (or used a proxy), it is time to point the tutorial page to your endpoint !
To do this, edit the index.html file, and search for the “<spar-natural” HTML element name (around line 68) and set the “endpoint” configuration attribute to your SPARQL endpoint URL (or to the proxy URL):
<spar-natural
src="config.ttl"
endpoint="https://localhost:7200/repositories/myRepo"
lang="en"
defaultLang="en"
distinct="true"
limit="1000"
debug="true"
></spar-natural>
Now the tutorial page is configured to point to your endpoint. Reload the page in your browser and you should see the endpoint URL displayed:
Now that the Sparnatural tutorial page points to your SPARQL endpoint, it is time to configure the query builder following your data structure. All this can be done via the configuration ontology you need to construct in Protégé.
Open Protégé, and start a new config ontology of yours (keep the provided config.ttl from the tutorial folder apart).
Sparnatural comes with 2 ontologies that need to be imported (through owl:imports) in your own configuration ontology :
A core configuration ontology at http://data.sparna.fr/ontologies/sparnatural-config-core
A datasource configuration ontology at http://data.sparna.fr/ontologies/sparnatural-config-datasources
Import the 2 Sparnatural configuration ontologies in your ontology ;
To import these ontologies in Protégé use section under “Imported Ontologies > Direct imports” and then in the dialog select “Import an ontology contained in a document located on the web”, and then enter the URI of an ontology above. Repeat the process for the other one.
Once both ontologies are loaded in Protégé, check in the Classes and Object Properties tab of Protégé that you see now you can see imported classes and properties from Sparnatural base ontologies.
Back in the “Active Ontology” tab, in the Ontology IRI field above the screen, write the https address where your configuration ontology is theoretically to be published (ex : https://data.mydomain.com/ontologies/sparnatural-config)
You are now ready to populate the existing structure with the entities (« Classes ») and the relations (« Object properties ») of your knowledge graph.
We will suppose in this tutorial that the knowledge graph data model consists of FOAF Persons and Organizations, with respective URI foaf:Person and foaf:Organization, linked with a property foaf:member. You will need to adapt the identifiers with your own URI identifiers.
First you need to create a class for each kind of entity : Organization and Person. Switch to the “Classes” tab for this.
Selec the “SparnaturalClass” in the class tree, and click the button to add a subclass under it. In the dialog you can directly type in the « Name » field of the dialog the real URI of the FOAF class you want to add; we will start with foaf:Person http://xmlns.com/foaf/0.1/Person .
Once created, edit the attributes of the new class by clicking the “+” button next to the « Annotations » label:
First add an « rdfs:label » annotation, in language “en”, with value “Person”.
Note that you can create labels in as many languages as needed as the Sparnatural component can switch languages, but for the moment let’s stick to English.
Second, add another annotation of type “tooltip” and enter a description that shall be displayed as a tooltip when the user hovers the corresponding entry in the query builder. You can enter the definition of the foaf:Person class “The foaf:Person class represents people. Something is a foaf:Person if it is a person. We don't nitpic about whether they're alive, dead, real, or imaginary.”
Add a third annotation to set the icon. Select the annotation type “faIcon” that is under “icon”, and enter the value “fa-solid fa-user”.
In general, to search for an icon code, go on https://fontawesome.com/ website, and search for a free License icon in the search bar, note the icon code (typically something like “fa-solid fa-user”), and enter this as a value.
Repeat the same process to create http://xmlns.com/foaf/0.1/Organization, with label “Organization” in language “en”, tooltip “An organisation represents a kind of Agent corresponding to social instititutions such as companies, societies etc. ” , and icon code “fa-solid fa-building”.
We will now create the relationship “member” between an Organization and a Person, and we will indicate we want it to be created as a dropdown list.
Switch into the « Object properties » tab. This is where the different kind of relations between entities can be set up as List properties, Autocomplete properties, Tree, Search fields, Map properties, Time properties and so on.
Unfold the object properties tree, select ListProperty entry, and click on the button to add a subproperty under it. Use http://xmlns.com/foaf/0.1/member as its URI.
Do as for the classes to give it an rdfs:label annotation in English.
We will relate foaf:member property to foaf:Organization class as a Domain and foaf:Person class as a Range, this you can edit in the Description area of your Protégé :
Select “foaf:Organization” as a value in the “Domains” section, and “foaf:Person” as a value in the “Ranges” section.
2 classes, one property, domain and range defined, just enough to see what your ontology looks like in Sparnatural’s interface !
Save your ontology in the “hello-sparnatural” tutorial folder with a name of your choice. Save it preferably in Turtle, or in RDF/XML, but NOT in an OWL-specific serialization (such as OWL/XML). Use the file name of your choice, like “myconfig.ttl”.
Edit the index.html page, look for the “<spar-natural>” tag and set the “src” attribute to point to your configuration file name, like “myconfig.ttl”, and save the file:
<spar-natural
src="myconfig.ttl"
endpoint="https://localhost:7200/repositories/myRepo"
lang="en"
defaultLang="en"
distinct="true"
limit="1000"
debug="true"
></spar-natural>
Open a CORS-enabled browser to load the index.html file in it : you should see your 2 classes linked with your properties, populated by the data from your SPARQL endpoint:
If everything is OK, you should see a list of Person URIs (or another class from your knowledge graph) listed in the dropdown. You can try to build a query and verify that it works !
If it does not work:
check that the URIs you used in your configuration file for the 2 classes and the property do correspond to actual URI from your knowledge graph.
debug the SPARQL query by opening your web browser console (F12 key) and monitor the SPARQL query that is sent to populate the dropdown box.
Congratulations, you have successfully completed this “Hello Sparnatural” tutorial !
Look at the provided configuration ontology
The tutorial folder comes with an included ontology in the “config.ttl” file. You can try loading this ontology in Protégé and have a look at the various configuration features it contains, as a source of inspiration.
Read the configuration how-to
Sparnatural offers many nice features to explore your knowledge graph :
Autocomplete widgets, trees, maps, calendars and more.
Ability to map the configuration ontology to the underlying knowledge graph structure, if you want to display things with a different structure.
Ability to enable optional, negative or multilingual properties.
Ability to customize Sparnatural through a CSS theme file.
Ability to configure Sparnatural using a (Google or Excel) spreadsheet
All of these you can learn in the « How-to configure Sparnatural » document. The Sparnatural documentation website offers comprehensive documentation on all the features. The Github repository of Sparnatural is where you can ask questions, report bugs, and reach us.
Tune the HTML and upload the demo page online
You can further tune the content of the index.html webpage, and customize it anyway you like. Once done, you can simply upload the entire folder on a (your) web server so that it is publicly accessible !
To give the users a few examples of queries they could write in the interface, you can save sample queries to display in the HTML page.
Save the sample queries only after your Sparnatural configuration ontology is stable. Otherwise there is a risk that you will need to rewrite them.
Start creating a query via the in-place query builder and open your browser console at the same time. Here you can see that each time you add a new parameter to your query, a new « Sparnatural JSON query structure » message appears.
Once your query written, then find the last « Object » in the Sparnatural JSON query structures listed here :
then right click on it and select « Copy object ».
Edit the example-querues.js javascript file :
Select the value of “example_1” variable, from the first “{“ character to the last “}”, and Paste what you have copied from the console.
Repeat the same process to save a second query in the “example_2” variable.
Add more variables if needed.
Save the file
Edit the index.html file and uncomment the example queries section around line 57 to 64, above the “<spar-natural>” tag:
<!-- uncomment to enable links to load sample queries
<p>
Load example queries :
<a href="#" onclick="document.querySelector('spar-natural').loadQuery(window['example_1']);return false;">example 1</a>
|
<a href="#" onclick="document.querySelector('spar-natural').loadQuery(window['example_2']);return false;">example 2</a>
</p>
-->
Adjust the title of the query accordingly (e.g. replace “example 1” with “My beautiful query”) :
Your query is saved and can be loaded in the query builder in one click !
[1] This plugin is part of another project at https://github.com/sparna-git/sparnatural-yasgui-plugins
[2] The browser console can be opened with the F12 key
[3] For more information we suggest to check https://enable-cors.org/, and the wikipedia page on Same Origin Policy at https://en.wikipedia.org/wiki/Same-origin_policy
“Hello Sparnatural”
How-to adapt the “hello Sparnatural” page to your own Knowledge Graph
Version : 2.1
Last modified on : october 2024
Authors : thomas.francart@sparna.fr, marie.muller@sparna.fr
License : this document is placed under the LGPL 3.0 license, like Sparnatural
Content of the tutorial folder 3
Setup your local working environment 4
Allow loading of local files in your browser 4
Ensure your SPARQL endpoint is CORS-enabled, or use a proxy 6
Allow CORS on your triplestore 6
…or use Sparnatural SPARQL proxy 7
Point the tutorial page to your SPARQL service 7
Create your first Sparnatural configuration 8
Setup your configuration using the spreadsheet 8
Create 2 entities in the « Entities » tab 8
Create the « foaf:Person » entity 8
Create the « foaf:Organization » entity 10
Create a property in the « Properties » tab 10
Convert the spreadsheet in RDF 12
Point the demo page to your config file 13
Annex : adjust the example queries 15
Welcome to this guide on how to setup the “Hello Sparnatural” page ! “Hello Sparnatural” is the tutorial page released with Sparnatural in each of the releases. This documentation will guide you on the necessary steps to work with this tutorial page, and start adapting it to your own knowledge graph. Once customized you can keep the tutorial page in your local machine or publish it online, provided that your SPARQL endpoint is also publicly available.
At the end of this tutorial, you will have a working HTML page demonstrating the feasibility of plugin Sparnatural on your own data. You can then explore further possibilities of configuring Sparnatural in the other guide “How to configure Sparnatural”, and adapt the look-and-feel of the page to match your website.
In order to follow this guide, you need the following prerequisites:
You need to have your own SPARQL-accessible dataset. If you don’t have any SPARQL-accessible dataset, you can use the DBPedia dataset, accessible at https://dbpedia.org/sparql. GraphDB users can find their active repository SPARQL URL in the home page, in the “link” icon in the “Active repository” section:
You need to have a basic understanding of the structure of your dataset. More specifically you need to know the URI identifiers of 2 classes in your ontology, and one property linking these two classes. If you don’t know this information, try to find the documentation of your dataset, in the form of UML diagrams or documentation tables.
You need to have a spreadsheet or online spreadsheet editor (Excel or Google Sheets for example)
You need to have a basic understanding of HTML, and a basic text editor to edit an HTML page.
This guide will explain:
How to setup your local work environment
How to adjust the tutorial page to use your configuration file and your own SPARQL endpoint URL
How to setup a minimal configuration demonstrating how Sparnatural can work on your data
What are the next steps once you completed this tutorial
The “Hello Sparnatural” tutorial page is included with each release of Sparnatural starting from 8.4.0. To get this tutorial page:
go to the latest release of Sparnatural
download the “hello-sparnatural.zip” file from the assets list
unzip it in a local folder on your computer
The tutorial folder is based on a very simple Bootstrap HTML template, in which Sparnatural is inserted and integrated with the YasGUI SPARQL editor and query result viewer[1].
The tutorial folder is composed of the following files:
Files you will edit in this tutorial:
index.html: the main HTML page that you can open in a browser and that includes the Sparnatural component.
config.ttl: a basic Sparnatural configuration file. In this tutorial you will create your own new config file.
config.xlsx : the SHACL configuration spreadsheet that you will edit and convert to produce a new version of the « config.ttl » file
example-queries.js: sample queries that you can change after your configuration has been adapted.
Files you can further customize after this tutorial if you want to enhance your demo:
main.js: the Javascript code executed by index.html, containing Sparnatural event listeners as well as YasGUI initialization code.
styles.css: the specific CSS rules for the index.html page.
Files you will not have to edit:
sparnatural.js and sparnatural.css: the code of the Sparnatural component, with its CSS rules
sparnatural-yasgui-plugins.js: the code of the result table display plugin[2]
fa subfolder: folder containing the Fontawesome free icon set.
config-hello-sparnatural-foaf.xlsx : a copy of the « config.xlsx » edited to match the content of this tutorial, so that you can compare with what you do
Open the file index.html page from the tutorial folder in your browser. You will see a blank page with Sparnatural not loading properly, and and error in your browser console[3]:
This is because browsers, for security reasons, disable by default the dynamic loading of other files from your local directory - in our case the Sparnatural configuration file. In order for this to work, we need to instruct the browser that it is safe to dynamically load local files. This is called “enabling CORS for local files”.
/!\ Don’t worry, changing these settings will not affect the other security restrictions in your browser, in particular related to CORS.
/!\ Of course, this is only in order to work with local files. Once deployed on a web server, this restriction is not applicable anymore, and normal users of your page will not have to set the same settings.
The procedure to enable CORS for local files depends on the browser:
Firefox
To make Firefox CORS-enabled for local files:
Open Firefox
Type “about:config” in the address bar
Accept security warning
Search for the config security.fileuri.strict_origin_policy
Set this config to “false”
Restart your browser to make sure this is taken into account
Chrome, Chromium or Edge
To make Chrome, Chromium or Edge CORS-enabled for local files :
Close Chrome
Open a command-line or a terminal
Re-run chrome with the flag “--allow-file-access-from-files”, e.g. on Ubuntu Linux “chromium --allow-file-access-from-files”
You can create a shortcut with this flag set, for example in Windows, create a shortcut to Chrome and modify the command being run in the shortcut properties:
Once you have configured this setting, try reopening the index.html page. You should see Sparnatural loaded correctly:
CORS stands for Cross-Origin Resource Sharing. It is a mechanism by which a web client can retrieve resources from a different server from the one which it was originally loaded[4]. With CORS, servers can indicate that they allow clients loaded from another domain (or from certain other domains) to send them requests. Note that this restriction applies to client-server interactions, not to server-server interactions.
In the case of Sparnatural, it is the HTML page that sends the SPARQL query directly to a SPARQL service. This SPARQL service thus needs to allow clients/webpages to send queries to it even if they are loaded from another domain, otherwise the query will simply fail with a security warning, and you can see security errors in the requests of your browser console.
You thus need to make sure that the SPARQL endpoint you want to query with Sparnatural is CORS-enabled, unless in your target architecture the Sparnatural page will be served from the same domain as the SPARQL endpoint.
In case the SPARQL endpoint you want to query is public, the website https://www.test-cors.org/ can allow you to check if CORS is enabled. Most of the large SPARQL services already allow CORS, e.g. DBpedia, Wikidata, etc.
The procedure to allow CORS from your triplestore varies depending on the tool.
GraphDB
To enable CORS on GraphDB, you need to set some specific runtime properties. Please refer to the GraphDB documentation at https://graphdb.ontotext.com/documentation/10.2/directories-and-config-properties.html?highlight=cors#workbench-properties
Virtuoso
To enable CORS on Virtuoso, follow the documentation at https://vos.openlinksw.com/owiki/wiki/VOS/VirtTipsAndTricksCORsEnableSPARQLURLs
Sometimes you can’t modify the triplestore parameters, or your security policy would not allow it. In that case we provide a SPARQL proxy that is CORS-enabled and that will forward the request to a target SPARQL endpoint, just acting as a bridge between Sparnatural and the target SPARQL endpoint. This SPARQL proxy is deployed at https://proxy.sparnatural.eu and documented in the Sparnatural documentation.
/!\ Of course this is only a temporary workaround, and you must not use the online proxy server in a production environment. You should deploy your own SPARQL proxy in that case. The code of the SPARQL proxy server is open-source in its own Github repository, just in case.
Now that you have 1. adjusted the security settings of your browser and 2. enabled CORS on your triplestore (or used a proxy), it is time to point the tutorial page to your endpoint !
To do this, edit the index.html file, and search for the “<spar-natural” HTML element name (around line 68) and set the “endpoint” configuration attribute to your SPARQL endpoint URL (or to the proxy URL):
<spar-natural
src="config.ttl"
endpoint="https://localhost:7200/repositories/myRepo"
lang="en"
defaultLang="en"
distinct="true"
limit="1000"
debug="true"
></spar-natural>
Here you can also adjust the language parameters : the default language is the language in which the knowledge graph is supposed to always have a label for all entities. This is meant to deal with situations where some entities do have a label in the user preferred language, and others don’t, but will have a label in the default language. This is explained in more details in the « how to configure » documentation.
Now the tutorial page is configured to point to your endpoint. Reload the page in your browser and you should see the endpoint URL displayed:
Now that the Sparnatural tutorial page points to your SPARQL endpoint, it is time to configure the query builder following your data structure. All this can be done in the configuration file config.xlsx. This spreadsheet is actually a way to encode a SHACL specification of your data model, which Sparnatural will use as an input.
In the provided config.xlsx file, you will find a small configuration example working on DBPedia. We will guide you on how to adapt it with different classes and properties. The followup « how to configure » documentation contains an in-depth documentation of the structure of the Excel table, which we will not describe in details here.
In the « Entities » tab, leave the rows from 1 to 9 unchanged. Start by emptying the example configuration entities lien 10 and onwards (from 10 to 14 exactly), so you start with an empty table.
We will suppose in this tutorial that the knowledge graph data model consists of FOAF Persons and Organizations, with respective URI foaf:Person and foaf:Organization, linked with a property foaf:member. You will need to adapt the identifiers with your own URI identifiers.
The foaf:Person entity will be created on line 10.
URI
In cell A10 you write the URI of the configuration entity (actually, the URI of a SHACL NodeShape) : this column uses the "this" prefix declared in the header of the configuration sheet, and the same local part of the class URI, here « Person », which gives the following URI : « this:Person ».
Sort order : sh:order^^xsd:integer
In cell B10, enter the sort order of the entity in the class dropdown list, here « 1 » as we want it to appear first.
Fontawesome icon : volipi:iconName
In cell C10, enter the Fontawesome icon code for the entity, here "fa-solid fa-user"
In general, to search for an icon code, go on https://fontawesome.com/ website, and search for a free License icon in the search bar, note the icon code (typically something like “fa-solid fa-user”), and enter this as a value.
Type : rdf:type(separator=",")
In cell D10, enter « sh:NodeShape ». The value of the column D needs to always be set to « sh:NodeShape ».
This should give you something like this :
Target Class : sh:targetClass
In cell E10, write the identifier of the class in the OWL ontology to which the entity in the configuration corresponds : here « foaf:Person ».
Label : rdfs:label@en
In cell F10, enter the label that will be displayed in Sparnatural for this entity, in english (you can adjust the language code in the header row line 9 to another language if needed - don’t forget to change the « lang » parameter of the <spar-natural /> HTML element in that case).
Tooltip : sh:description@en
In cell H10, enter the following tooltip in English (which is the definition of the Person class given in the FOAF ontology) : « The Person class represents people [...] We don't nitpic about whether they're alive, dead, real, or imaginary. »
Now your very first SHACL entity has been created !
Repeat the same process to create foaf:Organization line below on line 11, with the following values :
A11 : write the URI « this:Organization » ;
B11 : the order « 2 » ;
C11 : Fontawesome icon code « fa-solid fa-building » ;
D11 : rdf:type « sh:NodeShape » ;
E11 : target Class « foaf:Organization » ;
F11 : english label « Organization » ;
H11 : tooltip « The Organization class represents a kind of Agent corresponding to social institutions such as companies, societies etc. »
This should give you something like this :
All the different options are explained in more details in the « How to configure Sparnatural » manual, chapter « Declaring classes ».
Now let’s add a « foaf:member » property in tab “Properties”. This property will link our 2 classes together, and we will indicate we it as a dropdown list.
Start by emptying all the table from line 8 downwards (from line 8 to line 17 exactly). You can also keep one line as an example or copy-paste it and adapt it.
URI of the constraint
In cell A8, enter the URI of the constraint (This is actually the URI of a SHACL property shape) : this column uses the "this" prefix. /!\ Do not confuse it with the URI of the property itself. Usually this identifier is the concatenation of the entity URI and the ontology property URI, which in our case gives « this:Organization_member », as the “member” property will apply to Organizations in our case ;
URI of the property
In cell B8, enter the exact URI of the property from the ontology, here it’s « foaf:member ».
Domain entity
In cell C8, indicate the « domain » entity to which the property applies : « this:Organization » (the URI must be one of the entities in the Entities tab).
Display label
In cell E8, enter the display label in English, as it will appear in the UI interface, here « member ».
Tooltip
In cell G8, enter the tooltip in English, for example « Specifies the Agent member of this Group ».
This should give you a line similar to this one :
Node kind
In cell K8, enter “sh:IRI”, which indicates the proprety points to IRI resources (as opposed to blank nodes or literals).
Target entity/class
In cell M8, the range will be the target class of the property, here « foaf:Person ». Note how this is a reference to the class identifier, and not to the entity URI using the « this » prefix. It must correspond to one of the value of the “sh:targetClass” column from the “Entities” tab.
Search widget
In cell O8 enter « core:ListProperty » to display the values as a list of items. Other values are available to control how the user can search for values of this property.
For more information about the properties, jump to the the « How to configure Sparnatural » manual, chapter « Declaring properties »
Before Sparnatural can read the configuration, it needs to be converted to RDF. More details on this “xls2rdf” converter are given in the “how to configure” documentation, we will simply describe here the most simple way to do it:
Go to SKOS Play website, tab Convert : https://skos-play.sparna.fr/play/convert
Submit the Excel file in the “In a local file on my computer” field
Check the “Ignore SKOS post-processings on the data” box at the bottom of the form
Click on « Convert » button
Save the result in a new « myconfig.ttl » file in the hello-sparnatural folder
Note that, each time you modify the Excel configuration file, you need to convert it again.
Edit the index.html page, look for the “<spar-natural>” tag and set the “src” attribute to point to your configuration file name, like “myconfig.ttl”, and save the file:
<spar-natural
src="myconfig.ttl"
endpoint="https://localhost:7200/repositories/myRepo"
lang="en"
defaultLang="en"
distinct="true"
limit="1000"
debug="true"
></spar-natural>
Open a CORS-enabled browser to load the index.html file in it : you should see your 2 classes linked with your properties, populated by the data from your SPARQL endpoint:
If everything is OK, you should see a list of Person URIs (or another class from your knowledge graph) listed in the dropdown. You can try to build a query and verify that it works !
If it does not work:
check that the URIs you used in your configuration file for the 2 classes and the property do correspond to actual URI from your knowledge graph.
debug the SPARQL query by opening your web browser console (F12 key) and monitor the SPARQL query that is sent to populate the dropdown box.
Congratulations, you have successfully completed this “Hello Sparnatural” tutorial !
Read the configuration how-to
Sparnatural offers many nice features to explore your knowledge graph :
Autocomplete widgets, trees, maps, calendars and more.
Ability to map the configuration ontology to the underlying knowledge graph structure, if you want to display things with a different structure.
Ability to enable optional, negative or multilingual properties.
Ability to customize Sparnatural through a CSS theme file.
Ability to express aggregation queries (like COUNT)
All of these you can learn in the «How-to configure Sparnatural » document. The Sparnatural documentation website offers comprehensive documentation on all the features. The Github repository of Sparnatural is where you can ask questions, report bugs, and reach us.
Tune the HTML and upload the demo page online
You can further tune the content of the index.html webpage, and customize it anyway you like. Once done, you can simply upload the entire folder on a (your) web server so that it is publicly accessible !
To give the users a few examples of queries they could write in the interface, you can save sample queries to display in the HTML page.
Save the sample queries only after your Sparnatural configuration ontology is stable. Otherwise there is a risk that you will need to rewrite them.
Start creating a query via the in-place query builder and open your browser console at the same time. Here you can see that each time you add a new parameter to your query, a new « Sparnatural JSON query structure » message appears.
Once your query written, then find the last « Object » in the Sparnatural JSON query structures listed here :
then right click on it and select « Copy object ».
Edit the example-queries.js javascript file :
Select the value of “example_1” variable, from the first “{“ character to the last “}”, and Paste what you have copied from the console.
Repeat the same process to save a second query in the “example_2” variable.Add more variables if needed.
Save the file
Edit the index.html file and uncomment the example queries section around line 57 to 64, above the “<spar-natural>” tag:
<!-- uncomment to enable links to load sample queries
<p>
Load example queries :
<a href="#" onclick="document.querySelector('spar-natural').loadQuery(window['example_1']);return false;">example 1</a>
|
<a href="#" onclick="document.querySelector('spar-natural').loadQuery(window['example_2']);return false;">example 2</a>
</p>
-->
Adjust the title of the query accordingly (e.g. replace “example 1” with “My beautiful query”) :
Your query is saved and can be loaded in the query builder in one click !
[1] While using YasGUI is an obvious choice, YasGUI is not a requirement of Sparnatural. You can choose to present query results differently than in YasGUI, or you may not want to display the raw SPARQL query to the user.
[2] This plugin is part of another project at https://github.com/sparna-git/sparnatural-yasgui-plugins
[3] The browser console can be opened with the F12 key
[4] For more information we suggest to check https://enable-cors.org/, and the wikipedia page on Same Origin Policy at https://en.wikipedia.org/wiki/Same-origin_policy