Widget-Plugin: Berechnungselement

Das Symbol für Widgets vom Typ Berechnungselement im Xima® Formcycle Designer.

Plugin-Download (erfordert Anmeldung)

Content [ Hide ]

Funktionsbeschreibung

Das Plugin stellt ein neues Widget im Designer zur Verfügung, welches es erlaubt, auf einfache Art Mathematische Berechnungen auszuführen. Das Widget erzeugt ein gesperrtes Eingabefeld, welches zur Ausgabe des Ergebnisses dient. In den Eigenschaften dieses Eingabefelds, kann eine Formel mit Feldplatzhaltern wie z.B. ([%tf1%] + [%tf2%]) / 1.19 eingegeben werden. Zusätzlich können Schriftfarbe und Ausgabeformat für das Ergebnis festgelegt werden. 

Installation

Das Plugin kann als Mandant-Plugin oder System-Plugin installiert werden. Eine Anleitung zur Installation von Plugins finden Sie hier.

Konfiguration

An Widgets dieses Typs können die folgenden Eigenschaften konfiguriert werden:

Base properties

Basic settings for Base properties

Content [ Hide ]

User interface for changing basic properties of a form field, such as its name or its width.

Elements can be repeated. In this example, the user can enter one or more email addresses.

The number of repetitions can also be set automatically, depending on the value of another element. In this example the fieldset with the data of a single child is repeated. There are always as many fieldsets as the number of children the user selected.

The base properties name, width and hidden can be set for each form field.

Base properties

NameDescription
element6.3.0+ Element type of the form field. The element type can be changed by selecting another element type in the dropdown menu. The element types an element can be transformed into depend on the original type. Containers and fieldsets can only be transformed into the respective other element type. All other element types can be transformed into any other type, except for containers and fieldsets.
nameName of the form field. Only letters and numbers may be used.
aliasAn alternative name for the form element, which may contain any characters. See below.
widthWidth of the form, relative to the width of other form fields on the same row. For example, when placing two form fields next to each, giving both a width of 2 means that both will take 50% of the available width. Setting the width of the first form field to 1, and the width of the second one to 3 results in the first one taking 25% of the available width, and the second one taking 75%. 
hiddenWhen checked, the form field will be hidden initially. To show it again, the option visible if can be used, or a Javascript function such as  jQuery.fn.visible. 
disabledWhen checked, the content of the form field cannot be edited.
RepeatWhen this option is activated, the user can freely create any number of copies (repetitions) of this form element. For example, this can be used to let the user enter one or multiple email addresses. Please note that you cannot nest repeated elements: if a container is marked as repeated, none of its containing elements can be repeated.
Min. repeatMinimum number of allowed repetitions. When this limit is reached, the user cannot delete any more repeated elements. This is also the inital number of repetitions when the form is opened.
Max. repeatMaximum number of allowed repetitions. When this limit is reached, the user cannot add any more repeated elements.
Repeat triggerWhen an element is selected here: The number of repeated elements is automatically set to the value of the selected element. For example: Assume there is a select element or input element that lets the user enter number of children in their household. Also assume there is a fieldset for entering some data of these children. The fieldset is marked as repeated, and the select or input element is set as the repetition trigger. Now when the user enters how many children they have got, fieldsets are removed or created automatically so that there is always one fieldset for each child.
Hide buttons6.2.0+  Available only when an element was selected for Repeat trigger. Enable this option to hide the plus and minus buttons for adding and removing repeated elements. Use this option when the number of repeated elements should be controlled only by trigger.

Alias

When a form is submitted, key-value pairs are sent with the name of the form being the key and the entered text being the value. Within workflow actions or templates, you can access the values of submitted form elements with variables. The name of a form element cannot contain special characters such as accented characters (é or ô). When sending data to web services or when integrating third party systems, it may become neccessary to make use of special characters. In this case, you can set an alias for a form element. This alias does not have any restrictions on which characters you can use.

This form elements does not possess any additional settings for the section Base properties.

Style

Basic settings for Style

For Xima® Formcycle versions up to 6.3.2, the properties described here are still located in the Base properties section.

The properties available here are used to configure the visibility of the form element. The basic property Hidden is available to each form element. The properties Disabled and Repeat as well as the properties dependent on them are only available for form element types where they are useful.

