Merge branch 'dev' into f-form-elements-select

src/doc/administration/comments.rst

+The comments feature of the caosdb webui
+========================================
+
+WebUI contains a feature that allows users to add comments to existing
+records.
+
+The feature is not enabled by default.
+
+You can manually activate it using the following steps: - Add a new
+RecordType (e.g. using the Edit Mode) called “Annotation” - Add a new
+RecordType called “CommentAnnotation” with parent “Annotation” - Add a
+new TEXT Property called “comment” - Add a new REFERENCE Property called
+“annotationOf”
+
+or using the following XML:
+
+.. code:: xml
+
+   <Property id="-1" name="comment" description="A comment on something." datatype="TEXT">
+   </Property>
+
+   <Property id="-2" name="annotationOf" description="The core property of the [Annotation] denoting which entity the annotation is annotating." datatype="REFERENCE">
+   </Property>
+
+    <RecordType id="-3" name="Annotation" description="Annotations annotate other entities in order to represent information about these entities without changing them. Mostly this will be comments by users on these entities or flags used by third party programs.">
+       <Property id="-2" name="annotationOf" description="The core property of the [Annotation] denoting which entity the annotation is annotating." datatype="REFERENCE" importance="OBLIGATORY">
+       </Property>
+   </RecordType>
+
+   <RecordType name="CommentAnnotation" description="CommentAnnotations represent user comments on other entities. As they are entities themselves they can be 'responded' by just annotating them with another CommentAnnotation.">
+       <Parent id="-3" name="Annotation" description="Annotations annotate other entities in order to represent information about these entities without changing them. Mostly this will be comments by users on these entities or flags used by third party programs." />
+       <Property id="-1" name="comment" description="A comment on something." datatype="TEXT" importance="OBLIGATORY">
+       </Property>
+   </RecordType>
+
+Additionally, on some servers the comment button might be disabled using
+CSS.
+
+E.g. on the demo server you would have to comment out the following
+lines in ``demoserver.css``:
+
+.. code:: css
+
+   .caosdb-new-comment-button {
+       visibility: hidden;
+   }
+
+Using the YAML-Datamodel-Interface
+----------------------------------
+
+It’s even easier to add the model using the yaml interface. Use the
+following yaml file:
+
+.. code:: yaml
+
+
+   Annotation:
+     description: Annotations annotate other entities in order to represent information about these entities without changing them. Mostly this will be comments by users on these entities or flags used by third party programs.
+     obligatory_properties:
+       annotationOf:
+         description: The core property of the [Annotation] denoting which entity the annotation is annotating.
+         datatype: REFERENCE
+
+   CommentAnnotation:
+     description: CommentAnnotations represent user comments on other entities. As they are entities themselves they can be 'responded' by just annotating them with another CommentAnnotation.
+     inherit_from_obligatory:
+       - Annotation
+     obligatory_properties:
+       comment:
+         description: A comment on something.
+         datatype: TEXT
+
+Save this file under “datamodel.yaml”.
+
+Make sure you have installed caosdb-models.
+
+Then sync the model:
+
+.. code:: python
+
+   import caosdb as db
+   from caosmodels.parser import parse_model_from_yaml
+
+   model = parse_model_from_yaml("datamodel.yaml")
+   model.sync_data_model(noquestion=True)

src/doc/administration/index.rst

+Administration
+==============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+   :hidden:
+
+   comments
+   static-snapshots

src/doc/administration/static-snapshots.md

+# Creating Static WebUI Snapshots
+
+It can be helpful to generate static snapshots of WebUI contents, e.g. for reviewing layouts or for presentation purposes. This is possible with a little bit of effort. Excitingly not only the layout can be exported, but also a lot of the javascript functionality can be maintained in the static pages.
+
+**NOTE: This manual page is currently work in progress.**
+
+## Create the static webui folder in the docker container
+
+We need a static version of the caosdb-webui. In principle it can be simply copied from e.g. a running docker container or from the public-directory. As it contains self-referencing (cyclic) symlinks a little bit of care has to be taken.
+
+### Using Docker
+
+Login to the caosdb/linkahead docker container as root:
+```bash
+docker exec -u 0 -ti linkahead /bin/bash
+```
+
+We need to be root (`-u 0`) in order to be able to create a copy of caosdb-webui within the container.
+
+Create the copy using `cp` and the option for following symlinks `-L`:
+
+```bash
+cp -L git/caosdb-server/caosdb-webui/public/ webui-copy
+```
+
+It will warn you that two symlinks (which are cyclic) cannot be created. That's fine, we will create these two symlinks later.
+
+```
+cp: cannot copy cyclic symbolic link 'git/caosdb-server/caosdb-webui/public/1602145811'  <- The number here is a "unique" build number
+cp: cannot copy cyclic symbolic link 'git/caosdb-server/caosdb-webui/public/webinterface'
+```
+
+**Please copy the build number somewhere, or make sure your terminal history does not get wiped.**
+
+Copy webui-copy from the docker container to the location where you want to store the snapshots:
+`docker cp linkahead:/opt/caosdb/webui-copy/ .`
+
+Create the two missing symlinks in webui-copy/public:
+```
+ln -s webui-copy/public webui-copy/public/1602145811
+ln -s webui-copy/public webui-copy/public/webinterface
+```
+
+You can now use the included xslt stylesheet to convert xml files to html using:
+```bash
+xsltproc webui-copy/public/webcaosdb.xsl test.xml > test.html
+```
+
+As the generated html file still contains invalid references to `/webinterface/1602145811`
+you have to replace all occurences of `/webinterface` with webui-copy/public`.

src/doc/extension/module.md

+# How to add a module to CaosDB WebUI
+The CaosDB WebUI is organized in modules which can easily be added and on a module basis enabled or disabled.
+
+There are a few steps necessary to create a new module.
+
+## Create the module file
+Create a new file in `src/core/js` starting with `ext_`. E.g. `ext_flight_preview.js`. This file should define one function that wraps every thing and which is enabled at the bottom of the file:
+
+```js
+/*
+ * ** header with license infoc
+ * ...
+ */
+
+'use strict';
+
+/**
+ * description of the module ...
+ *
+ * @module ext_flight_preview
+ * @version 0.1
+ *
+ * @requires somelibrary
+ * (pass the dependencies as arguments)
+ */
+var ext_flight_preview = function (somelibrary) {
+
+    var init = function (toolbox) {
+        /* initialization of the module */
+    }
+
+    /**
+     * doc string
+     */
+    var some_function = function (arg1, arg2) {
+    }
+
+    /* the main function must return the initialization of the module */
+    return {
+        init: init,
+    };
+//pass the dependencies as arguments here as well
+}(somelibrary);
+
+// this will be replaced by require.js in the future.
+$(document).ready(function() {
+    // use a variable starting with `BUILD_MODULE_` to enable your module
+    // the build variable has to be enabled in the `build.properties.d/` directory.
+    // Otherwise the module will not be activated.
+    if ("${BUILD_MODULE_EXT_BOTTOM_LINE}" === "ENABLED") {
+        caosdb_modules.register(ext_flight_preview);
+    }
+});
+```
+## Update xml
+Add a section to `src/core/xsl/main.xsl` to include your new file.
+
+```xsl
+<xsl:element name="script">       
+   <xsl:attribute name="src">         
+     <xsl:value-of select="concat($basepath,'webinterface/${BUILD_NUMBER}/js/ext_sss_markdown.js')"/>             
+   </xsl:attribute>     
+</xsl:element>
+```
+
+## Add to index.html in test
+If you have unittests (and you should), you need to add a line in :
+`test/core/index.html`.
+
+## Update the changelog
+
+## Create a merge request
\ No newline at end of file

src/doc/extension/xslt-debugging.md

+# XSLT Debugging
+
+The CaosDB WebUI uses [XSLT](https://en.wikipedia.org/wiki/XSLT) to transform the servers response into a web page.
+In the webui-repository these XSLT stylesheets can be found in `src/core/` and `src/core/xsl`.
+
+The XSLT stylesheet is typically interpreted on the client side, e.g. in Mozilla Firefox. Error output of the browser regarding XSLT problems are typically hard to debug. For example, Firefox typically does not print detailed information about the location of an exception in the sourcecode.
+
+So what options do we have to debug xslt stylesheets?
+
+* So called "printf-style" debugging
+* Using a different xslt processor
+
+I found this thread on Stack Overflow very helpful:
+https://stackoverflow.com/questions/218522/tools-for-debugging-xslt
+
+# "printf-style" debugging
+
+As mentioned in the Stack Overflow thread referenced above, `<xsl:message>` can be used to output debugging messages during XSLT processing.
+
+# Using different XSLT processors
+
+## xsltproc from libxslt
+
+`xsltproc` is a tool from libxslt that allows transforming XML using XSLT stylesheets on the command line. It is called using:
+```bash
+xsltproc <stylesheet> <xmlfile>
+```
+
+So a possible workflow for debugging an xslt script could be:
+* Save the test response from the server as `test.xml`.
+* Run `make` in repository `caosdb-webui`
+* Go to folder `public` in `caosdb-webui`
+* Run: `xsltproc webcaosdb.xsl test.xml`

src/doc/index.rst

@@ -10,6 +10,7 @@ Welcome to the documentation of CaosDB's web UI!
    Getting started <getting_started>
    Tutorials <tutorials/index>
    Concepts <concepts>
+   administration/index.rst
    Extending the UI <extension>
    API <api/index>