diff --git a/README.md b/README.md index c8d4901..4f614c8 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,74 @@ -## Dataverse External Vocabulary Management +# Dataverse External Vocabulary Management -Dataverse supports the use of third-party vocabulary services through a generic external vocabulary support mechanism, service-specific scripts, and a custom json configuration setting that allows specification of how fields in Dataverse metadatablocks are to be associated with specific services and vocabularies. +Dataverse supports the use of third-party vocabulary and persistent identifier (PID) services through a generic external vocabulary support mechanism that allows service-specific scripts, and field-specific json configurations added via a Dataverse setting that allows specification of how fields in Dataverse metadatablocks are to be associated with specific services and vocabularies. -This repository contains several usable scripts and example materials that demonstrate how to configure Dataverse to leverage them. +For example, instead of a plain text type in, one could select a term from multiple vocabularies: + +Select a vocabulary + +![Input2](https://github.com/user-attachments/assets/e984acc4-de04-49f7-8397-a7f2c4fc70f5) + +and then a term + +![Input3](https://github.com/user-attachments/assets/de48f382-4d74-4e75-aa29-a76853e88eba) + +and have them displayed as a link to the remote site defining the term: + +![Display2](https://github.com/user-attachments/assets/27aab9fe-c876-4ab6-8d74-eb6cc29274c4) + +Or, with [additions planned for Dataverse 6.4](https://github.com/IQSS/dataverse/pull/10712), one could replace the four author related fields with selectors for [ORCID](https://orcid.org) (people) and [ROR](https://ror.org) (organizations) + +![Input1](https://github.com/user-attachments/assets/b0f724e1-952b-4d48-8f89-8f046d797ce8) + +which would display as entries with icons that link to the definition pages. + +![Display1](https://github.com/user-attachments/assets/67fd166e-855b-4044-8dfd-d2ae0ccbfed5) + +and can still support entering info for people/organizations who do not have ORCID or ROR entries. + +Display can also be graphical, as in displaying [Local Contexts](https://localcontexts.org/) Notices and Labels + +![image](https://github.com/user-attachments/assets/87aab5b1-6aca-49b1-8f7a-1e253932650d) + +## Repository Contents + +This repository contains scripts and example materials that demonstrate how to configure Dataverse to leverage them. They are a mixture of initial proofs-of-concept, demonstrations of alternative approaches, and some that are potentially mature enough for production use (although the latter often require later versions of Dataverse which have extensions/bug fixes for the underlying mechanism. Documentation in the /examples subdirectory provides additional details for specific scripts and configuration for specific fields. + +It also contains a [JSON Schema that can be used to validate configuration files](https://github.com/gdcc/dataverse-external-vocab-support/blob/main/examples/config/demo/CVocConf.schema.json). + +## Scripts in Production + +The following scripts/config files are being used in production (or testing) at one or more Dataverse Sites + +* **ORCID and ROR for Dataset authors** - see [https://github.com/gdcc/dataverse-external-vocab-support/examples/authorIDandAffilationUsingORCIDandROR.md](https://github.com/gdcc/dataverse-external-vocab-support/examples/authorIDandAffilationUsingORCIDandROR.md) + + +* **Integration with [https://localcontexts.org](https://localcontexts.org)** (on [https://demo.dataverse.org](https://demo.dataverse.org) using the LocalContexts Sandbox) - see [https://github.com/gdcc/dataverse-external-vocab-support/tree/main/packages/local_contexts](https://github.com/gdcc/dataverse-external-vocab-support/tree/main/packages/local_contexts) + +## Deployment + +In general there are three steps to add interaction with a vocabulary or PID service to Dataverse: + +* Identify the metadata field to be enhanced. This can be a field in an existing block, or one in a custom block that you install (there are some custom blocks in this repo for various scripts). As with any custom block, you must [install it in Dataverse](https://guides.dataverse.org/en/latest/admin/metadatacustomization.html#metadata-block-setup), enable the use of this new block in your Dataverse collection (e.g. Use the Edit/General Information menu item, /Metadata Fields section to add the block/specific fields.) and add any desired terms from the example block to the Browse/Search Facets list (same Edit/General Information menu item) +* Create a configuration file and [submit it as the :CVocConf setting value](https://guides.dataverse.org/en/latest/installation/config.html#cvocconf) for your Dataverse. It is probably easiest to modify the example scripts here. Nominally you would only need to change the metadata field the script will enhance and the URL for the location of the script. You should validate your file against the provided [JSON Schema](https://guides.dataverse.org/en/latest/installation/config.html#cvocconf) to avoid errors that can break the Dataverse page display. +* Deploy the script(s) to a local location that matches the URL you chose in the config file. It is possible to access the scripts from the github.io URLs used in the example config files here, but this is not recommended as we are not yet versioning the scripts and assuring that the version in the repository will not change. + +To deploy scripts to multiple fields, you need to add one section (JSON Object) per field/script combo to the array in your config file. + +## How It All Works + +The basic idea of the Dataverse External Vocabulary mechanism is to simplify adding and displaying controlled terms and PIDs as metadata. As far as Dataverse is concerned, all that is happening is that a term or PID URI is being entered into a text field and Dataverse then stores and displays the term/PID URI. The interesting part is that a JavaScript is taking over Dataverse's text input and text display to instead provide support such as a type-ahead lookup from a vocabulary/PID service and, on the diplay side, displaying the human-readable name of associated with the term/PID, and potentially additional metadata about the term/PID, rather than the raw URI. + +The scripts know which fields to manage based on some invisible data-cvoc-* attributes Dataverse adds to the page's HTML. Dataverse has a flexible configuration mechanism to allow admins to specify which fields should be associated with which scripts, but, in other repositories, these associations could be static. For example, [this simple static example page](examples/staticOrcidAndRorExample.html) shows the ORCID and ROR scripts associated with two input and two display fields. You can look at the page source to see the additional attributes in the HTML that make this work. + +There's more of course. When a repository already has separate subfields for names and identifiers, scripts can be written to fill in both. If the underlying vocabulary/PID service supports multiple vocabularies, or has an advanced search mechanism, the scipts can be written to let you select which vocabulary to use or provide an advanced search interface. If there's a field where you want to be able to handle free text as well as controlled terms/PIDs, scripts can support that as well. Dataverse also includes a mechanism to allow metadata about the terms/PIDs to be captured, making it possible to provide internationalization for search (i.e. allowing search in your language for a term), include organization acronyms in exported metadata formats, etc. Fortunately, most of this complexity is handled by script/config example developers and Dataverse admins just need to select which ones to install. + +For further details, see [James D. Myers, & Vyacheslav Tykhonov. (2023). A Plug-in Approach to Controlled Vocabulary Support in Dataverse.](https://doi.org/10.5281/zenodo.8133723) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8133723.svg)](https://doi.org/10.5281/zenodo.8133723) -Example Setup: -To enable external voabulary support on the example metadata block provided you need to: -* Install the custom metadata block -* Update your solr schema to include the custom fields -* Set the :CVocConf setting - use the /examples/config/cvoc-conf.json as the value -* Enable the use of this new block in your test Dataverse collection (e.g. Use the Edit/General Information menu item, /Metadata Fields section to add the block/specific fields.) -* Add any desired terms from the example block to the Browse/Search Facets list (same Edit/General Information menu item) -Only the third step is specific to enabling external vocabulary support. The others are just the standard steps for installing a new metadata block in Dataverse. -If you create your own :CVocConf setting value (i.e. to manage other fields), you can use the /examples/config/CVocConf.schema.json file to validate your syntax. ### Packages diff --git a/examples/affiliation.md b/examples/affiliation.md index 259fb7e..91624d6 100644 --- a/examples/affiliation.md +++ b/examples/affiliation.md @@ -2,7 +2,7 @@ The affiliation example illustrates a lookup in ROR.org for the author affiliati Two files comprise this example: -- examples/config/affiliation.json : the configuration file that needs to be uploaded in the :CVocConf setting +- examples/config/demo/affiliation.json : the configuration file that needs to be uploaded in the :CVocConf setting - scripts/affiliation.js : the Javascript file that modifies standard Dataverse behaviour diff --git a/examples/authorIDandAffilationUsingORCIDandROR.md b/examples/authorIDandAffilationUsingORCIDandROR.md new file mode 100644 index 0000000..ff52838 --- /dev/null +++ b/examples/authorIDandAffilationUsingORCIDandROR.md @@ -0,0 +1,35 @@ +## Dataverse Author Field Example + +This example manages the author field (the name, idType, Identifier, and affiliation child fields), providing (ORCID)[https://orcid/org] and (ROR)[https://ror.org] lookup while also allowing free text entries (for entities that don't have these identifiers) and manual entry of alternate identifiers for authors. + +This example requires the changes being added to Dataverse in (PR #10712)[https://github.com/IQSS/dataverse/pull/10712] expected in v6.4. + +This example requires several files: + +- examples/config/authorsOrcidAndRor.json : the configuration file that needs to be uploaded in the :CVocConf setting + +- scripts/people.js : the Javascript file that provides ORCID support, +- scripts/ror.js : the Javascript file that provides ROR support, +- scripts/cvocutil.js : a Javascript file with common methods used by both scripts, + +(These scripts also use jquery and select2 which are already included in Dataverse). + +### How to install: + +Minimal: + +- load the authorsOrcidAndRor.json file in the :CVocConf setting using the [Dataverse API](https://guides.dataverse.org/en/latest/installation/config.html?highlight=cvocconf). e.g. using curl: `curl -X PUT --upload-file authorsOrcidAndRor.json http://localhost:8080/api/admin/settings/:CVocConf`. + +- Alternately, add the two JSON Objects in the top level JSON Array in authorsOrcidAndRor.json to you existing :CVocConf setting file (for installations that are deploying other CVoc scripts already) + +- refresh your browser page. That's it. You should see displays like those shown in this repo's README file. + +Production: +- Also copy the three script files to a local website and adjust the URLs in authorsOrcidAndRor.json that invoke them to use your local copies. This assures that changes in this repository will not automatically be used on your site. +- Adapt your CSS styling to improve how well the interfaces created by the script match your custom style. + +### Interesting Features +- Searches can be done by person/organization name, but can also use other metadata, e.g. a person's email address or an originization in their employment or education history in their ORCID profile, or the acronym of an organization (entry must be at least 3 letters) +- Once an ORCID or ROR has been used in a given browser, that entry will appear at the top of the list as soon as it is one of the results returned from the service. This makes it easier to find a commonly used entry when there are similar ones. +- The people.js script understands that Dataverse has separate idType and Identifier fields for authors. When a free text entry is added as a name (i.e. there is no associated ORCID), the script will restore the idType and Identifier subfields so that an Identifier of some other type that Dataverse supports can be entered. +- Both ORCID and ROR icons are displayed with entries. They link to the person's/organization's page at ORCID/ROR. diff --git a/examples/authors.md b/examples/authors.md index 5484571..68efe7a 100644 --- a/examples/authors.md +++ b/examples/authors.md @@ -1,31 +1,31 @@ -The authors example uses the external vocabularies mechanism to implement a simple lookup and copy-and-paste functionality for the authors fields (name, affiliation, indentification scheme and number). It is different from the other examples as it does not store URLs to the external vocabulary, but instead copies the data directly into the dataverse metadata fields. The link with the vocabulary URI is therefore not persisted. +The authors example uses the external vocabularies mechanism to implement a simple lookup and copy-and-paste functionality for the authors fields (name, affiliation, identification scheme and number). It is different from the other examples as it does not store URLs to the external vocabulary, but instead copies the data directly into the dataverse metadata fields. The link with the vocabulary URI is therefore not persisted. There are several reasons why we implemented it like this: -- we did not want to expose the personel data unprotected to the public internet. By copying the data instead of the URL, we can open the vocabulary only to the IP ranges that need access to dataset metadata editing, which for our institution is esentially on-premis or via VPN. The vocabulary server is no longer needed when the dataset metadata is published and accessed publicly. +- we did not want to expose the personal data unprotected to the public internet. By copying the data instead of the URL, we can open the vocabulary only to the IP ranges that need access to dataset metadata editing, which for our institution is essentially on-premis or via VPN. The vocabulary server is no longer needed when the dataset metadata is published and accessed publicly. -- the data in the vocabulary will rarely change, it will only be expanded. The risk of author information getting outdated is very low. And even if so, it is likely that it would be better to leave the old metadata alone. +- the data in the vocabulary will rarely change, it will only be expanded. The risk of author information getting out-dated is very low. And even if so, it is likely that it would be better to leave the old metadata alone. -- we implemented it as a prototype for other metadata fields where the vocabulary data will most certainly change and we do not want these changes to percollate into the metadata of existing datasets. One such field is our faculty or department field. Departments splitting and merging do occur fairly regularly and we want the metadata to reflect the organisational entity as it was when the dataset was created. While this can be achieved in external vocabularies with deprecated entries, the extra complexity of maintaining the external vocabulary for a fairly simple list is not worth it. We will just change the list as we go and leave the existing data alone. +- we implemented it as a prototype for other metadata fields where the vocabulary data will most certainly change and we do not want these changes to percolate into the metadata of existing datasets. One such field is our faculty or department field. Departments splitting and merging do occur fairly regularly and we want the metadata to reflect the organiational entity as it was when the dataset was created. While this can be achieved in external vocabularies with deprecated entries, the extra complexity of maintaining the external vocabulary for a fairly simple list is not worth it. We will just change the list as we go and leave the existing data alone. To illustrate the example for our authors lookup there are 2 files provided: -- examples/config/authors.json : the configuration file that needs to be uploaded in the :CVocConf setting +- examples/config/demo/authors.json : the configuration file that needs to be uploaded in the :CVocConf setting - scripts/authors.js : the Javascript file that modifies standard Dataverse behaviour The standard authors compound fields are used, so there is no need to modify the default citation metadata block. -Note that this is a trimmed-down version of de code that we use in production. Our production version can be found in our [github repository](https://github.com/libis/rdm-covoc_server). There you will also find the implementation of a small REST server that performs the search in the background. +Note that this is a trimmed-down version of the code that we use in production. Our production version can be found in our [github repository](https://github.com/libis/rdm-covoc_server). There you will also find the implementation of a small REST server that performs the search in the background. -The JSON configuration file has most fields empty, but as they are all required, they need to be present in the configuration file. The `field-name` and `term-uri-field` have both been set to `authorName`. Only the field `field-name` should be set for this to work, but as I found out the hard way, the external vocabulary code insits that the `term-uri-field` also points to a valid metadata field. Theoretically, this means that the external vocabulary code that looks up values externally could be triggered if an URI is filled in in the `authorName` field, but it is fairly safe to asume that that will not be the case during normal use. +The JSON configuration file has most fields empty, but as they are all required, they need to be present in the configuration file. The `field-name` and `term-uri-field` have both been set to `authorName`. Only the field `field-name` should be set for this to work, but as I found out the hard way, the external vocabulary code insists that the `term-uri-field` also points to a valid metadata field. Theoretically, this means that the external vocabulary code that looks up values externally could be triggered if an URI is filled in in the `authorName` field, but it is fairly safe to assume that that will not be the case during normal use. -The `js-url` field in the configuration file points to the location where the JavaScript file is located. Since we already use an Apache frontend server to enable the Shibboleth logins, we decided to reverse-proxy the JavaScript file there as well. The other fields are emtpy and have no influence on our code. +The `js-url` field in the configuration file points to the location where the JavaScript file is located. Since we already use an Apache frontend server to enable the Shibboleth logins, we decided to reverse-proxy the JavaScript file there as well. The other fields are empty and have no influence on our code. The JavaScript file contains three parts: - first of all code that is triggered each time the page is loaded and each time an author compound field set is added or deleted. That piece of code is responsible for creating the HTML code for a modal dialog box with search box and table with results. It also puts a search button next to each authorName input field that will display the dialog box. -- the `authorsQuery` function performs a call to a server that will search the given string in the database and return the data for the matches found. The code asumes this to be a simeple REST server that returns JSON data. The server itself in our case uses a Solr index to query and retrieve the data. Again, for security reasons we did not want to expose the Solr server directly beyond the server itself, so a simple REST server in front of it sanitizes the queries and protects the Solr index from being abused. +- the `authorsQuery` function performs a call to a server that will search the given string in the database and return the data for the matches found. The code assumes this to be a simple REST server that returns JSON data. The server itself in our case uses a Solr index to query and retrieve the data. Again, for security reasons we did not want to expose the Solr server directly beyond the server itself, so a simple REST server in front of it sanitizes the queries and protects the Solr index from being abused. -- the `importAuthorData` function is triggered when a user selects one of the search results and is responsible for copying the JSON data into the input fields on the dataset metadata form. Most of it is pretty straightforward code looking for the input fields in the form and setting the values, except for the part where the `identifierScheme` has to be filled in. The dropdown box consists of multiple elements that have to be changed in sync and it took a while to figure that out. This is also the weakest point in the code, as translations could modify any displayed text and thus could break the code that relies on the text `ORCID` to be present in the dropdown box. In this case that is something we have full contol of, but be warned when porting this code to other fields. \ No newline at end of file +- the `importAuthorData` function is triggered when a user selects one of the search results and is responsible for copying the JSON data into the input fields on the dataset metadata form. Most of it is pretty straightforward code looking for the input fields in the form and setting the values, except for the part where the `identifierScheme` has to be filled in. The dropdown box consists of multiple elements that have to be changed in sync and it took a while to figure that out. This is also the weakest point in the code, as translations could modify any displayed text and thus could break the code that relies on the text `ORCID` to be present in the dropdown box. In this case that is something we have full control of, but be warned when porting this code to other fields. \ No newline at end of file diff --git a/examples/config/authorsOrcidAndRor.json b/examples/config/authorsOrcidAndRor.json new file mode 100644 index 0000000..7e8caad --- /dev/null +++ b/examples/config/authorsOrcidAndRor.json @@ -0,0 +1,75 @@ +[ + { + "field-name": "authorAffiliation", + "term-uri-field": "authorAffiliation", + "js-url": ["https://qualitativedatarepository.github.io/dataverse-external-vocab-support/scripts/ror.js","https://qualitativedatarepository.github.io/dataverse-external-vocab-support/scripts/cvocutils.js"], + "protocol": "ror", + "retrieval-uri": "https://api.ror.org/organizations/{0}", + "allow-free-text": true, + "prefix": "https://ror.org/", + "managed-fields": {}, + "languages":"en", + "vocabs": { + "rors": { + "uriSpace": "https://ror.org/" + } + }, + "retrieval-filtering": { + "@context": { + "termName": "https://schema.org/name", + "scheme": "http://www.w3.org/2004/02/skos/core#inScheme", + "lang": "@language", + "content": "@value" + }, + "scheme": { + "pattern": "http://www.grid.ac/ontology/" + }, + "termName": { + "pattern": "{0}", + "params": ["/name"] + }, + "@type": { + "pattern": "https://schema.org/Organization" + } + } + }, + { + "field-name": "author", + "term-uri-field": "authorIdentifier", + "js-url": ["https://qualitativedatarepository.github.io/dataverse-external-vocab-support/scripts/people.js","https://qualitativedatarepository.github.io/dataverse-external-vocab-support/scripts/cvocutils.js"], + "protocol": "orcid", + "retrieval-uri": "https://pub.orcid.org/v3.0/{0}/person", + "allow-free-text": true, + "prefix": "https://orcid.org/", + "managed-fields": { + "personName":"authorName", + "idType":"authorIdentifierScheme" + }, + "languages":"en", + "vocabs": { + "orcid": { + "uriSpace": "https://orcid.org/" + } + }, + "retrieval-filtering": { + "@context": { + "personName": "https://schema.org/name", + "scheme": "http://www.w3.org/2004/02/skos/core#inScheme" + }, + "personName": { + "pattern": "{0}, {1}", + "params": ["/name/family-name/value", "/name/given-names/value"] + }, + "@id": { + "pattern": "{0}", + "params": ["@id"] + }, + "scheme": { + "pattern": "ORCID" + }, + "@type": { + "pattern": "https://schema.org/Person" + } + } + } +] diff --git a/examples/config/affiliation.json b/examples/config/demos/affiliation.json similarity index 100% rename from examples/config/affiliation.json rename to examples/config/demos/affiliation.json diff --git a/examples/config/authors.json b/examples/config/demos/authors.json similarity index 100% rename from examples/config/authors.json rename to examples/config/demos/authors.json diff --git a/examples/config/cvoc-conf.json b/examples/config/demos/cvoc-conf.json similarity index 100% rename from examples/config/cvoc-conf.json rename to examples/config/demos/cvoc-conf.json diff --git a/examples/config/cvoc-conf.singlevocab.json b/examples/config/demos/cvoc-conf.singlevocab.json similarity index 100% rename from examples/config/cvoc-conf.singlevocab.json rename to examples/config/demos/cvoc-conf.singlevocab.json diff --git a/examples/config/grantNumberAgencyFundreg.json b/examples/config/demos/grantNumberAgencyFundreg.json similarity index 100% rename from examples/config/grantNumberAgencyFundreg.json rename to examples/config/demos/grantNumberAgencyFundreg.json diff --git a/examples/config/keywordExample.json b/examples/config/demos/keywordExample.json similarity index 100% rename from examples/config/keywordExample.json rename to examples/config/demos/keywordExample.json diff --git a/examples/config/rorAuthAffiliation.json b/examples/config/demos/rorAuthAffiliation.json similarity index 96% rename from examples/config/rorAuthAffiliation.json rename to examples/config/demos/rorAuthAffiliation.json index 7bade9b..80c6c95 100644 --- a/examples/config/rorAuthAffiliation.json +++ b/examples/config/demos/rorAuthAffiliation.json @@ -1,36 +1,36 @@ -[ - { - "field-name": "authorAffiliation", - "term-uri-field": "authorAffiliation", - "js-url": ["/cvoc/js/ror.js","/cvoc/js/cvocutils.js"], - "protocol": "ror", - "retrieval-uri": "https://api.ror.org/organizations/{0}", - "allow-free-text": true, - "prefix": "https://ror.org/", - "managed-fields": {}, - "languages":"", - "vocabs": { - "rors": { - "uriSpace": "https://ror.org/" - } - }, - "retrieval-filtering": { - "@context": { - "termName": "https://schema.org/name", - "scheme": "http://www.w3.org/2004/02/skos/core#inScheme", - "lang": "@language", - "content": "@value" - }, - "scheme": { - "pattern": "http://www.grid.ac/ontology/" - }, - "termName": { - "pattern": "{0}", - "params": ["/name"] - }, - "@type": { - "pattern": "https://schema.org/Organization" - } - } - } +[ + { + "field-name": "authorAffiliation", + "term-uri-field": "authorAffiliation", + "js-url": ["/cvoc/js/ror.js","/cvoc/js/cvocutils.js"], + "protocol": "ror", + "retrieval-uri": "https://api.ror.org/organizations/{0}", + "allow-free-text": true, + "prefix": "https://ror.org/", + "managed-fields": {}, + "languages":"", + "vocabs": { + "rors": { + "uriSpace": "https://ror.org/" + } + }, + "retrieval-filtering": { + "@context": { + "termName": "https://schema.org/name", + "scheme": "http://www.w3.org/2004/02/skos/core#inScheme", + "lang": "@language", + "content": "@value" + }, + "scheme": { + "pattern": "http://www.grid.ac/ontology/" + }, + "termName": { + "pattern": "{0}", + "params": ["/name"] + }, + "@type": { + "pattern": "https://schema.org/Organization" + } + } + } ] \ No newline at end of file diff --git a/examples/config/depositorOrcid.json b/examples/config/depositorOrcid.json new file mode 100644 index 0000000..76fea8b --- /dev/null +++ b/examples/config/depositorOrcid.json @@ -0,0 +1,38 @@ +[ + { + "field-name": "depositor", + "term-uri-field": "depositor", + "js-url": ["https://qualitativedatarepository.github.io/dataverse-external-vocab-support/scripts/people.js","https://qualitativedatarepository.github.io/dataverse-external-vocab-support/scripts/cvocutils.js"], + "protocol": "orcid", + "retrieval-uri": "https://pub.orcid.org/v3.0/{0}/person", + "allow-free-text": true, + "prefix": "https://orcid.org/", + "managed-fields": {}, + "languages":"en", + "vocabs": { + "orcid": { + "uriSpace": "https://orcid.org/" + } + }, + "retrieval-filtering": { + "@context": { + "personName": "https://schema.org/name", + "scheme": "http://www.w3.org/2004/02/skos/core#inScheme" + }, + "personName": { + "pattern": "{0}, {1}", + "params": ["/name/family-name/value", "/name/given-names/value"] + }, + "@id": { + "pattern": "{0}", + "params": ["@id"] + }, + "scheme": { + "pattern": "ORCID" + }, + "@type": { + "pattern": "https://schema.org/Person" + } + } + } +] diff --git a/examples/config/grantNumberAgencyRor.json b/examples/config/grantNumberAgencyRor.json new file mode 100644 index 0000000..078eaed --- /dev/null +++ b/examples/config/grantNumberAgencyRor.json @@ -0,0 +1,36 @@ +[ + { + "field-name": "grantNumberAgency", + "term-uri-field": "grantNumberAgency", + "js-url": ["https://qualitativedatarepository.github.io/dataverse-external-vocab-support/scripts/ror.js","https://qualitativedatarepository.github.io/dataverse-external-vocab-support/scripts/cvocutils.js"], + "protocol": "ror", + "retrieval-uri": "https://api.ror.org/organizations/{0}", + "allow-free-text": true, + "prefix": "https://ror.org/", + "managed-fields": {}, + "languages":"", + "vocabs": { + "ror": { + "uriSpace": "https://ror.org/" + } + }, + "retrieval-filtering": { + "@context": { + "termName": "https://schema.org/name", + "scheme": "http://www.w3.org/2004/02/skos/core#inScheme", + "lang": "@language", + "content": "@value" + }, + "scheme": { + "pattern": "http://www.grid.ac/ontology/" + }, + "termName": { + "pattern": "{0}", + "params": ["/name"] + }, + "@type": { + "pattern": "https://schema.org/Organization" + } + } + } +] \ No newline at end of file diff --git a/examples/staticOrcidAndRorExample.css b/examples/staticOrcidAndRorExample.css new file mode 100644 index 0000000..79a0975 --- /dev/null +++ b/examples/staticOrcidAndRorExample.css @@ -0,0 +1,40 @@ +/* Some minimal styling for the static example. */ +h1 { + text-align: center; +} +#select2-drop{ + width: 400px !important; +} +.select2-container { +min-width: 400px!important; +} +.select2-container .select2-selection--single .select2-selection__rendered { + width:100%; + vertical-align:middle; +} +img { + vertical-align: middle; +} +div { + height:40px; + width:100%; + margin-bottom:30px; +} +.select2-container { + display:block!important; +} +.select2-container .select2-selection--single .select2-selection__rendered { + display:inline-block!important; + max-width:85%; + padding-right:5px!important; +} +.select2-selection__clear, .select2-selection__rendered { + vertical-align: -webkit-baseline-middle; +} +.select2-results ul > li { + font-weight:400; + font-size:14px; +} +.select2-rendered__match { + font-weight:600; +} diff --git a/examples/staticOrcidAndRorExample.html b/examples/staticOrcidAndRorExample.html new file mode 100644 index 0000000..f579d3c --- /dev/null +++ b/examples/staticOrcidAndRorExample.html @@ -0,0 +1,103 @@ + + + + + + + + + + + + + + + +

