Formulare (Forms)
- Robert Mühsig
- Dinah Bolli (Unlicensed)
- 1 Zweck und Einsatz
- 2 Grundaufbau
- 3 Designer
- 3.1 Beispiel
- 4 Übersicht
- 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.1 Gruppen
- 6 Zugriff auf global abgelegte Einträge
- 7 Übersetzungen
- 8 Glossar
- 9 Ausführliches Beispiel
- 9.1 Code
- 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
GroupInfo
Formularelemente
TextDateYesNo(Checkbox)Choice(Dropdown)AdditionalProfileObjectoderObjectCollectionGlobalSchemaAndSummary(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.
<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
Gruppen dürfen nicht weitere Gruppen enthalten (es gibt keine Verschachtelung).
Attribute für Group
Attributname | Beschreibung |
|---|---|
| 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
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:
Erweitert:
Attribute für Text
Attributname | Beschreibung |
|---|---|
| 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 |
| Beschreibung des Elements in der Eingabeoberfläche |
| Vordefinierter Text, den der Benutzer bearbeiten kann. |
| Wenn |
| Wenn |
| Wenn |
Inhalte für Text
Elementname | Beschreibung |
|---|---|
| Zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche als Tooltip angezeigt. |
| 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:
Erweitert: mit Value und Required:
Erweitert: mit RelativeDate:
Gerechnet ab Datum: 12.01.2024
Attribute für Date
Attributname | Beschreibung |
|---|---|
| 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 |
| Beschreibung des Elements in der Eingabeoberfläche |
| Definition des Datumformates, z. B. |
| Wenn |
| Vorausgewähltes fixes Datum, das der Benutzer bearbeiten kann. |
| Vorausgewähltes Datum, das der Benutzer bearbeiten kann und das relativ zum Zeitpunkt der Dokumenterstellung ist.
Die Attribute
|
| Anzahl Monate, die zum relativen Datum dazu addiert werden (positive und negative Zahlen erlaubt). Siehe |
| Anzahl Tage, die zum relativen Datum dazuaddiert werden (positive und negative Zahlen erlaubt). Siehe |
| Wenn |
Inhalte für Date
Elementname | Beschreibung |
|---|---|
| Zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche als Tooltip angezeigt. |
| 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:
Erweitert mit adaptiver Dateneingabe
Attribute für YesNo
Attributname | Beschreibung |
|---|---|
| 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 |
| Beschreibung des Elements in der Eingabeoberfläche |
| Wenn |
| Wenn |
| Wenn |
Inhalte für YesNo
Elementname | Beschreibung |
|---|---|
| Adaptive Dateneingabe: ist der Wert |
| Adaptive Dateneingabe: ist der Wert |
| Zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche als Tooltip angezeigt. |
| 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:
Erweitert mit adaptiver Dateneingabe:
Attribute für Choice
Attributname | Beschreibung |
|---|---|
| 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 |
| Beschreibung des Elements in der Eingabeoberfläche |
| Wenn |
| Vorausgewählte Option: Hier muss der Wert, der bei der gewünschten Option im |
| Beschriftung der Option, die "nichts ausgewählt" symbolisiert. |
| Wenn |
Inhalte für Choice
Elementname | Beschreibung |
|---|---|
| Mögliche Auswahl. Es muss mindestens eine mögliche Auswahl konfiguriert werden.
|
| Zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche als Tooltip angezeigt. |
| 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.
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.
Attribute für AdditionalProfile
Attributname | Beschreibung |
|---|---|
| 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 |
| Beschreibung des Elements in der Eingabeoberfläche |
| Erfordert die Eingabe einer ganzen Zahl (1, 2, 3, …, n). |
Inhalte für AdditionalProfile
Elementname | Beschreibung |
|---|---|
| Zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche als Tooltip angezeigt. |
Objects und ObjectCollections
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.
Ein Object bzw. eine ObjectCollection wird in Forms folgendermassen angezeigt:
Attribute für Object bzw. ObjectCollection
Attributname | Beschreibung |
|---|---|
| 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 |
| Beschreibung des Elements in der Eingabeoberfläche |
Inhalte für Object bzw. ObjectCollection
Elementname | Beschreibung |
|---|---|
| Definiert alle benötigten Daten, die schlussendlich in einer Vorlage verwendet können sollen. |
| Definiert, welche Felder in der Listenansicht angezeigt werden sollen. |
| 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.
Beispiel Anwendungsfall Vorlage “Protokoll“
Das folgende Beispiel zeigt den Grundaufbau einer ObjectCollection. Sie besteht aus Schema, Summary sowie DataProviders.
XML-Konfiguration
Screenshots
1) Listenansicht: ohne hinzugefügte Objekte
3) Listenansicht mit hinzugefügten Objekten
In der Listenansicht werden FirstName, LastName und Alias angezeigt (in Summary definiert).
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).
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
SchemaundSummary.GlobalDataProviders → eine global abgelegte Konfiguration mit den Elementen
CsvDataProvider,ExcelDataProvider,GlobalDataProviders,HttpDataProvideroderSqlDataProvider.GlobalElements → alle anderen Elemente (z.B.
TextoderYesNo) exklusiveGroup.
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 |
|---|---|
| Die ID des globalen Eintrags, der referenziert werden soll. |
Beispiel
Ein konkretes Beispiel zum Erkennen des Zusammenhangs zwischen dem globalen Eintrag und der Referenz auf einen globalen Eintrag gibt es hier: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/31457334/Globale+Konfigurationen#Globale-Eintr%C3%A4ge-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.
GlobalDataProviders
Dieses Element holt einen Eintrag aus den Globalen Konfigurationen vom Typ FormsGlobalDataProviders, um ein Object oder eine ObjectCollection zu konfigurieren.
GlobalElements
Dieses Element holt einen Eintrag aus den Globalen Konfigurationen vom Typ FormsGlobalElements.
Ü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.
Attribute
Attributname | Beschreibung |
|---|---|
(optional) | Übersetzte Beschreibung des Elements in der Eingabeoberfläche. |
(optional) | Übersetzte zusätzliche Informationen für den Benutzer, der das Formular ausfüllt. Wird in der Eingabeoberfläche angezeigt. |
| Übersetzter Text, der dem Benutzer angezeigt wird, wenn diese Auswahl ungültig ausgefüllt wurde. |
| Übersetzter, vordefinierter Wert (je nach Elementart), den der Benutzer bearbeiten kann. |
Anwendungsbeispiel mit translate- Attributen
Erklärung des Anwendungsbeispiels
Alle Formularelemente haben eine übersetzte Beschreibung (
Label), z.B. das TextfeldSubject.Das Textfeld
Titlehat einen fix hinterlegten Wert.Die CheckBox
ShowSalutationhat eine zusätzliche übersetzte Information.Das Textfeld
CopyTomuss zwingend ausgefüllt werden und hat eine übersetzte Validierungsnachricht.Das Datumsfeld
Datehat 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 |
|---|---|---|
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 |
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
Code
Forms
Felder
Screenshot
PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland