New wizard editor component #320

Merged

jsheunis merged 1 commit from wizardeditor into main

2026-02-04 17:42:20 +00:00

jsheunis commented

2026-02-04 17:41:09 +00:00

Owner

closes datalink/shacl-vue#152

This feature allows custom form dialog construction via config, as well as TTL template
specification, which is then string-serialized using the user inputs upon form save, followed
by adding the parsed quads to the graph store. This is a powerful feature that allows
arbitrarily complex user input and metadata linkage via relatively simple primitive form
input configuration. These wizard editors can be configured to appear for any class.
These are the working principles:

a new wizard is declared and configured via the new wizard_editors option, which allows
several standard options along with the important: an array of inputs and the template
inputs have to specify the type, among other rendering options; currently supported
types include text, text-paragraph, and boolean. The plan is to extend these
substantially, possibly driven by LinkML types provided by a specific schema, but also
allowing already supported shacl-vue editors. Each input configures the associated
input component in the wizard form, and they will render in the order provided via
configuration.
inputs also have to specify a unique prop, which becomes the field name through which
this input is referenced, both in shacl-vue internals and inside the TTL template.
the template should be a TTL string, with to-be-populated field names inside
{curly brackets}. Field names include all props configured for inputs, as well as
{pid}, which refers to the identifty of the current record being edited and from which
the wizard is launched. TTL can either be supplied directly as a string, or as a URL via
the existing content option.
declared wizards are configured for rendering for specific classes via the new option
wizard_editor_selection.
wizards can be supplied with icons via configuration; these can come in different formats:
- an mdi- string which will render any of the standard free mdi icons
- 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 SVG used in this context should have a viewport or width/height of 24x24 px

This commit includes a documentation update that covers all details related to the wizard
editor feature, extensively.

To achieve the above, the following major code changes were done:

The NodeShapeEditor, which renders for a given record when it is being created or edited
inside the FormEditor, will check the wizard_editor_selection to see if any wizards need
to be made available for the current record type (a.k.a. class). If yes, it will render those
as buttons at the top of the form below the All fields button. The wizards render as clickable
buttons, with customizable tooltips and icons, which will open a dialog when clicked, passing
along all config options related to the selected wizard
The new WizardEditor will render inside the dialog. It will display all general config
options of the wizard, and will then render a row per input. Inputs have their own descriptions
and validation rules embedded (taken from config). Reset and Cancel buttons are self-explanatory.
The save button will run validation on all inputs, and on successful validation will emit a save
event to the parent component (NodeShapeEditor), also passing along all entered input values.
On detecting a save event from a wizard, the NodeShapeEditor will:
- receive the input values and declare them as wizardData
- add the node ID of the current record to the wizardData under the pid field, which is how
  the record can be referenced inside the TTL template
- pass wizardData to the existing fillStringTemplate utility function to render valid TTL
  output
- pass the TTL to rdfDS.parseTTLandDedup(newTTL) that outputs quads and adds them to the graph
  store
rdfDS.parseTTLandDedup(newTTL) returns all the quads that were parsed and added to the graph
store. These are now process individually. Importantly, if an added quad has a subject value that
is identical
to the current node ID, we delete it from the graph store, because it uses a nonsense named node
(the node ID of the record, which is not reproducibly identical to the record PID). However, we
also add the quad's object to the formData under the index of the current node and the quad's
predicate, in order to keep linkage to the TTL-parsed quads. Importantly, the existing standard
functionality that runs when saving a form (for record creation or editing) will then take care
of adding the correct quads to the graph store to replace those that were deleted.
Continuing with the individual processing of quads that were parsed from TTL and added to the graph
store, if an added quad has a subject value that is NOT identical to the current node ID, AND it
is a named node, this means that a new record has been added to the graph store and it is therefore
eligible for submission. This is added to savedNodes and nodesToSubmit, as well as a separate
NodeShapeEditor-specific tracker of all wizard-added quads.
Garbage cleanup is also necessary in the case where quads were added to the graph store by a wizard
but the form was then subsequently cancelled. To deal with this, NodeShapeEditor registers a form
cancel handler via the existing registerHandler functionality, which will delete all the relevant
quads.

Lastly, for improved UI the headings of "property groups" in the NodeShapeEditor have been
removed. This is in anticipation of the complete removal of parent-class-based grouping of
properties inside the NodeShapeEditor.

