1 Zweck und Einsatz
2 Grundaufbau
3 Designer
- 3.1 Beispiel
4 Übersicht
- 4.1 Weitere Profile in Vorlage integrieren
- 4.2 Adaptive Dateneingabemaske
5 Elemente
- 5.1 Gruppen
  - 5.1.1 Attribute für Group
- 5.2 Info
  - 5.2.1 Beispiel in XML
- 5.3 Text
  - 5.3.1 Beispiele in XML mit Vorschau
  - 5.3.2 Attribute für Text
  - 5.3.3 Inhalte für Text
- 5.4 Date
  - 5.4.1 Beispiele im XML mit Vorschau
  - 5.4.2 Attribute für Date
  - 5.4.3 Inhalte für Date
- 5.5 YesNo
  - 5.5.1 Beispiele in XML mit Vorschau
  - 5.5.2 Attribute für YesNo
  - 5.5.3 Inhalte für YesNo
- 5.6 Choice
  - 5.6.1 Beispiele im XML mit Vorschau
  - 5.6.2 Attribute für Choice
  - 5.6.3 Inhalte für Choice
- 5.7 AdditionalProfile
  - 5.7.1 Beispiel
  - 5.7.2 Attribute für AdditionalProfile
  - 5.7.3 Inhalte für AdditionalProfile
- 5.8 Objects und ObjectCollections
  - 5.8.1 Attribute für Object bzw. ObjectCollection
  - 5.8.2 Inhalte für Object bzw. ObjectCollection
  - 5.8.3 Beispiel Anwendungsfall Vorlage “Protokoll“
    - 5.8.3.1 XML-Konfiguration
    - 5.8.3.2 Screenshots
6 Zugriff auf global abgelegte Einträge
- - 6.1.1 Attribute für GlobalElements, GlobalSchemaAndSummary und GlobalDataProviders
- 6.2 Beispiel
- 6.3 GlobalSchemaAndSummary
- 6.4 GlobalDataProviders
- 6.5 GlobalElements
7 Übersetzungen
- 7.1 Attribute
- 7.2 Anwendungsbeispiel mit translate- Attributen
  - 7.2.1 Erklärung des Anwendungsbeispiels
8 Glossar
9 Ausführliches Beispiel
- 9.1 Code
  - 9.1.1 Forms
  - 9.1.2 Felder
- 9.2 Screenshot

Zweck und Einsatz

Über diese Dokumentfunktion können Eigenschaften über ein Formular abgefragt werden, indem man Textboxen, Checkboxen, Dropdowns etc., sogenannte Elemente, konfiguriert.

Diese Funktion steht in “classic” Vorlagen nicht in vollem Funktionsumfang zur Verfügung.
Weitere Informationen zu den verschiedenen Vorlagen Versionen finden Sie hier.

Grundaufbau

<FormsConfiguration>
  <Elements>
    <!-- Formularelemente und Gruppen hier einfügen -->
  </Elements>
</FormsConfiguration>

Designer

Öffnet man Forms im Vorlageneditor, landet man automatisch auf der einfachen Ansicht. Via Klick auf die Vorschau, gelangt man in den Forms-Designer. Der Designer ermöglicht einem das Formular im Handumdrehen in einer Benutzeroberfläche zusammenzustellen.

Ein Formular besteht aus verschiedenen Elementen: Strukturelementen, die zur Übersichtlichkeit des Formulars beitragen, sowie Formularelementen, deren vom Benutzer eingegebenen Werte schlussendlich im Dokument landen.

Hinter der Benutzeroberfläche des Designer steht eine XML-Konfiguration für jedes Element. Diese findet man über den Button “Erweiterte Ansicht”. Alle Elemente werden nun im folgenden Kapitel beschrieben.

Beispiel

<FormsConfiguration>
  <Elements>
    <Text Id="Subject" translate-Label="Forms.Subject" />
    <Date Id="Date" translate-Label="Forms.Date" RelativeDate="Today" translate-Format="Configuration.DateFormat.WrittenOut" />
    <AdditionalProfile Id="MainSigner" Label="Hauptunterzeichnende*r" PreselectByIndex="1" />
    <AdditionalProfile Id="CoSigner" Label="Mitunterzeichnende*r" />
    <Group Title="Weitere Einstellungen">
      <YesNo Id="ShowContact" Label="Kontakt anzeigen" Value="true">
        <ElementsIfYes>
          <Choice Id="ContactFormOption" Label="Anzeigeart" SelectedValue="0">
            <Option Value="0" Label="Unpersönlicher Kontakt" />
            <Option Value="1" Label="Persönlicher Kontakt" />
          </Choice>
        </ElementsIfYes>
      </YesNo>
    </Group>
    <GlobalElements Key="Forms.Attachments" />
  </Elements>
</FormsConfiguration>

Übersicht

Folgende Forms-Elemente sind möglich:

Strukturelemente

Group
Info

Formularelemente

Text
Date
YesNo (Checkbox)
Choice (Dropdown)
AdditionalProfile
Object oder ObjectCollection
GlobalSchemaAndSummary (globale abgelegte Schema/Summary-Konfiguration)
GlobalDataProviders (global abgelegter DataProvider)
GlobalElements (global abgelegte Forms-Konfiguration)

Weitere Profile in Vorlage integrieren

Die Profilfelder des Benutzers, der ein Dokument generiert, werden automatisch während der Dokumenterstellung bereitgestellt und beinhalten z. B. die Organisationsdaten wie Logos oder Postanschriften sowie die persönlichen Benutzerdaten. Mittels Profilwechsel im primedocs-Ribbon werden in einem Dokument, das Profilfelder enthält, die Daten des ausgewählten Profils angezeigt.

Mittels AdditionalProfile können noch zusätzliche Profile in das Dokument integriert werden. Diese Profilauswahl zeigt die Profile des eigenen Benutzers oder ihm freigegebene Fremdprofile an.
Somit sind AdditionalProfiles für Anwendungsfälle gedacht, in denen andere Personen aus der Firma im Dokument auftauchen sollen. Die Anwendung von AdditionalProfile ist zum Beispiel sinnvoll…

bei zusätzlichen Unterschriften in einer Vorlage.
bei der Zusammenarbeit mit weiteren Mitarbeitenden oder Abteilungen in einer Vorlage. z. B. in einer Vorlage soll neben der Fachbereichsleiterin auch die Kostenstellenverantwortliche erwähnt werden.
in weitaus mehr Anwendungsfällen.

In der Vorlage müssen folglich auch die entsprechenden Forms-Felder des AdditionalProfile eingefügt sein.

Adaptive Dateneingabemaske

Forms ermöglicht das Anzeigen von Feldern aufgrund eines bedingten Wertes. In den Formularelementen YesNo und Choice kann man dadurch aufgrund eines Wertes das Erscheinen von weiteren Formularelementen steuern. Die möglichen Formularelemente, die erscheinen können, sind: Text, Date, Choice, YesNo und Info.
Beispiel: ein Info-Element soll nur angezeigt werden, wenn das YesNo-Feld aktiviert (= true) ist:

Die Elemente für die adaptive Dateneingabemaske heissen ElementsIfYes / ElementsIfNo bei YesNo-Elementen (für true und false) und ElementsIfValue bei Choice-Elementen (für einen spezifischen Wert). Beispiele für die XML-Konfiguration und die Dokumentation der ElementsIf-Elemente finden Sie unter Choice und YesNo.

Info-Element in ElementsIfYes in einem YesNo

<YesNo Name="ShowThing" Label="Muss unterzeichnet werden">
  <ElementsIfYes>
    <Info>Bitte sicherstellen, dass ein Signaturbild hinterlegt ist.<Info>
  </ElementsIfYes>
</YesNo>

Elemente

Gruppen

Gruppen sind Strukturelemente und gruppieren Formularelemente mit <Group>...</Group> für die visuelle Darstellung.

Beispiel in XML

<FormsConfiguration>
  <Elements>
    <!-- [Formularelemente] -->
    <Group Title="Telefonnummern">
      <!-- [Formularelemente] -->
    </Group>
    <!-- [Formularelemente] -->
  </Elements>
</FormsConfiguration>

Gruppen dürfen nicht weitere Gruppen enthalten (es gibt keine Verschachtelung).

Attribute für `Group`

Attributname	Beschreibung

Attributname	Beschreibung
`Title` (optional)	Titel, der auf der Eingabeoberfläche angezeigt wird.

Info

Dieses Element erlaubt die Anzeige von Informationstext im Forms-Dialog. Der anzuzeigende Text wird als Inhalt des Info-Elements angegeben.

Beispiel in XML

<FormsConfiguration>
  <Elements>
    <Info>Wichtig: Jedes Protokoll muss auch im Teams-Kanal «Protokollfeed» gesendet werden.</Info>
  </Elements>
</FormsConfiguration>

Text

Das Text-Element bietet dem Benutzer die Möglichkeit, in Forms einen Text einzugeben. Es wird entsprechend typischerweise als Textfeld angezeigt. In der Vorlage wird ein Nur-Text-Inhaltssteuerelement (Plain Text Content Control) eingefügt.

Beispiele in XML mit Vorschau

Simpel:

<Text Id="Subject" Label="Betreff" />

Erweitert:

<Text Id="Subject" Label="Betreff" Value="Protokoll für" MultiLine="true" Required="true">
  <Description>Bitte treffenden Betreff eingeben, der das Anliegen kurz, prägnant und präzise beschreibt.</Description>
  <ValidationMessage>Bitte einen Betreff eingeben.</ValidationMessage>
</Text>

Betreff mit Beschreibung, die angezeigt wird, wenn der Cursor über dem Textfeld schwebt.

Attribute für `Text`

Attributname	Beschreibung

Attributname	Beschreibung
`Id` (erforderlich)	Wird zur Identifikation benötigt (Einfügen in der Vorlage, Verwendung in Feldern). Darf keine Leerzeichen enthalten und muss eindeutig sein. Forms fügt automatisch den Präfix `Forms.` hinzu (aus `Subject` wird z. B. `Forms.Subject`).
`Label` (erforderlich)	Beschreibung des Elements in der Eingabeoberfläche
`Value` (optional)	Vordefinierter Text, den der Benutzer bearbeiten kann.
`MultiLine` (optional)	Wenn `true`: Möglichkeit in der Eingabeoberfläche, Zeilenumbrüche einzufügen.
`Required` (optional)	Wenn `true`: Der Benutzer muss eine Eingabe tätigen, der Text darf nicht leer sein und nicht nur aus Leerzeichen bestehen. Empfohlen: Zusätzlich eine spezifische `ValidationMessage` konfigurieren.
`OnlyVisibleDuringGeneration` (optional)	Wenn `true`: Das Feld wird nur beim erstmaligen Generieren des Dokuments angezeigt. Öffnet der Benutzer den Forms-Dialog erneut im primedocs Ribbon im offenen Dokument, wird es nicht mehr angezeigt.