Failed to execute the [velocity] macro. Cause: [null]. Click on this message for details.
User interface for changing basic properties of a form field, such as visibility, repeatability and whether the form element is disabled.
Failed to execute the [velocity] macro. Cause: [null]. Click on this message for details.
Elements can be repeated so that the user can enter as many data as desired.
Failed to execute the [velocity] macro. Cause: [null]. Click on this message for details.
The number of repetitions can also be set automatically, depending on the value of another element. In this example the fieldset with the data of a single child is repeated. There are always as many fieldsets as the number of children the user selected.
NameBeschreibung
hiddenWhen checked, the form field will be hidden initially. To show it again, the option visible if can be used, or a Javascript function such as  jQuery.fn.visible. 
disabledWhen checked, the content of the form field cannot be edited.
RepeatWhen this option is activated, the user can freely create any number of copies (repetitions) of this form element. For example, this can be used to let the user enter one or multiple email addresses. Please note that you cannot nest repeated elements: if a container is marked as repeated, none of its containing elements can be repeated.
Min. repeatMinimum number of allowed repetitions. When this limit is reached, the user cannot delete any more repeated elements. This is also the inital number of repetitions when the form is opened.
Max. repeatMaximum number of allowed repetitions. When this limit is reached, the user cannot add any more repeated elements.
Repeat triggerWhen an element is selected here: The number of repeated elements is automatically set to the value of the selected element. For example: Assume there is a select element or input element that lets the user enter number of children in their household. Also assume there is a fieldset for entering some data of these children. The fieldset is marked as repeated, and the select or input element is set as the repetition trigger. Now when the user enters how many children they have got, fieldsets are removed or created automatically so that there is always one fieldset for each child.
Hide buttons6.2.0+  Available only when an element was selected for Repeat trigger. Enable this option to hide the plus and minus buttons for adding and removing repeated elements. Use this option when the number of repeated elements should be controlled only by trigger.

This form element possesses the following additional properties for the section Style.

Mögliche Eigenenschaften und deren Standardwerte, nachdem die Option Ausgabeformat angewählt wurde und das Ergebnis dieser Konfiguration im Formular.

Konfigurationsmöglichkeiten für der Schriftfarbe, nachdem die Option Farbänderung angewählt wurde.
NameBeschreibung
AusgabeformatDurch Anwählen dieser Option kann die Ausgabe (wenn es sich um eine Zahl handelt) mit Eigenschaften aus der Autonumeric-Javascript-Bibliothek formatiert werden. Wenn diese Option gewählt ist, werden die Eigenschaften Ausrichtung der Einheit, Dezimalstellen, Tausendertrennzeichen, Dezimaltrennzeichen und Einheit konfigurierbar.
Ausrichtung der EinheitLegt die Position der Einheit fest. Es kann zwischen Rechts vom Wert und Links vom Wert gewählt werden. Nur sichtbar, wenn die Option Ausgabeformat angewählt wurde.
DezimalstellenAnzahl der Nachkommastellen, die immer sichtbar sind. Wenn dieses Feld sichtbar ist, muss es zwingend befüllt werden, da das Berechnungs-Widget ansonsten funktionsunfähig ist. Nur sichtbar, wenn die Option Ausgabeformat angewählt wurde. Standardwert: 2
TausendertrennzeichenOptionales Zeichen, welches bei der Ausgabe der Zahlenwerte zwischen Tausenderstellen eingefügt wird. Nur sichtbar, wenn die Option Ausgabeformat angewählt wurde. Standardwert: .
DezimaltrennzeichenZeichen, welches bei der Ausgabe der Zahlenwerte zwischen Vor- und Nachkommastellen eingefügt wird. Wenn dieses Feld sichtbar ist, muss es zwingend befüllt werden, da das Berechnungs-Widget ansonsten funktionsunfähig ist. Nur sichtbar, wenn die Option Ausgabeformat angewählt wurde. Standardwert: ,
EinheitOptionales Zeichen bzw. optionale Zwischenkette, welche zusätzlich zum Wert im Feld angezeigt wird. Die Position kann mir der Eigenschaft Ausrichtung der Einheit festgelegt werden. Nur sichtbar, wenn die Option Ausgabeformat angewählt wurde. 
FarbänderungDas Anwählen dieser Option erlaubt es, die Schriftfarbe für positive und negative Zahlen festzulegen. Wenn diese Option gewählt ist, werden die Eigenschaften Positive Farbe und Negative Farbe konfigurierbar. Für Zahlenwerte, welche Null entsprechen und Texte erfolgt keine Farbänderung.
Positive FarbeÜber eine vorgegebene Auswahl von Farben oder einen Colorpicker kann hier die Farbe bestimmt werden, mit der der im Feld sichtbare wert angezeigt werden soll, wenn es sich um eine positive Zahl handelt. Nur sichtbar, wenn die Option Farbänderung angewählt wurde.
Negative FarbeÜber eine vorgegebene Auswahl von Farben oder einen Colorpicker kann hier die Farbe bestimmt werden, mit der der im Feld sichtbare wert angezeigt werden soll, wenn es sich um eine negative Zahl handelt. Nur sichtbar, wenn die Option Farbänderung angewählt wurde.