closes https://hub.psychoinformatics.de/datalink/shacl-vue/issues/152 This feature allows custom form dialog construction via config, as well as TTL template specification, which is then string-serialized using the user inputs upon form save, followed by adding the parsed quads to the graph store. This is a powerful feature that allows arbitrarily complex user input and metadata linkage via relatively simple primitive form input configuration. These wizard editors can be configured to appear for any class. These are the working principles: - a new wizard is declared and configured via the new `wizard_editors` option, which allows several standard options along with the important: an array of `inputs` and the `template` - `inputs` have to specify the `type`, among other rendering options; currently supported `type`s include `text`, `text-paragraph`, and `boolean`. The plan is to extend these substantially, possibly driven by LinkML types provided by a specific schema, but also allowing already supported `shacl-vue` editors. Each `input` configures the associated input component in the wizard form, and they will render in the order provided via configuration. - `input`s also have to specify a unique `prop`, which becomes the field name through which this input is referenced, both in `shacl-vue` internals and inside the TTL template. - the `template` should be a TTL string, with to-be-populated field names inside `{curly brackets}`. Field names include all `prop`s configured for `input`s, as well as `{pid}`, which refers to the identifty of the current record being edited and from which the wizard is launched. TTL can either be supplied directly as a string, or as a URL via the existing `content` option. - declared wizards are configured for rendering for specific classes via the new option `wizard_editor_selection`. - wizards can be supplied with icons via configuration; these can come in different formats: - an `mdi-` string which will render any of the standard free `mdi` icons - 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 SVG used in this context should have a viewport or width/height of 24x24 px This commit includes a documentation update that covers all details related to the wizard editor feature, extensively. To achieve the above, the following major code changes were done: - The `NodeShapeEditor`, which renders for a given record when it is being created or edited inside the `FormEditor`, will check the `wizard_editor_selection` to see if any wizards need to be made available for the current record type (a.k.a. class). If yes, it will render those as buttons at the top of the form below the `All fields` button. The wizards render as clickable buttons, with customizable tooltips and icons, which will open a dialog when clicked, passing along all config options related to the selected wizard - The new `WizardEditor` will render inside the dialog. It will display all general config options of the wizard, and will then render a row per input. Inputs have their own descriptions and validation rules embedded (taken from config). Reset and Cancel buttons are self-explanatory. The save button will run validation on all inputs, and on successful validation will emit a `save` event to the parent component (`NodeShapeEditor`), also passing along all entered input values. - On detecting a `save` event from a wizard, the `NodeShapeEditor` will: - receive the input values and declare them as `wizardData` - add the node ID of the current record to the `wizardData` under the `pid` field, which is how the record can be referenced inside the TTL template - pass `wizardData` to the existing `fillStringTemplate` utility function to render valid TTL output - pass the TTL to `rdfDS.parseTTLandDedup(newTTL)` that outputs quads and adds them to the graph store - `rdfDS.parseTTLandDedup(newTTL)` returns all the quads that were parsed and added to the graph store. These are now process individually. Importantly, if an added quad has a subject value that is identical to the current node ID, we delete it from the graph store, because it uses a nonsense named node (the node ID of the record, which is not reproducibly identical to the record PID). However, we also add the quad's object to the `formData` under the index of the current node and the quad's predicate, in order to keep linkage to the TTL-parsed quads. Importantly, the existing standard functionality that runs when saving a form (for record creation or editing) will then take care of adding the correct quads to the graph store to replace those that were deleted. - Continuing with the individual processing of quads that were parsed from TTL and added to the graph store, if an added quad has a subject value that is NOT identical to the current node ID, AND it is a named node, this means that a new record has been added to the graph store and it is therefore eligible for submission. This is added to `savedNodes` and `nodesToSubmit`, as well as a separate `NodeShapeEditor`-specific tracker of all wizard-added quads. - Garbage cleanup is also necessary in the case where quads were added to the graph store by a wizard but the form was then subsequently cancelled. To deal with this, `NodeShapeEditor` registers a form cancel handler via the existing `registerHandler` functionality, which will delete all the relevant quads. Lastly, for improved UI the headings of "property groups" in the `NodeShapeEditor` have been removed. This is in anticipation of the complete removal of parent-class-based grouping of properties inside the `NodeShapeEditor`.

