Changes for page Datenbankzähler-Plugin

From version < 1.2 >
edited by awa
on 21.11.2019, 09:36
To version < 2.1
edited by gru
on 29.01.2021, 16:38
<
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.awa
1 +XWiki.gru
Default language
... ... @@ -1,0 +1,1 @@
1 +de
Content
... ... @@ -1,180 +1,336 @@
1 +[[**Plugin download**>>url:https://customer.formcycle.eu/index.php/apps/files/?dir=/FORMCYCLE%20-%20Plugins%20Customer/fc-plugin-bundle-dbcounter&fileid=5521||target="_blank"]] (requires login)
2 +
1 1  {{content/}}
2 2  
3 -{{figure image="dbcounter_plugin_installation_en.png"}}
4 -The database counter plugin may be installed as either a client plugin or a system plugin. It requries no additional configuration.
5 +{{figure image="plugin_dbcounter_workflow_select_en.png" width="600"}}
6 +The database counter plugin may be installed as either a client plugin or a system plugin. It requires no additional configuration. Once installed, it offers to new workflow actions: //Variable// and //Counter.//. The //Counter// action requires you to choose a fixed counter that you would like to change. In contrast, the //Variable// action lets you choose the counter based on the submitted form data.
5 5  {{/figure}}
6 6  
7 -The database counter plugin lets you create one or more global counter in a database. The counter value may be incremented, decremented or reset during [[workflow processing>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.WebHome]]. Some possible uses cases are:
9 +The database counter plugin lets you create one or more counter in a database. It also adds a new menu entry to the backend where you can view and edit all available counters. You can then use the [[workflow processing>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.WebHome]] to increment or decrement the counter. This plugin is subject to additional charge.
8 8  
9 -* A reservation form that counts the number of participants. When a certain limit is reached, further form submissions are blocked.
10 -* Generating a custom ID for a form record that is independent of the internal FORMCYCLE process ID. This is useful especially when the ID needs to conform to a certain pattern or has to be reset in regular intervals.
11 -* Repeating the actions of a certain state //n// times, where //n// is set depending of a submitted form value.
11 +Some of the possible use cases include:
12 12  
13 -Furthermore, it is also possible to access the current value of the counter via a [[system variable>>doc:Formcycle.UserInterface.Variables]] during workflow processing; or via [[an AJAX request >>doc:Formcycle.FormDesigner.CodingPanel.ScriptTab.WebHome]] from within a form.
13 +* A registration form for a weekly event, when you need to keep track of the number of registered participants. You can then block new registrations for a certain date when the maximum number of participants has been reached.
14 +* Generating a unique {{smallcaps}}id{{/smallcaps}} for a form record that is independent of internal {{smallcaps}}id{{/smallcaps}}s used by {{formcycle/}}. Useful especially when the {{smallcaps}}id{{/smallcaps}} needs to conform to a certain pattern or needs to be reset in fixed intervals.
15 +* Running the [[actions>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.WebHome]] of a certain [[state>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.States.WebHome]] n-times, where //n// is determined by the value of a submitted form field.
14 14  
15 -Each counter has got both a name as well as a unqiue [[UUID>>https://en.wikipedia.org/wiki/Universally_Unique_Identifier]]. The UUID uniquely identifies a counter and is used when querying the counter value with an AJAX request.
17 +Once the plugin is installed, you can manage the available counter in a separate backend page. You can check which counters exist currently and add or delete counter. The current value of each counter is displayed as well, and if necessary, you can also change the counter's value.
16 16  
17 -== Workflow action "Counter" ==
19 +In addition, this plugin offers two new [[workflow>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.WebHome]] [[actions>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.WebHome]]: //Counter// and //Variable//. The action //Counter// requires you to select a predefined counter. The action //Variable//, on the other hand, lets you select a counter based on the value of a submitted fo m field. See the sections on each action below for further details.
18 18  
19 -Once the plugin is installed, you can choose a new action in the [[workflow processing configuration>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.WebHome]]. The action is a plugin action named //Counter//. You can use this action to modify the value of a counter or reset it in regular intervals.
20 -=== Allgemeine Einstellungen ===
21 +Lastly, you can also access the current value of a counter either via a [[variable>>doc:Formcycle.UserInterface.Variables]] during workflow processing or [[via an {{smallcaps}}Ajax{{/smallcaps}} request from within an opened form>>doc:Formcycle.FormDesigner.CodingPanel.ScriptTab.WebHome]].
21 21  
22 -{{figure image="dbcounter_plugin_action_base_settings_en.png"}}
23 -Base settings for the workflow action //Counter//. Here you can choose which counter should be changed and in what manner.
24 -{{/figure}}
23 +Each counter has got both a name as well as a unique [[{{smallcaps}}Uuid{{/smallcaps}}>>https://de.wikipedia.org/wiki/Universally_Unique_Identifier]]. The {{smallcaps}}Uuid{{/smallcaps}} uniquely identifies a counter and is used, for example, when querying the counter's current value via an {{smallcaps}}Ajax{{/smallcaps}} request.
25 25  
26 -; 1 - Zählername
27 -: Auswahl des Zählers, dessen Wert geändert werden soll. Für jeden Zähler wird sowohl sein Name als auch seine UUID angezeigt. Die UUID dient der eindeutigen Identifikation des Zählers und wird etwa bei der Abfrage per AJAX verwendet. Um einen Zähler zu löschen, wird dieser ausgewählt und das Papierkorb-Symbol rechts neben der Auswahl betätigt. Um einen neuen Zähler hinzuzufügen, wird zuerst auf das Plus-Symbol gedrückt, anschließend der gewünschte Name des Zählers eingegeben und schließlich der neue Zähler durch Drücken des Plus-Symbols angelegt.
28 -; 2 - Zählaktion
29 -: Gibt an, in welcher Art und Weise der Wert des Zählers geändert werden soll. Möglich Optionen sind:
30 -:; Hochzählen
31 -:: Erhöht den Wert des Zählers um die eingegebene Zahl.
32 -:; Herunterzählen
33 -:: Erniedrigt den Wert des Zählers um die eingegebene Zahl.
34 -:; Zähler auf Startwert zurücksetzen
35 -:: Setzt den Wert des Zählers auf den eingegebenen Startwert zurück.
36 -; 3 - Schrittweite
37 -: Anzahl, um die der Zähler hoch beziehungsweise herunter gesetzt werden soll.
38 -; 4 - Startwert
39 -: Initialer Wert des Zählers, den dieser annimmt, wenn er angelegt wird. Es ist auch möglich, den Zähler auf diesen Startwert zurückzusetzen.
40 -; 5 - Automatisch zurücksetzen
41 -: Ist diese Option aktiviert, erscheint eine weitere Konfigurationsmöglichkeit zum Einstellen, wann der Zähler automatisch auf den Startwert zurückgesetzt werden soll. Dies kann etwa beim Überschreiten eines bestimmten Werts oder in regelmäßigen Zeitabständen erfolgen.
25 +This is plugin bundle that includes two workflow action plugins, one placeholder replacer plugin, and one servlet action plugin. The following sections describe these plugins in more detail.
42 42  
43 -=== Automatisches Zurücksetzen ===
27 +== Menu entry "Counter configuration" ==
44 44  
45 -{{figure image="dbcounter_plugin_action_reset_greater_or_equal_en.png"}}
46 -Die Konfiguration zum Zurücksetzen eines Zählers, wenn dessen Wert eine bestimmte Grenze übersteigt.
47 -{{/figure}}
29 +{{info}}
30 + This plugin adds a new [[role permission>>doc:Formcycle.UserInterface.UserSettings.Roles]] that controls whether a user is granted access to this menu entry. Contact your administrator in case you do not see the menu entry and believe you should have access.
31 +{{/info}}
48 48  
49 -{{figure image="dbcounter_plugin_action_reset_daily_en.png"}}
50 -Die Konfiguration zum täglichen Zurücksetzen eines Zählers.
51 -{{/figure}}
33 +{{figure image="plugin_dbcounter_config_base_en.png" width="600"}}
34 + The menu with an overview of all existing counter. You can add or delete counter, or modify existing counters.{{/figure}}
52 52  
53 -{{figure image="dbcounter_plugin_action_reset_weekly_en.png"}}
54 -Die Konfiguration zum wöchentlichen Zurücksetzen eines Zählers.
55 -{{/figure}}
36 +Once installed, a new menu entry appears in the main menu bar to the left. Please note that you may have to sign out and sign in again. The menu //Counter configuration// contains an overview of all existing counters, including their name and their current value. You can modify or delete existing counter, or add new counters.
56 56  
57 -{{figure image="dbcounter_plugin_action_reset_monthly_en.png"}}
58 -Die Konfiguration zum monatlichen Zurücksetzen eines Zählers.
59 -{{/figure}}
38 +Press the plus icon to the top left to add a new counter. If you would like to delete an existing counter, click on that counter to select it, then press the trash icon to the top left.
60 60  
61 -{{figure image="dbcounter_plugin_action_reset_yearly_en.png"}}
62 -Die Konfiguration zum jährlichen Zurücksetzen eines Zählers.
63 -{{/figure}}
40 +=== Properties ===
64 64  
42 +Select a counter by clicking on it in the list of counters to the left. The following details are shown for the counter:
43 +
44 +; {{smallcaps}}Uuid{{/smallcaps}}
45 +: A unique {{smallcaps}}id{{/smallcaps}} of the counter. You need to use this {{smallcaps}}Uuid{{/smallcaps}}, for example, when you want to retrieve the counter's current value via an {{smallcaps}}Ajax{{/smallcaps}} request, see also the servlet action plugin below.
46 +; Current value
47 +: The current value of the counter.
48 +; Creation date
49 +: The date when the counter was created.
50 +; Last change
51 +: The date of the most recent change to the counter's value.
52 +
53 +Additionally, you can also edit the following properties of a counter:
54 +
55 +; Counter name
56 +: The name of this counter. When you change the name of a counter, you may have to change existing //Variable// action, placeholders and {{smallcaps}}Ajax{{/smallcaps}} requests that reference a counter by its name. {{smallcaps}}Ajax{{/smallcaps}} requests that reference a counter by its {{smallcaps}}Uuid{{/smallcaps}} do not have to be updated.
57 +; Description
58 +: An optional description of this counter. This description is shown only within this backend menu.
59 +; Initial value
60 +: The initial value of this counter. This is also the value that is used when a workflow action resets a counter to its initial value.
61 +; Reset automatically
62 +: When this option es enabled, the value of this counter is reset in period intervals.
63 +
64 +=== Reset automatically ===
65 +
66 +The following settings are available when the option to reset the counter automatically is enabled:
67 +
65 65  {{info}}
66 -Geschieht ein Zurücksetzen des Zählers, so ist nach Ausführung der aktuellen Aktion der Wert des Zählers gleich dem Startwert, wie er in den allgemeinen Einstellung eingegeben wurde. Zum Beispiel: Die Counter-Aktion sei so eingestellt, dass der Zähler um 3 erhöht wird. Weiterhin soll der Zähler täglich zurückgesetzt werden. Der aktuelle Wert sei //39//, der Startwert //11//. Die erste Counter-Aktion, die an einem Tag ausgeführt wird, setzt nun dern Wert des Zählers auf den Wert //11// zurück. Das Hochzählen um //3// erfolgt erst ab der zweiten Counter-Aktion an einem Tag.
69 + When a counter is reset, then after the counter action was processed, the counter's value will be equal to the configured initial value. For example: Assume the counter action was configured to increment the counter by //3// each time it is executed, and should be reset daily. Let the the current counter value be //37// and the intial value //11//. The first counter action that is executed on a new day will now reset the counter to //11//, and not be incremented at all. Starting with the second counter action of that day, the counter will be incremented by //3// each time the action is executed.
67 67  {{/info}}
68 68  
69 -Es ist möglich, den Zähler in regelmäßigen Abständen zurückzusetzen. Diese Option ist nur verfügbar, wenn als Zählaktion nicht //Zähler auf Startwert zurücksetzen// gewählt wurde. Zudem muss in den allgemeinen Einstellungen die Option //Automatische zurücksetzen// aktiviert sein. Es kann dann ausgewählt werden, wann der Zähler zurückgesetzt werden soll.
72 +{{info}}
73 + Please note that the counter is not reset by background task, but only when the workflow action //Counter// or //Variable// is executed. Or, to be more precise, the counter value is reset (instead of being incremented or decremented), when the time points at which the counter should have been reset contains at least one point that lies between the last point in time the counter value was modified and the current point in time.
74 +{{/info}}
70 70  
71 -Hierbei ist zu beachten, dass der Zähler nicht in einem Hintergrundprozess zurückgesetzt wird, sondern erst wenn die Verarbeitungsaktion //Counter// ausgeführt wird. Genauer: Der Zählwert wird bei Ausführung der Aktion zurückgesetzt (anstelle erhöht oder erniedrigt zu werden), falls zwischen dem Zeitpunkt, an dem der Zählwert zuletzt geändert wurde, und dem aktuellen Zeitpunkt des Servers ein Zeitpunkt liegt, an dem der Zähler gemäß Konfiguration zurückgesetzt hätte werden müssen.
76 +; Condition
77 +: Lets you choose when and how the counter should be reset. The following options are available:
78 +:; Counter greater than or equal
79 +:: Available only when the counting action was set to //count up//. The counter is reset to its initial value when, after the counter was incremented, its value is now greater than or equal to the given limit.
80 +:; Counter less than or equal
81 +:: Available only when the counting action was set to //count down//. The counter is reset to its initial value when, after the counter was decremented, its value is now less than or equal to the given limit.
82 +:; daily
83 +:: The counter is reset each day at the given time of day.
84 +:; weekly
85 +:: The counter is reset at each of the given days of the week and at the given time of the day.
86 +:; monthly
87 +:: The counter is reset each month at the given date and time of the day.
88 +:; yearly
89 +:: The counter is reset each year the given day, month and time of the day.
72 72  
73 -; 1 - Bedingung
74 -: Hier kann festgelegt werden, wann und unter welchen Umständen der Zähler zurückgesetzt werden soll.
75 -:; Zähler größer gleich
76 -:: Nur verfügbar, wenn als Zählaktion //Hochzählen// gewählt wurde. Der Zähler wird auf den Startwert zurückgesetzt, wenn durch die aktuelle Aktion der Wert des Zählers so geändert wird, dass dieser größer oder gleich dem in (2) festgelegten Wert ist.
77 -:; Zähler kleiner gleich
78 -:: Nur verfügbar, wenn als Zählaktion //Herunterzählen// gewählt wurde. Der Zähler wird auf den Startwert zurückgesetzt, wenn durch die aktuelle Aktion der Wert des Zählers so geändert wird, dass dieser kleiner oder gleich dem in (2) festgelegten Wert ist.
79 -:; täglich
80 -:: Der Zähler wird jeden Tag zur bei (2) gewählten Uhrzeit auf den Startwert zurückgesetzt.
81 -:; wöchentlich
82 -:: Der Zähler wird an jedem unter (2) gewählten Wochentag zu der unter (3) gewählten Uhrzeit zurückgesetzt.
83 -:; monatlich
84 -:: Der Zähler wird jeden Monat zum unter (2) gewählten Tag zu der unter (3) gewählten Uhrzeit zurückgesetzt.
85 -:; jährlich
86 -:: Der Zähler wird jedes Jahr zum unter (2) und (3) gewählten Tag zu der unter (4) gewählten Uhrzeit zurückgesetzt
91 +== Workflow action "Counter" ==
87 87  
88 -=== Allgemeine Rückgabeparameter ===
93 +{{figure image="plugin_dbcounter_action_counter_en.png"}}
94 + The settings for the workflow action //Counter//. You can select the counter to modify and how its value should be changed, e.g. incrementing or decrementing it by a certain amount.
95 +{{/figure}}
89 89  
90 -{{figure image="dbcounter_plugin_action_return_parameters_en.png"}}
91 -Einstellungen für die Rückgabeparameter, die später über Platzhalter verfügbar sind.
97 +Once the plugin is installed, you can select the new action //Counter// in the [[workflow processing configuration>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.WebHome]]. This action lets you modify the value of a predefined counter.
98 +
99 +Compared with the action //Variable//, here you need to select a predefined counter. You should have created this counter in the counter configuration menu (see above). Use this action when you need a global, non-dynamic counter, such as when you want to generate an identifier for each form record.
100 +
101 +; Counter name
102 +: Name of the counter to be modified. For each counter you can see its name as well as its {{smallcaps}}Uuid{{/smallcaps}}. The {{smallcaps}}Uuid{{/smallcaps}} uniquely identifies a counter and is used when querying it via an {{smallcaps}}Ajax{{/smallcaps}} request. To delete a counter, first select the counter, then click on the thrash icon to the right. To add a counter, first click on the plus icon, then enter a name for the new counter, and finally save the counter by pressing the floppy disc icon.
103 +; Counting action
104 +: Lets you chose how the value of the counter should be changed. Possible options are:
105 +:; Increment count
106 +:: Adds the given amount to the current value of the counter.
107 +:; Decrement count
108 +:: Substracts the given amount from the current value of the counter.
109 +:; Reset counter to start value
110 +:: Sets the current value of the counter back to the selected initial value.
111 +; Step size
112 +: Amount by which the counter is incremented or decremented.
113 +; Use global settings (deprecated)
114 +: You should leave this option checked and configure the counter settings in the counter configuration menu (see above). It exists only to ensure backwards compatibility with older versions of the plugin and may be removed in future versions.
115 +
116 +== Workflow action "Variable" ==
117 +
118 +{{figure image="plugin_dbcounter_action_variable_en.png"}}
119 + Settings for the workflow action //Variable//. It lets you select a counter dynamically by its name. You can also make use of placeholder variables to select a counter based on the value of some form field.
92 92  {{/figure}}
93 93  
94 -Manchmal ist es notwendig, auf den neuen Zählwert zugreifen zu können. Dies kann über Aktionsplatzhalter geschehen, welche auf die Rückgabewerte einer Aktion zugreifen. In den allgemeinen Rückgabeparametern kann eingestellt werden, über welchem Schlüssel die Rückgabeparameter Aktion zugegriffen werden kann. Beispielsweise trage die Zähleraktion den Namen //CountUp//. Dann kann über den Platzhalter //[%$CountUp.RESULT[0].count%]// auf den aktuellen Zählwert zugegriffen werden, falls unter (3) bei den allgemeinen Rückgabeparameter der Wert //count// eingetragen wurde. Folgende Rückgabeparameter sind verfügbar:
122 +Once the plugin is installed, you can select the new action //Variiable// in the [[workflow processing configuration>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.WebHome]]. This action lets you select a counter by its name and modify its value.
95 95  
124 +Compared with the action //Counter//, here you do not have to choose a predefined counter. You can also use [[placeholder variables>>doc:Formcycle.UserInterface.Variables]] to select a counter based on the submitted form data. In case the counter does not exists yet, a new counter is created dynamically.
125 +
126 +Use this action when you need different counters for each submitted form record. For example, if you have got a participation form where users can sign up for a certain date, you can use a counter for each date to keep track of the number of registered people for that date. The counter name could be formatted like //participants-year-month-day//.
127 +
128 +=== Change variable ===
129 +
130 +Select the name of the variable ("counter") to modify and how its value should be changed.
131 +
132 +; Counter name
133 +: Name of the counter to modify. Enter name of the counter, not its {{smallcaps}}Uuid{{/smallcaps}}). You can also use [[placeholder variables>>doc:Formcycle.UserInterface.Variables]] to select a counter based on a submitted form field.
134 +; Counting action
135 +: Lets you chose how the value of the counter should be changed. Possible options are:
136 +:; Increment count
137 +:: Adds the given amount to the current value of the counter.
138 +:; Decrement count
139 +:: Subtracts the given amount from the current value of the counter.
140 +:; Reset counter to start value
141 +:: Sets the current value of the counter back to the selected initial value.
142 +; Step size
143 +: Amount by which the counter is incremented or decremented.
144 +
145 +=== Default settings if variable does not exists yet ===
146 +
147 +In case the variable ("counter") with the given name does not exist yet, a new counter is created. Here you can edit the default settings for a newly created counter. In case the counter exists already, these settings do not have any effect.
148 +
149 +; Initial value
150 +: The initial value of the newly created counter.
151 +; Reset automatically
152 +: Whether the newly created counter should be reset automatically. When this option is enabled, a few more settings appear. See the section on the counter configuration menu above for further details.
153 +
154 +== General return parameters ==
155 +
156 +{{figure image="plugin_dbcounter_action_return_parameters_en.png"}}
157 +Settings for the return parameters of the counter action. You can access the returned values via placeholder variables.
158 +{{/figure}}
159 +
160 +Sometimes it may be necessary to access the new value of the counter. To do so, you can use [[action variables>>doc:Formcycle.UserInterface.Variables]] for accessing the returned values of an action. The section //general return parameters// lets you configure the key you need to use for accessing the return values. For example, assume a counter action were named //CountUp//. Then you can use the variable //[%$CountUp.RESULT[0].currentValue%]// to access the current counter value, provided you entered the key //currentValue// in the input field for the //Counter// return value. The following return values are available:
161 +
96 96  ; 1 - ResultCode
97 -: Ein nummerischer Zahlenwert, der angibt, ob die Zählaktion erfolgreich war oder nicht. Folgende Ergebnisnummern sind möglich:
163 +: A numerical value that indicates whether the counter action was successful or not. The following result codes are possible:
98 98  :; 1 (OK)
99 -:: Die Zählaktion wurde erfolgreich abgearbeitet.
165 +:: The counter action was processed successfully.
100 100  :; 10 (UNKNOWN_ACTION_ERROR)
101 -:: Die Zählaktion kann nicht ausgeführt werden, da eine unbekannte Zählaktion ausgewählt wurde. Aktuell werden die Zählaktionen //Hochzählen//, //Herunterzählen// und //Auf den Startwert zurücksetzen// unterstützt.
167 +:: The counter action could not be processed, an unknown counting action was selected. The currently supported counting actions are //count up//, //count down// and //reset counter to start value//.
102 102  :; 11 (PARSING_ERROR)
103 -:: Ein konfigurierter Wert hat nicht den erwarteten Datentyp, etwa wenn für die Schrittweite des Zählers keine syntaktisch korrekte Zahl eingegeben wurde.
169 +:: A settings does not conform to the expected data type or syntax; such as when a letter was entered for the initial value (instead of a number).
104 104  :; 40 (INTERNAL_ERROR)
105 -:: Es ist ein anderer Fehler aufgetreten, der nicht näher klassifiziert werden kann.
171 +:: The counter action was not successful. The type of error cannot be specified more closely.
106 106  ; 2 - ResultMessage
107 -: Eine englische Beschreibung des Resultats (Erfolg oder Fehler).
173 +: An English description of the result (success or error).
108 108  ; 3 - Counter
109 -: Der neue nummerische Wert des Zählers, nachdem die Zählaktion ausgeführt wurde.
175 +: The new numerical value of the counter, after the counting action was applied.
110 110  ; 4 - IsReset
111 -: Entweder //true//, falls der Zähler durch die aktuelle Aktion zurückgesetzt wurde; oder //false//, wenn er nicht zurückgesetzt wurde.
177 +: Either //true//, when the counter was reset during the current action; or //false// if it was not reset.
112 112  ; 5 - CounterAfterReset
113 -: Falls der Zähler zurückgesetzt wurde: Der nummerische Wert des Zählers vor dem Zurücksetzen.
179 +: In case the counter was reset: The numerical value of the counter before the reset.
114 114  
115 -== Systemplatzhalter-Plugin ==
181 +== System variable plugin ==
116 116  
117 117  {{figure image="dbcounter-plugin-placeholder_en.png"}}
118 -Ein Beispiel für den Platzhalter zum Auslesen des Zählwerts. Hier wird ein Zähler ausgelesen, der die Anzahl an Anmeldungen für eine Veranstaltung zählt. Dann wird geprüft, ob der Zählwert die maximale Anzahl an Anmeldungen übersteigt. Basierend auf dieser Prüfung kann dem Nutzer dann ein Fehler angezeigt werden, falls die Veranstaltung bereits ausgebucht ist. Hierbei handelt es sich um eine serverseitige Prüfung zur Validierung, bereits im Formular bei der Anmeldung sollte dem Nutzer natürlich schon die Information gegeben werden, ob überhaupt noch Plätze frei sind.
184 + An example for how to retrieve the current value of a counter. Here we read a counter that is used for keeping track of the number of participants of some event. We then check whether the value exceeds the maximum number of participants. Based on the result of this check, we can display an appropriate error message to the user in case the limit was reached. By performing this check during workflow processing, we can validate the data on the server and prevent manipulatios. Please note that it is best practice to give the user some feedback while the fill out the form and inform the user in case no more free slots are available.
119 119  {{/figure}}
120 120  
121 -Nach Installation des Plugins ist ein neuer [[Systemplatzhalter>>doc:Formcycle.UserInterface.Variables]] verfügbar, über den auf den aktuellen Wert eines Zählers zugegriffen werden kann. Dies ist etwa nützlich, um in einer Aktionsbedingung den Zählwert nutzen und prüfen zu können. Der Platzhalter baut sich nach dem folgenden Schema auf:
187 +Once the plugin is installed, you can access the current value of the plugin with a [[system variable>>doc:Formcycle.UserInterface.Variables]]. This can be used, for example, to access the counter value in the condition of a workflow action and compare it with a submitted value. The system variable has got the following pattern:
122 122  
123 -{{code}}
124 -[%$DBCOUNTER.<Zählername>%]
189 +{{code language="none"}}
190 +[%$DBCOUNTER.<CounterName>%]
125 125  {{/code}}
126 126  
127 -Um also etwa auf den Zähler mit dem Name //test// zuzugreifen, muss der folgende Platzhalter genutzt werden:
193 +For example, in order to access the value of a counter named //test//, you can use the following variable:
128 128  
129 -{{code}}
195 +{{code language="none"}}
130 130  [%$DBCOUNTER.test%]
131 131  {{/code}}
132 132  
133 -== Servlet-Aktions-Plugin ==
199 +In case you need to access a counter that may not exist yet, you need to provide an initial value for the counter. When the counter does not exist yet, a new counter with the given initial value is created. Use the following pattern:
134 134  
201 +{{code language="none"}}
202 +[%$DBCOUNTER(<CounterName>, <InitialValue>)%]
203 +{{/code}}
204 +
205 +For example, if the counter is named //participants-2020-03-17// and should start at //0// in case it does not exist, you can use the following variable:
206 +
207 +{{code language="none"}}
208 +[%$DBCOUNTER(participants-2020-03-17, 0)%]
209 +{{/code}}
210 +
211 +== Servlet action plugin ==
212 +
135 135  {{figure image="dbcounter_plugin_servlet_action.png"}}
136 -Beispiel zum Auslesen eines Zählers im Formular mittels AJAX. Die URL wird anhand der im Formular zur Verfügung stehenden Metadaten aufgebaut. Hiermit wird vermieden, die URL hart im Quelltext zu hinterlegen, was zu Fehlern führt, wenn sich etwa der Server oder der Kontextpfad ändern sollte.
214 + An example for how the counter value can be accessed via an {{smallcaps}}Ajax{{/smallcaps}} request. The {{smallcaps}}Url{{/smallcaps}} is build with the metadata available in the form context. This avoids having to enter the {{smallcaps}}Url{{/smallcaps}} directly in the code, which is prone to error: the host or context path could change, for example, when the form is moved between a development and production.
137 137  {{/figure}}
138 138  
139 -Nach Installation des Plugins ist eine neue Servlet-Aktion verfügbar, mit der auf den aktuellen Wert eines Zähler zugegriffen werden kann. Dies ist etwa nützlich, wenn aus dem Formular heraus ein Zählwert per AJAX-Anfrage abgerufen werden soll. Die URL für das Servlet baut sich nach dem folgenden Schema auf:
140 140  
141 -{{code}}
142 -https://<HOST>/<FORMCYCLE_CONTEXT_PATH>/plugin?name=Servlet%20Counter&client-id=<MANDANT_ID>&id=<ZAEHLER_UUID>
218 +Once the plugin is installed, a new servlet plugin action is available that lets you access the current value of a counter via an {{smallcaps}}Http{{/smallcaps}} request. This is useful, for example, when you would like to read the counter's current value from within a form and display it in the form. The {{smallcaps}}Url{{/smallcaps}} for the counter action plugin servlet takes the following pattern:
219 +
220 +{{code language="none"}}
221 +https://<Host>/<FormcycleContextPath>/plugin?name=Servlet%20Counter&client-id=<ClientId>&id=<CounterUuid>
143 143  {{/code}}
144 144  
145 -Falls also etwa FORMCYCLE lokal unter dem Pfad //xima-formcycle// installiert wurde, der Zähler in einem Projekt des Mandanten mit der ID //1// verwendet wird und die UUID //bc49d3b0-f869-4e59-864e-ddcc2925ed63// besitzt, dann lautet die URL:
224 +Assuming {{formcycle/}} was installed locally and runs in the context path //formcycle//, and the counter plugins was installed within a client with the {{smallcaps}}id{{/smallcaps}} //1//, and the {{smallcaps}}Uuid{{/smallcaps}} of the counter is //bc49d3b0-f869-4e59-864e-ddcc2925ed63//, the {{smallcaps}}Url{{/smallcaps}} is:
146 146  
147 -{{code}}
148 -https://localhost:8080/xima-formcycle/plugin?name=Servlet%20Counter&client-id=1&id=bc49d3b0-f869-4e59-864e-ddcc2925ed63
226 +{{code language="none"}}
227 +https://localhost:8080/formcycle/plugin?name=Servlet%20Counter&client-id=1&id=bc49d3b0-f869-4e59-864e-ddcc2925ed63
149 149  {{/code}}
150 150  
151 -Alternativ ist es auch möglich, statt der //client-id// die ID des Formulars zu verwenden. Diese IDs lediglich verwendet, um das Servlet-Aktions-Plugin zu bestimmen, welches ausgeführt werden soll, und werden von diesem konkreten Plugin nicht ausgewertet:
230 +Alternatively, you can also use the {{smallcaps}}id{{/smallcaps}} of the form instead of the //client-id//. Both the client and the form {{smallcaps}}id{{/smallcaps}} are used only to identify the servlet to be executed; and are not used in any way by this counter servlet.
152 152  
153 -{{code}}
154 -https://<HOST>/<FORMCYCLE_CONTEXT_PATH>/plugin?name=Servlet%20Counter&project-id=<FORMULAR_ID>&id=<ZAEHLER_UUID>
232 +{{code language="none"}}
233 +https://<Host>/<FormcycleContextPath>/plugin?name=Servlet%20Counter&project-id=<FormID>&id=<CounterUuid>
155 155  {{/code}}
156 156  
157 -Nach Ausführung des Servlet-Aktions-Plugin wird das Ergebnis als JSON-Objekt zurückgeliefert, siehe hierzu auch die Abbildung. Dieses JSON-Objekt hat die folgenden Einträge:
236 +=== HTTP parameter ===
158 158  
238 +In addtional to the parameters mentioned above, you can also specify a few more paramters as {{smallcaps}}Url{{/smallcaps}} parameters. The following is an overview of all available parameters.
239 +
240 +; name
241 +: The name of the servlet plugin action to execute. Set this to //Servlet Counter// for this plugin.
242 +; client-id
243 +: {{smallcaps}}id{{/smallcaps}} of the client where the counter plugin was installed. Not required in case the plugin was installed as a system plugin. Only one of //client-id// or //project-id// may be specified.
244 +; project-id
245 +: {{smallcaps}}id{{/smallcaps}} of a form that belongs to a client that has access to the counter plugin., in dem das Zähler-Plugin zur Verfügung steht. Only one of //client-id// or //project-id// may be specified.
246 +; id
247 +: {{smallcaps}}Uuid{{/smallcaps}} of counter to read. In case a counter with the given {{smallcaps}}Uuid{{/smallcaps}} does not exist yet, a corresponding error code is returned, see below. Only one of //id// or //counter-name// may be specified.
248 +; counter-name
249 +: Name of the counter to read. In case a counter with the given name does not exist yet, a new counter is created with the given initial value.Only one of //id// or //counter-name// may be specified.
250 +; counter-initial
251 +: Optional. The initial value of the counter, in case it does not exist yet. Defaults to //0//. This parameter is allowed only when //counter-name// is specified.
252 +; counter-array
253 +: Optional. Either //true// or //false//, defaults to //false//. When this is set to //true//, the parameter //counter-name// or //id// may be specified multiple times. This will return an array with the current value of all specified counters. This can be used, for example, to reduce the amount of {{smallcaps}}Http{{/smallcaps}} requests when you need to query multiple counter simultaneously.
254 +
255 +=== HTTP response ===
256 +
257 +If the servlet action plugin is executed successfully, it returns a {{smallcaps}}Json{{/smallcaps}} object as shown in the figure to the right. When the parameter //counter-array// was set to //true//, a {{smallcaps}}Json{{/smallcaps}} array is returned instead, with each item being a {{smallcaps}}Json{{/smallcaps}} object as described below.
258 +
259 +The {{smallcaps}}Json{{/smallcaps}}-Objekt has got the following properties:
260 +
159 159  ; Status
160 -: Gibt an, ob der Servlet-Aufruf erfolgreich war. Der Wert ist ein weiteres JSON-Objekt mit folgenden Einträgen:
262 +: Indicates whether the servlet request was successful. The value is another {{smallcaps}}Json{{/smallcaps}} object with the following entries:
161 161  :; Msg
162 -:: Ein nummerischer Wert, der angibt, ob der Servlet-Aufruf erfolgreich war. Mögliche Werte sind:
163 -::; (OK)
164 -::; (NO_REQUEST_ID_ERROR)
165 -::; (NO_COUNTER_TO_UUID_ERROR)
264 +:: A numerical value that indicates whether the servlet request was successful. Possible values are:
265 +::; 0 (OK)
266 +::: The request was successful.
267 +::; 12 (NO_REQUEST_ID_ERROR)
268 +::: The request did not specify a counter UUID.
269 +::; 13 (NO_COUNTER_TO_UUID_ERROR)
270 +::: No counter with the specified UUID exists.
271 +::; 40 (INTERNAL_ERROR)
272 +::: The counter action was not successful. The type of error cannot be specified more closely.
166 166  :; Code
167 -:: Eine englische Beschreibung des Resultats (Erfolg oder Fehler).
274 +:: An English description of the result (success or error).
168 168  ; Counter
169 -: Informationen zum angefragten Zähler. Der Wert ist ein weiteres JSON-Objekt mit folgenden Einträgen:
170 -: Der aktuelle nummerische Wert des Zählers.
276 +: Details about the requested counter. The value is another {{smallcaps}}Json{{/smallcaps}} object with the following entries:
171 171  :; LastChange
172 -:: Das Datum mit Uhrzeit, an dem der Zähler zuletzt geändert wurde. Das Datum wird mit dem Datums- und Zeitformat der aktuellen Server-Locale formattiert.
278 +:: The date and time of the most recent modification of the counter value. The date and time is formatted according to the current server locale.
173 173  :; LastChangeTimestamp
174 -:: Das Datum mit Uhrzeit, an dem der Zähler zuletzt geändert wurde. Der Zeitstempel ist eine ganze Zahl, welche die Anzahl an Millisekunden seit dem 1. Januar, 1970, 00:00:00 GMT angibt.
280 +:: The date and time of the most recent modification of the counter value. The timestamp is a whole number indicating the number of milliseconds January 1st, 1970, 00:00:00 GMT.
175 175  :; Value
176 -:: Der aktuelle nummerische Wert des Zählers.
282 +:: The current numerical value of the counter.
177 177  :; UUID
178 -:: Die UUID des angefragten Zählers, dessen Wert ausgelesen wurde.
284 +:: The UUID of the requested counter.
179 179  :; Name
180 -:: Der Name des angefragten Zählers, dessen Wert ausgelesen wurde.
286 +:: The name of the requested counter.
287 +
288 +== Changelog ==
289 +
290 +This section lists all known versions of this plugin and describes the changes that were made in each version.
291 +
292 +=== 2.3.3 ===
293 +
294 +* Fixed some spelling mistakes
295 +
296 +=== 2.3.2 ===
297 +
298 +* Fixed a UI bug: The checkbox //Use global settings// (action //Counter//) now toggles the options below correctly.
299 +* Fixed some spelling mistakes
300 +
301 +=== 2.3.1 ===
302 +
303 +* Fixed a bug with {{smallcaps}}Mysql{{/smallcaps}} that prevented this plugin from working with that database management system.
304 +
305 +=== 2.3.0 ===
306 +
307 +* New action: //Variable//
308 +* Lets you select a counter by its name and allows for placeholder variables. This requires an initial value.
309 +* New placeholder variable: //DBCOUNTER(name, initialValue)//. Creates a new counter in case a counter with the given name does not exist yet.
310 +* Added 3 new parameters to the servlet action plugin: //counter-name//, //counter-initial// and //counter-array//.
311 +
312 +=== 2.2.0 ===
313 +
314 +* Make sure to reset the counter even when its value is only read
315 +* Portal page that adds a new menu entry to the backend: Counter configuration
316 +* Deprecate editing a counter's settings in the workflow action directly
317 +
318 +=== 2.1.0 ===
319 +
320 +* Modifications for {{formcycle/}} version 6.1.6
321 +* The //CounterPlugin// and //ServletCounterPlugin// had the same name, this resulted in errors
322 +* Fixed an error that resulted in a counter not being resetted correctly
323 +* Add a new property to the {{smallcaps}}Json{{/smallcaps}} object returned by the servlet action plugin: //Counter.LastChangeTimestamp//
324 +* Added a new system variable replacer plugin that lets you access the value of a counter via a variable: //[%DBCOUNTER.name%]//
325 +
326 +=== 2.0.0 ===
327 +
328 +* Modifications to make the plugin work with {{formcycle/}} version 6.0.2
329 +
330 +=== 1.0.1 ===
331 +
332 +* Fix a bug where the counter value was not set when retrieved for the first time
333 +
334 +=== 1.0.0 ===
335 +
336 +* Initial version

Navigation

Copyright 2000-2025