Wiki source code of Platzhalter

Hide last authors

version	line-number	content
1.1	1	{{content/}}
	2
54.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.Designer.Workflow.Actions.WebHome]] and [[data base queries>>Formcycle.UserInterface.Data.DBQueries]].
1.1	4
54.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
54.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
54.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
54.3	17	=== Using variables for actions ===
1.1	18
54.3	19	Form fields can be selected by clicking on the variable icon to the right of each action setting supporting variables.
1.1	20
54.3	21	=== Using variables for templates ===
1.1	22
54.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
54.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
54.3	29	== Variable types ==
1.1	30
	31	{{id name="sec_form_placeholder"/}}
	32
54.3	33	=== Form elements ===
1.1	34
	35	{{panel monospace="true" title="Syntax"}}
54.3	36	[%<FormFieldName>%]
1.1	37	{{/panel}}
	38
54.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.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]].
1.1	40
54.3	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//.
1.1	42
54.3	43	=== Question element variables ===
49.2	44
54.3	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:
49.2	46
	47	{{table}}
	48	\|= - \|= A1 \|= A2 \|= A3
49.4	49	\|Q1\|☑\|☐\|☐
	50	\|Q2\|☑\|☑\|☐
49.3	51	\|Q3\|☑\|☑\|☑
49.2	52	{{/table}}
	53
54.3	54	Then:
49.2	55
54.3	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//
49.2	58
54.3	59	=== Special form elements ===
1.1	60
54.3	61	There are some special variables available:
1.1	62
	63	; [%xf-action%]
54.3	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).
1.1	65	; [%lang%]
54.3	66	: Refers to the language of the form when it was filled out, eg. //de//, //de-CH//, //en//, or //fr-FR//.
1.1	67
54.3	68	=== System variables ===
1.1	69
49.5	70	{{id name="system"/}}
	71
1.1	72	{{panel monospace="true" title="Syntax"}}
	73	[%$<Name>%]
	74	{{/panel}}
	75
54.3	76	System variables take the value of the corresponding system value. The following system variables are available for actions and templates:
1.1	77
	78	; [%$CLIENT_ID%]
54.3	79	: The client ID of the client of the current form.
54.1	80	; [%$DEFAULT_MAIL_SENDER%] {{version major="7" minor="3"}}{{/version}}
54.3	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.
54.1	82	; [%$DEFAULT_MAIL_SENDERNAME%] {{version major="7" minor="3"}}{{/version}}
54.3	83	: Returns the sender name (system) for the configured mail server. If this is not configured, an empty string is returned.
1.1	84	; [%$FORM_LINK%]
54.3	85	: The URL of the current form.
1.1	86	; [%$FORM_PROCESS_LINK%]
54.3	87	: The URL of the current form for the current process.
1.1	88	; [%$FORM_VERIFY_LINK%]
54.3	89	: The URL to confirm Double opt in. Can only be used once.
1.1	90	; [%$FORM_INBOX_NAME%]
54.3	91	: Returns the inbox name the form record currently resides in.
28.1	92	; [%$FORM_INBOX_LINK%]
54.3	93	: Returns the inbox link the form record currently resides in.
29.1	94	; [%$FORM_INVITE_LINK%]
54.3	95	: Returns the invitation link of the form.
52.1	96	; [%$FORM_HISTORY_HTML%] {{version major="7" minor="2" patch="0"/}}
54.3	97	: Returns the the history of a form record as (HTML) table.
1.1	98	; [%$PROCESS_ID%]
54.3	99	: The current process ID of the form record.
1.1	100	; [%$PROJECT_ALIAS%]
54.3	101	: The alias of the current form.
1.1	102	; [%$PROJECT_ID%]
54.3	103	: The form ID of the current form.
31.1	104	; [%$PROJECT_TITLE%]
54.3	105	: As of version 7, [%$PROJECT_NAME%] is now called [%$PROJECT_TITLE%] .
	106	: The title of the current form.
1.1	107	; [%$RECORD_ID%]
54.3	108	: The ID of the current form record.
32.1	109	; [%$RECORD_READ%]
54.3	110	: Whether the current form record was read. Evaluated as a Boolean, i.e. true or false.
32.1	111	; [%$RECORD_UNREAD%]
54.3	112	: Whether the current form record was not read. Evaluated as a Boolean, i.e. true or false.
35.1	113	; [%$RECORD_ATTR.<customAttrKey>%]
54.3	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.
1.1	115	; [%$SOURCE_SERVER%]
54.3	116	: The name of the server that has provided the current form, either the name of the {{fserver/}} or the local server.
1.1	117	; [%$SOURCE_SERVER_URL%]
54.3	118	: The URL of the server that has provided the current form, either the name of the {{fserver/}} or the local server.
1.1	119	; [%$STATUS_ID%]
54.3	120	: The ID of the current state.
1.1	121	; [%$STATUS_NAME%]
54.3	122	: The name of the current state.
36.1	123	; [%$STATUS_TYPE%]
54.3	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]].
1.1	133
54.3	134	==== System variables with parameters ====
1.1	135
	136	{{panel monospace="true" title="Syntax"}}
	137	[%$<Name>(<Parameter>...)%]
	138	{{/panel}}
	139
	140	; [%$DATE("<format>", <lang>)%]
54.3	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}}
1.1	142	; [%$FORM_DATE_CREATED("<format>", <lang>)%]
54.3	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}}
1.1	144	; [%$FORM_DATE_MODIFIED("<format>", <lang>)%]
54.3	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}}
1.1	146
	147	{{id name="sec_user_variables"/}}
	148