Inhalte für `Text`

Elementname	Beschreibung

Elementname	Beschreibung
`Description` (optional)	Zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche als Tooltip angezeigt.
`ValidationMessage` (optional)	Text, der dem Benutzer angezeigt wird, wenn dieses Textfeld ungültig ausgefüllt wurde.

Date

Das Date-Element bietet dem Benutzer die Möglichkeit, in Forms ein Datum auszuwählen. Es wird entsprechend typischerweise als Date picker angezeigt. In der Vorlage wird ein Datumsauswahl-Inhaltssteuerelement (Date Picker Content Control) eingefügt.

Beispiele im XML mit Vorschau

Simpel:

<Date Id="CreationDate" Label="Erstelldatum" Format="dd.MM.yyyy" />

Erweitert: mit Value und Required:

<Date Id="CreationDate" Label="Erstelldatum" Format="dd.MM.yyyy" Value="2020-12-31" Required="true">
  <Description>Optimalerweise sollte hier das Datum des Postversands gewählt werden.</Description>
  <ValidationMessage>Bitte ein Erstelldatum auswählen.</ValidationMessage>
</Date>

Erweitert: mit RelativeDate:

<Date Id="CreationDate" Label="Erstelldatum" Format="dd.MM.yyyy" RelativeDate="FirstDayOfMonth" OffsetMonths="2" OffsetDays="-1"  />

Gerechnet ab Datum: 12.01.2024

Attribute für `Date`

Attributname	Beschreibung

Attributname	Beschreibung
`Id` (erforderlich)	Wird zur Identifikation benötigt (Einfügen in der Vorlage, Verwendung in Feldern). Darf keine Leerzeichen enthalten und muss eindeutig sein. Forms fügt automatisch den Präfix `Forms.` hinzu (aus `CreationDate` wird z. B. `Forms.CreationDate`).
`Label` (erforderlich)	Beschreibung des Elements in der Eingabeoberfläche
`Format` (erforderlich)	Definition des Datumformates, z. B. `dd.MM.yyyy` für "31.12.2020" oder `d. MMMM yyyy` für "31. Dezember 2020". Siehe Liste mit Datumsformaten. In der Basiskonfiguration befinden sich in den globalen Übersetzungen mehrere Datumsformate, auf die zugegriffen werden kann.
`Required` (optional)	Wenn `true`: Der Benutzer muss ein Datum auswählen, das Datum darf nicht leer sein. Empfohlen: Zusätzlich eine spezifische `ValidationMessage` konfigurieren.
`Value` (optional)	Vorausgewähltes fixes Datum, das der Benutzer bearbeiten kann. Format: `yyyy-MM-dd`, z. B. `2020-12-31` Kann nicht in Kombination mit `RelativeDate` verwendet werden.
`RelativeDate` (optional)	Vorausgewähltes Datum, das der Benutzer bearbeiten kann und das relativ zum Zeitpunkt der Dokumenterstellung ist. Wenn `Today`: Datum der Dokumenterstellung Wenn `FirstDayOfMonth`: Erster Tag des Monats der Dokumenterstellung Wenn `FirstDayOfYear`: Erster Tag des Jahres der Dokumenterstellung Die Attribute `OffsetMonths` und `OffsetDays` können verwendet werden, um das relative Datum weiter anzupassen. Beispiele: Aktueller Tag: `RelativeDateOption="Today"` Erster Tag des aktuellen Monats: `RelativeDateOption="FirstDayOfMonth"` Letzter Tag des vorherigen Monats: `RelativeDateOption="FirstDayOfMonth" OffsetDays="-1"` Letzter Tag des aktuellen Monats: `RelativeDateOption="FirstDayOfMonth" OffsetMonths="1" OffsetDays="-1"` Letzter Tag des vorherigen Jahres: `RelativeDateOption="FirstDayOfYear" OffsetDays="-1"` Letzter Tag des aktuellen Jahres: `RelativeDateOption="FirstDayOfYear" OffsetMonths="12" OffsetDays="-1"`
`OffsetMonths` (optional)	Anzahl Monate, die zum relativen Datum dazu addiert werden (positive und negative Zahlen erlaubt). Siehe `RelativeDateOption`.
`OffsetDays` (optional)	Anzahl Tage, die zum relativen Datum dazuaddiert werden (positive und negative Zahlen erlaubt). Siehe `RelativeDateOption`.
`OnlyVisibleDuringGeneration` (optional)	Wenn `true`: Das Feld wird nur beim erstmaligen Generieren des Dokuments angezeigt. Öffnet der Benutzer den Forms-Dialog erneut im primedocs Ribbon im offenen Dokument, wird es nicht mehr angezeigt.

Inhalte für `Date`

Elementname	Beschreibung

Elementname	Beschreibung
`Description` (optional)	Zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche als Tooltip angezeigt.
`ValidationMessage` (optional)	Text, der dem Benutzer angezeigt wird, wenn dieses Datumsfeld ungültig ausgefüllt wurde.

YesNo

