Add ability to copy attrs between entities by ref

- Add option to copyAttributeList to copy attributes as a linked reference
- Added EMLUtilities file to store common EML functions, like getParentEML
- Made sure that parentModel is passed down the line of sub-models correctly in eml attribute related models/collections
- Fixed logic with listeners

Issue #2652

Author: robyngit

src/js/collections/metadata/eml/EMLAttributes.js

@@ -61,22 +61,34 @@ define([
       },
 
       /**
-       * Add an attribute to the collection. Will try to set the parentModel
-       * if it is not already set.
-       * @param {object} attributes - The model attributes of the new EML
-       * attribute, optional. May include the parentModel
+       * Add an attribute to the collection. Will try to set the parentModel if
+       * it is not already set.
+       * @param {object|EMLAttribute} [attributes] - The model attributes of the
+       * new EML attribute. Should include the parentModel. Or an instance of
+       * EMLAttribute.
        * @param {object} options - Options to pass to the add method
        * @returns {EMLAttribute} The newly added attribute
        */
       addAttribute(attributes = {}, options = {}) {
+        let modifiedAttrs = attributes;
         // A parent (entity) model is required for some of Attribute's methods
-        const modifiedAttrs = { ...attributes };
-        if (!modifiedAttrs.parentModel) {
-          modifiedAttrs.parentModel = this.getParentModel();
-        }
-        if (!modifiedAttrs.xmlID) {
-          modifiedAttrs.xmlID = DataONEObject.generateId();
+        if (attributes instanceof EMLAttribute) {
+          if (!modifiedAttrs.get("parentModel")) {
+            modifiedAttrs.set("parentModel", this.getParentModel());
+          }
+          if (!modifiedAttrs.get("xmlID")) {
+            modifiedAttrs.set("xmlID", DataONEObject.generateId());
+          }
+        } else {
+          modifiedAttrs = { ...attributes };
+          if (!modifiedAttrs.parentModel) {
+            modifiedAttrs.parentModel = this.getParentModel();
+          }
+          if (!modifiedAttrs.xmlID) {
+            modifiedAttrs.xmlID = DataONEObject.generateId();
+          }
         }
+
         return this.add(modifiedAttrs, options);
       },
 
@@ -138,7 +150,7 @@ define([
        * number of attributes in the collection, the extra attributes will be
        * removed.
        * @param {string[]} names - An array of new attribute names
-       * @param {EMLEntity} parentModel - The model that contains this
+       * @param {EMLAttributeList} parentModel - The model that contains this
        * collection
        * @param {object} options - Options to pass to the add, remove, and set
        * methods

src/js/collections/metadata/eml/EMLEntities.js

@@ -7,7 +7,8 @@ define([
   "models/metadata/eml211/EMLEntity",
   "models/metadata/eml211/EMLDataTable",
   "models/metadata/eml211/EMLOtherEntity",
-], (Backbone, EMLEntity, EMLDataTable, EMLOtherEntity) => {
+  "models/DataONEObject",
+], (Backbone, EMLEntity, EMLDataTable, EMLOtherEntity, DataONEObject) => {
   // The names of the nodes that are considered entities in EML
   const ENTITY_NODE_NAMES = [
     "otherEntity",
@@ -378,8 +379,14 @@ define([
        * thrown if any attributes from the source entity are invalid. If set to
        * false, only valid attributes will be copied over, and invalid
        * attributes will be ignored.
+       * @param {boolean} [byRef] - If true, the attributes will be copied as a
+       * reference to the source attributes. Meaning that changes to the source
+       * attributes will affect the target attributes. If false (default), the
+       * attributes will have the same values as the source attributes, but will
+       * be a deep copy. This means that changes to the source attributes will
+       * not affect the target attributes.
        */
-      copyAttributeList(source, targets, errorIfInvalid = true) {
+      copyAttributeList(source, targets, errorIfInvalid = true, byRef = false) {
         if (!source || !targets) return;
 
         const sourceAttrs = source.get("attributeList");
@@ -397,26 +404,64 @@ define([
             errors.join ? errors.join("\n") : "Invalid attribute list",
           );
         }
-        const attrsStr = source.get("attributeList").serialize();
+
         targets.forEach((target) => {
-          const attrList = target.get("attributeList");
-          const emlAttrs = attrList.get("emlAttributes");
-          // Use remove rather than reset to trigger events
-          emlAttrs.remove(emlAttrs.models);
-          const attrDOM = new DOMParser().parseFromString(attrsStr, "text/xml");
-          emlAttrs.add(attrDOM, { parse: true });
-          // remove xmlID from the target attributes
-          emlAttrs.each((attr) => attr.unset("xmlID"));
-          // Reference to entity model required for attr & sub-models
-          emlAttrs.each((attr) => attr.set("parentModel", target));
-
-          // Invalid to have both attributes and references
-          if (attrList.hasReferences()) {
-            attrList.removeReferences();
+          if (!target) return;
+          if (byRef) {
+            this.copyAttributeListByRef(source, target);
+          } else {
+            this.deepCopyAttributeList(source, target);
           }
         });
       },
 
+      /**
+       * Copy the attribute list from a source entity to a target entity by
+       * reference. This means that changes to the source will be reflected in
+       * the target.
+       * @param {EMLEntity} source - The entity to copy attributes from
+       * @param {EMLEntity} target - The entity to copy attributes to
+       */
+      copyAttributeListByRef(source, target) {
+        const sourceAttrList = source.get("attributeList");
+        let sourceId = sourceAttrList.get("xmlID");
+
+        if (!sourceId) {
+          sourceId = DataONEObject.generateId();
+          sourceAttrList.set("xmlID", sourceId);
+        }
+
+        // empty the target attribute list
+        const targetAttrList = target.get("attributeList");
+        targetAttrList.setReferences(sourceId);
+      },
+
+      /**
+       * Deep copy the attribute list from a source entity to a target entity.
+       * This means that changes to the source will not be reflected in the
+       * target.
+       * @param {EMLEntity} source - The entity to copy attributes from
+       * @param {EMLEntity} target - The entity to copy attributes to
+       */
+      deepCopyAttributeList(source, target) {
+        const attrsStr = source.get("attributeList").serialize();
+        const attrList = target.get("attributeList");
+        const emlAttrs = attrList.get("emlAttributes");
+        // Use remove rather than reset to trigger events
+        emlAttrs.remove(emlAttrs.models);
+        const attrDOM = new DOMParser().parseFromString(attrsStr, "text/xml");
+        emlAttrs.add(attrDOM, { parse: true });
+        // remove xmlID from the target attributes
+        emlAttrs.each((attr) => attr.unset("xmlID"));
+        // Reference to entity model required for attr & sub-models
+        emlAttrs.each((attr) => attr.set("parentModel", target));
+
+        // Invalid to have both attributes and references
+        if (attrList.hasReferences()) {
+          attrList.removeReferences();
+        }
+      },
+
       /**
        * Get the attribute lists of all entities in the collection.
        * @returns {EMLAttributeList[]} The attribute lists of all entities in the

src/js/common/EMLUtilities.js

@@ -0,0 +1,33 @@
+"use strict";
+
+define([], () => {
+  /**
+   * @namespace EMLUtilities
+   * @description A generic utility object that contains functions used
+   * throughout MetacatUI to perform useful functions related to EML, but not
+   * used to store or manipulate any state about the application.
+   * @type {object}
+   * @since 0.0.0
+   */
+  const EMLUtilities = /** @lends EMLUtilities.prototype */ {
+    /**
+     * Climbs up the model hierarchy until it finds the EML model
+     * @param {Backbone.Model} model - The starting model
+     * @param {number} [maxTries] - The maximum number of levels to climb
+     * @returns {EML211|false} - Returns the EML 211 Model or null if not found
+     */
+    getParentEML(model, maxTries = 6) {
+      let emlModel = model.get("parentModel");
+      let tries = 0;
+
+      while (emlModel && emlModel.type !== "EML" && tries < maxTries) {
+        emlModel = emlModel.get("parentModel");
+        tries += 1;
+      }
+
+      return emlModel && emlModel.type === "EML" ? emlModel : false;
+    },
+  };
+
+  return EMLUtilities;
+});