54.3	149	=== User variables ===
1.1	150
	151	{{id name="fig_prefill_user_variables"/}}
54.3	152	{{figure image="prefill_user_variables_en.png"}}Using user variables to prefill form fields with data of the logged in user.{{/figure}}
1.1	153
	154
	155	{{html wiki="true"}}
54.3	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>
1.1	157	{{/html}}
	158
	159
	160
	161	{{html wiki="true"}}
54.3	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>
1.1	163	{{/html}}
	164
	165
53.1	166
	167	{{html wiki="true"}}
54.3	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>
53.1	169	{{/html}}
	170
	171
	172
	173	{{html wiki="true"}}
54.3	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>
53.1	175	{{/html}}
	176
	177
	178
	179	{{html wiki="true"}}
54.3	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>
53.1	181	{{/html}}
	182
	183
54.3	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"]]).
54.1	185
1.1	186	{{panel monospace="true" title="Syntax"}}
54.3	187	[%$<user object>.<attribute>%]
1.1	188	{{/panel}}
	189
54.3	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.
1.1	191
54.3	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.
1.1	193
	194
54.3	195	==== User objects ====
	196
1.1	197	; [%$USER%]
54.3	198	: User object for accessing the current user.
1.1	199
	200	; [%$LAST_USER%]
54.3	201	: User object for accessing the last user.
1.1	202
	203	; [%$INITIAL_USER%]
54.3	204	: User object for accessing the user that submitted the form.
1.1	205
54.3	206	==== Attributes ====
1.1	207
54.3	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.
1.1	209
54.3	210	Example: The user variable [%$USER.mail%] returns the email address of the user that has logged into the form.
1.1	211
	212	; authTypeId
54.3	213	: ID of the [[authenticator>>doc:Formcycle.UserInterface.UserSettings.ExternalUsers.WebHome]] the user chose for login.
1.1	214	; displayName
54.3	215	: Display name of the user
1.1	216	; familyName
54.3	217	: Family name of the user
1.1	218	; firstName
54.3	219	: First name of the user
1.1	220	; gender
54.3	221	: Gender of the user
1.1	222	; groups
54.3	223	: Group names of the user
1.1	224	; id
54.3	225	: ID of the user. (system ID for FORMCYCLE users)
1.1	226	; linkedId
54.3	227	: A user profile may have a linked identifier, which is the identifier of another user profile.
1.1	228	; locale
54.3	229	: Language of the user
1.1	230	; location
54.3	231	: Location of the user
1.1	232	; mail
54.3	233	: email address of the user
1.1	234	; phone
54.3	235	: phone number of the user
1.1	236	; pictureUrl
54.3	237	: URL to the profile picture of the user
1.1	238	; profileUrl
54.3	239	: URL to the profile of the user
1.1	240	; rawData
54.3	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.
1.1	242	; role
54.3	243	: Role of the user
1.1	244	; title
54.3	245	: Title of the user
1.1	246	; typedId
54.3	247	: Type of the [[authenticator>>doc:Formcycle.UserInterface.UserSettings.ExternalUsers.WebHome]] the user chose for login.
1.1	248	; userName
54.3	249	: user name
1.1	250
	251	{{id name="sec_appointment_variables"/}}
	252
54.3	253	=== Appointment variables ===
1.1	254
54.3	255	Appointment variables can be used when [[appointments>>doc:Formcycle.Designer.Form.FormElements.Appointment.WebHome]] are booked with the form.
1.1	256
	257	{{panel monospace="true" title="Syntax"}}
	258	[%$<Name>%]
	259	{{/panel}}
	260
	261	; [%$APPOINTMENT_LIST%]
54.3	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.
1.1	263	; [%$APPOINTMENT_LINK%]
54.3	264	: Creates a link to an iCal file that contains all the dates of the form record.
1.1	265
	266	{{id name="sec_system_placeholder_html"/}}
	267
54.3	268	=== System variables for HTML templates ===
1.1	269
	270	{{panel monospace="true" title="Syntax"}}
	271	[%$<Name>(<Parameter1>,<Parameter2>)%]
	272	{{/panel}}
	273
54.3	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.
1.1	275
	276	; [%$ATTACHMENT_LIST%]
54.3	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//.
1.1	284	:; [%$ATTACHMENT_ZIP%]
54.3	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//.
1.1	294
54.3	295	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	296
54.3	297	=== Template variables ===
1.1	298
	299	{{panel monospace="true" title="Syntax"}}
	300	[%$$<Name>%]
	301	{{/panel}}
	302
54.3	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]].
1.1	304
54.3	305	=== Action variables ===
1.1	306
49.5	307	{{id name="action"/}}
48.1	308
1.1	309	{{panel monospace="true" title="Syntax"}}
54.3	310	[%$<actionName>.<returnValue>%]
1.1	311	{{/panel}}
	312
54.3	313	Some actions have got return values that can accessed by action variables.
1.1	314
54.3	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.
1.1	316
54.3	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.
45.1	323
54.3	324	The following action variables are __not__ supported in the old workflow:
45.1	325
54.3	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.
47.2	330
54.3	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()%]
47.6	332
54.3	333	The following action variable is __only__ supported in the old workflow:
47.2	334
54.3	335	; [%$<actionName>.COUNT%]
	336	: The number of results. Evaluates to an integer value.