ENH: xlsx template generator

Summary

Allows to create XLSX templates

Focus

Test Environment

unit test (including one for all dimr schemas which is to be removed)

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related issues
• Up-to-date CHANGELOG.md (or not necessary)
• Up-to-date JSON schema (or not necessary)
• Appropriate user and developer documentation (or not necessary)
  • How do I use the software? Assume "stupid" users.
  • How do I develop or debug the software? Assume novice developers.
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md (or not necessary)
• Appropriate user and developer documentation (or not necessary)
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there specifications? Are they satisfied?

For further good practices have a look at our review guidelines.

src/doc/table-json-conversion/specs.md

+# Konversion zwischen LinkAhead-Datenmodellen, JSON-Schema und XLSX (und zurück) #
+
+Top level of json must be a dict. keys of the dict are RT names.
+
+
+Frage: is the first RT never an array?
+
+
+Do not use sheet name, but only content of hidden rows
+
+## Datenmodelle in JSON-Schema und JSON-Daten ##
+
+Das Datenmodell in LinkAhead legt fest, welche Arten von Records es in einer LinkAhead-Instanz gibt
+und wie diese aussehen. Dieses Datenmodell kann auch in einem JSON Schema repräsentiert werden, dass
+die Struktur von JSON Dateien festlegt, die zu dem Datenmodell gehörige Records enthält.
+
+Zum Beispiel kann das folgende JSON den Record einer Person beschreiben:
+
+```JSON
+{
+    "Person": {
+        "family_name": "Steve",
+        "given_name": "Stevie"
+    }
+}
+```
+
+Ein *JSON Schema* schreibt eine konkrete Struktur vor, und die zugehörige JSON Dateien können
+genutzt werden, um Daten zu bestimmten Record-Strukturen zu repräsentieren.  Beispielsweise könnte
+man ein JSON Schema erstellen, dass es erlaubt "Training" Records mit Informationen zu abgehaltenen
+Trainings zu speichern.  Dies ist insbesondere wertvoll beim Datenim- und export.  Man
+könnte Webformulare aus dem Json Schema generieren oder es nutzen, um in LinkAhead gespeicherte
+Objekte als JSON zu exportieren.
+
+## Von JSON zu XLSX: Datenrepräsentation ##
+
+Im Folgenden wird beschrieben, wie JSON Dateien, die LinkAhead-Records reprästentieren in XLSX
+Dateien umgewandelt werden, bzw. wie aus XLSX-Dateien JSON Dateien mit Records erstellt werden.
+
+Der Attributname (oben "Person") legt den RecordType fest und der Wert diese Attributs kann entweder
+ein Objekt oder eine Liste sein.  Ist es ein Objekt (wie im obigen Beispiel), so wird ein einzelner
+Record repräsentiert.  Bei einer Liste mehrere Records, die den gleichen RecordType als Parent
+haben.
+
+Die *Properties* des Records (oben `family_name` und `given_name`) werden zu *Spalten* im XLSX.  Die
+Properties haben wiederum einen Attributnamen und einen Wert.  Der Wert kann
+
+a. primitiv (Text, Zahl, Boolean, ...)
+b. ein Record
+c. eine Liste von primitiven Typen
+d. eine Liste von Records
+
+sein.
+
+In den Fällen *a.* und *c.* wird in XLSX eine Zelle in der zur Property gehörigen Spalte erstellt.
+Im Fall *b.* wird prinzipiell für die Properties des Records Spalten erstellt.  Tatsächlich wird der
+referenzierte Record genauso behandelt wie der ursprüngliche.  D.h. die Fälle a.-d. werden wieder
+für die einzelnen Properties betrachtet.
+
+Für den Fall *d.* ist die zweidimensionale Struktur eines XLSX Blatts nicht ausreichend.  Daher
+werden für solche Fälle *neue* XLSX-Blätter/-Tabellen erstellt.
+
+In diesen werden die referenzierten Records behandelt wie oben beschrieben. Es gibt jedoch
+zusätzliche Spalten die es erlauben zu erkennen, von welchem "externen" Record diese Records
+referenziert werden.
+
+Wir betrachten diese vier Fälle nun im Detail:
+
+### a. Properties mit primitiven Datentypen ###
+
+```JSON
+{
+    "Training": {
+        "date": "2023-01-01",
+        "url": "www.indiscale.com",
+        "duration": 1.0,
+        "participants": 1,
+        "remote": false
+    }
+}
+```
+Dieser Eintrag wird in einem XLSX-Blatt mit dem folgenden Inhalt abgebildet:
+
+| date       | url               | duration | participants | remote |
+|------------|-------------------|----------|--------------|--------|
+| 2023-01-01 | www.indiscale.com | 1.0      | 1            | false  |
+
+### b. Property, die einen Record referenziert ###
+
+```JSON
+{
+    "Training": {
+        "date": "2023-01-01",
+        "supervisor": {
+            "family_name": "Stevenson",
+            "given_name": "Stevie",
+        }
+    }
+}
+```
+
+Dieser Eintrag wird in einem XLSX Blatt mit dem folgenden Inhalt abgebildet:
+
+| date       | `supervisor.family_name` | `supervisor.given_name` |
+|------------|--------------------------|-------------------------|
+| 2023-01-01 | Stevenson                | Stevie                  |
+
+Beachten Sie, dass die Spaltennamen umbenannt werden dürfen.  Die Zuordnung der Spalte zu Properties
+von Records wird über den Inhalt von versteckten Zeilen gewährleistet.
+
+### c. Properties, die Listen mit Werten von primitiven Datentypen enthalten ###
+
+```JSON
+{
+    "Training": {
+        "url": "www.indiscale.com",
+        "subjects": ["Math", "Physics"],
+    }
+}
+```
+
+Dieser Eintrag würde in einem XLSX Blatt mit dem folgenden Inhalt abgebildet:
+
+| url               | subjects     |
+|-------------------|--------------|
+| www.indiscale.com | Math;Physics |
+
+Die Listenelemente werden separiert von `;` in die Zelle geschrieben.  Wenn die Elemente den
+Separator `;` enthalten, dann wird dieser mit einem `\\` escaped.
+
+### d. Properties, die Listen mit Referenzen enthalten ###
+
+```JSON
+{
+    "Training": {
+        "date": "2023-01-01",
+        "coach": [
+            {
+              "family_name": "Sky",
+              "given_name": "Max",
+            },
+            {
+              "family_name": "Sky",
+              "given_name": "Min",
+            }
+        ]
+    }
+}
+```
+
+Da die beiden Coaches nicht vernünftig in einer Zelle dargestellt werden können, bedarf es nun eines
+weiteren Tabellenblatts, das die Eigenschaften der Coaches enthält.
+
+Das Blatt zu den *Trainings* enthält in diesem Beispiel nur die "date" Spalte:
+
+| date       |
+|------------|
+| 2023-01-01 |
+
+Zusätzlich gibt es ein *weiteres* Blatt in dem die Coaches gespeichert werden.  Hier ist nun
+entscheidend, dass definiert wird, wie von potentiell mehreren "Trainings" das richtige Element
+gewählt wird.  In diesem Fall bedeutet dies, dass das "date" eindeutig sein muss.
+
+TODO: In welchem Scope gilt diese Eindeutigkeit? Können wir dies checken?
+
+Das zweite Blatt sieht dann wie folgt aus
+
+| date       | `coach.family_name` | `coach.given_name` |
+|------------|---------------------|--------------------|
+| 2023-01-01 | Sky                 | Max                |
+| 2023-01-01 | Sky                 | Min                |
+
+## Data in XLSX: Hidden automation logic ##
+
+### First column: Marker for row types ###
+
+The first column in each sheet will be hidden and it will contain an entry in each row that needs
+special treatment.  The following values are used:
+
+- ``IGNORE``: This row is ignored.  It can be used for explanatory texts or layout.
+- ``COL_TYPE``: Typically the first row that is not `IGNORE`.  It indicates the row that defines the
+  type of columns (`FOREIGN`, `SCALAR`, `LIST`, `IGNORE`).  This row may occur only once.
+- ``PATH``: Indicates that the row is used to define the path within the JSON.  These rows are
+  typically hidden for users.
+
+An example table could look like this:
+
+| `IGNORE`   |                                     | Welcome        | to this       | file!        |                    |
+| `IGNORE`   |                                     | Please         | enter your    | data here:   |                    |
+| `COL_TYPE` | `IGNORE`                            | `SCALAR`       | `SCALAR`      | `LIST`       | `SCALAR`           |
+| `PATH`     |                                     | `Training`     | `Training`    | `Training`   | `Training`         |
+| `PATH`     |                                     | `url`          | `date`        | `subjects`   | `supervisor`       |
+| `PATH`     |                                     |                |               |              | `email`            |
+| `IGNORE`   | Please enter one training per line. | Training URL   | Training date | Subjects     | Supervisor's email |
+|------------|-------------------------------------|----------------|---------------|--------------|--------------------|
+|            |                                     | example.com/mp | 2024-02-27    | Math;Physics | steve@example.com  |
+|            |                                     | example.com/m  | 2024-02-27    | Math         | stella@example.com |
+
+### Parsing XLSX data ###
+
+To extract the value of a given cell, we traverse all path elements (in ``PATH`` rows) from top to
+bottom. The final element of the path is the name of the Property to which the value belongs.  In
+the example above, `steve@example.com` is the value of the `email` Property in the path
+`["Training", "supervisor", "email"]`.
+
+The path elements are sufficient to identify the object within a JSON, at least if the corresponding
+JSON element is a single object. If the JSON element is an array, the appropriate object within the
+array needs to be selected.
+
+For this selection additional ``FOREIGN`` columns are used. The paths in these columns must all have
+the same *base* and one additional *unique key* component.  For example, two `FOREIGN` columns could
+be `["Training", "date"]` and `["Training", "url"]`, where `["Training"]` is the *base path* and
+`"date"` and `"url"` are the *unique keys*.
+
+The base path defines the table (or recordtype) to which the entries belong, and the values of the
+unique keys define the actual rows to which data belongs.
+
+For example, this table defines three coaches for the two trainings from the last table:
+
+| `COL_TYPE` | `FOREIGN`             | `FOREIGN`             | `SCALAR`               |
+| `PATH`     | `Training`            | `Training`            | `Training`             |
+| `PATH`     | `date`                | `url`                 | `coach`                |
+| `PATH`     |                       |                       | `given_name`           |
+| `IGNORE`   | Date of training      | URL of training       | The coach's given name |
+| `IGNORE`   | from sheet 'Training' | from sheet 'Training' |                        |
+|------------|-----------------------|-----------------------|------------------------|
+|            | 2024-02-27            | example.com/mp        | Ada                    |
+|            | 2024-02-27            | example.com/mp        | Berta                  |
+|            | 2024-02-27            | example.com/m         | Chris                  |