Home > Javascript integration version 7

Javascript integration and parameters reference - version 7

/!\This documentation applies to version 7 of Sparnatural. See the version 8 integration documentation for versions 8 and above.

Constructor

  <div id="sparnatural-container"></div>

and then

 sparnatural = document.getElementById('sparnatural-container').Sparnatural({
   // reference to OWL or JSON configuration
   config: "sparnatural-config.ttl",
   language: "en",
   // other parameters... see below
 });

A typical integration in a web page looks like this :


      var sparnatural;
      $( document ).ready(function($) {          

        sparnatural = document.getElementById('sparnatural-container').Sparnatural({
          config: "sparnatural-config.ttl",
          language: "en",
          maxDepth: 4,                                                                        
          addDistinct: true,
          sendQueryOnFirstClassSelected: true,
          backgroundBaseColor: '29,224,153',
          autocomplete : null,
          list : null,
          defaultEndpoint : "http://dbpedia.org/sparql",
          onQueryUpdated: function(queryString, queryJson) {
            // ... here : query post-processing ...
            // then : integration with YASQE and YASR
            yasqe.setValue(queryString);
            yasqe.query();
          }
        });
      }) ;

Parameters reference

Setting / Description Default value if not set
config config/spec-search.json
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 an OWL Turtle or RDF/XML file, an inline Turtle String, a URL to a JSON file, or a JSON object. Example : sparnatural-config.ttl  
language en
Language code to use to display the labels of classes and properties from the configuration file.  
defaultEndpoint null
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, or the autocomplete and list parameters must be provided for low-level datasource integration.  
addDistinct false
Whether the DISTINCT keyword should be inserted to the generated SPARQL query.  
typePredicate rdf:type
The type predicate to use to generate the type criteria. Defaults to rdf:type, but could be changed to http://www.wikidata.org/prop/direct/P31 for Wikidata integration.  
sendQueryOnFirstClassSelected false
Whether to emit the query when the very first class is selected, before the complete first criteria is complete, to select all the instances of this class.  
maxDepth 3
Maximum depth of the constructed query (number of inner ‘Where’ clauses).  
maxOr 3
Maximum number of different values that can be selected for a given property criteria.  
backgroundBaseColor 250,136,3
The base color to use as the background. This color should be given in the format ‘R,G,B’. Transparency is applied to the base color to generate the color gradient.  
autocomplete  
A Javascript object providing the necessary functions for the autocomplete widget. If using SPARQL datasources to populate the widgets, this is optional. This provides a low-level hook to populate autocomplete fields. See the autocomplete reference below  
list  
A Javascript object providing the necessary functions for the list widget. If using SPARQL datasources to populate the widgets, this is optional. This provides a low-level hook to populate list fields. See the list reference below.  
dates  
A Javascript object providing the necessary functions for the date widget. See the dates reference below.  
onQueryUpdated  
A Javascript function(queryString, queryJson) { ... } taking as a parameter the SPARQL query String and the SPARQL query JSON data structure. See the onQueryUpdated reference below  
onSubmit  
A Javascript function(form) { ... } that is triggered when the submit button inside Sparnatural is clicked. This function is optional, if not provided, no submit button is displayed. See the See the onSubmit reference below  
tooltipConfig  
The tooltip configuration object. Possible configuration options are described in Tippy documentation here. Defaults to : <pre>{
allowHTML: true,
plugins: [],
placement: ‘right-start’,
offset: [5, 5],
theme: ‘sparnatural’,
arrow: false,
delay: [800, 100],
duration: [200, 200]
}</pre>		  
sparqlPrefixes /!\ unstable {}
A set of prefixes in the form "foaf" : "http://xmlns.com/foaf/0.1/" to be added to the output SPARQL query. This is an unstable param, current use is discouraged.  
localCacheDataTtl /!\ beta feature 1000 * 60 * 60 * 24
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 Cache-Control: no-cache header is returned in the response, no cache will happen, whatever the value of this field. The server can return Cache-Control: public for lists to be properly cached.  
filterConfigOnEndpoint /!\ beta feature false
If set to true, Sparnatural will issue on initialisation a serie of queries to the SPARQL endpoint to determine if each class and properties in the provided configuration is actually implemented in the graph. Classes or properties with no instances will be hidden from the lists displayed to the user.  

autocomplete reference

The autocomplete object must provide the functions documented below. The autocomplete feature relies on Easyautocomplete so interested readers are invited to refer to Easyautocomplete documentation for more information.

autocomplete : {
	/**
	 * This must return the URL that will be called when the user starts
	 * typing a few letter in a search field.
	 *
	 * @param {string} domain - The domain of the criteria currently being edited, i.e. type of the triple subjects.
	 * @param {string} property - The predicate of the criteria currently being edited
	 * @param {string} range - The range of the criteria currently being edited, i.e. type of the triple objects. This is the class of the entities being searched for.
	 * @param {string} key - The letters that the user has typed in the search field.
	 **/
	autocompleteUrl : function(domain, property, range, key) {
		console.log("Please specify function for autocompleteUrl option in in init parameters of Sparnatural : function(domain, property, range, key)") ;
	},

	/**
   	 * Returns the path in the returned JSON structure where the list of entries should be read.
   	 * This is typically the data structure itself, but can correspond to a subentry inside.
   	 *
	 * @param {string} domain - The domain of the criteria currently being edited
	 * @param {string} property - The predicate of the criteria currently being edited
	 * @param {string} range - The range of the criteria currently being edited
	 * @param {object} data - The data structure returned from an autocomplete call
   	 **/
	listLocation: function(domain, property, range, data) {
		return data;
	},

	/**
   	 * Returns the label to display for a single autocomplete result; defaults to `element.label`.
   	 *
   	 * @param {object} element - A single autocomplete result
   	 **/
	elementLabel: function(element) {
		return element.label;
	},

	/**
	 * Returns the URI to of a single autocomplete result; ; defaults to `element.uri`.
	 *
	 * @param {object} element - A single autocomplete result
	 **/
	elementUri: function(element) {
		return element.uri;
	},

	/**
	 * Whether the Easyautocomplete 'enableMatch' flag should be set; this should
	 * be useful only when loading the autocomplete results from a local file, leave to
	 * false otherwise.
	 **/
	enableMatch: function(domain, property, range) {
		return false;
	},
}

list reference

The list object must provide the functions documented below to populate select dropdowns.

list : {

	/**
	 * This must return the URL that will be called to list the values to populate the dropdown.
	 *
	 * @param {string} domain - The domain of the criteria currently being edited, i.e. type of the triple subjects.
	 * @param {string} property - The predicate of the criteria currently being edited
	 * @param {string} range - The range of the criteria currently being edited, i.e. type of the triple objects. This is the class of the entities being searched for.
	 **/
	listUrl : function(domain, property, range) {
		console.log("Please specify function for listUrl option in in init parameters of Sparnatural : function(domain, property, range)" ) ;
	},

	/**
   	 * Returns the path in the returned JSON structure where the list of entries should be read.
   	 * This is typically the data structure itself, but can correspond to a subentry inside.
   	 *
	 * @param {string} domain - The domain of the criteria currently being edited
	 * @param {string} property - The predicate of the criteria currently being edited
	 * @param {string} range - The range of the criteria currently being edited
	 * @param {object} data - The data structure returned from a list call
   	 **/
	listLocation: function(domain, property, range, data) {
		return data;
	},

	/**
   	 * Returns the label to display for a single list entry; defaults to `element.label`.
   	 *
   	 * @param {object} element - A single list entry
   	 **/
	elementLabel: function(element) {
		return element.label;
	},

	/**
   	 * Returns the URI for a single list entry; defaults to `element.uri`.
   	 *
   	 * @param {object} element - A single list entry
   	 **/
	elementUri: function(element) {
		return element.uri;
	}

dates reference

dates : {
	datesUrl : function(domain, property, range, key) {
		console.log("Please specify function for datesUrl option in in init parameters of Sparnatural : function(domain, property, range, key)") ;
	},
	listLocation: function(domain, property, range, data) {
		return data;
	},
	elementLabel: function(element) {
		return element.label+' '+element.synonyms.join(' ');
	},
	elementStart: function(element) {
		return element.start.year;
	},
	elementEnd: function(element) {
		return element.stop.year;
	}				
}

onQueryUpdated reference

The onQueryUpdated function is called everytime the query is modified :

/**
 * Callback notified each time the query is modified.
 *
 * @param {object} queryString - The SPARQL query string
 * @param {object} queryJson - The query as a JSON data structure
 **/
onQueryUpdated : function (queryString, queryJson) {
	console.log(queryString) ;
}

onSubmit reference

The onSubmit function is called when the submit button is clicked. Sparnatural listens for other events to update the state of the button (loading/not loading state and active/disabled state). The functions are:

  • enableLoading()
  • disableLoading()

enableLoading() should be called inside the onSubmit() method and disableLoading() when the query has returned. In a typical integration with YasGUI this looks like this:

      var sparnatural;
      $( document ).ready(function($) {          

        sparnatural = document.getElementById('sparnatural-container').Sparnatural({
          // ...
          onQueryUpdated: function(queryString, queryJson) {
            // store the query in yasqe
            yasqe.setValue(queryString);
          },
          // triggered when "play" button is clicked
          onSubmit: function(form) {
            // enable loader on button
            form.sparnatural.enableLoading() ; 
            // 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);
        // disable load on Sparnatural
        sparnatural.disableLoading() ;
      });