Merge branch 'dev' into f-test-linkify

.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/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){