Zum Hauptinhalt springen
Version: 4.1 (2026 H2)

Platzhalterzuordnung (PlaceholderMapping)

Zweck und Einsatz​

Damit in Layouts dynamische Daten angezeigt werden können, benötigen sie Platzhalter.

Über die Platzhalterzuordnung werden in der Inhaltsvorlage resp. einer PowerPoint-Vorlage Platzhalter mit den gewünschten Daten abgefüllt, die zuvor in einer übergeordneten Vorlage - z. B. einem Layout oder einer Master-Vorlage - mittels Platzhalterdefinition (PlaceholderDefinition)-Funktion "versprochen" wurden.

Die Daten können dabei aus der Formulare (Forms)-Dokumentfunktion oder über die Felder (Fields)-Dokumentfunktion (Benutzerdaten, JavaScript-Funktionen) kommen.

Folgendes Beispiel weist dem Platzhalter mit Name Footer das Field FooterGeneral aus der Dokumentfunktion Felder (Fields) zu:
<Text Name="Footer" SourceField="FooterGeneral" />

hinweis

Jeder Platzhalter, der im Layout definiert wurde muss gemappt werden, sonst erscheint eine Fehlermeldung.

tipp

Im Kontext von Textbausteinen lässt sich das Mapping mit $.createAutoMapping() automatisch erzeugen, statt jeden Eintrag von Hand zu schreiben.

Grundaufbau​

<PlaceholderMappingConfiguration>
  <Mappings>
    <!-- Platzhalter -->
  </Mappings>
</PlaceholderMappingConfiguration>

Attribute​

Folgende Attribute müssen bei allen verfügbaren Elementarten (Text, Picture, YesNo) gesetzt werden:

AttributnameBeschreibung
Name
(erforderlich)		Wird zur Identifikation benötigt, darf gleich heissen wie das Feld aus Forms oder Fields. Darf keine Leerzeichen enthalten.
SourceField (erforderlich)Wird benötigt, um das Feld aus Forms oder Fields zu mappen. Entsprechend kommt hier die Id des entsprechenden Feldes rein.

Es gibt drei Quellen für Platzhalter, die im Attribut SourceField angesprochen werden können:

  • ein Benutzerfeld: Profile.User.FirstName
  • ein Forms-Feld: Forms.MyTextfield / Forms.MainSigner.FirstName
  • ein Field: MyField (Achtung: der Name eines Field darf keinen Punkt enthalten, weil Gruppierungen nur mittels Objects und ObjectCollections möglich sind).
info

In den weitaus meisten Fällen wird ein Field erstellt, das dynamisch Inhalte kombiniert und ausgibt - und dann einem Platzhalter zugewiesen wird. Benutzerfelder werden praktisch nie ohne Umweg über ein Field zugewiesen.

Elemente​

Text​

<Text Name="CreateDate" SourceField="Forms.Date" />

Picture​

<Picture Name="PartnerLogo" SourceField="PartnerLogo" />

YesNo​

<YesNo Name="ShowClassification" SourceField="Forms.ShowClassification" />
hinweis

YesNo wird derzeit nur beim PowerPoint-Binding unterstützt (nicht in Word- oder Excel-Vorlagen).

GlobalMappings​

Über das Element GlobalMappingskann eine global abgelegte Platzhalterzuordnung geholt werden.

<GlobalMappings Key="Placeholders.Map.Letter" />

Mehr Informationen zu den Globalen Konfigurationen sind hier zu finden: Global Configurations.

Ein konkretes Beispiel zum Erkennen des Zusammenhangs zwischen dem globalen Eintrag und der Referenz auf einen globalen Eintrag gibt es hier: Global Configurations.

Attribute für GlobalMappings​

Die Referenz auf einen globalen Eintrag passiert mittels dem Key-Attribut. Wählt man dieses aus, wird einem automatisch eine Liste mit allen zur Verfügung stehenden globalen Einträgen angezeigt.

AttributnameBeschreibung
Key
(erforderlich)		Die ID des globalen Eintrags, der referenziert werden soll.

Platzhalter aus dem Layout übernehmen​

Damit die Zuordnung nicht Platzhalter für Platzhalter von Hand aus dem Layout übertragen werden muss, bietet der Editor der Platzhalterzuordnung die Aktion «+ Insert layout configuration» an. Sie liest die Platzhalterdefinition (PlaceholderDefinition) der zugrunde liegenden Layout- bzw. Master-Vorlage aus und gleicht sie mit der aktuellen Zuordnung ab.

Beim Ausführen:

  • Für jeden im Layout definierten Platzhalter, der in der Zuordnung noch fehlt, wird ein leerer Mapping-Eintrag eingefügt. Das SourceField wird anschliessend von Hand zugewiesen.
  • Bereits vorhandene Zuordnungen bleiben unverändert; es entstehen keine Duplikate.
  • Zuordnungen, die keinem Platzhalter im Layout mehr entsprechen (verwaiste Einträge), werden nicht gelöscht, sondern auskommentiert — so gehen keine Angaben verloren und die Bereinigung bleibt kontrollierbar.

Der Abgleich löst dabei auch referenzierte globale Einträge auf: Sowohl die GlobalDefinitions der Layout-Definition als auch die GlobalMappings der Zuordnung werden vor dem Vergleich flachgeklopft.

tipp

Über welches globale Mapping die Aktion Vorgaben zieht, steuert der Layouter in der Platzhalterdefinition über den Block DefinitionMappings.

Beispiel-XML-Konfiguration​

<PlaceholderMappingConfiguration>
  <Mappings>
    <!-- Daten für Kopfzeile -->
    <Text Name="CreateDate"      SourceField="Forms.Date" /><!-- aus Forms -->
    <Picture Name="PartnerLogo"  SourceField="PartnerLogo" /><!-- aus Fields -->
    <!-- Daten für Fusszeile -->
    <GlobalMappings Key="Placeholders.Map.Page" /><!-- global abgelegt -->
    <Text Name="Footer" SourceField="Profile.Org.Footer" /><!-- aus Benutzerprofil -->
  </Mappings>
</PlaceholderMappingConfiguration>