Wiki source code of Platzhalter
Show last authors
author | version | line-number | content |
---|---|---|---|
1 | {{content/}} | ||
2 | |||
3 | Variables are used to dynamically insert the value of form fields, the results of actions, certain system properties and more. They are available to [[templates>>doc:Formcycle.UserInterface.FilesAndTemplates.WebHome]], most settings of [[actions>>doc:Formcycle.Designer.Workflow.Actions.WebHome]] and [[data base queries>>Formcycle.UserInterface.Data.DBQueries]]. | ||
4 | |||
5 | As a common use case, consider a form allowing a user to enter their email address. When you would like to send an email to the address they entered, variables must be used. | ||
6 | |||
7 | == Using variables == | ||
8 | |||
9 | {{figure image="1_en_VariablesEmail.png" group="platzhalter"}} | ||
10 | Symbol for opening a variable selection on an option field and a text field as it is used inside the action type E-mail. | ||
11 | {{/figure}} | ||
12 | |||
13 | {{figure image="2_en_Variables.png" group="platzhalter"}} | ||
14 | The variable selection menu. Here you can select the form field whose value is to be used. | ||
15 | {{/figure}} | ||
16 | |||
17 | === Using variables for actions === | ||
18 | |||
19 | Form fields can be selected by clicking on the variable icon to the right of each action setting supporting variables. | ||
20 | |||
21 | === Using variables for templates === | ||
22 | |||
23 | {{figure image="3_en_VariablesTemplates.png" group="platzhalter"}} | ||
24 | Variables may be used for templates as well. The button //Variables// at the bottom opens the variable selection menu. | ||
25 | {{/figure}} | ||
26 | |||
27 | The variable selection menu can be opened either by clicking the button the the right hand side of the template editor or by pressing //Ctrl// + //Space//. | ||
28 | |||
29 | == Variable types == | ||
30 | |||
31 | {{id name="sec_form_placeholder"/}} | ||
32 | |||
33 | === Form elements === | ||
34 | |||
35 | {{panel monospace="true" title="Syntax"}} | ||
36 | [%<FormFieldName>%] | ||
37 | {{/panel}} | ||
38 | |||
39 | This variable takes the value of the form field with the specified name. They are used mainly for actions such as [[Email>>doc:Formcycle.Designer.Workflow.Actions.EMail]], [[Create text file>>doc:Formcycle.Designer.Workflow.Actions.CreateTextFile]], [[Database query>>doc:Formcycle.Designer.Workflow.Actions.SQLStatement]] as well as for [[Templates>>doc:Formcycle.Designer.Workflow.Actions.HtmlResponsePage]]. | ||
40 | |||
41 | Example: The variable {{code language="none"}}[%tfEmail%]{{/code}} will take the value of the [[input field>>doc:Formcycle.Designer.Form.FormElements.Input]] named //tfEmail//. | ||
42 | |||
43 | === Question element variables === | ||
44 | |||
45 | To access the values of [[select elements>>doc:Formcycle.Designer.Form.FormElements.Selection]] displayed as questions, you can use the following variables. Assume the select element is named //sel1//, has got 3 questions Q1, Q2, Q3 and 3 answers A1, A2, A3, and also assume these answers are selected: | ||
46 | |||
47 | {{table}} | ||
48 | |= - |= A1 |= A2 |= A3 | ||
49 | |Q1|☑|☐|☐ | ||
50 | |Q2|☑|☑|☐ | ||
51 | |Q3|☑|☑|☑ | ||
52 | {{/table}} | ||
53 | |||
54 | Then: | ||
55 | |||
56 | * //[%sel1%]// resolves to //A1;A1,A2;A1,A2,A3// | ||
57 | * //[%sel1_0%]// resolves to //A1//, //[%sel1_1%]// resolves to //A1,A2//, and //[%sel1_2%]// resolves to //A1,A2,A3// | ||
58 | |||
59 | === Special form elements === | ||
60 | |||
61 | There are some special variables available: | ||
62 | |||
63 | ; [%xf-action%] | ||
64 | : The name of the button used for submitting the form. Could be used to execute an action in the workflow only when a certain button was used (by adding an appropriate condition to the action). | ||
65 | ; [%lang%] | ||
66 | : Refers to the language of the form when it was filled out, eg. //de//, //de-CH//, //en//, or //fr-FR//. | ||
67 | |||
68 | === System variables === | ||
69 | |||
70 | {{id name="system"/}} | ||
71 | |||
72 | {{panel monospace="true" title="Syntax"}} | ||
73 | [%$<Name>%] | ||
74 | {{/panel}} | ||
75 | |||
76 | System variables take the value of the corresponding system value. The following system variables are available for actions and templates: | ||
77 | |||
78 | ; [%$CLIENT_ID%] | ||
79 | : The client ID of the client of the current form. | ||
80 | ; [%$DEFAULT_MAIL_SENDER%] {{version major="7" minor="3"}}{{/version}} | ||
81 | : Returns the e-mail sender (system) for the configured mail server. If a separate mail server is configured under Client > Settings, these configuration will be used, otherwise the system e-mail server. | ||
82 | ; [%$DEFAULT_MAIL_SENDERNAME%] {{version major="7" minor="3"}}{{/version}} | ||
83 | : Returns the sender name (system) for the configured mail server. If this is not configured, an empty string is returned. | ||
84 | ; [%$FORM_LINK%] | ||
85 | : The URL of the current form. | ||
86 | ; [%$FORM_PROCESS_LINK%] | ||
87 | : The URL of the current form for the current process. | ||
88 | ; [%$FORM_VERIFY_LINK%] | ||
89 | : The URL to confirm Double opt in. Can only be used once. | ||
90 | ; [%$FORM_INBOX_NAME%] | ||
91 | : Returns the inbox name the form record currently resides in. | ||
92 | ; [%$FORM_INBOX_LINK%] | ||
93 | : Returns the inbox link the form record currently resides in. | ||
94 | ; [%$FORM_INVITE_LINK%] | ||
95 | : Returns the invitation link of the form. | ||
96 | ; [%$FORM_HISTORY_HTML%] {{version major="7" minor="2" patch="0"/}} | ||
97 | : Returns the the history of a form record as (HTML) table. | ||
98 | ; [%$PROCESS_ID%] | ||
99 | : The current process ID of the form record. | ||
100 | ; [%$PROJECT_ALIAS%] | ||
101 | : The alias of the current form. | ||
102 | ; [%$PROJECT_ID%] | ||
103 | : The form ID of the current form. | ||
104 | ; [%$PROJECT_TITLE%] | ||
105 | : As of version 7, [%$PROJECT_NAME%] is now called [%$PROJECT_TITLE%] . | ||
106 | : The title of the current form. | ||
107 | ; [%$RECORD_ID%] | ||
108 | : The ID of the current form record. | ||
109 | ; [%$RECORD_READ%] | ||
110 | : Whether the current form record was read. Evaluated as a Boolean, i.e. true or false. | ||
111 | ; [%$RECORD_UNREAD%] | ||
112 | : Whether the current form record was not read. Evaluated as a Boolean, i.e. true or false. | ||
113 | ; [%$RECORD_ATTR.<customAttrKey>%] | ||
114 | : Read user-defined form record attributes (e.g. [%$RECORD_ATTR.loopCount%]). This allows values to be stored on the form record and accessed in any action. | ||
115 | ; [%$SOURCE_SERVER%] | ||
116 | : The name of the server that has provided the current form, either the name of the {{fserver/}} or the local server. | ||
117 | ; [%$SOURCE_SERVER_URL%] | ||
118 | : The URL of the server that has provided the current form, either the name of the {{fserver/}} or the local server. | ||
119 | ; [%$STATUS_ID%] | ||
120 | : The ID of the current state. | ||
121 | ; [%$STATUS_NAME%] | ||
122 | : The name of the current state. | ||
123 | ; [%$STATUS_TYPE%] | ||
124 | : The type of the current state. These four values are possible: //RECEIVED// , //SAVED//, //ERROR// and //CUSTOM// (Custom status created by user). | ||
125 | ; [%$TRIGGER.actionName%] | ||
126 | : The name of the action of the providing event. | ||
127 | ; [%$TRIGGER.taskName%] | ||
128 | : The name of the task where the action of the event is located. | ||
129 | ; [%$TRIGGER.triggerName%] | ||
130 | : The name of the event where the action of the event is located. | ||
131 | ; [%$COUNTER_CLIENT.<name of the counter>%] | ||
132 | : The current value of a client [[counter>>doc:Formcycle.UserInterface.Data.Counter]]. | ||
133 | |||
134 | ==== System variables with parameters ==== | ||
135 | |||
136 | {{panel monospace="true" title="Syntax"}} | ||
137 | [%$<Name>(<Parameter>...)%] | ||
138 | {{/panel}} | ||
139 | |||
140 | ; [%$DATE("<format>", <lang>)%] | ||
141 | : Current date. The parameters are optional. When no parameter is specified, the date will be returned in default format. You can specify a custom date format with the first parameter, see the [[java.text.SimpleDateFormat>>https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html]] for more info on the date format string. The second parameter specifies the language, which affects the names of weekdays and months. Example: {{code language="none"}}[%$DATE("yyyy/MM/dd", en-GB)%]{{/code}} | ||
142 | ; [%$FORM_DATE_CREATED("<format>", <lang>)%] | ||
143 | : Creation date of the form record. The parameters are optional. When no parameter is specified, the date will be returned in default format. You can specify a custom date format with the first parameter, see the [[java.text.SimpleDateFormat>>https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html]] for more info on the date format string. The second parameter specifies the language, which affects the names of weekdays and months. Example: {{code language="none"}}[%$FORM_DATE_CREATED("yyyy/MM/dd", en-GB)%]{{/code}} | ||
144 | ; [%$FORM_DATE_MODIFIED("<format>", <lang>)%] | ||
145 | : Available with FORMCYCLE version 6.0.5~{~{/info}} Last change date of the form record. The parameters are optional. When no parameter is specified, the date will be returned in default format. You can specify a custom date format with the first parameter, see the [[java.text.SimpleDateFormat>>https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html]] for more info on the date format string. The second parameter specifies the language, which affects the names of weekdays and months. Example: {{code language="none"}}[%$FORM_DATE_MODIFIED("yyyy/MM/dd", en-GB)%]{{/code}} | ||
146 | |||
147 | {{id name="sec_user_variables"/}} | ||
148 | |||
149 | === User variables === | ||
150 | |||
151 | {{id name="fig_prefill_user_variables"/}} | ||
152 | {{figure image="prefill_user_variables_en.png"}}Using user variables to prefill form fields with data of the logged in user.{{/figure}} | ||
153 | |||
154 | |||
155 | {{html wiki="true"}} | ||
156 | <div class='xm-figure xm-float-right xm-clear-h2' data-alt='Using user variables to prefill form fields with data of the logged in user.'><div class='xm-figure-inner' style='width:310px'>{{lightbox image='prefill_user_variables_en.png' width='300' group='$height' group='$group' title='Using user variables to prefill form fields with data of the logged in user.'/}}<div class='xm-figure-caption'>Using user variables to prefill form fields with data of the logged in user.</div></div></div> | ||
157 | {{/html}} | ||
158 | |||
159 | |||
160 | |||
161 | {{html wiki="true"}} | ||
162 | <div class='xm-figure xm-float-right xm-clear-h2' data-alt='Using user variables to prefill form fields with data of the logged in user.'><div class='xm-figure-inner' style='width:310px'>{{lightbox image='prefill_user_variables_en.png' width='300' group='$height' group='$group' title='Using user variables to prefill form fields with data of the logged in user.'/}}<div class='xm-figure-caption'>Using user variables to prefill form fields with data of the logged in user.</div></div></div> | ||
163 | {{/html}} | ||
164 | |||
165 | |||
166 | |||
167 | {{html wiki="true"}} | ||
168 | <div class='xm-figure xm-float-right xm-clear-h2' data-alt='Using user variables to prefill form fields with data of the logged in user.'><div class='xm-figure-inner' style='width:310px'>{{lightbox image='prefill_user_variables_en.png' width='300' group='$height' group='$group' title='Using user variables to prefill form fields with data of the logged in user.'/}}<div class='xm-figure-caption'>Using user variables to prefill form fields with data of the logged in user.</div></div></div> | ||
169 | {{/html}} | ||
170 | |||
171 | |||
172 | |||
173 | {{html wiki="true"}} | ||
174 | <div class='xm-figure xm-float-right xm-clear-h2' data-alt='Using user variables to prefill form fields with data of the logged in user.'><div class='xm-figure-inner' style='width:310px'>{{lightbox image='prefill_user_variables_en.png' width='300' group='$height' group='$group' title='Using user variables to prefill form fields with data of the logged in user.'/}}<div class='xm-figure-caption'>Using user variables to prefill form fields with data of the logged in user.</div></div></div> | ||
175 | {{/html}} | ||
176 | |||
177 | |||
178 | |||
179 | {{html wiki="true"}} | ||
180 | <div class='xm-figure xm-float-right xm-clear-h2' data-alt='Using user variables to prefill form fields with data of the logged in user.'><div class='xm-figure-inner' style='width:310px'>{{lightbox image='prefill_user_variables_en.png' width='300' group='$height' group='$group' title='Using user variables to prefill form fields with data of the logged in user.'/}}<div class='xm-figure-caption'>Using user variables to prefill form fields with data of the logged in user.</div></div></div> | ||
181 | {{/html}} | ||
182 | |||
183 | |||
184 | User variables may be used in [[actions>>doc:Formcycle.Designer.Workflow.Actions.WebHome]], [[templates>>doc:Formcycle.UserInterface.FilesAndTemplates.WebHome]], [[data base queries>>Formcycle.UserInterface.Data.DBQueries]] or directly in [[form elements>>Formcycle.Designer.Form.FormElements.WebHome]] for prefilling the form (see [[figure>>||anchor="fig_prefill_user_variables"]]). | ||
185 | |||
186 | {{panel monospace="true" title="Syntax"}} | ||
187 | [%$<user object>.<attribute>%] | ||
188 | {{/panel}} | ||
189 | |||
190 | There are three user objects available which can be used to access information about the user (user profile). If a user variable is being used without any attributes (e.g. [%$USER%]), all user information will be returned in [[JSON>>https://de.wikipedia.org/wiki/JavaScript_Object_Notation]] format. | ||
191 | |||
192 | For sensible use of the user variables it is necessary to enable [[form login>>doc:Formcycle.UserInterface.MyForms.Access||anchor="form_login"]]. If this is not configured the user object will be set to an anonymous user. | ||
193 | |||
194 | |||
195 | ==== User objects ==== | ||
196 | |||
197 | ; [%$USER%] | ||
198 | : User object for accessing the current user. | ||
199 | |||
200 | ; [%$LAST_USER%] | ||
201 | : User object for accessing the last user. | ||
202 | |||
203 | ; [%$INITIAL_USER%] | ||
204 | : User object for accessing the user that submitted the form. | ||
205 | |||
206 | ==== Attributes ==== | ||
207 | |||
208 | Using attributes on user objects permits access to specific user information. The following attributes are available for all users but may not always have a value. If the attribute contains a value depends on the [[authenticator>>doc:Formcycle.UserInterface.UserSettings.ExternalUsers.WebHome]] being used for logging into the form. | ||
209 | |||
210 | Example: The user variable **[%$USER.mail%]** returns the email address of the user that has logged into the form. | ||
211 | |||
212 | ; authTypeId | ||
213 | : ID of the [[authenticator>>doc:Formcycle.UserInterface.UserSettings.ExternalUsers.WebHome]] the user chose for login. | ||
214 | ; displayName | ||
215 | : Display name of the user | ||
216 | ; familyName | ||
217 | : Family name of the user | ||
218 | ; firstName | ||
219 | : First name of the user | ||
220 | ; gender | ||
221 | : Gender of the user | ||
222 | ; groups | ||
223 | : Group names of the user | ||
224 | ; id | ||
225 | : ID of the user. (system ID for FORMCYCLE users) | ||
226 | ; linkedId | ||
227 | : A user profile may have a linked identifier, which is the identifier of another user profile. | ||
228 | ; locale | ||
229 | : Language of the user | ||
230 | ; location | ||
231 | : Location of the user | ||
232 | |||
233 | : email address of the user | ||
234 | ; phone | ||
235 | : phone number of the user | ||
236 | ; pictureUrl | ||
237 | : URL to the profile picture of the user | ||
238 | ; profileUrl | ||
239 | : URL to the profile of the user | ||
240 | ; rawData | ||
241 | : All the information about the user in a [[JSON>>https://de.wikipedia.org/wiki/JavaScript_Object_Notation]] format. Depending on the chosen authenticator, the raw data may include additional information about the user that can otherwise not be accessed through attributes. | ||
242 | ; role | ||
243 | : Role of the user | ||
244 | ; title | ||
245 | : Title of the user | ||
246 | ; typedId | ||
247 | : Type of the [[authenticator>>doc:Formcycle.UserInterface.UserSettings.ExternalUsers.WebHome]] the user chose for login. | ||
248 | ; userName | ||
249 | : user name | ||
250 | |||
251 | {{id name="sec_appointment_variables"/}} | ||
252 | |||
253 | === Appointment variables === | ||
254 | |||
255 | Appointment variables can be used when [[appointments>>doc:Formcycle.Designer.Form.FormElements.Appointment.WebHome]] are booked with the form. | ||
256 | |||
257 | {{panel monospace="true" title="Syntax"}} | ||
258 | [%$<Name>%] | ||
259 | {{/panel}} | ||
260 | |||
261 | ; [%$APPOINTMENT_LIST%] | ||
262 | : Creates a summary of the dates booked with the form record in the form of a //ul// HTML list. For each appointment a button is also created, with which the booked appointment can be added to a calendar. This variable is intended for use in HTML templates. | ||
263 | ; [%$APPOINTMENT_LINK%] | ||
264 | : Creates a link to an iCal file that contains all the dates of the form record. | ||
265 | |||
266 | {{id name="sec_system_placeholder_html"/}} | ||
267 | |||
268 | === System variables for HTML templates === | ||
269 | |||
270 | {{panel monospace="true" title="Syntax"}} | ||
271 | [%$<Name>(<Parameter1>,<Parameter2>)%] | ||
272 | {{/panel}} | ||
273 | |||
274 | In addition to the system variables available to both workflow actions and templates, the following variables can be used only in [[HTML templates>>doc:Formcycle.UserInterface.FilesAndTemplates.HTML.WebHome]]. They are used for downloading attachments and are valid for the same browser session that was active when the form was submitted. | ||
275 | |||
276 | ; [%$ATTACHMENT_LIST%] | ||
277 | : Inserts a list with all available attachments that can be downloaded. This will create an //ul// element. | ||
278 | ; [%$ATTACHMENT_ZIP=fileName,linkText%] | ||
279 | : Creates a link for downloading all attachments as a zip archive. Optionally you may specify the parameters //fileName// and //linkText//. The following variations are possible: | ||
280 | :; [%$ATTACHMENT_ZIP=fileName,linkText%] | ||
281 | :: Creates a link with the text //linkText// for downloading all attachements a zip archive that will be named //fileName//. | ||
282 | :; [%$ATTACHMENT_ZIP=fileName%] | ||
283 | :: Creates a link with the text //fileName// for dowloading all attachments a zip file that will be named //fileName//. | ||
284 | :; [%$ATTACHMENT_ZIP%] | ||
285 | :: Creates a link with the text {{code language="none"}}attachment.zip{{/code}} for downloading all attachements as a zip file named {{code language="none"}}attachment.zip{{/code}}. | ||
286 | ; [%$ATTACHMENT=attachmentName,linkText,fileName%] | ||
287 | : Creates a link for downloading a single attachment with the given name that must have been created as part of the workflow processing. The parameters //linkText// and //fileName// are optional, allowing for the following combinations: | ||
288 | :; [%$ATTACHMENT=attachmentName,linkText,fileName%] | ||
289 | :: Creates a link with the text //linkText// for downloading a single attachment with the name //attachmentName// as a file named //fileName//. | ||
290 | :; [%$ATTACHMENT=attachmentName,linkText%] | ||
291 | :: Creates a link with the text //linkText// for an attachment with the name //attachmentName//. | ||
292 | :; [%$ATTACHMENT=attachmentName%] | ||
293 | :: Creates a link for downloading an attachment with the name //attachmentName//. | ||
294 | |||
295 | When the specified attachment does not exist, these variables will not have any effect and will be removed from the rendered HTML template. | ||
296 | |||
297 | === Template variables === | ||
298 | |||
299 | {{panel monospace="true" title="Syntax"}} | ||
300 | [%$$<Name>%] | ||
301 | {{/panel}} | ||
302 | |||
303 | A template variables takes the value of the content of a [[template>>doc:Formcycle.UserInterface.FilesAndTemplates.WebHome]] (for example [[text>>doc:Formcycle.UserInterface.FilesAndTemplates.Text]], [[email>>doc:Formcycle.UserInterface.FilesAndTemplates.Email]], or [[link>>doc:Formcycle.UserInterface.FilesAndTemplates.Link]]) and can be used by workflow action such as [[Email>>doc:Formcycle.Designer.Workflow.Actions.EMail]]. | ||
304 | |||
305 | === Action variables === | ||
306 | |||
307 | {{id name="action"/}} | ||
308 | |||
309 | {{panel monospace="true" title="Syntax"}} | ||
310 | [%$<actionName>.<returnValue>%] | ||
311 | {{/panel}} | ||
312 | |||
313 | Some actions have got return values that can accessed by action variables. | ||
314 | |||
315 | These variables look similar to system variables, but they contain a period as a separator for the action name and the return value. The following action variables are available. | ||
316 | |||
317 | ; [%$<actionName>.SUCCESS%] | ||
318 | : Whether the action could be processed successfully. Evaluates to a boolean, ie. true or false. | ||
319 | ; [%$<actionName>.RESULT%] | ||
320 | : A single return value. Evaluates to a string value. | ||
321 | ; [%$<actionName>.RESULT[<Index>].<Identifier>%] | ||
322 | : Certain actions may return more than one result, corresponding to a //List<Map<String,String>>// in Java. The index and identifier is set by the corresponding action implementation and cannot be changed. This is used mostly by custom plugins when multiple values need to be returned. | ||
323 | |||
324 | The following action variables are __not__ supported in the old workflow: | ||
325 | |||
326 | ; [%$<actionName>.ERROR_CODE%] | ||
327 | : In case of error the thrown error code of the action. | ||
328 | ; [%$<actionName>.ERROR_MESSAGE%] | ||
329 | : In case of error the thrown error message of the action. | ||
330 | |||
331 | In the new workflow, the number of elements of JSON arrays can be queried from variable values with //.length()//, e.g.: **[%$Database query.RESULT.rows.length()%]** | ||
332 | |||
333 | The following action variable is __only__ supported in the old workflow: | ||
334 | |||
335 | ; [%$<actionName>.COUNT%] | ||
336 | : The number of results. Evaluates to an integer value. |