Globale Konfiguration teilen und pro Vorlage übersteuern

Mehrere Briefvorlagen teilen sich den Block mit Beilagen und Kopien am Briefende: Die Forms-Elemente und das Field dazu liegen in den globalen Konfigurationen und werden in jeder Vorlage nur referenziert. Eine einzelne Vorlage soll «Kopie an» mit einem Standardtext vorbelegen, ohne dass sich an den globalen Einträgen oder an den übrigen Vorlagen etwas ändert.

Ergebnis

• Alle Briefvorlagen zeigen im Forms-Dialog die Felder «Beilagen» und «Kopie an» und geben sie im selben Block am Briefende aus.
• In einer Vorlage ist «Kopie an» mit einem Standardtext vorbelegt, den der Anwender überschreiben kann.
• Die globalen Einträge bleiben unverändert und gelten weiter für alle anderen Vorlagen.

Global oder lokal

Ein globaler Eintrag ist XML, das an einer Stelle gepflegt und in der Vorlage über ein Global…-Element mit Key referenziert wird. Bei der Dokumenterstellung setzt primedocs den Inhalt des Eintrags an die Stelle der Referenz. Für den Zugriff im Code und für die Prüfung auf doppelte Ids unterscheidet sich ein global eingebundenes Element danach nicht mehr von einem lokal definierten. Daraus folgen drei Regeln:

• Code greift über die Id zu, nicht über den Key. $("Forms.CopyTo") sucht das Forms-Element mit der Id CopyTo, unabhängig davon, ob es aus einem globalen Eintrag stammt oder direkt in der Vorlage steht. Der Key eines globalen Eintrags (Forms.CopyTo = Gruppe Forms, Eintrag CopyTo) ist ein eigener Name, der nur durch Konvention gleich aussieht.
• Jede Id und jeder Feldname kommt in einer Vorlage nur einmal vor. Definiert eine Vorlage ein Forms-Element mit derselben Id wie ein eingebundenes globales Element, meldet die Validierung eine doppelte Id, in Fields einen doppelten Feldnamen. Übersteuern heisst darum immer: die globale Referenz ersetzen oder modifizieren, nicht zusätzlich lokal definieren.
• Ein globaler Eintrag hat genau einen Stand. Globale Konfigurationen sind nicht versioniert. Eine Änderung wirkt auf jede Vorlage, die den Eintrag referenziert, auf veröffentlichte Vorlagen ebenso wie auf Entwürfe. Keine Vorlage hält einen älteren Stand des Eintrags fest.

Situation	Umsetzung
Mehrere Vorlagen brauchen dieselbe Konfiguration	globaler Eintrag, in jeder Vorlage referenziert
Die Konfiguration gehört zu genau einer Vorlage	lokal in der Vorlage
Mehrere Vorlagen teilen die Logik, eine weicht in einem Element ab	globaler Eintrag. Die abweichende Vorlage ersetzt das Forms-Element (Schritt 4) oder modifiziert das Field (Variante)
Gleiche Logik, aber pro Vorlage mit anderen Eingaben	Funktion als GlobalCode mit Parametern
Benutzersichtbare Texte in mehreren Sprachen	Globale Übersetzungen

Bausteine

Baustein	Aufgabe in diesem Beispiel	Referenz
Globaler Eintrag Forms.Enclosures (Typ FormsGlobalElements)	Eingabefeld «Beilagen», Id Enclosures	Forms: GlobalElements
Globaler Eintrag Forms.CopyTo (Typ FormsGlobalElements)	Eingabefeld «Kopie an», Id CopyTo	Forms: GlobalElements
Globaler Eintrag Fields.EnclosureBox (Typ FieldsGlobalFields)	Text-Field EnclosureBox setzt den Block aus beiden Eingaben zusammen	Fields: GlobalFields
Forms und Fields (Inhaltsvorlagen)	referenzieren die globalen Einträge, und eine Vorlage ersetzt Forms.CopyTo	Forms, Fields
Word-Inhaltsvorlagen	EnclosureBox am Briefende binden	Zugriff auf primedocs-Felder

Datenfluss

Schritt 1: Ein globaler Forms-Eintrag pro Element

In den globalen Konfigurationen zwei Einträge vom Typ FormsGlobalElements anlegen.

Key Forms.Enclosures:

<FormsGlobalElements>
  <Text Id="Enclosures" Label="Beilagen" MultiLine="true" />
</FormsGlobalElements>

Key Forms.CopyTo:

