Docs

Developer

XML

Inhalte

Reference / Bausteine

Reference

Kurzbeschreibung

Das XML-Element <Reference> bindet einen vorhandenen Dokumentbaustein in die aktuelle Dokumentvorlage ein.

Dadurch können wiederkehrende Inhalte zentral gepflegt und mehrfach verwendet werden.

Dokumentbausteine gehören zu den wichtigsten Konzepten innerhalb von intracon:bk, da sie die Wiederverwendbarkeit und Wartbarkeit von Dokumentvorlagen erheblich verbessern.

Einordnung

Bereich: Inhalte

Schwierigkeitsgrad: ⭐⭐⭐☆☆

Vorkenntnisse: Block, Content, Variable

Empfohlener nächster Artikel: If

Zweck

Mit <Reference> wird ein vorhandener Dokumentbaustein in eine Dokumentvorlage eingebunden.

Der Baustein wird während der Dokumenterzeugung an der Position der Referenz verarbeitet.

Dadurch lassen sich wiederkehrende Inhalte zentral verwalten und in mehreren Dokumentvorlagen verwenden.

Typische Beispiele sind:

Briefköpfe
Fußzeilen
Signaturblöcke
Standardtexte
Datenschutzhinweise
Anschriften
wiederkehrende Tabellen
komplette Dokumentabschnitte

Grundsyntax

<Reference
    Name="Briefkopf"
    RefId="21a0081f-6f11-4743-8b05-3f85e22368e5"
    RefName="Briefkopf">
</Reference>

Position innerhalb der Dokumentvorlage

Eine Referenz kann überall dort verwendet werden, wo Dokumentinhalt eingefügt werden soll.

Typischerweise wird sie innerhalb eines <Content> oder direkt auf Root-Ebene verwendet.

Je nach Einsatzzweck wird der referenzierte Baustein an der jeweiligen Position verarbeitet.

Developer-Unterstützung

Die Eigenschaften einer Referenz – insbesondere die RefId – werden vom Developer automatisch ermittelt.

Da diese Informationen dem Redakteur normalerweise nicht bekannt sind, sollte eine neue Referenz grundsätzlich über die Funktionen des Developers eingefügt werden.

Dadurch werden alle erforderlichen Attribute automatisch korrekt gesetzt.

Developer-Tipp

Erzeugen Sie neue Referenzen möglichst über den Developer und bearbeiten Sie die erzeugten Attribute anschließend nur bei Bedarf manuell.

Attribute

Attribut	Beschreibung
Name	Anzeigename des referenzierten Dokumentbausteins.
RefId	Eindeutige technische Kennung (GUID) des Dokumentbausteins.
RefName	Interner Name des Dokumentbausteins.

Hinweis

Für das XML-Element <Reference> stehen keine weiteren Attribute zur Verfügung.

Unterelemente

Innerhalb einer Referenz können weitere XML-Elemente verwendet werden.

Der häufigste Anwendungsfall ist die Übergabe von Parametern an den eingebundenen Dokumentbaustein.

Derzeit werden folgende Unterelemente unterstützt:

Element	Zweck
RefParam	Übergibt Parameter an den referenzierten Dokumentbaustein.

Weitere Unterelemente können abhängig von der verwendeten Developer-Version zur Verfügung stehen.

RefParam

Mit <RefParam> können Werte an den eingebundenen Dokumentbaustein übergeben werden.

Dadurch lassen sich Dokumentbausteine flexibel wiederverwenden, ohne deren XML-Code anpassen zu müssen.

Ein Dokumentbaustein kann die übergebenen Parameter anschließend innerhalb seines eigenen XML-Codes auswerten.

Grundsyntax

<Reference
    Name="Briefkopf"
    RefId="21a0081f-6f11-4743-8b05-3f85e22368e5"
    RefName="Briefkopf">

    <RefParam
        Name="Mandant"
        Path="source.mandant">
    </RefParam>

</Reference>

Attribute von RefParam

Attribut	Beschreibung
Name	Name des Parameters innerhalb des Dokumentbausteins.
Path	Übergibt den Inhalt einer Variable.
Const	Übergibt einen festen Wert.
DataType	Datentyp des übergebenen Parameters.

Parameterübergabe

Ein Dokumentbaustein kann beliebig oft verwendet werden.

Über <RefParam> erhält jede Einbindung ihre eigenen Werte.

Dadurch kann derselbe Dokumentbaustein beispielsweise

unterschiedliche Überschriften,
verschiedene Anschriften,
individuelle Texte oder
fachliche Steuerinformationen

erhalten.

Dies erhöht die Wiederverwendbarkeit erheblich.

Typisches Beispiel

<Reference
    Name="Briefkopf"
    RefId="21a0081f-6f11-4743-8b05-3f85e22368e5"
    RefName="Briefkopf">

    <RefParam
        Name="Name"
        Path="source.name">
    </RefParam>

    <RefParam
        Name="Vorname"
        Path="source.vorname">
    </RefParam>

</Reference>

Der Dokumentbaustein erhält beide Parameter und kann diese innerhalb seines eigenen XML-Codes verwenden.

Best Practices

Dokumentbausteine möglichst allgemein halten.
Fachliche Unterschiede über RefParam steuern.
Wiederkehrende Inhalte nicht mehrfach in Dokumentvorlagen pflegen.
Neue Referenzen grundsätzlich über den Developer einfügen.
Dokumentbausteine zentral warten und mehrfach verwenden.

XML-Wissen

Eine Referenz kopiert den XML-Code des Dokumentbausteins nicht in die Dokumentvorlage.

Während der Dokumenterzeugung wird stattdessen der referenzierte Dokumentbaustein verarbeitet und dessen Ergebnis an der Position der Referenz eingefügt.

Dadurch bleibt ein Dokumentbaustein zentral wartbar und kann gleichzeitig von beliebig vielen Dokumentvorlagen verwendet werden.

Zuletzt aktualisiert am 4. August 2026

Setter Barcodes