islandora / controlled_access_terms

Drupal module for subject and agents

Controlled Access Terms

Introduction

This Drupal 8 module creates vocabularies to represent common named entities in archival description (Corporate Bodies, Families, and Persons) as well as subject terms.

It is intended to be used in conjunction with both the ArchivesSpace/Drupal 8 Integration project and Islandora 8.

Requirements

This module requires the following modules:

• name
• geolocation
• token

Installation

Download and install as with other Drupal modules.

For example, using composer from the Drupal site's web directory:

$ composer require islandora/controlled_access_terms
$ drush en -y controlled_access_terms

Enable controlled_access_terms_defaults to create the default vocabularies.

Configuration

Provided vocabularies and fields may be configured in the same manner as other Drupal 8 vocabularies.

Provided Vocabularies

Below is a list of the vocabularies provided by controlled_access_terms_defaults. The fields with "EDTF" accept and display dates corresponding to the Library of Congress 2018 Extended Date/Time Format Specification (EDTF). See the section below for more information on EDTF.

• Corporate Body
  • Preferred Name (Name)
  • Type
    • Organizational Unit (org:OrganizationalUnit)
    • Airline (schema:Airline)
    • Corporation (schema:Corporation)
    • Educational Organization (schema:EducationalOrganization)
    • Government Organization (schema:GovernmentOrganization)
    • LocalBusiness (schema:LocalBusiness)
    • Medical Organization (schema:MedicalOrganization)
    • Non-Governmental Organization (schema:NGO)
    • Performing Group (schema:PerformingGroup)
    • Sports Organization (schema:SportsOrganization)
    • Sports Team (schema:SportsTeam)
  • Authority Link
  • Founding Date (EDTF)
  • Dissolution Date (EDTF)
  • Alternate Name
  • Description
  • Related Entities
• Family
  • Display Label (Name)
  • Description
  • Date Begin (EDTF)
  • Date End (EDTF)
  • Authority Link
  • Relation
• Person
  • (Display) Name
  • Authority Link
  • Preferred Name
  • Alternate Name
  • Description
  • Birth Date (EDTF)
  • Death Date (EDTF)
  • Relationships
• Geographic Location
  • Name (Title)
  • Authority Link
  • Latitude/Longitude (WGS 84)
  • Description
  • Alternate Name
  • Broader
• Subject
  • Name
  • Language
  • Description
  • Authority Link

Extended Date/Time Format (EDTF)

The Library of Congress created the Extended Date/Time Format Specification which was subsequently incorporated with ISO 8601-2019. This modules provides a custom EDTF field type with a corresponding formatter (for display) and widget (for data entry).

