Merge pull request #9 from Kris-LIBIS/main

authors and affiliation lookup examples added

Author: qqmyers

examples/affiliation.md

@@ -0,0 +1,13 @@
+The affiliation example illustrates a lookup in ROR.org for the author affiliation field. As with the authors example, it is a simple lookup and fill-in solution. Do not expect changes in the ROR database to be propagated in the Dataset metadata.
+
+Two files comprise this example:
+
+- examples/config/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
+
+How to install:
+
+- load the affiliation.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 affiliation.json http://localhost:8080/api/admin/settings/:CVocConf`.
+
+- refresh your browser page. That's it. You should see a search icon next to the affiliation input box of the Dataset Metadata editor which pops up a search dialog. Type some text in the search box (e.g. `UCLA`) and hit the `ENTER` key. Click on an organization name to see the ROR page and select the `import` button to copy the name in the Dataset metadata form.

examples/authors.md

@@ -0,0 +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.
+
+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.
+
+- 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.
+
+- 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.
+
+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
+
+- 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.
+
+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 `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 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 `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.

examples/config/affiliation.json

@@ -0,0 +1,14 @@
+[
+  {
+    "field-name": "authorAffiliation",
+    "term-uri-field": "authorAffiliation",
+    "js-url": "https://gdcc.github.io/dataverse-external-vocab-support/scripts/affiliation.js",
+    "protocol": "covoc-author",
+    "retrieval-uri": "",
+    "allow-free-text": true,
+    "languages": "",
+    "vocabs": "",
+    "managed-fields": {},
+    "retrieval-filtering": {}
+  }
+]

examples/config/authors.json

@@ -0,0 +1,14 @@
+[
+  {
+    "field-name": "authorName",
+    "term-uri-field": "authorName",
+    "js-url": "/covoc/js/covoc.js",
+    "protocol": "covoc-author",
+    "retrieval-uri": "",
+    "allow-free-text": true,
+    "languages": "",
+    "vocabs": "",
+    "managed-fields": {},
+    "retrieval-filtering": {}
+  }
+]

scripts/affiliation.js

