improved readme

ULB-Darmstadt · Sep 14, 2023 · f74d744 · f74d744
1 parent c37f837
commit f74d744
Show file tree

Hide file tree

Showing 4 changed files with 29 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -16,16 +16,28 @@ This library provides an HTML5 web component that renders [SHACL shapes](https:/
     <script src="https://cdn.jsdelivr.net/npm/@ulb-darmstadt/shacl-form/dist/index.js" type="module"></script>
   </head>
   <body>
-    <shacl-form id="my-form" data-shapes="..."></shacl-form>
+    <!-- SHACL shapes can be defined on the attribute 'data-shapes' or can be loaded by setting attribute 'data-shapes-url' -->
+    <shacl-form data-shapes="
+      @prefix sh: <http://www.w3.org/ns/shacl#> .
+      @prefix ex: <http://example.org#> .
+
+      ex:ExampleShape
+        a sh:NodeShape ;
+        sh:property [
+          sh:name 'my value' ;
+          sh:path ex:exampleValue ;
+          sh:maxCount 3 ;
+        ] .
+    "></shacl-form>
 
     <script>
-      const form = document.getElementById("my-form")
+      const form = document.querySelector("shacl-form")
       form.addEventListener('change', event => {
         // check if form validates according to the SHACL shapes
         if (event.detail?.valid) {
           // get data graph as RDF triples and log them to the browser console
-          const data = form.serialize('application/ld+json') 
-          console.log('entered form data', data)
+          const triples = form.serialize() 
+          console.log('entered form data', triples)
           // store the data somewhere, e.g. in a triple store
         }
       })
@@ -34,14 +46,14 @@ This library provides an HTML5 web component that renders [SHACL shapes](https:/
 </html>
 ```
 
-### Element data attributes
+### Element attributes
 Attribute | Description
 ---|---
 data-shapes | SHACL shape definitions (e.g. a turtle string) to generate the form from
-data-shapes-url | When `data-shapes` is not set, the shapes graph is loaded from this URL
-data-shape-subject | Optional subject (id) of the shacl node shape to use as root for the form. If not set, the first found shacl node shape will be used
+data-shapes-url | When `data-shapes` is not set, the SHACL shapes are loaded from this URL
+data-shape-subject | Optional subject (id) of the SHACL node shape to use as root for the form. If not set, the first found node shape will be used
 data-values | RDF triples (e.g. a turtle string) to use as existing data values in the generated form
-data-values-url | When `data-values` is not set, the data graph is loaded from this URL
+data-values-url | When `data-values` is not set, the data triples are loaded from this URL
 data-value-subject | The subject (id) of the generated data. If this is not set, a blank node with a new UUID will be used. If `data-values` or `data-values-url` is set, this id is also used to find existing data in the data graph to fill the form
 data-language | Language to use if shapes contain langStrings, e.g. in `sh:name` or `rdfs:label`
 data&#x2011;ignore&#x2011;owl&#x2011;imports | By default, `owl:imports` IRIs are fetched and the resulting triples added to the shapes graph. Set this attribute in order to disable this feature
@@ -52,7 +64,7 @@ data-submit-button | Whether to append a submit button to the form. The string v
 serialize(format?: string): string | []
 ```
 
-Serializes the form data as RDF triples. Supported formats:  `text/turtle` (default), `application/ld+json`, `application/n-triples`, `application/n-quads`, `application/trig`. Format `application/ld+json` returns a JSON array, all other formats return a string.
+Serializes the form data to RDF triples. Supported formats:  `text/turtle` (default), `application/ld+json`, `application/n-triples`, `application/n-quads`, `application/trig`. Format `application/ld+json` returns a JSON array, all other formats return a string.
 
 ```typescript
 validate(ignoreEmptyValues: boolean): Promise<boolean>

diff --git a/src/plugin.ts b/src/plugin.ts
@@ -6,21 +6,24 @@ export class Plugins {
 
     register(plugin: Plugin) {
         if (plugin.predicate === undefined && plugin.datatype === undefined) {
-            console.warn('not registering plugin because it does neither define predicate nor datatype', plugin)
+            console.warn('not registering plugin because it does neither define "predicate" nor "datatype"', plugin)
         } else {
             this.plugins[`${plugin.predicate}^${plugin.datatype}`] = plugin
         }
     }
 
     find(predicate: string | undefined, datatype: string | undefined): Plugin | undefined {
+        // first try to find plugin with matching predicate and datatype
         let plugin = this.plugins[`${predicate}^${datatype}`]
         if (plugin) {
             return plugin
         }
+        // now prefer predicate over datatype
         plugin = this.plugins[`${predicate}^${undefined}`]
         if (plugin) {
             return plugin
         }
+        // last, try to find plugin with matching datatype
         return this.plugins[`${undefined}^${datatype}`]
     }
 }

diff --git a/src/plugins/mapbox.ts b/src/plugins/mapbox.ts
@@ -11,7 +11,7 @@ const dialogTemplate = '<style>#shaclMapDialog .closeButton { position: absolute
 #shaclMapDialog .closeButton:hover { background-color: #FFF }\
 #shaclMapDialog .hint { position: absolute; right: 60px; top: 3px; z-index: 1; padding: 4px 6px; background-color: #FFFA; border-radius: 4px; }\
 </style><dialog id="shaclMapDialog" onclick="event.target==this && this.close()">\
-<div class="hint">Draw a polygon or point, then close map</div>\
+<div class="hint">&#x24D8; Draw a polygon or point, then close map</div>\
 <button class="closeButton" type="button" onclick="this.parentElement.close()">&#x2715;</button>\
 </dialog>'
 

diff --git a/src/property-template.ts b/src/property-template.ts
@@ -27,7 +27,7 @@ const mappers: Record<string, (template: ShaclPropertyTemplate, term: Term) => v
     [`${PREFIX_SHACL}languageIn`]:   (template, term) => { template.languageIn = template.config.lists[term.value]; template.datatype = DataFactory.namedNode(PREFIX_RDF + 'langString') },
     [`${PREFIX_SHACL}defaultValue`]: (template, term) => { template.defaultValue = term },
     [`${PREFIX_SHACL}hasValue`]:     (template, term) => { template.hasValue = term },
-    [SHACL_PREDICATE_CLASS.value]:        (template, term) => {
+    [SHACL_PREDICATE_CLASS.value]:   (template, term) => {
         template.class = term as NamedNode
         // try to find node shape that has requested target class
         const nodeShapes = template.config.shapesGraph.getSubjects(`${PREFIX_SHACL}targetClass`, term, SHAPES_GRAPH)
@@ -80,15 +80,9 @@ export class ShaclPropertyTemplate  {
         this.merge(quads)
 
         // provide best fitting label for UI
-        this.label = this.name?.value || ''
+        this.label = this.name?.value || findLabel(quads, config.attributes.language)
         if (!this.label) {
-            this.label = findLabel(quads, config.attributes.language)
-        }
-        if (!this.label) {
-            this.label = this.path ? removePrefixes(this.path, config.prefixes) : ''
-        }
-        if (!this.label) {
-            this.label = 'unknown'
+            this.label = this.path ? removePrefixes(this.path, config.prefixes) : 'unknown'
         }
     }