Changes for page Zähler

From version 1.1
edited by gru
on 19.08.2021, 10:16
Change comment: There is no comment for this version
To version 1.25
edited by gru
on 31.08.2021, 10:47
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,1 +1,120 @@
1 -TODO
1 +{{content/}}
2 +
3 +{{id name="fig_counter"/}}
4 +{{figure image="counter_en.png"}}Configuration interface for creating counters: (1) list of existing counters, (2) area for editing the selected counter, (3) metadata of the counter.{{/figure}}
5 +
6 +The values of the counters can be changed with the action [[Change counter>>doc:Formcycle.Designer.Workflow.Actions.ModifyCounter]] and read out via [[variables>>doc:Formcycle.UserInterface.Variables]] and thus used in [[conditions>>doc:Formcycle.Designer.Workflow.FlowControl.Condition]], for example.
7 +
8 +== Creating a counter ==
9 +
10 +Open the "Data > Counter" module and click the "New" button {{ficon name="plus-circle-outline"/}} in the header of the list (see point 1 in [[figure>>||anchor="fig_counter"]]). Then the appropriate [[settings>>||anchor="HKonfigurationsoptionen"]] for the counter can be made. With a click on the //Save// button the counter is created.
11 +
12 +== Configuration options ==
13 +
14 +; Name
15 +: Name of the counter
16 +; Current value
17 +: The current value of the counter is displayed here. After clicking on the pencil symbol, the value can be adjusted and accepted by clicking on the check mark.
18 +; Reset automatically
19 +: If this option has been activated, the following options can be used to specify under which conditions the counter is to be reset:
20 +:; Initial value
21 +:: Value to which the counter is to be reset
22 +:; Condition
23 +:: Condition under which the counter is to be reset. The following options are available for selection:
24 +::: - Counter greater than or equal
25 +::: - Counter less than or equal
26 +::: - daily
27 +::: - weekly
28 +::: - monthly
29 +::: - yearly
30 +:: According to the selection made here, the following fields become visible:
31 +::; Value
32 +::: Value with which the counter is to be compared. Only available if //counter greater than or equal// or //counter less than or equal// has been selected as condition.
33 +::; at
34 +::: Time at which the reset should take place. Only available if //daily//, //weekly//, //monthly// or //annually// is selected as condition.
35 +::; On days
36 +::: Day of the week on which the reset should take place. Only available if //weekly// is selected as condition.
37 +::; Day of the month
38 +::: Day in month on which the counter is to be reset. Only available if //monthly// or //yearly// is selected as condition.
39 +::; Month
40 +::: Month in which the counter is to be reset. Only available if //annual// is selected as condition.
41 +
42 +The following information is also displayed under the settings in //Counter meta data//:
43 +
44 +; UUID
45 +: System internal UUID of the counter
46 +; Angelegt am
47 +: Time when the counter was created
48 +; Geändert am
49 +: Time when changes were last made to the meter
50 +
51 +== Variables ==
52 +
53 +The values of counters can be read out via [[variables>>doc:Formcycle.UserInterface.Variables]], for example in the workflow or as values of form elements. The syntax is as follows:
54 +
55 +{{code language="none"}}[%$COUNTER_CLIENT.<name of the counter>%]{{/code}}
56 +
57 +
58 +== Access of counter value via servlet ==
59 +
60 +=== Servlet {{smallcaps}}URL{{/smallcaps}} and parameters ===
61 +
62 +The value of the counters can be determined within forms via a servlet call. It is possible to select the counter by its name or UUID. The corresponding {{smallcaps}}URL{{/smallcaps}}s for calling the values could look like the following, for example:
63 +
64 +{{code language="none"}}https://<server address>/formcycle/form/clientcounter/?frid=<Valid frid>&name=<name of the counter>{{/code}}
65 +and
66 +{{code language="none"}}https://<server address>/formcycle/form/clientcounter/?frid=<Valid frid>&uuid=<UUID of the counter>{{/code}}
67 +
68 +
69 +In both cases a valid //form request id// (frid) is required, which can be found in the form via JavaScript under {{code language="none"}}XFC_METADATA.currentSessionFRID{{/code}}. In the same way, the {{smallcaps}}URL{{/smallcaps}} of the servlet can be read via JavaScript under {{code language="none"}}XFC_METADATA.urls.counter_client{{/code}}. This is important because the {{smallcaps}}URL{{/smallcaps}} differs when called from frontend and master servers.
70 +
71 +=== Return values ===
72 +
73 +The result is returned as JSON. Besides the actual value, other information is also returned. The response has the following structure:
74 +; success
75 +: Boolean value that indicates whether the meter value could be read successfully.
76 +; msg
77 +: Server message related to the request, which can be used for debugging. A successful access returns e.g. //Counter found//.
78 +; result
79 +: Response to the request. If the request was not successful, only an empty JSON object literal is returned. On the other hand, if the request was successful, the following sub-items are included in the JSON object literal:
80 +:; lastChange
81 +:: Formatted output of date and time of the last change of the counter value
82 +:; lastChangeTimestamp
83 +:: Epoch of the last change of the counter value
84 +:; name
85 +:: Name of the counter
86 +:; uuid
87 +:: UUID of the counter
88 +:; value
89 +:: Current counter value
90 +
91 +=== Example of an AJAX request in a form ===
92 +
93 +An example AJAX request that writes the current counter value of the //sample counter// to the //tf1// field might look like the following:
94 +
95 +{{code language="javascript"}}
96 +$.ajax({
97 + method: "GET",
98 + url: XFC_METADATA.urls.counter_client,
99 + data: {
100 + name: "Examplecounter",
101 + frid: XFC_METADATA.currentSessionFRID,
102 + }
103 +}).then(function(data) {
104 + if (data.success) {
105 + $('[data-name="tf1"]').val(data.result.value);
106 + } else {
107 + console.warn("Access to counter 'Examplecounter' failed:", data.msg);
108 + }
109 +}).catch(function(jqXHR, errorTextStatus, errorThrown) {
110 + console.warn("Access to counter 'Examplecounter' failed:", errorThrown, "(" + errorTextStatus + ")");
111 +});
112 +{{/code}}
113 +
114 +=== Inserting a template for an AJAX request in the form ===
115 +
116 +{{figure image="counter_query_en.png"}}Selection of the template for the counter query in the JavaScript area of the form designer.{{/figure}}
117 +
118 +A template similar to the above example function can be inserted directly in the JavaScript area of the Form Designer using Autocomplete. To do this, enter {{code language="none"}}Counter query{{/code}} (or at least {{code language="none"}}Counter{{/code}}) one after the other in the JavaScript area and select and confirm the //Counter query// option suggested by Autocomplete with a click or with the Arrow keys and the Enter key.
119 +
120 +After the template is inserted, the required functionality must be added and the name of the counter must be changed.