Both the formatter and widget include settings for controlling how the EDTF is entered and displayed. For example, the widget allows EDTF values to use intervals; however, the widget settings (accessible through the bundle's form display page) can restrict the field to only accept single-dates.

Note: widget settings will not apply to data imported through other means (e.g. the Migrate API or REST-based updates). To apply some basic EDTF validation when using Migrate API, set validate: true in the migration's destination. This is a coarser validation than the widgets provided but will rule out some malformed date strings.

The formatter settings allow administrators to control how the date is displayed. The default setting is YYYY-MM-DD (e.g. 1900-01-31) but settings can change, for example, the separator and the date order to display dates in 'mm/dd/yyyy' format (e.g. 01/31/1900).

Documentation

Further documentation for this module is available on the Islandora 8 documentation site.

Troubleshooting/Issues

Having problems or solved a problem? Check out the Islandora google groups for a solution.

• Islandora Group
• Islandora Dev Group

Maintainers/Sponsors

Current maintainers:

• Seth Shaw

Development

If you would like to contribute, please get involved by attending our weekly Tech Call. We love to hear from you!

If you would like to contribute code to the project, you need to be covered by an Islandora Foundation Contributor License Agreement or Corporate Contributor License Agreement. Please see the Contributors pages on Islandora.ca for more information.

We recommend using the islandora-playbook to get started.

License

GPLv2.

controlled_access_terms's Issues

[BUG] Undefined array key 3 warning when using date interval in JSON-LD

What steps does it take to reproduce the issue?

Create an item with and EDTF interval, e.g. '2022/2023', and view the JSON-LD. This creates a warning in the logs stating "Undefined array key 3" because the converter is expecting a single date.

What did you expect to happen?

No warnings. It should return the earliest ISO 8601 date value for the interval.

[USE CASE] Defaults should install without RDF

Overview of Use Case
I want to use Controlled Access Terms Defaults and the useful default vocabularies in a Drupal site but we don't need/use the RDF module.

Title (Goal):
Install Controlled Access Terms Defaults without RDF

Primary Actor:
Site Admin

Scope
Non-Islandora Drupal sites (or Islandora sites who want to do more sophisticated RDF 🦞 )

[BUG] Linked agent relator type is not translatable

What steps does it take to reproduce the issue?
Make an islandora object and configure at least one linked agent on the item. Set the site up to use a secondary language and then select the other language and see that the relator type is not translatable.

• When does this issue occur?
  When viewing any item in another language that displays a linked agent.

• Which page does it occur on?
  On the secondary language version of any default view of items as well as the edit form (if the form config is set up to allow edit of that field in secondary language) -- and it could also appear in any teaser or search results display is configured to also display the field.

• What happens?
  Even though the relator type is able to have a translation provided for it, the actual label is never passed through the drupal t() function, so it cannot be translated until this PR is merged.

• To whom does it occur (anonymous visitor, editor, administrator)?
  All users who could see items with linked agent values when viewed in a different language.

• What did you expect to happen?
  For example, if the second language is French, I'd expect to see a French translation for the relator type such as "Artist", I'd expect to see "Artiste" instead.

Which version of Islandora are you using?
2.x-dev

Any related open or closed issues to this bug report?
no

Screenshots:
English version of some linked agents on an example content item:

French version of the same item:

[FEATURE] Validate date intervals for EDTF

Overview of feature request

Add functionality to validate that in EDTF intervals, the start date is sooner than the end date within the EDTFUtils class.

What kind of user is the feature intended for?

Developers and Collections Managers who work with Extended Date Time Format (EDTF) dates and need to ensure accurate date intervals.

What inspired the request?

The need to ensure data integrity and logical consistency in date intervals. Users should be confident that date intervals are correctly formatted, with the start date always preceding the end date.

What existing behavior do you want changed?

The current validate function in the EDTFUtils class does not check that for intervals, the start date is sooner than the end date. This can lead to incorrect data representation and potential logical errors in date-related operations.

Any brand new behavior do you want to add to Islandora?

Yes, introduce a check within the validate function to compare the start and end dates of an interval. If the start date is later than the end date, an appropriate error message should be returned.

Any related open or closed issues to this feature request?

No known related issues at this time.

[BUG] EDTF date sets in multivalued fields are rendered into human-readable text incorrectly.

What steps does it take to reproduce the issue?

• Enable date sets in an EDTF field (admittedly, this is "not recommended")

• Enable multiple values in that field

• Add multiple date sets to see how they render.

• When does this issue occur?
  When looking at the node

• Which page does it occur on?
  a node

• What happens?
  the human-readable version of each date set includes data from other "deltas" (i.e. other values in the multivalued field)

In my example the first two values in the multivalued field are:

• [1667,1668,1670..1672] which renders as "one of the dates: 1667, 1668, 1670 until 1672"

• [..1760-12-03] which renders as "one of the dates: 1667, 1668, 1670 until 1672, 1760-12-03 or some earlier date"

• To whom does it occur (anonymous visitor, editor, administrator)?
  Everyone can see it.

• What did you expect to happen?
  the values to be rendered to text independently

Which version of Islandora are you using?
2
more meaningfully, the starter site

Any related open or closed issues to this bug report?

not that i know of

Screenshots:

[BUG] Open intervals with null values don't work: "Could not parse EDTF value '1937/' for indexing node/nid"

What steps does it take to reproduce the issue?

• When does this issue occur?
  When indexing items with an open interval with a null value e.g. '1937/'

• Which page does it occur on?
  Errors are in watchdog and come from indexing in EDTF Year.

• What happens?
  The years don't get added for faceting.

• To whom does it occur (anonymous visitor, editor, administrator)?
  Content editors / searchers

• What did you expect to happen?
  The null-valued intervals should be treated the same as open-ended intervals that use, e.g. /...

Which version of Islandora are you using?
2

Any related open or closed issues to this bug report?
no

Screenshots:

[FEATURE] EDTF - support intervals

Overview of feature request
Let's extend the coverage of EDTF, it supports intervals:
https://www.loc.gov/standards/datetime/edtf.html

‘2004-02-01/2005’ is a time interval beginning sometime on February 1, 2004 and ending sometime in 2005. The start endpoint has calendar day precision and the end endpoint has calendar year precision. Similar to the previous example, the precision of the time interval at large is undefined.

But the constraint does not allow to create this.

What kind of user is the feature intended for?

Content author.

What inspired the request?

Our requirements at a client project where intervals are needed, for instance a piece of content can be created during years in some rare cases.

What existing behavior do you want changed?
The validation in EDFUtils: https://github.com/Islandora/controlled_access_terms/blob/2.x/src/EDTFUtils.php#L132

Any brand new behavior do you want to add to Islandora?

Nothing brand new, just better coverage of EDTF specs.

[BUG] Some EDTF date intervals fail to parse into ISO8601

What steps does it take to reproduce the issue?

• Enter an EDTF date interval in the form YYYY-MM/YYYY-MM, e.g. "1960-01/1960-02"
• Attempt to parse it using controlled_access_terms\EDTFUtils::iso8601Value. Example:

 drush ev 'print_r(\Drupal\controlled_access_terms\EDTFUtils::iso8601Value("1960-02/1960-03"));'
 [warning] Undefined array key 3 EDTFUtils.php:344
T00:00:00%

• It throws a php warning, and returns an invalid ISO 8601 date string "T00:00:00%"
• We found this problem in our own custom code that attempts to parse values of an EDTF date field in a search_api processor.
• I have not encountered other cases that produce wonky results, but I'm guessing there are some.

When does this issue occur?

• Any place that tries to convert and EDTF date to ISO8601:
• In the controlled_access_terms module, I see this in the following hook implementations: controlled_access_terms_jsonld_alter_normalized_array(), controlled_access_terms_tokens()

Any related open or closed issues to this bug report?

• [FEATURE] Validate date intervals for EDTF #123
• [FEATURE] EDTF - support intervals #122
• (probably others)

[FEATURE] Let the relator display "as a label" (bolded etc).

Overview of feature request

When viewing a Linked Agent field, the field value includes the relator, a colon, and the value. However, this can be hard to scan. Ideally the relator could show up "like a label" for the content it describes.

It's this line here: https://github.com/Islandora/controlled_access_terms/blob/2.x/src/Plugin/Field/FieldFormatter/TypedRelationFormatter.php#L32

What kind of user is the feature intended for?
Site Designers

What inspired the request?
Trying to put metadata display into a table, and realized Linked Agents looked a little funky.

What existing behavior do you want changed?
Concatenating the relator to the value

Any brand new behavior do you want to add to Islandora?
Use something else - template? - to let the relator and value be formatted (incuding as a label to match other field labels?)

Any related open or closed issues to this feature request?

[BUG] Deleting a term does not delete Typed Relation references to it.

What steps does it take to reproduce the issue?

• Create a term.

• Create a typed relation field on a node [any entity? not sure]

• Refer to the created term in the typed relation field.

• Delete the term.

• When does this issue occur?
  When you delete the term the problem happens; it becomes visible on reloading the node's page

• Which page does it occur on?
  Any node. I have not tested on other entities.

• What happens?
  The value remains in the node. When viewing the node, the "Type" label appears (in this case "Attributed name:"), but where the term name formerly rendered, nothing is rendered.

• To whom does it occur (anonymous visitor, editor, administrator)?
  It is confusing to everyone, I'm sure.

• What did you expect to happen?
  I thought the delete hook was picked up by typed relation fields.

Which version of Islandora are you using?
the version on the sandbox. The real question is what version of controlled access terms? Which is not apparent from the interface.

Any related open or closed issues to this bug report?

Not that I know of

Screenshots:
inline

EDIT: this is not a Typed Relation issue. This is how Drupal Entity Relationship fields work too.

[FEATURE] Support paragraphs in EDTF Year processor

Overview of feature request

If a date field on a paragraph is selected in EDTF year processor, the dates do not get parsed.

What kind of user is the feature intended for?
Everyone

Any brand new behavior do you want to add to Islandora?
If a date field on a paragraph is selected EDTF year processor, the dates from that field should get indexed while indexing an entity.

[BUG] Year zero does not exist

What steps does it take to reproduce the issue?

Supply 0000 to an EDTF field. There should be a validation error according to https://en.wikipedia.org/wiki/Year_zero . The value is accepted, but nothing is rendered at the node display in the date field.

• When does this issue occur?

• Which page does it occur on?
  Node edit / view

• What happens?
  Lack of rendered variation, lack of validation error.

• What did you expect to happen?
  A validation error should happen, 0000 is not a valid year.

[FEATURE] More configurable displays of the Authority Link field.

Overview of feature request

What kind of user is the feature intended for?
Anyone using this field in taxonomy terms in islandora

What inspired the request?
Uncovered that if only the uri, but not the source or title are set (can happen during migrations), then nothing will display at all.

What existing behavior do you want changed?
There are three elements of this field and zero ability to configure what displays! In the rendered item, and more importantly, in Views.

Any brand new behavior do you want to add to Islandora?
Configurable authority link field display.
Adding individual "elements" to views, or search api? (note i haven't investigated this with search api and i'm really concerned with views.)

Any related open or closed issues to this feature request?
don't think so.

[BUG] JSONLD hook fails if any EDTF field exists without an RDF mapping.

What steps does it take to reproduce the issue?

• Create a new EDTF field on a node, put some content in it, and load the node.
• Check the watchdog logs. You will see:
  Warning: Undefined array key "field_new_date" in controlled_access_terms_jsonld_alter_normalized_array() (line 65 of /var/www/html/drupal/web/modules/contrib/controlled_access_terms/controlled_access_terms.module)

code is here:

controlled_access_terms/controlled_access_terms.module

Line 65 in 4fc7177

foreach ($context['current_entity_rdf_mapping']->get('fieldMappings')[$field]['properties'] as $predicate) {

Any related open or closed issues to this bug report?
not that I found.

[TECH DEBT] Revisit why we are using Features in Controlled Access Terms Defaults

Controlled Access Terms and its's Defaults were designed to be usable with any Drupal, even one that does not use Islandora. I believe they work OK in that capacity.

Is a Feature still the desired way to ship Controlled Access Terms Defaults? Features imply some level of receiving updates.

Now that Islandora Defaults is a Starter Site we thought it would be a good opportunity to revisit why we made some modules as Drupal Features.

[FEATURE] Update for ProfessionalWiki/EDTF v3.0.0

Overview of feature request

ProfessionalWiki/EDTF now has a 3.0.0 version which has some breaking changes from 2.x. We should evaluate if we need to update our use of their API before we can bump our version requirement.

Could not parse the date '1964/2008'

We have an EDTF field. Inputting range date such as 1964/2008 throws the following error: Could not parse the date '1964/2008'

Seems like this is where the checking happens: https://github.com/Islandora/controlled_access_terms/blob/2.x/src/EDTFUtils.php#L193

Additional Notes

• "islandora/controlled_access_terms": "2.x-dev",
• "professional-wiki/edtf": "^2.0"

<?php
$date = "1964/2008";
$pattern = '/^([%\?~])?(Y?(-?[\dX]+)(E\d)?(S\d)?)([%\?~])?-?([%\?~])?([\dX]{2})?([%\?~])?-?([%\?~])?([\dX]{2})?([%\?~])?$/';
preg_match($pattern, $date, $parsed_date);
print_r($parsed_date);
?>

It does work in the sandbox!

[BUG] Updated config format

We need to update config values for all solr year processors for sites that had the old setting before #113 was merged

We need a hook_update_N in this module to append node to all solr indexes that have an edtf year processor set but are of the format bundle|field and not entity_type|bundle|field

diff --git a/config/sync/search_api.index.default_solr_index.yml b/config/sync/search_api.index.default_solr_index.yml
index 1ea2baaa..48cf7988 100644
--- a/config/sync/search_api.index.default_solr_index.yml
+++ b/config/sync/search_api.index.default_solr_index.yml
@@ -482,10 +482,10 @@ processor_settings:
   custom_value: {  }
   edtf_year_only:
     fields:
-      islandora_object|field_copyright_date: islandora_object|field_copyright_date
-      islandora_object|field_edtf_date: islandora_object|field_edtf_date
-      islandora_object|field_edtf_date_created: islandora_object|field_edtf_date_created
-      islandora_object|field_edtf_date_issued: islandora_object|field_edtf_date_issued
+      node|islandora_object|field_copyright_date: node|islandora_object|field_copyright_date
+      node|islandora_object|field_edtf_date: node|islandora_object|field_edtf_date
+      node|islandora_object|field_edtf_date_created: node|islandora_object|field_edtf_date_created
+      node|islandora_object|field_edtf_date_issued: node|islandora_object|field_edtf_date_issued
     ignore_undated: 1
     ignore_open_start: 0
     open_start_year: '0'

[FEATURE] Get Entity Browser to work with typed relation fields.

Drupal's Entity Browser lets you replace an entity autocomplete by a view. This lets you have extensive sorting and filtering. Example shown here:

However it doesn't work with Typed Relation fields, because the Entity Browser widget is exclusive to Entity Reference fields.

Can we extend the Entity Browser widget so that it works with Typed Relations?

A naive attempt resulted in a partial success, except for its handling of multiple values. As seen below, the Entity Browser widget handles all values as part of a single widget, while the typed relation field, when repeated, causes separate widgets. In the example below, the "creator" entity and the "publisher" entity both show up under both relations - not good.

There are probably other places where this fails. Can we find a way to harmonize these awesome modules?