Expression Manager/en - Revision history

FuzzyBot: Updating to match new version of source page

2025-12-02T20:37:26Z

Updating to match new version of source page

← Older revision		Revision as of 22:37, 2 December 2025
Line 2:		Line 2:
	__TOC__		__TOC__

	~~<div class="simplebox"> Note: This feature is only available in LimeSurvey 1.92 or later. </div>~~		=Quick Start Tutorial=

	=Quick Start Tutorial=

	==Overview==		==Overview==
Line 177:		Line 175:
	#*You can hide assessment scores without needing JavaScript or CSS		#*You can hide assessment scores without needing JavaScript or CSS
	#Replacement Fields		#Replacement Fields
	#*~~Instead of using {INSERTANS:SGQA}, you can just use~~ the Question Code - this makes it easier to read and validate.		#*Use the Question Code to insert values from answer to previous questions - this makes it easier to read and validate.
	~~#*This also avoids the common need to edit questions to change the SGQA code to make everything work~~.
	#Tailoring - you can conditionally display text based upon other values		#Tailoring - you can conditionally display text based upon other values
	#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")		#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
Line 189:		Line 186:
	#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question -- available is assesments are enabled for the survey, otherwise always zero		#*.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question -- available is assesments are enabled for the survey, otherwise always zero
	#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant		#*.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant
	#*.shown - the answer as displayed to the user ~~(this is what {INSERTANS:xxx} does)~~		#*.shown - the answer as displayed to the user
	#*.qid - the question ID		#*.qid - the question ID
	#*.gid - the group ID		#*.gid - the group ID
