Forms
- Dinah Bolli (Unlicensed)
- Daniela Zimmermann
- 1 Purpose and use
- 2 Structure
- 3 Designer
- 3.1 Example
- 4 Overview
- 5 Elements
- 5.1 Groups
- 5.2 Info
- 5.3 Text
- 5.3.1 Examples
- 5.3.2 Attributes for Text
- 5.3.3 Contents for Text
- 5.4 Date
- 5.4.1 Examples in XML with preview
- 5.4.2 Attributes for Date
- 5.4.3 Content for Date
- 5.5 YesNo
- 5.5.1 Examples in XML with preview
- 5.5.2 Attributes for YesNo
- 5.5.3 Contents for YesNo
- 5.6 Choice
- 5.6.1 Examples in XML with preview
- 5.6.2 Attributes for Choice
- 5.6.3 Contents for Choice
- 5.7 AdditionalProfile
- 5.7.1 Example
- 5.7.2 Attribute for AdditionalProfile
- 5.7.3 Content for AdditionalProfile
- 5.8 Objects, ObjectCollections und DataProvider
- 6 Übersetzungen
- 7 Glossary, Terms
- 8 Extensive example
- 8.1 Code
- 8.2 Screenshot
Purpose and use
This document function can be used to query content via a form by configuring text boxes, checkboxes, dropdowns, etc., so-called elements.
This function is not available to its full extent in ‘classic’ templates.
Further information on the different template versions can be found here.
Structure
<FormsConfiguration>
<Elements>
<!-- Insert form elements and groups here -->
</Elements>
</FormsConfiguration>Designer
If you open Forms in the template editor, you are automatically taken to the simple view. Clicking on the preview takes you to the Forms Designer. The designer allows you to put together the form in a user interface in no time at all.
A form consists of various elements: structural elements that contribute to the clarity of the form and form elements whose values entered by the user ultimately end up in the document.
Behind the Designer user interface is an XML configuration for each element. This can be found via the ‘Advanced view’ button. All elements are now described in the following chapter.
Example
<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="Main-signer" PreselectByIndex="1" />
<AdditionalProfile Id="CoSigner" Label="Co-signer" />
<Group Title="Additional settings">
<YesNo Id="ShowContact" Label="Show contact" Value="true">
<ElementsIfYes>
<Choice Id="ContactFormOption" Label="Display type" SelectedValue="0">
<Option Value="0" Label="Impersonal contact" />
<Option Value="1" Label="Personal contact" />
</Choice>
</ElementsIfYes>
</YesNo>
</Group>
<GlobalElements Key="Forms.Attachments" />
</Elements>
</FormsConfiguration>Overview
The following form elements are possible:
Structure elements
GroupInfo
Form elements
TextDateYesNo(Checkbox)Choice(Dropdown)AdditionalProfileObjectorObjectCollectionGlobalSchemaAndSummary(globally stored schema/summary configuration)GlobalDataProviders(globally stored DataProvider)GlobalElements(globally stored Forms configuration)
Integrate additional profiles into template
The profile fields of the user who generates a document are automatically provided during document creation and contain, for example, organisational data such as logos or postal addresses as well as personal user data. By switching profiles in the primedocs ribbon, the data of the selected profile is displayed in a document that contains profile fields.
Additional profiles can be integrated into the document using AdditionalProfile. This profile selection displays the user's own profiles or external profiles that have been released for the user.AdditionalProfiles are therefore intended for use cases in which other people from the company are to appear in the document. The use of AdditionalProfile is useful, for example...
for additional signatures in a template.
when working with other employees or departments in a template. e.g. in a template, the cost centre manager should also be mentioned in addition to the head of department.
in many more use cases.
The corresponding forms fields of the AdditionalProfile must therefore also be inserted in the template.
Adaptive data input mask
Forms allows fields to be displayed based on a conditional value. In the YesNo and Choice form elements, this allows you to control the appearance of other form elements based on a value. The possible form elements that can appear are: Text, Date, Choice, YesNo and Info.
Example: an info element should only be displayed if the YesNo field is activated (= true):
The elements for the adaptive data entry mask are called ElementsIfYes / ElementsIfNo for YesNo elements (for true and false) and ElementsIfValue for Choice elements (for a specific value). Examples of the XML configuration and the documentation of the ElementsIf elements can be found under Forms | Attributes for Choice and Forms | Attributes for YesNo .
<YesNo Name="ShowThing" Label="Muss unterzeichnet werden">
<ElementsIfYes>
<Info>Please ensure that a signature image is stored.<Info>
</ElementsIfYes>
</YesNo>Elements
Groups
Groups are structure elements and group form elements with <Group>...</Group> for visual representation.
Groups must not contain other groups (no nesting).
Attributes for Group
Attributname | Description |
|---|---|
| Title that will be displayed on the input interface. |
Info
This element allows to display information text in the Forms dialog. The text to be displayed is specified as the content of the Info element.
Example:
Text
The Text element provides the user with the ability to enter text in Forms. Accordingly, it is typically displayed as a text box. A Plain Text Content Control is inserted in the Word template.
Examples
Simple
Advanced
Attributes for Text
Attribute name | Description |
|---|---|
| Required for identification (insertion in template, use in https://primesoft-group.atlassian.net/wiki/x/YQapAw ). Must not contain spaces and must be unique. Forms automatically adds the prefix |
| Label of the element in the input interface. |
| Predefined text that the user can edit |
| If |
| If |
| If |
Contents for Text
Element name | Description |
|---|---|
| Additional information for the user filling in the form. Displayed in the input interface (possibly as a tooltip). |
| Text that will be displayed to the user if this text field was filled in invalidly. |
Date
The Date element allows the user to select a date in forms. It is typically displayed as a date picker. A date picker content control is inserted in the template.
Examples in XML with preview
Simple:
Expanded: with Value and Required:
Expanded: with RelativeDate:
Calculated from date: 12.01.2024
Attributes for Date
Attribute name | Description |
|---|---|
| Is required for identification (insertion in the template, use in https://primesoft-group.atlassian.net/wiki/x/YQapAw ). Must not contain spaces and must be unique. Forms automatically adds the prefix |
| Description of the element in the input interface |
| Definition of the date format, e.g. |
| If |
| Preselected fixed date that the user can edit. |
| Preselected date that the user can edit and that is relative to the time of document creation.
The
|
| Number of months that are added to the relative date (positive and negative numbers permitted). See |
| Number of days that are added to the relative date (positive and negative numbers permitted). See |
| If |
Content for Date
Element name | Description |
|---|---|
| Additional information for the user filling out the form. Is displayed as a tooltip in the input interface. |
| Text that is displayed to the user if this date field has been filled in invalidly. |
YesNo
The YesNo element provides the user with the ability to check ("Yes") or uncheck ("No") an option in the input interface. Accordingly, it is typically displayed as a check box. A Check Box Content Control is inserted in the Word template.
Examples in XML with preview
Simple
Enhanced with adaptive data input
Attributes for YesNo
Attribute name | Description |
|---|---|
| Required for identification (insertion in template, use in scripts). Must not contain spaces and must be unique. Forms automatically adds the prefix |
| Label of the element in the input interface |
| If |
| If |
| If |
Contents for YesNo
Element name | Description |
|---|---|
| Adaptive data entry: if the value is |
| Adaptive data entry: if the value is |
| Additional information for the user filling in the form. Displayed in the input interface (possibly as a tooltip). |
| Text that will be displayed to the user if this text field was filled in invalidly. |
Choice
The Choice element provides the user with the ability to choose between different options in the input interface. Accordingly, it is typically displayed as a drop down. A combo box content control is inserted in the Word template.
Examples in XML with preview
Simple
Erweitert mit adaptiver Dateneingabe:
Attributes for Choice
Attribute name | Description |
|---|---|
| Required for identification (insertion in template, use in scripts). Must not contain spaces and must be unique. Forms automatically adds the prefix |
| Label the element in the input interface. |
| If |
| Preselected option: The value that is in the |
| Label of the option symbolizing "nothing selected" |
| If |
Contents for Choice
Element name | Description |
|---|---|
| Possible selection. At least one possible selection must be configured.
|
| Additional information for the user filling out the form. Is displayed as a tooltip in the input interface. |
| Text that is displayed to the user if this selection is invalid. |
AdditionalProfile
The AdditionalProfile element allows the user to select an additional profile. The profiles created by the user and the external profiles released to the user are displayed in a dropdown in the form and can be selected.
As a profile is based on the user and a user has various user fields (e.g. first name, telephone number, function, signature image, etc.), all user fields of a user are offered for insertion in the template. As a user field is either a text, a checkbox or an image, the corresponding content control can be inserted in the template.
Example
The most common case in which an AdditionalProfile is used is the signing of a document. For example, you would like to offer the user two AdditionalProfiles for a letter: the first with a pre-selection of their own profile and the second for the free selection of a co-signing person.
Attribute for AdditionalProfile
Attribute name | Description |
|---|---|
| Is required for identification (insertion in the template, use in fields). Must not contain spaces and must be unique. Forms automatically adds the prefix |
| Description of the element in the input interface |
| Requires the entry of an integer (1, 2, 3, ..., n). |
Content for AdditionalProfile
Element name | Description |
|---|---|
| Additional information for the user filling out the form. Is displayed as a tooltip in the input interface. |
Objects, ObjectCollections und DataProvider
Object or ObjectCollection s can be defined to map objects such as a recipient, invoice items or any other data objects in the template.
An Object or an ObjectCollection is displayed in Forms as follows:
Attribute für Object bzw. ObjectCollection
Attribute name | Description |
|---|---|
| Is required for identification (insertion in the template, use in fields). Must not contain spaces and must be unique. Forms automatically adds the prefix |
| Description of the element in the input interface |
Inhalte für Object bzw. ObjectCollection
Element name | Description |
|---|---|
| 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. |
Like any element, Objects oder ObjectCollections can be configured any number of ways. More information can be found on the Data interface page.
Beispiel Anwendungsfall Vorlage “Protokoll“
The following example shows the basic structure of an ObjectCollection. It consists of Schema, Summary as well as DataProviders:
XML-Konfiguration
Übersetzungen
All the above-mentioned elements can be displayed with translation. If an attribute with the prefix translate- is used, the corresponding attribute does not have to be configured as well.
Translations are fetched from the Global Translations as follows:
Attribute name | Description |
|---|---|
(optional) | Translated label of the element in the input interface. |
(optional) | Translated additional information for the user filling in the form. Displayed in the input interface. |
| Translated text displayed to the user if this selection was filled in invalidly. |
| Translated, predefined value (depending on the element type) that the user can edit. |
Application example from above with translated labels:
Glossary, Terms
Name | Description |
|---|---|
Forms | Name of the new document function, formerly quasi "Document Parameter". |
Forms dialog | Name for the new dialog, formerly quasi "Document Parameter dialog" |
Form element | An input element in the Forms dialog, e.g. of type "Text" or "Choice |
Structural element | Elements that are displayed in the Forms dialog but do not request input and therefore do not end up in the Document Part |
Field | All form elements, which finally end up in the Document Part |
Plain Text Content Control | Word content control that can only contain text |
Date Picker Content Control | Word content control where a date can be selected |
Check Box Content Control | Word content control with CheckBox icon that can be enabled and disabled |
Drop-Down List Content Control | Word content control, where you can choose from predefined options |
Combo Box Content Control | Word content control, where you can choose from predefined options and enter any text you want. |
Object | An object is defined via a schema. Objects can be filled manually or via |
ObjectCollection | A collection of objects. The difference to the object is that the list can store multiple objects of the same type. |
DataProvider | Defines a source for objects. |
Extensive example
Code
Forms
Felder
Screenshot
PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland