Authority lookup webcomponent

perrauda commented 1 year ago

Goal

A webcomponent geov-authority-lookup which we can lookup URI entities from authority files (Wikidata and GND)

Spec

Two webcomponents: geov-authority-lookup and geov-authority-lookup-explorer This will use lobid (for gnd) and SPARQL (for Wikidata). See Confluence documentation.

geov-authority-lookup-explorer

It's just a mini webcomponent which only a certain number of best occurences from a result of API can be display.

Mockup (The 'Open' button will be 'clear' and accompanied by an 'open' button)

Features: With three buttons, we can copy, select or access the uri.

Select: The user can select an item. This emits the selected URI in an event on geov-authority-lookup. Open: The user can open the website of the item in a new browser tab. Copy: The user can copy the URI to the clipboard. (not available by default)

Inputs:

api (e.g. 'wikidata' or 'gnd')
keywords
type (can be null)
nbOccurencesMax (by default: 5) the number of occurences on display
listButtons (by default ['select', 'open']) (other possible value in this list: 'copy')

geov-authority-lookup

It's a webcomponent which the previous webcomponent can be used there. The webcomponent will mainly be completed with a search field, a type selection and a button.

Mockup

On mobile

Inputs

list of type (Person, Place, Group to start)
list of authority we want use (by default, 'gnd', 'wikidata')

Examples of data with API

Wikidata:

We can use item & name.

GND (lobid) https://lobid.org/gnd/search?q=Johan,Kepler&filter=type:Person&format=json:preferredName

Returns (partial data):


    "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Portrait%20of%20Johannes%20Kepler.jpg?width=100",
    "label": "Kepler, Johannes",
    "id": "https://d-nb.info/gnd/118561448",
    "category": "Individualisierte Person"

We can use label & id.

IdRef additional integration: idref https://documentation.abes.fr/aideidrefdeveloppeur/index.html#UtiliserApiSolr

https://www.idref.fr/Sru/Solr?q=geogname_t:(Lyon)&start=0&rows=5&indent=on&sort=score%20desc&fl=id,ppn_z,affcourt_z&version=2.2&wt=json

We can use ppn_z (for concatenate URI, no alternative) & affcourt_z (label)

joschne commented 1 year ago

I like this spec @perrauda ! The UI is clean and clear. I like the splitting in two components.

These are my considerations. If you agree with them, please adapt the spec accordingly, otherwise let's discuss it here.

Requirements

Must have actions per item:

Select: The user can select an item. This emits the selected URI in an event on geov-authority-lookup.
Open: The user can open the website of the item in a new browser tab.

Nice to have action per item:

Copy: The user can copy the URI to the clipboard.

We could have three inputs on geov-authority-lookup to enable / disable each of the three actions. By default, Select and Open should be enabled.

Design

In the mockup of eov-authority-lookup-explorer the list items currently have two actions: copy and open. Instead of icons I suggest to use buttons: https://ionicframework.com/docs/api/item#buttons-in-items (The icon is used if the whole item is clickable: https://ionicframework.com/docs/api/item#clickable-items or just as icon without click action: https://ionicframework.com/docs/api/item#icons-in-items)

Responsive Design

How willl the component look on mobile?

WikiData API

I don't really like that you have to parse html from the snippet and that you have to concatenate the title to create the URI. If you think, the Wikidata Query Service is as well a good option, I'd prefer it. Then we are already in the world of LOD standards, which seems more reliable to me in terms of long term support and it makes it very flexible for further developments of the component. In short, unless you have clear arguments for Cirrus, I opt for SPARQL (Wikidata Query Service).

perrauda commented 1 year ago

Thank you, the specifications have been modified following your comment. Is it ok? On my side OK for SPARQL, I will study it a little more in the meantime.

joschne commented 1 year ago

Perfect.

A thought: Both buttons now have the same style. I think, select is the primary action, open the secondary. To reflect this hierarchy visually, you could set the fill of "Open" to "clear". In addition, you could add a open icon (the one you had before) to the end of the button.

Question: What "types" would you start with? I suggest to start with Person, Place and Group. The mapping to GND and Wikidata Types is then to be done during implementation.

perrauda commented 1 year ago

Ok for the buttons, I note that.