Line 280:		Line 277:
	==Replacements => Micro-Tailoring==		==Replacements => Micro-Tailoring==

	Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {~~INSERTANS:111X3X4~~} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.		Users could tailor some messages and questions based upon prior responses. For example, a question might be, ''{TOKEN:FIRSTNAME}, you said {SPORT.shown} was your favorite sport''. However, it was not possible to do conditional tailoring (like say "Mr." or "Mrs." depending upon the person's gender), or conjugate verbs or decline nouns without fancy JavaScript. Authors could implement surveys that seemed to tailor questions, but it required separate questions for each permutation, and complex conditions to decide which questions to display.

	==Validation==		==Validation==

	Question could be validated with Regular expressions, or minimum/maximum values, or let an ~~SGQA~~ response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.		Question could be validated with Regular expressions, or minimum/maximum values, or let an response serve as the minimum or maximum value. However, validations could not be based upon calculations of other variables without fancy JavaScript.

	==Equations==		==Equations==
Line 475:		Line 472:
	Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:		Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
	*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).		*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (Only for NOT anonymous survey).
	*[[Adding a question#Information_from_previous_answers\|~~INSERTANS:SGQA~~]] - the display value of an answer (e.g. "Yes")~~. For~~ Expression Manager ~~it's the same that using {QCODE.shown}~~.		*[[Adding a question#Information_from_previous_answers\|QCODE.shown]] - the display value of an answer (e.g. "Yes") using Expression Manager.
	*All [[The_template_editor#Keywords\|{XXX} values used by templates]].		*All [[The_template_editor#Keywords\|{XXX} values used by templates]].
	*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question		*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question
Line 1,081:		Line 1,078:
	\|grey text\|\|style='color:#808080; background-color:#eee8aa'\|Sample\|\|string\|\|none\|\|single and double-quoted strings are shown in grey text		\|grey text\|\|style='color:#808080; background-color:#eee8aa'\|Sample\|\|string\|\|none\|\|single and double-quoted strings are shown in grey text
	\|-		\|-
	\|cyan text\|\|style='color:#4169e1; background-color:#eee8aa'\|Sample\|\|variable set on the same page,\|\|<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value\|\|Any variable that is set on the same page to the current question is shown in cyan text, showning it can be updated in javascript. The tooltip shows its name ~~(if you used INSERTANS:xxx) or SGQA code (if you used the new naming system)~~, the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.		\|cyan text\|\|style='color:#4169e1; background-color:#eee8aa'\|Sample\|\|variable set on the same page,\|\|<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value\|\|Any variable that is set on the same page to the current question is shown in cyan text, showning it can be updated in javascript. The tooltip shows its name, the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
	\|-		\|-
	\|green text\|\|style='color:#008000; background-color:#eee8aa'\|Sample\|\|variable set on a prior page\|\|<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value\|\|Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name ~~(if you used INSERTANS:xxx) or SGQA code (if you used the new naming system)~~, the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.		\|green text\|\|style='color:#008000; background-color:#eee8aa'\|Sample\|\|variable set on a prior page\|\|<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value\|\|Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name, the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
	\|-		\|-
	\|bold pink text\|\|style='color:#9370db; background-color:#eee8aa'\|Sample\|\|variable set on a later page <sup>in general : empty at survey start, but can be filled with index or move previous</sup>\|\|<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value\|\|Any variable that is set on a next page is shown in bold pink text. The tooltip shows its name ~~(if you used INSERTANS:xxx) or SGQA code (if you used the new naming system)~~, the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.		\|bold pink text\|\|style='color:#9370db; background-color:#eee8aa'\|Sample\|\|variable set on a later page <sup>in general : empty at survey start, but can be filled with index or move previous</sup>\|\|<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value\|\|Any variable that is set on a next page is shown in bold pink text. The tooltip shows its name, the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
	\|-		\|-
	\|bold tan text\|\|style='color:#a0522d; background-color:#eee8aa'\|Sample\|\|a lime replacement value\|\|the value\|\|Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.		\|bold tan text\|\|style='color:#a0522d; background-color:#eee8aa'\|Sample\|\|a lime replacement value\|\|the value\|\|Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.

FuzzyBot: Updating to match new version of source page

2025-08-05T19:21:15Z

Updating to match new version of source page

← Older revision		Revision as of 21:21, 5 August 2025
Line 548:		Line 548:
	Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:		Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:

	QuestionCode . '_' . ~~SubQuestionID~~ . '_' . ScaleId		QuestionCode . '_' . SubQuestionCode . '_' . ScaleId

			SubQuestion Code & Scale ID need to be used or not, depending on the question type - see table below.
	For '''comment''' and '''other''', question code are QuestionCode_comment and QuestionCode_other		For '''comment''' and '''other''', question code are QuestionCode_comment and QuestionCode_other

FuzzyBot: Updating to match new version of source page

2024-04-02T15:06:18Z

Updating to match new version of source page

← Older revision		Revision as of 17:06, 2 April 2024
Line 434:		Line 434:
	For example <code>Q0.NAOK > "50"</code> is true if Q0.NAOK is a numeric question with 9 as value. This is because the operator <code>></code> will assume it's alphabetical compare and not numerical.		For example <code>Q0.NAOK > "50"</code> is true if Q0.NAOK is a numeric question with 9 as value. This is because the operator <code>></code> will assume it's alphabetical compare and not numerical.

	To be sure to compare integer value, you can use <code>[[Expression_Manager#Implemented_Functions\|intval]](Q0.NAOK) > 50</code>, just remember if Q0.NAOK is not a number (empty or a string), then intval(Q0.NAOK) === 0. To compare string value ("A" < "B") use [[Expression_Manager#Implemented_Functions\|strcmp]] directly : <code>strcmp(Q0.NAOK,"B")</code> or <code>strcmp(Q0.NAOK,"A5")</code>.		To be sure to compare integer value, you can use <code>[[Expression_Manager#Implemented_Functions\|intval]](Q0.NAOK) > 50</code>, just remember if Q0.NAOK is not a number (empty or a string), then intval(Q0.NAOK) == 0. To compare string value ("A" < "B") use [[Expression_Manager#Implemented_Functions\|strcmp]] directly : <code>strcmp(Q0.NAOK,"B")</code> or <code>strcmp(Q0.NAOK,"A5")</code>.

	===Caution about using Assignment Operator (=)===		===Caution about using Assignment Operator (=)===
Line 1,102:		Line 1,102:

	==[[ExpressionScript examples\|Step-by-Step examples]]==		==[[ExpressionScript examples\|Step-by-Step examples]]==

			==[[StatFunctions\|Expression Manager statistic functions]]==

	==[[Expression Manager for developers\|Reference for Developers]]==		==[[Expression Manager for developers\|Reference for Developers]]==

	==[[Expression Manager roadmap\|RoadMap/Status/ToDo List]]==		==[[Expression Manager roadmap\|RoadMap/Status/ToDo List]]==

FuzzyBot: Updating to match new version of source page

2022-06-24T13:38:11Z

Updating to match new version of source page

← Older revision		Revision as of 15:38, 24 June 2022
Line 868:		Line 868:
	\|formatNumber(X,PAT)\|\|return the string value of number X formatted according to Java number format pattern PAT\|\|		\|formatNumber(X,PAT)\|\|return the string value of number X formatted according to Java number format pattern PAT\|\|
	\|-		\|-
	\|getAnsOption(X)\|\|~~returns the text corresponding to the selected option for answer X~~\|\|~~this is the same as X.shown~~		\|getAnsOption(X)\|\| [[ExpressionAnswerOptions\|Core plugin ExpressionAnswerOptions ]] \|\|
	\|-		\|-
	\|getAnsOption(X,Y)\|\|~~returns the text corresponding to the option at index Y of node X~~\|\|		\|getAnsOption(X,Y)\|\| [[ExpressionAnswerOptions\|Core plugin ExpressionAnswerOptions ]] \|\|
	\|-		\|-
	\|getRelevance(X)\|\|returns the relevance equation for question X\|\|		\|getRelevance(X)\|\|returns the relevance equation for question X\|\|

C schmitz: Text replacement - " enclose="div"" to ""

2022-02-16T12:58:45Z

Text replacement - " enclose="div"" to ""

← Older revision		Revision as of 14:58, 16 February 2022
Line 357:		Line 357:
	Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:		Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:

	<syntaxhighlight lang="java~~" enclose="div~~">{if(is_empty(PFTotals),		<syntaxhighlight lang="java">{if(is_empty(PFTotals),
	'',		'',
	if(PFTotals >= -5 && PFTotals <= -4,		if(PFTotals >= -5 && PFTotals <= -4,

FuzzyBot: Updating to match new version of source page

2020-11-28T13:26:10Z

Updating to match new version of source page

Show changes

C schmitz: Text replacement - "Expression Manager" to "ExpressionScript"

2020-02-11T13:45:11Z

Text replacement - "Expression Manager" to "ExpressionScript"

Show changes

C schmitz: Text replacement - "sub-question" to "subquestion"

2018-09-28T10:40:04Z

Text replacement - "sub-question" to "subquestion"

FuzzyBot: Importing a new version from external source

2014-10-15T07:24:30Z

Importing a new version from external source

← Older revision		Revision as of 09:24, 15 October 2014
Line 19:		Line 19:
	==Relevance (Controlling Navigation/Branching)==		==Relevance (Controlling Navigation/Branching)==

	Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses an Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).		Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses a Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).

	This image shows one way to review the relevance logic for a survey. It computes Body Mass Index. The relevance equation is shown in square bracket right after the variable name (which is in green). So, the relevance of weight, weight_units, height and height_units are all 1, meaning that those questions are always asked. However, the relevance for BMI is {!is_empty(height) and !is_empty(weight)}, which means that BMI will only be computed if the subject enters a value for both height and weight (thereby avoiding the risk of a divide by zero error). Also, the Report question is only shown if the subject answers all four main questions (height, height_units, weight, weight_units).		This image shows one way to review the relevance logic for a survey. It computes Body Mass Index. The relevance equation is shown in square bracket right after the variable name (which is in green). So, the relevance of weight, weight_units, height and height_units are all 1, meaning that those questions are always asked. However, the relevance for BMI is {!is_empty(height) and !is_empty(weight)}, which means that BMI will only be computed if the subject enters a value for both height and weight (thereby avoiding the risk of a divide by zero error). Also, the Report question is only shown if the subject answers all four main questions (height, height_units, weight, weight_units).

FuzzyBot: Importing a new version from external source

2014-10-15T07:18:15Z

Importing a new version from external source

← Older revision		Revision as of 09:18, 15 October 2014
Line 461:		Line 461:

	Example and workaround		Example and workaround
	* <code>{if( 1 ,"<strong>",""}information{if( 1 ,"</strong>",""}</code> is broken with XSS security, here you can use <code>{if(1,"<strong>information</strong>","information"}</code>		* <code>{if( 1 ,"<strong>","")}information{if( 1 ,"</strong>","")}</code> is broken with XSS security, here you can use <code>{if(1,"<strong>information</strong>","information")}</code>
	* <code><a href="/script.php?value={if(QCODE == "Y","yes","no")}">next</a></code>, here you can use an equation question because using a complete question code is OK : <code><a href="/script.php?value={EQUATION.NAOK}">next</a></code>		* <code><a href="/script.php?value={if(QCODE == "Y","yes","no")}">next</a></code>, here you can use an equation question because using a complete question code is OK : <code><a href="/script.php?value={EQUATION.NAOK}">next</a></code>

← Older revision		Revision as of 12:40, 28 September 2018
Line 122:		Line 122:
	#'''Relevance''' Equation: A new question attribute controlling question visiblity		#'''Relevance''' Equation: A new question attribute controlling question visiblity
	#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.		#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
	#*Internally, all array_filter and array_filter_exclude commands become ~~sub-question~~-level relevance		#*Internally, all array_filter and array_filter_exclude commands become subquestion-level relevance
	#'''Equation''' Question Type: A new question type that saves calculations or reports to the database		#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
	#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"		#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
	#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+		#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
	#*Stands for Survey-Group-Question-Answer		#*Stands for Survey-Group-Question-Answer
	#*SGQA variable names look like 123X5X382X971, and may have ~~sub-question~~ suffixes.		#*SGQA variable names look like 123X5X382X971, and may have subquestion suffixes.
	#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed		#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
	#'''Question Code''': This is the preferred variable name for EM		#'''Question Code''': This is the preferred variable name for EM
Line 251:		Line 251:
	#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.		#*There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.
	#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)		#*It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)
	#*It also shows the relevance, ~~sub-question~~-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.		#*It also shows the relevance, subquestion-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
	#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)		#*Everything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)
	#*The syntax-highligting supports rapid navigation and editing of the survey.		#*The syntax-highligting supports rapid navigation and editing of the survey.
Line 609:		Line 609:
	==The reserved 'this', 'self', and 'that' variables==		==The reserved 'this', 'self', and 'that' variables==

	Quite often, you want to evalute all parts of a question, such as counting how many ~~sub-questions~~ have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.		Quite often, you want to evalute all parts of a question, such as counting how many subquestions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.

	The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).		The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).
Line 624:		Line 624:
	*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)		*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
	*nocomments - only subquestions that are not comments		*nocomments - only subquestions that are not comments
	*sq_X - where X is a row or column identifier. Only ~~sub-questions~~ matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....		*sq_X - where X is a row or column identifier. Only subquestions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....

	Examples:		Examples:
Line 641:		Line 641:
	*that.''qname''.''sub-selector''.''suffix''		*that.''qname''.''sub-selector''.''suffix''

	''qname'' is the question name without any ~~sub-question~~ extensions. So, say you create a question 'q1', that is its ''qname''		''qname'' is the question name without any subquestion extensions. So, say you create a question 'q1', that is its ''qname''

	Examples:		Examples:
Line 654:		Line 654:
	The one caveat is that when you use the [[Show Logic File\|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'		The one caveat is that when you use the [[Show Logic File\|Show Logic File]] feature, it will show you the expanded value of 'self' and 'that'. This lets you see the actual equation that will be generated so that you (and Expression Manager) can validate that the variables exist. This may seem confusing since you may see quite lenghty equations. However, if you edit the question, you will see the original equation using 'self' and/or 'that'

	Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have ~~sub-questions~~ (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.		Also note that you should not use these variables if (a) you want to explicitly name each variable used in an equation, or (b) use variables that do not have subquestions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

	==Access to Functions==		==Access to Functions==