Merge branch 'f-form-doc' into 'main'

DOC: enhance documentation on how to create forms in the webui

See merge request !126

src/doc/extension/forms.rst

@@ -49,14 +49,26 @@ As the generated form is a plain HTML form, the javascript form API can be used.
 Placing the form in a panel below the navbar
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-There are functions in the `form_panel` module to make it easy to place forms at the typical location: 
-below the navbar. The following shows how the config (see above) is passed to 
-`init_show_form_panel_button`  a direct call to `make_form` is no longer necessary.
+There are functions in the ``form_panel`` module to make it easy to place forms at the typical location:
+below the navbar. The following shows how the config (``csv_form_config``, see above) is passed to
+``init_show_form_panel_button``. A direct call to `make_form` is no longer necessary.
 
 .. code-block:: javascript
 
     const title = "Upload CSV File"; // title of the form and text in the toolbox
     const panel_id = "csv_upload_form_panel";
+    const accepted_file_formats = [".csv"]
+    const csv_form_config = {
+        fields: [{
+            type: "file",
+            name: "csvfile",
+            label: "Upload CSV file",
+            required: true,
+            cached: false,
+            accept: accepted_file_formats.join(","),
+            help: "Select JSON export that you want to upload."
+        }],
+    };
 
     /**
      * Add a button to the navbar, saying "Upload CSV File" which opens a
@@ -75,36 +87,37 @@ below the navbar. The following shows how the config (see above) is passed to
         init_show_form_panel_button();
     }
 
+This example also illustrates how you can add a file upload to the form.
+
 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.
+If you intend to call a server-side script, the config has to be changed a litte bit:
+name the script which is to be called in the ``script`` field.
 
 .. code-block:: javascript
 
     const config = {
         script: "process.py",
         fields: [
-            { type: "reference_drop_down", name: "experiment_id", label: "Experiment", query: "FIND 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 },
+            { type: "integer", name: "number", label: "A Number", required: true }
         ],
     };
-    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",
+      "number": "400"
     }
 
-For more and advanced options for the form see the :doc:`API documentation <../api/module-form_elements>`
+Please refer to the `server side scripting documentation
+<https://docs.indiscale.com//caosdb-server/administration/server_side_scripting.html>`_
+to learn how to use form data and uploaded files within a server side script.
 
 
+API Documentation
+--------
+
+For more and advanced options for the form see the :doc:`API documentation <../api/module-form_elements>`