Merge branch 'f-person-reference' into 'dev'

Document reference resolver and move person resolving to separate example

See merge request !41

.gitignore

@@ -26,3 +26,4 @@ xerr.log
 conf/ext
 test/ext
 src/ext
+*~

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added warnings to inform about minimum width when accessing tour and
   edit mode on small screens.
 - Added a tutorial for the edit mode to the documentation
+- Documentation on how to customize reference resolving
 
 ### Changed (for changes in existing functionality)
 
@@ -26,6 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   dropped entirely (e.g. "jumbotron"). Please have a look at
     * https://getbootstrap.com/docs/5.0/migration/
     * https://getbootstrap.com/docs/4.6/migration/
+- Moved the resolving of references to Person Records to separate
+  example which can be disabled
 
 ### Deprecated (for soon-to-be removed features)
 

build.properties.d/00_default.properties

@@ -42,7 +42,6 @@
 # Modules enabled/disabled by default
 ##############################################################################
 BUILD_MODULE_EXT_PREVIEW=ENABLED
-BUILD_MODULE_EXT_RESOLVE_REFERENCES=ENABLED
 BUILD_MODULE_EXT_SSS_MARKDOWN=DISABLED
 BUILD_MODULE_EXT_TRIGGER_CRAWLER_FORM=DISABLED
 BUILD_MODULE_EXT_AUTOCOMPLETE=ENABLED
@@ -55,6 +54,9 @@ BUILD_MODULE_EXT_ANNOTATION=ENABLED
 BUILD_MODULE_USER_MANAGEMENT=ENABLED
 BUILD_MODULE_USER_MANAGEMENT_CHANGE_OWN_PASSWORD_REALM=CaosDB
 
+BUILD_MODULE_EXT_RESOLVE_REFERENCES=ENABLED
+BUILD_EXT_REFERENCES_CUSTOM_RESOLVER=person_reference
+
 ##############################################################################
 # Navbar properties
 ##############################################################################

src/core/js/ext_references.js

@@ -273,22 +273,6 @@ var resolve_references = new function () {
     }
 
 
-    /**
-     * Return the name of a person as firstname + lastname
-     */
-    this.get_person_str = function (el) {
-        var valpr = getProperties(el);
-        if (valpr == undefined) {
-            return;
-        }
-        return valpr.filter(valprel =>
-                valprel.name.toLowerCase() == "firstname")[0].value +
-            " " +
-            valpr.filter(valprel => valprel.name.toLowerCase() ==
-                "lastname")[0].value;
-    }
-
-
     /**
      * Return true iff the entity has at least one direct parent named `par`.
      *
@@ -318,6 +302,18 @@ var resolve_references = new function () {
     /**
      * Return a reference_info for an entity.
      *
+     * You may add your own custom resolver by specifying a JS module
+     * via the `BUILD_EXT_REFERENCES_CUSTOM_RESOLVER` build
+     * variable. The custom resolver has to be a JS module (typically
+     * located at caosdb-webui/src/ext/js), the name of which is given
+     * as the value of `BUILD_EXT_REFERENCES_CUSTOM_RESOLVER`. It has
+     * to provide a `resolve` function that takes the entity id to be
+     * resolved as a string and returns a `reference_info` object with
+     * the resolved custom reference as a `text` property.
+     *
+     * See caosdb-webui/src/ext/js/person_reference_resolver.js for an
+     * example.
+     *
      * TODO refactor to be configurable.  @async @param {string} id - the id of
      * the entity which is to be resolved.  @return {reference_info}
      */
@@ -345,8 +341,6 @@ var resolve_references = new function () {
       var pths = getEntityHeadingAttribute(entity, "path")
     .split("/");
       ret["text"] = pths[pths.length - 1];
-        } else if (par.name === "Person") {
-            ret["text"] = this.get_person_str(entity);
   } else if (par.name === "TestReferenced" && typeof resolve_references.test_resolver === "function") {
       // this is a test case, initialized by the test suite.
       ret = resolve_references.test_resolver(entity);

src/doc/extension/references.rst

+Customizing the display of referenced entities
+=============================================
+
+CaosDB WebUI supports the customized display of referenced entities
+using the :doc:`ext_references <../api/module-resolve_references>`
+module. The ``BUILD_MODULE_EXT_RESOLVE_REFERENCES`` build variable has
+to be set to ``ENABLED`` (see :doc:`/getting_started`) in order to use
+this module.
+
+You may then define your own JavaScript module to define how
+references to specific Records should be resolved. The module has to
+be located at a directory which is known to CaosDB WebUI; we recommend
+``caosdb-webui/src/ext/js``. Set the value of the
+``BUILD_EXT_REFERENCES_CUSTOM_RESOLVER`` build variable to the name of
+this module. The module has to have a ``resolve`` function which takes
+an entity id as its only parameter and returns a ``reference_info``
+object with the resolved custom reference as a ``text`` property. So
+the basic structure of the module should look like
+
+.. code-block:: javascript
+
+   var my_reference_resolver = new function () {
+       // Has to be called ``resolve`` and has to take exactly one
+       // string parameter: the id of the referenced entity.
+       this.resolve = async function (id) {
+	   /*
+	    * find the string that the reference should be resolved to,
+	    * e.g., from the value of the entity's properties.
+	    */
+	   return {"text": new_reference_text}
+       }
+   }
+
+An example is located in
+``caosdb-webui/src/ext/js/person_reference_resolver.js``. It resolves
+any reference to a ``Person`` Record to the value of its ``firstname``
+and ``lastname`` properties separated by a space and is active by
+default.

src/ext/js/person_reference_resover.js

+/*
+ * ** header v3.0
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2021 IndiScale GmbH (info@indiscale.com)
+ * Copyright (C) 2021 Florian Spreckelsen (f.spreckelsen@indiscale.com)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * ** end header
+ */
+
+/**
+ * @module person_reference
+ *
+ * Replace the reference to a Person Record by the values of that
+ * Record's firstname and lastname properties.
+ *
+ * TODO: Make name(s) of person RecordType(s) and names of firstname
+ * and lastname properties configurable.
+ */
+var person_reference = new function () {
+
+    var logger = log.getLogger("person_reference");
+
+    const lastname_prop_name = "lastname"
+    const firstname_prop_name = "firstname"
+    const person_rt_name = "Person"
+
+    /**
+     * Return the name of a person as firstname + lastname
+     */
+    this.get_person_str = function (el) {
+  var valpr = getProperties(el);
+  if (valpr == undefined) {
+      return;
+  }
+  return valpr.filter(valprel =>
+      valprel.name.toLowerCase().trim() ==
+    firstname_prop_name.toLowerCase())[0].value +
+      " " +
+      valpr.filter(valprel => valprel.name.toLowerCase().trim() ==
+       lastname_prop_name.toLowerCase())[0].value;
+    }
+
+    this.resolve = async function (id) {
+
+  const entity = (await resolve_references.retrieve(id))[0];
+
+  if (resolve_references.is_child(entity, person_rt_name)) {
+      return {"text": person_reference.get_person_str(entity)};
+  }
+    }
+}

test/core/js/modules/ext_references.js.js

@@ -104,7 +104,7 @@ QUnit.test("is_child", function(assert){
 });
 
 QUnit.test("get_person_str", function(assert){
-    assert.ok(resolve_references.get_person_str);
+    assert.ok(person_reference.get_person_str);
 });
 
 QUnit.test("update_visible_references_without_summary", async function(assert){