@@ -0,0 +1,187 @@
+/************************************************************************************************************
+ * This JavaScript is responsible for the controlled vocabulary features in the browser.                    *
+ * The search button opens a dialog in which the controlled vocabulary server can be queried.               *
+ * On each result line, a button allows to copy-and-paste the information automatically in the form fields. *
+ * ******************************************************************************************************** *
+ * Author: Kris Dekeyser @ KU Leuven (2022). MIT License                                                    *
+ ************************************************************************************************************/
+
+/* DOM Element Identfiers
+ * **********************
+ * affiliation-modal: the modal for the dialog box
+ * affiliation-modal-title: the dialog box title
+ * affiliation-search-box: field in the dialog where search term can be entered
+ * affiliation-search-results: location where the query results will be displayed
+ * DOM Classes
+ * ***********
+ * search_added: class added when a search button has already been added
+ */
+
+var affiliationModalId ='affiliation-modal';
+var affiliationSearchBoxId = 'affiliation-search-box';
+var affiliationSearchResultsID = 'affiliation-search-results';
+var elementIdAttribute = 'data-affiliation-element-id';
+
+/* The browser will run this code the first time the editor is opened and each time a multiple field instance is 
+ * added or removed. This code is reposible for creating the HTML for the dialog box, adding a search button to 
+ * the affiliation name fields and creating the triggers for initializing the dialog box and the search action itself.
+ */
+$(document).ready(function() {
+  // Create Dialog box, if necessary
+  createAffiliationModal();
+
+  // Put a search button after each affiliation name field
+  putAffiliationSearchIcon();
+});
+
+function createAffiliationModal() {
+  let affiliationModal = document.getElementById(affiliationModalId);
+  if (!affiliationModal) {
+    // Create modal dialog
+    let dialog = document.createElement('div');
+    document.body.appendChild(dialog);
+    dialog.outerHTML =
+      '<div id="' + affiliationModalId + '" class="modal fade in" tabindex="-1" aria-labelledby="' + affiliationModalId + '-title" role="dialog" style="margin-top: 5rem">' + 
+        '<div class="modal-dialog" role="document">' + 
+          '<div class="modal-content">' + 
+            '<div class="modal-header">' + 
+              '<button class="close" type="button" data-dismiss="modal" aria-label="close"><span aria-label="Close">X</span></button>' + 
+              '<h5 id="' + affiliationModalId + '-title" class="modal-title">Search for organization in ROR</h5>' + 
+            '</div>' + 
+            '<div class="modal-body">' + 
+              '<div style="display: flex;">' + 
+                '<input id="' + affiliationSearchBoxId + '" class="form-control" accesskey="s" type="text" placeholder="Search for organization name ...">' + 
+                '<span class="glyphicon glyphicon-question-sign tooltip-icon" data-toggle="tooltip" data-placement="auto right" data-original-title="Type text and hit the Enter key to search." style="margin-left: 5px;"></span>' +
+              '</div>' +
+              '<div style="overflow-y: auto; height: 20em;">' + 
+                '<table id="' + affiliationSearchResultsID + '" class="table table-striped table-hover table-condensed"><tbody/></table>' + 
+              '</div>' +
+            '</div>' + 
+          '</div>' + 
+        '</div>' + 
+      '</div>';
+
+    // Before modal is opened, pull in the current value of the affiliation input field into the search box and launch a query for that value
+    $('#' + affiliationModalId).on('show.bs.modal', function(e) {
+      // Get the stored ID of the input field
+      let inputID = e.relatedTarget.getAttribute(elementIdAttribute);
+      let affiliationElement = document.getElementById(inputID);
+      // Fill in the input field text in the searchBox ...
+      let affiliationSearchBox = document.getElementById(affiliationSearchBoxId);
+      affiliationSearchBox.value = affiliationElement.value;
+      // ... and launch a query
+      affiliationsQuery(affiliationElement.value);
+      // Let the searchBox know where to write the data
+      affiliationSearchBox.setAttribute(elementIdAttribute, inputID);
+    });
+
+    // After model is opened, set focus on search box
+    $('#' + affiliationModalId).on('shown.bs.modal', function(e) {
+      // autofocus does not work with BS modal
+      let affiliationSearchBox = document.getElementById(affiliationSearchBoxId);
+      affiliationSearchBox.focus();
+      affiliationSearchBox.select();
+    });
+
+    // To minimize the load on the lookup service, we opted for an explicit enter to launch a query
+    document.getElementById(affiliationSearchBoxId).addEventListener('keyup', function(e) {
+      // Only if Enter key is pressed
+      if (e.key === 'Enter') {
+        // Get string from searchBox ...
+        let str = this.value;
+        // ... and launch query ...
+        affiliationsQuery(this.value);
+        // .. and prevent key to be added to the searchBox
+        e.preventDefault();
+      }
+    });
+  }
+}
+
+// Lauches a query to the external vocabulary server and fills in the results in the table element of the dialog searchBox
+
+/* arguments:
+ *  - str (String): text to search for
+ */
+
+function affiliationsQuery(str) {
+  // Vocabulary search REST call
+  fetch("https://api.ror.org/organizations?query=" + str)
+  .then(response => response.json())
+  .then(data => {
+    let table = document.querySelector('#' + affiliationSearchResultsID + ' tbody');
+    // Clear table content
+    table.innerHTML = ''
+    // Get ID of target input element
+    let id = document.getElementById(affiliationSearchBoxId).getAttribute(elementIdAttribute);
+    // Iterate over results
+    data.items.forEach((doc) => {
+      let label = doc.labels.length > 0 ? doc.labels[0].label : '';
+      let address = ( doc.addresses.length > 0 ? doc.addresses[0].city : '' ) + ', ' + doc.country.country_name;
+      // Add a table row for the doc
+      table.innerHTML += 
+      '<tr title="' + label + '">' +
+        '<td><a href="' + doc.id + '" target="_blank">' + doc.name + '</a></td>' +
+        '<td>' + address + '</td>' +
+        '<td>' + 
+          '<span ' + 
+            'class="btn btn-default btn-xs glyphicon glyphicon-import pull-right" title="import" ' + 
+            'onclick="importAffiliationData(\'' + id + '\', \'' + doc.name + '\');">' + 
+          '</span>' + 
+        '</td>' + 
+      '</tr>';
+    });
+  });
+}
+
+// Selector for all the author compound fields
+var authorSelector = "div#metadata_author ~ div.dataset-field-values div.edit-compound-field";
+
+// Adds a search button to all the affiliation input fields
+function putAffiliationSearchIcon() {
+  // Iterate over compound elements
+  document.querySelectorAll(authorSelector).forEach(element => {
+    // 'search_added' class marks elements that have already been processed
+    if (!element.classList.contains('search_added')) {
+      element.classList.add('search_added');
+      // Second child is element that encapsulates label and input of affiliation
+      let affiliationField = element.children[1];
+      // Input field within
+      let affiliationInput = affiliationField.querySelector('input');
+      // We create an bootstrap input group ...
+      let wrapper = document.createElement('div');
+      wrapper.className = 'input-group';
+      wrapper.style.display = 'flex';
+      // ... containing the input field ...
+      wrapper.appendChild(affiliationField.querySelector('input'));
+      // ... and a new seach button ...
+      let searchButton = document.createElement('button');
+      element.setAttribute('aria-describedby', searchButton.id);
+      searchButton.className = 'btn btn-default btn-sm bootstrap-button-tooltip compound-field-btn';
+      searchButton.setAttribute('type', 'button');
+      searchButton.setAttribute('title', 'Search in ROR');
+      searchButton.setAttribute('data-toggle', 'modal');
+      searchButton.setAttribute('data-target', '#' + affiliationModalId);
+      searchButton.setAttribute(elementIdAttribute, affiliationInput.id);
+      let searchIcon = document.createElement('span');
+      searchIcon.className = 'glyphicon glyphicon-search no-text';
+      searchButton.appendChild(searchIcon);
+      wrapper.appendChild(searchButton);
+      // ... and add that to the encapsulating element.
+      affiliationField.appendChild(wrapper);
+    }
+  })
+}
+
+// Import the query result data into the metadata form
+// arguments:
+// - id (String): identifier of the affiliationName input field
+// - affiliation: affiliation name
+function importAffiliationData(id, affiliation) {
+  // Get the affiliation input field
+  let affiliationElement = document.getElementById(id);
+  // Fill-in affiliation
+  affiliationElement.value = affiliation;
+  // Close the dialog box when the import is done
+  $('#' + affiliationModalId).modal('hide');
+}