In the document function "Document Parameter", the input mask that appears when generating a document can be configured.

The configuration can be roughly divided into three parts:

• DataNodes: In the "CustomContentSection" the fields, so-called DataNode controls, are defined.

• View: In the "View" section, the appearance of the document parameters is defined.

• DataSources: In "DataSources" database queries can be defined and the values can be used from the query.

Basic structure

CustomContentSection

At the top of the "DataNodes" the controls are defined, which are accessed in the "View" in the lower part.

In the View the appearance of the document parameter is defined. In the DataSources part, database queries can be defined, and the values from the query can be written to the controls defined under "DataNodes".

Example:

Attributes in CustomContentSection:

In contrast to the configuration defined above, in the example below the values of the WindowWidth and WindowHeight attributes are swapped out to the Global Configurations:

Thanks to this outsourcing to the Global Configurations it is ensured that the mentioned information only needs to be changed in one place. Consequently, changes are conveniently applied in all templates that have this link. If a different value needs to be set in the template than the one in the Global Configurations, a different value is simply written in the quotes.

DataNodes

This section is about the configuration between <DataNodes> and </DataNodes>. Each DataNode defines a Document Parameter field that can be accessed in the editor, in scripts or via extended bindings. For each field that exists in the Views, a DataNode must be created for reuse.

Basic structure of a DataNode:

Instead of "control name" the DataNodes below can be used. The Id is mandatory in every control and is displayed in editor mode and needed afterwards for use in editor, scripts or extended bindings. The Id must not contain spaces and must be unique.

Basic attributes

The following attributes can be inserted into any type of DataNode:

Text

Inserted in Word as a Plain Text Content Control. In the view, the Text control can be used to reference a TextBox, a RadioButton, a ComboBox, or a CheckBox. Depending on which of the below controls is used, something different will appear in Word in the text box:

Examples

Content

If something is written in between the start and end tag, the entered text is already in the text field when the document is generated. In the extended example e.g. Invitation.

Attributes for text controls

DateTime

Becomes a Date Picker Content Control in Word with calendar selection, and is also displayed that way in the Document Parameter.

Examples

Content

If the date is set between the start and end day, it is preselected when opened, such as 2022-08-15 for Thursday, August 15, 2022. If the content is empty, the current date is preselected in each case.

Attribute für DateTime-Elemente

CheckBox

Inserted in Word as a check box content control and is for a yes/no selection.

Examples

Content

If true is set between the start and end tags, the CheckBox is already checked when generating.

Attribute für CheckBox-Elemente

ComboBox

Is inserted into Word as a combo box content control, also called a dropdown. It is for choosing between given values (any input is allowed in Word).

Examples

Content

Item controls can be defined as content. Each item is available to the user as an entry in the combo box. The Value of the item is accessed in scripts.

Attribute des Item-Elements

• DisplayText

  • Display text in Document Parameter dialog and combo box content controls in Word.

  • Generally applies as content of this OneOffixx field, such as when accessed in scripts with <Element id="DocParam.ReasonForCongratulation " />.

  • Used in scripts for conditions when there is no $ character in front of the id.
    So in the above example, <Condition when="DocParam.ReasonForCongratulation = 'Employee Anniversary'> is true.

• Value

  • Must not be empty – it must contain at least one character. It should not contain spaces or special characters as Word does not accept them.

  • Used in scripts for conditions when there is a $ character in front of the Id.
    In the example above, <Condition when="$DocParam.ReasonForCongratulation = 'employeeAnniversary'> is thus true.

Attribute für ComboBox-Elemente

Collection

The Collection-DataNode is a function extension of the ComboBox. As the name suggests, a Collection is a collection of values. The difference between the collection of values in a Collection and values in a ComboBox is that the Collection can store complex data structures, while the ComboBox only allows a simple Key → Value mapping. Example:

A collection contains any number of elements, which in turn contain any number of text controls. These text controls are uniquely identified with an id. A Collection serves as the data basis for a ComboBox.

Since the Collection stores several values per entries, a corresponding mapping possibility for these values is still needed. For storing the values, the already known DataNodes (in the CustomContentSection) are defined according to the known scheme:

The naming can be chosen as desired. In this example, the Id was used as a prefix for the sake of clarity. Thus, based on this collection and the DataNodes, the following ComboBox can be defined in the Views:

The id of the ComboBox is identical to that of the Collection. As with other DataNodes, this establishes the connection between the defined DataNode and the corresponding view element. The CollectionLabelMember specifies which text control of the elements in the Collection should be displayed in the ComboBox for selection, in this example the name of the employee. The ComboBox is displayed in the dialog as follows:

Open

The CollectionSelectionMap defines which text of the selected element from the collection (source) is written to which DataNode (target). If an item is selected, the values of the selected item are written to the DataNodes according to the defined CollectionSelectionMap and can then be used according to the known scheme.

The complete configuration now looks like this:

When do Collections come into play?

Collections are mainly used when a selection exists on which several values directly depend. This can also be achieved with ComboBoxes without Collections, but without Collection the maintenance is more complex.

Example:

We have a ComboBox "Country" with the following selection: Switzerland Germany Austria Then there are two more fields, Currency and Capital, which depend on the selection in the ComboBox. The mapping looks like this:

The configuration without Collections

The ComboBox:

The dependent fields (as scripts):

Here it becomes directly apparent; if a new country has to be added, the adjustment or a condition must also be added in these two scripts.

The configuration with Collections

If a country is added to the selection with this configuration, only the entry in the collection has to be completed.

Views

Within the Views start and end tag there are individual View structures. A view contains texts, images, input options (text boxes, check boxes, combo boxes, ...) and buttons.

It is possible to define several View structures. The user can change the view by clicking on buttons (usually "Next" and "Back").

Basic structure

• Any number of view elements can be created.

• A view can contain any number of row elements.

• By default, a view has 4 columns. However, the number of columns can also be set to 1, 2, 3, 4, 6 or 12 with the Columns attribute.

• If you do not want to display a Document Parameter dialog, but only configure Document Parameter using the Quick Check, you can set the attribute IsVisible="false" on the level of the Views element.

Only one View:

Multiple views:

Special id: main: This view is the start view. In any case, a view with the Id main must be configured.

Navigation switches outside Rows

Attributes for buttons:

• Label: Label of the button

• TargetView: Id of the target view for forwarding buttons

• Type: Special actions

  • value Submit: exit Document Parameter dialog, continue in generation process

  • Value Cancel: Exit Document Parameter dialog, abort generation process

• IsDefault: If set to true: Determines the default action on Enter

Rows and their content

In addition to buttons, views also contain rows. The rows contain the actual content of the view and structure and form controls can be inserted into them. The structure controls are purely for customizing the appearance of the Document Parameter. The form controls are for inserting into the template or for inserting into scripts and extended bindings.

Attributes of the structure and form controls:

The views are divided into 4 columns by default. Each structure and form control has a width of 1. To increase the width, the ColumnSpan attribute is used. The structure and form controls are inserted from left to right. If a field is to be displayed offset by one column, this is accomplished with ColumnOffset="1".

The following attributes can be used for both structure controls and form controls:

Special case attribute Id:
The id is required for all form controls. It is obsolete for structural controls. It identifies the field defined in the DataNodes.

Structural controls

Example with structural controls

Form controls

If there is a DataNode with the same id, it will try to use it as a data source. These fields all have a Value attribute which is used as initial value

TextBox

→ Single or multiline text field, see section "Text" in chapter DataNodes.

Example for Mask:

In this example, the first 6 digits are required. If no 6 are entered, the Document Parameter cannot be confirmed. However, the last digit is optional.

Predefined text:

There are two ways to predefine a text in the text field: either via the Value attribute in the views...

...or via the input at the DataNodes between the start and end tag:

The predefined text field content may only be defined at one location at a time. If visible characters are defined at both locations, the value of the text control defined in the DataNodes is inserted. The value in the views is consequently ignored.

DatePicker

→ Date selection with calendar, see section "DateTime" in chapter DataNodes.

CheckBox

→ A selection box – or a CheckBox, see section "CheckBox" in chapter DataNodes.

ComboBox

→ A selection list or dropdown, see section "ComboBox" in chapter DataNodes.

The values for the ComboBox can be defined either in the DataNode or in the view. The choices for the ComboBox can be defined either in the DataNode control of type ComboBox or in the view. The choices are inherited from the DataNode control even if a list is defined in the view. If the list is defined in the view, then the DataNode control must be of type Text. Here is an overview:

1. The ComboBox defined in the DataNode section

2. The combobox defines in the view

RadioButton

RadioButtons are grouped by their id. All RadioButtons with the same id represent an "either-or selection".
For each selectable option, a single RadioButton control must be defined. The id means id of the datanode, i.e. the text or ComboBox control. The two attributes Label and Value are mandatory.

Since there are no RadioButton content controls in Word, there is no RadioButton DataNode in OneOffixx. Therefore, RadioButtons are mainly used in connection with snippets. The Text DataNode or the ComboBox DataNode are used as DataNode:

