Wiki source code of Platzhalter
Hide last authors
author | version | line-number | content |
---|---|---|---|
1.1 | 1 | {{content/}} | |
2 | |||
68.3 | 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.UserInterface.MyForms.WorkflowProcessing.Actions.WebHome]] and [[data base queries>>Formcycle.UserInterface.Data.DBQueries.WebHome]]. | |
1.1 | 4 | ||
68.3 | 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. | |
1.1 | 6 | ||
68.3 | 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. | ||
1.1 | 11 | {{/figure}} | |
12 | |||
68.3 | 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. | ||
1.1 | 15 | {{/figure}} | |
16 | |||
68.3 | 17 | === Using variables for actions === | |
1.1 | 18 | ||
68.3 | 19 | Form fields can be selected by clicking on the variable icon to the right of each action setting supporting variables. | |
15.2 | 20 | ||
68.3 | 21 | === Using variables for templates === | |
1.1 | 22 | ||
68.3 | 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. | ||
1.1 | 25 | {{/figure}} | |
26 | |||
68.3 | 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//. | |
1.1 | 28 | ||
68.3 | 29 | == Variable types == | |
1.1 | 30 | ||
68.2 | 31 | {{id name="sec_form_placeholder"/}} | |
68.1 | 32 | ||
68.3 | 33 | === Form elements === | |
1.1 | 34 | ||
35 | {{panel monospace="true" title="Syntax"}} | ||
68.3 | 36 | [%<FormFieldName>%] | |
1.1 | 37 | {{/panel}} | |
38 | |||
68.3 | 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.UserInterface.MyForms.WorkflowProcessing.Actions.EMail]], [[Create text file>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.WriteTextFile]], [[Database query>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.SQLStatement]] as well as for [[Templates>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.ResponsePage]]. | |
1.1 | 40 | ||
68.3 | 41 | Example: The variable {{code language="none"}}[%tfEmail%]{{/code}} will take the value of the [[input field>>doc:Formcycle.FormDesigner.FormElements.Input]] named //tfEmail//. | |
1.1 | 42 | ||
68.3 | 43 | === Special form elements === | |
1.1 | 44 | ||
68.3 | 45 | There are some special variables available: | |
1.1 | 46 | ||
44.12 | 47 | ; [%xf-action%] | |
68.3 | 48 | : 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). | |
44.12 | 49 | ; [%lang%] | |
68.3 | 50 | : Refers to the language of the form when it was filled out, eg. //de//, //de-CH//, //en//, or //fr-FR//. | |
1.1 | 51 | ||
68.3 | 52 | === System variables === | |
1.1 | 53 | ||
54 | {{panel monospace="true" title="Syntax"}} | ||
44.12 | 55 | [%$<Name>%] | |
1.1 | 56 | {{/panel}} | |
57 | |||
68.3 | 58 | System variables take the value of the corresponding system value. The following system variables are available for actions and templates: | |
1.1 | 59 | ||
44.8 | 60 | ; [%$CLIENT_ID%] | |
68.3 | 61 | : The client ID of the client of the current form. | |
44.8 | 62 | ; [%$FORM_LINK%] | |
68.3 | 63 | : The URL of the current form. | |
44.8 | 64 | ; [%$FORM_PROCESS_LINK%] | |
68.3 | 65 | : The URL of the current form for the current process. | |
44.8 | 66 | ; [%$FORM_VERIFY_LINK%] | |
68.3 | 67 | : The URL to confirm Double opt in. Can only be used once. | |
44.8 | 68 | ; [%$FORM_INBOX_NAME%] | |
68.3 | 69 | : {{version major="6" minor="1"/}}Returns the inbox name the form record currently resides in. | |
44.8 | 70 | ; [%$PROCESS_ID%] | |
68.3 | 71 | : The current process ID of the form record. | |
72 | ; [%$PROJECT_ALIAS%]"}} | ||
73 | : The alias of the current form. | ||
44.8 | 74 | ; [%$PROJECT_ID%] | |
68.3 | 75 | : The form ID of the current form. | |
44.8 | 76 | ; [%$PROJECT_NAME%] | |
68.3 | 77 | : The name of the current form. | |
44.8 | 78 | ; [%$RECORD_ID%] | |
68.3 | 79 | : The ID of the current form record. | |
44.8 | 80 | ; [%$SOURCE_SERVER%] | |
68.3 | 81 | : The name of the server that has provided the current form, either the name of the {{fserver/}} or the local server. | |
44.8 | 82 | ; [%$SOURCE_SERVER_URL%] | |
68.3 | 83 | : The URL of the server that has provided the current form, either the name of the {{fserver/}} or the local server. | |
44.8 | 84 | ; [%$STATUS_ID%] | |
68.3 | 85 | : The ID of the current state. | |
44.8 | 86 | ; [%$STATUS_NAME%] | |
68.3 | 87 | : The name of the current state. | |
1.1 | 88 | ||
68.3 | 89 | ==== System variables with parameters ==== | |
52.1 | 90 | ||
91 | {{panel monospace="true" title="Syntax"}} | ||
92 | [%$<Name>(<Parameter>...)%] | ||
93 | {{/panel}} | ||
94 | |||
95 | ; [%$DATE("<format>", <lang>)%] | ||
68.3 | 96 | : {{version major="6" minor="0" patch="5"/}} 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}} | |
52.1 | 97 | ; [%$FORM_DATE_CREATED("<format>", <lang>)%] | |
68.3 | 98 | : {{version major="6" minor="0" patch="5"/}} 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}} | |
52.1 | 99 | ; [%$FORM_DATE_MODIFIED("<format>", <lang>)%] | |
68.3 | 100 | : {{version major="6" minor="0" patch="5"/}} 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}} | |
52.1 | 101 | ||
68.1 | 102 | {{id name="sec_user_variables"/}} | |
53.4 | 103 | ||
68.3 | 104 | === User variables {{version major="6" minor="4" patch="0"/}} === | |
52.1 | 105 | ||
59.2 | 106 | {{id name="fig_prefill_user_variables"/}} | |
68.3 | 107 | {{figure image="prefill_user_variables_en.png"}}Using user variables to prefill form fields with data of the logged in user.{{/figure}} | |
59.2 | 108 | ||
68.1 | 109 | ||
110 | {{html wiki="true"}} | ||
68.3 | 111 | <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> | |
68.1 | 112 | {{/html}} | |
113 | |||
114 | |||
68.3 | 115 | User variables may be used in [[actions>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.WebHome]], [[templates>>doc:Formcycle.UserInterface.FilesAndTemplates.WebHome]], [[data base queries>>Formcycle.UserInterface.Data.DBQueries.WebHome]] or directly in [[form elements>>Formcycle.FormDesigner.FormElements.WebHome]] for prefilling the form (see [[figure>>||anchor="fig_prefill_user_variables"]]). | |
54.1 | 116 | ||
45.2 | 117 | {{panel monospace="true" title="Syntax"}} | |
68.3 | 118 | [%$<user object>.<attribute>%] | |
45.2 | 119 | {{/panel}} | |
45.1 | 120 | ||
68.3 | 121 | 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. | |
48.1 | 122 | ||
68.3 | 123 | For sensible use of the user variables it is necessary to enable [[form login>>doc:Formcycle.UserInterface.MyForms.Access.WebHome||anchor="form_login"]]. If this is not configured the user object will be set to an anonymous user. | |
49.1 | 124 | ||
45.1 | 125 | ||
68.3 | 126 | ==== User objects ==== | |
127 | |||
46.2 | 128 | ; [%$USER%] | |
68.3 | 129 | : User object for accessing the current user. | |
46.2 | 130 | ||
131 | ; [%$LAST_USER%] | ||
68.3 | 132 | : User object for accessing the last user. | |
46.2 | 133 | ||
134 | ; [%$INITIAL_USER%] | ||
68.3 | 135 | : User object for accessing the user that submitted the form. | |
46.2 | 136 | ||
68.3 | 137 | ==== Attributes ==== | |
48.1 | 138 | ||
68.3 | 139 | 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. | |
49.1 | 140 | ||
68.3 | 141 | Example: The user variable **[%$USER.mail%]** returns the email address of the user that has logged into the form. | |
51.1 | 142 | ||
143 | ; authTypeId | ||
68.3 | 144 | : ID of the [[authenticator>>doc:Formcycle.UserInterface.UserSettings.ExternalUsers.WebHome]] the user chose for login. | |
51.1 | 145 | ; displayName | |
68.3 | 146 | : Display name of the user | |
51.1 | 147 | ; familyName | |
68.3 | 148 | : Family name of the user | |
57.1 | 149 | ; firstName | |
68.3 | 150 | : First name of the user | |
51.1 | 151 | ; gender | |
68.3 | 152 | : Gender of the user | |
51.1 | 153 | ; groups | |
68.3 | 154 | : Group names of the user | |
51.1 | 155 | ; id | |
68.3 | 156 | : ID of the user. (system ID for FORMCYCLE users) | |
51.1 | 157 | ; linkedId | |
68.3 | 158 | : A user profile may have a linked identifier, which is the identifier of another user profile. | |
51.1 | 159 | ; locale | |
68.3 | 160 | : Language of the user | |
51.1 | 161 | ; location | |
68.3 | 162 | : Location of the user | |
51.1 | 163 | ||
68.3 | 164 | : email address of the user | |
51.1 | 165 | ; phone | |
68.3 | 166 | : phone number of the user | |
51.1 | 167 | ; pictureUrl | |
68.3 | 168 | : URL to the profile picture of the user | |
51.1 | 169 | ; profileUrl | |
68.3 | 170 | : URL to the profile of the user | |
51.1 | 171 | ; rawData | |
68.3 | 172 | : 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. | |
51.1 | 173 | ; role | |
68.3 | 174 | : Role of the user | |
51.1 | 175 | ; title | |
68.3 | 176 | : Title of the user | |
51.1 | 177 | ; typedId | |
68.3 | 178 | : Type of the [[authenticator>>doc:Formcycle.UserInterface.UserSettings.ExternalUsers.WebHome]] the user chose for login. | |
51.1 | 179 | ; userName | |
68.3 | 180 | : user name | |
51.1 | 181 | ||
68.1 | 182 | {{id name="sec_appointment_variables"/}} | |
183 | |||
68.3 | 184 | === Appointment variables {{version major="6" minor="5" patch="0"/}} === | |
64.1 | 185 | ||
68.3 | 186 | Appointment variables can be used when [[appointments>>doc:Formcycle.FormDesigner.FormElements.Appointment.WebHome]] are booked with the form. | |
67.1 | 187 | ||
66.1 | 188 | {{panel monospace="true" title="Syntax"}} | |
189 | [%$<Name>%] | ||
190 | {{/panel}} | ||
191 | |||
64.1 | 192 | ; [%$APPOINTMENT_LIST%] | |
68.3 | 193 | : 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. | |
64.1 | 194 | ; [%$APPOINTMENT_LINK%] | |
68.3 | 195 | : Creates a link to an iCal file that contains all the dates of the form record. | |
64.1 | 196 | ||
68.2 | 197 | {{id name="sec_system_placeholder_html"/}} | |
68.1 | 198 | ||
68.3 | 199 | === System variables for HTML templates === | |
1.1 | 200 | ||
201 | {{panel monospace="true" title="Syntax"}} | ||
44.11 | 202 | [%$<Name>(<Parameter1>,<Parameter2>)%] | |
1.1 | 203 | {{/panel}} | |
204 | |||
68.3 | 205 | 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. | |
1.1 | 206 | ||
44.11 | 207 | ; [%$ATTACHMENT_LIST%] | |
68.3 | 208 | : Inserts a list with all available attachments that can be downloaded. This will create an //ul// element. | |
209 | ; [%$ATTACHMENT_ZIP=fileName,linkText%] | ||
210 | : 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: | ||
211 | :; [%$ATTACHMENT_ZIP=fileName,linkText%] | ||
212 | :: Creates a link with the text //linkText// for downloading all attachements a zip archive that will be named //fileName//. | ||
213 | :; [%$ATTACHMENT_ZIP=fileName%] | ||
214 | :: Creates a link with the text //fileName// for dowloading all attachments a zip file that will be named //fileName//. | ||
44.11 | 215 | :; [%$ATTACHMENT_ZIP%] | |
68.3 | 216 | :: 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}}. | |
217 | ; [%$ATTACHMENT=attachmentName,linkText,fileName%] | ||
218 | : 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: | ||
219 | :; [%$ATTACHMENT=attachmentName,linkText,fileName%] | ||
220 | :: Creates a link with the text //linkText// for downloading a single attachment with the name //attachmentName// as a file named //fileName//. | ||
221 | :; [%$ATTACHMENT=attachmentName,linkText%] | ||
222 | :: Creates a link with the text //linkText// for an attachment with the name //attachmentName//. | ||
223 | :; [%$ATTACHMENT=attachmentName%] | ||
224 | :: Creates a link for downloading an attachment with the name //attachmentName//. | ||
1.1 | 225 | ||
68.3 | 226 | When the specified attachment does not exist, these variables will not have any effect and will be removed from the rendered HTML template. | |
1.1 | 227 | ||
68.3 | 228 | === Template variables === | |
1.1 | 229 | ||
230 | {{panel monospace="true" title="Syntax"}} | ||
44.11 | 231 | [%$$<Name>%] | |
1.1 | 232 | {{/panel}} | |
233 | |||
68.3 | 234 | 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.UserInterface.MyForms.WorkflowProcessing.Actions.EMail]]. | |
1.1 | 235 | ||
68.3 | 236 | === Action variables === | |
1.1 | 237 | ||
238 | {{panel monospace="true" title="Syntax"}} | ||
68.3 | 239 | [%$<actionName>.<returnValue>%] | |
1.1 | 240 | {{/panel}} | |
241 | |||
68.3 | 242 | Some actions have got return values that can accessed by action variables. | |
1.1 | 243 | ||
68.3 | 244 | 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. | |
1.1 | 245 | ||
68.3 | 246 | ; [%$<actionName>.SUCCESS%] | |
247 | : Whether the action could be processed successfully. Evaluates to a boolean, ie. true or false. | ||
248 | ; [%$<actionName>.COUNT%] | ||
249 | : The number of results. Evaluates to an integer value. | ||
250 | ; [%$<actionName>.RESULT%] | ||
251 | : A single return value. Evaluates to a string value. | ||
252 | ; [%$<actionName>.RESULT[<Index>].<Identifier>%] | ||
253 | : 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. |