Label

Basic settings for Label

This property defines the label text of an element. A label is the text above, below or to the right or left of an element. Not every element has got this property.

Failed to execute the [velocity] macro. Cause: [null]. Click on this message for details.
The label text appears next to a form element. It should be kept short and tell the user what they should enter in this form field.
NameBeschreibung
LabelValue of the label. This is the text that is displayed next to the element.
AlignmentSpecifies the position (left, right, above, below) of the label.
Width (in px)Distance between label and the element. Applies only when the alignment is set to left.
PlaceholderPlaceholder text, applies only to input fields.
TitleTooltip of the item (the HTML title attribute).
UnitText that after an element. Usually this is used for units, such EURO or km.

This form elements does not possess any additional settings for the section Label.

Berechnung

Die in diesem Bereich vorhandenen Eigenschaften dienen dazu, die Art der Berechnung und die für die Berechnung zu verwendende Formel festzulegen.

Beispiel für die Berechnungsformel für eine Verkettung von Strings der Eingabefelder tf1 und tf2 und das Ergebnis im Formular.

Beispiel für eine Berechnung eines Feldes, welches sich weiter oben im Formular befindet als die Berechnungsfelder, auf deren Wert es zugreift. Durch das Vergeben eines Wertes bei Reihenfolge Index am Berechnungs-Widget der Teilsummen, werden diese zuerst berechnet und erst danach wird die Gesamtsumme ermittelt.
NameBeschreibung
BerechnungsfeldIn dieses nicht mit einem Label benannte Feld kann ein Berechnungsformel eingegeben werden, welche bei jeder Wertänderung von einem der in der Berechnungsformel verwendeten Eingabelemente erneut ausgeführt wird. Als Syntax wird JavaScript verwendet. Für das Ermitteln der zu verwendenden Werte von anderen Eingabelementen können neben jQuery-Selektoren auch Xima® Formcycle Platzhalter verwendet werden.
Reihenfolge IndexDie Abarbeitungsreihenfolge einer Berechnung findet in der Regel von oben nach unten und von links nach rechts statt, so wie diese auf dem Formular hinterlegt wurden. Dies ist für die meisten Anwendungsfälle ausreichend. Ist es jedoch notwendig, dass eine bestimmte Berechnung vor einer anderen stattfinden muss, kann für diese eine Indexzahl vergeben werden. Dies ist zum Beispiel nötig, wenn die Summe aus bestimmten Berechnungsfeldern weiter oben im Formular ausgegeben werden soll. Wenn es merhere Berechnungs-Widgets im Formular gibt ist die Reihenfolge der Abarbeitung wie folgt: Zuerst werden alle Berechnungenfelder mit einem Index abgearbeitet, wobei vom niedrigsten Indexwert zum größten Indexwert vorgegangen wird. Anschließend werden alle Berechnungen ohne einen Index ausgeführt, entsprechend den normalen Regeln (von oben nach unten und von links nach rechts).

Constraints

Basic settings for Constraints

The constraints panel contains options to check the value of form fields, when form fields should be visible and when they can be edited. Some constraints are available only for some element, see the list of element..

Properties

A form field can be made a required field, requiring the user to enter something or select an option.
NameDescription
hidden ifHides the form fieldm when a certain conditions is satisfied.
visible ifMakes a form field that has been hidden visible again, when a certain condition is satisfied.
read-only ifLocks a form field and disallows any input, when a certain condition is satisfied.
editable ifMake a form field that has been set to read-only editable again, when a certain condition is satisfied.
requiredWhen this option is activated, a value must be entered for the form field. Conditions set under required if are ignored when this option is activated.
required ifMarks a form field as a required field, when a certain condition is satisfied.
required groupAvailable only when the form field is a required field. Specifies the required group the form field should belong to. When two or more form fields belong to the same group, at least one of these form fields needs to be filled out, all other fields may remain empty.