Quick Static ORCID/ROR Demonstrator

+

This static HTML page demonstrates how the scripts in this repository are designed to attach to specific fields via + the use of data-cvoc-* attributes embedded in the page. Once you've viewed the page and tried it out, take a look at the + page source to see the added attributes. With Dataverse, these attributes are automatically generated based + on the :CVocConf setting. For other repositories - if you can add these attributes to your page, you can use the scripts as well. + Note - the page is truly static and the inputs and outputs are not connected (if someone wants to add some Javascript to update + the display entries when new inputs are selected, feel free!)

+

Input

+
+ +
+ +
+
+
+ + +
+
+

Display

+
+
+ Person 1: + https://orcid.org/0000-0001-8462-650X +   + https://ror.org/014trz974 +
+
+ Person 2: + Myers, Not Jim +   + Not QDR +
+
+
+ + diff --git a/packages/local_contexts/local_contexts.js b/packages/local_contexts/local_contexts.js index 9fd7cc9..64a1759 100644 --- a/packages/local_contexts/local_contexts.js +++ b/packages/local_contexts/local_contexts.js @@ -80,7 +80,7 @@ async function cvoc_lc_editProject() { const baseUrl = `${serviceUrl}projects/` const selectId = "LCAddSelect_" + num; projectInput.after( - ''); if (projectInput[0].value !== "") { const project = await cvoc_lc_LoadOrFetch(projectInput[0].value, serviceUrl) // console.log(project) @@ -150,6 +150,24 @@ async function cvoc_lc_editProject() { cache: true } }) + + //Add a tab stop and key handling to allow the clear button to be selected via tab/enter + const observer = new MutationObserver((mutationList, observer) => { + var button = $('#' + selectId).parent().find('.select2-selection__clear'); + button.attr("tabindex","0"); + button.on('keydown',function(e) { + if(e.which == 13) { + $('#' + selectId).val(null).trigger('change'); + } + }); + }); + + observer.observe($('#' + selectId).parent()[0], { + childList: true, + subtree: true } + ); + + // If the input has a value already, format it the same way as if it // were a new selection var id = projectInput.val(); @@ -176,6 +194,12 @@ async function cvoc_lc_editProject() { $('#' + selectId).on('select2:clear', function(e) { $("input[data-lc='" + num + "']").attr('value', ''); }); + //When the field is selected via keyboard, move the focus and cursor to the new input + $('#' + selectId).on('select2:open', function(e) { + $(".select2-search__field").focus() + $(".select2-search__field").attr("id",selectId + "_input") + document.getElementById(selectId + "_input").select(); + }); } } } diff --git a/scripts/people.js b/scripts/people.js index 01a10fa..bd535fc 100644 --- a/scripts/people.js +++ b/scripts/people.js @@ -1,5 +1,6 @@ var personSelector = "span[data-cvoc-protocol='orcid']"; var personInputSelector = "input[data-cvoc-protocol='orcid']"; +var orcidPrefix = "orcid:"; $(document).ready(function() { expandPeople(); @@ -18,67 +19,88 @@ function expandPeople() { if (id.startsWith("https://orcid.org/")) { id = id.substring(18); } - //Try it as an ORCID (could validate that it has the right form and even that it validates as an ORCID, or can just let the GET fail - $.ajax({ - type: "GET", - url: "https://pub.orcid.org/v3.0/" + id + "/person", - dataType: 'json', - headers: { - 'Accept': 'application/json' - }, - success: function(person, status) { - //If found, construct the HTML for display - var name = person.name['family-name'].value + ", " + person.name['given-names'].value; - var html = "" + name + ""; - personElement.innerHTML = html; - //If email is public, show it using the jquery popover functionality - if (person.emails.email.length > 0) { - $(personElement).popover({ - content: person.emails.email[0].email, - placement: 'top', - template: '' - }); - personElement.onmouseenter = function() { - $(this).popover('show'); - }; - personElement.onmouseleave = function() { - $(this).popover('hide'); - }; - } - //Store the most recent 100 ORCIDs - could cache results, but currently using this just to prioritized recently used ORCIDs in search results - if (localStorage.length > 100) { - localStorage.removeItem(localStorage.key(0)); - } - localStorage.setItem(id, name); - }, - failure: function(jqXHR, textStatus, errorThrown) { - //Generic logging - don't need to do anything if 404 (leave display as is) - if (jqXHR.status != 404) { - console.error("The following error occurred: " + textStatus, errorThrown); + if (id.match(/^\d{4}-\d{4}-\d{4}-(\d{4}|\d{3}X)$/) !== null) { + //Try it as an ORCID (could validate that it has the right form and even that it validates as an ORCID, or can just let the GET fail + $.ajax({ + type: "GET", + url: "https://pub.orcid.org/v3.0/" + id + "/person", + dataType: 'json', + headers: { + 'Accept': 'application/json' + }, + success: function(person, status) { + //If found, construct the HTML for display + var name = person.name['family-name'].value + ", " + person.name['given-names'].value; + var displayElement = $('').text(name).append($('').attr('href', 'https://orcid.org/' + id).attr('target', '_blank').attr('rel', 'noopener').html('ORCID logo')); + $(personElement).hide(); + let sibs = $(personElement).siblings("[data-cvoc-index='" + $(personElement).attr('data-cvoc-index') + "']"); + if (sibs.length == 0) { + displayElement.prependTo($(personElement).parent()); + } else { + displayElement.insertBefore(sibs.eq(0)); + } + //Store the most recent ORCIDs - could cache results, but currently using this just to prioritized recently used ORCIDs in search results + storeValue(orcidPrefix, id, name); + }, + error: function(jqXHR, textStatus, errorThrown) { + //Treat as plain text + $(personElement).show(); + let index = $(personElement).attr('data-cvoc-index'); + if (index !== undefined) { + $(personElement).siblings("[data-cvoc-index='" + index + "']").show().removeClass('hidden'); + } + //Generic logging if not 404 + if (jqXHR.status != 404) { + console.error("The following error occurred: " + textStatus, errorThrown); + } } + }); + } else { + //Plain text entry + $(personElement).show(); + let index = $(personElement).attr('data-cvoc-index'); + if (index !== undefined) { + $(personElement).siblings("[data-cvoc-index='" + index + "']").show().removeClass('hidden'); } - }); + } } }); } function updatePeopleInputs() { - //For each input element within personInputSelector elements + //For each input element within personInputSelector elements $(personInputSelector).each(function() { var personInput = this; if (!personInput.hasAttribute('data-person')) { //Random identifier let num = Math.floor(Math.random() * 100000000000); + $(personInput).attr('data-person', num); + + let parentField = $(personInput).attr('data-cvoc-parent'); + var parent = $(personInput).closest("[data-cvoc-parentfield='" + parentField + "']"); + + let hasParentField = $("[data-cvoc-parentfield='" + parentField + "']").length > 0; + let managedFields = {}; + if (hasParentField) { + managedFields = JSON.parse($(personInput).attr('data-cvoc-managedfields')); + if (Object.keys(managedFields).length > 0) { + //Hide managed fields + $(parent).find("input[data-cvoc-managed-field='" + managedFields.personName + "']").hide(); + $(parent).find("[data-cvoc-managed-field='" + managedFields.idType + "']").parent().hide(); + } + //Hide the actual input and give it a data-person number so we can find it + $(personInput).parent().hide(); + } else { + $(personInput).hide(); + } - //Hide the actual input and give it a data-person number so we can find it - $(personInput).hide(); $(personInput).attr('data-person', num); //Todo: if not displayed, wait until it is to then create the select 2 with a non-zero width //Add a select2 element to allow search and provide a list of choices var selectId = "personAddSelect_" + num; - $(personInput).after( - ''); $("#" + selectId).select2({ theme: "classic", tags: $(personInput).attr('data-cvoc-allowfreetext'), @@ -98,7 +120,7 @@ function updatePeopleInputs() { var pos = item.text.search(/\d{4}-\d{4}-\d{4}-\d{3}[\dX]/); if (pos >= 0) { var orcid = item.text.substr(pos, 19); - return $('').append(item.text.replace(orcid, "" + orcid + "")); + return $('').append(item.text.replace(orcid, "" + orcid + "")); } return item.text; }, @@ -138,17 +160,21 @@ function updatePeopleInputs() { 'Accept': 'application/json' }, processResults: function(data, page) { + let newItems = data['expanded-result']; + if (newItems == null) { + return { results: [] }; + } return { results: data['expanded-result'] //Sort to bring recently used ORCIDS to the top of the list - .sort((a, b) => (localStorage.getItem(b['orcid-id'])) ? 1 : 0) + .sort((a, b) => Number(getValue(orcidPrefix, b['orcid-id']).name != null) - Number(getValue(orcidPrefix, a['orcid-id']).name != null)) .map( function(x) { return { - text: x['given-names'] + " " + x['family-names'] + - ", " + + text: x['family-names'] + ", " + x['given-names'] + + "; " + x['orcid-id'] + - ((x.email.length > 0) ? ", " + x.email[0] : ""), + ((x.email.length > 0) ? "; " + x.email[0] : ""), id: x['orcid-id'], //Since clicking in the selection re-opens the choice list, one has to use a right click/open in new tab/window to view the ORCID page //Using title to provide that hint as a popup @@ -159,6 +185,22 @@ function updatePeopleInputs() { } } }); + //Add a tab stop and key handling to allow the clear button to be selected via tab/enter + const observer = new MutationObserver((mutationList, observer) => { + var button = $('#' + selectId).parent().find('.select2-selection__clear'); + console.log("BL : " + button.length); + button.attr("tabindex", "0"); + button.on('keydown', function(e) { + if (e.which == 13) { + $('#' + selectId).val(null).trigger('change'); + } + }); + }); + + observer.observe($('#' + selectId).parent()[0], { + childList: true, + subtree: true + }); //If the input has a value already, format it the same way as if it were a new selection var id = $(personInput).val(); if (id.startsWith("https://orcid.org")) { @@ -171,23 +213,32 @@ function updatePeopleInputs() { 'Accept': 'application/json' }, success: function(person, status) { - var name = person.name['given-names'].value + " " + person.name['family-name'].value; - var text = name + ", " + id; + var name = person.name['family-name'].value + ", " + person.name['given-names'].value; + var text = name + "; " + id; if (person.emails.email.length > 0) { - text = text + ", " + person.emails.email[0].email; + text = text + "; " + person.emails.email[0].email; } var newOption = new Option(text, id, true, true); newOption.title = 'Open in new tab to view ORCID page'; $('#' + selectId).append(newOption).trigger('change'); }, - failure: function(jqXHR, textStatus, errorThrown) { + error: function(jqXHR, textStatus, errorThrown) { if (jqXHR.status != 404) { console.error("The following error occurred: " + textStatus, errorThrown); } } }); } else { - //If the initial value is not an ORCID (legacy, or if tags are enabled), just display it as is + //If the initial value is not an ORCID (legacy, or if tags are enabled), just display it as is + if (Object.keys(managedFields).length > 0) { + //Handle managed fields + if (id.length > 0) { + $(parent).find("[data-cvoc-managed-field='" + managedFields.idType + "']").parent().show(); + $(personInput).parent().show(); + } + id = $(parent).find("input[data-cvoc-managed-field='" + managedFields.personName + "']").val(); + } + var newOption = new Option(id, id, true, true); $('#' + selectId).append(newOption).trigger('change'); } @@ -203,10 +254,58 @@ function updatePeopleInputs() { //Tags are allowed, so just enter the text as is $("input[data-person='" + num + "']").val(data.id); } + + //In the multi-field case, we should also fill in the other hidden managed fields + if (hasParentField) { + var parent = $("input[data-person='" + num + "']").closest("[data-cvoc-parentfield='" + parentField + "']"); + let isOrcid = data.text.includes(';'); + for (var key in managedFields) { + if (key == 'personName') { + $(parent).find("input[data-cvoc-managed-field='" + managedFields[key] + "']").attr('value', data.text.split(";", 1)[0]); + } else if (key == 'idType') { + let selectField = $(parent).find("[data-cvoc-managed-field='" + managedFields[key] + "']").find("select"); + let orcidVal = $(selectField).find('option:contains("ORCID")').val(); + $(selectField).val(isOrcid ? orcidVal : ''); + + } + } + if (Object.keys(managedFields).length > 0) { + if (isOrcid) { + //Hide managed fields + $(parent).find("input[data-person='" + num + "']").parent().hide(); + $(parent).find("[data-cvoc-managed-field='" + managedFields.idType + "']").parent().hide(); + } else { + //Show managed fields + let idField = $(parent).find("input[data-person='" + num + "']"); + idField.val(''); + idField.parent().show(); + $(parent).find("[data-cvoc-managed-field='" + managedFields.idType + "']").parent().show(); + } + } + } }); //When a selection is cleared, clear the hidden input $('#' + selectId).on('select2:clear', function(e) { + $(this).empty().trigger("change"); $("input[data-person='" + num + "']").attr('value', ''); + //In the multi-field case, we should also clear the other hidden managed fields + if (hasParentField) { + var parent = $("input[data-person='" + num + "']").closest("[data-cvoc-parentfield='" + parentField + "']"); + for (var key in managedFields) { + if (key == 'personName') { + $(parent).find("input[data-cvoc-managed-field='" + managedFields[key] + "']").val(''); + } else if (key == 'idType') { + $(parent).find("[data-cvoc-managed-field='" + managedFields[key] + "']").find("select").val(''); + } + } + } + }); + //Force cursor to appear in text box when opening via key press + $('#' + selectId).on('select2:open', function(e) { + $(".select2-search__field").focus() + $(".select2-search__field").attr("id", selectId + "_input") + document.getElementById(selectId + "_input").select(); + }); } }); @@ -236,4 +335,4 @@ function markMatch(text, term) { $result.append(text.substring(match + term.length)); return $result; -} \ No newline at end of file +} diff --git a/scripts/ror.js b/scripts/ror.js index db2d38b..e1e3830 100644 --- a/scripts/ror.js +++ b/scripts/ror.js @@ -13,24 +13,32 @@ $(document).ready(function() { }); function expandRors() { - console.log("expandRors"); // Check each selected element $(rorSelector).each(function() { var rorElement = this; // If it hasn't already been processed if (!$(rorElement).hasClass('expanded')) { + //Child field case - if non-managed display, the string before this is name (affiliation) and we need to remove the duplicate affiliation string + //This is true for Dataverse author field - may not be true elsewhere - tbd + let prev = $(rorElement)[0].previousSibling; + if(prev !== undefined) { + let val = $(rorElement)[0].previousSibling.nodeValue; + if(val !== null) { + $(rorElement)[0].previousSibling.data = val.substring(0,val.indexOf('(')); + } + } // Mark it as processed $(rorElement).addClass('expanded'); var id = rorElement.textContent; if (!id.startsWith(rorIdStem)) { - $(rorElement).html(getRorDisplayHtml(id, ['No ROR Entry'], false, true)); + $(rorElement).html(getRorDisplayHtml(id, null, ['No ROR Entry'], false, true)); } else { //Remove the URL prefix - "https://ror.org/".length = 16 id = id.substring(rorIdStem.length); //Check for cached entry let value = getValue(rorPrefix, id); if(value.name !=null) { - $(rorElement).html(getRorDisplayHtml(value.name, value.altNames, false, true)); + $(rorElement).html(getRorDisplayHtml(value.name, rorIdStem + id, value.altNames, false, true)); } else { // Try it as an ROR entry (could validate that it has the right form or can just let the GET fail) $.ajax({ @@ -41,12 +49,11 @@ function expandRors() { 'Accept': 'application/json', }, success: function(ror, status) { - console.log(ror); // If found, construct the HTML for display var name = ror.name; var altNames= ror.acronyms; - $(rorElement).html(getRorDisplayHtml(name, altNames, false, true)); + $(rorElement).html(getRorDisplayHtml(name, rorIdStem + id, altNames, false, true)); //Store values in localStorage to avoid repeating calls to CrossRef storeValue(rorPrefix, id, name + "#" + altNames); }, @@ -64,7 +71,7 @@ function expandRors() { }); } -function getRorDisplayHtml(name, altNames, truncate=true, addParens=false) { +function getRorDisplayHtml(name, url, altNames, truncate=true, addParens=false) { if(typeof(altNames) == 'undefined') { altNames=[]; } @@ -74,8 +81,11 @@ function getRorDisplayHtml(name, altNames, truncate=true, addParens=false) { altNames.unshift(name); name=name.substring(0,rorMaxLength) + "…"; } + if(url != null) { + name = name + '' +'ROR logo'; + } if(addParens) { - name = " (" + name +")"; + name = ' (' + name + ')'; } return $('').append(name).attr("title", altNames); } @@ -97,7 +107,7 @@ function updateRorInputs() { // choices var selectId = "rorAddSelect_" + num; $(rorInput).after( - ''); $("#" + selectId).select2({ theme: "classic", tags: $(rorInput).attr('data-cvoc-allowfreetext'), @@ -126,9 +136,9 @@ function updateRorInputs() { altNames = idnum.substr(pos+2).split(','); idnum=idnum.substr(0,pos); } - return getRorDisplayHtml(name, altNames); + return getRorDisplayHtml(name, rorIdStem + idnum, altNames); } - return getRorDisplayHtml(name, ['No ROR Entry']); + return getRorDisplayHtml(name, null, ['No ROR Entry']); }, language: { searching: function(params) { @@ -146,7 +156,6 @@ function updateRorInputs() { term = params.term; if (!term) { term = ""; - console.log("no term!"); } var query = { query: term, @@ -165,11 +174,11 @@ function updateRorInputs() { results: data['items'] // Sort the list // Prioritize active orgs - .sort((a, b) => (b.status === 'active') ? 1 : -1) + .sort((a, b) => Number(b.status === 'active') - Number(a.status === 'active')) // Prioritize those with this acronym - .sort((a, b) => (b.acronyms.includes(params.term)) ? 1 : -1) + .sort((a, b) => Number(b.acronyms.includes(params.term)) - Number(a.acronyms.includes(params.term))) // Prioritize previously used entries - .sort((a, b) => (getValue(rorPrefix, b['id'].replace(rorIdStem,'')).name != null) ? 1 : -1) + .sort((a, b) => Number(getValue(rorPrefix, b['id'].replace(rorIdStem,'')).name != null) - Number(getValue(rorPrefix, a['id'].replace(rorIdStem,'')).name != null)) .map( function(x) { return { @@ -181,6 +190,23 @@ function updateRorInputs() { } } }); + //Add a tab stop and key handling to allow the clear button to be selected via tab/enter + const observer = new MutationObserver((mutationList, observer) => { + var button = $('#' + selectId).parent().find('.select2-selection__clear'); + console.log("BL : " + button.length); + button.attr("tabindex","0"); + button.on('keydown',function(e) { + if(e.which == 13) { + $('#' + selectId).val(null).trigger('change'); + } + }); + }); + + observer.observe($('#' + selectId).parent()[0], { + childList: true, + subtree: true } + ); + // If the input has a value already, format it the same way as if it // were a new selection var id = $(rorInput).val(); @@ -207,7 +233,7 @@ function updateRorInputs() { } }); } else { - // If the initial value is not in CrossRef, just display it as is + // If the initial value is not in ROR, just display it as is var newOption = new Option(id, id, true, true); newOption.altNames = ['No ROR Entry']; $('#' + selectId).append(newOption).trigger('change'); @@ -231,6 +257,13 @@ function updateRorInputs() { $('#' + selectId).on('select2:clear', function(e) { $("input[data-ror='" + num + "']").attr('value', ''); }); + //When the field is selected via keyboard, move the focus and cursor to the new input + $('#' + selectId).on('select2:open', function(e) { + $(".select2-search__field").focus() + $(".select2-search__field").attr("id",selectId + "_input") + document.getElementById(selectId + "_input").select(); + + }); } }); } \ No newline at end of file