ExpressionScript Engine - Quick start guide - Revision history

Joffm at 15:13, 19 August 2020

2020-08-19T15:13:58Z

← Older revision		Revision as of 17:13, 19 August 2020
Line 93:		Line 93:

	<!--T:88-->		<!--T:88-->
	Let's focus now on another example - a simple census survey. To download it, click on the following link: [[Media:~~ES survey - Cohabs~~.zip\|Census survey example]].		Let's focus now on another example - a simple census survey. To download it, click on the following link: [[Media:LS3_group_relevance.zip\|Census survey example]].

	<!--T:89-->		<!--T:89-->

Joffm at 14:59, 19 August 2020

2020-08-19T14:59:59Z

← Older revision		Revision as of 16:59, 19 August 2020
Line 46:		Line 46:

	<!--T:76-->		<!--T:76-->
	To better understand the relevance concept, let's focus on the following survey which computes the Body Mass Index (BMI) of survey respondents. To download it, click on the following link: [[Media:~~ES_survey_-_Cohabs~~.zip\|Body Mass Index survey example]].		To better understand the relevance concept, let's focus on the following survey which computes the Body Mass Index (BMI) of survey respondents. To download it, click on the following link: [[Media:LS3_em_tailoring.zip\|Body Mass Index survey example]].

	<!--T:77-->		<!--T:77-->
Line 116:		Line 116:
	<!--T:94-->		<!--T:94-->
	Note that you do not use the curly braces when you enter a relevance equation.		Note that you do not use the curly braces when you enter a relevance equation.


	==Tailoring/Piping== <!--T:95-->		==Tailoring/Piping== <!--T:95-->

Ritapas: Changed reference in last title to ES instead of EM. Updated the link to the presentation, since the original one was broken.

2020-08-13T11:07:46Z

Changed reference in last title to ES instead of EM. Updated the link to the presentation, since the original one was broken.

