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
  - 5.8.2 Attribute für ObjectCollection
  - 5.8.3 Serienerstellung über SelectedObjectId bei ObjectCollection
  - 5.8.4 Inhalte für Object bzw. ObjectCollection
  - 5.8.5 Beispiel Anwendungsfall Vorlage “Protokoll“
    - 5.8.5.1 XML-Konfiguration
    - 5.8.5.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

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

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`