Example to illustrate the columns:

Configuration:

Result (columns were marked):

Open

Validation

User input can be validated, as mentioned. If one or more fields are marked accordingly, the user cannot leave the Document Parameter dialog until the conditions are met.

Overview of all validation options:

• DataNode controls

  • "Text": with Required or Regex.

  • "CheckBox": with Required

• Form controls

  • "ComboBox": with IsInvalidWhenValue

  • "RadioButton": when linked to text element with Required. The ShowRequiredIncicator attribute is used to determine where the warning icon should be displayed.

Example (in German):

Bindings

Simple Bindings

Bindings refer to other values and can use them as "value basis" and for queries. Bindings can be used to control the following attributes:

IsVisible example:

The button named "Notes >" is displayed in the Document Parameter only if there is a value "DocParam.Advanced" = "true" (i.e. an enabled CheckBox). IsEnabled works the same way.

TargetView example:

Value Bind example:

Values can also be bound to controls, e.g. to display an overview of the entered data on the last page:

Instead of individual controls, entire rows can also be bound:

Row example:

Comparison operators of bindings:

Multiple conditions can be linked with AND or OR:

• || for OR

• && for AND (stands for &&) (XML attributes do not allow "&", so & must be used)

Multiple bindings can also be specified separated by , :

Calc: Calculations in bindings

The value bases for the bindings can be extended with mathematical functions. The addressing of the fields remains the same ($('DocParam.Xyz')). To link the fields mathematically, the normal base operators (+, -, /, *) can be used.

Overview of all possible operators and how they are used:

Each Calc call contains as final argument the formatting string, separated from the term by a ;. This value can be omitted (but the enclosing '' cannot). The ; is mandatory.

Formatting:

• N2 → Number with two decimal places (default).

• C2 → Currency format according to the currently selected document language with two decimal places.

Complete list with format codes: Standard numeric format strings

Syntax:

The library used is capable of calculating exponent-before-dot-before-dash. → ( a + b * c) == (a + (b * c)) != ((a + b ) * c) . The calc keyword is not case sensitive.

Examples

Value-Bind:

IsVisible-Bind:

Furthermore Calc offers the possibility to "count" selected CheckBoxes:

The boolean "Checked" value of the checkbox is converted by Calc to an integer with value 0 for false (= not checked) and 1 for true (= checked), so that the values can be added together. The above example stands for: "If two of the checkboxes 1 through 4 are selected, then display the Row with the label." Attention must be paid to the formatting: Mandatory without decimal places, because 1.00 is not equal to 1, and accordingly cannot be converted back to a boolean value.

Unless default values are specified in the DataNode elements, all Calc binding values are initialized with 0. Especially for "IsEnabled"- and "IsVisible"-bindings with "Calc"-conditions you should pay attention to valid default values, otherwise the condition is always fulfilled initially.

Script – JavaScript

For requirements that cannot be covered with the usual configurations, the Document Parameter document function offers the possibility to write JavaScript.

JavaScript functions can be defined within the Script element. Valid ECMAScript 5.1 is allowed.
JavaScript knowledge is required to use this feature. The basics of JavaScript are not listed in this documentation.

There are two ways to call the functions:

• Using the OnSubmit attribute on the Views element (see example above)
  Either true or false must be returned for these functions:

  • true: No validation error = Document Parameter dialog is exited.

  • false: Validation error, validation overview is displayed = Document Parameter dialog remains open

• Via the OnChange attribute on a view value control (e. e.g. on a TextBox control; see example above)
  No return value is required for these functions.

For interaction with DataNode controls, the OO object can be used as follows:

• OO.getValue("ANY_ID"): Returns the text value of the DataNode control with the corresponding id. Example: var valueFromExampleDocParam = OO.getValue("DocParam.Example");

• OO.setValue("ANY_ID", "ANY_VALUE"): Sets the text value of the DataNode control with the corresponding id. Example: OO.setValue("DocParam.Example", "New content...");.

• OO.addValidationMessage("ANY_ID", "ANY_VALIDATION_MESSAGE"): Sets a validation error with a message for the DataNode control with the corresponding id. Note: All validation messages are displayed in the validation overview. If a control with the given id is found, an error message is displayed. Example: OO.addValidationMessage("DocParam.Example", "If X and Y have been set, something must be entered in the Example field.");

DataSources

The DataSources feature is documented on this page.

Beispiele about all topics on this page

Simple Document Parameter dialog configuration

Document parameter with validation

Simple Bindings (in German)

Calc Bindings (in German)