← Older revision		Revision as of 13:07, 13 August 2020
Line 217:		Line 217:
	The [[ExpressionScript sample surveys\|sample surveys]] page shows many working examples containing a variety of validation expressions.		The [[ExpressionScript sample surveys\|sample surveys]] page shows many working examples containing a variety of validation expressions.

	=~~Expression Manager~~ - presentation= <!--T:122-->		=ExpressionScript - presentation= <!--T:122-->


	<!--T:123-->		<!--T:123-->
	To find out more about ~~the Expression Manager~~ and how you can use different expressions to enhance your survey, please click on the following [https://manual.limesurvey.org/ExpressionScript_-_Presentation link].		To find out more about ExpressionScript and how you can use different expressions to enhance your survey, please click on the following [https://manual.limesurvey.org/ExpressionScript_-_Presentation link].
	</translate>		</translate>

Jugen: Fixed incorrect presentation link

2020-08-13T06:56:12Z

Fixed incorrect presentation link

← Older revision		Revision as of 08:56, 13 August 2020
Line 221:		Line 221:

	<!--T:123-->		<!--T:123-->
	To find out more about the Expression Manager and how you can use different expressions to enhance your survey, please click on the following [https://manual.limesurvey.org/~~Expression_Manager_~~-~~_presentation~~ link].		To find out more about the Expression Manager and how you can use different expressions to enhance your survey, please click on the following [https://manual.limesurvey.org/ExpressionScript_-_Presentation link].
	</translate>		</translate>

C schmitz: Marked this version for translation

2020-03-03T08:09:49Z

Marked this version for translation

Show changes

C schmitz at 08:09, 3 March 2020

2020-03-03T08:09:39Z

← Older revision		Revision as of 10:09, 3 March 2020
Line 1:		Line 1:
	<languages />		<languages />
			<translate>
	__TOC__		__TOC__

Line 171:		Line 171:

	To find out more about the Expression Manager and how you can use different expressions to enhance your survey, please click on the following [https://manual.limesurvey.org/Expression_Manager_-_presentation link].		To find out more about the Expression Manager and how you can use different expressions to enhance your survey, please click on the following [https://manual.limesurvey.org/Expression_Manager_-_presentation link].
			</translate>

C schmitz: C schmitz moved page ExpressionScript Engine - Quick start guide/en to ExpressionScript Engine - Quick start guide without leaving a redirect

2020-03-03T08:07:08Z

C schmitz moved page ExpressionScript Engine - Quick start guide/en to ExpressionScript Engine - Quick start guide without leaving a redirect

← Older revision	Revision as of 10:07, 3 March 2020
(No difference)

FuzzyBot: Updating to match new version of source page

2020-02-11T13:45:05Z

Updating to match new version of source page

FuzzyBot: FuzzyBot moved page Expression Manager - quick start guide/en to ExpressionScript Engine - Quick start guide/en without leaving a redirect: Part of translatable page "Expression Manager - quick start guide"

2020-02-11T13:30:01Z

FuzzyBot moved page Expression Manager - quick start guide/en to ExpressionScript Engine - Quick start guide/en without leaving a redirect: Part of translatable page "Expression Manager - quick start guide"

← Older revision	Revision as of 15:30, 11 February 2020
(No difference)

FuzzyBot: Updating to match new version of source page

2019-03-19T20:05:12Z

Updating to match new version of source page

← Older revision		Revision as of 22:05, 19 March 2019
Line 7:		Line 7:


	Within [https://www.limesurvey.org LimeSurvey], you can further customize your surveys via the usage of the Expression Manager (EM). It can be used to specify the following:		Within [https://www.limesurvey.org LimeSurvey], you can further customize your surveys via the usage of the Expression Manager (EM).
			Sidenote: "EM will be renamed into ExpressionScript (ES). If you read ExpressionScript somewhere, it is just the new name of EM."

			EM can be used to specify the following:

	# '''Navigation/Branching''' - allows a respondent's answers to change the order in which the questions are displayed;		# '''Navigation/Branching''' - allows a respondent's answers to change the order in which the questions are displayed;
	# '''Tailoring/Piping''' - helps you phrase the question (such as referring to prior answers, or conjugating sentences based upon the age or gender of your subjects) or how to generate custom reports (like assessment scores or tailored advice);		# '''Tailoring/Piping''' - helps you phrase the question (such as referring to prior answers, or conjugating sentences based upon the age or gender of your subjects) or how to generate custom reports (like assessment scores or tailored advice);

← Older revision		Revision as of 15:45, 11 February 2020
Line 7:		Line 7:


	Within [https://www.limesurvey.org LimeSurvey], you can further customize your surveys via the usage of the ~~Expression Manager~~ (EM).		Within [https://www.limesurvey.org LimeSurvey], you can further customize your surveys via the usage of the ExpressionScript (short: ES).
	Sidenote: "~~EM will be renamed into~~ ExpressionScript (ES). If you read ~~ExpressionScript~~ somewhere, it is just the ~~new~~ name of EM."		Sidenote: "ExpressionScript was named Expression Manager (EM) in earlier version. If you read Expression Manager somewhere, it is just the old name of ES."

	EM can be used to specify the following:		ES can be used to specify the following:

	# '''Navigation/Branching''' - allows a respondent's answers to change the order in which the questions are displayed;		# '''Navigation/Branching''' - allows a respondent's answers to change the order in which the questions are displayed;
Line 16:		Line 16:
	# '''Validation''' - ensures that answers pass certain criteria, like min and max values or a certain input pattern.		# '''Validation''' - ensures that answers pass certain criteria, like min and max values or a certain input pattern.

	EM provides an intuitive way to specify the logic for each of those features. Nearly anything that you can write as a standard mathematical equation is a valid expression.		ES provides an intuitive way to specify the logic for each of those features. Nearly anything that you can write as a standard mathematical equation is a valid expression.

	EM currently provides access to 70 functions and it can be easily extended to support more. It also lets you access you		ES currently provides access to 70 functions and it can be easily extended to support more. It also lets you access you
	variables using human-readable variable names (rather than [[SGQA_identifier\|SGQA names]]).		variables using human-readable variable names (rather than [[SGQA_identifier\|SGQA names]]).

	The upcoming sections show the main places where the EM is used.		The upcoming sections show the main places where the ES is used.


Line 27:		Line 27:


	Some surveys use "Goto Logic", such that if you answer Question1 with option C, you are redirected to Question5. This approach is very limited since it is hard to validate it. Moreover, it easily breaks when you have to reorder questions. On the other hand, EM uses [https://en.wikipedia.org/wiki/Boolean_algebra Boolean relevance equations] to specify all the conditions under which a question might be valid. If the question is relevant, then the question is shown, otherwise, it is not applicable, and the value "NULL" is stored in the database.		Some surveys use "Goto Logic", such that if you answer Question1 with option C, you are redirected to Question5. This approach is very limited since it is hard to validate it. Moreover, it easily breaks when you have to reorder questions. On the other hand, ES uses [https://en.wikipedia.org/wiki/Boolean_algebra Boolean relevance equations] to specify all the conditions under which a question might be valid. If the question is relevant, then the question is shown, otherwise, it is not applicable, and the value "NULL" is stored in the database.

	<div class='simplebox'> '''Note:''' This is similar to what can be done via the [[Setting conditions\|Conditions editor]], but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA identifiers).</div>		<div class='simplebox'> '''Note:''' This is similar to what can be done via the [[Setting conditions\|Conditions editor]], but ES lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA identifiers).</div>


Line 35:		Line 35:


	To better understand the relevance concept, let's focus on the following survey which computes the Body Mass Index (BMI) of survey respondents. To download it, click on the following link: [[Media:~~EM_survey_~~-_Cohabs.zip\|Body Mass Index survey example]].		To better understand the relevance concept, let's focus on the following survey which computes the Body Mass Index (BMI) of survey respondents. To download it, click on the following link: [[Media:ES_survey_-_Cohabs.zip\|Body Mass Index survey example]].

	The relevance equation is shown below in the '''Relevance''' column after the variable name. The relevance values of weight, weight_units, height, and height_units are all 1 (default value), meaning that those questions are always displayed. 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 getting a zero error). Also, question "Report" is only shown if the respondent answers all four main questions (height, heightunits, weight, weightunits).		The relevance equation is shown below in the '''Relevance''' column after the variable name. The relevance values of weight, weight_units, height, and height_units are all 1 (default value), meaning that those questions are always displayed. 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 getting a zero error). Also, question "Report" is only shown if the respondent answers all four main questions (height, heightunits, weight, weightunits).
Line 72:		Line 72:


	Let's focus now on another example - a simple census survey. To download it, click on the following link: [[Media:EM survey - Cohabs.zip\|Census survey example]].		Let's focus now on another example - a simple census survey. To download it, click on the following link: [[Media:ES survey - Cohabs.zip\|Census survey example]].

	The first page asks how many people live with you and stores that in the "cohabs" variable. This page is only shown if you have more than one cohabitant (it is shown for the second person cohabitating with you). Also, p2name, p2age. p2sum are displayed only if the question before each of them contains a response.		The first page asks how many people live with you and stores that in the "cohabs" variable. This page is only shown if you have more than one cohabitant (it is shown for the second person cohabitating with you). Also, p2name, p2age. p2sum are displayed only if the question before each of them contains a response.
Line 80:		Line 80:


	So, the group also has question-level relevance criteria, such that some questions only appear if you answered certain questions before them (e.g., p2age is displayed if p2name was answered). EM combines the Group and Question-level relevance for you. '''Questions in a group are only asked if the group as a whole is relevant. Then, only the subset of questions within the group that are relevant are asked.'''		So, the group also has question-level relevance criteria, such that some questions only appear if you answered certain questions before them (e.g., p2age is displayed if p2name was answered). ES combines the Group and Question-level relevance for you. '''Questions in a group are only asked if the group as a whole is relevant. Then, only the subset of questions within the group that are relevant are asked.'''

	Here is the screenshot for editing the group-level relevance of ''Cohabitant 2'':		Here is the screenshot for editing the group-level relevance of ''Cohabitant 2'':
Line 94:		Line 94:


	EM lets you easily do simple and complex conditional tailoring. Sometimes you just need a simple substitution, like saying, "You said you purchased <nowiki>[</nowiki>Product]. What did you like best about it?". Sometimes you need conditional substitution like "<nowiki>[</nowiki>Mr./Mrs.] <nowiki>[</nowiki>LastName], would you be willing to complete our survey?". In this case, you want to use "Mr. or Mrs." based on the person's gender. Other times you need even more complex substitution (such as based upon a mathematical computation). EM supports each of these types of tailoring/piping.		ES lets you easily do simple and complex conditional tailoring. Sometimes you just need a simple substitution, like saying, "You said you purchased <nowiki>[</nowiki>Product]. What did you like best about it?". Sometimes you need conditional substitution like "<nowiki>[</nowiki>Mr./Mrs.] <nowiki>[</nowiki>LastName], would you be willing to complete our survey?". In this case, you want to use "Mr. or Mrs." based on the person's gender. Other times you need even more complex substitution (such as based upon a mathematical computation). ES supports each of these types of tailoring/piping.


Line 143:		Line 143:


	Anything within curly braces is treated as an expression, being syntax-highlighted (color coded) in the prior image. If you have any typos (such as misspelled or undefined variable names or functions), EM would show an error. In our below example:		Anything within curly braces is treated as an expression, being syntax-highlighted (color coded) in the prior image. If you have any typos (such as misspelled or undefined variable names or functions), ES would show an error. In our below example:
	* heightunit.shown is an undefined variable name (it is actually heightunits.shown) and		* heightunit.shown is an undefined variable name (it is actually heightunits.shown) and
	* "rnd()" is an undefined function (the proper function name is "round()").		* "rnd()" is an undefined function (the proper function name is "round()").
Line 155:		Line 155:
	You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.		You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

	Please remember that all tailoring must surround expressions with curly braces so that LimeSurvey knows which parts of the question are free text and which should be parsed ~~through Expression Manager~~.		Please remember that all tailoring must surround expressions with curly braces so that LimeSurvey knows which parts of the question are free text and which should be parsed by the ExpressionScript engine.


Line 161:		Line 161:


	EM controls how most of the advanced question options work. These control aspects like min/max numbers of answers, min/max individual values, min/max sum values, and checking that entered values match specified string patterns. Any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.		ES controls how most of the advanced question options work. These control aspects like min/max numbers of answers, min/max individual values, min/max sum values, and checking that entered values match specified string patterns. Any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

	In all of these cases, since the advanced question attribute is always considered an expression, you do not use curly braces when specifying it.		In all of these cases, since the advanced question attribute is always considered an expression, you do not use curly braces when specifying it.

	The [[~~Expression Manager~~ sample surveys\|sample surveys]] page shows many working examples containing a variety of validation expressions.		The [[ExpressionScript sample surveys\|sample surveys]] page shows many working examples containing a variety of validation expressions.

	=Expression Manager - presentation=		=Expression Manager - presentation=