VarReference

Kurzbeschreibung

Das XML-Element <VarReference> bindet einen Dokumentbaustein dynamisch ein.

Anders als bei <Reference> wird der Name des einzubindenden Bausteins nicht fest im XML hinterlegt, sondern während der Dokumenterzeugung aus dem Inhalt einer Variablen ermittelt.

Einordnung

Bereich: Inhalte

Schwierigkeitsgrad: ⭐⭐⭐⭐☆

Vorkenntnisse: Reference · RefParam · Variable

Siehe auch

• Reference
• RefParam
• Variable

Zweck

<VarReference> ermöglicht es, Dokumentbausteine abhängig vom Inhalt einer Variablen einzubinden.

Dadurch kann dieselbe Dokumentvorlage in unterschiedlichen fachlichen Situationen automatisch unterschiedliche Bausteine verwenden.

Die Entscheidung erfolgt während der Dokumenterzeugung.

Unterschied zu Reference

Der wichtigste Unterschied besteht darin, wie der Name des Bausteins bestimmt wird.

Arbeitsweise

Während der Dokumenterzeugung wird zunächst der Inhalt der im Attribut Path angegebenen Variablen gelesen.

Der Inhalt dieser Variablen wird anschließend als Name des einzubindenden Dokumentbausteins verwendet.

Beispielsweise:

Variable

↓

source.Y_Einzug

↓

Variableninhalt

↓

Y_Einzugsermaechtigung

↓

Einzubindender Dokumentbaustein

Der Redakteur muss den Namen des Bausteins daher nicht kennen.

Er ergibt sich vollständig aus den Daten des Auftrags.

Typisches Einsatzgebiet

Ein häufiges Einsatzgebiet sind sogenannte Beitragsbescheide.

Hier existieren häufig

• wenige eigentliche Dokumentvorlagen,
• aber eine große Anzahl fachlicher Dokumentbausteine.

Welche Bausteine benötigt werden, entscheidet bereits das vorgelagerte Fachverfahren.

Dieses stellt entsprechende Variablen bereit.

Die Rolle des Quellsystems

Die eigentliche Logik befindet sich nicht innerhalb von intracon.

Das Quellsystem entscheidet,

• welche Variablen erzeugt werden,
• welche Werte diese besitzen und
• welche Bausteine dadurch eingebunden werden.

Die Dokumentvorlage übernimmt lediglich die dynamische Einbindung.

Dadurch bleibt die XML-Vorlage vergleichsweise einfach, obwohl zahlreiche fachliche Kombinationen möglich sind.

Hinweis

Welche Variablen und Werte zur Verfügung stehen, wird vom jeweiligen Quellsystem beziehungsweise dessen Fachverantwortlichen definiert.

Diese Informationen müssen dem Redakteur bekannt sein, da sie nicht Bestandteil der Dokumentvorlage sind.

Attribute

Path

Path verweist auf die Variable, deren Inhalt den Namen des einzubindenden Dokumentbausteins liefert.

Beispiel:

<VarReference Path="source.Y_Einzug">
</VarReference>

Enthält die Variable beispielsweise

Y_Einzugsermaechtigung

wird automatisch der Dokumentbaustein

Y_Einzugsermaechtigung

eingebunden.

DefaultName

Ist die Variable leer oder kann kein passender Dokumentbaustein gefunden werden, kann alternativ ein Standardbaustein verwendet werden.

Dazu dient das Attribut DefaultName.

Hier wird direkt der Name des Dokumentbausteins angegeben.

Dadurch können Standardtexte oder Fallback-Lösungen bereitgestellt werden.

Prefix und Postfix

Mit Prefix und Postfix kann der ermittelte Bausteinname erweitert werden.

Beispiel:

Prefix

+

Variableninhalt

+

Postfix

↓

Vollständiger Bausteinname

Diese Funktion wird nur selten benötigt, bietet jedoch zusätzliche Flexibilität bei Namenskonventionen.

RefParam

Wie bei <Reference> können innerhalb einer <VarReference> auch <RefParam>-Elemente verwendet werden.

Dadurch lassen sich Parameter an den dynamisch eingebundenen Dokumentbaustein übergeben.

Somit können auch dynamische Dokumentbausteine mit individuellen Informationen versorgt werden.

Typische Einsatzgebiete

<VarReference> eignet sich insbesondere für:

• Beitragsbescheide
• fachlich unterschiedliche Dokumentvarianten
• modulare Dokumentvorlagen
• dynamische Textbausteine
• variable Dokumentinhalte

Besondere Herausforderung

Die technische Umsetzung ist vergleichsweise einfach.

Die eigentliche Herausforderung besteht darin, den Lesefluss des fertigen Dokuments über sämtliche fachlichen Kombinationen hinweg sicherzustellen.

Da unterschiedliche Datensätze unterschiedliche Dokumentbausteine einbinden können, sollte jeder Baustein so gestaltet werden, dass er sich harmonisch in das Gesamtdokument einfügt.

Best Practices

• Nur Variablen verwenden, deren mögliche Inhalte bekannt sind.
• Einen DefaultName definieren, wenn ein Standardbaustein vorgesehen ist.
• Dokumentbausteine konsistent benennen.
• Dynamische Kombinationen mit unterschiedlichen Datensätzen testen.
• Bei Bedarf Parameter über <RefParam> an den Baustein übergeben.

Developer-Tipp

<VarReference> trennt fachliche Entscheidungen vom Dokumentlayout.

Das Quellsystem entscheidet, welcher Baustein benötigt wird.

Die Dokumentvorlage entscheidet lediglich, wie dieser Baustein dargestellt wird.

XML-Wissen

<VarReference> erweitert das Konzept von <Reference> um eine dynamische Auswahl.

Dadurch kann dieselbe Dokumentvorlage unterschiedlich aufgebaut sein, obwohl ihr XML-Code unverändert bleibt.

Die eigentliche Variabilität entsteht ausschließlich durch den Inhalt der verwendeten Variablen.

Typische Fehler

Variable enthält keinen gültigen Bausteinnamen

Existiert kein Dokumentbaustein mit dem ermittelten Namen, kann kein Baustein eingebunden werden.

Ein DefaultName kann in solchen Fällen eine sinnvolle Absicherung darstellen.

Fachliche Logik in der Dokumentvorlage erwarten

Die Entscheidung, welcher Baustein verwendet wird, trifft nicht die Dokumentvorlage.

Sie wird bereits vom vorgelagerten Quellsystem getroffen.

Lesefluss nicht berücksichtigen

Da unterschiedliche Kombinationen von Dokumentbausteinen entstehen können, sollte jede fachliche Konstellation getestet werden.

Nur so lässt sich ein durchgängiger und verständlicher Dokumentaufbau sicherstellen.

Fazit

<VarReference> ermöglicht die dynamische Einbindung von Dokumentbausteinen anhand des Inhalts einer Variablen.

Dadurch können mit wenigen Dokumentvorlagen sehr viele fachliche Varianten abgebildet werden.

Die eigentliche Steuerung erfolgt durch das Quellsystem, während die Dokumentvorlage ausschließlich die Darstellung übernimmt.