Add documentation on the forms module

.gitignore

@@ -15,6 +15,9 @@
 /build
 __pycache__
 
+# auto-generated sources
+/src/doc/api
+
 # screen logs
 screenlog.*
 xerr.log

README_SETUP.md

@@ -81,5 +81,6 @@ Build documentation in `build/` with `make doc`.
 - sphinx
 - sphinx-autoapi
 - jsdoc (`npm install jsdoc`)
+- jsdoc-sphinx  (`npm install jsdoc-sphinx`)
 - sphinx-js
 - recommonmark

src/core/js/ext_bottom_line.js

@@ -23,6 +23,28 @@
 
 'use strict';
 
+/**
+ * @typedef {BottomLineConfig}
+ * @property {string|HTMLElement} fallback - Fallback content if none of
+ *     the creators are applicable.
+ * @property {string} version - the version of the configuration which must
+ *     match this module's version.
+ * @property {CreatorConfig[]} creators - an array of creators.
+ */
+
+/**
+ * @typedef {CreatorConfig}
+ * @property {string} [id] - a unique id for the creator. optional, for
+ *     debuggin purposes.
+ * @property {function|string} is_applicable - If this is a string this has
+ *     to be valid javascript! An asynchronous function which accepts one
+ *     parameter, an entity in html representation, and which returns true
+ *     iff this creator is applicable for the given entity.
+ * @property {string} create - This has to be valid javascript! An
+ *     asynchronous function which accepts one parameter, an entity in html
+ *     representation. It returns a HTMLElement or text node which will be
+ *     shown in the bottom line container iff the creator is applicable.
+ */
 
 /**
  * Add a special section to each entity one the current page where a thumbnail,
@@ -45,6 +67,7 @@
  * @requires UTIF (from utif.js library)
  * @requires ext_table_preview (module from ext_table_preview.js)
  */
