Document the behaviour of `InstancesSelectEditor` #155

New issue

Open

opened 2025-07-23 19:49:39 +00:00 by jsheunis · 1 comment

jsheunis commented

2025-07-23 19:49:39 +00:00

(Migrated from github.com)

With the work being done on https://github.com/psychoinformatics-de/shacl-vue/issues/127, the developed ShaclORClassEditor is turning out to share many common behaviour and code with InstancesSelectEditor. It could well turn out that a common abstraction can be created to feed these two components. The form that it will take (base components and/or composables) is yet to be determined.

In the mean time, it would be very useful to have a clear description of the (common) behaviour of these components. They are quite complicated, and having a source to go back to during further development will be extremely helpful.

Some initial notes:

Commonalities

If the component has a populated modelvalue on mounting, the corresponding record for this modelvalue has to be fetched, if using dumpthings service.
Fetching a next page of records should happen when the scroller reaches the last item in the dropdown. While fetching, the circular loader should display to indicate data fetching in progress.

Differences

Component design and appearance:
- InstancesSelectEditor: a single dropdown containing a list of records to select from; and a button to add a new record of the associated class or subclasses.
- ShaclORClassEditor: a first dropdown to select the data type from a list of options (hence "OR"), then afterwards a dropdown containing a list of records (of the selected data type) to select from;
When to fetch the first page of records:
- InstancesSelectEditor: fetches first page of records when the user clicks on the dropdown to start scrolling.
- ShaclORClassEditor: fetched first page of records when the user selects the data type from the list of options, which then makes the dropdown component appear; i.e. before the user clicks on the dropdown to start scrolling
Ability to add new items of the class and subclasses:
- InstancesSelectEditor: yes
- ShaclORClassEditor: no (this was a design decision, to simplify the component; it was thought that a new item could always be added by selecting the relevant class on the main data type panel and opening a form to create a new record; this decision might be revisited in future)

With the work being done on https://github.com/psychoinformatics-de/shacl-vue/issues/127, the developed `ShaclORClassEditor` is turning out to share many common behaviour and code with `InstancesSelectEditor`. It could well turn out that a common abstraction can be created to feed these two components. The form that it will take (base components and/or composables) is yet to be determined. In the mean time, it would be very useful to have a clear description of the (common) behaviour of these components. They are quite complicated, and having a source to go back to during further development will be extremely helpful. Some initial notes: ### Commonalities 1. If the component has a populated modelvalue on mounting, the corresponding record for this modelvalue has to be fetched, if using dumpthings service. 2. Fetching a next page of records should happen when the scroller reaches the last item in the dropdown. While fetching, the circular loader should display to indicate data fetching in progress. ### Differences 1. Component design and appearance: - `InstancesSelectEditor`: a single dropdown containing a list of records to select from; and a button to add a new record of the associated class or subclasses. - `ShaclORClassEditor`: a first dropdown to select the data type from a list of options (hence "OR"), then afterwards a dropdown containing a list of records (of the selected data type) to select from; 2. When to fetch the first page of records: - `InstancesSelectEditor`: fetches first page of records when the user clicks on the dropdown to start scrolling. - `ShaclORClassEditor`: fetched first page of records when the user selects the data type from the list of options, which then makes the dropdown component appear; i.e. _before_ the user clicks on the dropdown to start scrolling 3. Ability to add new items of the class and subclasses: - `InstancesSelectEditor`: yes - `ShaclORClassEditor`: no (this was a design decision, to simplify the component; it was thought that a new item could always be added by selecting the relevant class on the main data type panel and opening a form to create a new record; this decision might be revisited in future)

jsheunis commented

2025-11-12 10:55:18 +00:00

(Migrated from github.com)

The above is not a problem anymore, since the ShaclORClassEditor now fully depends on and instantiates the InstancesSelectEditor.

However, because of the complexity of the InstancesSelectEditor and the fact that it is used by other components, it is likely still a good idea to document it.

The above is not a problem anymore, since the `ShaclORClassEditor` now fully depends on and instantiates the `InstancesSelectEditor`. However, because of the complexity of the `InstancesSelectEditor` and the fact that it is used by other components, it is likely still a good idea to document it.