Types: Ok for types, we start with Person, Place and Group. List of types in GND (However several types are subclasses): https://d-nb.info/standards/elementset/gnd Wikidata it's more complicated to find a list of types, we need to find one by one I think, no problem with this three types.

In GND explorer we could see the list of types they were using (8 or 9) but the website is currently down.

joschne commented 1 year ago

Ok, spec review is finished from my side

perrauda commented 1 year ago

additional integration: idref

perrauda commented 1 year ago

@KleiolabDK Hello, the webcomponent is ready, just as you asked, and you can now do a review for the UX aspect.

Here is the doc: https://design-dev.geovistory.org/?path=/docs/data-components-authority-lookup--basic You'll find different stories, all can be tested

KleiolabDK commented 1 year ago

thank you @perrauda this looks great!

For me, the functionalities are fine.

comment 1 DK

Just two comments:

short response when clicking "select"

In order to improve the authority lookup explorer, when clicking select nothing visible happens. a small user feedback like "you have selected id1111" would be helpful.

in the authority lookup explorer, it would be good to enable "copy" by default

KleiolabDK commented 1 year ago

comment 2 DK

my comments are regarding the documentation:

describe somehwere which APIs are available for this webcomponent and how they can be called/connected (idref, gnd, wikidata)

Note: I have now seen that this is described in the selction "Component API". however, this section "Component API" is not referenced in the menu on the left. Please add it there. You can then reference to this section in the examples above.

KleiolabDK commented 1 year ago

comment 3 DK

authority lookup explorer:

it is not clear what the part "stories" is for. if not needed, better to delete it:

KleiolabDK commented 1 year ago

comment 4 DK

explain here the available buttons and what they do:

select
copy
open

KleiolabDK commented 1 year ago

comment 5 DK

elaborate a bit more how the selection of the type/class can help to refine search results (maybe with an example)

KleiolabDK commented 1 year ago

comment 6 DK

Regarding the APIs, we have currently GND, idref and wikidata. I would suggest to include the API of Geovistory Public. I am aware that this is a new requirement, but given the estimate from Alexandre that this can be done in 1 day, I think it would be great.

--- End of Review ---

joschne commented 1 year ago

comment 1 DK

Agreed:

For Select button: We add a alert("you selected "+ uri)

We activate the Copy button in the first story (Playground).

Edit Done in https://github.com/geovistory/design-system/pull/69

joschne commented 1 year ago

comment 2 DK

It is not so easy to add a link to the left. We agreed to try to make a link to the left. If it is not possible, we add a link to "Component API" to the introduction text.

Edit Added Table of contents in https://github.com/geovistory/design-system/pull/69

joschne commented 1 year ago

comment 3 DK

Since we don't need the stories of geov-authority-lookup-explorer, we delete them.

Edit Done in https://github.com/geovistory/design-system/pull/69

joschne commented 1 year ago

comment 5 DK

We add a table explaining what the type-filter does on each API:

joschne commented 1 year ago

comment 6 DK

Agreed.

We add geovistory api. In the second line of each search result we put: {class label} – {entity id}

E.g. Mozart Person – i123123

in addition we change the layout of the cards to better use space in case of different numbers of result per API.

joschne commented 1 year ago

comment 4 DK

     ...
     It is maintained by the Bibliographic Agency for Higher Education (ABES) in France.

<- ADD THE FOLLOWING TEXT HERE ->

The component has a rich API for customization and styling, see below.

Supported user actions:

Filter the authority files by search terms (full text) and type
View a ranked list of entities.
Click on one of the following buttons:
- Select: Emits the URI of the selected entity as a DOM event.
- Copy: Copies the URI of the selected entity to the clipboard.
- Open: Opens the URI of the selected entity in a new browser tab.
```
() => <GeovAuthorityLookup displayCopyBtn={true} displayOpenBtn={true} displaySelectBtn={true}></GeovAuthorityLookup>
```

<- ADD THE FOLLOWING TEXT HERE ->



The buttons have this behavior:
- **Select**: Emits the URI of the selected entity as a DOM event.
- **Copy**: Copies the URI of the selected entity to the clipboard.
- **Open**: Opens the URI of the selected entity in a new browser tab.

geovistory / design-system