shacl-vue

Wizard editors ​

Sometimes the standard shacl-vue approach of matching a dedicated editor component to a single modeled property shape does not fully address the use case at hand. Think of creating complicated, multi-jump linkages between a record being edited and some other records, perhaps multiple at a time.

Let's take the following example: a user might want to add a DOI (Digital Object Identifier) to a Publication record, but there is no doi property on the Publication class, and instead:

  • a Publication has an identifiers slot, with the range Identifier
  • the Identifier class has slots: notation and creator
  • there is also a DOI class that subclasses from Identifier
  • to create a DOI record, the notation is important, while the creator is already known

Ideally, all of these classes and slots and linkages are details that should be of no concern to the user. They just want to add a DOI for their publication (actually the only really required field to enter is notation!) and having to do that via the existing route (find the identifiers slot -> create a new DOI record -> add notation -> add the creator correctly! -> finally save and link the created DOI record) is unnecessarily complex and bad UX.

There should be simpler way to achieve this. And there is, using the "Wizard Editor"!

This is a powerful feature that allows specification of arbitrarily complex user input and metadata linkage via relatively simple configuration of primitive form inputs and metadata templates. Think of it as a way to:

  • specify which arbitrary inputs should be shown in a form
  • specify how those input values should feed into a TTL template
  • autocreate arbitrarily complex and linked metadata upon saving the wizard form

A wizard editor can be configured to appear for any class, to use any of the supported inputs, and to use any TTL template. Specific configuration options are provided below.

Wizard editor configuration ​

This section will provide all currently available wizard configuration options using the DOI use case as a demonstrator, with the following config:

yaml
wizard_editor_selection:
  xyzri:XYZPublication:
    - DOIWizard

wizard_editors:
  DOIWizard:
    name: DOI Wizard
    description: Enter the 'Notation' field and hit *Save* in order to create a DOI record
    icon: mdi-identifier
    tooltip: Add a DOI
    inputs:
      - prop: notation
        name: Notation
        description: This is the unique DOI identifier text usually following 'http://doi.org/'
        type: text
        placeholder: 'example: 10.21105/joss.03262'
        required: true
        pattern: # some XSD-compatible regular expression 
        default: # some default value
    template: content:DOIWizardTemplate

content:
  DOIWizardTemplate:
    url: DOIWizardTemplate.ttl

1. wizard_editor_selection ​

This option provides a means to specify which wizards should show up where in the application. It is an object with keys being either class IRIs (in CURIE format) or dedicated sub-options _classes or _slots.

a) _classes key ​

This sub-option takes a list of wizard editor names as value, and specifies that the listed wizard editors should be rendered for all classes. These wizard editors will be rendered at the top of the class page next to the class name, for example the "Quick Add" wizard shown below:

alt

b) Class CURIE key ​

If the key is a class CURIE, this means that a to-be-specified wizard (or multiple) will be rendered for said class in any of three possible locations. These locations are specified as additional sub-options, each taking a value of list of wizard editor names:

  • _class: This renders at the top of the class page next to the class name (same as with the _classes key)
  • _record: This renders inside the editor form when a record is being edited, as shown below:
alt
  • _record_view: This renders inside the record viewer, as shown below:
alt

c) _slots key ​

The _slots sub-option has an object value, with the keys of that object being slot URIs in CURIE format. This allows wizards to be rendered for any class containing a specified slot/property. For each specified slot, further specification is possible of the location where the intended wizard(s) should be rendered, using the same _class, _record, and _record_view format explained above.

d) wizard_editor_selection example ​

The following detailed configuration example shows a real-world use case:

yaml
wizard_editor_selection:
  _classes:
    - AddRecordWizard
  xyzri:XYZPublication:
    _class:
      - DOIImportWizard
    _record_view:
      - DOIWizard
  xyzri:XYZPerson:
    _record:
      - DepictionUploadWizard
  _slots:
    dlthings:distributions:
      _record:
        - FileUploadWizard

This configuration instructs shacl-vue to do the following:

  • for all classes, at the top of each class page, show the AddRecordWizard
  • for the xyzri:XYZPublication class:
    • at the top of the class page, show the DOIImportWizard
    • in each record viewer, show the DOIWizard
  • for the xyzri:XYZPerson class:
    • inside a record editor, show the DepictionUploadWizard
  • for any class that contains the dlthings:distributions slot, inside a record editor, show the FileUploadWizard

