fisrt commit

.hgignore

+dist
+node_modules

LICENSE

+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

README.md

+# Sparnatural - A natural way of building SPARQL queries
+
+Sparnatural is a **visual SPARQL query builder written in javascript**.
+
+It supports the creation of basic graph patterns with the selection of values with autocomplete search or dropdown lists. It can be configured through a JSON-LD ontology file that defines the classes and properties to be presented in the component.
+
+![](documentation/screencast-sparnatural-dbpedia-v3-en.gif)
+
+You can play with an **online demo at http://labs.sparna.fr/sparnatural-demo-dbpedia/**.
+
+# Getting Started
+
+To get started :
+
+1. Read the following documentation;
+2. Look at how things work in file `sparnatural-demo-dbpedia/index.html`; 
+3. In particular look at how the specifications are written by looking at [the source of `sparnatural-demo-dbpedia/index.html`](https://github.com/sparna-git/Sparnatural/blob/master/sparnatural-demo-dbpedia/index.html#L100)
+4. Adapt `sparnatural-demo-dbpedia/index.html` by changing the configuration and adapting the SPARQL endpoint URL;
+
+# Features
+
+## Query Structure
+
+### Basic query pattern
+
+Select the type of entity to search...
+
+![](documentation/1-screenshot-class-selection.png)
+
+... then select the type of the related entity.
+
+![](documentation/2-screenshot-object-type-selection.png)
+
+In this case there is only one possible type of relation that can connect the 2 entities, so it gets selected automatically. Then select a value for the related entity, in this case in a dropdown list :
+
+![](documentation/3-screenshot-value-selection.png)
+
+Congratulations, your first SPARQL query criteria is complete !
+
+![](documentation/4-screenshot-criteria.png)
+
+Now you can fetch the generated SPARQL query :
+
+![](documentation/5-screenshot-sparql.png)
+
+### "WHERE"
+
+This enables to navigate the graph :
+
+![](documentation/6-where.png)
+
+### "AND"
+
+Combine criterias :
+
+![](documentation/7-and.png)
+
+### "OR"
+
+Select multiple values for a criteria :
+
+![](documentation/8-or.png)
+
+## Values selection
+
+Sparnatural offers currently 6 ways of selecting a value for a criteria : autocomplete field, dropdown list, simple string value, date range (year or date precision), date range with a search in a period name (e.g. "bronze age"), or no selection at all.
+
+### Autocomplete field
+
+![](documentation/9-autocomplete.png)
+
+### Dropdown list
+
+![](documentation/10-list.png)
+
+### String value (text search)
+
+![](documentation/11-search.png)
+
+### Date range (year or date precision)
+
+![](documentation/12-time-date.png)
+
+### Date range with search in period name
+
+### No value selection
+
+This is useful when a type a of entity is used only to navigate the graph, but without the ability to select an instance of these entities.
+
+![](documentation/13-no-value.png)
+
+
+
+
+## Multilingual
+
+Sparnatural is multilingual and supports displaying labels of classes and properties in multiple languages.
+
+
+## Limitations
+
+### Only basic graph patterns, no UNION, OPTIONAL, BIND, etc.
+
+Sparnatural produces only basic graph patterns with VALUES. It does not support the creation of UNION, OPTIONAL, SERVICE, BIND, etc...
+
+### SPARQL endpoint needs to be CORS-enabled
+
+To send SPARQL queries to a service that is not hosted on the same domain name as the web page in which Sparnatural is included, the SPARQL endpoint needs to allow [Cross-Origin Resource Sharing (CORS)](https://enable-cors.org/).
+
+# Integration
+
+## Specification of classes and properties
+
+The component is configurable using a JSON(-LD) ontology file. Look at the specification files under the `config` folders of the demos to get an idea. The file contains :
+
+### Class definition
+
+```json
+    {
+      "@id" : "http://dbpedia.org/ontology/Museum",
+      "@type" : "Class",
+      "label": [
+        {"@value" : "Museum", "@language" : "en"},
+        {"@value" : "Musée","@language" : "fr"}
+      ],
+      "faIcon":  "fas fa-university"
+    },
+```
+
+### Property definitions with domains and ranges
+
+```json
+    {
+      "@id" : "http://dbpedia.org/ontology/museum",
+      "@type" : "ObjectProperty",
+      "subPropertyOf" : "sparnatural:AutocompleteProperty",
+      "label": [
+        {"@value" : "displayed at","@language" : "en"},
+        {"@value" : "exposée à","@language" : "fr"}
+      ],
+      "domain": "http://dbpedia.org/ontology/Artwork",
+      "range": "http://dbpedia.org/ontology/Museum",
+      "datasource" : "datasources:search_rdfslabel_bifcontains"
+    },
+```
+
+### Using font-awesome icons
+
+It is possible to directly use font-awesome icons in place of icons embedded in your application :
+
+```json
+"faIcon":  "fas fa-user",
+```
+
+## How to integrate Sparnatural in a webpage
+
+Have a look at `index.html` in the demos folder to see how the component is integrated in a webpage.
+
+
+## Map the query structure to a different graph structure
+
+Map classes or properties in the config to a corresponding SPARQL property path or a corresponding class URI, using the `sparqlString` JSON key, e.g. :
+
+```
+    {
+      "@id" : "http://labs.sparna.fr/sparnatural-demo-dbpedia/onto#bornIn",
+      "@type" : "ObjectProperty",
+      ...
+      "sparqlString": "<http://dbpedia.org/ontology/birthPlace>/<http://dbpedia.org/ontology/country>",
+    },
+```
+
+Then call `expandSparql` on the `sparnatural` instance by passing the original SPARQL query, to replace all mentions of original classes and properties URI with the corresponding SPARQL string :
+
+```
+queryString = sparnatural.expandSparql(queryString);
+```

demos/sparnatural-demo-an/timeline.css

+    .vis-timeline {
+      background: #fafcff;
+    }
+
+    .vis-item {
+      box-shadow: 5px 5px 20px rgba(128,128,128, 0.5);
+    }
+
+    .vis-item,
+    .vis-item.vis-line {
+    	background-color:#fff;
+    	border-color:#868da4;
+    	color:#222;
+    }
+    
+    .vis-item a {
+    	color:#222;
+    }
+
+    .vis-item.vis-dot {
+    }
+
+    .vis-item.vis-selected {
+		background-color:#fffef1;
+    }
+
+    .vis-time-axis .vis-text {
+      padding-top: 10px;
+      padding-left: 5px;
+    }
+
+    .vis-time-axis .vis-text.vis-major {
+      font-weight: bold;
+    }
+
+    .vis-time-axis .vis-grid.vis-minor {
+    }
+
+    .vis-time-axis .vis-grid.vis-major {
+
+    }
\ No newline at end of file

demos/sparnatural-demo-an/timeline.js

+
+var timelinePlugin = function(yasr) {
+  var plugin = {};
+  //var options = $.extend(true, {}, timelinePlugin.defaults);
+  var cm = null;
+  
+  var draw = function() {
+     var container = $("<div id='timeResult' style='margin-top:1em;'></div>");
+     container.empty().appendTo(yasr.resultsContainer);
+     var element = document.getElementById('timeResult');
+     var itemsList=[];  
+
+     var bindings = yasr.results.getBindings();
+     if (!bindings || bindings.length === 0) {
+    	 return [];
+     }
+    
+     for (var i = 0; i < bindings.length; i++) {
+      
+          var binding 	= bindings[i];
+          var label		= null;
+          var stringFirstDate = null;
+          var stringSecondDate= null;
+          var uri=null; 
+          
+          for (var bindingVar in binding) {
+                //check if value is a xsd date
+                if(hasDateDatatype(binding[bindingVar]) || hasGYearDatatype(binding[bindingVar])) {                
+                    if(stringFirstDate == null) {
+                    	stringFirstDate = binding[bindingVar].value;
+                    } else {
+                    	stringSecondDate = binding[bindingVar].value;
+                    }
+              } else if (binding[bindingVar].type == 'literal') {
+                  label = binding[bindingVar].value;
+              } else if(binding[bindingVar].type == 'uri') {
+            	  uri=binding[bindingVar].value;
+              }   
+          }
+          
+          // parse the dates
+          var start =	(stringFirstDate !== null)?parseDate(stringFirstDate):null;
+          var end   =	(stringSecondDate !== null)?parseDate(stringSecondDate):null;
+          
+          // generate a default label if null
+          if(label == null) {
+        	  label = stringFirstDate+' / '+stringSecondDate;
+          }
+          
+          // if we have start and end date
+          if(stringFirstDate != null && stringSecondDate != null){
+                if(start.getTime() < end.getTime()){
+                  itemsList.push({
+                    id: 		i+1,
+                    content: 	'<a href="'+uri+'" target="_blank" style="text-decoration:none; cursor:pointer;" title="'+uri+'">'+label+'</a>', 
+                    start: 		start, 
+                    end: 		end, 
+                    title: 		label + ' ('+ stringFirstDate+' / '+stringSecondDate+ ')'
+                  });
+                } else {
+                  itemsList.push({
+                    id: 		i+1, 
+                    content: 	'<a href="'+uri+'" style="text-decoration:none; cursor:pointer;" target="_blank" title="'+uri+'">'+label+'</a>', 
+                    start: 		end, 
+                    end: 		start, 
+                    title:		label + ' (' + stringSecondDate+' / '+stringFirstDate + ')'
+                  });
+                }
+          }
+
+          // if we have only one date
+          if(stringFirstDate != null && stringSecondDate == null){  
+            itemsList.push({
+              id: 		i+1, 
+              content: 	'<a href="'+uri+'" style="text-decoration:none; cursor:pointer;" target="_blank" title="'+uri+'">'+label+'</a>', 
+              start: 	start,
+              title: 	label + ' (' + stringFirstDate + ')'
+            });
+          }
+      
+    }
+
+    var items = new vis.DataSet(itemsList);
+
+    var options = {
+    		limitSize : false,
+    		showTooltips: true,
+    		tooltip: {
+		      followMouse: true,
+		      overflowMethod: 'cap'
+		    }
+    };
+
+
+
+    // Create a Timeline
+    var timeline = new vis.Timeline(element, items, options);
+
+  };
+  
+  var parseDate = function(value) {
+	var dateParts = value.match(/(-?\d\d?\d?\d?)-(\d\d?)-(\d\d?)/);
+	
+	if(dateParts == null) {
+		dateParts = value.match(/(-?\d\d?\d?\d?)/);
+		dateParts[2] = "01";
+		dateParts[3] = "01";
+	}
+	
+  	dateParts[2] -= 1; //months are zero-based
+  	// use 3 variables constructor for proper handling of negative dates
+  	// see https://stackoverflow.com/questions/41340836/why-does-date-accept-negative-values
+  	return new Date(dateParts[1], dateParts[2], dateParts[3]);
+  }
+
+  var canHandleResults = function() {
+	var dateVars = getDateVariables();
+	return dateVars.length == 1 || dateVars.length == 2;
+  };
+
+
+  var getDateVariables = function() {
+    if (!yasr.results) return [];
+    var bindings = yasr.results.getBindings();
+    if (!bindings || bindings.length === 0) {
+      return [];
+    }
+    var dateVars = [];
+    var checkedVars = [];
+    for (var i = 0; i < bindings.length; i++) {
+      var binding = bindings[i];
+      for (var bindingVar in binding) {
+        if (checkedVars.indexOf(bindingVar) === -1 && binding[bindingVar].value) {
+          checkedVars.push(bindingVar);
+          if (hasDateDatatype(binding[bindingVar]) || hasGYearDatatype(binding[bindingVar])) {
+        	  dateVars.push(bindingVar);
+          }
+        }
+      }
+      
+      if (checkedVars.length === yasr.results.getVariables().length) {
+        //checked all vars. can break now
+        break;
+      }
+    }
+    
+    return dateVars;
+  };
+  
+  var hasDateDatatype = function(value) {
+    if(value.datatype == 'http://www.w3.org/2001/XMLSchema#date'){
+      return true;
+    }else{
+      return false;
+    }
+  };
+  
+  var hasGYearDatatype = function(value) {
+    if(value.datatype == 'http://www.w3.org/2001/XMLSchema#gYear'){
+      return true;
+    }else{
+      return false;
+    }
+  };
+
+  
+  return {
+    draw: draw,
+    name: "Timeline",
+    canHandleResults: canHandleResults,
+    getPriority: 1
+  };
+};
+

demos/sparnatural-demo-databnf/index.html

+<!doctype html>
+<html lang="fr">
+	<head>
+		<!-- Required meta tags -->
+		<meta charset="utf-8">
+		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+
+		<!-- Bootstrap CSS -->
+		<link href="https://stackpath.bootstrapcdn.com/bootswatch/4.3.1/litera/bootstrap.min.css" rel="stylesheet" integrity="sha384-D/7uAka7uwterkSxa2LwZR7RJqH2X6jfmhkJ0vFPGUtPyBMF2WMq9S+f9Ik5jJu1" crossorigin="anonymous">
+		<link rel="stylesheet" href="sparnatural.css" />
+
+		<!-- Font Awesome -->
+		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@5.9.0/css/all.min.css" />
+
+		<!-- YASGUI stuff -->
+		<link href='http://cdn.jsdelivr.net/npm/yasgui-yasqe@2.11.22/dist/yasqe.min.css' rel='stylesheet' type='text/css'/>
+		<link href='http://cdn.jsdelivr.net/npm/yasgui-yasr@2.12.19/dist/yasr.min.css' rel='stylesheet' type='text/css'/>
+
+		<title>SPARnatural - requêtes SPARQL naturelles</title>
+
+		<style>
+		  .yasqe .CodeMirror { font-size: 0.8em; height: 400px; }
+
+		  .yasr_header {
+		  	display: none;
+		  }
+		</style>
+		
+	</head>
+	<body>
+		<header>
+			<nav class="navbar navbar-expand  navbar-dark bg-dark">
+				<a class="navbar-brand display-1 mr-auto" href="#">SPARnatural - requêtes SPARQL naturelles</a>
+			</nav>
+		</header>
+		
+		<div class="container-fluid" style="margin-top:1em;">
+			<div class="row">
+				<div class="col-md-7">
+					<div id="ui-search"></div>
+				</div>
+				<div class="col-md-5">
+					<div class="row" style="margin-bottom:0.5em;">
+		            <div class="col-md-12">
+		             <span style="font-size:90%;"> 
+		             Les requêtes sont envoyées à <a id="endpoint" href="https://data.bnf.fr/sparql">https://data.bnf.fr/sparql</a>
+		             </span>
+		            </div>
+		          </div>
+		          <div class="row">
+		            <div class="col-md-12">
+		  					 <textarea id="yasqe"></textarea>
+		            </div>
+		          </div>
+				</div>
+			</div>