+
 var ext_bottom_line = function($, logger, is_in_view_port, load_config, getEntityPath, connection, UTIF, ext_table_preview) {
 
     /**
@@ -52,28 +75,7 @@ var ext_bottom_line = function($, logger, is_in_view_port, load_config, getEntit
      *     (entity) Note: This property can as well be a
      *     javascript string which evaluates to a function.
      */
-    /**
-     * @type {BottomLineConfig}
-     * @property {string|HTMLElement} fallback - Fallback content if none of
-     *     the creators are applicable.
-     * @property {string} version - the version of the configuration which must
-     *     match this module's version.
-     * @property {CreatorConfig[]} creators - an array of creators.
-     */
 
-    /**
-     * @type {CreatorConfig}
-     * @property {string} [id] - a unique id for the creator. optional, for
-     *     debuggin purposes.
-     * @property {function|string} is_applicable - If this is a string this has
-     *     to be valid javascript! An asynchronous function which accepts one
-     *     parameter, an entity in html representation, and which returns true
-     *     iff this creator is applicable for the given entity.
-     * @property {string} create - This has to be valid javascript! An
-     *     asynchronous function which accepts one parameter, an entity in html
-     *     representation. It returns a HTMLElement or text node which will be
-     *     shown in the bottom line container iff the creator is applicable.
-     */
 
     /**
      * Check if an entity has a path attribute and one of a set of extensions.
@@ -547,6 +549,9 @@ var ext_bottom_line = function($, logger, is_in_view_port, load_config, getEntit
 
     }
 
+    /**
+     * @exports ext_bottom_line
+     */
     return {
         previewShownEvent: previewShownEvent,
         previewReadyEvent: previewReadyEvent,

src/doc/Makefile

@@ -33,8 +33,9 @@ BUILDDIR       = ../../build/doc
 
 # npm is not always in the global PATH
 NPM_PATH = $(shell npm bin)
+NPM_PREFIX = $(shell npm prefix)
 
-.PHONY: doc-help Makefile apidoc
+.PHONY: doc-help Makefile api
 
 # Put it first so that "make" without argument is like "make help".
 doc-help:
@@ -42,10 +43,9 @@ doc-help:
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
+%: Makefile api
 	PATH=$(NPM_PATH):$$PATH $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 #	sphinx-build -M html . ../../build/doc
 
-# Not necessary in this repository, apidoc is doone with the sphinx-autoapi extension
-# apidoc:
-# 	@$(SPHINXAPIDOC) -o _apidoc --update --title="CaosDB Server" ../main/
+api:
+	PATH=$(NPM_PATH):$$PATH jsdoc -t $(NPM_PREFIX)/node_modules/jsdoc-sphinx/template -d $@ -r "../../src/core"

src/doc/conf.py

@@ -41,13 +41,15 @@ release = '0.x.y-beta-rc2'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx_js',
+#    'sphinx_js',
     'sphinx.ext.todo',
     "sphinx.ext.autodoc",
-    'autoapi.extension',
+#    'autoapi.extension',
     "recommonmark",            # For markdown files.
     "sphinx_rtd_theme",
-    # 'sphinx.ext.intersphinx',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig',
     # 'sphinx.ext.napoleon',     # For Google style docstrings
 ]
 
@@ -207,3 +209,4 @@ autodoc_default_options = {
 
 autoapi_type = 'javascript'
 autoapi_dirs = ['../core/js/']
+autoapi_add_toctree_entry = False

src/doc/extension.rst

+
+Extending the CaosDB Web Interface
+==================================
+
+Here we collect information on how to extend the web interface as a developer.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   extension/*
+
+

src/doc/extension/forms.rst

+
+Creating forms for the CaosDB Web Interface
+===========================================
+
+The ``form_elements`` module provides a library for generating forms from simple config objects. The forms are styled for the seamless integration into the CaosDB web interface and are especially useful for calling server side scripts.
+
+See also the :doc:`API documentation <../api/module-form_elements>`
+
+Examples
+--------
+
+Generating a generic form
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following code snippet adds a form to the body of the HTML document.
+
+.. code-block:: javascript
+
+    function my_special_submit_handler (form) {
+        // handle form submision
+    };
+    const config = {
+        name: "my_form",
+        fields: [
+            { type: "reference_drop_down", name: "experiment_id", label: "Experiment", query: "FIND Record Experiment", required: true },
+            { type: "integer", name: "number", label: "A Number", required: true },
+            { type: "date", name: "date", label: "A Date", required: false },
+            { type: "text", name: "comment", label: "A Comment", required: false },
+        ],
+        submit: my_special_submit_handler
+    };
+    const form = form_elements.make_form(config);
+    $("body").append(form);
+
+The form has four fields:
+
+    1. A drop-down menu which contains all Records of type "Experiment" as options,
+    2. an integer field, labeled "A Number",
+    3. a date field, labeled "A Date", and
+    4. a text field, labeled "A Comment".
+
+The first two fields are required and the form cannot be submitted without it. The latter are optional.
+
+On submission, the function ``my_special_submit_handler`` is being called with the form element as only parameter.
+
+As the generated form is a plain HTML form, the javascript form API can be used. However, there are special methods in the ``form_elements`` module e.g. :doc:`get_fields <../api/module-form_elements>` which are especially designed to interact with the forms generated by the ``make_form`` factory.
+
+Calling a server-side script
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you intend to call a server-side script, the config has to be changed a litte bit and the script calling is done by the ``form_elements`` module. There is no need to define the submit_hander anymore. Instead, just name the script which is to be called.
+
+.. code-block:: javascript
+
+    const config = {
+        script: "process.py",
+        fields: [
+            { type: "reference_drop_down", name: "experiment_id", label: "Experiment", query: "FIND Record Experiment", required: true },
+            { type: "integer", name: "number", label: "A Number", required: true },
+            { type: "date", name: "date", label: "A Date", required: false },
+            { type: "text", name: "comment", label: "A Comment", required: false },
+        ],
+    };
+    const form = form_elements.make_form(config);
+    $("body").append(form);
+
+On submission, the form data will be send as a json file to the script and passed as the first parameter. The call would look like ``./process.py form.json`` and the file would contain, for example,
+
+.. code-block:: json
+
+    {
+      "experiment_id": "234234",
+      "number": "400",
+      "date": "2020-12-24",
+      "comment": "This is a comment",
+    }
+
+For more and advanced options for the form see the :doc:`API documentation <../api/module-form_elements>`
+
+

src/doc/index.rst

@@ -10,7 +10,8 @@ Welcome to the documentation of CaosDB's web UI!
    Getting started <getting_started>
    Tutorials <tutorials/index>
    Concepts <concepts>
-   API Index<genindex>
+   Extending the UI <extension>
+   API <api/index>
 
 
 This documentation helps you to :doc:`get started<getting_started>`, explains the most important

test/docker/Dockerfile

@@ -13,4 +13,5 @@ RUN pip3 install pandas xlrd==1.2.0
 RUN pip3 install git+https://gitlab.com/caosdb/caosdb-advanced-user-tools.git@dev
 # For automatic documentation
 RUN npm install -g jsdoc
+RUN npm install -g jsdoc-sphinx
 RUN pip3 install sphinx-js sphinx-autoapi recommonmark sphinx-rtd-theme