2. wizard_editors ​

This is the main config option that allows creation of a wizard editor and specification of its inputs, template, and other options. The wizard receives a key (here DOIWizard), and then its options:

Wizard options include:

name ​

This is a human-readable name for the wizard that will be displayed at the top of the wizard form.

description ​

This is human-readble descriptive text or instructions to help users understand the context and purpose of the form, and will render inside the initiated wizard form underneath the name. It can be supplied as plain text or as Markdown.

icon ​

This provides a means to specify the icon image that will show up on records for which the specific wizard has been configured to render. Clicking on the icon is the primary and only way to open the associated wizard editor. Icons can be specified in different formats:

  • an mdi- string which will render any of the standard free icons from the mdi icon library
  • an svg string, which will be rendered as is
  • a content: pointer to an SVG file, which will be loaded and rendered as is

Importantly, any SVGf file or string used in this context should have a viewport or width/height of 24x24 px.

tooltip ​

This is a short human-readable sentence that will show when the cursor hovers over the wizard icon and is intended to explain shortly what the wizard does.

inputs ​

The core of the wizard lies in its specification of inputs. An input can have several properties:

  • prop is the field name through which this input is referenced, both in shacl-vue internals and inside the TTL template
  • name will render as the input label
  • description is a further description of the input that will render when hovering over the input label;
  • type tells shacl-vue which type of input component to render for which the input value will be captured; currently we support:
    • text
    • text-paragraph
    • boolean
    • object: an input with this type can itself receive more input specifications recursively
    • upload: this will render a file upload widget; note that this requires an associated config for the gitannex_p2phttp_config_wizard option to be specified; see the Requirements for the wizard editor uploader section for more information.
  • multi_valued allow adding multiple values of the same type for the same input field
  • placeholder will render if the field has no entered value yet
  • required will make the field required (or not) for validation purposes
  • pattern will apply a regular expression check to text-based inputs for validation purposes
  • default will prepopulate the value of the input

component ​

This option tells the wizard editor to render a specific VueJS component instead of using the built-in input-driven components of the wizard editor feature. Such components can be supplied via runtime plugins and should be specified using the format <plugin-name>:<component-name>, e.g. component: doi:DOIFetcher. Wizard editors using the component option should still specify inputs in order for the template filling step to function correctly.

template ​

Another core part of the wizard specification is the TTL template string, which will be populated using the values entered for the wizard inputs. The TTL string format is the same as is already supported by shacl-vue. For example:

turtle
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix dlthings: <https://concepts.datalad.org/s/things/unreleased/> .
@prefix ror: <https://ror.org/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<{pid}> dcterms:identifier _:n0-1.
_:n0-1 a dlthings:DOI;
    skos:notation "{notation}";
    dcterms:creator ror:01fyxcz70.

Note the following inside the template:

  • {pid} is the standard way to refer to the record within the context of which the wizard editor is rendered, for example if the DOIWizard is initiated from a specific Publication record, that record's identifier becomes available inside the TTL template.
  • {notation} is an example of how the prop of a configured input is used to reference it inside the TTL template
  • sub-inputs of inputs with type: object can be accessed using dot-notation, e.g {person.name}

The TTL template can be specified as a direct string inside the configuration, but also as a file via a content: pointer to the file URL.

Nunjucks support ​

The curly-braces approach to string template filling, shown in the template above, is useful up to a point. However, one can quickly encounter the shortfalls of such a simple approach, e.g. when there is the need to render array elements in a template, or when some values require conditional rendering, or when additional processes or calculations are needed before rendering. For these real-world scenarios, shacl-vue supports the use of Nunjucks templates. For a Nunjucks template to be recogized as such by shacl-vue, the extension has to be .nunjucks.ttl.

Apart from supporting standard Nunjucks templating features, shacl-vue also supplies the following Nunjucks filters and global methods:

ttl ​

A filter that applies character escaping to make the output ttl-safe

_randomUUID ​

A method that uses JavaScript's crypto.randomUUID() to generate a random UUI.

_ISO8601datetime ​

A method that uses JavaScript's Date() and toISOString() tot generate an ISO8601-compliant date-time string.

Wizard editor demo ​

The PsyInf Knowledge Pooling Tool UI has a "DOI Import Wizard" implementation that demonstrates all of the above.

alt

The UI source code repository contains all necessary components, including: