From 98e9b2b0a656bc10fb1f1da3276771e00f9318e2 Mon Sep 17 00:00:00 2001
From: florian <f.spreckelsen@inidscale.com>
Date: Mon, 13 Sep 2021 13:42:36 +0200
Subject: [PATCH] DOC: Add explanation on customizing the resolving of
references
---
.gitignore | 1 +
src/doc/extension/references.rst | 38 ++++++++++++++++++++++++++++++++
2 files changed, 39 insertions(+)
create mode 100644 src/doc/extension/references.rst
diff --git a/.gitignore b/.gitignore
index f69db87a..a89ffdab 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,3 +26,4 @@ xerr.log
conf/ext
test/ext
src/ext
+*~
diff --git a/src/doc/extension/references.rst b/src/doc/extension/references.rst
new file mode 100644
index 00000000..63c55161
--- /dev/null
+++ b/src/doc/extension/references.rst
@@ -0,0 +1,38 @@
+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.
--
GitLab