Anweisungen

Anweisungen verknüpfen Komponenten über Sektions- und Kapitelgrenzen hinweg: Eine Sektion speichert Werte unter einem Schlüssel, andere Sektionen holen sie wieder ab und füllen damit ihre eigenen Komponenten automatisch aus.

Damit lassen sich Stammdaten - Kundennummer, Anlagenname, Standort, Prüfer - einmal erfassen und in allen weiteren Sektionen automatisch bereitstellen, ohne dass der Anwender sie erneut eintippt.

Inhalt

1. Die Datenwolke
2. Wo Anweisungen konfiguriert werden
3. setValue: Werte speichern
4. getValue: Werte abholen
5. Durchgerechnetes Beispiel
6. Wann Anweisungen ausgeführt werden
7. Was der Anwender im Dokument sieht
8. Gut zu wissen

Die Datenwolke

Alle Anweisungen arbeiten auf einem gemeinsamen Speicher, der Datenwolke. Sie gilt für das gesamte geöffnete Dokument:

• Eine setValue-Anweisung speichert den Wert einer Komponente unter einem Schlüssel in der Datenwolke.
• Eine getValue-Anweisung holt ihn dort wieder ab.

Man kann sich die Datenwolke wie ein schwarzes Brett vorstellen, an dem jede Sektion ihre Werte aushängt und andere Sektionen sie abholen.

Der Schlüssel ist typischerweise ein fachlicher Wert - eine Anlagen-, Kunden- oder Prüfnummer. Dadurch finden sich Sektionen, die fachlich zusammengehören, ohne dass sie fest miteinander verdrahtet werden müssten.

Sektion "Kopfdaten"                                      Sektion "Pruefung1"

  anlagennummer  = 4711  ─┐                          ┌─► anlagenName  (wird gefüllt)
  anlagenName            ─┼─ setValue ─► [ 4711 ] ───┤
  standort               ─┘                 ▲        └─► standort     (wird gefüllt)
                                            │
                                    Schlüssel = Wert
                                    von "anlagennummer"

Was in der Datenwolke liegt, ist immer dreistufig aufgebaut:

{
  "4711": {
    "Kopfdaten": {
      "anlagenName": "Kesselhaus Nord",
      "standort": "Werk 2 / Halle 3"
    }
  }
}

Mehrere Sektionen können unter demselben Schlüssel speichern - dann stehen auf Ebene 2 mehrere Einträge nebeneinander. Alles, was unter einem Schlüssel liegt, wird im Folgenden als Bündel bezeichnet.

Wo Anweisungen konfiguriert werden

Anweisungen gehören zu einer Sektion und werden im Template-Editor gepflegt:

Template bearbeiten → Schritt 2 „Aufbau” → Sektion bearbeiten → Schaltfläche „Komponenten Anweisungen”

Es öffnet sich das Fenster Anweisungen mit einer Liste aller Anweisungen der Sektion:

Über Anweisung hinzufügen wird eine neue Zeile angelegt und sofort zum Bearbeiten geöffnet. Das Bearbeitungsformular enthält:

Die Reihenfolge der Anweisungen ist fachlich relevant: Innerhalb einer Sektion werden sie von oben nach unten abgearbeitet. Sie lässt sich per Ziehgriff ändern, solange keine Anweisung gerade bearbeitet wird.

Mit Übernehmen wird die Liste in die Sektion geschrieben; anschließend das Template wie gewohnt speichern.

setValue: Werte speichern

Eine setValue-Anweisung legt einen Wert in der Datenwolke ab.

• Source = was gespeichert wird
• Target = unter welchem Schlüssel es liegt

Source

Der Eintrag aus Source wird gleichzeitig zum Namen des Wertes auf Ebene 3 der Datenwolke - bei Platzhaltern einschließlich des $. Ein mit $sectionName gespeicherter Wert heißt in der Datenwolke also "$sectionName".

Target

Beispiel

Drei Anweisungen in der Sektion Kopfdaten:

[
  { "type": "setValue", "source": "anlagenName",  "target": "$anlagennummer" },
  { "type": "setValue", "source": "standort",     "target": "$anlagennummer" },
  { "type": "setValue", "source": "$sectionName", "target": "$anlagennummer" }
]

Ergibt in der Datenwolke (bei anlagennummer = 4711):

{
  "4711": {
    "Kopfdaten": {
      "anlagenName": "Kesselhaus Nord",
      "standort": "Werk 2 / Halle 3",
      "$sectionName": "Kopfdaten"
    }
  }
}

Die dritte Anweisung speichert bewusst eine Kennung, mit der sich das Bündel später gezielt filtern lässt - siehe Filter.

getValue: Werte abholen

