Zeige letzte Bearbeiter
1 {{figure image="1_WidgetXFormula_Logo_de.png" clear="h3"}}
2 Das Symbol für Widgets vom Typ //Berechnungselement// im {{designer/}}.
3 {{/figure}}
4
5 [[**Plugin-Download**>>https://customer.formcycle.eu/index.php/s/0dj4omg2bvsdkHe||rel="noopener noreferrer" target="_blank"]]
6
7 {{content/}}
8
9 == Funktionsbeschreibung ==
10
11 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. {{code language="none"}}([%tf1%] + [%tf2%]) / 1.19{{/code}} eingegeben werden. Zusätzlich können Schriftfarbe und Ausgabeformat für das Ergebnis festgelegt werden.
12
13 == Installation ==
14
15 Das Plugin kann als Mandant-Plugin oder System-Plugin installiert werden. Eine Anleitung zur Installation von Plugins finden Sie [[hier>>doc:Formcycle.UserInterface.Client.Plugins]].
16
17 == Konfiguration ==
18
19 An Widgets dieses Typs können die folgenden Eigenschaften konfiguriert werden:
20
21 {{internBaseOptionsElement page="base" headline="h3"/}}
22
23 {{internBaseOptionsElement page="style"}}
24 {{figure image="2_WidgetXFormula_Autonumeric_de.png"}}
25 Mögliche Eigenenschaften und deren Standardwerte, nachdem die Option //Ausgabeformat// angewählt wurde und das Ergebnis dieser Konfiguration im Formular.
26 {{/figure}}
27
28 {{figure image="3_WidgetXFormula_Farbe_de.png"}}
29 Konfigurationsmöglichkeiten für der Schriftfarbe, nachdem die Option //Farbänderung// angewählt wurde.
30 {{/figure}}
31
32
33 {{table dataTypeAlpha="0" fullwidth="false" colWidth="-500"}}
34 |=Name|=Beschreibung
35 |Ausgabeformat|Durch 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.
36 |Ausrichtung der Einheit|Legt 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.
37 |Dezimalstellen|Anzahl 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: {{code language="none"}}2{{/code}}
38 |Tausendertrennzeichen|Optionales Zeichen, welches bei der Ausgabe der Zahlenwerte zwischen Tausenderstellen eingefügt wird. Nur sichtbar, wenn die Option //Ausgabeformat// angewählt wurde. Standardwert: {{code language="none"}}.{{/code}}
39 |Dezimaltrennzeichen|Zeichen, 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: {{code language="none"}},{{/code}}
40 |Einheit|Optionales 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.
41 |Farbänderung|Das 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.
42 |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.
43 |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.
44 {{/table}}
45 {{/internBaseOptionsElement}}
46
47 {{internBaseOptionsElement page="label" headline="h3"/}}
48
49 === Berechnung ===
50
51 Die in diesem Bereich vorhandenen Eigenschaften dienen dazu, die Art der Berechnung und die für die Berechnung zu verwendende Formel festzulegen.
52
53 {{figure image="4_WidgetXFormula_Formel1_de.png"}}
54 Beispiel für die Berechnungsformel für eine Verkettung von Strings der Eingabefelder //tf1// und //tf2// und das Ergebnis im Formular.
55 {{/figure}}
56
57 {{figure image="5_WidgetXFormula_Formel2_de.png"}}
58 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.
59 {{/figure}}
60
61 {{table dataTypeAlpha="0" fullwidth="false" colWidth="-500"}}
62 |=Name|=Beschreibung
63 |Berechnungsfeld|In 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.
64 Als Syntax wird //JavaScript// verwendet. Für das Ermitteln der zu verwendenden Werte von anderen Eingabelementen können neben //jQuery//-Selektoren auch {{formcycle/}} [[Platzhalter>>doc:Formcycle.UserInterface.Variables]] verwendet werden.
65 |Feldwerte|Hier kann ausgewählt werden, mit welchem Datentypen die Feldwerte behandelt werden sollen. Entwerder soll für jeden Feldwert automatisch ermittelt, welcher Datentyp der er hat oder es sollen alle Feldwerte als Text gelesen werden. Letzteres ist zum Verketten von Strings sinnvoll. Jedoch sind damit Berechnungen (z.B. [%tf1%] - [%tf2%]) ausgeschlossen.
66 |Leere Felder|Hier kann ausgewählt werden, was passieren soll, wenn ein Formularelement keinen Wert hat. Entweder wird es wie die Zahl 0 behandlelt oder wie leerer Text. Bei nummerischen Berechnungen sollte der Wert in der Regel wie die Zahl 0 behandelt werden.
67 |Reihenfolge Index|Diese Option ist nur in Ausnahmefällen notwendig. Standardmäßig werden die Felder automatisch in der Reihenfolge abgearbeitet, wie es die Formeln vorgeben. Falls die automatisch erkannte Reihenfolge einmal nicht korrekt sein sollte, kann eine Indexzahl vergeben werden. Wenn in wenigstens einem Formelfeld ein Index gesetzt ist, 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).
68 {{/table}}
69
70 {{internBaseOptionsElement page="cond" headline="h3"/}}
71
72 {{internBaseOptionsElement page="help" headline="h3"/}}
73
74 {{internBaseOptionsElement page="css" headline="h3"/}}
75
76 {{internBaseOptionsElement page="attr" headline="h3"/}}
77
78 {{internBaseOptionsElement page="avail" headline="h3"/}}
79
80 {{internBaseOptionsElement page="misc" headline="h3"/}}
81
82 == Druckbild im Word-/PDF-Export ==
83
84 Wenn ein Formular per Word-/PDF-Export exportiert wird, sieht das Widget wie ein normales, auf Readonly geschaltetes, Eingabefeld aus.
85
86 == Formelbeispiele ==
87
88 {{table colWidth="-500"}}
89 |=Formel|=Erklärung
90 |{{code language="none"}}[%tf1%] - [%tf2%]
91
92 $('[name=tf1]').val() - $('[name=tf2]').val(){{/code}}|Subtraktion der Werte in den Eingabefeldern //tf1// und //tf2// einmal unter Verwendung von Passwörtern und einmal mittels //jQuery//-Selektoren
93 |{{code language="none"}}[%tf2%] * (1 + ([%tf1%] / 100)){{/code}}|Wird in //tf1// z.B. der Steuersatz und in //tf2// der Nettobetrag eingegeben, wird der Bruttobetrag berechnet
94 |{{code language="none"}}[%tf1%] + " " + [%tf2%]{{/code}}|Stringverkettung aus den Eingaben in den Eingabefeldern //tf1// und //tf2//
95 |{{code language="none"}}[%tf1%].length{{/code}}|Anzahl der eigegebenen Zeichen im Eingabefeld //tf1//
96 |{{code language="none"}}([%tf1%]<2) ? "Genehmigt" : "Abgelehnt"{{/code}}|Wenn der Wert in //tf1// kleiner als 2 ist, soll "Genehmigt" ausgegeben werden. Ansonsten "Abgelehnt".
97 |{{code language="none"}}$('[org_name=tf1]').sum()
98
99 $('[data-org-name=tf1]').sum(){{/code}}
100 (neue Schreibweise bei W3C konformen Modus)|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.
101 {{/table}}
102
103 Ein Demo-Beispiel zu den erwähnten Möglichkeiten finden Sie [[hier>>https://formexchange.formcycle.eu/formcycle/form/alias/104/widget_formula||rel="noopener noreferrer" target="_blank"]].
104
105 == Mögliche CSS-Anpassungen ==
106
107 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:
108
109 {{code language="css"}}
110 .CXFormula .label-top{
111 display: none;
112 }
113 .XFormula{
114 border: none !important;
115 background: none !important;
116 padding: 0;
117 }
118 {{/code}}
119
120
121 == Versionshistorie ==
122
123 === 2.3.1 ===
124
125 * Fix: Ungeklammerte Kommaausdrücke im JavaScript einer Formel werden nun unterstützt
126 * Verbesserte Fehlermeldung in der Konsole, wenn eine Formel syntaktisch ungültig ist.
127
128 === 2.3.0 ===
129
130 * Feature: Es kann nun ausgewählt werden, ob die Datentypen der Feldwerte automatisch ermittelt werden sollen oder ob die Feldwerte immer als Text gelesen werden sollen. Bisher wurden sie immer automatisch ermittelt.
131
132 === 2.2.1 ===
133
134 * Verbesserung der Performance beim Auswerten der Formeln.
135
136 === 2.2.0 ===
137
138 * Erfordert mindestens {{formcycle/}} Version 7.2.0.
139 * Auch nicht Formel-Platzhalter in der Formel werden ersetzt
140 * Das Eingabfeld für die Formel passt sich in der Höhe automatisch seinem Inhalt an.
141 * Das Eingabfeld für die Formel erlaubt die Eingabe von Zeilenumbrüchen.
142 * Bei Änderungen des Werts eines Formelfelds wird das JQuery-Ereignis //change// ausgelöst.
143 * Der this-Kontext innerhalb des Formel-JavaScript-Ausdrucks wird nun auf die JQuery-Instanz des Formelfelds gesetzt, dessen Formel evaluiert wird.
144
145 === 2.1.1 ===
146
147 * Fix: Formeln, welche von einem Element abhängen, welches über eine Bedingung versteckt oder gesperrt geschalten und geleert wird, aktualisieren sich, wenn die abängigen Elemente geleert werden.
148
149 === 2.1.0 ===
150
151 * Feature: Validationsattribute wie etwa Pflichtfeld, maximaler Wert und minimaler Wert sind nun auch am Berechnungsfeld verfügbar. Damit kann etwa einfach geprüft werden, ob die Summe von Elementen einen bestimmten Wert nicht überschreitet.
152
153 === 2.0.9 ===
154
155 * Fix: Beim Auführen einer Formel wird das Symbol "$" and "xm_jq()" gebunden, wenn verfügbar. Dies vermeidet Probleme, wenn das Formular in einer Drittseite eingebettet ist und die Drittseite das global "$" anders definiert.
156
157 === 2.0.8 ===
158
159 * Fix: Es wird "xm_jq()" verwendet, wenn verfügbar. Dies behebt Problem bei der Einbindung in Drittseiten, wenn die Drittseite eine andere JQuery-Bibliothek lädt.
160
161 === 2.0.7 ===
162
163 * Change: Verhalten für Checkbox-Elemente geändert: Bei Nutzung von Platzhalter ist Wert nun der am Element hinterlegte Werte (z.B. on), statt immer 0 oder 1.
164 * Change: Für Auswahlelemente mit der Darstellung "Radiobutton" ist bei Nutzung von Platzhaltern der Wert nun der Wert der ausgewählten Option, nicht mehr die Anzahl der ausgewählten Optionen.
165 * Change: Für Auswahlelemente mit der Darstellung "Checkbox" ist bei Nutzung von Platzhaltern der Wert nun die Summe der Werte aller ausgewählten Optionen (falls alle Werte nummerisch sind) oder die String-Konkatenation der Werte aller ausgewählten Optionen (wenn nicht alle Werte nummerisch sind), nicht mehr die Anzahl der ausgewählten Optionen.
166
167 === 2.0.6 ===
168
169 * Fix: Titel- und Platzhalter-Attribute werden korrekt kodiert, wenn das Berechnungsfeld erzeugt wird.
170
171 === 2.0.5 ===
172
173 * Performanz beim Auswerten von Formeln verbessert
174
175 === 2.0.4 ===
176
177 * Feature: Platzhalterauswahl im Editor hinzugefügt.
178
179 === 2.0.3 ===
180
181 * Fix: Kleinere Darstellungsfehler behoben
182
183 === 2.0.2 ===
184
185 * Feature: Berechnungsfelder können nun initial gesperrt und als Mussfeld geschalten werden.
186 * Fix: XSS-Angriffe verhindern
187 * Fix: Abarbeitungsreihenfolge der Berechnungsfelder angepasst, sodass nun problemlos in der Formel eines Berechnungsfeldes, Platzhalter für andere Berechnungselemente genutzt werden können.
188
189 === 2.0.1 ===
190
191 * Attribut data-name hinzugefügt (W3C-Konformität)
192
193 === 2.0.0 ===
194
195 * Initialer Release für die Version 7