@ulb-darmstadt/shacl-form 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/README.md +126 -17
  2. package/dist/config.d.ts +3 -1
  3. package/dist/exports.d.ts +2 -0
  4. package/dist/form-bootstrap.d.ts +3 -2
  5. package/dist/form-bootstrap.js +2 -0
  6. package/dist/form-default.d.ts +5 -0
  7. package/dist/form-default.js +2 -0
  8. package/dist/form-material.d.ts +3 -2
  9. package/dist/form-material.js +335 -0
  10. package/dist/plugins/mapbox.d.ts +12 -7
  11. package/dist/plugins/mapbox.js +1 -1
  12. package/dist/property-template.d.ts +2 -0
  13. package/dist/theme.d.ts +3 -0
  14. package/dist/themes/bootstrap.d.ts +2 -2
  15. package/dist/themes/{native.d.ts → default.d.ts} +1 -1
  16. package/package.json +13 -9
  17. package/dist/bootstrap.js +0 -2
  18. package/dist/form-native.d.ts +0 -4
  19. package/dist/index.js +0 -2
  20. package/dist/material.js +0 -335
  21. package/dist/themes/material.js +0 -335
  22. package/dist/themes/material.js.LICENSE.txt +0 -65
  23. /package/dist/{bootstrap.js.LICENSE.txt → form-bootstrap.js.LICENSE.txt} +0 -0
  24. /package/dist/{index.js.LICENSE.txt → form-default.js.LICENSE.txt} +0 -0
  25. /package/dist/{material.js.LICENSE.txt → form-material.js.LICENSE.txt} +0 -0
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # SHACL Form Generator
2
2
 
3
- ```
3
+ ```console
4
4
  npm i @ulb-darmstadt/shacl-form
5
5
  ```
6
6
 
@@ -9,11 +9,12 @@ An HTML5 web component for editing/viewing [RDF](https://www.w3.org/RDF/) data t
9
9
  ## [See demo here](https://ulb-darmstadt.github.io/shacl-form/)
10
10
 
11
11
  ### Basic usage
12
+
12
13
  ```html
13
14
  <html>
14
15
  <head>
15
16
  <!-- load web component -->
16
- <script src="https://cdn.jsdelivr.net/npm/@ulb-darmstadt/shacl-form/dist/index.js" type="module"></script>
17
+ <script src="https://cdn.jsdelivr.net/npm/@ulb-darmstadt/shacl-form/dist/form-default.js" type="module"></script>
17
18
  </head>
18
19
  <body>
19
20
  <!--
@@ -38,8 +39,8 @@ An HTML5 web component for editing/viewing [RDF](https://www.w3.org/RDF/) data t
38
39
  form.addEventListener('change', event => {
39
40
  // check if form data validates according to the SHACL shapes
40
41
  if (event.detail?.valid) {
41
- // get data graph as RDF triples (default format is 'text/turtle')
42
- // and log them to the browser console
42
+ // get data graph as RDF triples and
43
+ // log them to the browser console
43
44
  const triples = form.serialize()
44
45
  console.log('entered form data', triples)
45
46
  // store the data somewhere, e.g. in a triple store
@@ -51,6 +52,7 @@ An HTML5 web component for editing/viewing [RDF](https://www.w3.org/RDF/) data t
51
52
  ```
52
53
 
53
54
  ### Element attributes
55
+
54
56
  Attribute | Description
55
57
  ---|---
56
58
  data-shapes | SHACL shape definitions (e.g. a turtle string) to generate the form from
@@ -58,18 +60,21 @@ data-shapes-url | When `data-shapes` is not set, the SHACL shapes are loaded fro
58
60
  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
59
61
  data-values | RDF triples (e.g. a turtle string) to use as existing data graph to fill the form
60
62
  data-values-url | When `data-values` is not set, the data graph triples are loaded from this URL
61
- 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 the root node in the data graph to fill the form
63
+ data-value-subject | The subject (id) of the generated data. If this is not set, a blank node with a new UUID is created. If `data-values` or `data-values-url` is set, this id is also used to find the root node in the data graph to fill the form
62
64
  data-language | Language to use if shapes contain langStrings, e.g. in `sh:name` or `rdfs:label`. Default is [`navigator.language`](https://www.w3schools.com/jsref/prop_nav_language.asp)
63
- data&#x2011;ignore&#x2011;owl&#x2011;imports | By default, `owl:imports` URLs are fetched and the resulting RDF triples are added to the shapes graph. Set this attribute to any value in order to disable this feature
64
- data-mode | When set to `"view"`, turns the web component into a viewer that displays the given data graph without editing functionality
65
- data-submit-button | Whether to add a submit button to the form. The value of this attribute is used as the button label. `submit` events will only fire after successful validation
65
+ data-loading | Text to display while the web component is initializing. Default: `"Loading..."`
66
+ data&#x2011;ignore&#x2011;owl&#x2011;imports | By default, `owl:imports` URLs are fetched and the resulting RDF triples are added to the shapes graph. Setting this attribute to any value disables this feature
67
+ data-view | When set, turns the web component into a viewer that displays the given data graph without editing functionality
68
+ data-collapse | When set, `sh:group`s and properties with `sh:node` and `sh:maxCount` != 1 are displayed in a collapsible accordion-like widget to reduce visual complexity of the form. The collapsible element is initially shown closed, except when this attribute's value is `"open"`
69
+ data-submit-button | [Ignored when `data-view` attribute is set] Whether to add a submit button to the form. The value of this attribute is used as the button label. `submit` events get emitted only when the form data validates
66
70
 
67
71
  ### Element functions
72
+
68
73
  ```typescript
69
74
  serialize(format?: string): string
70
75
  ```
71
76
 
72
- Serializes the form data to RDF triples. Supported formats: `text/turtle` (default), `application/ld+json`, `application/n-triples`, `application/n-quads`, `application/trig`.
77
+ Serializes the form data to RDF triples. <a name="formats"></a>Supported formats: `text/turtle` (default), `application/ld+json`, `application/n-triples`, `application/n-quads`, `application/trig`.
73
78
 
74
79
  ```typescript
75
80
  validate(ignoreEmptyValues: boolean): Promise<boolean>
@@ -84,7 +89,7 @@ Register a [plugin](./src/plugin.ts) to customize editing/viewing certain proper
84
89
  ```typescript
85
90
  setTheme(theme: Theme)
86
91
  ```
87
- Set a design theme to use for rendering. See section "Theming" below.
92
+ Set a design theme to use for rendering. See section [Theming](#Theming).
88
93
  ```typescript
89
94
  setClassInstanceProvider((className: string) => Promise<string>)
90
95
  ```
@@ -92,15 +97,119 @@ Sets a callback function that is called when a SHACL property has an `sh:class`
92
97
  - `example:Instance a example:Class`
93
98
  - `example:Instance a owl:NamedIndividual; skos:broader example:Class`
94
99
 
95
- You can also use `rdfs:subClassOf` or `skos:broader` to build class hierarchies.
100
+ Class hierarchies can be built using `rdfs:subClassOf` or `skos:broader`.
101
+
102
+ ## Features
103
+
104
+ ### Data graph binding
105
+
106
+ `<shacl-form>` requires only a shapes graph as input via the attribute `data-shapes` (or `data-shapes-url`) to generate an empty form and create new RDF data from the form input fields. Using the attributes `data-values` (or `data-values-url`) and `data-value-subject`, you can also bind an existing data graph to the form. The given data graph is then used to fill the form input fields.
107
+
108
+ ### Viewer mode
109
+
110
+ `<shacl-form>` not only is an RDF data editor, but can also be used as a viewer by setting attribute `data-view` and binding both, a shapes and a data graph. See the [demo](https://ulb-darmstadt.github.io/shacl-form/#viewer-mode) for an example.
111
+
112
+ ### Providing additional data to the shapes graph
113
+
114
+ Apart from setting the element attributes `data-shapes` or `data-shapes-url`, there are two ways of adding RDF data to the shapes graph:
115
+ 1. While parsing the triples of the shapes graph, any encountered `owl:imports` predicate that has a valid HTTP URL value will tried to be fetched with the HTTP Accept header set to all of the [supported](#formats) MIME types. A successful response will be parsed and added to the shapes graph. The [example shapes graph](https://ulb-darmstadt.github.io/shacl-form/#example) contains the following triples:
116
+ ```
117
+ example:Attribution
118
+ owl:imports <https://w3id.org/nfdi4ing/metadata4ing/> ;
119
+ sh:property [
120
+ sh:name "Role" ;
121
+ sh:path dcat:hadRole ;
122
+ sh:class prov:Role ;
123
+ ] .
124
+ ```
125
+ In this case, the URL references an ontology which among other things defines instances of class `prov:Role` that are then used to populate the "Role" dropdown in the form.
126
+
127
+ 2. The `<shacl-form>` element has a function `setClassInstanceProvider((className: string) => Promise<string>)` that registers a callback function which is called when a SHACL property has
128
+ an `sh:class` predicate. The expected return value of this callback function is a (promise of a) string (e.g. in format `text/turtle`) that contains RDF class instance definitions of the given class. Instances can be defined e.g. like:
129
+ - `example:Instance a example:Class`
130
+ - `example:Instance a owl:NamedIndividual; skos:broader example:Class`
131
+
132
+ Class hierarchies can be built using `rdfs:subClassOf` or `skos:broader`.
133
+
134
+ In [this example](https://ulb-darmstadt.github.io/shacl-form/#example), the code:
135
+
136
+ ```typescript
137
+ form.setClassInstanceProvider((clazz) => {
138
+ if (clazz === 'http://example.org/Material') {
139
+ return `
140
+ <http://example.org/steel> a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Steel".
141
+ <http://example.org/wood> a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Wood".
142
+ <http://example.org/alloy> a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Alloy".
143
+ <http://example.org/plaster> a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Plaster".
144
+ `
145
+ }
146
+ )
147
+ ```
148
+ returns instances of the class `http://example.org/Material` that are then used to populate the "Artwork material" dropdown in the form.
149
+
150
+ A more realistic use case of this feature is calling some API endpoint to fetch class instance definitions from existing ontologies.
151
+
152
+ ### SHACL "or" constraint
153
+
154
+ `<shacl-form>` supports using [sh:or](https://www.w3.org/TR/shacl/#OrConstraintComponent) to let users select between different options on nodes or properties.
155
+ The [example shapes graph](https://ulb-darmstadt.github.io/shacl-form/#example) has the following triples:
156
+ ```
157
+ example:Attribution
158
+ a sh:NodeShape ;
159
+ sh:property [
160
+ sh:maxCount 1 ;
161
+ sh:minCount 1 ;
162
+ sh:path prov:agent ;
163
+ sh:or (
164
+ [ sh:node example:Person ; rdfs:label "Person" ]
165
+ [ sh:node example:Organisation ; rdfs:label "Organisation" ]
166
+ )
167
+ ] .
168
+ ```
169
+ When adding a new attribution, `<shacl-form>` renders a dropdown to let the user select between the two options Person/Organisation. After selecting one of the options, the dropdown is replaced by the input fields of the selected node shape.
170
+
171
+ When binding an existing data graph to the form, the `sh:or` constraint is tried to be resolved depending on the respective data value:
172
+ - For RDF literals, an `sh:or` option with a matching `sh:datatype` is chosen
173
+ - For blank nodes or named nodes, the `rdf:type` of the value is tried to be matched with a node shape having a corresponding `sh:targetClass` or with a property shape having a corresponding `sh:class`
174
+
175
+ ### SHACL shape inheritance
176
+
177
+ SHACL defines two ways of inheriting shapes: [sh:and](https://www.w3.org/TR/shacl/#AndConstraintComponent)
178
+ and [sh:node](https://www.w3.org/TR/shacl/#NodeConstraintComponent). `<shacl-form>` supports both. In [this example](https://ulb-darmstadt.github.io/shacl-form/#example), node shape `example:ArchitectureModelDataset` extends `example:Dataset` by defining the following RDF triple:
179
+
180
+ ```
181
+ example:ArchitectureModelDataset sh:node example:Dataset .
182
+ ```
183
+
184
+ Properties of inherited shapes are displayed first.
185
+
186
+ ### Plugins
187
+
188
+ Plugins can modify rendering of the form and add functionality to edit and view certain RDF datatypes or predicates (or a combination of both). As an example, the JavaScript of [this page](https://ulb-darmstadt.github.io/shacl-form/#example) contains the following code:
189
+ ```typescript
190
+ import { MapboxPlugin } from '@ulb-darmstadt/shacl-form/plugins/mapbox.js'
191
+ const form = document.getElementById("shacl-form")
192
+ form.registerPlugin(new MapboxPlugin({ datatype: 'http://www.opengis.net/ont/geosparql#wktLiteral' }, API_KEY))
193
+ ```
194
+ In effect, whenever a SHACL property has an `sh:datatype` of `http://www.opengis.net/ont/geosparql#wktLiteral`, the plugin is called to create the editor and/or viewer HTML elements. This specific plugin uses [Mapbox GL](https://docs.mapbox.com/mapbox-gl-js/guides/) to edit or view geometry in format [well known text](http://giswiki.org/wiki/Well_Known_Text) on a map.
195
+ Custom plugins can be built by extending class [Plugin](https://github.com/ULB-Darmstadt/shacl-form/blob/main/src/plugin.ts#L40).
196
+
197
+ ### Property grouping and collapsing
198
+
199
+ Properties can be grouped using [sh:group](https://www.w3.org/TR/shacl/#group) in the shapes graph. [This example](https://ulb-darmstadt.github.io/shacl-form/#example) defines a group "Physical properties" and assigns certain properties to it.
200
+
201
+ When the element attribute `data-collapse` is set, `<shacl-form>` creates an accordion-like widget that toggles the visibility of grouped properties in order to reduce the visual complexity of the form. If the grouped properties should initially be shown, set `data-collapse="open"`.
202
+
203
+ Apart from grouped properties, all properties having an `sh:node` predicate and `sh:maxCount` != 1 are collapsed.
204
+
205
+ ### Theming
96
206
 
97
- ## Theming
98
- `<shacl-form>` comes in 3 different bundles, each providing a specific theme:
207
+ `<shacl-form>` comes in 3 different bundles, each providing a specific theme. See the [demo page](https://ulb-darmstadt.github.io/shacl-form/#theming) for an example.
99
208
 
100
209
  Theme | Import statement
101
210
  --- | ---
102
- Native (opinionated raw HTML) | `import '@ulb-darmstadt/shacl-form/index.js'`
103
- [Bootstrap](./src/themes/bootstrap.ts) | `import '@ulb-darmstadt/shacl-form/bootstrap.js'`
104
- [Material Design](./src/themes/material.ts) | `import '@ulb-darmstadt/shacl-form/material.js'`
211
+ [Default]((./src/themes/default.ts)) (slightly customized default browser styles) | `import '@ulb-darmstadt/shacl-form/form-default.js'`
212
+ [Bootstrap](./src/themes/bootstrap.ts) [alpha status] | `import '@ulb-darmstadt/shacl-form/form-bootstrap.js'`
213
+ [Material Design](./src/themes/material.ts) [alpha status] | `import '@ulb-darmstadt/shacl-form/form-material.js'`
105
214
 
106
- Custom themes can be employed by implementing class [Theme](./src/theme.ts) yourself, then activating it with function `setTheme()` on the `<shacl-form>` element.
215
+ Custom themes can be employed by extending class [Theme](./src/theme.ts), then calling function `setTheme()` on the `<shacl-form>` element.
package/dist/config.d.ts CHANGED
@@ -10,9 +10,11 @@ export declare class ElementAttributes {
10
10
  values: string | null;
11
11
  valuesUrl: string | null;
12
12
  valueSubject: string | null;
13
- mode: string | null;
13
+ view: string | null;
14
14
  language: string;
15
+ loading: string;
15
16
  ignoreOwlImports: string | null;
17
+ collapse: string | null;
16
18
  submitButton: string | null;
17
19
  }
18
20
  export declare class Config {
package/dist/exports.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ export { Theme, InputListEntry, Editor } from "./theme";
2
+ export { Plugin } from './plugin';
package/dist/form-bootstrap.d.ts CHANGED
@@ -1,4 +1,5 @@
1
- import { ShaclForm } from "./form";
2
- export declare class ShaclFormElement extends ShaclForm {
1
+ import { ShaclForm as FormBase } from "./form";
2
+ export * from './exports';
3
+ export declare class ShaclForm extends FormBase {
3
4
  constructor();
4
5
  }