From 93ac2c7788c411c6c4675ae900024a8f12eec65e Mon Sep 17 00:00:00 2001
From: fspreck <f.spreckelsen@indiscale.com>
Date: Tue, 6 Dec 2022 16:01:47 +0100
Subject: [PATCH] DOC: Add documentation for hiding/showing of properties
---
src/doc/extension/display_of_properties.rst | 86 +++++++++++++++++++++
1 file changed, 86 insertions(+)
create mode 100644 src/doc/extension/display_of_properties.rst
diff --git a/src/doc/extension/display_of_properties.rst b/src/doc/extension/display_of_properties.rst
new file mode 100644
index 00000000..b5fdfe30
--- /dev/null
+++ b/src/doc/extension/display_of_properties.rst
@@ -0,0 +1,86 @@
+Tweaking the display of properties
+==================================
+
+Hide or show properties for specific roles and users
+****************************************************
+
+.. note::
+
+ This feature is part of CaosDB WebUI 0.10 and is not available for 0.9.X or
+ older.
+
+.. warning::
+
+ Hiding properties is purely cosmetics and should **never** be considered a
+ security feature. The hidden properties are still part of the server
+ response.
+
+Sometimes it is desirable to hide certain properties for specific users or
+roles, e.g., when they might be irrelevant or confusing. For example, an
+internal id might only be of interest to curators or administrators, whereas it
+is entirely meaningless to most other users.
+
+To configure the hiding of properties, you first need to enable the build
+variable ``BUILD_MODULE_EXT_PROPERTY_DISPLAY``. Then, the display of the
+properties is configured in ``conf/ext/json/ext_prop_display.json``. In there,
+properties of a specific RecordType can be hidden by specifying the name of the
+property, and the names of the roles and/or users from whom it should be hidden.
+
+.. code-block:: json
+
+ {
+ "RecordTypeName": {
+ "hide": [
+ {
+ "name": "property name",
+ "roles": ["list", "of", "roles"],
+ "users": ["list", "of", "users"]
+ },
+ ...
+ ]
+ },
+ ...
+ }
+
+In the same way but using the ``show`` keyword, properties can be hidden for
+everyone **but** the specified users/roles:
+
+.. code-block:: json
+
+ {
+ "RecordTypeName": {
+ "show": [
+ {
+ "name": "property name",
+ "roles": ["list", "of", "roles"],
+ "users": ["list", "of", "users"]
+ },
+ ...
+ ]
+ },
+ ...
+ }
+
+
+For example, using the data from demo.indiscale.com, the following would hide
+the ``price`` of all ``MusicalInstruments`` from ``anonymous`` and their
+``Manufacturer`` from the ``admin`` user.
+
+.. code-block:: json
+
+ {
+ "MusicalInstrument": {
+ "hide": [
+ {"name": "price", "roles": ["anonymous"], "users": []},
+ {"name": "Manufacturer", "roles": [], "users": ["admin"]}
+ ]
+ }
+ }
+
+Future
+******
+
+In the future, this feature will be extended to allow the RecordType-wise
+`sorting <https://gitlab.com/caosdb/caosdb-webui/-/issues/189>`__ of properties
+and to `toggle <https://gitlab.com/caosdb/caosdb-webui/-/issues/190>`__
+properties.
--
GitLab