Condition

Any condition referring to the value of a select element uses the value of the option for testing the condition, as entered in the colum value.

You can change a form field's visibility and read-only state depending on the value of another form element. The following conditions are available for the options hidden if, visible if, read-only if, editable if, and required if:

  • has a value
  • has no value
  • equals
  • not equals
  • lower than
  • lower equal than
  • greater than
  • greater equal than
  • between
  • regular expression

You can also select elements with the element picker to the right. Click on the hand-shaped icon and then on the element you would like to use. This comes in handy when editing forms with many form fields.

ConditionDescription
has a value / has no value

The conditions evaluates to true when the value of the form field is (not) empty.

In particular, having a value mean the following for different form elements:

  • for a checkbox, that the checkbox is not checked.
  • for a selection, that some option other than Please select an option has been selected. When the selection field is displayed as a combo box, the first option will be selected by default, unless the selection is a required field, in which case the option Please select an option will be selected by default.
  • for an input field, that at least one character has been entered.
equalsThe condition evaluates to true when the value of the form field equals the given value. Comparisons are case-sensitive.
not equalsThe condition evaluates to true when the value of the form field does not equal the given value. Comparisons are case-sensitive.
lower than / lower or equal thanThe condition evaluates to true when the value is lower (or equal) than the specified value.
greater than / greater or equal thanThe condition evaluates to true when the value is greater (or equal) than the specified value.
betweenThe condition evaluates to true when the value is between the specified range, inclusively. The interval must be entered with a dash (-), for example 2-10. Negative numbers must be enclosed in parentheses, eg. (-10) - (- 5).
regexpThe condition evaluates to true when the value matches the specified regexp.

Clear or reset automatically

For the properties hidden if and read-only if, you may choose whether the form field should be cleared or reset automatically when the form field ist hidden or disabled. Clearing a form field means that its value is removed, eg. deleting the entered text for an input field or unchecking all checkboxes for a select field. Resetting a form field, on the other hand, refers to changing its value back to the original or initial value it had when the form was openend. In case the form was opened for the first time and not submitted yet, the original value is the value as set in the Xima® Formcycle Designer. Otherwise, when the form was already submitted and is opened in the inbox, the original value is the most recently submitted (saved) value.

For example, consider the case of entering an address. The user can choose between a physical address and a post-office box, and only one input field is visible depending on the user's choice. When the form is submitted, a value should be send only for one of both fields. By selecting the empty automatically options, the input field post-office box will be cleared automatically when the user selects a physical address.

When an element is cleared or reset, all the elements it contains are cleared or reset as well. This applies to form elements of type page, container, and fieldset.

This form elements does not possess any additional settings for the section Constraints.

Help

Basic settings for Help

Failed to execute the [velocity] macro. Cause: [null]. Click on this message for details.
You can edit the help text that is shown as a tooltip. By default, there is no help text and no help icon.
Failed to execute the [velocity] macro. Cause: [null]. Click on this message for details.
The help text appears when hovering over the   icon with the mouse.

This feature allows you to add an explanation or help text to a form element. By default, the help text is empty. Once you enter a help text, you will see a help icon   appear next to the form element. When the user hovers over the help icon with the mouse, the help text is shown as an overlay. 

To change the design of the help icon or the overlay bubble, create your own CSS theme.

This form elements does not possess any additional settings for the section Help.

CSS classes

Basic settings for CSS classes

Failed to execute the [velocity] macro. Cause: [null]. Click on this message for details.
Selecting CSS Classes.

This property lets you select one or many CSS classes for an element. The available CSS classes are read from the CSS in the CSS tab and from the selected CSS theme. When you select or deselect a class, the changes are applied immediately and any layout or design changes are visible in the form. You can also filter the available classes by using the filter at the end of the list.

This form elements does not possess any additional settings for the section CSS classes.

Attributes

Basic settings for Attributes

Arbitrary custom HTML attributes are deprecated. HTML5 defines so-called data- attributes that can be used to store custom data in HTML elements. For example, it is ok to use the attributes data-price or data-serial-id, but you should not use attributes such as price or serialId.

