CINXE.COM

<!DOCTYPE html> <html lang="en-US"> <head> <meta charset="UTF-8">  <title>Sparnatural | Sparnatural : visual knowledge graph explorer with SPARQL, in the browser, configurable with SHACL</title> <meta name="generator" content="Jekyll v3.10.0" /> <meta property="og:title" content="Sparnatural" /> <meta property="og:locale" content="en_US" /> <meta name="description" content="Sparnatural : visual knowledge graph explorer with SPARQL, in the browser, configurable with SHACL" /> <meta property="og:description" content="Sparnatural : visual knowledge graph explorer with SPARQL, in the browser, configurable with SHACL" /> <link rel="canonical" href="http://docs.sparnatural.eu/Javascript-integration.html" /> <meta property="og:url" content="http://docs.sparnatural.eu/Javascript-integration.html" /> <meta property="og:site_name" content="Sparnatural" /> <meta property="og:type" content="website" /> <meta name="twitter:card" content="summary" /> <meta property="twitter:title" content="Sparnatural" /> <script type="application/ld+json"> {"@context":"https://schema.org","@type":"WebPage","description":"Sparnatural : visual knowledge graph explorer with SPARQL, in the browser, configurable with SHACL","headline":"Sparnatural","url":"http://docs.sparnatural.eu/Javascript-integration.html"}</script>  <link rel="preconnect" href="https://fonts.gstatic.com"> <link rel="preload" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700&display=swap" as="style" type="text/css" crossorigin> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="theme-color" content="#157878"> <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,500,700|Open+Sans:300,300i,400,400i,700,700i" rel="stylesheet">  <link href="/assets/vendor/bootstrap/css/bootstrap.min.css" rel="stylesheet"> <link href="/assets/vendor/bootstrap-icons/bootstrap-icons.css" rel="stylesheet">  <link rel="stylesheet" href="/assets/fa/css/all.min.css" /> <link rel="stylesheet" href="/assets/css/style.css?v=0749f99a06ebf397cbf5d4fa03801e49f2b0f124"> <style> #documentation-section { padding-top: 115px; height: auto; overflow: visible; } .anchorjs-link { transition: all .25s linear; } *:hover > .anchorjs-link { margin-left: -1.125em !important; } </style> </head> <body>   <header id="header" class="fixed-top d-flex align-items-center"> <div class="container d-flex justify-content-between align-items-center"> <div id="logo"> <h1><a href="#">Sparnatural documentation</a></h1> </div> <nav id="navbar" class="navbar"> <ul> <li class="dropdown"><a href="#"> Lang. </a> <ul style="width:80%;"> <li><a href="/fr">fr</a></li> <li><a href="/">en</a></li> </ul> </li> <li><a class="nav-link" href="https://github.com/sparna-git/Sparnatural">  Github</a></li> </ul> </nav> </div> </header> <main id="content" class="main-content" role="main">  <section id="documentation-section"> <div class="container"> <a href="index.html">Home</a> > Javascript integration <h1 id="javascript-integration-and-parameters-reference">Javascript integration and parameters reference</h1> <h2 id="constructor">Constructor</h2> Sparnatural is inserted as custom HTML element named <code class="language-plaintext highlighter-rouge">spar-natural</code> (note the dash), with specific attributes. It looks like so: <div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <spar-natural src="sparnatural-config.ttl" endpoint="https://dbpedia.org/sparql" lang="en" defaultLang="en" limit="1000" debug="true" /> </code></pre></div></div> <h2 id="html-attributes-reference">HTML attributes reference</h2> <table> <thead> <tr> <th>Attribute</th> <th>Description</th> <th>Default</th> <th>Mandatory/Optional</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">src</code></td> <td>Provides the configuration that specifies the classes and properties to be displayed, and how they are mapped to SPARQL. This can be either the URL of a SHACL or OWL file, in Turtle or RDF/XML. Example : <code class="language-plaintext highlighter-rouge">sparnatural-config.ttl</code>. Another option is to provide a serialized JSON obj as a string. For example: <code class="language-plaintext highlighter-rouge">JSON.stringify(configAsJsonObj)</code>. It is possible to pass multiple URLs be separating them with a whitespace, e.g. <code class="language-plaintext highlighter-rouge">sparnatural-config.ttl statistics.ttl</code></td> <td><code class="language-plaintext highlighter-rouge">undefined</code></td> <td>Mandatory</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">endpoint</code></td> <td>The URL of a SPARQL endpoint that will be used as the default service for the datasource queries provided in the configuration. If not specified, each datasource should indicate explicitely a SPARQL endpoint. Note that this URL can use the <code class="language-plaintext highlighter-rouge">default-graph-uri</code> parameter to restrict the query to a specified named graph, as per <a href="https://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/#dataset">SPARQL protocol specification</a>, e.g. <code class="language-plaintext highlighter-rouge">http://ex.com/sparql?default-graph-uri=http%3A%2F%2Fencoded-named-graph-uri</code>. This can also contain multiple endpoint URLs in combination with the <code class="language-plaintext highlighter-rouge">catalog</code> attribute (see “<a href="/Querying-multiple-endpoints.html">querying multiple endpoints</a>”)</td> <td><code class="language-plaintext highlighter-rouge">undefined</code></td> <td>Mandatory except for advanced use-cases.</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">catalog</code> (unstable)</td> <td>The catalog of endpoints, if you pass multiple endpoints. This is advanced configuration. (see “<a href="/Querying-multiple-endpoints.html">querying multiple endpoints</a>”)</td> <td>none</td> <td>Optional</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">defaultLang</code></td> <td>Dataset default language. A language in which the dataset always provides labels/titles that can be used as default if a label in the user language is not present.</td> <td><code class="language-plaintext highlighter-rouge">en</code></td> <td>Recommended</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">debug</code></td> <td>If set to <code class="language-plaintext highlighter-rouge">true</code>, Sparnatural will log JSON and SPARQL queries on the console, as they are generated.</td> <td><code class="language-plaintext highlighter-rouge">false</code></td> <td>Optional</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">distinct</code></td> <td>Whether the <code class="language-plaintext highlighter-rouge">DISTINCT</code> keyword should be inserted to the generated SPARQL query.</td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td>Optional</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">lang</code></td> <td>User language preference. The language code to use to display labels of classes and properties from the configuration file, and to query for values in lists and search fields.</td> <td><code class="language-plaintext highlighter-rouge">en</code></td> <td>Recommended</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">limit</code></td> <td>A number that will be used to add a <code class="language-plaintext highlighter-rouge">LIMIT</code> keyword in the generated SPARQL queries. If set to an empty string or a negative number, no <code class="language-plaintext highlighter-rouge">LIMIT</code> keyword is inserted.</td> <td><code class="language-plaintext highlighter-rouge">-1</code></td> <td>Optional</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">maxDepth</code></td> <td>Maximum depth of the constructed query (number of inner ‘Where’ clauses).</td> <td><code class="language-plaintext highlighter-rouge">4</code></td> <td>Optional</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">localCacheDataTtl</code> (beta)</td> <td>The time that the dropdown lists will be stored in cache on the client, if the server has allowed it in its response headers, that is if <code class="language-plaintext highlighter-rouge">Cache-Control: no-cache</code> header is returned in the response, no cache will happen, whatever the value of this field. The server can return <code class="language-plaintext highlighter-rouge">Cache-Control: public</code> for lists to be properly cached.</td> <td><code class="language-plaintext highlighter-rouge">1000 * 60 * 60 * 24</code></td> <td>Optional</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">maxOr</code></td> <td>Maximum number of different values that can be selected for a given property criteria. For example how many country can be chosen on the list widget</td> <td><code class="language-plaintext highlighter-rouge">3</code></td> <td>Optional</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">prefixes</code> (unstable)</td> <td>A set of prefixes in the form <code class="language-plaintext highlighter-rouge">foaf: http://xmlns.com/foaf/0.1/ skos:http://www.w3.org/2004/02/skos/core#</code> to be added to the output SPARQL query. This is applied in the <code class="language-plaintext highlighter-rouge">expand</code> method.</td> <td><code class="language-plaintext highlighter-rouge">none</code></td> <td> </td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">queryLang</code></td> <td>The language used as a parameters to datasources, to e.g. populate dropdown lists with labels of this language.</td> <td>same value as <code class="language-plaintext highlighter-rouge">lang</code></td> <td>Recommended</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">submitButton</code></td> <td>Whether Sparnatural should display a submit button to allow the user to execute the query. A click on the submit button will trigger a <code class="language-plaintext highlighter-rouge">submit</code> event. In case it is not provided, it is the page responsibility to either execute the query automatically at each update in the <code class="language-plaintext highlighter-rouge">queryUpdated</code> event or provide its own way to submit the query.</td> <td><code class="language-plaintext highlighter-rouge">true</code></td> <td>Optional</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">typePredicate</code></td> <td>The type predicate to use to generate the type criteria. Defaults to rdf:type, but could be changed to e.g. <code class="language-plaintext highlighter-rouge"><http://www.wikidata.org/prop/direct/P31>+</code> for Wikidata integration, or <code class="language-plaintext highlighter-rouge"><http://www.w3.org/2000/01/rdf-schema#subClassOf>+</code> to query OWL-style models.</td> <td><code class="language-plaintext highlighter-rouge">rdf:type</code></td> <td>Optional</td> </tr> </tbody> </table> <h2 id="sparnatural-events">Sparnatural events</h2> Then the HTML page needs to listen to specific events triggered by Sparnatural, notably <code class="language-plaintext highlighter-rouge">queryUpdated</code> and <code class="language-plaintext highlighter-rouge">submit</code> : <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>const sparnatural = document.querySelector("spar-natural"); // triggered as soon there is a modification in the query sparnatural.addEventListener("queryUpdated", (event) => { // do something with the query }); // triggered when submit button is called sparnatural.addEventListener("submit", (event) => { // so something }); // triggered when reset button is clicked sparnatural.addEventListener("reset", (event) => { // do something }); </code></pre></div></div> See below for the complete reference of the available events. A typical integration in a web page looks like this : <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>const sparnatural = document.querySelector("spar-natural"); sparnatural.addEventListener("queryUpdated", (event) => { // expand query to replace identifiers with content of sparqlScript annotation console.log(event.detail.queryString); console.log(event.detail.queryJson); console.log(event.detail.querySparqlJs); queryString = sparnatural.expandSparql(event.detail.queryString); // set query on YasQE yasqe.setValue(queryString); // save JSON query document.getElementById('query-json').value = JSON.stringify(event.detail.queryJson); }); sparnatural.addEventListener("submit", (event) => { // enable loader on button sparnatural.disablePlayBtn() ; // trigger the query from YasQE yasqe.query(); }); sparnatural.addEventListener("reset", (event) => { yasqe.setValue(""); }); </code></pre></div></div> <h3 id="queryupdated-event">“queryUpdated” event</h3> The <code class="language-plaintext highlighter-rouge">queryUpdated</code> event is triggered everytime the query is modified. The event detail contains : <ul> <li>The SPARQL string in <code class="language-plaintext highlighter-rouge">queryString</code></li> <li>The JSON Sparnatural structure in <code class="language-plaintext highlighter-rouge">queryJson</code></li> <li>The (SPARQL.js format)[https://github.com/RubenVerborgh/SPARQL.js/] structure in <code class="language-plaintext highlighter-rouge">querySparqlJs</code></li> </ul> <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sparnatural.addEventListener("queryUpdated", (event) => { console.log(event.detail.queryString); console.log(event.detail.queryJson); console.log(event.detail.querySparqlJs); }); </code></pre></div></div> <h3 id="submit-event">“submit” event</h3> The <code class="language-plaintext highlighter-rouge">submit</code> event is triggered when the submit button is clicked. In typical integrations, the state of the submit button can be updated upon submit. The submit button can be “not loading and active”, “loading” or “disabled”. The functions to update the state of the button are: <ul> <li><code class="language-plaintext highlighter-rouge">sparnatural.disablePlayBtn()</code></li> <li><code class="language-plaintext highlighter-rouge">sparnatural.enablePlayBtn()</code></li> </ul> <code class="language-plaintext highlighter-rouge">disablePlayBtn()</code> should be called on <code class="language-plaintext highlighter-rouge">submit</code> event and <code class="language-plaintext highlighter-rouge">enablePlayBtn()</code> when the query has returned. In a typical integration with YasGUI this looks like this: <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>const sparnatural = document.querySelector("spar-natural"); sparnatural.addEventListener("queryUpdated", (event) => { queryString = sparnatural.expandSparql(event.detail.queryString); yasqe.setValue(queryString); }); sparnatural.addEventListener("submit", (event) => { // disable the button and show a spinning loader sparnatural.disablePlayBtn() ; // trigger the query from YasQE yasqe.query(); }); const yasqe = new Yasqe(document.getElementById("yasqe")); const yasr = new Yasr(document.getElementById("yasr")); yasqe.on("queryResponse", function(_yasqe, response, duration) { // print the responses in YASR yasr.setResponse(response, duration); // re-enable play button in Sparnatural sparnatural.enablePlayBtn() ; }); </code></pre></div></div> <h3 id="reset-event">“reset” event</h3> The <code class="language-plaintext highlighter-rouge">submit</code> event is triggered when the reset button is clicked. It can be used to empty or reset other part of the page, typically YasQE. A typical integration is the following: <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sparnatural.addEventListener("reset", (event) => { yasqe.setValue(""); }); </code></pre></div></div> <h3 id="init-event">“init” event</h3> The <code class="language-plaintext highlighter-rouge">init</code> event is triggered when Sparnatural has finished reading its configuration. Listen to this event to pass additionnal JSON customization with <code class="language-plaintext highlighter-rouge">sparnatural.customization = { ... }</code> (see below). <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sparnatural.addEventListener("init", (event) => { console.log("Sparnatural is initialized"); // sparnatural.customization = { ... } }); </code></pre></div></div> <h2 id="sparnatural-element-api">Sparnatural element API</h2> The table below summarizes the various functions that can be called on the Sparnatural element. <table> <thead> <tr> <th>Function</th> <th>Description</th> <th>Parameters</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">sparnatural.enablePlayBtn()</code></td> <td>Removes the loading from the play button once a query has finished executing.</td> <td>none</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">sparnatural.disablePlayBtn()</code></td> <td>Disables the play button once a query has started its execution.</td> <td>none</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">sparnatural.loadQuery(query)</code></td> <td>Loads a query structure in Sparnatural.</td> <td>Query structure as documented in <a href="Query-JSON-format">the query JSON format</a></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">sparnatural.expandSparql(sparqlString)</code></td> <td>Expands a SPARQL query string according to the configuration, in particular the <code class="language-plaintext highlighter-rouge">sparqlString</code> annotations, as documented in the <a href="OWL-based-configuration">OWL-based configuration</a> A SPARQL query string</td> <td>string</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">sparnatural.clear()</code></td> <td>Clears the Sparnatural editor, as if the reset button was clicked.</td> <td>none</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">sparnatural.executeSparql(query:string, callback: (data: any) => void, errorCallback?:(error: any) => void)</code></td> <td>Executes the provided SPARQL query, using configured endpoint or multiple endpoints from the catalog, and using the configured headers.</td> <td>1/ The SPARQL query string 2/ the callback when execution succeeds 3/ the callback on error</td> </tr> </tbody> </table> <h2 id="sparnatural-bindings">Sparnatural bindings</h2> Starting from 9.1, releases of Sparnatural include a <a href="https://github.com/sparna-git/Sparnatural/blob/master/src/sparnatural-bindings.js"><code class="language-plaintext highlighter-rouge">sparnatural-bindings.js</code></a> Javascript file that can be used to facilitate the integration of the events and functions of Sparnatural in typical integration scenarios. In particular for a scenario when Sparnatural is integrated with YasQE as a read-only query viewer and YasR, and where Sparnatural is responsible for executing the query, you can call the following functions: <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>// binds Sparnatural with the YasR plugins bindSparnaturalWithYasrPlugins(sparnatural, yasr); // binds Sparnatural with itself for the query execution and integration with yasqe and yasr bindSparnaturalWithItself(sparnatural, yasqe, yasr); </code></pre></div></div> <h2 id="sparnatural-behavior-customization">Sparnatural behavior customization</h2> The behavior of Sparnatural can be further adjusted with the <code class="language-plaintext highlighter-rouge">customization</code> object : <code class="language-plaintext highlighter-rouge">sparnatural.customization = { ... }</code>. That call must be done within the <code class="language-plaintext highlighter-rouge">init</code> event listener, after Sparnatural has finished reading its initial specification file. <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sparnatural.addEventListener("init", (event) => { console.log("Sparnatural is initialized"); sparnatural.customization = { ... } }); </code></pre></div></div> In particular this object allows to pass in functions to provide data to the different widgets. See the reference documentation below. <h3 id="sparnatural-customization-object-reference">Sparnatural customization object reference</h3> The customization object structure is outlined below. All items are optionnal. <div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ autocomplete: { dataProvider : { getAutocompleteSuggestions: function( domain:string, predicate:string, range:string, key:string, lang:string, defaultLang:string, typePredicate:string, callback:(items:{term:RDFTerm;label:string;group?:string}[]) => void, errorCallback?:(payload:any) => void ) }, // the maximum number of items to be proposed in the autocomplion list maxItems: number }, list: { dataProvider : { getListContent: function( domain:string, predicate:string, range:string, lang:string, defaultLang:string, typePredicate:string, callback:(values:{literal:string}[]) => void ):void } }, tree: { dataProvider : { getRoots: function( domain:string, predicate:string, range:string, lang:string, defaultLang:string, typePredicate:string, callback:(items:{term:RDFTerm;label:string;hasChildren:boolean;disabled:boolean}[]) => void, errorCallback?:(payload:any) => void ):void, getChildren: function( node:string, domain:string, predicate:string, range:string, lang:string, defaultLang:string, typePredicate:string, callback:(items:{term:RDFTerm;label:string;hasChildren:boolean;disabled:boolean}[]) => void, errorCallback?:(payload:any) => void ):void } }, map: { // initial zoom level of the map, when opened // see https://leafletjs.com/reference.html#map-setview // typically, from 0 to ~ 12 zoom : number, // initial center of the map, when opened // see https://leafletjs.com/reference.html#map-setview center : { lat:number, long:number } }, headers: { "header name": "value" }, sparqlHandler: { executeSparql( sparql:string, callback: (data: any) => void, errorCallback?:(error: any) => void ):void; } } </code></pre></div></div> Note that the <code class="language-plaintext highlighter-rouge">RDFTerm</code> data structure referenced above is the following: <div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>export class RDFTerm { type: string; value: string; "xml:lang"?: string; datatype?:string } </code></pre></div></div> <h3 id="example-of-custom-data-provider-function">Example of custom data provider function</h3> <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sparnatural.addEventListener("init", (event) => { sparnatural.customization = { autocomplete: { dataProvider: { getAutocompleteSuggestions: function( domain, predicate, range, key, lang, defaultLang, typePredicate, callback, errorCallback ) { // build the list of autocomplete items to show console.log("domain,predicate,range : "+domain+" "+predicate+" "+range); let items = [ { term: { type:"IRI", value:"http://exemple.fr/1" }, label: key+" : suggestion 1" }, { term: { type:"IRI", value:"http://exemple.fr/2" }, label: key+" : suggestion 2" } ]; // call the callback function with the list of items callback(items); } } } }; }); </code></pre></div></div> <h3 id="http-headers-configuration">HTTP headers configuration</h3> To set the headers of requests made by Sparnatural, use the customization objet above, with the <code class="language-plaintext highlighter-rouge">headers</code> key. See this example: <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sparnatural.addEventListener("init", (event) => { sparnatural.customization = { headers: { "User-Agent" : "This is Sparnatural calling" } } }); </code></pre></div></div> <h3 id="example-of-custom-sparql-handler">Example of custom SPARQL handler</h3> <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sparnatural.addEventListener("init", (event) => { sparnatural.customization = { sparqlHandler: { executeSparql( sparql:string, callback: (data: {}) => void, errorCallback?:(error: any) => void ):void { console.log("Received SPARQL "+sparql); // ... execute SPARQL ... // fire callback with SPARQL results callback({}); } } } }); </code></pre></div></div> </div> </section> </main> <script src="https://code.jquery.com/jquery-3.3.1.min.js" crossorigin="anonymous"></script> <script src="https://cdn.jsdelivr.net/npm/anchor-js/anchor.min.js"></script> <script> anchors.options.placement = 'left'; anchors.add(); </script> <script> $( document ).ready(function($) { // add bootstrap table class on all tables $('table').addClass("table"); }) ; </script> </body> </html>