Eine getValue-Anweisung holt einen Wert aus der Datenwolke und schreibt ihn in eine Komponente.

Source

Steht in anlagennummer der Wert 4711, so schlägt $anlagennummer das Bündel "4711" nach.

Params

Vor der Auswertung werden leere Werte und leere Sektionen aus dem Bündel entfernt. Danach entscheidet der Schalter Array:

Filter

Der Filter schränkt die Liste der Sektionen ein, bevor Index greift. Er wird als JSON-Objekt angegeben; alle enthaltenen Bedingungen müssen zutreffen:

{"$sectionName": "Kopfdaten"}

Ist der Wert einer Bedingung eine Liste, genügt es, wenn der gespeicherte Wert einer der Einträge ist:

{"$sectionType": ["Kopf", "Deckblatt"]}

Gefiltert wird immer über Werte, die auch tatsächlich gespeichert wurden. Damit ein Filter greifen kann, muss die speichernde Sektion die passende Kennung also per setValue mit in die Datenwolke legen.

Durchgerechnetes Beispiel

Ziel: Anlagenname und Standort werden einmal in den Kopfdaten erfasst und erscheinen in jeder Prüfsektion automatisch.

Aufbau

Kapitel Anlage mit den Sektionen Kopfdaten und Pruefung1:

Anweisungen in der Sektion Kopfdaten

[
  { "type": "setValue", "source": "anlagenName",  "target": "$anlagennummer" },
  { "type": "setValue", "source": "standort",     "target": "$anlagennummer" },
  { "type": "setValue", "source": "$sectionName", "target": "$anlagennummer" }
]

Anweisungen in der Sektion Pruefung1

[
  {
    "type": "getValue",
    "source": "$Kopfdaten.anlagennummer",
    "target": "anlagenName",
    "params": {
      "name": "anlagenName",
      "array": true,
      "index": 0,
      "filter": { "$sectionName": "Kopfdaten" }
    }
  },
  {
    "type": "getValue",
    "source": "$Kopfdaten.anlagennummer",
    "target": "standort",
    "params": {
      "name": "standort",
      "array": true,
      "index": 0,
      "filter": { "$sectionName": "Kopfdaten" }
    }
  }
]

Was dabei passiert

Der Anwender trägt in den Kopfdaten 4711, Kesselhaus Nord und Werk 2 / Halle 3 ein. In der Datenwolke steht:

{
  "4711": {
    "Kopfdaten": {
      "anlagenName": "Kesselhaus Nord",
      "standort": "Werk 2 / Halle 3",
      "$sectionName": "Kopfdaten"
    }
  }
}

Beim Wechsel in Pruefung1 läuft die erste getValue-Anweisung:

1. Source $Kopfdaten.anlagennummer → Wert 4711 → Schlüssel des Bündels
2. Bündel "4711" holen und leere Einträge entfernen
3. Als Liste der Sektionen betrachten: [ Kopfdaten ]
4. Filter {"$sectionName": "Kopfdaten"} → der Eintrag bleibt erhalten
5. Index 0 → das Wertepaket der Sektion Kopfdaten
6. Name anlagenName → "Kesselhaus Nord"
7. Der Wert wird in die Komponente anlagenName der Sektion Pruefung1 geschrieben

Für weitere Prüfsektionen werden dieselben beiden Anweisungen einfach kopiert.

Wann Anweisungen ausgeführt werden

Anweisungen laufen automatisch, während ein Dokument bearbeitet wird:

1. Beim Öffnen des Dokuments und bei jedem Sektionswechsel wird die Datenwolke geleert.
2. Alle setValue-Anweisungen aller Sektionen des Dokuments werden ausgeführt - die Datenwolke ist damit vollständig.
3. Die getValue-Anweisungen der aktuellen Sektion werden ausgeführt und füllen deren Komponenten.
4. Anschließend laufen die setValue-Anweisungen erneut. Dadurch können soeben abgeholte Werte direkt weitergespeichert werden - Ketten aus getValue → setValue funktionieren also innerhalb desselben Durchlaufs.

Aufräumen bei geänderten Quellen

Ändert sich der Wert einer Quelle oder wird eine Sektion bzw. ein Kapitel gelöscht, prüft flexiDok zusätzlich alle Sektionen darauf, ob automatisch gefüllte Komponenten noch zu ihrer Quelle passen. Dabei gilt:

• Eine automatisch gefüllte Komponente wird geleert, wenn ihre Quelle nun einen anderen Wert liefert oder gar nicht mehr auffindbar ist.
• Eine leere Komponente wird beim Aufräumen nie automatisch befüllt - das geschieht erst, wenn der Anwender die Sektion betritt.
• Betrifft das Leeren eine als Pflicht gekennzeichnete Komponente, wird die Sektion als unvollständig markiert.
• Kaskaden werden mit aufgelöst: Leert das Aufräumen eine Komponente, die ihrerseits Quelle für eine weitere Komponente ist, wird auch diese geprüft.