Das YesNo-Element bietet dem Benutzer die Möglichkeit, in Forms eine Option zu aktivieren ("Ja") oder zu deaktivieren ("Nein"). Es wird entsprechend typischerweise als Checkbox angezeigt. In der Vorlage wird ein Kontrollkästchensteuerelement (Check Box Content Control) eingefügt.

Beispiele in XML mit Vorschau

Simpel:

<YesNo Id="MustBeSigned" Label="Muss unterzeichnet werden" />

Erweitert mit adaptiver Dateneingabe

<YesNo Id="MustBeSigned" Label="Muss unterzeichnet werden" Value="false" RequiredValue="true">
  <Description>Anwählen, wenn das Protokoll von Hand unterzeichnet werden muss</Description>
  <ValidationMessage>Protokolle müssen immer unterzeichnet werden.</ValidationMessage>
  <ElementsIfYes>
    <Info>Bitte sicherstellen, dass ein Signaturbild hinterlegt ist.</Info>
  </ElementsIfYes>
</YesNo>

Beim Stillstehen des Cursor über der CheckBox

Beim Bestätigen des Dialogs, ohne, dass Checkbox aktiviert ist.

Info-Element in ElementsIfYes

Attribute für `YesNo`

Attributname	Beschreibung

Attributname	Beschreibung
`Id` (erforderlich)	Wird zur Identifikation benötigt (Einfügen in der Vorlage, Verwendung in Feldern). Darf keine Leerzeichen enthalten und muss eindeutig sein. Forms fügt automatisch den Präfix `Forms.` hinzu (aus `MustBeSigned` wird z. B. `Forms.MustBeSigned`).
`Label` (erforderlich)	Beschreibung des Elements in der Eingabeoberfläche
`Value` (optional)	Wenn `true`: Die YesNo-Option ist zu Beginn aktiviert.
`RequiredValue` (optional)	Wenn `true`: Der Benutzer muss die YesNo-Option aktivieren. Wenn `false`: Der Benutzer muss die YesNo-Option deaktivieren. Empfohlen: Zusätzlich eine spezifische `ValidationMessage` konfigurieren.
`OnlyVisibleDuringGeneration` (optional)	Wenn `true`: Das Feld wird nur beim erstmaligen Generieren des Dokuments angezeigt. Öffnet der Benutzer den Forms-Dialog erneut im primedocs Ribbon im offenen Dokument, wird es nicht mehr angezeigt.

Inhalte für `YesNo`

Elementname	Beschreibung

Elementname	Beschreibung
`ElementsIfYes` (optional)	Adaptive Dateneingabe: ist der Wert `true`, werden alle Forms-Elemente angezeigt, die zwischen `<ElementsIfYes>` und `</ElementsIfYes>` eingegeben sind.
`ElementsIfNo` (optional)	Adaptive Dateneingabe: ist der Wert `false`, werden alle Forms-Elemente angezeigt, die zwischen `<ElementsIfNo>` und `</ElementsIfNo>` eingegeben sind.
`Description` (optional)	Zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche als Tooltip angezeigt.
`ValidationMessage` (optional)	Text, der dem Benutzer angezeigt wird, wenn diese YesNo-Option ungültig ausgefüllt wurde.

Choice

Das Choice-Element bietet dem Benutzer die Möglichkeit, in Forms zwischen mehreren Optionen auszuwählen. Es wird entsprechend typischerweise als Dropdown angezeigt. In der Vorlage wird ein Datumsauswahl-Kombinationsfeld-Inhaltssteuerelement (Combo Box Content Control) eingefügt.

Beispiele im XML mit Vorschau

Simpel:

<Choice Id="Classification" Label="Klassifizierung">
  <Option Value="public" Label="Öffentlich" />
  <Option Value="confidential" Label="Vertraulich" />
  <Option Value="secret" Label="Geheim" />
</Choice>

Erweitert mit adaptiver Dateneingabe:

<Choice Id="Classification" Label="Klassifizierung" Required="true" SelectedValue="confidential" EmptyOptionLabel="Bitte Klassifizierung wählen...">
  <Option Value="public" Label="Öffentlich" />
  <Option Value="confidential" Label="Vertraulich" />
  <Option Value="secret" Label="Geheim" />
  <Description>Bitte beachten: Geheime Dokumente dürfen niemals per E-Mail versendet werden.</Description>
  <ValidationMessage>Bitte Klassifizierung auswählen.</ValidationMessage>
  <ElementsIfValue SelectedValue="secret">
    <Text Id="SecretId" Label="Geheimnummer" />
  </ElementsIfValue>
</Choice>

Attribute für `Choice`

Attributname	Beschreibung

Attributname	Beschreibung
`Id` (erforderlich)	Wird zur Identifikation benötigt (Einfügen in der Vorlage, Verwendung in Feldern). Darf keine Leerzeichen enthalten und muss eindeutig sein. Forms fügt automatisch den Präfix `Forms.` hinzu (aus `Classification` wird z. B. `Forms.Classification`).
`Label` (erforderlich)	Beschreibung des Elements in der Eingabeoberfläche
`Required` (optional)	Wenn `true`: Der Benutzer muss eine Option auswählen. Empfohlen: Zusätzlich eine spezifische `ValidationMessage` konfigurieren.
`SelectedValue` (optional)	Vorausgewählte Option: Hier muss der Wert, der bei der gewünschten Option im `Value`-Attribut steht, angegeben werden.
`EmptyOptionLabel` (optional)	Beschriftung der Option, die "nichts ausgewählt" symbolisiert.
`OnlyVisibleDuringGeneration` (optional)	Wenn `true`: Das Feld wird nur beim erstmaligen Generieren des Dokuments angezeigt. Öffnet der Benutzer den Forms-Dialog erneut im primedocs Ribbon im offenen Dokument, wird es nicht mehr angezeigt.