<FormsGlobalElements>
  <Text Id="CopyTo" Label="Kopie an" MultiLine="true" />
</FormsGlobalElements>

Warum zwei Einträge statt einem: Eine Vorlage kann eine GlobalElements-Referenz nur als Ganzes ersetzen, nicht ein einzelnes Element darin. Stünden beide Elemente im selben Eintrag, müsste die abweichende Vorlage auch «Beilagen» lokal nachbauen und bekäme spätere Änderungen daran nicht mehr mit. Wie fein die globalen Einträge geschnitten sind, bestimmt also, was eine Vorlage einzeln übersteuern kann.

Schritt 2: Globales Field für den Block

Einen Eintrag vom Typ FieldsGlobalFields mit Key Fields.EnclosureBox anlegen:

<FieldsGlobalFields>
  <!-- Erwartet in der Vorlage die Forms-Elemente mit den Ids Enclosures und CopyTo -->
  <Text Name="EnclosureBox">
    <Code><![CDATA[
      function main() {
        const enclosures = $("Forms.Enclosures");
        const copyTo = $("Forms.CopyTo");
        return $.joinNonEmpty("\n\n",
          enclosures ? "Beilagen:\n" + enclosures : "",
          copyTo ? "Kopie an:\n" + copyTo : "");
      }
    ]]></Code>
  </Text>
</FieldsGlobalFields>

• Das Field liest die Eingaben über die Ids Enclosures und CopyTo. Es setzt voraus, dass jede Vorlage, die Fields.EnclosureBox referenziert, Forms-Elemente mit diesen Ids enthält, egal ob global eingebunden oder lokal definiert. Fehlt eines, bricht die Dokumenterstellung mit einem Fehler ab, der EnclosureBox und die fehlende Referenz nennt.
• Diese Abhängigkeit ist der Vertrag zwischen den globalen Einträgen. Der XML-Kommentar im Eintrag hält ihn für alle fest, die den Eintrag später bearbeiten.
• $.joinNonEmpty(…) lässt leere Teile weg: Ohne Beilagen erscheint nur der Kopienteil, ohne beide Eingaben bleibt der Block leer.

Schritt 3: Vorlagen referenzieren die globalen Einträge

In jeder Briefvorlage die Dokumentfunktion Forms aktivieren:

<FormsConfiguration>
  <Elements>
    <GlobalElements Key="Forms.Enclosures" />
    <GlobalElements Key="Forms.CopyTo" />
  </Elements>
</FormsConfiguration>

Die Dokumentfunktion Fields:

<FieldsConfiguration>
  <Fields>
    <GlobalFields Key="Fields.EnclosureBox" />
  </Fields>
</FieldsConfiguration>

In der Word-Inhaltsvorlage den Cursor ans Briefende setzen, auf «Feld binden» klicken und EnclosureBox wählen. Das Feld wird als Nur-Text-Inhaltssteuerelement eingefügt. Die Zeilenumbrüche aus \n ergeben die Zeilen des Blocks.

Schritt 4: Die abweichende Vorlage ersetzt ein Element

In der einen Vorlage, die «Kopie an» vorbelegen soll, die Referenz auf Forms.CopyTo durch ein lokales Element mit derselben Id ersetzen:

<FormsConfiguration>
  <Elements>
    <GlobalElements Key="Forms.Enclosures" />
    <Text Id="CopyTo" Label="Kopie an" MultiLine="true" Value="Buchhaltung, zur Rechnungsstellung" />
  </Elements>
</FormsConfiguration>

• Id: genau CopyTo, ohne Forms. davor. Das Präfix entsteht erst beim Zugriff im Code.
• Value: der Standardtext, den der Sachbearbeiter im Dialog überschreiben kann.
• Label und MultiLine: aus dem globalen Element übernehmen, damit der Dialog in allen Vorlagen gleich aussieht. Für mehrsprachige Vorlagen translate-Label mit einer globalen Übersetzung verwenden.
• Die Referenz <GlobalElements Key="Forms.CopyTo" /> muss entfallen. Stehen beide in der Konfiguration, meldet die Validierung die Id CopyTo doppelt.

Fields-Konfiguration und Word-Vorlage bleiben unverändert: Fields.EnclosureBox findet über die Id CopyTo jetzt das lokale Element.

Das lokale Element ist eine Kopie. Ändert sich später das globale Forms.CopyTo, etwa die Beschriftung, erreicht die Änderung diese Vorlage nicht. Sie muss hier von Hand nachgeführt werden.

Testen