The panel attributes lets you add custom attributes to the corresponding HTML elements of each form element. You can access them with JavaScript later, or add existing HTML attributes such as the attribute type for <input> elements.

This panel lets you add custom HTML attributes that may be needed for custom features implemented via JavaScript.

A custom HTML attribute has been added and can be seen when inspecting the generated HTML.

Adding an attribute

To add an HTML attribute, just enter the name and the value of the attribute into one of the columns. A new, empty column will be added automatically.

Deleting an attribute

Click on the   icon to the left to delete an attribute.

Accessing data attributes via JavaScript

If you want to add custom data to an element, use the prefix data- for the name. Additionally, the attribute name should contain no uppercase letters and use dashes to separate words. For example, data-serial-version is a good data attribute, dataSerialVersion is not. When accessing these attributes via JavaScript, remove the dashes and capitalize the first letter of each word.

Assuming the attribute data-serial-version was set to 1aFXc for the element tfSerialVer, you can access this data as follows:

const serialVersion = $("[name='tfSerialVer']").data("serialVersion");
console.log("Serial version is:" , serialVersion);

This form elements does not possess any additional settings for the section Attributes.

Available only if

Basic settings for Available only if

The property Available only if controls whether elements are displayed or not depending on the current state or user.

Note that when an element is not available, it is never rendered and will not be present anywhere in the HTML. This means that users cannot see the form field or its current data even if they take a look at the source code of the form.

Failed to execute the [velocity] macro. Cause: [null]. Click on this message for details.
This lets you restrict the form field to a certain user group or to a certain state.

When only one state or a user group is selected, the form element is displayed only when the form is in the selected state or viewed by a user of the selected user group. For each state and user group there is also the opposite option to display a form element only when it is not in the selected state or not viewed by the selected user group. For example, when you want display a form element only when a user fills out the form for the first time, you can select the option no state.

If both a state and a user group are selected, the form element is displayed only when the form is both in the selected state as well as opened by a user belonging to one of the selected user groups.

The selection no state means that the form was opened for the first time and not submitted yet.

This form elements does not possess any additional settings for the section Available only if.

Other

Basic settings for Other

Failed to execute the [velocity] macro. Cause: [null]. Click on this message for details.
Comments can be added for internal use. They will not be visible to the user when they open the form.

You can add a comment for internal use that will not appear anywhere in the form.

This form elements does not possess any additional settings for the section Other.

Druckbild im Word-/PDF-Export

Wenn ein Formular per Word-/PDF-Export exportiert wird, sieht das Widget wie ein normales, auf Readonly geschaltetes, Eingabefeld aus.

Formelbeispiele

FormelErklärung
[%tf1%] - [%tf2%]

$('[name=tf1]').val() - $('[name=tf2]').val()		Subtraktion der Werte in den Eingabefeldern tf1 und tf2 einmal unter Verwendung von Passwörtern und einmal mittels jQuery-Selektoren
[%tf2%] * (1 + ([%tf1%] / 100))Wird in tf1 z.B. der Steuersatz und in tf2 der Nettobetrag eingegeben, wird der Bruttobetrag berechnet
[%tf1%] + " " + [%tf2%]Stringverkettung aus den Eingaben in den Eingabefeldern tf1 und tf2
[%tf1%].length()Anzahl der eigegebenen Zeichen im EIngabefeld tf1
([%tf1%]<2) ? "Genehmigt" : "Abgelehnt"Wenn der Wert in tf1 kleiner als 2 ist, soll "Genehmigt" ausgegeben werden. Ansonsten "Abgelehnt".
$('[org_name=tf1]').sum()Beispiel für Berechnen der Summe von wiederholten Elementen mit dem Namen tf1. Für wiederholte Elemente und Elemente innerhalb von wiederholten Containern und Fieldsets muss ein normaler JavaScript-Selektor oder wie in diesem Beispiel ein jQuery-Selektor verwendet werden.

Mögliche CSS-Anpassungen

Um die Ausgabe zu formatieren, können per CSS Anpassungen vorgenommen werden. Wenn zum Beispiel die Ausgabe anstatt einem gesperrten Eingabefeld wie ein Text aussehen soll, kann folgender CSS-Code verwendet werden:

.CXFormula .label-top{
   display: none;
}
.XFormula{
   border: none !important;
   background: none !important;
   padding: 0;
}
Tags:
Created by gru on 23.02.2021, 18:38
Copyright 2000-2025