Inhalte für `Choice`

Elementname	Beschreibung

Elementname

Beschreibung

Option
(erforderlich,
mehrere möglich)

Mögliche Auswahl. Es muss mindestens eine mögliche Auswahl konfiguriert werden.
Attribute:

Value: Entspricht Value von ComboBox-DataNode beim Dokument-Parameter.
Label: Entspricht DisplayText von ComboBox-DataNode beim Dokument-Parameter.

Description
(optional)

Zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche als Tooltip angezeigt.

ValidationMessage
(optional)

Text, der dem Benutzer angezeigt wird, wenn diese Auswahl ungültig ausgefüllt wurde.

AdditionalProfile

Das AdditionalProfile-Element ermöglicht dem Benutzer das Auswählen eines zusätzlichen Profils. Die vom Benutzer erstellten Profile sowie die dem Benutzer freigegebenen Fremdprofile werden im Forms in einem Dropdown angezeigt und können ausgewählt werden.

Da ein Profil auf dem Benutzer basiert und ein Benutzer verschiedene Benutzerfelder hat (z.B. Vorname, Telefonnummer, Funktion, Signaturbild etc.), werden in der Vorlage alle Benutzerfelder eines Benutzers zum Einfügen angeboten. Da ein Benutzerfeld entweder ein Text, eine Checkbox oder ein Bild ist, kann in der Vorlage das dementsprechende Inhaltssteuerelement eingefügt werden.

AdditionalProfiles können nur mittels XML-Konfiguration und nicht via Designer definiert werden.

Beispiel

Der meistverwendete Fall in dem ein AdditionalProfile eingesetzt wird, ist die Unterzeichnung eines Dokuments. Zum Beispiel möchte man dem Benutzer für einen Brief zwei AdditionalProfiles anbieten: das erste mit einer Vorselektion des eigenen Profils und das zweite zur freien Auswahl einer mitunterzeichnenden Person.

<AdditionalProfile Id="MainSigner" Label="Hauptunterzeichnende*r" PreselectByIndex="1" />
<AdditionalProfile Id="CoSigner"   Label="Mitunterzeichnende*r" />

Attribute für `AdditionalProfile`

Attributname	Beschreibung

Attributname	Beschreibung
`Id` (erforderlich)	Wird zur Identifikation benötigt (Einfügen in der Vorlage, Verwendung in Feldern). Darf keine Leerzeichen enthalten und muss eindeutig sein. Forms fügt automatisch den Präfix `Forms.` hinzu (aus `Classification` wird z. B. `Forms.Classification`).
`Label` (erforderlich)	Beschreibung des Elements in der Eingabeoberfläche
`PreselectByIndex` (optional)	Erfordert die Eingabe einer ganzen Zahl (1, 2, 3, …, n). Wenn `1`: Das im Unterschriftsprofil erste hinterlegte Profil wird vorselektiert. Wenn `n`: Wenn eines hinterlegt ist, wird das im Unterschriftsprofil `n`te Profil vorselektiert.

Inhalte für `AdditionalProfile`

Elementname	Beschreibung

Elementname	Beschreibung
`Description` (optional)	Zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche als Tooltip angezeigt.

Objects und ObjectCollections

Diese Funktion steht nicht in “classic” Vorlagen zur Verfügung.

Als Alternative für “classic” Vorlagen kann über die Adressschnittstellen (classic) auf Kontaktdaten zugegriffen werden. Weitere Informationen zu den verschiedenen Vorlagen Versionen finden Sie hier.

Object bzw. ObjectCollection s können definiert werden, um Objekte, wie z. B. einen Empfänger, Rechnungspositionen oder beliebige andere Datenobjekte in der Vorlage abzubilden.

Muss nur ein Objekt in der Vorlage abgebildet werden, nimmt man das Element Object.

Müssen mehrere Objekte abgebildet werden, nimmt man das Element ObjectCollection.

Ein Object bzw. eine ObjectCollection wird in Forms folgendermassen angezeigt:

Ein Object / ObjectCollection in Forms

Attribute für `Object` bzw. `ObjectCollection`

Attributname	Beschreibung

Attributname	Beschreibung
`Id` (erforderlich)	Wird zur Identifikation benötigt (Einfügen in der Vorlage, Verwendung in Feldern). Darf keine Leerzeichen enthalten und muss eindeutig sein. Forms fügt automatisch den Präfix `Forms.` hinzu (aus `Classification` wird z. B. `Forms.Classification`).
`Label` (erforderlich)	Beschreibung des Elements in der Eingabeoberfläche

Inhalte für `Object` bzw. `ObjectCollection`

Elementname	Beschreibung

Elementname	Beschreibung
`Schema`	Definiert alle benötigten Daten, die schlussendlich in einer Vorlage verwendet können sollen.
`Summary`	Definiert, welche Felder in der Listenansicht angezeigt werden sollen.
`DataProviders` (optional)	Definiert Datenquellen, um Objekte z.B. von einem CRM, einer Web-API oder anderen Quellen zu laden.