jsheunis added 1 commit

2026-02-04 17:41:09 +00:00

New wizard editor component 3c091c324f

- a new wizard is declared and configured via the new 'wizard_editors' option, which allows
several standard options along with the important: an array of 'inputs' and the 'template'
- 'inputs' have to specify the 'type', among other rendering options; currently supported
'type's include 'text', 'text-paragraph', and 'boolean'. The plan is to extend these
substantially, possibly driven by LinkML types provided by a specific schema, but also
allowing already supported 'shacl-vue' editors. Each 'input' configures the associated
input component in the wizard form, and they will render in the order provided via
configuration.
- 'input's also have to specify a unique 'prop', which becomes the field name through which
this input is referenced, both in 'shacl-vue' internals and inside the TTL template.
- the 'template' should be a TTL string, with to-be-populated field names inside
'curly brackets'. Field names include all 'prop's configured for 'input's, as well as
'pid', which refers to the identifty of the current record being edited and from which
the wizard is launched. TTL can either be supplied directly as a string, or as a URL via
the existing 'content' option.
- declared wizards are configured for rendering for specific classes via the new option
'wizard_editor_selection'.
- wizards can be supplied with icons via configuration; these can come in different formats:
- an 'mdi-' string which will render any of the standard free 'mdi' icons
- 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 SVG used in this context should have a viewport or width/height of 24x24 px

This commit includes a documentation update that covers all details related to the wizard
editor feature, extensively.

To achieve the above, the following major code changes were done:
- The 'NodeShapeEditor', which renders for a given record when it is being created or edited
inside the 'FormEditor', will check the 'wizard_editor_selection' to see if any wizards need
to be made available for the current record type (a.k.a. class). If yes, it will render those
as buttons at the top of the form below the 'All fields' button. The wizards render as clickable
buttons, with customizable tooltips and icons, which will open a dialog when clicked, passing
along all config options related to the selected wizard
- The new 'WizardEditor' will render inside the dialog. It will display all general config
options of the wizard, and will then render a row per input. Inputs have their own descriptions
and validation rules embedded (taken from config). Reset and Cancel buttons are self-explanatory.
The save button will run validation on all inputs, and on successful validation will emit a 'save'
event to the parent component ('NodeShapeEditor'), also passing along all entered input values.
- On detecting a 'save' event from a wizard, the 'NodeShapeEditor' will:
- receive the input values and declare them as 'wizardData'
- add the node ID of the current record to the 'wizardData' under the 'pid' field, which is how
the record can be referenced inside the TTL template
- pass 'wizardData' to the existing 'fillStringTemplate' utility function to render valid TTL
output
- pass the TTL to 'rdfDS.parseTTLandDedup(newTTL)' that outputs quads and adds them to the graph
store
- 'rdfDS.parseTTLandDedup(newTTL)' returns all the quads that were parsed and added to the graph
store. These are now process individually. Importantly, if an added quad has a subject value that
is identical
to the current node ID, we delete it from the graph store, because it uses a nonsense named node
(the node ID of the record, which is not reproducibly identical to the record PID). However, we
also add the quad's object to the 'formData' under the index of the current node and the quad's
predicate, in order to keep linkage to the TTL-parsed quads. Importantly, the existing standard
functionality that runs when saving a form (for record creation or editing) will then take care
of adding the correct quads to the graph store to replace those that were deleted.
- Continuing with the individual processing of quads that were parsed from TTL and added to the graph
store, if an added quad has a subject value that is NOT identical to the current node ID, AND it
is a named node, this means that a new record has been added to the graph store and it is therefore
eligible for submission. This is added to 'savedNodes' and 'nodesToSubmit', as well as a separate
'NodeShapeEditor'-specific tracker of all wizard-added quads.
- Garbage cleanup is also necessary in the case where quads were added to the graph store by a wizard
but the form was then subsequently cancelled. To deal with this, 'NodeShapeEditor' registers a form
cancel handler via the existing 'registerHandler' functionality, which will delete all the relevant
quads.

Lastly, for improved UI the headings of 'property groups' in the 'NodeShapeEditor' have been
removed. This is in anticipation of the complete removal of parent-class-based grouping of
properties inside the 'NodeShapeEditor'.