Merge pull request #56 from nchiasson-dgi/FDR-398

FDR-398: Merging in latest from main

README.md

@@ -2,19 +2,77 @@
 
 Display citations for Islandora Objects.
 
+## Introduction
+
+The module enables users to add multiple citation style languages,
+map csl fields to drupal fields and render citations using these.
+
+### Citation Type Field
+A new field, 'field_csl_type' is added which references CSL type taxonomy.
+This is a required field for rendering citations
+and derives the citation display.
+
+### Citation style languages
+An interface is provided to add citation style languages either by pasting
+the csl in the provided text-area or by uploading a csl file.
+
+Three default citation style languages are provided with the module -
+APA
+MLA
+Chicago Manual of Style
+
+### Mapping CSL fields
+Any drupal field can be mapped to a csl field with third party settings.
+Edit any field to update the citations mapping section.
+
+#### Entity Reference and Entity Reference Revision fields
+- Users are able to map csl fields from the referenced entity
+by selecting the map from entity option.
+
+- If a direct mapping is selected for the entity reference field,
+the title of the referenced entity will be mapped to the selected csl value.
+This option is not available for paragraphs.
+
+### Typed Relation fields
+Typed relations fields are mapped directly from their relations.
+For example, author relation would get mapped to author csl field.
+
+### Multi Value fields
+Multi value fields are displayed as comma separated strings
+For multi-value date fields, only the first value is considered
+and the rest are ignored.
+
+### Citations display block
+A block is provided which allows users to select a
+default CSL to render the citations in.
+
 ## Installation
 
 Install as
 [usual](https://www.drupal.org/docs/extending-drupal/installing-modules).
 
 ## Configuration
 
+Add a new citations style language
+/admin/structure/islandora-citations
 
-// Todo
+Configure the citations block and set a default CSL
+admin/structure/block/manage/displaycitations
+
+Map csl fields to entity fields
+admin/structure/types/manage/<content_type>/fields/<field_id>
+For example: /admin/structure/types/manage/islandora_object/fields/node.islandora_object.field_member_of
 
 ## Usage
 
-// Todo
+Run the migration for csl type taxonomy - `drush migrate:import csl_type `
+Place the citations block from the block layout section.
+Map the relevant drupal fields to csl fields.
+
+## Known Issues
+
+Module is under active development and there are some known issues:
+ - Normalisation of date range fields
 
 ## Maintainers/Sponsors
 

islandora_citations.info.yml

@@ -2,7 +2,7 @@ name: Islandora citations
 type: module
 description: Provides a service to manage citations.
 package: Custom
-core_version_requirement: ^9 || ^10
+core_version_requirement: ^10
 dependencies:
   - drupal:field_permissions
   - drupal:node

islandora_citations.module

@@ -5,6 +5,7 @@
  * General hook implementations.
  */
 
+use Drupal\Core\Entity\EntityInterface;
 use Drupal\Core\Form\FormStateInterface;
 
 /**
@@ -18,10 +19,15 @@ function islandora_citations_form_field_config_edit_form_alter(&$form, FormState
     $cslFieldOptions = array_combine($cslPropertyArray, $cslPropertyArray);
     $entity = $form_state->getFormObject()->getEntity();
 
+    $form['islandora_citations'] = [
+      '#title' => 'Citation Settings',
+      '#type' => 'fieldset',
+    ];
+
     // For typed relation, there is no separate mapping.
     // It can just be enabled and the mapping will be based on rel type.
     if ($entity->getType() == 'typed_relation') {
-      $form['third_party_settings']['islandora_citations']['use_entity_checkbox'] = [
+      $form['islandora_citations']['use_entity_checkbox'] = [
         '#title' => t('Map CSL from relation type'),
         '#description' => t('Enable mapping of this typed relation  field from the selected relation type. Rel types, author and creator both get mapped to author.'),
         '#type' => 'checkbox',
@@ -35,7 +41,7 @@ function islandora_citations_form_field_config_edit_form_alter(&$form, FormState
     // For ER fields, we allow both mapping selected from entity
     // or mapping just the title of the ER entity.
     if ($entity->getType() == 'entity_reference_revisions' || $entity->getType() == 'entity_reference') {
-      $form['third_party_settings']['islandora_citations']['use_entity_checkbox'] = [
+      $form['islandora_citations']['use_entity_checkbox'] = [
         '#title' => t('Map from referenced entity'),
         '#description' => \t('If this field is enabled, the csl mapping will be taken from the referenced entity. Make sure you map fields in the referenced entity before enabling this.'),
         '#type' => 'checkbox',
@@ -46,7 +52,7 @@ function islandora_citations_form_field_config_edit_form_alter(&$form, FormState
 
     // We do not allow direct mapping for typed relation or ERR.
     if (!($entity->getType() === 'entity_reference_revisions' || $entity->getType() === 'typed_relation')) {
-      $form['third_party_settings']['islandora_citations']['csl_field'] = [
+      $form['islandora_citations']['csl_field'] = [
         '#type' => 'select',
         '#title' => \t('CSL Field'),
         '#description' => \t('Select which CSL value this field should be mapped to.'),
@@ -57,10 +63,21 @@ function islandora_citations_form_field_config_edit_form_alter(&$form, FormState
       ];
     }
 
+    $form['#entity_builders'][] = 'islandora_citations_field_config_edit_form_form_builder';
     return $form;
   }
 }
 
+/**
+ * Entity builder for the config edit form with third party options.
+ *
+ * @see islandora_citations_field_config_edit_form_alter()
+ */
+function islandora_citations_field_config_edit_form_form_builder($entity_type, EntityInterface $configEntity, &$form, FormStateInterface $form_state) {
+  $configEntity->setThirdPartySetting('islandora_citations', 'csl_field', $form_state->getValue('csl_field'));
+  $configEntity->setThirdPartySetting('islandora_citations', 'use_entity_checkbox', $form_state->getValue('use_entity_checkbox'));
+}
+
 /**
  * Implements hook_theme().
  */

migrations/csl_type.yml

@@ -1,101 +1,56 @@
 id: csl_type
 label: CSL Type.
 migration_tags:
-  - taxonomy
+  - dgi_taxonomy
 migration_group: islandora
 source:
   plugin: embedded_data
   data_rows:
-    -
-      name: 'article'
-    -
-      name: 'article-journal'
-    -
-      name: 'article-magazine'
-    -
-      name: 'article-newspaper'
-    -
-      name: 'bill'
-    -
-      name: 'book'
-    -
-      name: 'broadcast'
-    -
-      name: 'chapter'
-    -
-      name: 'classic'
-    -
-      name: 'collection'
-    -
-      name: 'dataset'
-    -
-      name: 'document'
-    -
-      name: 'entry'
-    -
-      name: 'entry-dictionary'
-    -
-      name: 'entry-encyclopedia'
-    -
-      name: 'event'
-    -
-      name: 'figure'
-    -
-      name: 'graphic'
-    -
-      name: 'hearing'
-    -
-      name: 'interview'
-    -
-      name: 'legal_case'
-    -
-      name: 'legislation'
-    -
-      name: 'manuscript'
-    -
-      name: 'map'
-    -
-      name: 'motion_picture'
-    -
-      name: 'musical_score'
-    -
-      name: 'pamphlet'
-    -
-      name: 'paper-conference'
-    -
-      name: 'patent'
-    -
-      name: 'performance'
-    -
-      name: 'periodical'
-    -
-      name: 'personal_communication'
-    -
-      name: 'post'
-    -
-      name: 'post-weblog'
-    -
-      name: 'regulation'
-    -
-      name: 'report'
-    -
-      name: 'review'
-    -
-      name: 'review-book'
-    -
-      name: 'software'
-    -
-      name: 'song'
-    -
-      name: 'speech'
-    -
-      name: 'standard'
-    -
-      name: 'thesis'
-    -
-      name: 'treaty'
-    -
-      name: 'Webpage'
+    - name: 'article'
+    - name: 'article-journal'
+    - name: 'article-magazine'
+    - name: 'article-newspaper'
+    - name: 'bill'
+    - name: 'book'
+    - name: 'broadcast'
+    - name: 'chapter'
+    - name: 'classic'
+    - name: 'collection'
+    - name: 'dataset'
+    - name: 'document'
+    - name: 'entry'
+    - name: 'entry-dictionary'
+    - name: 'entry-encyclopedia'
+    - name: 'event'
+    - name: 'figure'
+    - name: 'graphic'
+    - name: 'hearing'
+    - name: 'interview'
+    - name: 'legal_case'
+    - name: 'legislation'
+    - name: 'manuscript'
+    - name: 'map'
+    - name: 'motion_picture'
+    - name: 'musical_score'
+    - name: 'pamphlet'
+    - name: 'paper-conference'
+    - name: 'patent'
+    - name: 'performance'
+    - name: 'periodical'
+    - name: 'personal_communication'
+    - name: 'post'
+    - name: 'post-weblog'
+    - name: 'regulation'
+    - name: 'report'
+    - name: 'review'
+    - name: 'review-book'
+    - name: 'software'
+    - name: 'song'
+    - name: 'speech'
+    - name: 'standard'
+    - name: 'thesis'
+    - name: 'treaty'
+    - name: 'webpage'
   ids:
     name:
       type: string

src/Controller/IslandoraCitationsController.php

@@ -50,19 +50,21 @@ public function provideArguments($node_type) {
     ];
     $fields = $this->entityFieldManager->getFieldDefinitions('node', $node_type);
 
+    $rows = [];
     foreach ($fields as $field_definition) {
 
       if (!empty($field_definition->getTargetBundle())) {
         $data = $field_definition->getThirdPartySetting('islandora_citations', 'csl_field');
+        $dataForMappedEntities = $field_definition->getThirdPartySetting('islandora_citations', 'use_entity_checkbox');
         $rows[] = [$field_definition->getName(),
-          $data ? implode(',', $data) : '-',
-          [
-            'data' => new FormattableMarkup('<a href=":link">@name</a>',
-          [
-            ':link' => 'fields/node.' . $node_type . '.' . $field_definition->getName(),
-            '@name' => $this->t('Edit'),
-          ]),
-          ],
+          $data ? implode(',', $data) : ($dataForMappedEntities ? 'Mapped from entity' : '-'),
+            [
+              'data' => new FormattableMarkup('<a href=":link">@name</a>',
+                [
+                  ':link' => 'fields/node.' . $node_type . '.' . $field_definition->getName(),
+                  '@name' => $this->t('Edit'),
+                ]),
+            ],
         ];
       }
     }
@@ -92,6 +94,7 @@ public function paragraphsArguments($paragraphs_type) {
     ];
     $fields = $this->entityFieldManager->getFieldDefinitions('paragraph', $paragraphs_type->id());
 
+    $rows = [];
     foreach ($fields as $field_definition) {
       if (!empty($field_definition->getTargetBundle())) {
         $data = $field_definition->getThirdPartySetting('islandora_citations', 'csl_field');

src/Form/SelectCslForm.php

@@ -77,7 +77,7 @@ public function buildForm(array $form, FormStateInterface $form_state) {
       }
     }
     // Check default csl exist or not.
-    if (!in_array($default_csl, $cslItems)) {
+    if (!array_key_exists($default_csl, $cslItems)) {
       $default_csl = array_values($cslItems)[0];
     }
     $csl = !empty($default_csl) ? $this->getDefaultCitation($default_csl) : '';

src/IslandoraCitationsHelper.php

@@ -81,7 +81,14 @@ public function loadCslJsonSchema() {
    * Cet citations styles from config entity.
    */
   public function getCitationEntityList() {
-    return $this->citationsStorage->getQuery()->execute();
+    $citationIds = $this->citationsStorage->getQuery()->execute();
+    $citationEntities = $this->citationsStorage->loadMultiple($citationIds);
+    $citationList = [];
+    foreach ($citationEntities as $citationEntity) {
+      $citationList[$citationEntity->id()] = $citationEntity->label();
+    }
+
+    return $citationList;
   }
 
   /**

src/Normalizer/DateTimeNormalizer.php

@@ -57,9 +57,13 @@ public function normalize($datetime, $format = NULL, array $context = []) {
     assert($datetime instanceof DateTimeInterface);
     $drupal_date_time = $datetime->getDateTime()->setTimezone($this->getNormalizationTimezone());
     if ($drupal_date_time === NULL) {
-      return $drupal_date_time;
+      return NULL;
     }
+
     $date = $this->dateFormatter->format($drupal_date_time->getTimestamp(), 'custom', 'Y-m-d');
+
+    $element = [];
+
     foreach ($context['csl-map'] as $cslField) {
       $element[$cslField] = $date;
     }

src/Normalizer/NormalizerBase.php

@@ -18,8 +18,8 @@ abstract class NormalizerBase extends SerializationNormalizerBase implements Nor
   /**
    * {@inheritdoc}
    */
-  public function supportsNormalization($data, $format = NULL) {
-    return $format === static::FORMAT && parent::supportsNormalization($data, $format);
+  public function supportsNormalization($data, ?string $format = NULL, array $context = []): bool {
+    return $format === static::FORMAT && parent::supportsNormalization($data, $format, $context);
   }
 
   /**