Wie jedes Element, können auch Objects oder ObjectCollections in einer Forms-Konfiguration beliebig oft definiert werden. Mehr Informationen sind auf der Seite Datenschnittstelle nachzulesen.

Objects, ObjectCollections und DataProviders können nur mittels XML-Konfiguration definiert werden.

Beispiel Anwendungsfall Vorlage “Protokoll“

Das folgende Beispiel zeigt den Grundaufbau einer ObjectCollection. Sie besteht aus Schema, Summary sowie DataProviders.

XML-Konfiguration

<FormsConfiguration>
  <Elements>
    <!-- Formularelemente -->
    <ObjectCollection Id="data" Label="Teilnehmende">
      <!-- Defines the ObjectCollection's elements to use in JavaScript -->
      <Schema>
        <Text Id="FirstName" Label="Vorname" />
        <Text Id="LastName" Label="Name" />
        <Text Id="Alias" Label="Kürzel" />
        <YesNo Id="IsLead" Label="Hat Sitzungsleitung" />
        <YesNo Id="IsProtocol" Label="Macht Protokoll" />
      </Schema>
      <!-- Defines what fields are shown in the list view -->
      <Summary>
        <Field Id="FirstName" />
        <Field Id="LastName" />
        <Field Id="Alias" />
      </Summary>
      <!-- Defines the DataProviders -->
      <DataProviders>
        [...]      
      </DataProviders>
    </ObjectCollection>
  </Elements>
</FormsConfiguration>

Screenshots

1) Listenansicht: ohne hinzugefügte Objekte

ObjectCollection in Forms ohne Objekte

3) Listenansicht mit hinzugefügten Objekten

In der Listenansicht werden FirstName, LastName und Alias angezeigt (in Summary definiert).

ObjectCollection in Forms mit Objekten

2) Forms: Objekte erfassen

In der Protokoll-Vorlage werden die Daten für die Eingaben von FirstName, LastName, Alias sowie den YesNo-Werten von IsLead und IsProtocol verwendet (in Schema definiert).

Objekte erfassen in Forms

Zugriff auf global abgelegte Einträge

Es gibt die folgenden Typen von globalen Einträgen, die in einer Forms-Konfiguration referenziert werden können:

GlobalSchemaAndSummary → eine global abgelegte Konfiguration mit den Elementen Schema und Summary.
GlobalDataProviders → eine global abgelegte Konfiguration mit den Elementen CsvDataProvider, ExcelDataProvider, GlobalDataProviders, HttpDataProvider oder SqlDataProvider.
GlobalElements → alle anderen Elemente (z.B. Text oder YesNo) exklusive Group.

Mehr Informationen zu den Globalen Konfigurationen sind hier zu finden: Globale Konfigurationen | Umgang mit typisierten Feldern.

Attribute für `GlobalElements`, `GlobalSchemaAndSummary` und `GlobalDataProviders`

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

Attributname	Beschreibung

Attributname	Beschreibung
`Key` (erforderlich)	Die ID des globalen Eintrags, der referenziert werden soll.

Beispiel

<FormsConfiguration>
  <Elements>
    <Group Title="Empfängeradressen">
      <GlobalElements Key="Forms.Recipient" />
    </Group>
    <Group Title="Brief">
      <GlobalElements Key="Forms.ContactTypeRefNr" />
      <GlobalElements Key="Forms.DateSubject" />
      <GlobalElements Key="Forms.Signers" />
      <GlobalElements Key="Forms.CopyAttachments" />
    </Group>
  </Elements>
</FormsConfiguration>

Ein konkretes Beispiel zum Erkennen des Zusammenhangs zwischen dem globalen Eintrag und der Referenz auf einen globalen Eintrag gibt es hier: Globale Konfigurationen | Globale Einträge in den Vorlagen referenzieren.

GlobalSchemaAndSummary

Dieses Element holt einen Eintrag aus den Globalen Konfigurationen vom Typ FormsGlobalSchemaAndSummary, um ein Object oder eine ObjectCollection zu konfigurieren.

<FormsConfiguration>
  <ObjectCollection Id="Recipient" Label="Empfängeradressen">
    <GlobalSchemaAndSummary Key="Recipients.Objects.ProtocolSchema" />
  </ObjectCollection>
</FormsConfiguration>

GlobalDataProviders

Dieses Element holt einen Eintrag aus den Globalen Konfigurationen vom Typ FormsGlobalDataProviders, um ein Object oder eine ObjectCollection zu konfigurieren.

<FormsConfiguration>
  <Object Id="Recipient" Label="Empfängeradressen">
    <GlobalSchemaAndSummary Key="Recipients.Objects.DefaultSchema" />
    <DataProviders>
      <GlobalDataProviders Key="Recipients.Objects.DefaultProviders" />
    </DataProviders>
  </Object>
</FormsConfiguration>

GlobalElements

Dieses Element holt einen Eintrag aus den Globalen Konfigurationen vom Typ FormsGlobalElements.

<FormsConfiguration>
  <GlobalElements Key="Forms.ReportDefault" />
</FormsConfiguration>

Übersetzungen

Alle obengenannten Elemente können mit Übersetzung angezeigt werden. Wird ein Attribut mit dem Präfix translate- verwendet, muss das entsprechende Attribut nicht auch konfiguriert werden. Stattdessen wird die jeweilige ID eines Übersetzungseintrags von den Globalen Übersetzungen angegeben.

Der Einsatz der translate-Attribute in Forms machen in folgenden Fällen Sinn:

Bei Lösungen mit mehreren Benutzeroberflächensprachen: hier sind translate-Attribute notwendig, damit der Dialog in jeder jeweiligen Sprache angezeigt wird und die entsprechenden Übersetzungen erstellt werden.
Bei Lösungen mit einer Benutzeroberflächensprache: hier sind translate-Attribute nicht notwendig, aber durchaus sinnvoll, wenn man sicherstellen möchte, dass bei einer Änderung eines Wortes, diese Änderung nur einmal global angepasst werden kann.

Attribute

Attributname	Beschreibung

Attributname	Beschreibung
`translate-Label` (optional)	Übersetzte Beschreibung des Elements in der Eingabeoberfläche.
`translate-Description` (optional)	Übersetzte zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche angezeigt.
`translate-ValidationMessage` (optional)	Übersetzter Text, der dem Benutzer angezeigt wird, wenn diese Auswahl ungültig ausgefüllt wurde.
`translate-Value` (optional)	Übersetzter, vordefinierter Wert (je nach Elementart), den der Benutzer bearbeiten kann.

Anwendungsbeispiel mit `translate-` Attributen

<FormsConfiguration>
  <Elements>
    <Text Id="Subject"         translate-Label="FormsTexts.Subject" />
    <Text Id="Title"           translate-Value="Texts.Memo" translate-Label="FormsTexts.Title" />
    <YesNo Id="ShowSalutation" translate-Description="FormsDescriptions.ShowSalutation" translate-Label="FormsTexts.ShowSalutation" />
    <Text Id="CopyTo"          Required="true" translate-ValidationMessage="FormsMsg.MandatoryField" translate-Label="FormsTexts.Title" />
    <Date Id="Date"            translate-Label="FormsTexts.Date" translate-Format="DateFormat.WrittenOut" />
  </Elements>
</FormsConfiguration>

Erklärung des Anwendungsbeispiels

Alle Formularelemente haben eine übersetzte Beschreibung (Label), z.B. das Textfeld Subject.
Das Textfeld Title hat einen fix hinterlegten Wert.
Die CheckBox ShowSalutation hat eine zusätzliche übersetzte Information.
Das Textfeld CopyTo muss zwingend ausgefüllt werden und hat eine übersetzte Validierungsnachricht.
Das Datumsfeld Date hat ein Datumsformat, das in einem globalen Übersetzungseintrag ist, weil es sprachabhängig ist (z.B. im Fall von 05.08.2024 (Deutsch) und 08/05/2024 (Englisch)).

Glossar

Deutsch	Englisch	Beschreibung

Deutsch	Englisch	Beschreibung
Forms	Forms	Name der neuen Dokumentfunktion, Gegenstück in classic-Vorlagen: "Dokument-Parameter"
Forms-Dialog	Forms dialog	Bezeichnung für den neuen Dialog, Gegenstück in classic-Vorlagen: "Dokument-Parameter-Dialog"
Formularelement	Form element	Ein Input-Element im Forms-Dialog, z. B. vom Typ "Text" oder "Choice"
Strukturelement	Structural element	Elemente, die im Forms-Dialog angezeigt werden, die aber keinen Input anfordern und daher nicht im Document Part landen
Feld	Field	Alle Formularelemente, welche schlussendlich im Document Part landen
Nur-Text-Inhaltssteuerelement	Plain Text Content Control	Word-Content Control, das nur Text enthalten kann (offizielle Bezeichnung im Word-GUI)
Datumsauswahl-Inhaltssteuerelement	Date Picker Content Control	Word-Content Control, bei dem ein Datum ausgewählt werden kann (offizielle Bezeichnung im Word-GUI)
Kontrollkästchensteuerelement	Check Box Content Control	Word-Content Control mit CheckBox-Symbol, das aktiviert und deaktiviert werden kann (offizielle Bezeichnung im Word-GUI)
Dropdownlisten-Inhaltssteuerelement	Drop-Down List Content Control	Word-Content Control, beidem aus vorgegebenen Optionen ausgewählt werden kann (offizielle Bezeichnung im Word-GUI)
Kombinationsfeld-Inhaltssteuerelement	Combo Box Content Control	Word-Content Control, beidem aus vorgegebenen Optionen ausgewählt und auch irgendein gewünschter Text eingegeben werden kann (offizielle Bezeichnung im Word-GUI)
Objekt	Object	Ein Objekt wird über ein Schema definiert. Objekte lassen sich manuell oder über `DataProvider` abfüllen.
Objektliste	ObjectCollection	Eine Ansammlung von Objekten. Der Unterschied zum Objekt liegt darin, dass die Liste mehre Objekte des gleichen Types speichern kann.
DataProvider	DataProvider	Definiert eine Quelle für Objekte.

Ausführliches Beispiel

Die Reihenfolge der Formularelemente im Forms-XML bestimmt die Reihenfolge im Dialog.

Code

Forms

<FormsConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Elements>
    <Object Id="RecipientAddressData" translate-Label="AddressData.Addresses">
      <!-- Defines the ObjectCollection's elements to use in JavaScript -->
      <Schema>
        <Text Id="CompanyName" translate-Label="AddressData.Company" />
        <Text Id="FirstName" translate-Label="AddressData.FirstName" />
        <Text Id="Surname" translate-Label="AddressData.Surname" />
        <Text Id="Street" translate-Label="AddressData.Street" />
        <Text Id="PostalCode" translate-Label="AddressData.PostalCode" />
        <Text Id="City" translate-Label="AddressData.City" />
        <Text Id="Country" translate-Label="AddressData.Country" />
      </Schema>
      <!-- Defines what fields are shown in the result list -->
      <Summary>
        <Field Id="CompanyName" />
        <Field Id="FirstName" />
        <Field Id="Surname" />
        <Field Id="Street" />
        <Field Id="City" />
      </Summary>
      <!-- Defines the DataProviders -->
      <DataProviders>
        <!-- CsvDataProvider -->
        <CsvDataProvider DisplayName="Kundenadressen">
          <Options>
            <FilePath>\\fileshare\addressdata.csv</FilePath>
            <HasHeaders>true</HasHeaders>
            <Delimiter>,</Delimiter>
          </Options>
          <SearchParameters>
            <Text Id="Vorname" translate-Label="AddressData.FirstName" />
            <Text Id="Nachname" translate-Label="AddressData.Surname" />
            <Text Id="Ort" translate-Label="AddressData.City" />
          </SearchParameters>
          <Mapping>
            <!-- Source = Spaltenname in Csv / Target = Schema-Element-Id ↑ -->
            <Map Source="Vorname" Target="FirstName" />
            <Map Source="Nachname" Target="Surname" />
            <Map Source="Adresse" Target="Street" />
            <Map Source="Postleitzahl" Target="PostalCode" />
            <Map Source="Ort" Target="City" />
            <Map Source="Land" Target="Country" />
            <Map Source="Telefonnummer" Target="Phone" />
            <Map Source="E-Mail-Adresse" Target="Email" />
          </Mapping>
        </CsvDataProvider>
      </DataProviders>
    </Object>
    <Text Id="Salutation" translate-Label="Forms.Salutation" />
    <Text Id="Subject" translate-Label="Forms.Subject" />
    <Date Id="Date" translate-Label="Forms.Date" RelativeDate="Today" translate-Format="DateFormat.WrittenOut" />
  </Elements>
</FormsConfiguration>

Felder

<FieldsConfiguration>
  <Fields>
    <!-- Funktion definiert, wie die einzelnen Felder des Feldes "RecipientAddressData" 
    im Dokument ausgegeben sollen (JavaScript) -->
    <Text Name="RecipientAddressBlock">
      <Code>
        function main() {
          if ($("Forms.RecipientAddressData") !== undefined){
            const firstRecipient = $("Forms.RecipientAddressData");
            
            var recipientBlock = $.joinNonEmpty("\n",
              firstRecipient.CompanyName != "" ? firstRecipient.CompanyName : firstRecipient.FirstName + " " + firstRecipient.Surname,
              firstRecipient.Street,
              firstRecipient.PostalCode + " " + firstRecipient.City);
            
            if (firstRecipient.Country != "CH"){
              recipientBlock += "\n" + firstRecipient.Country;
            }
            return recipientBlock;
            
          } else {
            return "";
          }
        }
      </Code>
    </Text>
  </Fields>
</FieldsConfiguration>

Formulare (Forms)

Zweck und Einsatz

Grundaufbau

Designer

Beispiel

Übersicht

Weitere Profile in Vorlage integrieren

Adaptive Dateneingabemaske

Elemente

Gruppen

Attribute für Group

Info

Beispiel in XML

Text

Beispiele in XML mit Vorschau

Attribute für Text

Inhalte für Text

Date

Beispiele im XML mit Vorschau

Attribute für Date

Inhalte für Date

YesNo

Beispiele in XML mit Vorschau

Attribute für YesNo

Inhalte für YesNo

Choice

Beispiele im XML mit Vorschau

Attribute für Choice

Inhalte für Choice

AdditionalProfile

Beispiel

Attribute für AdditionalProfile

Inhalte für AdditionalProfile

Objects und ObjectCollections

Attribute für Object bzw. ObjectCollection

Inhalte für Object bzw. ObjectCollection

Beispiel Anwendungsfall Vorlage “Protokoll“

XML-Konfiguration

Screenshots

Zugriff auf global abgelegte Einträge

Attribute für GlobalElements, GlobalSchemaAndSummary und GlobalDataProviders

Beispiel

GlobalSchemaAndSummary

GlobalDataProviders

GlobalElements

Übersetzungen

Attribute

Anwendungsbeispiel mit translate- Attributen

Erklärung des Anwendungsbeispiels

Glossar

Ausführliches Beispiel

Code

Forms

Felder

Screenshot

Attribute für `Group`

Attribute für `Text`

Inhalte für `Text`

Attribute für `Date`

Inhalte für `Date`

Attribute für `YesNo`

Inhalte für `YesNo`

Attribute für `Choice`

Inhalte für `Choice`

Attribute für `AdditionalProfile`

Inhalte für `AdditionalProfile`

Attribute für `Object` bzw. `ObjectCollection`

Inhalte für `Object` bzw. `ObjectCollection`

Attribute für `GlobalElements`, `GlobalSchemaAndSummary` und `GlobalDataProviders`

Anwendungsbeispiel mit `translate-` Attributen