osc-variant/README.md

# OSC-Variant

Anwendung zum Anpassen einer OSC-Datei an einen Standort.

## Funktion

Diese Anwendung passt die Inhalte eine OSC-Datei an, sodass (standortbezogene) Formularvarianten für Formularverweise
verwendet werden.
Weiterhin ist das Auflisten der Inhalte einer OSC-Datei möglich.

Hierzu wird die Datei deserialisiert, die entsprechenden Formularfelder ermittelt und die Formularvariante
sowie die Anzeige anhand eines Profils angepasst.

Wird in einer OSC-Datei eine noch nicht bekannte Eigenschaft erkannt, wird die weitere Bearbeitung abgebrochen, um keine
unvollständigen Ausgabedateien zu erzeugen.

### Beispiele

Zum Auflisten der Inhalte einer Datei wird folgender Befehl verwendet:

```
osc-variant list meine-beispieldatei.osc
```

Zum Auflisten der Inhalte mit allen Abhängigkeiten, z.B. Daten- und Merkmalkataloge und bei Formularen wird der Befehl
`tree` verwendet:

```
osc-variant tree meine-beispieldatei.osc
```

Achtung! Dies erzeugt eine sehr umfangreiche Ausgabe.

Zum Vergleich zweier OSC-Dateien wird der Unterbefehl `diff` verwendet.
Der optionale Parameter `--strict` vergleicht auch den Inhalt der OSC-Datei.
Ohne diesen wird nur das Vorhandensein von Inhalten und die Revision verglichen. 

```
osc-variant diff meine-beispieldatei.osc andere-beispieldatei.osc
```

bzw.

```
osc-variant diff meine-beispieldatei.osc andere-beispieldatei.osc --strict
```

Zum Anpassen des Inhalts einer Datei:

```
osc-variant modify meine-beispieldatei.osc --profile ukw-profil.yml --output ukw-beispieldatei.osc
```

Die Parameter `--profile` und `--output` sind optional.

Ohne Profildatei wird die Datei lediglich eingelesen, Leerzeichen am Ende eines XML-Tags entfernt und wieder ausgegeben.

Ohne eine Angabe der Ausgabedatei wird auf die Standardausgabe ausgegeben.

#### Kompakte Ausgabe

OSC-Dateien sind XML-Dateien. Diese Anwendung ermöglicht optional die Ausgabe als kompaktere XML-Datei ohne Zeilenumbrüche.
Hierzu ist die Option `--compact` vorgesehen. Es können, je nach Datei, bis zu 30% eingespart werden.

#### Sortierung

Bei der Auflistung der Inhalte, kann die Option `--sorted` dazu verwendet werden, die angezeigten Einträge alphabetisch zu sortieren.
Die Sortierung erfolgt dabei nach Namen des Katalogs oder des Formulars.

#### Experimentelle Funktionen

Neben den gebräuchlichen Funktionen gibt es weitere, derzeit noch experimentelle, Funktionen. 

##### Sortierung bei Modifikation

Beim Modifizieren der Inhalte kann die experimentelle Option `--x-sorted` dazu verwendet werden, die Einträge im Anschluss an die Modifikation
nach Namen zu sortieren.
Dies erlaubt eine konsistente Reihenfolge der Einträge, wodurch ein direkter Vergleich mit Vorversionen ermöglicht wird.
ACHTUNG: Es kann sein, dass dadurch ein Import der resultierenden OSC-Datei nicht mehr möglich ist, da das genaue Verhalten des Imports aktuell noch nicht bekannt ist.

##### Entfernen von Inhalten der Systembibliothek bei Modifikation

Mit der die experimentelle Option `--x-strip` ist es möglich, die in der OSC-Datei enthaltenen und beim Import nicht genutzten Inhalte aus der Systembibliothek zu entfernen.

Hierbei werden alle Inhalte entfernt, die im Ordner "ONKOSTAR Bibliothek" enthalten sind, beim Import jedoch ignoriert werden.

## Profile

Zum Erstellen von Varianten einer OSC-Datei wird eine Profildatei im YAML-Format verwendet.

In ihr sind die durchzuführenden Änderungen definiert. Eine Profildatei hat die folgende Form:

```
forms:
  - name: "ExampleForm"
    form_field:
      - name: "formularfeld"
        hide: true
    form_references:
      - name: "ref_first_mtb"
        referenced_data_form: "Formularverweis.Variante"
        anzeige_auswahl: "Referenziertes Formular vom: {Datum}"
        anzeige: "Datum im referenzierten Formular: {Datum}"
        scripts_code: |
          // Beispielcode
          console.log(getFieldValue('ref_first_mtb'));
    menu_category:
      name: Beispielformulare
      position: 1.0
      column: 0
```

Hierzu wird die Anwendung angewiesen im Formular "ExampleForm" den Formularverweis im Formularfeld "ref_first_mtb":

* den Verweis auf das Formular "Formularverweis.Variante" zu setzen
* die Anzeige im Auswahlmenü auf "Referenziertes Formular vom: {Datum}" zu setzen
* die Anzeige unterhalb des Auswahlmenüs auf "Datum im referenzierten Formular: {Datum}" zu setzen
* den Code zur Ausführung "nach Aktualisierung" für das Formularfeld auf die angegebene, mehrzeilige Zeichenkette anzupassen

und dabei die vorhandenen Angaben für den Formularverweis zu ersetzen.

Die Angaben für `referenced_data_form`, `anzeige_auswahl`, `anzeige` und `scripts_code` sind optional.
Wird keine Angabe gemacht, wird der bestehende Wert beibehalten.

Zudem wird im Formular "ExampleForm" das Formularfeld "formularfeld" ausgeblendet, indem der Filter auf "false" gesetzt wird.
Dadurch wird das Formularfeld nie angezeigt.
Ein zuvor bestehender Filter wird ersetzt.
Weiterhin wird die Eigenschaft "Speichern" des Formularfelds auf "Immer speichern" gesetzt um sicherzustellen, dass zuvor
enthaltene Daten weiterhin gespeichert bleiben und werden, auch wenn das Formularfeld nicht sichtbar ist.

**Achtung!** Diese Anwendung überprüft keine Scripts und verwendet angegebene Scripts als "valid" im resultierenden OSC-File.

Zudem kann die Menükategorie angepasst werden.
Die Angabe einer `menu_category` ist fakultativ.
Wird sie angeben, sind die Felder `name`, `position` und `column` verpflichtend.

Es können beliebig viele Formulare mit beliebig vielen Änderungen zu Formularverweisen in einer Profildatei
hinterlegt werden, jedoch ist mindestens eine Angabe zu einem Formularfeld erforderlich.

Beispiele für eine Profildatei sind unter [`examples/`](examples/) zu finden.