Sind Komponenten geleert worden, erscheint der Hinweis Betroffene Sektionen mit einer Liste der betroffenen Sektionen. Dieser Hinweis meldet jede automatische Bereinigung - auch dann, wenn sie fachlich völlig korrekt ist.

Was der Anwender im Dokument sieht

Jede Komponente, die Ziel einer getValue-Anweisung der gerade geöffneten Sektion ist, wird im Dokument mit einem @-Symbol gekennzeichnet. Der Tooltip dazu lautet Feld wird automatisch ausgefüllt.

So ist auf einen Blick erkennbar, welche Angaben aus einer anderen Sektion stammen und nicht von Hand gepflegt werden müssen.

Gut zu wissen

Bei getValue muss die Quelle mit $ beginnen

Source ohne führendes $ wird bei getValue nicht als Verweis erkannt - die Zielkomponente bleibt dann leer. Richtig ist $anlagennummer bzw. $Kopfdaten.anlagennummer.

Ziel und Quelle haben feste Reichweiten

• Das Ziel einer getValue-Anweisung muss immer in derselben Sektion liegen wie die Anweisung.
• Verweise der Form $sektion.komponente reichen genau eine Ebene weit: in eine andere Sektion desselben Kapitels. Kapitelübergreifende Verweise dieser Art gibt es nicht.
• Kapitelübergreifend arbeiten lässt sich trotzdem - über den Schlüssel: Die Datenwolke gilt für das ganze Dokument, deshalb erreicht ein unter 4711 gespeicherter Wert jede Sektion, die unter 4711 nachschlägt.

Gleiche Schlüssel treffen sich

Weil die Datenwolke für das ganze Dokument gilt, landen identische Schlüssel aus verschiedenen Kapiteln im selben Bündel. Das ist der eigentliche Nutzen des Verfahrens - aber auch eine Fehlerquelle: Ein fester Schlüssel wie stammdaten sammelt die Werte aller Sektionen ein, die ihn verwenden. Fachliche Nummern als Schlüssel sind deshalb meist die bessere Wahl.

Lieber Filter als feste Indizes

Sektionen, die nichts (mehr) speichern, fallen aus dem Bündel heraus - die Positionen der übrigen Einträge verschieben sich dadurch. Ein fest eingetragener Index greift dann auf die falsche Sektion zu. Robuster ist es, in der speichernden Sektion eine Kennung (etwa $sectionName) mitzuschicken und beim Abholen darüber zu filtern; Index steht dann in der Regel auf 0.

Mehrfachauswahlen verhalten sich je nach Auswahlmenge unterschiedlich

Werte aus Mehrfachauswahlen werden als Liste gespeichert. Enthält die Liste genau einen Eintrag, wird dieser einzeln gespeichert; ist sie leer, wird nichts gespeichert. Eine Zielkomponente bekommt also je nach Auswahl unterschiedliche Formen - bei der Konfiguration einplanen.

Leere Quellen liefern nichts

Ist die Quellkomponente leer, existiert kein Schlüssel und es wird nichts abgeholt; die Zielkomponente bleibt leer. Automatische Übernahmen setzen also voraus, dass der Anwender den Schlüsselwert zuerst erfasst - es lohnt sich, die entsprechende Komponente im Template möglichst weit vorne und als Pflicht einzuplanen.

Fehlkonfigurationen fallen nicht auf

Eine falsch konfigurierte Anweisung erzeugt keine Fehlermeldung - die Zielkomponente bleibt einfach leer. Wenn eine Übernahme nicht funktioniert, sollte in dieser Reihenfolge geprüft werden:

1. Ist das Target der getValue-Anweisung eine Komponente derselben Sektion? Stimmt die Schreibweise des technischen Komponentennamens?
2. Beginnt Source mit $ und existiert die Quellkomponente (bzw. die Sektion) im selben Kapitel?
3. Ist die Quelle gefüllt? Ohne Wert gibt es keinen Schlüssel.
4. Stimmen der Ziel-Schlüssel der setValue-Anweisung und die Quelle der getValue-Anweisung wirklich überein?
5. Passt Name in den Parametern zum Source der speichernden setValue-Anweisung?
6. Ist Array aktiviert und der Index korrekt - oder greift ein zu enger Filter?

Parameter gelten nur für getValue

Bei setValue-Anweisungen können Parameter zwar eingetragen werden, sie werden aber weder ausgewertet noch in der Übersicht angezeigt.