• Eine Standardvorlage im Vorlageneditor testen: «Beilagen» und «Kopie an» sind leer. Beide ausfüllen, dann zeigt der Block beide Teile. Nur «Kopie an» ausfüllen, dann zeigt der Block nur den Kopienteil.
• Die abweichende Vorlage testen: «Kopie an» ist mit dem Standardtext vorbelegt, und der Block zeigt ihn.
• In der abweichenden Vorlage probehalber <GlobalElements Key="Forms.CopyTo" /> wieder einfügen: Die Validierung meldet die doppelte Id CopyTo. So lässt sich prüfen, dass die Vorlage das globale Element wirklich ersetzt und nicht ergänzt.

Varianten

Field mit Modifications übersteuern

Weicht nicht die Eingabe ab, sondern die Ausgabe, bietet Fields einen eigenen Mechanismus. Beispiel: Eine Vorlage gibt nur die Kopien in einer Zeile aus, ohne Beilagen. Das Modifications-Element in GlobalFields ersetzt dazu ein Field des referenzierten Eintrags nur für diese Vorlage:

<FieldsConfiguration>
  <Fields>
    <GlobalFields Key="Fields.EnclosureBox">
      <Modifications>
        <Text Name="EnclosureBox">
          <Code><![CDATA[
            function main() {
              const copyTo = $("Forms.CopyTo");
              return copyTo ? "Kopie an: " + copyTo : "";
            }
          ]]></Code>
        </Text>
      </Modifications>
    </GlobalFields>
  </Fields>
</FieldsConfiguration>

• Die Modifikation ersetzt die Definition des Fields vollständig, nicht einzelne Attribute. Sie enthält darum den ganzen Code.
• Name und Field-Typ müssen zu einem Field des referenzierten Eintrags passen, auch eines verschachtelt eingebundenen. Sonst meldet die Validierung, dass das zu modifizierende Field fehlt oder der Typ nicht übereinstimmt.
• Modifizierbar sind Text, FormattedText, WordContent, InlineWordContent, WordTableRows, Date, YesNo und Picture.
• Andere Fields, die EnclosureBox verwenden, erhalten ebenfalls den modifizierten Wert. Details: Felder modifizieren.

Forms kennt keinen solchen Mechanismus. Dort bleibt das Ersetzen der Referenz wie in Schritt 4 der einzige Weg.

Einen globalen Eintrag ändern, ohne alle Vorlagen zu treffen

Weil globale Einträge keinen Versionsstand haben, trifft jede Änderung alle referenzierenden Vorlagen. Besonders heikel ist das Umbenennen oder Entfernen einer Id: Jede Vorlage und jedes globale Field, das die Id im Code verwendet, bricht danach ab. Für solche Änderungen einen neuen Eintrag mit eigenem Key anlegen (z. B. Forms.CopyToV2), die Vorlagen einzeln umstellen und testen und den alten Eintrag erst entfernen, wenn keine Vorlage ihn mehr referenziert.

Stolpersteine

Symptom	Ursache	Lösung
Die Validierung meldet eine doppelte Id CopyTo	Die globale Referenz und das lokale Element stehen gleichzeitig in der Vorlage	Die Referenz <GlobalElements Key="Forms.CopyTo" /> entfernen
Die Validierung meldet mehrere Fields mit demselben Namen	Ein lokales Field heisst gleich wie ein Field aus einem referenzierten globalen Eintrag	Das globale Field über Modifications übersteuern statt lokal neu definieren
Die Dokumenterstellung bricht mit einem Fehler zu EnclosureBox und einer fehlenden Referenz ab	Die Vorlage referenziert Fields.EnclosureBox, enthält aber kein Forms-Element mit der Id CopyTo oder Enclosures	Das Element global einbinden oder lokal definieren
Die Validierung lehnt die Id Forms.CopyTo ab	Das Präfix Forms. gehört nicht zur Id, und Punkte sind in Forms-Ids standardmässig nicht erlaubt	Id CopyTo verwenden
Die Validierung findet den globalen Eintrag nicht	Key abweichend geschrieben, oder der Eintrag hat einen anderen Typ als das referenzierende Element verlangt	Key exakt übernehmen, einschliesslich Gross- und Kleinschreibung, und den Typ des Eintrags prüfen
Eine geänderte Beschriftung fehlt in einer Vorlage	Die Vorlage ersetzt das globale Element lokal (Schritt 4)	Die lokale Kopie nachführen

Verwandte Seiten

• Globale Konfigurationen, Globale Übersetzungen
• Forms, Fields, Code