LimeSurvey Manual - User contributions [en]

Available third party plugins

2026-05-19T11:31:23Z

Mazi: /* Export and statistics plugins */

Some plugins are listed in the [https://account.limesurvey.org/limestore Limestore]. If you have a plugin you would like to share with the world, feel free to add it to this page.

== Authentication plugins ==

* [https://survey-consulting.com/product/extended-auth-ldap-limesurvey-plugin Free Auth LDAP Plugin]
* [https://survey-consulting.com/product/limesurvey-saml-plugin/ SAML SSO Plugin]
* [https://github.com/technowhizz/LimeSurvey-RegDomainRestricter Registration Email Domain Restrictor]
* [http://extensions.sondages.pro/authentification-by-wordpress/ Authentification by WordPress user]
* [https://github.com/univlorraine/limesurvey-cas CAS Authentication plugin for LimeSurvey]
* [https://github.com/atlet/LimeSurvey-ShibbolethAuth LimeSurvey Shibboleth auth plugin]
* [https://framagit.org/Animafac/limesurvey/limesurvey-rememberme LimeSurvey RememberMe plugin]
* [https://github.com/SondagesPro/limesurvey-oauth2 OAuth2 authentication]

== Export and statistics plugins ==

* [https://survey-consulting.com/product/free-limesurvey-reporting-plugin/ Free LimeSurvey Reporting Plugin]: Create live reports for your LimeSurvey data with custom charts and admin notifications. Ideal for automated evaluations and printable summaries.
* [https://survey-consulting.com/product/limesurvey-codebook-plugin/ LimeSurvey Codebook Plugin – Export All Question & Answer Codes]: Generate a complete codebook of your LimeSurvey survey – all question codes, subquestion codes and answer codes on one screen. Export to CSV or JSON instantly.
* [http://extensions.sondages.pro/exportcompleteanswers/ exportCompleteAnswers : Complete New export system allowing export Answer code and answer text in CSV. Options is manageable by super admin.]
* [http://extensions.sondages.pro/triple-s-export/ exportTripleS : export in Triple-S XML2 or XML1.3 format survey structure and data.]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendAdminStatitistics extendAdminStatitistics : rewriting of core statistics, actually put sub question in same table and graph]
* [https://github.com/reportico-web/limesurvey-reportico Reportico Reporting module for LimeSurvey]: generate charts,tables and statistics from survey data
* [https://www.robotspaceship.ai/loesungen/limesurvey-ppt-exporter PowerPoint Export] Export answers to PowerPoint (.pptx) as bar, pie, grouping, matrix, or dual-array charts, including ranking questions and text word clouds.

== Public survey plugins ==
* [https://survey-consulting.com/product/respondent-driven-sampling-rds-limesurvey-plugin/ Respondent Driven Sampling (RDS) Plugin]: Add respondent driven sampling (RDS) to your LimeSurvey setup. Tokens are generated on submit and stored for controlled participant invitations.
* [http://extensions.sondages.pro/hideemptycolumn-for-limesurvey/ hideEmptyColumn : A plugin to add a solution to hide column of array question type with ExpressionScript of LimeSurvey ]
* [http://extensions.sondages.pro/moreaccessibility/ moreAccessibility : some option to add accessibility to public survey] 2.6lts compatible onlmy, deprecated in 3.0
* [https://git.framasoft.org/Shnoulle/addQuestionCodeClass addQuestionCodeClass : add the question code at the question wrapper class]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/radioToStarRating radioToStarRating : set any radio list to star rating system]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/moveSomeAnswers moveSomeAnswers] : If using random_order attribute : allow to always move some answers at end.

== Data editing plugins ==
* [https://survey-consulting.com/product/create-limesurvey-surveys-from-csv/ Copy Survey from CSV plugin]: Enables automated survey duplication based on CSV input – perfect for mass-creating standardized evaluations.
* [https://manual.limesurvey.org/MassAction_Plugin MassAction] : A plugin for faster survey editing by loading questions details into editable cells. Includes a search and replace feature.

== Email plugins ==
* [https://survey-consulting.com/product/automatically-send-email-invitations/ Automatically send email invitations]: Script for automatically sending LimeSurvey email invitations using a cronjob. Allows setting email batch sizes.
* [https://survey-consulting.com/product/automatically-send-email-reminders/ Automatically send email reminders]: Script for automatically sending LimeSurvey email reminders using a cronjob. Helps you [https://survey-consulting.com/how-to-prevent-limesurvey-email-invitations-or-reminders-being-treated-as-spam/ solving spam issues] and working around email sending limits.
* [https://gitlab.com/SondagesPro/mailing/noMailToExample noMailToExample]
* [https://github.com/LimeSurvey/LimeSurvey/blob/develop/plugins/mailSenderToFrom/mailSenderToFrom.php mailSenderToFrom]
* [https://github.com/Xites/LS_mailDKIM mailDKIM]
* [https://github.com/Xites/LS_mailEmbedImages mailEmbedImages]
* [https://github.com/RegioneER/LsRerAntiphishing Anti Phishing Templates] this free software plugin, mandatory alters mail notifications templates, by displaying urls inside email messages.

== Other plugins ==

* [http://extensions.sondages.pro/recomputeexpression-for-limesurvey Recompute Expressions:] A Plugin for LimeSurvey to recompute expression in survey with already submitted survey. Allow to update some relevance too.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/showAdvancedSettings showAdvancedSettings:] Show advanced settings in question edit by default.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/replaceRegister replaceRegisterː] Extra option for Register, starting point for other plugin.
* [http://extensions.sondages.pro/fixmaxstep-for-question-index/ fixMaxStep : Fix question index for token answer persistence survey:] Example of usage : get the complete index when user come back to the survey.
* [http://extensions.sondages.pro/sendmailajax-all-email-in-one/ sendMailAjax : Send token email one by one with ajaxː] Allow to send all email in one click without restriction.
* [http://extensions.sondages.pro/mailing-management/sendmailcron sendMailCron: Automatically send invitations and reminders using cronjobsː] Automatically sends invitations and reminders in custom intervals. Extensive configuration and debugging options
* [https://github.com/SteveCohen/Piwik-for-Limesurvey Piwik-for-Limesurvey Piwik for LimeSurvey]: Plugs Piwik into LimeSurvey, so you can track your survey admin users and respondents.
* [https://github.com/SondagesPro/surveysModel Mark surveys as "Survey Model/Template"ː] Allow admins to mark a survey as "Survey Model", a kind of "master survey" or "survey template" which only users with appropriate rights are allowed to edit. The common user is only allowed to create copies based on such a survey template.
* [https://github.com/SondagesPro/LS-toolsDomDocument toolsDomDocumentː] a tools for anothers plugin
* [https://github.com/TonisOrmisson/limesurvey-url-templates UrlTemplateChangerː] Set respondent's interview template over an URL parameter.
* [https://github.com/evently-nl/zesthook ZestHookː] Makes it possible to send a Post request on every response submission. You can set the URL to post to, as well as several other options.
* [https://github.com/CEric-fr/limesurvey-rgpd Extension RGPD pour LimeSurvey] Each questionnaire owner is able to interact with these conditions of use via a new submenu added in the "questionnaire parameters" entitled: GDPR configuration.
* [https://github.com/projeto-cade-unb/Lime2Camunda Lime2Camunda] Plugin for integration with LimeSurvey with Camunda, which at the end of completing the survey it starts a process instance in Camunda submitting all questions and answers as process variables.
* [https://github.com/librecodecoop/lsTelegramNotify lsTelegramNotify]: Allows you to send after survey completed event to Telegram as text, PDF or CSV.
* [https://github.com/LibreCodeCoop/LSNextcloud LSNextcloud]: Save all survey responses and their attachments automatically to a folder in your Nextcloud.

== Example and demo plugins ==
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendRemoteControl extendRemoteControl] : Show how to add function to [[RemoteControl_2_API]], show how to create a new admin page too (usage of public function actionIndex() )

[[Category:Plugins]]

Available third party plugins

2026-05-19T11:30:28Z

Mazi: /* Public survey plugins */ Fixed list

Some plugins are listed in the [https://account.limesurvey.org/limestore Limestore]. If you have a plugin you would like to share with the world, feel free to add it to this page.

== Authentication plugins ==

* [https://survey-consulting.com/product/extended-auth-ldap-limesurvey-plugin Free Auth LDAP Plugin]
* [https://survey-consulting.com/product/limesurvey-saml-plugin/ SAML SSO Plugin]
* [https://github.com/technowhizz/LimeSurvey-RegDomainRestricter Registration Email Domain Restrictor]
* [http://extensions.sondages.pro/authentification-by-wordpress/ Authentification by WordPress user]
* [https://github.com/univlorraine/limesurvey-cas CAS Authentication plugin for LimeSurvey]
* [https://github.com/atlet/LimeSurvey-ShibbolethAuth LimeSurvey Shibboleth auth plugin]
* [https://framagit.org/Animafac/limesurvey/limesurvey-rememberme LimeSurvey RememberMe plugin]
* [https://github.com/SondagesPro/limesurvey-oauth2 OAuth2 authentication]

== Export and statistics plugins ==

* [https://survey-consulting.com/product/free-limesurvey-reporting-plugin/ Free LimeSurvey Reporting Plugin]: Create live reports for your LimeSurvey data with custom charts and admin notifications. Ideal for automated evaluations and printable summaries.
* [http://extensions.sondages.pro/exportcompleteanswers/ exportCompleteAnswers : Complete New export system allowing export Answer code and answer text in CSV. Options is manageable by super admin.]
* [http://extensions.sondages.pro/triple-s-export/ exportTripleS : export in Triple-S XML2 or XML1.3 format survey structure and data.]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendAdminStatitistics extendAdminStatitistics : rewriting of core statistics, actually put sub question in same table and graph]
* [https://github.com/reportico-web/limesurvey-reportico Reportico Reporting module for LimeSurvey]: generate charts,tables and statistics from survey data
* [https://www.robotspaceship.ai/loesungen/limesurvey-ppt-exporter PowerPoint Export] Export answers to PowerPoint (.pptx) as bar, pie, grouping, matrix, or dual-array charts, including ranking questions and text word clouds.

== Public survey plugins ==
* [https://survey-consulting.com/product/respondent-driven-sampling-rds-limesurvey-plugin/ Respondent Driven Sampling (RDS) Plugin]: Add respondent driven sampling (RDS) to your LimeSurvey setup. Tokens are generated on submit and stored for controlled participant invitations.
* [http://extensions.sondages.pro/hideemptycolumn-for-limesurvey/ hideEmptyColumn : A plugin to add a solution to hide column of array question type with ExpressionScript of LimeSurvey ]
* [http://extensions.sondages.pro/moreaccessibility/ moreAccessibility : some option to add accessibility to public survey] 2.6lts compatible onlmy, deprecated in 3.0
* [https://git.framasoft.org/Shnoulle/addQuestionCodeClass addQuestionCodeClass : add the question code at the question wrapper class]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/radioToStarRating radioToStarRating : set any radio list to star rating system]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/moveSomeAnswers moveSomeAnswers] : If using random_order attribute : allow to always move some answers at end.

== Data editing plugins ==
* [https://survey-consulting.com/product/create-limesurvey-surveys-from-csv/ Copy Survey from CSV plugin]: Enables automated survey duplication based on CSV input – perfect for mass-creating standardized evaluations.
* [https://manual.limesurvey.org/MassAction_Plugin MassAction] : A plugin for faster survey editing by loading questions details into editable cells. Includes a search and replace feature.

== Email plugins ==
* [https://survey-consulting.com/product/automatically-send-email-invitations/ Automatically send email invitations]: Script for automatically sending LimeSurvey email invitations using a cronjob. Allows setting email batch sizes.
* [https://survey-consulting.com/product/automatically-send-email-reminders/ Automatically send email reminders]: Script for automatically sending LimeSurvey email reminders using a cronjob. Helps you [https://survey-consulting.com/how-to-prevent-limesurvey-email-invitations-or-reminders-being-treated-as-spam/ solving spam issues] and working around email sending limits.
* [https://gitlab.com/SondagesPro/mailing/noMailToExample noMailToExample]
* [https://github.com/LimeSurvey/LimeSurvey/blob/develop/plugins/mailSenderToFrom/mailSenderToFrom.php mailSenderToFrom]
* [https://github.com/Xites/LS_mailDKIM mailDKIM]
* [https://github.com/Xites/LS_mailEmbedImages mailEmbedImages]
* [https://github.com/RegioneER/LsRerAntiphishing Anti Phishing Templates] this free software plugin, mandatory alters mail notifications templates, by displaying urls inside email messages.

== Other plugins ==

* [http://extensions.sondages.pro/recomputeexpression-for-limesurvey Recompute Expressions:] A Plugin for LimeSurvey to recompute expression in survey with already submitted survey. Allow to update some relevance too.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/showAdvancedSettings showAdvancedSettings:] Show advanced settings in question edit by default.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/replaceRegister replaceRegisterː] Extra option for Register, starting point for other plugin.
* [http://extensions.sondages.pro/fixmaxstep-for-question-index/ fixMaxStep : Fix question index for token answer persistence survey:] Example of usage : get the complete index when user come back to the survey.
* [http://extensions.sondages.pro/sendmailajax-all-email-in-one/ sendMailAjax : Send token email one by one with ajaxː] Allow to send all email in one click without restriction.
* [http://extensions.sondages.pro/mailing-management/sendmailcron sendMailCron: Automatically send invitations and reminders using cronjobsː] Automatically sends invitations and reminders in custom intervals. Extensive configuration and debugging options
* [https://github.com/SteveCohen/Piwik-for-Limesurvey Piwik-for-Limesurvey Piwik for LimeSurvey]: Plugs Piwik into LimeSurvey, so you can track your survey admin users and respondents.
* [https://github.com/SondagesPro/surveysModel Mark surveys as "Survey Model/Template"ː] Allow admins to mark a survey as "Survey Model", a kind of "master survey" or "survey template" which only users with appropriate rights are allowed to edit. The common user is only allowed to create copies based on such a survey template.
* [https://github.com/SondagesPro/LS-toolsDomDocument toolsDomDocumentː] a tools for anothers plugin
* [https://github.com/TonisOrmisson/limesurvey-url-templates UrlTemplateChangerː] Set respondent's interview template over an URL parameter.
* [https://github.com/evently-nl/zesthook ZestHookː] Makes it possible to send a Post request on every response submission. You can set the URL to post to, as well as several other options.
* [https://github.com/CEric-fr/limesurvey-rgpd Extension RGPD pour LimeSurvey] Each questionnaire owner is able to interact with these conditions of use via a new submenu added in the "questionnaire parameters" entitled: GDPR configuration.
* [https://github.com/projeto-cade-unb/Lime2Camunda Lime2Camunda] Plugin for integration with LimeSurvey with Camunda, which at the end of completing the survey it starts a process instance in Camunda submitting all questions and answers as process variables.
* [https://github.com/librecodecoop/lsTelegramNotify lsTelegramNotify]: Allows you to send after survey completed event to Telegram as text, PDF or CSV.
* [https://github.com/LibreCodeCoop/LSNextcloud LSNextcloud]: Save all survey responses and their attachments automatically to a folder in your Nextcloud.

== Example and demo plugins ==
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendRemoteControl extendRemoteControl] : Show how to add function to [[RemoteControl_2_API]], show how to create a new admin page too (usage of public function actionIndex() )

[[Category:Plugins]]

Available third party plugins

2026-05-19T11:28:57Z

Mazi: /* Email plugins */ Description added

Some plugins are listed in the [https://account.limesurvey.org/limestore Limestore]. If you have a plugin you would like to share with the world, feel free to add it to this page.

== Authentication plugins ==

* [https://survey-consulting.com/product/extended-auth-ldap-limesurvey-plugin Free Auth LDAP Plugin]
* [https://survey-consulting.com/product/limesurvey-saml-plugin/ SAML SSO Plugin]
* [https://github.com/technowhizz/LimeSurvey-RegDomainRestricter Registration Email Domain Restrictor]
* [http://extensions.sondages.pro/authentification-by-wordpress/ Authentification by WordPress user]
* [https://github.com/univlorraine/limesurvey-cas CAS Authentication plugin for LimeSurvey]
* [https://github.com/atlet/LimeSurvey-ShibbolethAuth LimeSurvey Shibboleth auth plugin]
* [https://framagit.org/Animafac/limesurvey/limesurvey-rememberme LimeSurvey RememberMe plugin]
* [https://github.com/SondagesPro/limesurvey-oauth2 OAuth2 authentication]

== Export and statistics plugins ==

* [https://survey-consulting.com/product/free-limesurvey-reporting-plugin/ Free LimeSurvey Reporting Plugin]: Create live reports for your LimeSurvey data with custom charts and admin notifications. Ideal for automated evaluations and printable summaries.
* [http://extensions.sondages.pro/exportcompleteanswers/ exportCompleteAnswers : Complete New export system allowing export Answer code and answer text in CSV. Options is manageable by super admin.]
* [http://extensions.sondages.pro/triple-s-export/ exportTripleS : export in Triple-S XML2 or XML1.3 format survey structure and data.]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendAdminStatitistics extendAdminStatitistics : rewriting of core statistics, actually put sub question in same table and graph]
* [https://github.com/reportico-web/limesurvey-reportico Reportico Reporting module for LimeSurvey]: generate charts,tables and statistics from survey data
* [https://www.robotspaceship.ai/loesungen/limesurvey-ppt-exporter PowerPoint Export] Export answers to PowerPoint (.pptx) as bar, pie, grouping, matrix, or dual-array charts, including ranking questions and text word clouds.

== Public survey plugins ==
~ [https://survey-consulting.com/product/respondent-driven-sampling-rds-limesurvey-plugin/ Respondent Driven Sampling (RDS) Plugin]: Add respondent driven sampling (RDS) to your LimeSurvey setup. Tokens are generated on submit and stored for controlled participant invitations.
* [http://extensions.sondages.pro/hideemptycolumn-for-limesurvey/ hideEmptyColumn : A plugin to add a solution to hide column of array question type with ExpressionScript of LimeSurvey ]
* [http://extensions.sondages.pro/moreaccessibility/ moreAccessibility : some option to add accessibility to public survey] 2.6lts compatible onlmy, deprecated in 3.0
* [https://git.framasoft.org/Shnoulle/addQuestionCodeClass addQuestionCodeClass : add the question code at the question wrapper class]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/radioToStarRating radioToStarRating : set any radio list to star rating system]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/moveSomeAnswers moveSomeAnswers] : If using random_order attribute : allow to always move some answers at end.

== Data editing plugins ==
* [https://survey-consulting.com/product/create-limesurvey-surveys-from-csv/ Copy Survey from CSV plugin]: Enables automated survey duplication based on CSV input – perfect for mass-creating standardized evaluations.
* [https://manual.limesurvey.org/MassAction_Plugin MassAction] : A plugin for faster survey editing by loading questions details into editable cells. Includes a search and replace feature.

== Email plugins ==
* [https://survey-consulting.com/product/automatically-send-email-invitations/ Automatically send email invitations]: Script for automatically sending LimeSurvey email invitations using a cronjob. Allows setting email batch sizes.
* [https://survey-consulting.com/product/automatically-send-email-reminders/ Automatically send email reminders]: Script for automatically sending LimeSurvey email reminders using a cronjob. Helps you [https://survey-consulting.com/how-to-prevent-limesurvey-email-invitations-or-reminders-being-treated-as-spam/ solving spam issues] and working around email sending limits.
* [https://gitlab.com/SondagesPro/mailing/noMailToExample noMailToExample]
* [https://github.com/LimeSurvey/LimeSurvey/blob/develop/plugins/mailSenderToFrom/mailSenderToFrom.php mailSenderToFrom]
* [https://github.com/Xites/LS_mailDKIM mailDKIM]
* [https://github.com/Xites/LS_mailEmbedImages mailEmbedImages]
* [https://github.com/RegioneER/LsRerAntiphishing Anti Phishing Templates] this free software plugin, mandatory alters mail notifications templates, by displaying urls inside email messages.

== Other plugins ==

* [http://extensions.sondages.pro/recomputeexpression-for-limesurvey Recompute Expressions:] A Plugin for LimeSurvey to recompute expression in survey with already submitted survey. Allow to update some relevance too.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/showAdvancedSettings showAdvancedSettings:] Show advanced settings in question edit by default.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/replaceRegister replaceRegisterː] Extra option for Register, starting point for other plugin.
* [http://extensions.sondages.pro/fixmaxstep-for-question-index/ fixMaxStep : Fix question index for token answer persistence survey:] Example of usage : get the complete index when user come back to the survey.
* [http://extensions.sondages.pro/sendmailajax-all-email-in-one/ sendMailAjax : Send token email one by one with ajaxː] Allow to send all email in one click without restriction.
* [http://extensions.sondages.pro/mailing-management/sendmailcron sendMailCron: Automatically send invitations and reminders using cronjobsː] Automatically sends invitations and reminders in custom intervals. Extensive configuration and debugging options
* [https://github.com/SteveCohen/Piwik-for-Limesurvey Piwik-for-Limesurvey Piwik for LimeSurvey]: Plugs Piwik into LimeSurvey, so you can track your survey admin users and respondents.
* [https://github.com/SondagesPro/surveysModel Mark surveys as "Survey Model/Template"ː] Allow admins to mark a survey as "Survey Model", a kind of "master survey" or "survey template" which only users with appropriate rights are allowed to edit. The common user is only allowed to create copies based on such a survey template.
* [https://github.com/SondagesPro/LS-toolsDomDocument toolsDomDocumentː] a tools for anothers plugin
* [https://github.com/TonisOrmisson/limesurvey-url-templates UrlTemplateChangerː] Set respondent's interview template over an URL parameter.
* [https://github.com/evently-nl/zesthook ZestHookː] Makes it possible to send a Post request on every response submission. You can set the URL to post to, as well as several other options.
* [https://github.com/CEric-fr/limesurvey-rgpd Extension RGPD pour LimeSurvey] Each questionnaire owner is able to interact with these conditions of use via a new submenu added in the "questionnaire parameters" entitled: GDPR configuration.
* [https://github.com/projeto-cade-unb/Lime2Camunda Lime2Camunda] Plugin for integration with LimeSurvey with Camunda, which at the end of completing the survey it starts a process instance in Camunda submitting all questions and answers as process variables.
* [https://github.com/librecodecoop/lsTelegramNotify lsTelegramNotify]: Allows you to send after survey completed event to Telegram as text, PDF or CSV.
* [https://github.com/LibreCodeCoop/LSNextcloud LSNextcloud]: Save all survey responses and their attachments automatically to a folder in your Nextcloud.

== Example and demo plugins ==
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendRemoteControl extendRemoteControl] : Show how to add function to [[RemoteControl_2_API]], show how to create a new admin page too (usage of public function actionIndex() )

[[Category:Plugins]]

Available third party plugins

2026-05-19T11:27:53Z

Mazi: /* Email plugins */ Added automatic email sending plugins

Some plugins are listed in the [https://account.limesurvey.org/limestore Limestore]. If you have a plugin you would like to share with the world, feel free to add it to this page.

== Authentication plugins ==

* [https://survey-consulting.com/product/extended-auth-ldap-limesurvey-plugin Free Auth LDAP Plugin]
* [https://survey-consulting.com/product/limesurvey-saml-plugin/ SAML SSO Plugin]
* [https://github.com/technowhizz/LimeSurvey-RegDomainRestricter Registration Email Domain Restrictor]
* [http://extensions.sondages.pro/authentification-by-wordpress/ Authentification by WordPress user]
* [https://github.com/univlorraine/limesurvey-cas CAS Authentication plugin for LimeSurvey]
* [https://github.com/atlet/LimeSurvey-ShibbolethAuth LimeSurvey Shibboleth auth plugin]
* [https://framagit.org/Animafac/limesurvey/limesurvey-rememberme LimeSurvey RememberMe plugin]
* [https://github.com/SondagesPro/limesurvey-oauth2 OAuth2 authentication]

== Export and statistics plugins ==

* [https://survey-consulting.com/product/free-limesurvey-reporting-plugin/ Free LimeSurvey Reporting Plugin]: Create live reports for your LimeSurvey data with custom charts and admin notifications. Ideal for automated evaluations and printable summaries.
* [http://extensions.sondages.pro/exportcompleteanswers/ exportCompleteAnswers : Complete New export system allowing export Answer code and answer text in CSV. Options is manageable by super admin.]
* [http://extensions.sondages.pro/triple-s-export/ exportTripleS : export in Triple-S XML2 or XML1.3 format survey structure and data.]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendAdminStatitistics extendAdminStatitistics : rewriting of core statistics, actually put sub question in same table and graph]
* [https://github.com/reportico-web/limesurvey-reportico Reportico Reporting module for LimeSurvey]: generate charts,tables and statistics from survey data
* [https://www.robotspaceship.ai/loesungen/limesurvey-ppt-exporter PowerPoint Export] Export answers to PowerPoint (.pptx) as bar, pie, grouping, matrix, or dual-array charts, including ranking questions and text word clouds.

== Public survey plugins ==
~ [https://survey-consulting.com/product/respondent-driven-sampling-rds-limesurvey-plugin/ Respondent Driven Sampling (RDS) Plugin]: Add respondent driven sampling (RDS) to your LimeSurvey setup. Tokens are generated on submit and stored for controlled participant invitations.
* [http://extensions.sondages.pro/hideemptycolumn-for-limesurvey/ hideEmptyColumn : A plugin to add a solution to hide column of array question type with ExpressionScript of LimeSurvey ]
* [http://extensions.sondages.pro/moreaccessibility/ moreAccessibility : some option to add accessibility to public survey] 2.6lts compatible onlmy, deprecated in 3.0
* [https://git.framasoft.org/Shnoulle/addQuestionCodeClass addQuestionCodeClass : add the question code at the question wrapper class]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/radioToStarRating radioToStarRating : set any radio list to star rating system]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/moveSomeAnswers moveSomeAnswers] : If using random_order attribute : allow to always move some answers at end.

== Data editing plugins ==
* [https://survey-consulting.com/product/create-limesurvey-surveys-from-csv/ Copy Survey from CSV plugin]: Enables automated survey duplication based on CSV input – perfect for mass-creating standardized evaluations.
* [https://manual.limesurvey.org/MassAction_Plugin MassAction] : A plugin for faster survey editing by loading questions details into editable cells. Includes a search and replace feature.

== Email plugins ==
* [https://survey-consulting.com/product/automatically-send-email-invitations/ Automatically send email invitations]:
* [https://survey-consulting.com/product/automatically-send-email-reminders/ Automatically send email reminders]: Script for automatically sending LimeSurvey email reminders using a cronjob. Helps you [https://survey-consulting.com/how-to-prevent-limesurvey-email-invitations-or-reminders-being-treated-as-spam/ solving spam issues] and working around email sending limits.
* [https://gitlab.com/SondagesPro/mailing/noMailToExample noMailToExample]
* [https://github.com/LimeSurvey/LimeSurvey/blob/develop/plugins/mailSenderToFrom/mailSenderToFrom.php mailSenderToFrom]
* [https://github.com/Xites/LS_mailDKIM mailDKIM]
* [https://github.com/Xites/LS_mailEmbedImages mailEmbedImages]
* [https://github.com/RegioneER/LsRerAntiphishing Anti Phishing Templates] this free software plugin, mandatory alters mail notifications templates, by displaying urls inside email messages.

== Other plugins ==

* [http://extensions.sondages.pro/recomputeexpression-for-limesurvey Recompute Expressions:] A Plugin for LimeSurvey to recompute expression in survey with already submitted survey. Allow to update some relevance too.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/showAdvancedSettings showAdvancedSettings:] Show advanced settings in question edit by default.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/replaceRegister replaceRegisterː] Extra option for Register, starting point for other plugin.
* [http://extensions.sondages.pro/fixmaxstep-for-question-index/ fixMaxStep : Fix question index for token answer persistence survey:] Example of usage : get the complete index when user come back to the survey.
* [http://extensions.sondages.pro/sendmailajax-all-email-in-one/ sendMailAjax : Send token email one by one with ajaxː] Allow to send all email in one click without restriction.
* [http://extensions.sondages.pro/mailing-management/sendmailcron sendMailCron: Automatically send invitations and reminders using cronjobsː] Automatically sends invitations and reminders in custom intervals. Extensive configuration and debugging options
* [https://github.com/SteveCohen/Piwik-for-Limesurvey Piwik-for-Limesurvey Piwik for LimeSurvey]: Plugs Piwik into LimeSurvey, so you can track your survey admin users and respondents.
* [https://github.com/SondagesPro/surveysModel Mark surveys as "Survey Model/Template"ː] Allow admins to mark a survey as "Survey Model", a kind of "master survey" or "survey template" which only users with appropriate rights are allowed to edit. The common user is only allowed to create copies based on such a survey template.
* [https://github.com/SondagesPro/LS-toolsDomDocument toolsDomDocumentː] a tools for anothers plugin
* [https://github.com/TonisOrmisson/limesurvey-url-templates UrlTemplateChangerː] Set respondent's interview template over an URL parameter.
* [https://github.com/evently-nl/zesthook ZestHookː] Makes it possible to send a Post request on every response submission. You can set the URL to post to, as well as several other options.
* [https://github.com/CEric-fr/limesurvey-rgpd Extension RGPD pour LimeSurvey] Each questionnaire owner is able to interact with these conditions of use via a new submenu added in the "questionnaire parameters" entitled: GDPR configuration.
* [https://github.com/projeto-cade-unb/Lime2Camunda Lime2Camunda] Plugin for integration with LimeSurvey with Camunda, which at the end of completing the survey it starts a process instance in Camunda submitting all questions and answers as process variables.
* [https://github.com/librecodecoop/lsTelegramNotify lsTelegramNotify]: Allows you to send after survey completed event to Telegram as text, PDF or CSV.
* [https://github.com/LibreCodeCoop/LSNextcloud LSNextcloud]: Save all survey responses and their attachments automatically to a folder in your Nextcloud.

== Example and demo plugins ==
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendRemoteControl extendRemoteControl] : Show how to add function to [[RemoteControl_2_API]], show how to create a new admin page too (usage of public function actionIndex() )

[[Category:Plugins]]

Available third party plugins

2026-05-19T11:24:28Z

Mazi: /* Public survey plugins */ Added link to free RDS plugin

Some plugins are listed in the [https://account.limesurvey.org/limestore Limestore]. If you have a plugin you would like to share with the world, feel free to add it to this page.

== Authentication plugins ==

* [https://survey-consulting.com/product/extended-auth-ldap-limesurvey-plugin Free Auth LDAP Plugin]
* [https://survey-consulting.com/product/limesurvey-saml-plugin/ SAML SSO Plugin]
* [https://github.com/technowhizz/LimeSurvey-RegDomainRestricter Registration Email Domain Restrictor]
* [http://extensions.sondages.pro/authentification-by-wordpress/ Authentification by WordPress user]
* [https://github.com/univlorraine/limesurvey-cas CAS Authentication plugin for LimeSurvey]
* [https://github.com/atlet/LimeSurvey-ShibbolethAuth LimeSurvey Shibboleth auth plugin]
* [https://framagit.org/Animafac/limesurvey/limesurvey-rememberme LimeSurvey RememberMe plugin]
* [https://github.com/SondagesPro/limesurvey-oauth2 OAuth2 authentication]

== Export and statistics plugins ==

* [https://survey-consulting.com/product/free-limesurvey-reporting-plugin/ Free LimeSurvey Reporting Plugin]: Create live reports for your LimeSurvey data with custom charts and admin notifications. Ideal for automated evaluations and printable summaries.
* [http://extensions.sondages.pro/exportcompleteanswers/ exportCompleteAnswers : Complete New export system allowing export Answer code and answer text in CSV. Options is manageable by super admin.]
* [http://extensions.sondages.pro/triple-s-export/ exportTripleS : export in Triple-S XML2 or XML1.3 format survey structure and data.]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendAdminStatitistics extendAdminStatitistics : rewriting of core statistics, actually put sub question in same table and graph]
* [https://github.com/reportico-web/limesurvey-reportico Reportico Reporting module for LimeSurvey]: generate charts,tables and statistics from survey data
* [https://www.robotspaceship.ai/loesungen/limesurvey-ppt-exporter PowerPoint Export] Export answers to PowerPoint (.pptx) as bar, pie, grouping, matrix, or dual-array charts, including ranking questions and text word clouds.

== Public survey plugins ==
~ [https://survey-consulting.com/product/respondent-driven-sampling-rds-limesurvey-plugin/ Respondent Driven Sampling (RDS) Plugin]: Add respondent driven sampling (RDS) to your LimeSurvey setup. Tokens are generated on submit and stored for controlled participant invitations.
* [http://extensions.sondages.pro/hideemptycolumn-for-limesurvey/ hideEmptyColumn : A plugin to add a solution to hide column of array question type with ExpressionScript of LimeSurvey ]
* [http://extensions.sondages.pro/moreaccessibility/ moreAccessibility : some option to add accessibility to public survey] 2.6lts compatible onlmy, deprecated in 3.0
* [https://git.framasoft.org/Shnoulle/addQuestionCodeClass addQuestionCodeClass : add the question code at the question wrapper class]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/radioToStarRating radioToStarRating : set any radio list to star rating system]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/moveSomeAnswers moveSomeAnswers] : If using random_order attribute : allow to always move some answers at end.

== Data editing plugins ==
* [https://survey-consulting.com/product/create-limesurvey-surveys-from-csv/ Copy Survey from CSV plugin]: Enables automated survey duplication based on CSV input – perfect for mass-creating standardized evaluations.
* [https://manual.limesurvey.org/MassAction_Plugin MassAction] : A plugin for faster survey editing by loading questions details into editable cells. Includes a search and replace feature.

== Email plugins ==

* [https://gitlab.com/SondagesPro/mailing/noMailToExample noMailToExample]
* [https://github.com/LimeSurvey/LimeSurvey/blob/develop/plugins/mailSenderToFrom/mailSenderToFrom.php mailSenderToFrom]
* [https://github.com/Xites/LS_mailDKIM mailDKIM]
* [https://github.com/Xites/LS_mailEmbedImages mailEmbedImages]
* [https://github.com/RegioneER/LsRerAntiphishing Anti Phishing Templates] this free software plugin, mandatory alters mail notifications templates, by displaying urls inside email messages.

== Other plugins ==

* [http://extensions.sondages.pro/recomputeexpression-for-limesurvey Recompute Expressions:] A Plugin for LimeSurvey to recompute expression in survey with already submitted survey. Allow to update some relevance too.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/showAdvancedSettings showAdvancedSettings:] Show advanced settings in question edit by default.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/replaceRegister replaceRegisterː] Extra option for Register, starting point for other plugin.
* [http://extensions.sondages.pro/fixmaxstep-for-question-index/ fixMaxStep : Fix question index for token answer persistence survey:] Example of usage : get the complete index when user come back to the survey.
* [http://extensions.sondages.pro/sendmailajax-all-email-in-one/ sendMailAjax : Send token email one by one with ajaxː] Allow to send all email in one click without restriction.
* [http://extensions.sondages.pro/mailing-management/sendmailcron sendMailCron: Automatically send invitations and reminders using cronjobsː] Automatically sends invitations and reminders in custom intervals. Extensive configuration and debugging options
* [https://github.com/SteveCohen/Piwik-for-Limesurvey Piwik-for-Limesurvey Piwik for LimeSurvey]: Plugs Piwik into LimeSurvey, so you can track your survey admin users and respondents.
* [https://github.com/SondagesPro/surveysModel Mark surveys as "Survey Model/Template"ː] Allow admins to mark a survey as "Survey Model", a kind of "master survey" or "survey template" which only users with appropriate rights are allowed to edit. The common user is only allowed to create copies based on such a survey template.
* [https://github.com/SondagesPro/LS-toolsDomDocument toolsDomDocumentː] a tools for anothers plugin
* [https://github.com/TonisOrmisson/limesurvey-url-templates UrlTemplateChangerː] Set respondent's interview template over an URL parameter.
* [https://github.com/evently-nl/zesthook ZestHookː] Makes it possible to send a Post request on every response submission. You can set the URL to post to, as well as several other options.
* [https://github.com/CEric-fr/limesurvey-rgpd Extension RGPD pour LimeSurvey] Each questionnaire owner is able to interact with these conditions of use via a new submenu added in the "questionnaire parameters" entitled: GDPR configuration.
* [https://github.com/projeto-cade-unb/Lime2Camunda Lime2Camunda] Plugin for integration with LimeSurvey with Camunda, which at the end of completing the survey it starts a process instance in Camunda submitting all questions and answers as process variables.
* [https://github.com/librecodecoop/lsTelegramNotify lsTelegramNotify]: Allows you to send after survey completed event to Telegram as text, PDF or CSV.
* [https://github.com/LibreCodeCoop/LSNextcloud LSNextcloud]: Save all survey responses and their attachments automatically to a folder in your Nextcloud.

== Example and demo plugins ==
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendRemoteControl extendRemoteControl] : Show how to add function to [[RemoteControl_2_API]], show how to create a new admin page too (usage of public function actionIndex() )

[[Category:Plugins]]

Available third party plugins

2026-05-19T11:23:23Z

Mazi: /* Data editing plugins */ Added link to free CSV copy plugin

Some plugins are listed in the [https://account.limesurvey.org/limestore Limestore]. If you have a plugin you would like to share with the world, feel free to add it to this page.

== Authentication plugins ==

* [https://survey-consulting.com/product/extended-auth-ldap-limesurvey-plugin Free Auth LDAP Plugin]
* [https://survey-consulting.com/product/limesurvey-saml-plugin/ SAML SSO Plugin]
* [https://github.com/technowhizz/LimeSurvey-RegDomainRestricter Registration Email Domain Restrictor]
* [http://extensions.sondages.pro/authentification-by-wordpress/ Authentification by WordPress user]
* [https://github.com/univlorraine/limesurvey-cas CAS Authentication plugin for LimeSurvey]
* [https://github.com/atlet/LimeSurvey-ShibbolethAuth LimeSurvey Shibboleth auth plugin]
* [https://framagit.org/Animafac/limesurvey/limesurvey-rememberme LimeSurvey RememberMe plugin]
* [https://github.com/SondagesPro/limesurvey-oauth2 OAuth2 authentication]

== Export and statistics plugins ==

* [https://survey-consulting.com/product/free-limesurvey-reporting-plugin/ Free LimeSurvey Reporting Plugin]: Create live reports for your LimeSurvey data with custom charts and admin notifications. Ideal for automated evaluations and printable summaries.
* [http://extensions.sondages.pro/exportcompleteanswers/ exportCompleteAnswers : Complete New export system allowing export Answer code and answer text in CSV. Options is manageable by super admin.]
* [http://extensions.sondages.pro/triple-s-export/ exportTripleS : export in Triple-S XML2 or XML1.3 format survey structure and data.]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendAdminStatitistics extendAdminStatitistics : rewriting of core statistics, actually put sub question in same table and graph]
* [https://github.com/reportico-web/limesurvey-reportico Reportico Reporting module for LimeSurvey]: generate charts,tables and statistics from survey data
* [https://www.robotspaceship.ai/loesungen/limesurvey-ppt-exporter PowerPoint Export] Export answers to PowerPoint (.pptx) as bar, pie, grouping, matrix, or dual-array charts, including ranking questions and text word clouds.

== Public survey plugins ==
* [http://extensions.sondages.pro/hideemptycolumn-for-limesurvey/ hideEmptyColumn : A plugin to add a solution to hide column of array question type with ExpressionScript of LimeSurvey ]
* [http://extensions.sondages.pro/moreaccessibility/ moreAccessibility : some option to add accessibility to public survey] 2.6lts compatible onlmy, deprecated in 3.0
* [https://git.framasoft.org/Shnoulle/addQuestionCodeClass addQuestionCodeClass : add the question code at the question wrapper class]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/radioToStarRating radioToStarRating : set any radio list to star rating system]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/moveSomeAnswers moveSomeAnswers] : If using random_order attribute : allow to always move some answers at end.

== Data editing plugins ==
* [https://survey-consulting.com/product/create-limesurvey-surveys-from-csv/ Copy Survey from CSV plugin]: Enables automated survey duplication based on CSV input – perfect for mass-creating standardized evaluations.
* [https://manual.limesurvey.org/MassAction_Plugin MassAction] : A plugin for faster survey editing by loading questions details into editable cells. Includes a search and replace feature.

== Email plugins ==

* [https://gitlab.com/SondagesPro/mailing/noMailToExample noMailToExample]
* [https://github.com/LimeSurvey/LimeSurvey/blob/develop/plugins/mailSenderToFrom/mailSenderToFrom.php mailSenderToFrom]
* [https://github.com/Xites/LS_mailDKIM mailDKIM]
* [https://github.com/Xites/LS_mailEmbedImages mailEmbedImages]
* [https://github.com/RegioneER/LsRerAntiphishing Anti Phishing Templates] this free software plugin, mandatory alters mail notifications templates, by displaying urls inside email messages.

== Other plugins ==

* [http://extensions.sondages.pro/recomputeexpression-for-limesurvey Recompute Expressions:] A Plugin for LimeSurvey to recompute expression in survey with already submitted survey. Allow to update some relevance too.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/showAdvancedSettings showAdvancedSettings:] Show advanced settings in question edit by default.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/replaceRegister replaceRegisterː] Extra option for Register, starting point for other plugin.
* [http://extensions.sondages.pro/fixmaxstep-for-question-index/ fixMaxStep : Fix question index for token answer persistence survey:] Example of usage : get the complete index when user come back to the survey.
* [http://extensions.sondages.pro/sendmailajax-all-email-in-one/ sendMailAjax : Send token email one by one with ajaxː] Allow to send all email in one click without restriction.
* [http://extensions.sondages.pro/mailing-management/sendmailcron sendMailCron: Automatically send invitations and reminders using cronjobsː] Automatically sends invitations and reminders in custom intervals. Extensive configuration and debugging options
* [https://github.com/SteveCohen/Piwik-for-Limesurvey Piwik-for-Limesurvey Piwik for LimeSurvey]: Plugs Piwik into LimeSurvey, so you can track your survey admin users and respondents.
* [https://github.com/SondagesPro/surveysModel Mark surveys as "Survey Model/Template"ː] Allow admins to mark a survey as "Survey Model", a kind of "master survey" or "survey template" which only users with appropriate rights are allowed to edit. The common user is only allowed to create copies based on such a survey template.
* [https://github.com/SondagesPro/LS-toolsDomDocument toolsDomDocumentː] a tools for anothers plugin
* [https://github.com/TonisOrmisson/limesurvey-url-templates UrlTemplateChangerː] Set respondent's interview template over an URL parameter.
* [https://github.com/evently-nl/zesthook ZestHookː] Makes it possible to send a Post request on every response submission. You can set the URL to post to, as well as several other options.
* [https://github.com/CEric-fr/limesurvey-rgpd Extension RGPD pour LimeSurvey] Each questionnaire owner is able to interact with these conditions of use via a new submenu added in the "questionnaire parameters" entitled: GDPR configuration.
* [https://github.com/projeto-cade-unb/Lime2Camunda Lime2Camunda] Plugin for integration with LimeSurvey with Camunda, which at the end of completing the survey it starts a process instance in Camunda submitting all questions and answers as process variables.
* [https://github.com/librecodecoop/lsTelegramNotify lsTelegramNotify]: Allows you to send after survey completed event to Telegram as text, PDF or CSV.
* [https://github.com/LibreCodeCoop/LSNextcloud LSNextcloud]: Save all survey responses and their attachments automatically to a folder in your Nextcloud.

== Example and demo plugins ==
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendRemoteControl extendRemoteControl] : Show how to add function to [[RemoteControl_2_API]], show how to create a new admin page too (usage of public function actionIndex() )

[[Category:Plugins]]

Available third party plugins

2026-05-19T11:21:40Z

Mazi: /* Export and statistics plugins */ Added link to free reporting plugin

Some plugins are listed in the [https://account.limesurvey.org/limestore Limestore]. If you have a plugin you would like to share with the world, feel free to add it to this page.

== Authentication plugins ==

* [https://survey-consulting.com/product/extended-auth-ldap-limesurvey-plugin Free Auth LDAP Plugin]
* [https://survey-consulting.com/product/limesurvey-saml-plugin/ SAML SSO Plugin]
* [https://github.com/technowhizz/LimeSurvey-RegDomainRestricter Registration Email Domain Restrictor]
* [http://extensions.sondages.pro/authentification-by-wordpress/ Authentification by WordPress user]
* [https://github.com/univlorraine/limesurvey-cas CAS Authentication plugin for LimeSurvey]
* [https://github.com/atlet/LimeSurvey-ShibbolethAuth LimeSurvey Shibboleth auth plugin]
* [https://framagit.org/Animafac/limesurvey/limesurvey-rememberme LimeSurvey RememberMe plugin]
* [https://github.com/SondagesPro/limesurvey-oauth2 OAuth2 authentication]

== Export and statistics plugins ==

* [https://survey-consulting.com/product/free-limesurvey-reporting-plugin/ Free LimeSurvey Reporting Plugin]: Create live reports for your LimeSurvey data with custom charts and admin notifications. Ideal for automated evaluations and printable summaries.
* [http://extensions.sondages.pro/exportcompleteanswers/ exportCompleteAnswers : Complete New export system allowing export Answer code and answer text in CSV. Options is manageable by super admin.]
* [http://extensions.sondages.pro/triple-s-export/ exportTripleS : export in Triple-S XML2 or XML1.3 format survey structure and data.]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendAdminStatitistics extendAdminStatitistics : rewriting of core statistics, actually put sub question in same table and graph]
* [https://github.com/reportico-web/limesurvey-reportico Reportico Reporting module for LimeSurvey]: generate charts,tables and statistics from survey data
* [https://www.robotspaceship.ai/loesungen/limesurvey-ppt-exporter PowerPoint Export] Export answers to PowerPoint (.pptx) as bar, pie, grouping, matrix, or dual-array charts, including ranking questions and text word clouds.

== Public survey plugins ==
* [http://extensions.sondages.pro/hideemptycolumn-for-limesurvey/ hideEmptyColumn : A plugin to add a solution to hide column of array question type with ExpressionScript of LimeSurvey ]
* [http://extensions.sondages.pro/moreaccessibility/ moreAccessibility : some option to add accessibility to public survey] 2.6lts compatible onlmy, deprecated in 3.0
* [https://git.framasoft.org/Shnoulle/addQuestionCodeClass addQuestionCodeClass : add the question code at the question wrapper class]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/radioToStarRating radioToStarRating : set any radio list to star rating system]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/moveSomeAnswers moveSomeAnswers] : If using random_order attribute : allow to always move some answers at end.

== Data editing plugins ==
* [https://manual.limesurvey.org/MassAction_Plugin MassAction] : A plugin for faster survey editing by loading questions details into editable cells. Includes a search and replace feature.

== Email plugins ==

* [https://gitlab.com/SondagesPro/mailing/noMailToExample noMailToExample]
* [https://github.com/LimeSurvey/LimeSurvey/blob/develop/plugins/mailSenderToFrom/mailSenderToFrom.php mailSenderToFrom]
* [https://github.com/Xites/LS_mailDKIM mailDKIM]
* [https://github.com/Xites/LS_mailEmbedImages mailEmbedImages]
* [https://github.com/RegioneER/LsRerAntiphishing Anti Phishing Templates] this free software plugin, mandatory alters mail notifications templates, by displaying urls inside email messages.

== Other plugins ==

* [http://extensions.sondages.pro/recomputeexpression-for-limesurvey Recompute Expressions:] A Plugin for LimeSurvey to recompute expression in survey with already submitted survey. Allow to update some relevance too.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/showAdvancedSettings showAdvancedSettings:] Show advanced settings in question edit by default.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/replaceRegister replaceRegisterː] Extra option for Register, starting point for other plugin.
* [http://extensions.sondages.pro/fixmaxstep-for-question-index/ fixMaxStep : Fix question index for token answer persistence survey:] Example of usage : get the complete index when user come back to the survey.
* [http://extensions.sondages.pro/sendmailajax-all-email-in-one/ sendMailAjax : Send token email one by one with ajaxː] Allow to send all email in one click without restriction.
* [http://extensions.sondages.pro/mailing-management/sendmailcron sendMailCron: Automatically send invitations and reminders using cronjobsː] Automatically sends invitations and reminders in custom intervals. Extensive configuration and debugging options
* [https://github.com/SteveCohen/Piwik-for-Limesurvey Piwik-for-Limesurvey Piwik for LimeSurvey]: Plugs Piwik into LimeSurvey, so you can track your survey admin users and respondents.
* [https://github.com/SondagesPro/surveysModel Mark surveys as "Survey Model/Template"ː] Allow admins to mark a survey as "Survey Model", a kind of "master survey" or "survey template" which only users with appropriate rights are allowed to edit. The common user is only allowed to create copies based on such a survey template.
* [https://github.com/SondagesPro/LS-toolsDomDocument toolsDomDocumentː] a tools for anothers plugin
* [https://github.com/TonisOrmisson/limesurvey-url-templates UrlTemplateChangerː] Set respondent's interview template over an URL parameter.
* [https://github.com/evently-nl/zesthook ZestHookː] Makes it possible to send a Post request on every response submission. You can set the URL to post to, as well as several other options.
* [https://github.com/CEric-fr/limesurvey-rgpd Extension RGPD pour LimeSurvey] Each questionnaire owner is able to interact with these conditions of use via a new submenu added in the "questionnaire parameters" entitled: GDPR configuration.
* [https://github.com/projeto-cade-unb/Lime2Camunda Lime2Camunda] Plugin for integration with LimeSurvey with Camunda, which at the end of completing the survey it starts a process instance in Camunda submitting all questions and answers as process variables.
* [https://github.com/librecodecoop/lsTelegramNotify lsTelegramNotify]: Allows you to send after survey completed event to Telegram as text, PDF or CSV.
* [https://github.com/LibreCodeCoop/LSNextcloud LSNextcloud]: Save all survey responses and their attachments automatically to a folder in your Nextcloud.

== Example and demo plugins ==
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendRemoteControl extendRemoteControl] : Show how to add function to [[RemoteControl_2_API]], show how to create a new admin page too (usage of public function actionIndex() )

[[Category:Plugins]]

Available third party plugins

2025-10-10T10:27:50Z

Mazi: /* Authentication plugins */ Added new "Free Auth LDAP Plugin"

Some plugin are listed in the [https://account.limesurvey.org/limestore Limestore]. If you have a plugin you would like to share with the world, feel free to add it to this page.

== Authentication plugins ==

* [https://survey-consulting.com/product/extended-auth-ldap-limesurvey-plugin Free Auth LDAP Plugin]
* [https://survey-consulting.com/product/limesurvey-saml-plugin/ SAML SSO Plugin]
* [https://github.com/technowhizz/LimeSurvey-RegDomainRestricter Registration Email Domain Restrictor]
* [http://extensions.sondages.pro/authentification-by-wordpress/ Authentification by WordPress user]
* [https://github.com/univlorraine/limesurvey-cas CAS Authentication plugin for LimeSurvey]
* [https://github.com/atlet/LimeSurvey-ShibbolethAuth LimeSurvey Shibboleth auth plugin]
* [https://framagit.org/Animafac/limesurvey/limesurvey-rememberme LimeSurvey RememberMe plugin]

== Export and statistics plugins ==

* [http://extensions.sondages.pro/exportcompleteanswers/ exportCompleteAnswers : Complete New export system allowing export Answer code and answer text in CSV. Options is manageable by super admin.]
* [http://extensions.sondages.pro/triple-s-export/ exportTripleS : export in Triple-S XML2 or XML1.3 format survey structure and data.]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendAdminStatitistics extendAdminStatitistics : rewriting of core statistics, actually put sub question in same table and graph]
* [https://github.com/reportico-web/limesurvey-reportico Reportico Reporting module for LimeSurvey]: generate charts,tables and statistics from survey data

== Public survey plugins ==
* [http://extensions.sondages.pro/hideemptycolumn-for-limesurvey/ hideEmptyColumn : A plugin to add a solution to hide column of array question type with ExpressionScript of LimeSurvey ]
* [http://extensions.sondages.pro/moreaccessibility/ moreAccessibility : some option to add accessibility to public survey] 2.6lts compatible onlmy, deprecated in 3.0
* [https://git.framasoft.org/Shnoulle/addQuestionCodeClass addQuestionCodeClass : add the question code at the question wrapper class]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/radioToStarRating radioToStarRating : set any radio list to star rating system]
* [https://framagit.org/SondagePro-LimeSurvey-plugin/moveSomeAnswers moveSomeAnswers] : If using random_order attribute : allow to always move some answers at end.

== Data editing plugins ==
* [https://manual.limesurvey.org/MassAction_Plugin MassAction] : A plugin for faster survey editing by loading questions details into editable cells. Includes a search and replace feature.

== Email plugins ==

* [https://gitlab.com/SondagesPro/mailing/noMailToExample noMailToExample]
* [https://github.com/LimeSurvey/LimeSurvey/blob/develop/plugins/mailSenderToFrom/mailSenderToFrom.php mailSenderToFrom]
* [https://github.com/Xites/LS_mailDKIM mailDKIM]
* [https://github.com/Xites/LS_mailEmbedImages mailEmbedImages]

== Other plugins ==

* [http://extensions.sondages.pro/recomputeexpression-for-limesurvey Recompute Expressions:] A Plugin for LimeSurvey to recompute expression in survey with already submitted survey. Allow to update some relevance too.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/showAdvancedSettings showAdvancedSettings:] Show advanced settings in question edit by default.
* [https://git.framasoft.org/SondagePro-LimeSurvey-plugin/replaceRegister replaceRegisterː] Extra option for Register, starting point for other plugin.
* [http://extensions.sondages.pro/fixmaxstep-for-question-index/ fixMaxStep : Fix question index for token answer persistence survey:] Example of usage : get the complete index when user come back to the survey.
* [http://extensions.sondages.pro/sendmailajax-all-email-in-one/ sendMailAjax : Send token email one by one with ajaxː] Allow to send all email in one click without restriction.
* [http://extensions.sondages.pro/mailing-management/sendmailcron sendMailCron: Automatically send invitations and reminders using cronjobsː] Automatically sends invitations and reminders in custom intervals. Extensive configuration and debugging options
* [https://github.com/SteveCohen/Piwik-for-Limesurvey Piwik-for-Limesurvey Piwik for LimeSurvey]: Plugs Piwik into LimeSurvey, so you can track your survey admin users and respondents.
* [https://github.com/SondagesPro/surveysModel Mark surveys as "Survey Model/Template"ː] Allow admins to mark a survey as "Survey Model", a kind of "master survey" or "survey template" which only users with appropriate rights are allowed to edit. The common user is only allowed to create copies based on such a survey template.
* [https://github.com/SondagesPro/LS-toolsDomDocument toolsDomDocumentː] a tools for anothers plugin
* [https://github.com/TonisOrmisson/limesurvey-url-templates UrlTemplateChangerː] Set respondent's interview template over an URL parameter.
* [https://github.com/evently-nl/zesthook ZestHookː] Makes it possible to send a Post request on every response submission. You can set the URL to post to, as well as several other options.
* [https://github.com/CEric-fr/limesurvey-rgpd Extension RGPD pour LimeSurvey] Each questionnaire owner is able to interact with these conditions of use via a new submenu added in the "questionnaire parameters" entitled: GDPR configuration.
* [https://github.com/projeto-cade-unb/Lime2Camunda Lime2Camunda] Plugin for integration with LimeSurvey with Camunda, which at the end of completing the survey it starts a process instance in Camunda submitting all questions and answers as process variables.
* [https://github.com/LibreCodeCoop/LSNextcloud LSNextcloud] Allows you to send after survey completed event to Telegram as text, PDF or CSV.
* [https://github.com/librecodecoop/lsTelegramNotify lsTelegramNotify]: Allows you to send after survey completed event to Telegram as text, PDF or CSV.
* [https://github.com/LibreCodeCoop/LSNextcloud LSNextcloud]: Save all survey responses and their attachments automatically to a folder in your Nextcloud.

== Example and demo plugins ==
* [https://framagit.org/SondagePro-LimeSurvey-plugin/extendRemoteControl extendRemoteControl] : Show how to add function to [[RemoteControl_2_API]], show how to create a new admin page too (usage of public function actionIndex() )

[[Category:Plugins]]

Question type - Array

2025-10-04T07:50:09Z

Mazi: Added more details to basic information section

<languages /> <translate>


__TOC__

=Short description= 

</translate>
<onlyinclude>{{#ifeq:{{{transcludesection|short_description}}}|short_description|<div style="display:none;"><translate>
</div>


An array allows you to create a set of [[Question_types#Subquestions|subquestions]]. Each of them uses the same set of answer options. For example, you can use this question type when you need feedback on several aspects of a particular product.

For adding an "other" free text option an [https://survey-consulting.com/product/array-with-other-free-text-limesurvey-plugin/ additional plugin] can be used.

<div style="display:none;"></translate></div>}}</onlyinclude><translate>

=Video tutorial= 


To understand how the array-type questions work, check the following [https://www.youtube.com/watch?v=7134QebOQzY video tutorial].

=General description= 


In the below example, the ''array question type'' is used in order to rate four sci-fi movies:


<center>[[File:F_AFL.jpg]]</center>


'''Example:''' [[Media:Question tpye - Array using flexible labels.zip|Question type - Array using flexible labels.zip]]


<hr width="50%" style="margin:auto">


A further option available is the '''Semantic Differential'''. You have to choose either ''Array'' or ''Array (5 point choice)'' as question type to part the answer by using a pipe char "|" - which answer should be on the left side and which one on the right side of the array. For example, If you want to have 'Good' on the left side of the row and 'Evil' on the right side of the row, just write 'Good|Evil' into the answer field:


<center>[[File:H_SD.jpg]]</center>


'''Example:''' [[Media:Question type - Array - Semantic Differential Question Type.zip|Question type - Array - Semantic Differential Question Type.zip]]


<div class="simplebox">[[File:help.png]] '''Hint:''' If you use Windows and you do not know where the Pipe Char is on your keyboard, you can enter it by pressing and holding Alt key, entering 124, and releasing the Alt key.</div>

=General options= 


{{QS:mandatory}}


{{QS:relevance}}

=Display= 


{{QS:subquestion_width}}


{{QS:Random_order}}


{{QS:Repeat_headers}}


{{QS:Question_theme}}


{{QS:Hide_tip}}


{{QS:Hidden}}


{{QS:CSS_Class}}


{{QS:use_dropdown}}


{{QS:Printable_survey_relevance_help}}

=Logic= 


{{QS:min_answers}}


{{QS:max_answers}}


{{QS:array_filter}}


{{QS:array_filter_style}}


{{QS:array_filter_exclude}}


{{QS:Exclusive_option}}


{{QS:Random_group}}


{{QS:em_validation_q}}


{{QS:em_validation_q_tip}}

=Other= 


{{QS:Page_break}}


{{QS:scale_export}}

=Statistics= 


{{QS:Public_statistics}}


{{QS:Display_chart}}


{{QS:Chart_type}}


[[Category:Question types]][[Category:Arrays]]

</translate>

LimeSurvey-kompatible Internet-Provider

2025-02-25T10:21:26Z

Mazi: /* Deutschland */ Added entry

<div class="simplebox">Translation in progress.</div>

These providers have been tested successfully with LimeSurvey. Please add your provider if everything works fine - just don't add a link.

==Österreich==
* CISC, LLC.
* kapper.net
* World4you

==Deutschland==
* 1&1
* 1blue
* All-incl.com
* alphahosting
* Domainfactory
* EUserv Internet
* gn2-netwerk
* HostEurope
* Hostsharing eG
* ICDSoft
* kesslernet
* NX24 GmbH
* PCB - Tobias Berndt Hosting
* [https://survey-consulting.com/hosting Survey Consulting]
* Sysprovide
* Webhostone
* zedat FU Berlin

==Schweiz==
* Metanet

==Vereinigtes Königreich/England==
* 1&1
* 2020Media.com
* Centicero (using package Website)

==USA==
* 1&1
* Dreamhost
* GoDaddy (Using PHP 5.x and MySQL 5.x)
* Host Color
* ICDSoft
* Web Hosting Buzz

==Hongkong==
* ICDSoft

Installation - LimeSurvey CE/de

2025-02-25T10:05:05Z

Mazi: Fixed invalid link

<languages />

__TOC__

<div class="simplebox"> Anmerkung: Diese Installationsanleitung ist für Version 2.0 oder höher. Die Installationsanleitung für 1.92 finden Sie [[Installation Version 1.92 or older/de|hier]]; eine Anleitung zum Update [[Upgrading from a previous version/de|hier]].</div>

<span id="General"></span>
==Allgemein==

Das LimeSurvey-Projekt bietet zwei Installationsarten an:
*Auf Ihrem Webserver:<br />In diesem Fall folgen Sie einfach den Anweisungen hier auf dieser Seite.

*Auf Ihrem lokalen Windows-PC:<br />In der Regel möchten Sie LimeSurvey nur auf Ihrem lokalen PC installieren, wenn Sie Umfragen lokal erstellen (vor allem aus Geschwindigkeit- oder Test-Gründen) und später die Umfrage in Ihre Live-LimeSurvey-Installation auf einem Webserver integrieren wollen. Dafür haben wir ein spezielles Installationspaket vorbereitet, das einen Webserver, eine Datenbank und die LimeSurvey-Anwendung enthält. Siehe [[Installation of the LimeSurvey XAMPP package/de|Installationsanleitung]].

<span id="Make_sure_you_can_use_LimeSurvey_on_your_website"></span>
== Stellen Sie sicher, dass Sie LimeSurvey auf Ihrer Website verwenden können ==

Stellen Sie sicher, dass Ihr Server die folgenden Anforderungen erfüllt.

{{Note|Die Mindestanforderungen werden während der Installation überprüft!}}

<div class="mw-translate-fuzzy">
Die Mindestanforderungen für '''LimeSurvey 6.x''':
* Mindestens 250 MB Speicherplatz.
* MariaDB 10.3.38 oder höher '''ODER''' MySQL 8 oder höher '''ODER''' Microsoft SQL Server 2008 oder höher '''ODER''' Postgres 12 oder höher.
* PHP-Versionsanforderungen:
** LS 6.x von PHP 7.4.x bis 8.3.x
** LS 5.x von PHP 7.2.5 bis 8.0.x
** LS 3.x von PHP 5.5.9 bis 7.4.x
* php.ini `short_open_tag`-Einstellung sollte auf gesetzt sein `ON`
* Die folgenden PHP-Module/Bibliotheken sollten aktiviert sein:
** [[Installations-FAQ#Anforderungsseite#Was ist die mbstring (Multibyte String Functions)-Bibliothek|mbstring (Multibyte String Functions)]]-Erweiterung Bibliothek.
** PDO-Datenbanktreiber für MySQL (pdo_mysql oder pdo_mysqli) oder Postgres (pdo_pgsql) oder MSSQL ([https://php.net/manual/en/ref.pdo-sqlsrv.php pdo_sqlsrv] für Windows und [http://www.php.net/manual/en/ref.pdo-dblib.php pdo_dblib] für Linux).
** Außerdem gehen wir im Allgemeinen davon aus, dass alle PHP-Standardbibliotheken aktiviert sind.
*** hash
*** session
*** openssl oder mcrypt
*** fileinfo
*** SimpleXML
*** etc …
</div>

<div class="simplebox"> Anmerkung: Wenn Sie eine Verbindung von Linux zu einer MSSQL-Datenbank auf einem Windows Server mit dem dblib PDO-Treiber herstellen, dann muss das zu Grunde liegende FreeTDS korrekt konfiguriert werden. Auf der [[Troubleshooting]]-Seite finden Sie weitere Informationen.</div>

Optionale PHP-Erweiterungen:
* '''GD-Library''' '''mit installierter FreeType-Unterstützung''' wird für Captchas, schöne Diagramme in Statistiken oder zum Hochladen von Bildern über den HTML-Editor benötigt - siehe [https://php.net/manual/image.setup.php PHP GD-Library Extension-Dokumentation]
* '''IMAP''' (ziemlich Standard) wird für das [[Email Bounce Tracking System|Email Bounce Tracking System] benötigt. ] – siehe [https://php.net/manual/imap.setup.php Dokumentation zur PHP-IMAP-Erweiterung]
* "'LDAP"' muss installiert sein, um Umfrageteilnehmer über LDAP zu importieren – siehe [https:/ /php.net/manual/en/book.ldap.php PHP LDAP-Dokumentation]
* '''Zip''' (ziemlich Standard) wird für das Hochladen von Vorlagen, den Import von .zip-archivierten Ressourcen und den Excel-Export benötigt - siehe [https://php.net/manual/zip.setup.php PHP Zip Extension-Dokumentation]
* '''Zlib''' (ziemlich Standard) wird für das [[ComfortUpdate]] benötigt - siehe [https ://php.net/manual/zlib.setup.php PHP Zlib Extension-Dokumentation]

In der Regel wird Ihnen der Provider Ihres Webspace oder der Administrator bei diesen optionalen Komponenten weiterhelfen können.

Wenn Sie LimeSurvey auf einem Microsoft IIS installieren wollen, könnte der folgende Link hilfreich sein: "[[Installation on XP with IIS]]" (in Englisch).

===Browserkompatibilität===
'''Für Umfrageteilnehmer unterstützen wir derzeit Edge und alle neueren vergleichbaren Browser wie Firefox, Chrome, Opera usw. mit aktiviertem JavaScript.

'''Für den Administrationsteil''' unterstützen wir derzeit Edge und alle neueren vergleichbaren Browser wie Firefox, Chrome, Opera etc. mit aktiviertem JavaScript.

====Bildschirmgrößen====
Wir unterstützen jede angemessene Bildschirmgröße für die Teilnahme an Umfragen (360 x 640 Pixel und mehr).
Die minimal unterstützte Bildschirmauflösung für die Verwaltungsseite von LimeSurvey beträgt 1280 x 1024 Pixel.

<span id="Hosting_for_LimeSurvey"></span>
===Hosting für LimeSurvey===

<div class="mw-translate-fuzzy">
LimeSurvey sollte mit den meisten Hosting-Unternehmen zusammenarbeiten, die PHP und MySQL anbieten. Wenn Sie eine fertig installierte Version von LimeSurvey wünschen, können Sie [https://www.limesurvey.org/editions-and-prices/limesurvey-pro/editions-and-prices-professional LimeSurvey Cloud] ausprobieren, oder schauen Sie sich unsere [https://www.limesurvey.org/manual/LimeSurvey-compatible_hosting_companies/de Liste der LimeSurvey-kompatiblen Hosting-Unternehmen] an.
</div>

<span id="Download_the_LimeSurvey_package"></span>
==Laden Sie das LimeSurvey-Paket herunter==

[https://community.limesurvey.org/downloads/ Laden Sie] das neueste stabile LimeSurvey-Zip-Paket herunter (es stehen Ihnen auch die Pakete gzip, bz2 und 7zip zur Verfügung) und speichern Sie es auf Ihrer lokalen Festplatte.

<span id="Unpack_the_LimeSurvey_package"></span>
==Entpacken Sie das LimeSurvey-Paket==

Dekomprimieren Sie die ZIP-Datei mit Ihrer bevorzugten Komprimierungssoftware in ein spezielles Verzeichnis/Ordner. Stellen Sie beim Dekomprimieren der Datei sicher, dass Sie die Verzeichnisstruktur mit den Dateien dekomprimieren (dies ist das Standardverhalten der meisten Komprimierungsprogramme). Der Pfadname für das Installationsverzeichnis sollte keine Sonderzeichen „(“ oder „)“ enthalten, kann aber das Zeichen „Leerzeichen“ enthalten.

<span id="Collect_information_about_your_server"></span>
==Sammeln Sie Informationen über Ihren Server==

Sie müssen die folgenden Dinge wissen, um LimeSurvey korrekt auf Ihrem Webserver zu installieren:
*Ihre beabsichtigte Website-URL, auf der sich Ihre Skripte befinden (z. B. „http://my.domain.com/limesurvey“).
*Der physische Festplattenspeicherort auf Ihrem Server, auf dem sich Ihre Skripte befinden (z. B. „/home/usr/htdocs/limesurvey“).
*Der IP-/Netzstandort Ihres Datenbankservers (z. B. „localhost“).
*Wenn Ihr Datenbankserver einen nicht standardmäßigen Port verwendet, finden Sie heraus, um welchen Port es sich handelt.
*Ihren Benutzernamen und Ihr Passwort für Ihren Datenbankserver.
*Bei den meisten Anbietern können Sie die Datenbank nicht vom Skript erstellen lassen, sondern müssen dies selbst tun. Wenn Sie einen solchen Anbieter nutzen, legen Sie bitte selbst eine Datenbank (z.B. ''limesurvey'') an.

<span id="Upload_the_files_to_your_web_server"></span>
==Laden Sie die Dateien auf Ihren Webserver hoch==

Stellen Sie mit Ihrem FTP-Programm (z. B. FileZilla) eine Verbindung zu Ihrem Webserver her und erstellen Sie ein Verzeichnis zum Speichern Ihrer Skripte. Laden Sie dann die Dateien unter Verwendung der Verzeichnisstruktur hoch, in der sie sich befinden. Stellen Sie sicher, dass Sie die Dateien „im Binärmodus hochladen“ (überprüfen Sie die Einstellungen Ihres FTP-Programms). Bitte beachten Sie, dass das Hochladen im ASCII-Modus zu ungewöhnlichen Fehlern führen kann (z. B. Fehler „Klasse nicht gefunden“ während der Installation) und Bilder möglicherweise nicht korrekt hochgeladen werden.

<span id="Set_directory_permissions"></span>
==Verzeichnisberechtigungen festlegen==

Damit das Skript ordnungsgemäß funktioniert, benötigt es bestimmten Zugriff auf einige Verzeichnisse – dies gilt insbesondere für Linux/*nix-Systeme.
*Das Verzeichnis „/limesurvey/tmp“ (und alle seine Unterverzeichnisse und Dateien) werden für Importe und Uploads verwendet und sollten für Ihren Webserver auf "Lesen & Schreiben“ eingestellt sein.
*Das '''"/limesurvey/upload/"'' Verzeichnis (und alle seine Unterverzeichnisse und Dateien) muss auch ''Lesen & Schreiben'' für Ihren Webserver haben, um den Upload von Bildern und Mediendateien zu ermöglichen.
*Das Verzeichnis „/limesurvey/application/config/“ benötigt außerdem "Lesen und Schreiben"-Berechtigungen für Ihren Webserver.
*Die anderen Verzeichnisse können auf ''Schreibgeschützt'' gesetzt werden. Möglicherweise möchten Sie unter Linux/Unix die Berechtigungen für jede Datei im Verzeichnis /limesurvey/admin auf „Schreibgeschützt“ setzen.

{{Alert|Wenn Sie Linux verwenden, hängt das Festlegen von Berechtigungen von Ihrer Webserverkonfiguration ab. Wenn Sie beispielsweise Apache HTTPD unter CentOS verwenden, geben Sie '''chmod -R 755 ein<directory> ; chown -R Apache<directory> '''. Dadurch erhält jeder Lesezugriff und Ihr Webserver erhält die Berechtigung zum Schreiben. Weitere Informationen zu Linux-Berechtigungen finden Sie unter [https://www.linux.com/learn/tutorials/309527-understanding-linux-file-permissions folgendem Link].}}

<span id="Create_a_database_user"></span>
==Erstellen Sie einen Datenbankbenutzer==

LimeSurvey erstellt eine Datenbank und die darin enthaltenen Tabellen. Dazu benötigt es den Benutzernamen und das Passwort eines Datenbankbenutzers. Wir empfehlen generell, einen Datenbankbenutzer mit den folgenden Berechtigungen anzulegen:

- MySQL: AUSWÄHLEN, ERSTELLEN, EINFÜGEN, AKTUALISIEREN, LÖSCHEN, ALTER, DROP, INDEX

- PostgreSQL: SELECT, INSERT, UPDATE, DELETE, TRUNCATE, TRIGGER

- Microsoft SQL Server: „Unbekannt – wenn Sie diese Informationen finden können, vervollständigen Sie sie bitte.“

<span id="Run_the_installation_script"></span>
==Führen Sie das Installationsskript aus==

'''Gehen Sie zu "example.org/limesurvey/admin"'''. Wenn Sie alles richtig konfiguriert haben, sollte das LimeSurvey-Installationsprogramm starten – folgen Sie einfach den Anweisungen. Sie werden gefragt, ob Sie die Datenbank und/oder die Tabellen innerhalb der Datenbank erstellen möchten. LimeSurvey erstellt dann die benötigten Tabellen in der Datenbank.

<span id="Connect_to_the_administration_script_for_the_first_time"></span>
==Zum ersten Mal eine Verbindung zum Administrationsskript herstellen==

Sie sind fertig, wenn die Installation abgeschlossen ist! Öffnen Sie Ihren Browser und geben Sie die URL zur LimeSurvey-Administration ein. Angenommen, Sie haben „limesurvey“ als Verzeichnisnamen zum Speichern der Dateien verwendet, dann lautet das etwa „http://www.example.com/limesurvey/admin“.

Sie sollten einen Anmeldebildschirm erhalten. Die Standard-Anmeldeinformationen (sofern sie während der Installation nicht geändert wurden) sind:

<syntaxhighlight lang='html'>

Benutzer: admin
Passwort: Passwort

</syntaxhighlight>

Nach der Anmeldung werden Sie aufgefordert, das Standardpasswort zu ändern. Viel Spaß!

<span id="Further_configuration"></span>
==Weitere Konfiguration==

===Caching===

LimeSurvey verwendet standardmäßig den Yii-Dateicache, kann jedoch für die Verwendung anderer Cache-Engines konfiguriert werden. Mögliche weitere Caches sind:

* Memcached
* Redis
* WinCache
* XCache

Eine vollständige Beschreibung finden Sie in der [https://www.yiiframework.com/doc/api/1.1/CCache Yii-Dokumentation].

Seit LimeSurvey 4.0.0 haben Sie auch die Möglichkeit, Berechnungen im ExpressionScript zwischenzuspeichern. Dies kann je nach Komplexität der Umfrage zu einer erheblichen Beschleunigung führen. Um den Emcache zu aktivieren, fügen Sie Folgendes in Ihre config.php-Datei (Komponenten-Array) ein:

<syntaxhighlight lang="php">
'emcache' => array('class' => 'CFileCache'),
</syntaxhighlight>

Wie beim Haupt-Yii-Cache können auch andere Cache-Systeme verwendet werden.

{{Hinweis| Der Emcache ist nicht mit randomisierten Umfragen kompatibel und wird in solchen Fällen automatisch deaktiviert.}}

<span id="What_if_I_have_problems..."></span>
==Was ist, wenn ich Probleme habe...==

Wie bei allen Computerprogrammen funktionieren die Dinge meistens genau so, wie es in den Anweisungen steht, aber manchmal funktioniert es einfach nicht. Es gibt zu viele mögliche Gründe dafür, dass die Dinge nicht nach Plan laufen, als dass ich sie hier beschreiben könnte. Wenn Sie Probleme haben, lesen Sie zunächst die [[Installations-FAQ]]. Wenn Sie Ihre Antwort dort nicht finden, posten Sie bitte Ihr Problem und etwaige Fehlermeldungen in den [https://www.limesurvey.org/forum LimeSurvey-Foren] und öffnen Sie ein [https://www.limesurvey.org/contact-us Supportticket] (nur für Kunden, die LimeSurvey Cloud verwenden) oder treten Sie unserem [https://discord.gg/DEjguXn Discord-Kanal] bei.

Translations:Installation - LimeSurvey CE/16/de

2025-01-23T11:50:33Z

Mazi: Fixed invalid link

LimeSurvey sollte mit den meisten Hosting-Unternehmen zusammenarbeiten, die PHP und MySQL anbieten. Wenn Sie eine fertig installierte Version von LimeSurvey wünschen, können Sie [https://www.limesurvey.org/editions-and-prices/limesurvey-pro/editions-and-prices-professional LimeSurvey Cloud] ausprobieren, oder schauen Sie sich unsere [https://www.limesurvey.org/manual/LimeSurvey-compatible_hosting_companies/de Liste der LimeSurvey-kompatiblen Hosting-Unternehmen] an.

Installation - LimeSurvey CE

2025-01-23T11:48:40Z

Mazi: Fixed typo, added link

<languages />
<translate>


__TOC__


<div class="simplebox"> Note: These installation instructions are for version 2.0 or later. Older instructions for 1.92 can be found [[Installation Version 1.92 or older|here]] and update instructions can be found [[Upgrading from a previous version|here]]. </div>

==General== 


The LimeSurvey project provides two ways to install LimeSurvey:
*On your webserver:<br />In this case, just follow the instructions on this page starting with step 1.


*On your local Windows PC:<br />You usually only want to install LimeSurvey on your local PC if you want to create surveys locally (mainly for speed or development/test reasons) and upload them later to your live LimeSurvey installation on a web server. For this purpose, we have prepared a special LimeSurvey package which includes the web server, the database, the LimeSurvey application, and [[Installation of the LimeSurvey XAMPP package|instructions how to install it]].

==Make sure you can use LimeSurvey on your website== 


Make sure your server meets the following additional requirements.


{{Note|The minimum set of requirements will also be checked during the installation process!}}


The minimum set of requirements for '''LimeSurvey 6.x''':
* Minimum 250 MB disk space.
* MariaDB 10.3.38 or later '''OR''' MySQL 8 or later '''OR''' Microsoft SQL Server 2016 or later '''OR''' Postgres 12 or later.
* PHP version requirements:
** LS 6.x from PHP 7.4.x to 8.3.x
** LS 5.x from PHP 7.2.5 to 8.0.x
** LS 3.x from PHP 5.5.9 to 7.4.x
* php.ini `short_open_tag` setting should be set to `ON`
* The following PHP modules/libraries should be enabled:
** [[Installation FAQ#Requirements page#What is the mbstring (Multibyte String Functions) library|mbstring (Multibyte String Functions)]] extension library.
** PDO database driver for MySQL (pdo_mysql or pdo_mysqli) or Postgres (pdo_pgsql) or MSSQL ([https://php.net/manual/en/ref.pdo-sqlsrv.php pdo_sqlsrv] for Windows and [http://www.php.net/manual/en/ref.pdo-dblib.php pdo_dblib] for Linux).
** Also, we assume in general that all PHP default libraries are enabled
*** hash
*** session
*** openssl or mcrypt
*** fileinfo
*** SimpleXML
*** etc …


<div class="simplebox"> Note: If you are connecting from Linux to a MSSQL database on a Windows server using the dblib PDO driver, then the underlying FreeTDS needs to be set up correctly. Check out the [[Troubleshooting]] page for more information.</div>


Optional PHP Extensions:
* '''GD-Library''' '''with FreeType support''' installed is needed for captchas, nice charts in statistics or to upload images via the HTML editor - see [https://php.net/manual/image.setup.php PHP GD-Library Extension documentation]
* '''IMAP''' (pretty standard) is needed for the [[Email bounce tracking system|email bounce tracking system]] - see [https://php.net/manual/imap.setup.php PHP IMAP Extension documentation]
* '''LDAP''' installed is needed to import survey participants using LDAP - see [https://php.net/manual/en/book.ldap.php PHP LDAP Documentation]
* '''Zip''' (pretty standard) is needed for template upload, import of .zip archived resources, and excel export - see [https://php.net/manual/zip.setup.php PHP Zip Extension documentation]
* '''Zlib''' (pretty standard) is needed for the [[ComfortUpdate]] - see [https://php.net/manual/zlib.setup.php PHP Zlib Extension documentation]


In most cases, your web server provider or system administrator will be able to help you out with these optional components.


If you want to run Microsoft's IIS server, taking a look at [[Installation on XP with IIS]] might also help.


===Browser compatibility===
'''For the survey-taking side''', we currently support Edge and all newer comparable browsers like FF, Chrome, Opera etc. with activated JavaScript.


'''For the administration part''', we currently support Edge and all newer comparable browsers like FF, Chrome, Opera etc. with activated JavaScript.


====Screen sizes====
We support any reasonable screen size for survey taking (360px x 640px and up).
The minimum supported screen resolution for the LimeSurvey administration page is 1280px x 1024px.

===Hosting for LimeSurvey=== 


LimeSurvey should work with most hosting companies that provide PHP and MySQL. If you want a ready-installed version of LimeSurvey, you could try [https://www.limesurvey.org/editions-and-prices/limesurvey-pro/editions-and-prices-professional LimeSurvey Cloud] or check [https://www.limesurvey.org/manual/LimeSurvey-compatible_hosting_companies/en other hosting providers].

==Download the LimeSurvey package== 


[https://community.limesurvey.org/downloads/ Download] the latest stable LimeSurvey zip package (there are also gzip, bz2 and 7zip packages available for your convenience) and save it to your local disk.

==Unpack the LimeSurvey package== 


Uncompress the zip file into a dedicated directory/folder using your preferred compression software. When you uncompress the file make sure that you uncompress the directory structure with the files (this is default behavior for most compression programs). The path name for the installation directory should not include '(' or ')' special characters, but it may include the '''space''' character.

==Collect information about your server== 


You will need to know the following things to install LimeSurvey on your web server correctly:
*Your intended website URL where your scripts will reside (e.g. ''http://my.domain.com/limesurvey'').
*The physical disk location on your server where your scripts will reside (e.g. ''/home/usr/htdocs/limesurvey'').
*The IP/net location of your database server (i.e. ''localhost'').
*If your database server uses a non-standard port, find out which port it is.
*Your user name and password for your database server.
*With most providers you can't let the script create the database, but have to do it yourself. If you are using such a provider, please create a database (for example ''limesurvey'') yourself.

==Upload the files to your web server== 


Using your FTP program (e.g. FileZilla), connect to your web server and create a directory to store your scripts. Then upload the files using the directory structure they are in. Make sure you '''upload the files in binary mode''' (check the settings of your FTP program). Please note that uploading in ASCII mode can lead to uncommon errors (e.g. 'class not found' error during installation), also images may not be uploaded correctly.

==Set directory permissions== 


For the script to work properly it needs certain access to some directories - this applies especially to Linux/*nix systems.
*The '''"/limesurvey/tmp"''' directory (and all its subdirectories and files) are used for imports & uploads and should be set to ''Read & Write'' for your webserver.
*The '''"/limesurvey/upload/"''' directory (and all its subdirectories and files) must also have ''Read & Write'' for your webserver in order to enable picture and media files upload.
*The '''"/limesurvey/application/config/"''' directory also needs ''Read & Write'' permissions for your webserver.
*The other directories can be set to ''Read Only''. You may wish in Linux/Unix to set the permissions on each file within the /limesurvey/admin directory to ''Read Only''.


{{Alert|If you are using Linux, then setting permissions depends on your webserver configuration. For example, if you use Apache HTTPD on CentOS, type '''chmod -R 755 <directory> ; chown -R apache <directory>'''. This will give everyone access to read, and your webserver will have the permission to write. Check the [https://www.linux.com/learn/tutorials/309527-understanding-linux-file-permissions following link] for more information on Linux permissions.}}

==Create a database user== 


LimeSurvey will create a database and the tables inside it. To be able to do this, it will need the user name and password of a database user. We generally recommend creating a database user with the following permissions:


- MySQL: SELECT, CREATE, INSERT, UPDATE, DELETE, ALTER, DROP, INDEX


- PostgreSQL: SELECT, INSERT, UPDATE, DELETE, TRUNCATE, TRIGGER


- Microsoft SQL Server: ''Unknown - if you can find out this information, please complete it''.

==Run the installation script== 


'''Go to "example.org/limesurvey/admin"'''. If you configured everything correctly, the LimeSurvey installer should be starting - just follow the instructions. You will be asked whether you wish to create the database and/or create the tables inside the database. LimeSurvey will then create the needed tables in the database.

==Connect to the administration script for the first time== 


You are done when the installation finishes! Open your browser and enter the URL to the LimeSurvey administration. Assuming you used 'limesurvey' as the directory name to store the files in, this will be something like "http://www.example.com/limesurvey/admin".


You should get a login screen. The default login credentials (if they have not been changed during the installation) are:


<syntaxhighlight lang='html'>


User: admin
Password: password


</syntaxhighlight>


You will be prompted to change the default password after you logged in. Have fun!

==Further configuration== 

===Caching=== 


LimeSurvey uses the Yii file cache by default, but it can be configured to use other cache engines. Possible other caches are:


* Memcached
* Redis
* WinCache
* XCache


Please see the [https://www.yiiframework.com/doc/api/1.1/CCache Yii documentation] for full description.


Since LimeSurvey 4.0.0 you also have the possibility to cache calculations in the ExpressionScript. This can provide a significant speed-up depending on survey complexity. To enable the emcache, add this in your config.php file (components array):


<syntaxhighlight lang="php">
'emcache' => array('class' => 'CFileCache'),
</syntaxhighlight>


As with the main Yii cache, other cache systems can be used.


{{Note| The emcache is not compatible with randomized surveys, and will be automatically turned off in such cases.}}

==What if I have problems...== 


Like all computer programs, most of the time things will work just like the instructions say, but sometimes they just won't. There are too many possible reasons for things not going according to plan to describe here. If you have trouble, first check out the [[Installation FAQ]]. If you don't find your answer there, please post your problem and any error messages in the [https://www.limesurvey.org/forum LimeSurvey forums], open a [https://www.limesurvey.org/contact-us support ticket] (only for customers using LimeSurvey Cloud), or join our [https://discord.gg/DEjguXn Discord channel].

</translate>

TwoFactorAdminLogin

2024-06-18T08:34:23Z

Mazi: Removed details about how to download plugin

<languages />
<translate>


__TOC__

=Introduction= 


'''2-Factor-Authentication''' (2FA) is a way to add additional security to your account. It is called "two-factor-authentication" because two verification methods are used to access your account. The first "factor" is your usual password that is standard for any account. The second "factor" is a verification code retrieved from a 2FA application either from your computer or mobile device. For more details about 2FA and its importance, please visit the following [https://en.wikipedia.org/wiki/Multi-factor_authentication article].


If enabled, a 6 digits code (default value) has to be introduced when you log in to your LimeSurvey instance:


<center>[[File:2FA_login.png]]</center>


To learn more about this functionality, please continue reading below.

=How to install the 2FA plugin= 

Since version 6.x the plugin is a core plugin. So just visit the [[Plugin manager|Plugin Manager]] page and enable it from there (see below for more details).

=Activate the 2FA plugin= 


To activate your 2FA plugin, access your LimeSurvey instance, and activate it from your [[Plugin manager|Plugin Manager]]:


<center>[[File:2fa_activate.png]]</center>


To check the default settings, please click on "Configure".

==Plugin settings== 


The configuration page contains the following settings:


<center>[[File:2FA plugin configuration.png]]</center>


*'''Issuer:''' The text typed in this box will be displayed in the app as issuer name.
*'''Digits:''' The number of digits the resulting codes will be. Please leave it at 6 for Google Authenticator.
*'''TimePeriod:''' The number of seconds a code will be valid. If you use Google Authenticator, please leave it to 30.
*'''Discrepancy:''' The amount of discrepancy is allowed for the client after the TimePeriod expires (seconds)


*'''Algorithm:''' The algorithm used to generate a hash:
**''SHA1 (Default)''
**''SHA256''
**''MD5''


*'''Force 2FA:''' If you enable it, all instance users have to create a 2FA token after they log in again into the LimeSurvey instance.


Don't forget to click on "Save" after updating your 2FA configuration.

=2-Factor-Settings= 


Once you activated the plugin, a new menu item will be displayed on the top bar:


<center>[[File:2fa_location.png]]</center>


The dropdown menu includes the following two options:


*[[TwoFactorAdminLogin#2FA-Setting|2FA-Setting]]: Users can enable and manage their 2FA settings.
*[[TwoFactorAdminLogin#2FA-Administration|2FA-Administration]]: With the right permission, you can visualize whether the other instance users use 2FA or not.

==2FA-Setting== 


If you haven't created any 2FA-token yet, the following page will be displayed:


<center>[[File:2fa_register.png]]</center>


If you decide to create a 2FA-token, click on "Register 2FA now". You will be prompted by the following message box:


<center>[[File:2fa_user_settings.png]]</center>


To enable 2FA:
#Select the 2FA authentication method. By default, five different 2FA types are provided: Google Authenticator (default), Authy, YubiKey, Authenticator Plus, Duo, and HDE OTP.
#Scan the QR-code with your mobile phone. For a list of application recommendations, check this [https://en.wikipedia.org/wiki/Help:Two-factor_authentication#Enabling_2FA_on_smartphones_and_tablet_computers article].
#Enter the confirmation key displayed in your 2FA application.


{{Note|From a technical perspective, you can use any 2FA application that supports TOTP (Time-based One-Time Password algorithm). For more information on what TOTP is, please check this [https://en.wikipedia.org/wiki/Time-based_One-time_Password_algorithm article].}}


To confirm the creation of your 2FA-token, click on "Create 2FA binding".


<hr width="50%" style="margin:auto">


Once done, the following two options will be displayed in your personal 2FA settings:


<center>[[File:2fa_unset.png]]</center>


* '''Unset 2FA:''' Confirm your action to delete the 2FA-token associated to your account.


{{Note|Please note that you will need to re-authenticate again if "Force 2FA" is enabled from the plugin settings.}}


* '''Reset 2FA:''' If this option is selected, you will be asked to scan the new QR-code and introduce the new confirmation Key.

==2FA-Administration== 


With the necessary permissions, you can have access to the 2FA user management panel from where you can check how many users activated 2FA.


<center>[[File:2fa_user_management.png]]</center>


*'''Action:''' A red trash button is displayed in this column next to the users that have enabled 2FA. If someone asks to get the 2FA-token reset because he/she cannot log in anymore into your instance, you can delete the 2FA-token associated with his/her account from here.
*'''Username:''' All the instance users are listed under this column.
*'''Full name:'''The full name typed in here by your users is displayed in this field.
*'''Email:''' The email address corresponding to your users.
*'''2FA-Method:''' The 2FA-method chosen by each user.
*'''2FA enabled:''' If "1", it means that 2FA is enabled for the respective user.

=FAQs= 

==I am a super administrator and locked myself out. How can I delete my 2FA-token?== 


You will need access to your database and truncate the 2FA-related column.

==How can I enforce 2FA to all my users?== 


Enable "Force 2FA" from the plugin configuration menu.

==From where can I download the plugin?== 


Please access [https://www.limesurvey.org/limestore LimeStore] and [https://www.limesurvey.org/limestore?view=extensiondetails&id=49 download the plugin from download it from here]. To be able to download it, you need to hold a Premium package

==I use LimeSurvey Cloud. Do I have to purchase the plugin?== 


No. The plugin is already part of the core LimeSurvey plugins - you can enable it by accessing the plugin menu.

</translate>

StatFunctions

2024-02-26T09:59:05Z

Mazi: Added note about scanning files to use the plugin

{{FeatureStarting|4.1.0}}

=Usage=

Functions for the expression manager to count some statistics data :

* statCount(QuestionCode.sgqa[, submitted = 1][, self = true]) : count the number of already submitted answered questions by QuestionCode. You can count the number of submitted (= completed) surveys with statCount('sid') for example.
* statCountIf(QuestionCode.sgqa, value[, submitted = 1][, self = true]) : count the number of responses where answer to question QuestionCode equals value. The comparison uses [https://www.yiiframework.com/doc/api/1.1/CDbCriteria#compare-detail Yii compare], you can use <, >, >=, <=, <> operator at start of your value.

You can find an example of the usage of these 2 functions in: [https://github.com/LimeSurvey/LimeSurvey/blob/master/tests/data/surveys/survey_archive_statCountFunctionsTest.lsa survey_archive_statCountFunctionsTest] inside the test directory.

[[File:StatFunctionsSample.png]]

This plugin uses the [[ExpressionManagerStart]] plugin and it creates two functions. These 2 functions don't use javascript, so '''the check is done only when the respondent moves ahead in the survey'''.

Expression script don't have true and false as reserved word, then this strings are checked as variables name. You can use 1, 0 or the result of an expression for the second parameter. remind than "false" is evaluated a true in boolean.

{{Alert|Before using these functions the plugin must be activated in [[Plugin_manager#General|Plugin Manager]]. Scan the files there and then install and activate the plugin.}}

=Example=

* count number of submitted response : {statCount("id")}
* count number of responses (submitted or not) : {statCount("id", 0)}
* number of responses where respondent stopped at page 1 : {statCountIf("lastpage", 1, 0)}
* number of submitted responses with startlanguage "en" : {statCountIf("startlanguage", "en", 1)}
* number not completed responses to this survey : {sum(statCount("id", 0),statCount("id")*-1)}
* number of responses submitted in 2022 : {statCountIf("submitted", ">=2022-01-01")}
* number of submitted responses with Y at a YesNo question title {statCountIf(YesNo.sgqa, "Y")}
* number of responses (submitted or not) with Answer A1 at a Q01 question title {statCountIf(Q01.sgqa, "A1", 0)}
* Validate unicity on a short text question (not submitted) {statCountIf(self.sgqa, self.NAOK, 0, 1)} (only when move next page)

[[Category:Plugins]][[Category:Core Plugins]]

Expression Manager

2024-02-26T09:57:51Z

Mazi: Adjusted link syntax

<languages /> <translate>


__TOC__


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

=Quick Start Tutorial= 

==Overview== 


When customizing your surveys, you typically need a way to specify the following:
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked
#'''Tailoring/Piping''' - how to phrase the question (such as referring to prior answers, or conjugating sentences based upon the number or gender of your subjects), or how to generate custom reports (like assessment scores or tailored advice).
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern


Expression Manager (EM) provides an intuitive way to specifying the logic for each of those features. Nearly anything that you can write as a standard mathematical equation is a valid expression, even if you are calling functions. EM currently provides access to 80 functions, and can be easily extended to support more. It also lets you access your variables using human-readable variable names (rather than SGQA names).


The following sections show the main places where Expression Manager is used

==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 when 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 shown, 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).


[[File:tutorial1.jpg]]


Relevance is shown and editable in the following places:

===Viewing / Editing Question-Level Relevance=== 


This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.


[[File:tutorial2.jpg]]


This is the edit screen for the BMI question.


[[File:tutorial3.jpg]]


Note that you do not use the curly braces when you enter a Relevance Equation.

===Viewing / Editing Group-Level Relevance=== 


This is a sample census survey. 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 (so it is shown for the second person cohabitating with you), and also only shows if you specified how Person One is related to you (p1_rel).


[[File:tutorial4.jpg]]


As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}). 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.


Here is the screen for editing the group-level relevance for that question:


[[File:tutorial5.jpg]]


Note that you do not use the curly braces when you enter a Relevance Equation.

==Tailoring/Piping== 


EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need 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 upon 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.

===Conditional Equations=== 


The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height and weight in metric or non-metric units.


[[File:tailoring7.jpg]]


Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiply the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.


BMI computes the weight formula as {weight_kg / (height_m * height_m)}.


Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")


Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View


[[File:tailoring8.jpg]]


From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.


[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports=== 


<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>


This example shows the BMI report.


[[File:tailoring10.jpg]]


Here is the edit window for the same question.


[[File:tailoring11.jpg]]


As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.


[[File:tailoring12.jpg]]


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.

==Validation== 


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. You continue to enter those advanced question options as usual. However, now 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 option is always considered an expression, you do not use curly braces when specifying it.


The [[Expression Manager sample surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction= 


LimeSurvey uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).


This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions== 
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', participant data, and response data.
#*You also have easier access to questions, answers, and their properties.
#'''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.
#*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
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?== 


The short answer is No (but also yes).


EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.


However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.


This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?== 


Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.


Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?== 


Here is a list of pros and cons of each style:


{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}


The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?== 


Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - 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
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.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
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (boolean (can be different in PHP and JS))
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?== 


Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*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 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)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

=Getting Started= 


The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[ExpressionScript sample surveys|sample surveys]].
*Explore the [[ExpressionScript How-tos|use cases and HowTos]] and [[ExpressionScript examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)= 

==Conditions => Relevance== 


Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring== 


Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==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.

==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.

==Equations== 


Equations were not supported without fancy JavaScript.

==Equation Question Type== 


Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?= 


The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)== 


EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance=== 


Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.


Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.


Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:


{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}


The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.


As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance=== 


Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping=== 


Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).


Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations=== 


There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.


This solves a common request for storing Assessment scores within the database

==Syntax== 


Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).


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">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>


<div id="EMsyntax">Expression Manager supports the following syntax:</div>
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

=== Operators === 


EM syntax follows normal operator precedence:


{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

==== Warning with plus operator (+) ==== 


For consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, '''we recommend using the join() function for concatenation and sum() function for addition''', as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

==== Warning with mismatch between number and string and alphabetic comparison ==== 


When you want to compare value with relative or equality comparisons, pay attention to type mismatch. Value entered by user or answer code selected can be used as number if it's clearly a number.
If you surround one of the values with <code>"</code>it will force the comparison as text (alphabetic compare). If you want to compare numerically, never surround the number with quotation marks, <code>"</code>.


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>.

===Caution about using Assignment Operator (=)=== 


Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you should create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.


To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

===Using Assignment Operator=== 
The main reasons you may want to use assignment are:
* You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
* You need to forcibly change the response to a previous question based upon a later response
* You need complex quota : using one hidden single choice for quota and set it using assignment
* etc...


You can use all expression manager system for this purpose.


{{Alert|Assignment is done only in PHP. This doesn't update any values on the same page, but only when the user navigates with next, previous, save ….}}


{{Alert|If you don't use an [[Question_type_-_Equation|equation question]] type for this purpose: the assignment is done only after the logic of the current page is done. The recommended method is to always use an [[Question_type_-_Equation|equation question]].}}


Some example:
* Set answer to a short text question in lowercase : <code>{QCODE=strtolower(QCODE.NAOK)}</code>
* Set a default answer to an array question type at start of a survey : <code>{Q1_SQ1=((is_empty(Q1_SQ1.NAOK),"A99",Q1_SQ1.NAOK)}</code>
* Set a default answer to an array texts question type at start of a survey : <code>{Q1_SQY1_SQX1 = ((is_empty(Q1_SQY1_SQX1.NAOK),"Inserted answer", Q1_SQY1_SQX1.NAOK)}</code>
* Set an answer with condition : <code>{QCODE=if(YesNo="Y","A1","")}</code>

== XSS security == 


With XSS enable, some expression manager system can not be used :
* starting a HTML tag in expression but ending in another expression
* use a complex expression in URL.


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><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>

==Access to Variables== 


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).
*[[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}.
*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 addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.


<div class='simplebox'>
'''Important:''' It is only safe to refer to variables that occur in preceding pages or questions.
</div>


Furthermore, Expression Manager lets you access many properties of the Question:


{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== HTML editor issue=== 


{{Alert|This issue is fixed after 2.05 build 140803}}


If you use HTML editor, some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;


If you use HTML editor you need to use :
* and for &
* lt for <
* le for <=
* gt for >
* ge for >=

==Qcode Variable Naming== 


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


For '''comment''' and '''other''', question code are QuestionCode_comment and QuestionCode_other


{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F, other|| || ||{Q22_E}, {Q22_other}||{Q22_E.shown}, {Q22_other.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables== 


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 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''


''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)


''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g., from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*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 ....
*nosq_X - where X is a row or column identifier. Only subquestions not matching pattern X are selected. Note that search is done on complete code identifier, then nosq_X match and does not include subquestions nX, X, Xn


Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}


You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}


The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''


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


Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}


The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.


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 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.

==Usage of NAOK== 


NAOK --> "Not Applicable" (NA) is alright (OK)


Using NAOK, means that all or some of the variables are irrelevant (e.g. "Not Applicable" (NA) is alright (OK)).


When you put some variable from question in any equation : if this question (or subquestion) is hidden by condition : this disable all equation.


For example : count(Q1_SQ1,Q1_SQ2,Q1_SQ3,Q1_SQ4) give always an empty string if one subquestion of Q1 is filtered.
To count the number of checked subquestion in such question can be count(Q1_SQ1.NAOK,Q1_SQ2.NAOK,Q1_SQ3.NAOK,Q1_SQ4.NAOK). If the sub question is hidden :Expression manager return an empty string.


Without NAOK : if one question or one subquestion is hidden : Expression Manager return always an empty string, same to return false.


The .shown always use the NAOK system (empty string if hidden) but if you need the code of the answer : it's always a good idea to add .NAOK after the question code. Except if you need it and know what you do.


Another example and information is provided at [[#Overriding_Cascading_Conditions|Overriding Cascading Conditions]]

==Access to Functions== 


Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions=== 


The following functions are currently available:


{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank) questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal to the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if{{UpdatedIn|3.0.2}}||Excel-style if(test,result_if_true<nowiki>[</nowiki>,result_if_false = ""<nowiki>]</nowiki>)||if(test,result_if_true<nowiki>[</nowiki>,result_if_false = ""<nowiki>]</nowiki>)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|listifop{{NewIn|3.16.1}}||Return a 'glue'-separated list of the specified question property (retProp) from questions in the list which pass the criteria (cmpProp op value)||string listifop(cmpProp, op, value, retProp, glue, sgqa1, sgqa2, ... sgqaN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager sample surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive unicode string (starting by 0, return false if not found)|||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of an unicode string (starting by 0, return false if not found)||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle<nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of an unicode string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered=== 


Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.


{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)|| [[ExpressionAnswerOptions|Core plugin ExpressionAnswerOptions ]] ||
|-
|getAnsOption(X,Y)|| [[ExpressionAnswerOptions|Core plugin ExpressionAnswerOptions ]] ||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local== 


In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions== 


If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant


{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions=== 


Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.


To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).


So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).


The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?== 


Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):


{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}


All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.


Expression Manager provides this functionality by surrounding each expression with a named <nowiki><span></nowiki> element. Every time a value changes, it recomputes the expression that should appear in that <nowiki><span></nowiki> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality== 


{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting= 


To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting== 


{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|bold red text||style='color:#ff0000; background-color:#eee8aa'|'''Sample'''||An error||Some explanation on error||Can be an unknow variable or an error in function, .... Survey can be totally broken, this don't show to public user.
|-
|blue text||style='color:#0000ff; background-color:#eee8aa'|Sample||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|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.
|-
|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.
|-
|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 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.
|-
|red text||style='color:#ff4500; background-color:#eee8aa'|Sample||assignment operator (=) ||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading= 

==[[Expression Manager sample surveys|Expression Manager sample surveys]]== 

==[[ExpressionScript How-tos|Use Cases and HowTos]]== 

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

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

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

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

</translate>

Expression Manager

2024-02-26T09:55:43Z

Mazi: Link fix

<languages /> <translate>


__TOC__


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

=Quick Start Tutorial= 

==Overview== 


When customizing your surveys, you typically need a way to specify the following:
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked
#'''Tailoring/Piping''' - how to phrase the question (such as referring to prior answers, or conjugating sentences based upon the number or gender of your subjects), or how to generate custom reports (like assessment scores or tailored advice).
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern


Expression Manager (EM) provides an intuitive way to specifying the logic for each of those features. Nearly anything that you can write as a standard mathematical equation is a valid expression, even if you are calling functions. EM currently provides access to 80 functions, and can be easily extended to support more. It also lets you access your variables using human-readable variable names (rather than SGQA names).


The following sections show the main places where Expression Manager is used

==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 when 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 shown, 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).


[[File:tutorial1.jpg]]


Relevance is shown and editable in the following places:

===Viewing / Editing Question-Level Relevance=== 


This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.


[[File:tutorial2.jpg]]


This is the edit screen for the BMI question.


[[File:tutorial3.jpg]]


Note that you do not use the curly braces when you enter a Relevance Equation.

===Viewing / Editing Group-Level Relevance=== 


This is a sample census survey. 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 (so it is shown for the second person cohabitating with you), and also only shows if you specified how Person One is related to you (p1_rel).


[[File:tutorial4.jpg]]


As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}). 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.


Here is the screen for editing the group-level relevance for that question:


[[File:tutorial5.jpg]]


Note that you do not use the curly braces when you enter a Relevance Equation.

==Tailoring/Piping== 


EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need 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 upon 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.

===Conditional Equations=== 


The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height and weight in metric or non-metric units.


[[File:tailoring7.jpg]]


Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiply the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.


BMI computes the weight formula as {weight_kg / (height_m * height_m)}.


Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")


Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View


[[File:tailoring8.jpg]]


From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.


[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports=== 


<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>


This example shows the BMI report.


[[File:tailoring10.jpg]]


Here is the edit window for the same question.


[[File:tailoring11.jpg]]


As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.


[[File:tailoring12.jpg]]


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.

==Validation== 


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. You continue to enter those advanced question options as usual. However, now 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 option is always considered an expression, you do not use curly braces when specifying it.


The [[Expression Manager sample surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction= 


LimeSurvey uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).


This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions== 
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', participant data, and response data.
#*You also have easier access to questions, answers, and their properties.
#'''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.
#*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
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?== 


The short answer is No (but also yes).


EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.


However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.


This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?== 


Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.


Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?== 


Here is a list of pros and cons of each style:


{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}


The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?== 


Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - 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
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.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
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (boolean (can be different in PHP and JS))
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?== 


Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*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 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)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

=Getting Started= 


The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[ExpressionScript sample surveys|sample surveys]].
*Explore the [[ExpressionScript How-tos|use cases and HowTos]] and [[ExpressionScript examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)= 

==Conditions => Relevance== 


Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring== 


Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==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.

==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.

==Equations== 


Equations were not supported without fancy JavaScript.

==Equation Question Type== 


Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?= 


The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)== 


EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance=== 


Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.


Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.


Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:


{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}


The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.


As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance=== 


Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping=== 


Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).


Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations=== 


There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.


This solves a common request for storing Assessment scores within the database

==Syntax== 


Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).


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">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>


<div id="EMsyntax">Expression Manager supports the following syntax:</div>
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

=== Operators === 


EM syntax follows normal operator precedence:


{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

==== Warning with plus operator (+) ==== 


For consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, '''we recommend using the join() function for concatenation and sum() function for addition''', as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

==== Warning with mismatch between number and string and alphabetic comparison ==== 


When you want to compare value with relative or equality comparisons, pay attention to type mismatch. Value entered by user or answer code selected can be used as number if it's clearly a number.
If you surround one of the values with <code>"</code>it will force the comparison as text (alphabetic compare). If you want to compare numerically, never surround the number with quotation marks, <code>"</code>.


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>.

===Caution about using Assignment Operator (=)=== 


Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you should create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.


To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

===Using Assignment Operator=== 
The main reasons you may want to use assignment are:
* You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
* You need to forcibly change the response to a previous question based upon a later response
* You need complex quota : using one hidden single choice for quota and set it using assignment
* etc...


You can use all expression manager system for this purpose.


{{Alert|Assignment is done only in PHP. This doesn't update any values on the same page, but only when the user navigates with next, previous, save ….}}


{{Alert|If you don't use an [[Question_type_-_Equation|equation question]] type for this purpose: the assignment is done only after the logic of the current page is done. The recommended method is to always use an [[Question_type_-_Equation|equation question]].}}


Some example:
* Set answer to a short text question in lowercase : <code>{QCODE=strtolower(QCODE.NAOK)}</code>
* Set a default answer to an array question type at start of a survey : <code>{Q1_SQ1=((is_empty(Q1_SQ1.NAOK),"A99",Q1_SQ1.NAOK)}</code>
* Set a default answer to an array texts question type at start of a survey : <code>{Q1_SQY1_SQX1 = ((is_empty(Q1_SQY1_SQX1.NAOK),"Inserted answer", Q1_SQY1_SQX1.NAOK)}</code>
* Set an answer with condition : <code>{QCODE=if(YesNo="Y","A1","")}</code>

== XSS security == 


With XSS enable, some expression manager system can not be used :
* starting a HTML tag in expression but ending in another expression
* use a complex expression in URL.


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><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>

==Access to Variables== 


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).
*[[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}.
*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 addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.


<div class='simplebox'>
'''Important:''' It is only safe to refer to variables that occur in preceding pages or questions.
</div>


Furthermore, Expression Manager lets you access many properties of the Question:


{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== HTML editor issue=== 


{{Alert|This issue is fixed after 2.05 build 140803}}


If you use HTML editor, some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;


If you use HTML editor you need to use :
* and for &
* lt for <
* le for <=
* gt for >
* ge for >=

==Qcode Variable Naming== 


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


For '''comment''' and '''other''', question code are QuestionCode_comment and QuestionCode_other


{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F, other|| || ||{Q22_E}, {Q22_other}||{Q22_E.shown}, {Q22_other.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables== 


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 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''


''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)


''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g., from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*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 ....
*nosq_X - where X is a row or column identifier. Only subquestions not matching pattern X are selected. Note that search is done on complete code identifier, then nosq_X match and does not include subquestions nX, X, Xn


Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}


You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}


The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''


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


Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}


The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.


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 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.

==Usage of NAOK== 


NAOK --> "Not Applicable" (NA) is alright (OK)


Using NAOK, means that all or some of the variables are irrelevant (e.g. "Not Applicable" (NA) is alright (OK)).


When you put some variable from question in any equation : if this question (or subquestion) is hidden by condition : this disable all equation.


For example : count(Q1_SQ1,Q1_SQ2,Q1_SQ3,Q1_SQ4) give always an empty string if one subquestion of Q1 is filtered.
To count the number of checked subquestion in such question can be count(Q1_SQ1.NAOK,Q1_SQ2.NAOK,Q1_SQ3.NAOK,Q1_SQ4.NAOK). If the sub question is hidden :Expression manager return an empty string.


Without NAOK : if one question or one subquestion is hidden : Expression Manager return always an empty string, same to return false.


The .shown always use the NAOK system (empty string if hidden) but if you need the code of the answer : it's always a good idea to add .NAOK after the question code. Except if you need it and know what you do.


Another example and information is provided at [[#Overriding_Cascading_Conditions|Overriding Cascading Conditions]]

==Access to Functions== 


Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions=== 


The following functions are currently available:


{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank) questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal to the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if{{UpdatedIn|3.0.2}}||Excel-style if(test,result_if_true<nowiki>[</nowiki>,result_if_false = ""<nowiki>]</nowiki>)||if(test,result_if_true<nowiki>[</nowiki>,result_if_false = ""<nowiki>]</nowiki>)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|listifop{{NewIn|3.16.1}}||Return a 'glue'-separated list of the specified question property (retProp) from questions in the list which pass the criteria (cmpProp op value)||string listifop(cmpProp, op, value, retProp, glue, sgqa1, sgqa2, ... sgqaN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager sample surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive unicode string (starting by 0, return false if not found)|||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of an unicode string (starting by 0, return false if not found)||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle<nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of an unicode string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered=== 


Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.


{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)|| [[ExpressionAnswerOptions|Core plugin ExpressionAnswerOptions ]] ||
|-
|getAnsOption(X,Y)|| [[ExpressionAnswerOptions|Core plugin ExpressionAnswerOptions ]] ||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local== 


In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions== 


If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant


{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions=== 


Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.


To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).


So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).


The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?== 


Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):


{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}


All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.


Expression Manager provides this functionality by surrounding each expression with a named <nowiki><span></nowiki> element. Every time a value changes, it recomputes the expression that should appear in that <nowiki><span></nowiki> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality== 


{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting= 


To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting== 


{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|bold red text||style='color:#ff0000; background-color:#eee8aa'|'''Sample'''||An error||Some explanation on error||Can be an unknow variable or an error in function, .... Survey can be totally broken, this don't show to public user.
|-
|blue text||style='color:#0000ff; background-color:#eee8aa'|Sample||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|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.
|-
|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.
|-
|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 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.
|-
|red text||style='color:#ff4500; background-color:#eee8aa'|Sample||assignment operator (=) ||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading= 

==[[Expression Manager sample surveys|Expression Manager sample surveys]]== 

==[[ExpressionScript How-tos|Use Cases and HowTos]]== 

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

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

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

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

</translate>

Expression Manager

2024-02-26T09:54:45Z

Mazi: Fixed link

<languages /> <translate>


__TOC__


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

=Quick Start Tutorial= 

==Overview== 


When customizing your surveys, you typically need a way to specify the following:
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked
#'''Tailoring/Piping''' - how to phrase the question (such as referring to prior answers, or conjugating sentences based upon the number or gender of your subjects), or how to generate custom reports (like assessment scores or tailored advice).
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern


Expression Manager (EM) provides an intuitive way to specifying the logic for each of those features. Nearly anything that you can write as a standard mathematical equation is a valid expression, even if you are calling functions. EM currently provides access to 80 functions, and can be easily extended to support more. It also lets you access your variables using human-readable variable names (rather than SGQA names).


The following sections show the main places where Expression Manager is used

==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 when 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 shown, 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).


[[File:tutorial1.jpg]]


Relevance is shown and editable in the following places:

===Viewing / Editing Question-Level Relevance=== 


This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.


[[File:tutorial2.jpg]]


This is the edit screen for the BMI question.


[[File:tutorial3.jpg]]


Note that you do not use the curly braces when you enter a Relevance Equation.

===Viewing / Editing Group-Level Relevance=== 


This is a sample census survey. 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 (so it is shown for the second person cohabitating with you), and also only shows if you specified how Person One is related to you (p1_rel).


[[File:tutorial4.jpg]]


As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}). 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.


Here is the screen for editing the group-level relevance for that question:


[[File:tutorial5.jpg]]


Note that you do not use the curly braces when you enter a Relevance Equation.

==Tailoring/Piping== 


EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need 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 upon 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.

===Conditional Equations=== 


The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height and weight in metric or non-metric units.


[[File:tailoring7.jpg]]


Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiply the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.


BMI computes the weight formula as {weight_kg / (height_m * height_m)}.


Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")


Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View


[[File:tailoring8.jpg]]


From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.


[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports=== 


<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>


This example shows the BMI report.


[[File:tailoring10.jpg]]


Here is the edit window for the same question.


[[File:tailoring11.jpg]]


As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.


[[File:tailoring12.jpg]]


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.

==Validation== 


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. You continue to enter those advanced question options as usual. However, now 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 option is always considered an expression, you do not use curly braces when specifying it.


The [[Expression Manager sample surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction= 


LimeSurvey uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).


This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions== 
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', participant data, and response data.
#*You also have easier access to questions, answers, and their properties.
#'''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.
#*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
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?== 


The short answer is No (but also yes).


EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.


However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.


This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?== 


Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.


Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?== 


Here is a list of pros and cons of each style:


{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}


The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?== 


Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - 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
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.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
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (boolean (can be different in PHP and JS))
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?== 


Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*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 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)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

=Getting Started= 


The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[ExpressionScript sample surveys|sample surveys]].
*Explore the [[ExpressionScript How-tos|use cases and HowTos]] and [[ExpressionScript examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)= 

==Conditions => Relevance== 


Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring== 


Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==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.

==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.

==Equations== 


Equations were not supported without fancy JavaScript.

==Equation Question Type== 


Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?= 


The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)== 


EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance=== 


Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.


Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.


Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:


{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}


The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.


As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance=== 


Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping=== 


Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).


Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations=== 


There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.


This solves a common request for storing Assessment scores within the database

==Syntax== 


Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).


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">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>


<div id="EMsyntax">Expression Manager supports the following syntax:</div>
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

=== Operators === 


EM syntax follows normal operator precedence:


{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

==== Warning with plus operator (+) ==== 


For consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, '''we recommend using the join() function for concatenation and sum() function for addition''', as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

==== Warning with mismatch between number and string and alphabetic comparison ==== 


When you want to compare value with relative or equality comparisons, pay attention to type mismatch. Value entered by user or answer code selected can be used as number if it's clearly a number.
If you surround one of the values with <code>"</code>it will force the comparison as text (alphabetic compare). If you want to compare numerically, never surround the number with quotation marks, <code>"</code>.


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>.

===Caution about using Assignment Operator (=)=== 


Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you should create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.


To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

===Using Assignment Operator=== 
The main reasons you may want to use assignment are:
* You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
* You need to forcibly change the response to a previous question based upon a later response
* You need complex quota : using one hidden single choice for quota and set it using assignment
* etc...


You can use all expression manager system for this purpose.


{{Alert|Assignment is done only in PHP. This doesn't update any values on the same page, but only when the user navigates with next, previous, save ….}}


{{Alert|If you don't use an [[Question_type_-_Equation|equation question]] type for this purpose: the assignment is done only after the logic of the current page is done. The recommended method is to always use an [[Question_type_-_Equation|equation question]].}}


Some example:
* Set answer to a short text question in lowercase : <code>{QCODE=strtolower(QCODE.NAOK)}</code>
* Set a default answer to an array question type at start of a survey : <code>{Q1_SQ1=((is_empty(Q1_SQ1.NAOK),"A99",Q1_SQ1.NAOK)}</code>
* Set a default answer to an array texts question type at start of a survey : <code>{Q1_SQY1_SQX1 = ((is_empty(Q1_SQY1_SQX1.NAOK),"Inserted answer", Q1_SQY1_SQX1.NAOK)}</code>
* Set an answer with condition : <code>{QCODE=if(YesNo="Y","A1","")}</code>

== XSS security == 


With XSS enable, some expression manager system can not be used :
* starting a HTML tag in expression but ending in another expression
* use a complex expression in URL.


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><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>

==Access to Variables== 


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).
*[[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}.
*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 addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.


<div class='simplebox'>
'''Important:''' It is only safe to refer to variables that occur in preceding pages or questions.
</div>


Furthermore, Expression Manager lets you access many properties of the Question:


{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== HTML editor issue=== 


{{Alert|This issue is fixed after 2.05 build 140803}}


If you use HTML editor, some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;


If you use HTML editor you need to use :
* and for &
* lt for <
* le for <=
* gt for >
* ge for >=

==Qcode Variable Naming== 


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


For '''comment''' and '''other''', question code are QuestionCode_comment and QuestionCode_other


{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F, other|| || ||{Q22_E}, {Q22_other}||{Q22_E.shown}, {Q22_other.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables== 


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 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''


''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)


''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g., from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*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 ....
*nosq_X - where X is a row or column identifier. Only subquestions not matching pattern X are selected. Note that search is done on complete code identifier, then nosq_X match and does not include subquestions nX, X, Xn


Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}


You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}


The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''


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


Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}


The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.


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 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.

==Usage of NAOK== 


NAOK --> "Not Applicable" (NA) is alright (OK)


Using NAOK, means that all or some of the variables are irrelevant (e.g. "Not Applicable" (NA) is alright (OK)).


When you put some variable from question in any equation : if this question (or subquestion) is hidden by condition : this disable all equation.


For example : count(Q1_SQ1,Q1_SQ2,Q1_SQ3,Q1_SQ4) give always an empty string if one subquestion of Q1 is filtered.
To count the number of checked subquestion in such question can be count(Q1_SQ1.NAOK,Q1_SQ2.NAOK,Q1_SQ3.NAOK,Q1_SQ4.NAOK). If the sub question is hidden :Expression manager return an empty string.


Without NAOK : if one question or one subquestion is hidden : Expression Manager return always an empty string, same to return false.


The .shown always use the NAOK system (empty string if hidden) but if you need the code of the answer : it's always a good idea to add .NAOK after the question code. Except if you need it and know what you do.


Another example and information is provided at [[#Overriding_Cascading_Conditions|Overriding Cascading Conditions]]

==Access to Functions== 


Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions=== 


The following functions are currently available:


{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank) questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal to the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if{{UpdatedIn|3.0.2}}||Excel-style if(test,result_if_true<nowiki>[</nowiki>,result_if_false = ""<nowiki>]</nowiki>)||if(test,result_if_true<nowiki>[</nowiki>,result_if_false = ""<nowiki>]</nowiki>)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|listifop{{NewIn|3.16.1}}||Return a 'glue'-separated list of the specified question property (retProp) from questions in the list which pass the criteria (cmpProp op value)||string listifop(cmpProp, op, value, retProp, glue, sgqa1, sgqa2, ... sgqaN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager sample surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive unicode string (starting by 0, return false if not found)|||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of an unicode string (starting by 0, return false if not found)||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle<nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of an unicode string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered=== 


Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.


{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)|| [[ExpressionAnswerOptions|Core plugin ExpressionAnswerOptions ]] ||
|-
|getAnsOption(X,Y)|| [[ExpressionAnswerOptions|Core plugin ExpressionAnswerOptions ]] ||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local== 


In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions== 


If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant


{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions=== 


Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.


To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).


So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).


The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?== 


Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):


{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}


All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.


Expression Manager provides this functionality by surrounding each expression with a named <nowiki><span></nowiki> element. Every time a value changes, it recomputes the expression that should appear in that <nowiki><span></nowiki> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality== 


{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting= 


To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting== 


{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|bold red text||style='color:#ff0000; background-color:#eee8aa'|'''Sample'''||An error||Some explanation on error||Can be an unknow variable or an error in function, .... Survey can be totally broken, this don't show to public user.
|-
|blue text||style='color:#0000ff; background-color:#eee8aa'|Sample||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|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.
|-
|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.
|-
|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 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.
|-
|red text||style='color:#ff4500; background-color:#eee8aa'|Sample||assignment operator (=) ||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading= 

==[[Expression Manager sample surveys|Expression Manager sample surveys]]== 

==[[ExpressionScript How-tos|Use Cases and HowTos]]== 

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

==[[Expression Manager statistic functions|https://manual.limesurvey.org/StatFunctions]]==

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

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

</translate>

Expression Manager

2024-02-26T09:53:46Z

Mazi: Added link to stat functions

<languages /> <translate>


__TOC__


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

=Quick Start Tutorial= 

==Overview== 


When customizing your surveys, you typically need a way to specify the following:
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked
#'''Tailoring/Piping''' - how to phrase the question (such as referring to prior answers, or conjugating sentences based upon the number or gender of your subjects), or how to generate custom reports (like assessment scores or tailored advice).
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern


Expression Manager (EM) provides an intuitive way to specifying the logic for each of those features. Nearly anything that you can write as a standard mathematical equation is a valid expression, even if you are calling functions. EM currently provides access to 80 functions, and can be easily extended to support more. It also lets you access your variables using human-readable variable names (rather than SGQA names).


The following sections show the main places where Expression Manager is used

==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 when 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 shown, 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).


[[File:tutorial1.jpg]]


Relevance is shown and editable in the following places:

===Viewing / Editing Question-Level Relevance=== 


This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.


[[File:tutorial2.jpg]]


This is the edit screen for the BMI question.


[[File:tutorial3.jpg]]


Note that you do not use the curly braces when you enter a Relevance Equation.

===Viewing / Editing Group-Level Relevance=== 


This is a sample census survey. 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 (so it is shown for the second person cohabitating with you), and also only shows if you specified how Person One is related to you (p1_rel).


[[File:tutorial4.jpg]]


As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}). 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.


Here is the screen for editing the group-level relevance for that question:


[[File:tutorial5.jpg]]


Note that you do not use the curly braces when you enter a Relevance Equation.

==Tailoring/Piping== 


EM lets you easily do simple and complex conditional tailoring of your questions. Sometimes you just need 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 upon 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.

===Conditional Equations=== 


The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height and weight in metric or non-metric units.


[[File:tailoring7.jpg]]


Here weight_kg is {if(weight_units == 'kg', weight, weight * .453592)}. This if() function means that if the subject entered the weight using kilograms, use that value, otherwise multiply the entered value (which was in pounds) by .453592 to convert it to kilograms. The height_m variable uses a similar approach to compute the person's height in meters, even if he entered his height in inches.


BMI computes the weight formula as {weight_kg / (height_m * height_m)}.


Lastly, the report conditionally tailors the message for the subject, telling him what he entered. ("You said you are 2 meters tall and weight 70 kg.")


Although not well shown in the above image, weight_status uses nested if() statements to categorize the person as underweight to severely obese. You can see its equation in the Show Logic View


[[File:tailoring8.jpg]]


From the edit window for this question, you can see two things:
#Tailoring must surround expressions with Curly Braces
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.


[[File:tailoring9.jpg]]

===Tailored Questions, Answers, and Reports=== 


<div class="simplebox">Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <nowiki><span></nowiki> tag which is not valid inside select options.</div>


This example shows the BMI report.


[[File:tailoring10.jpg]]


Here is the edit window for the same question.


[[File:tailoring11.jpg]]


As you can see, anything in curly braces is treated as an expression, so is syntax-highlighted (color coded) in the prior image. If you had any typos (such as misspelled or undefined variable names or functions), EM would show an error, such as this, showing that height_unit is an undefined variable name (it is actually height_units), and rnd() is an undefined function (the proper function name is round()). In both cases, the errors are surrounded by a red box to make it easier to spot and fix them.


[[File:tailoring12.jpg]]


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.

==Validation== 


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. You continue to enter those advanced question options as usual. However, now 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 option is always considered an expression, you do not use curly braces when specifying it.


The [[Expression Manager sample surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.

=Introduction= 


LimeSurvey uses the new Expression Manager (EM) module which will let LimeSurvey support more complex branching, assessments, validation, and tailoring. It will replace how LimeSurvey manages Replacements, Conditions, and Assessments on the back-end. It will also speed up processing considerably since it eliminates most run-time database reads. EM was developed by Dr. Thomas White (TMSWhite).


This wiki page is the definitive reference for Expression Manager syntax and functionality.

==Key Definitions== 
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', participant data, and response data.
#*You also have easier access to questions, answers, and their properties.
#'''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.
#*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
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?== 


The short answer is No (but also yes).


EM is fully backwards-compatible with existing surveys. So, if you are happy to use Conditions and Assessments in the style that LimeSurvey used in versions <= 1.91+, you can continue to do so.


However, EM completely replaces how LimeSurvey internally deals with Conditions. Although you can still use the Conditions Editor to create and manage conditions, LimeSurvey 1.92 will convert those to the equivalent Relevance Equations. As part of the upgrade, LimeSurvey 1.92 will auto-convert all existing Conditions to Relevance Equations.


This should give you the best of both worlds - you can continue using LimeSurvey as you are used to, but will see the Relevance Equation equivalent so you can gradually migrate to Relevance Equations directly whenever you see fit.

==Can I mix use of Conditions and Relevance?== 


Yes. You can use the Conditions editor for some questions and the Relevance editor for others. Conditions are auto-converted to Relevance when you save the question.


Note, we assume that if you are using the Conditions editor, that you want those Conditions to over-write any manually entered Relevance equation. So, if you have existing Conditions and want to manually edit the Relevance, please delete the Conditions for that question first. Specifically, copy the generated relevance equation to a text editor, use the Conditions menu to delete all of the conditions for that question (which will also delete the relevance), then edit the question and paste the generated relevance equation from the text editor back into the relevance field for that question (and save the question). If there is enough demand for deleting conditions without deleting the generated relevance equation, we could add a bulk conversion process.

==How should I choose between Conditions and Relevance?== 


Here is a list of pros and cons of each style:


{| class="wikitable"
!Style!!Pros!!Cons
|-
|Conditions||1. Nice GUI for creating simple conditions <br/>2. GUI well documented and understood by support team||1. Only supports simple comparisons and does not AND/OR conditions well <br/>2. Cascading conditions work erratically <br/>3. Slow - database intensive, so can slow down long surveys <br/>4. Some reported problems with re-loading conditions <br/>5. GUI doesn't scale well when there are dozens, hundreds, or thousands of questions <br/>6. May be slow to convert paper-based surveys since must use SGQA names <br/>7. Often need a programmer to custom-code logic needed for complex branching
|-
|Relevance||1. Supports very complex logic, including 80+ functions and math/string operators <br/>2. Perfect support for cascading logic <br/>3. Fast - no extra database calls, so supports 1000+ question surveys <br/>4. No problems with re-loading logic since does not require SGQA codes <br/>5. Syntax-highlighting scales to 1000+ question surveys <br/>6. Easy and fast to use for groups wanting to computerize existing paper-based suveys. <br/>7. Easily supports semi-structured interviews and epidemiological surveys without needing a programmers||1. No GUI for simple conditions - use syntax-highlighting instead <br/>2. New, so support teams have not mastered EM yet.
|}


The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.

==What are some other benefits of using EM?== 


Here are some of the other reasons you might want to use EM.
#Calculations - you can create any calculation you can think of:
#*You have access to all common mathematical operators and functions
#*You have access to 70+ mathematical, date, and string processing functions
#*It is fairly easy for developers to add new functions if users need them
#Storing Calculations to Database
#*You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.
#*You use the Equation question type to accomplish this.
#Assessments
#*You can now create assessments or scale scores from any question type, not just the subset that used to be supported
#*You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page
#*You have more control over the reports generated based upon those assessment scores
#*You can store assessment scores in the database without needing JavaScript
#*You can hide assessment scores without needing JavaScript or CSS
#Replacement Fields
#*Instead of using {INSERTANS:SGQA}, you can just use the Question Code - 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
#*Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")
#*Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 children")
#*Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.
#New Variable Attributes - you can access the following to do your tailoring:
#* (no suffix) - an alias for qcode.code
#*.code - the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question
#*.NAOK - same as .code, but can be part of calculations or lists even if irrelevant
#*.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
#*.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)
#*.qid - the question ID
#*.gid - the group ID
#*.sgqa - the SGQA value for the question
#*.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another
#*.qseq - the question sequence (starting from 0)
#*.gseq - the group sequence (starting from 0)
#*.mandatory - whether the question is mandatory (Y/N)
#*.question - the text of the question
#*.relevance - the relevance equation for the question
#*.grelevance - the relevance equation for the group
#*.relevanceStatus - whether or not the question is currently relevant (boolean (can be different in PHP and JS))
#*.type - the question type (the one character code)
#Dynamic On-Page Changes
#*All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page
#*So, you have questions dynamically appear/disappear based upon whether they are relevant
#*Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.
#New Data Entry Screen
#*In addition to using the current data-entry system, you can just use Survey-All-In-One.
#*This supports the on-page relevance and tailoring, so data entry clerks can quickly tab through and they will only have to enter the relevant responses
#*This can be critical if your data entry person needs to see the tailoring, which is also dynamic.
#Eliminates the need for most custom JavaScript
#*EM easily supports complicated computations, scoring, tailoring and conditional logic.
#*Some things will still need JavaScript (like custom layouts and conditionally hiding question sub-elements), but your JavaScript can use the EM functions so that you can access questions by their Qcode instead of SGQA, and access any of the question properties listed above.

==What are some other helpful new features enabled by EM?== 


Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:
#You can create more complex validation criteria
#*All of the advanced question attribute (like max_answers, min_num_value_n, max_num_value) can use Expressions. So, you min/max criteria can be easily adjusted based upon prior responses, even if they are on the same page.
#*EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.
#Easy Re-ordering (or deleting) of Questions and Groups
#*Prior to version 1.92, you could not re-order questions or groups if LimeSurvey thought that such-re-ordering could break conditions in which they were used. Similarly, you could not delete questions if any other questions depended upon them.
#*With EM's syntax highlighting, it is easy to see and validate whether you try to use questions before they are declared. So, we now let you re-order or delete questions and groups whenever you like. EM will update all of the syntax highlighting to show you potential errors.
#*The re-order questions view has been enhanced to help with such review. It now shows the question's relevance equation and tailoring, so you can immediately see whether any variables become pink (meaning they are used before being declared).
#The Question/Group Navigation Index is always available and accurate
#*Prior to version 1.92, these indexes were not available if there were complex conditions
#*With EM, we can guarantee that they are accurate.
#*Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)
#**When jumping forwards, EM will re-validate all of the intervening questions/groups.
#**If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent
#**If any questions become relevant or newly fail mandatory or validation rules, EM will stop on that page and force the user to answer those questions before jumping to their final destination.
#Auto-conversion of Conditions to Relevance
#*When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them
#*Whenever you import a survey, relevance equations will be created as needed
#*Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.
#Convenient Syntax Highlighting
#*When EM shows the relevance equation, it will show the Qcode, even if you entered an SGQA code, as we assume this will be easier to read.
#*All variables are color coded to show whether they were declared before or after the current question (or before or after the current group). This lets you quickly detect and fix cases where you try to use variables for relevance (including array_filter), tailoring, or validation equations prior to declaring them.
#*In addition, if you hover your mouse over the color-coded variable, you will see the most important metadata about that question. This includes the Group Sequence #, Question Sequence #, Qcode, Text of the question, and all available answer choices (if it is a question type with enumerated answer choices).
#**The list of answer choices uses this syntax: 'answers':{key:val, ... }.
#**''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.
#**''val'' has the syntax ''''value~shown'''' where ''value'' is the assessment value (if using assessments, otherwise ''code'')(e.g. Qcode.value), and ''shown'' is the display value as seen by the subject (e.g. Qcode.shown)
#**This means that many surveys can use calculations without needing assessment mode. If you have enumerated answer options that are unique, non-decimal, and non-negative, you can simply do calculations on the Qcode.code values.
#Easy review of entire survey logic and content
#*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 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)
#*The syntax-highligting supports rapid navigation and editing of the survey.
#**If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.
#**If you click on a group name, it opens a browser window (or tab) showing the group-reorder view so that you can easily move questions around.
#**All of the question attributes are also syntax highlighted. This lets you set and see expressions within advanced question options (like basing the max/min number/sum of values on an expression)
#*The EM author used similar view (a little cleaner) to let his collaborating Epidemiologists and Institutional Review Board validate and authorize surveys with thousands of questions in highly branched and tailored structured interviews

=Getting Started= 


The best way to get started with EM is to:
*Install the latest stable version from http://www.limesurvey.org/en/download
*Import and explore the [[ExpressionScript sample surveys|sample surveys]].
*Explore the [[ExpressionScript How-tos|use cases and HowTos]] and [[ExpressionScript examples|step-by-step examples]].
*Explore the EM documentation (this page)
*Examine the built-in EM test suite
**From any survey, under tools, select the EM option
**Available Functions lists the 70+ functions and syntax
**Unit Tests of Isolated Expressions
***shows examples of using all EM functions and operators, and the PHP and JavaScript results
***note there are few functions that generate different results in the PHP and JavaScript versions, so this page lets you plan your EM logic accordingly.

=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)= 

==Conditions => Relevance== 


Conditions controlled which questions are visible. The general syntax was ''SGQA operator Value'', like ''111X2X3 == "Y"''. Conditions could be ANDed or ORed together, but mixing ANDs and ORs was difficult. The conditions themselves were stored in a separate table, and large portion of LimeSurvey's code was devoted to managing Conditions. Because of extensive database access, processing large numbers of conditions could cause noticable performance problems. Furthermore, once you had conditions assigned to questions or groups, you were often not allowed to re-order or delete them.

==Assessments => Equations and Micro-Tailoring== 


Assessments let users create scale scores from a collection of questions. However, they could not dynamically change on the current page, and their values were not stored to the database.

==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.

==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.

==Equations== 


Equations were not supported without fancy JavaScript.

==Equation Question Type== 


Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.

=How Will Expression Manager Replace/Extend That Functionality?= 


The Expression Manager is a new core module within LimeSurvey that makes it much easier to support the type of complex functionality that used to require custom JavaScript. It is also replacing the way LimeSurvey currently manages Conditions and Assessments.

==New Terminology When Referring to Expression Manager (EM)== 


EM "thinks" of its functionality in the following terms:
*'''Relevance-based Branching''' - if a question is relevant, then ask it, otherwise don't (e.g. make it invisible, and mark it as NULL in the database). There is a new Relevance field for all Question types, and also for each Group (so you can apply a set of conditions to an entire group without having to copy the same condition to each question, and/or combine group and question-level conditional logic).
*'''Tailoring''' - Once you know which questions should be asked, tailoring (sometimes called ''piping'') specifies how the question should be asked. This lets you support not only simple subsitution (like {TOKEN:FIRSTNAME}), but also conjugation of verbs and declination of nouns based upon the gender or number of your subjects. It also lets you change the message you deliver to a subject based upon whether they answered (or how they answered) other questions.
*'''Equations''' - EM adds a new question type called Equation which stores the result of an Expression. These equations results are computed and written to the database, even if you hide them on the page. Thus, they are useful for hidden scoring calculations, navigation based upon complex equations, assessments, and reports that should be generated and easily available within the database.

===Relevance and Cascading Relevance=== 


Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be displayed. If it is not relevant, then the question will be hidden, and the value will be NULLed in the database. If there are no relevant questions in a group, the entire group will be skipped.


Moreover, if any of the variables within an expression is irrelevant, then the expression always evaluates to false. This enables Cascading Relevance so that you do not have to write very long Relevance equations for each question.


Say you have 5 questions Q1-Q5, and you only want to show Q2 if Q1 was answered, and Q3 if Q2 was answered, etc. The relevance equations might be:


{| class="wikitable"
!Question Code!!Relevance!!Question
|-
|Q1||1||What is your name?
|-
|Q2||Q1||{Q1}, how old are you?
|-
|Q3||Q2||So, you are {Q2} years old. Are you married?
|-
|Q4||Q3 == "Y"||{Q1}, how long have you been married?
|-
|Q5||Q4||How many children do you have, {Q1}?
|}


The relevance calculations also work in JavaScript - so you could put all the above questions on one page and it would still work as expected. In fact, EM totally replaces how EM processes Survey vs. Group vs. Question-at-a-time survey formats. They now all use the exactly same navigation engine so they work identically regardless of survey style.


As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose an option that makes them irrelevant, then make them relevant again, your answers will still be available. However, as soon as you move to a different page, all irrelevant responses will be lost to integrity of the dataset.

===Group-Level Relevance=== 


Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first determine how many entities need follow-up (such as by asking how many people live in a household, or having people check which products they like from a long list). After knowning how many entities need follow-up, you can use Group-level relevance like {count >= 1}, {count >=2}, ... {count >= 10} for each of the 10 groups of follow-up questions. Within each group, you can have question-level conditional logic (e.g. gender or age-specific follow-up questions for each subject). The question and group-level relevance equations are ANDed together to determine which should be shown.

===Tailoring / Piping=== 


Anything within curly braces is now treated as an Expression (with one exception described below). Expressions have acccess to all of the LimeReplacementFields, all of the variables (via several aliases), all typical equation operators (mathematical, logical, and comparison), and dozens of functions (that even work dynamically on the client-side).


Using these equations, you can do things such as:
#Conditionally show tailored messages to the respondants based upon prior responses
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself
#Conjugate verbs and decline nouns within questions, answers, and reports.
#Show summaries of responses before the "Show your answers" page at the end of the survey

===Equations=== 


There is a new question type called Equation. It is like a Boilerplate questions, except that it stores the value of what is displayed in the database. So, if the Equation Question text contains an Assessment computation, that value would be stored in the database in a variable that can be displayed within public or private statistics.


This solves a common request for storing Assessment scores within the database

==Syntax== 


Anything contained within curly braces is now considered an Expression (with one exception: there must be no leading or trailing whitespace - this is needed to ensure the Expression Manager does not try to process embedded JavaScript).


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">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>


<div id="EMsyntax">Expression Manager supports the following syntax:</div>
*All standard mathematical operators (e.g. +,-,*,/,!)
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)
*Parentheses (so you can group sub-expressions)
*Conditional operators (e.g. &&,| | and these equivalents: and,or)
*Single and double-quoted strings (which can each embed strings with the other quote type)
*Comma operator (so can have a list of expressions and just return the final result)
*Assignment operator (=)
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes
*Pre-defined functions (there are already 70+, and it is easy to add more)

=== Operators === 


EM syntax follows normal operator precedence:


{| class="wikitable"
!Level!!Operator(s)!!Description
|-
|1||()||parentheses for grouping or calling functions
|-
|2||! - +||unary operators: not, negation, unary-plus
|-
|3||* /||times, divide
|-
|4||+ -||plus, minus
|-
|5||< <= > >= lt le gt ge||relative comparisons
|-
|6||== != eq ne||equality comparisons
|-
|7||and||logical AND
|-
|8||or||logical OR
|-
|9||=||assignment operator
|-
|10||,||comma operator
|}

==== Warning with plus operator (+) ==== 


For consistency between JavaScript and PHP, the plus operator (+) does addition if both operands are numeric, but does concatenation if both parts are non-numeric strings. However, '''we recommend using the join() function for concatenation and sum() function for addition''', as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

==== Warning with mismatch between number and string and alphabetic comparison ==== 


When you want to compare value with relative or equality comparisons, pay attention to type mismatch. Value entered by user or answer code selected can be used as number if it's clearly a number.
If you surround one of the values with <code>"</code>it will force the comparison as text (alphabetic compare). If you want to compare numerically, never surround the number with quotation marks, <code>"</code>.


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>.

===Caution about using Assignment Operator (=)=== 


Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you should create an Equation question type, and use an expression to set its value. However, there are some rare times that people really need this operator, so we made it available.


To help caution you about this operator, it is shown in red font within the syntax equations (so that you don't confuse it with "==")

===Using Assignment Operator=== 
The main reasons you may want to use assignment are:
* You need to set the default value for a question that does not accept defaults via equation (such as list radio, where the user interface lets you pick one of the answer options, but does not let you enter an equation). However, be careful, as LimeSurvey will not be able to validate that your equation generates one of the allowable answers for that question.
* You need to forcibly change the response to a previous question based upon a later response
* You need complex quota : using one hidden single choice for quota and set it using assignment
* etc...


You can use all expression manager system for this purpose.


{{Alert|Assignment is done only in PHP. This doesn't update any values on the same page, but only when the user navigates with next, previous, save ….}}


{{Alert|If you don't use an [[Question_type_-_Equation|equation question]] type for this purpose: the assignment is done only after the logic of the current page is done. The recommended method is to always use an [[Question_type_-_Equation|equation question]].}}


Some example:
* Set answer to a short text question in lowercase : <code>{QCODE=strtolower(QCODE.NAOK)}</code>
* Set a default answer to an array question type at start of a survey : <code>{Q1_SQ1=((is_empty(Q1_SQ1.NAOK),"A99",Q1_SQ1.NAOK)}</code>
* Set a default answer to an array texts question type at start of a survey : <code>{Q1_SQY1_SQX1 = ((is_empty(Q1_SQY1_SQX1.NAOK),"Inserted answer", Q1_SQY1_SQX1.NAOK)}</code>
* Set an answer with condition : <code>{QCODE=if(YesNo="Y","A1","")}</code>

== XSS security == 


With XSS enable, some expression manager system can not be used :
* starting a HTML tag in expression but ending in another expression
* use a complex expression in URL.


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><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>

==Access to Variables== 


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).
*[[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}.
*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 addition, Expression Manager lets you refer to variables by the Question Code (the 'title' column in the questions table within the database). This is also the variable label used when you export your data to SPSS, R, or SAS. For example, if you have questions about name, age, and gender, you could call those variables ''name'', ''age'', and ''gender'' instead of ''12345X13X22'', ''12345X13X23'', and ''12345X13X24''. This makes equations easier for everyone to read and validate the logic, plus makes it possible to shuffle questions around without having to keep track of group or question numbers.


<div class='simplebox'>
'''Important:''' It is only safe to refer to variables that occur in preceding pages or questions.
</div>


Furthermore, Expression Manager lets you access many properties of the Question:


{| class="wikitable"
!Syntax!!Meaning!!Example!!Example Result
|-
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'
|-
|Qcode.code||the selected response code for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{implode(',',name.code,gender.code)}||'Tom','M'
|-
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'
|-
|Qcode.value||the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question||{gender.value}||'1'
|-
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'
|-
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'
|-
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'
|-
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'
|-
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337
|-
|Qcode.type||the question type||{gender.type}||'G'
|-
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'
|-
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3
|-
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5
|-
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1
|-
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus}||1
|-
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'
|-
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'
|-
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'
|}

=== HTML editor issue=== 


{{Alert|This issue is fixed after 2.05 build 140803}}


If you use HTML editor, some characters are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;


If you use HTML editor you need to use :
* and for &
* lt for <
* le for <=
* gt for >
* ge for >=

==Qcode Variable Naming== 


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


For '''comment''' and '''other''', question code are QuestionCode_comment and QuestionCode_other


{| class="wikitable"
!Type!!Description!!Code!!SubQs!!Answer Options!!Scales!!Answer Code!!Answer Shown!!Relevance
|-
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}
|-
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}
|-
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}
|-
|1||Array (Flexible Labels) Dual Scale||Q4||sq1-sq5||0:a1-a3||1:b1-b3||{Q4_sq1_0}||{Q4_sq1_1.shown}||{Q4_sq1_1=='b2'}
|-
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}
|-
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}
|-
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}
|-
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}
|-
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}
|-
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}
|-
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||
|-
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||
|-
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}
|-
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}
|-
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}
|-
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}
|-
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}
|-
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}
|-
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}
|-
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20comment}||{Q20.shown}||{Q20=='B'}
|-
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}
|-
|M||Multiple Choice Checkbox||Q22||A-F, other|| || ||{Q22_E}, {Q22_other}||{Q22_E.shown}, {Q22_other.shown}||{Q22_E=='Y'}
|-
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_Dcomment}||{Q23_D.shown}||{!is_empty(Q23)}
|-
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}
|-
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q'}
|-
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}
|-
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}
|-
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}
|-
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}
|}

==The reserved 'this', 'self', and 'that' variables== 


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 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:
*self
*self.''suffix''
*self.''sub-selector''
*self.''sub-selector''.''suffix''


''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)


''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g., from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*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 ....
*nosq_X - where X is a row or column identifier. Only subquestions not matching pattern X are selected. Note that search is done on complete code identifier, then nosq_X match and does not include subquestions nX, X, Xn


Examples:
*Has any part of a question been answered? {count(self.NAOK)>0}
*What is the assessment score for this question? {sum(self.value)}


You can also use these to get row and column totals. Say you have a array of numbers with rows A-E and columns 1-5.
*What is the grand total? {sum(self.NAOK)}
*What is the total of row B? {sum(self.sq_B.NAOK)}
*What is the total of column 3? {sum(self.sq_3.NAOK)}


The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:
*that.''qname''
*that.''qname''.''suffix''
*that.''qname''.''sub-selector''
*that.''qname''.''sub-selector''.''suffix''


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


Examples:
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}
*What is the assessment score for q2? {sum(that.q2.NAOK)}
*What is the grand total of q3? {sum(that.q3.NAOK)}
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}


The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.


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 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.

==Usage of NAOK== 


NAOK --> "Not Applicable" (NA) is alright (OK)


Using NAOK, means that all or some of the variables are irrelevant (e.g. "Not Applicable" (NA) is alright (OK)).


When you put some variable from question in any equation : if this question (or subquestion) is hidden by condition : this disable all equation.


For example : count(Q1_SQ1,Q1_SQ2,Q1_SQ3,Q1_SQ4) give always an empty string if one subquestion of Q1 is filtered.
To count the number of checked subquestion in such question can be count(Q1_SQ1.NAOK,Q1_SQ2.NAOK,Q1_SQ3.NAOK,Q1_SQ4.NAOK). If the sub question is hidden :Expression manager return an empty string.


Without NAOK : if one question or one subquestion is hidden : Expression Manager return always an empty string, same to return false.


The .shown always use the NAOK system (empty string if hidden) but if you need the code of the answer : it's always a good idea to add .NAOK after the question code. Except if you need it and know what you do.


Another example and information is provided at [[#Overriding_Cascading_Conditions|Overriding Cascading Conditions]]

==Access to Functions== 


Expression Manager provides access to mathematical, string, and user-defined functions, as shown below. It has PHP and JavaScript equivalents for these functions so that they work identically on server-side (PHP) and client-side (JavaScript). It is easy to add new functions.

===Implemented Functions=== 


The following functions are currently available:


{| class="wikitable"
!Function!!Meaning!!Syntax
|-
|[http://www.php.net/manual/en/function.abs.php abs]||Absolute value||number abs(number)
|-
|[http://www.php.net/manual/en/function.acos.php acos]||Arc cosine||number acos(number)
|-
|[http://www.php.net/manual/en/function.addslashes.php addslashes]||Quote string with slashes||string addslashes(string)
|-
|[http://www.php.net/manual/en/function.asin.php asin]||Arc sine||number asin(number)
|-
|[http://www.php.net/manual/en/function.atan.php atan]||Arc tangent||number atan(number)
|-
|[http://www.php.net/manual/en/function.atan2.php atan2]||Arc tangent of two variables||number atan2(number, number)
|-
|[http://www.php.net/manual/en/function.ceil.php ceil]||Round fractions up||number ceil(number)
|-
|[http://www.php.net/manual/en/function.checkdate.php checkdate]||Returns true(1) if it is a valid date in gregorian calendar||bool checkdate(month,day,year)
|-
|convert_value||Convert a numerical value using a inputTable and outputTable of numerical values||number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
|-
|[http://www.php.net/manual/en/function.cos.php cos]||Cosine||number cos(number)
|-
|count||count the number of answered (non-blank) questions in the list||number count(arg1, arg12, ..., argN)
|-
|countif||Count the number of answered questions in the list equal to the first argument||number countif(matches, arg1, arg2, ... argN)
|-
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.date.php date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.exp.php exp]||Calculates the exponent of e||number exp(number)
|-
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)
|-
|[http://www.php.net/manual/en/function.floor.php floor]||Round fractions down||number floor(number)
|-
|[http://www.php.net/manual/en/function.gmdate.php gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])
|-
|[http://www.php.net/manual/en/function.html-entity-decode.php html_entity_decode]||Convert all HTML entities to their applicable characters (always uses ENT_QUOTES and UTF-8)||string html_entity_decode(string)
|-
|[http://www.php.net/manual/en/function.htmlentities.php htmlentities]||Convert all applicable characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlentities(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars.php expr_mgr_htmlspecialchars]||Convert special characters to HTML entities (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars(string)
|-
|[http://www.php.net/manual/en/function.htmlspecialchars-decode.php expr_mgr_htmlspecialchars_decode]||Convert special HTML entities back to characters (always uses ENT_QUOTES and UTF-8)||string htmlspecialchars_decode(string)
|-
|[http://www.php.net/manual/en/function.idate.php idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])
|-
|if{{UpdatedIn|3.0.2}}||Excel-style if(test,result_if_true<nowiki>[</nowiki>,result_if_false = ""<nowiki>]</nowiki>)||if(test,result_if_true<nowiki>[</nowiki>,result_if_false = ""<nowiki>]</nowiki>)
|-
|[http://www.php.net/manual/en/function.implode.php implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)
|-
|[http://www.php.net/manual/en/function.intval.php intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])
|-
|[http://www.php.net/manual/en/function.empty.php is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)
|-
|[http://www.php.net/manual/en/function.is-float.php is_float]||Finds whether the type of a variable is float||bool is_float(var)
|-
|[http://www.php.net/manual/en/function.is-int.php is_int]||Find whether the type of a variable is integer||bool is_int(var)
|-
|[http://www.php.net/manual/en/function.is-nan.php is_nan]||Finds whether a value is not a number||bool is_nan(var)
|-
|[http://www.php.net/manual/en/function.is-null.php is_null]||Finds whether a variable is NULL||bool is_null(var)
|-
|[http://www.php.net/manual/en/function.is-numeric.php is_numeric]||Finds whether a variable is a number or a numeric string||bool is_numeric(var)
|-
|[http://www.php.net/manual/en/function.is-string.php is_string]||Find whether the type of a variable is string||bool is_string(var)
|-
|join{{NewIn|2.0|b=130129}}||Join elements as a new string||join(arg1, arg2, ... argN)
|-
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)
|-
|listifop{{NewIn|3.16.1}}||Return a 'glue'-separated list of the specified question property (retProp) from questions in the list which pass the criteria (cmpProp op value)||string listifop(cmpProp, op, value, retProp, glue, sgqa1, sgqa2, ... sgqaN)
|-
|[http://www.php.net/manual/en/function.log.php log]|| The logarithm of number to base, if given, or the natural logarithm. ||number log(number,base=e)
|-
|[http://www.php.net/manual/en/function.ltrim.php ltrim]||Strip whitespace (or other characters) from the beginning of a string||string ltrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.max.php max]||Find highest value||number max(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.min.php min]||Find lowest value||number min(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.mktime.php mktime]||Get UNIX timestamp for a date (each of the 6 arguments are optional)||number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
|-
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)
|-
|[http://www.php.net/manual/en/function.nl2br.php nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)
|-
|[http://www.php.net/manual/en/function.number-format.php number_format]||Format a number with grouped thousands||string number_format(number)
|-
|pi||Get value of pi||number pi()
|-
|[http://www.php.net/manual/en/function.pow.php pow]||Exponential expression||number pow(base, exp)
|-
|[http://www.php.net/manual/en/function.quoted-printable-decode.php quoted_printable_decode]||Convert a quoted-printable string to an 8 bit string||string quoted_printable_decode(string)
|-
|[http://www.php.net/manual/en/function.quoted-printable-encode.php quoted_printable_encode]||Convert a 8 bit string to a quoted-printable string||string quoted_printable_encode(string)
|-
|[http://www.php.net/manual/en/function.quotemeta.php quotemeta]||Quote meta characters||string quotemeta(string)
|-
|[http://www.php.net/manual/en/function.rand.php rand]||Generate a random integer, see [[Expression Manager sample surveys#Randomly Ask One Question Per Group|this example]]||int rand() OR int rand(min, max)
|-
|regexMatch||compare a string to a [[Using regular expressions|regular expression]]||bool regexMatch(pattern,input)
|-
|[http://www.php.net/manual/en/function.round.php round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])
|-
|[http://www.php.net/manual/en/function.rtrim.php rtrim]||Strip whitespace (or other characters) from the end of a string||string rtrim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.sin.php sin]||Sine||number sin(arg)
|-
|[http://www.php.net/manual/en/function.sprintf.php sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.sqrt.php sqrt]||Square root||number sqrt(arg)
|-
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.str-pad.php str_pad]||Pad a string to a certain length with another string||string str_pad(input, pad_length <nowiki>[</nowiki>, pad_string])
|-
|[http://www.php.net/manual/en/function.str-repeat.php str_repeat]||Repeat a string||string str_repeat(input, multiplier)
|-
|[http://www.php.net/manual/en/function.str-replace.php str_replace]||Replace all occurrences of the search string with the replacement string||string str_replace(search, replace, subject)
|-
|[http://www.php.net/manual/en/function.strcasecmp.php strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strcmp.php strcmp]||Binary safe string comparison||int strcmp(str1, str2)
|-
|[http://www.php.net/manual/en/function.strip-tags.php strip_tags]||Strip HTML and PHP tags from a string||string strip_tags(str, allowable_tags)
|-
|[http://www.php.net/manual/en/function.stripos.php stripos]||Find position of first occurrence of a case-insensitive unicode string (starting by 0, return false if not found)|||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])
|-
|[http://www.php.net/manual/en/function.stripslashes.php stripslashes]||Un-quotes a quoted string||string stripslashes(string)
|-
|[http://www.php.net/manual/en/function.stristr.php stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strlen.php strlen]||Get string length||int strlen(string)
|-
|[http://www.php.net/manual/en/function.strpos.php strpos]||Find position of first occurrence of an unicode string (starting by 0, return false if not found)||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])
|-
|[http://www.php.net/manual/en/function.strrev.php strrev]||Reverse a string||string strrev(string)
|-
|[http://www.php.net/manual/en/function.strstr.php strstr]||Find first occurrence of a string||string strstr(haystack, needle<nowiki>[</nowiki>, before_needle=false])
|-
|[http://www.php.net/manual/en/function.strtolower.php strtolower]||Make a string lowercase||string strtolower(string)
|-
|[http://www.php.net/manual/en/function.strtotime.php strtotime]||Parse about any English textual datetime description into a Unix timestamp||int strtotime(string)
|-
|[http://www.php.net/manual/en/function.strtoupper.php strtoupper]||Make a string uppercase||string strtoupper(string)
|-
|[http://www.php.net/manual/en/function.substr.php substr]||Return part of an unicode string||string substr(string, start <nowiki>[</nowiki>, length])
|-
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)
|-
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)
|-
|[http://www.php.net/manual/en/function.tan.php tan]||Tangent||number tan(arg)
|-
|[http://www.php.net/manual/en/function.time.php time]||Return current UNIX timestamp||number time()
|-
|[http://www.php.net/manual/en/function.trim.php trim]||Strip whitespace (or other characters) from the beginning and end of a string||string trim(string <nowiki>[</nowiki>, charlist])
|-
|[http://www.php.net/manual/en/function.ucwords.php ucwords]||Uppercase the first character of each word in a string||string ucwords(string)
|-
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)
|}

===Functions that are Planned or Being Considered=== 


Other functions that are planned (or being considered) but which are not implemented yet include the following. Some of these are for backwards compatability with another survey tool.


{| class="wikitable"
!Syntax!!Meaning!!Comments
|-
|e()||returns the value of e||
|-
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||
|-
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||
|-
|getAnsOption(X)|| [[ExpressionAnswerOptions|Core plugin ExpressionAnswerOptions ]] ||
|-
|getAnsOption(X,Y)|| [[ExpressionAnswerOptions|Core plugin ExpressionAnswerOptions ]] ||
|-
|getRelevance(X)||returns the relevance equation for question X||
|-
|getStartTime()||returns the date corresponding to the system time when the interview was started||
|-
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||
|-
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||
|-
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||
|-
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||
|-
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||
|-
|isInvalid(X)||returns true if the answer is of type *INVALID*||
|-
|isNA(X)||returns true if the answer is of type *NA*||
|-
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||
|-
|isRefused(X)||returns true if the answer is of type *REFUSED*||
|-
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||
|-
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||
|-
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||
|-
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||
|-
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||
|-
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||
|-
|mean(X,...)||returns the mean of a list of values||
|-
|numAnsOptions(X)||returns the number of answer options that question X has||
|-
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||
|-
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||
|-
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||
|-
|showAllResponsesExcept( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|-
|showTheseResponses( questionList,attributeList,attributeTitleList)||questionList = pipe-delimited list of question identifiers; attributeList = pipe-delimited list of attributes (like question#, title, text, type - so you can decide what to show); attributeTitleList = pipe-delimited list of table headers, so can internationalize the report.||
|}

==Expression Manager Knows Which Variables are Local== 


In order to properly build the JavaScript for page, Expression Manager needs to know which variables are set on the page, and what their JavaScript ID is (e.g. for document.getElementById(x)). It also must know which variables are set on other pages (so that it can ensure that the needed <input type='hidden' value='x'> fields are present and populated).

==Cascading Conditions== 


If any of the variables are irrelevant, the whole equation will be irrelevant (false). For example, in the following table, N/A means that one of the variables was not relevant


{| class="wikitable"
!Operator!!Example!!a!!b!!Result
|-
|<nowiki>+ (unary)</nowiki>||<nowiki>+a</nowiki>||N/A|| ||false
|-
|- (unary)||-a||N/A|| ||false
|-
|!||!a||N/A|| ||false
|-
|== (or eq)||a == b||N/A||5||false
|-
|== (or eq)||a == b||N/A||0||false
|-
|== (or eq)||a == b||N/A||N/A||false
|-
|!= (or ne)||a != b||N/A||5|| false
|-
|!= (or ne)||a != b||N/A||N/A|| false
|-
|!= (or ne)||a != b||N/A||0||false
|-
|> (or gt)||a > b||N/A||5|| false
|-
|>= (or ge)||a >= b||N/A||5||false
|-
|< (or lt)||a < b||N/A||5||false
|-
|<= (or le)||a <= b||N/A||5||false
|-
|and||a and b||N/A||5||false
|-
|and||a and b||N/A||N/A||false
|-
|or||a or b||N/A||N/A||false
|-
|or||a or b||N/A||5||false
|-
|<nowiki>+</nowiki>||a + b||N/A||5||false
|-
|-||a - b||N/A||5||false
|-
|*||a * b||N/A||5||false
|-
|/||a / b||5||N/A||false
|-
|()||(a)||N/A|| ||false
|-
|(exp)||(a && b)||N/A||5||false
|-
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false
|-
|function||sum(a,b,b)||N/A||5||false
|-
|function||max(a,b)||N/A||5||false
|-
|function||min(a,b)||N/A||5||false
|-
|function||implode(', ',a,b,a,b)||N/A||5||false
|-
|function||if(a,a,b)||N/A||5||false
|-
|function||is_empty(a)||N/A|| ||false
|-
|function||is_empty(a)||0 (or blank)|| ||true
|-
|function||!is_empty(a)||N/A|| ||false
|}

===Overriding Cascading Conditions=== 


Say you want to show a running total of all relevant answers. You might try to use the equation {sum(q1,q2,q3,...,qN)}. However, this gets translated internally to LEMif(LEManyNA('q1','q2','q3',...,'qN'),'',sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). So, if any of the values q1-qN are irrelevant, the equation will always return false. In this case, the sum() will show 0 until all questions are answered.


To get around this, each variable can have a ".NAOK" suffix (meaning that Not Applicable is OK) added to it. In such cases, the following behavior occurs. Say you have a variable q1.NAOK
#q1 is not added to the LEManyNA() clause
#LEMval('q1') will continue to check whether the response is relevant, and will return <nowiki>''</nowiki> if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression).


So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).


The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converge on common paths later. For example, say subjects answer a survey in a way that is outside the normal range of responses. The author could alert the subjects that they may not get valid results, and ask them whether they really want to continue with the survey. If they say Yes, then the rest of the questions will be shown. The condition for the "rest of the questions" would check whether the initial responses were answered within the normal range OR whether the subject said Yes to the question that is only relevant if they answered outside the normal range.

==How does Expression Manager Support Conditional Micro-Tailoring?== 


Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):


{| class="wikitable"
!Question Code!!Relevance!!Question Type!!Question
|-
|name||1||text||What is your name?
|-
|age||1||text||How old are you?
|-
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}
|-
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.
|-
|kids||!badage||yesno||Do you have children?
|-
|parents||1||expr||{!badage && kids=='Y'}
|-
|numKids||parents||text||How many children do you have?
|-
|kid1||parents && numKids >= 1||text||How old is your first child?
|-
|kid2||parents && numKids >= 2||text||How old is your second child?
|-
|kid3||parents && numKids >= 3||text||How old is your third child?
|-
|kid4||parents && numKids >= 4||text||How old is your fourth child?
|-
|kid5||parents && numKids >= 5||text||How old is your fifth child?
|-
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
|-
|report||parents||yesno||{name}, you said you are {age} and that you have {numKids}. The sum of ages of your first {min(numKids,5)} kids is {sumage}
|}


All of these questions can be on a single page (e.g. in the same group), and only the relevant questions will display. Moreover, as you enter the ages of children, the sum() expression in the last question will dynamically update on the page.


Expression Manager provides this functionality by surrounding each expression with a named <nowiki><span></nowiki> element. Every time a value changes, it recomputes the expression that should appear in that <nowiki><span></nowiki> element and regenerates the display. You can have dozens, or even hundreds, of such tailored expressions on the same page, and the page will re-display all of them in a single screen refresh.

==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality== 


{| class="wikitable"
!Old Feature!!New Feature!!Comments
|-
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables
|-
|Assessments||Equation||Any assessment scores can be re-structured into an Equation. This both ensures that the score is written to the database, and also lets you see dynamic changes to the score value on the current page
|-
|Replacements||Expression Manager||The core engine takes the input string and treats everything within curly braces as an Expression - so it handles all historical replacements types. To avoid messing up embedded JavaScript, Expression Manager only processes content between curly braces as long as (a) there is no leading or trailing whitespace within the curly braces - e.g. {expr} is an expression, but { expr}, {expr }, and { expr } are not expressions. Furthermore, Expression Manager does not process content within its own strings (e.g. {list('hi','there {braces}')} generates "hi there {braces}"). It also ignores escaped curly braces (e.g. \{this is not an expression\})
|-
|Validation||Expression Manager||The plan is to take the current min/max Question Attributes and have Expression Manager process them. That way the min/max values can be expressions themselves
|}

=Syntax Highlighting= 


To help with entering and validating expressions, EM provides syntax highlighting with the following features:

==Types and Meanings of Syntax Highlighting== 


{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|bold red text||style='color:#ff0000; background-color:#eee8aa'|'''Sample'''||An error||Some explanation on error||Can be an unknow variable or an error in function, .... Survey can be totally broken, this don't show to public user.
|-
|blue text||style='color:#0000ff; background-color:#eee8aa'|Sample||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|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.
|-
|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.
|-
|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 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.
|-
|red text||style='color:#ff4500; background-color:#eee8aa'|Sample||assignment operator (=) ||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Additional Reading= 

==[[Expression Manager sample surveys|Expression Manager sample surveys]]== 

==[[ExpressionScript How-tos|Use Cases and HowTos]]== 

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

==[[Expression Manager statistic functions|https://manual.limesurvey.org/StatFunctions]]

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

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

</translate>

How to design a good survey (guide)

2023-08-08T06:57:45Z

Mazi: Fix link

<languages /><translate>

__TOC__


'''A Simple Guide to Making a Good Survey'''


LimeSurvey makes it easy to put together a survey very quickly. Unfortunately, that makes putting a bad survey together very easy too.


On this page, you will find a simple guide to putting together a survey which will not only be painless for your audience to complete; but will also give you meaningful answers.


The blog [https://www.survey-consulting.com/survey-design-tips-tricks "Survey design tips & tricks"] also provides other very useful information.

==Before Making a Survey== 


Some important questions need to be answered before designing any questionnaire - actually even before deciding whether a questionnaire is the right way to go.


<u>What is it that you really want to find out with your research?</u>


Once you have answered that question, ask the following:
*'''Will a survey help me obtain the information that I need for my research?'''
*'''Who are the right people to ask to complete the survey?'''
*'''How can I ensure that I reach the right people?'''
*'''What is the best way to help those completing the survey fully understand the questions (so that the information obtained is accurate / useful)?'''
*'''Which, if any, statistical methods (for data analysis) do I want/need to use on the data once it has been gathered?'''


These are just a few of the questions that you need clear answers to when deciding if LimeSurvey is the right tool for you.


LimeSurvey is great for fully structured (you know all the questions you might need to ask before you start the interview), standardized (everyone gets more or less the same questionnaire), mostly quantitative (it is mainly about numbers or questions with predefined answers) questionnaires which are collected online.


To some extent you can, of course, vary from this. You can use LimeSurvey to collect answers to some types of phone interviews. You can also use LimeSurvey to collect qualitative data, e.g., by using text questions.


But at some point, you might come to the conclusion that other research methods are more suitable.

==Structuring a Questionnaire== 


To decide in which order to ask questions and how to group them, there are some aspects to consider.


If possible, start with questions that are easy to answer and which all participants are comfortable answering. Often these will be screening questions, i.e., questions you need to ask to find out whether you are asking the right people (use [[Setting conditions|conditions]] and/or [[Survey quotas|quotas]] to deal with these screening questions).


Putting these types of questions at the beginning might help to avoid participants leaving your survey before completing it, as people might be less likely to terminate once they have already put some work into answering these lead-in/screening questions.


'''Examples''':
<syntaxhighlight lang="php">Which of the following fruit do you like?
#Apples ()
#Bananas ()
#Cherries ()


(single choice)


You can use conditions to make the next question appear about cherries if participant chose ''cherries''.


Why do you prefer cherries?
#They are tasty
#I love the color
#They are healthy
#They are juicy
#I love cherry pie


(multi choice (or single choice, depends if you need exact data) question)


How much do you like cherries?
#1) Not much more than other fruit
#2) Like them more than other fruit
#3) It's one of my favourite fruits!
#4) I ADORE CHERRIES!


(single choice)


Do you know any recipes with cherries?


[textfield]


</syntaxhighlight>


Above is an example of easy to answer lead-in questions followed by the main question.


The objective was to gather recipes with cherries, apples and bananas.


On the other hand, if you need to ask hard to answer questions, you might think about using different pages for each question or question group and putting these hard to answer questions at the very end. This way, if participants decide not to complete the survey, at least their previous responses are saved.


Something else to consider pertaining to structure - avoid biases introduced by the questionnaire itself.


For example, in market research there are concepts which require unaided and aided questions.


An example of an unaided question would be:


<syntaxhighlight lang="php">"Which brands of chocolate are you familiar with?"


(followed by an empty text box) </syntaxhighlight>


The following is an example of an aided question:


<syntaxhighlight lang="php"> "Which of the following brands of chocolate are you familiar with?"


(followed by a list of brands (multiple choice))</syntaxhighlight>


As mentioned previously, if you choose to include both types of questions (aided and unaided) in the same questionnaire, you should make sure to put them on different pages and put the unaided questions before the aided questions. Putting an aided question before an unaided question might unintentionally influence the response of participants, which would invalidate your results.

==Individual Questions== 


Questions should be non-suggestive. "What is your opinion about LimeSurvey?" is an acceptable (non-suggestive) question while "Don't you agree that LimeSurvey is a really great tool?" is a suggestive question.


Other examples and suggestions for phrasing questions:


People may say '''"yes"''' to donating money if asked questions in the following way:
* ''Do you love nature?''
* ''Will you donate money to help the river?''


They will probably say '''"no"''' when asked the questions this way:
* ''Is lack of money a problem for you?''
* ''Will you donate money to help the river?''


To help solicit the proper responses, order your questions:
*from the least sensitive to the most sensitive
*from general to more specific
*from questions about facts to questions about opinions


Also, a survey question can be:
*'''Open-ended''' (the person answers in their own words), or
*'''Closed-ended''' (the person chooses from a limited number of options)


Closed-ended questions are much easier to analyze, but may not allow respondents to give the answer they really want.


Example: "''What is your favorite color?''"


'''Open-ended''': Someone may answer "dark fuchsia", in which case you will need to have a category "dark fuchsia" in your results.


'''Closed-ended''': With a choice of only 12 colors your work will be easier, but respondents may not be able to pick their exact favorite color.


Carefully consider each question and decide if they should be open-ended or closed-ended. If you need deeper insight into responses, use open-ended questions. If this is not the case, close-ended questions can be used.


Example (open-ended): "''What do you think is the best way to clean up the river''?"


Make it '''open-ended''': the answers may not be easy to put in a table or graph, but you may gain deep insight into people's feelings and ideas about cleaning up the river or the environment and use direct quotes in your reporting.


Example (closed-ended): "''How often do you visit the river?''"


Make it '''closed-ended''' with the following options:
*Nearly every day
*At least 5 times a year
*1 to 4 times a year
*Almost never


You will be able to present this data in a neat bar graph.


When working with multiple-choice or single-choice questions, make sure to choose the appropriate question type and formulate both questions and answers appropriately.


'''For example:'''


<syntaxhighlight lang="php">Which of the following fruit do you like?
#Apples ()
#Bananas ()
#Cherries ()</syntaxhighlight>


The above is a typical multiple-choice question, as you can like several items on the list. On the other hand, "Which one of the following fruits do you most prefer?" is a single choice question.


Both fruit examples have been formulated to make clear that your concern is with only the fruit listed. If you were to ask, "Which is your favorite fruit?", you should either have a really exhaustive list of fruit or, more likely, use LimeSurvey's setting to add an "other" field. Generally, answer options in most cases need to be complete, mutually exclusive and definite.


If you have multiple- or single-choice questions with a lot of options to choose from, you need to be aware that this might introduce another bias, as participants are likely to focus their attention on the very first options and not those in the middle. LimeSurvey offers a great option to randomize the order of questions and, to some extent, eliminate this problem.

==What Makes a Good Survey?== 


There are 3 features of a survey that will help to elicit the proper responses needed for more accurate assessment(s):
# The questions are clear and precise, collectively allowing for detailed, unambiguous and meaningful answers.
# All predefined answers provided and their formats are appropriate to the question.
# There is room for people to add additional information if they need to.


Adding to that, always keep the user experience in mind. Reading, scrolling and clicking are tiring activities. So,:
# Avoid unnecessary questions.
# Use conditions to avoid asking questions not relevant for a specific participant.
# Keep questions and answers short and easy to read - use appropriate markup.
# Think about the trade-off between scrolling and clicking. Display everything on one page for short questionnaires (5-15 questions, depending on question complexity). Use groups wisely for longer questionnaires, i.e., group questions comprehensibly. Use group descriptions to give a clear statement about the topic of the following questions.
# Avoid confusing participants with different scales, i.e., limit the amount of different scale types, scale scopes and different scale descriptions as much as possible. Try not to change the direction of scales. (There are some methodological exceptions).
#For rating scales, it might be useful to use an even number of rating options to make decision making easier for the respondents (see below).


<syntaxhighlight lang="php">Example for answer scales about how ''good'' something is:


1. Very good


2. Good


3. Quite good


4. Not that good


5. Bad


6. Very bad


Example for answer scales about how ''bad'' something is:


1. Good


2. Fair


3. Bad</syntaxhighlight>


The best way to start designing a survey is to take a second to imagine your ideal feedback. It goes without saying that meaningful responses are the most useful ones, so try to create questions which invite these answers.


How can you go about that? The best method is to separate all the areas and decide what information you need.


For example, imagine you held an event that was open to the public and needed to get some general feedback about the event.


The following survey is an example of one that might be inadequate for eliciting useful responses:


<syntaxhighlight lang="php">Did you enjoy the Event?


( ) Yes


( ) No


How good was the Wi-Fi?


1 2 3 4 5 6 7 8 9 10


( ) ( ) ( ) ( ) ( ) ( ) ( ) ( ) ( ) ( )


Did you have problems getting to the event?


( ) Yes


( ) No


Was the map provided helpful?


( ) Yes


( ) No


How did you feel about the mixture of speakers?


( ) Very sad ( ) Sad( ) Neutral ( ) Happy ( ) Very Happy</syntaxhighlight>


Matrix questions would be a better choice for the above scenario.

==Matrix Questions.== 


As a general rule, scales should only be used for questions pertaining to age, time (maybe), or quantities. Matrix questions have to be worded properly in order to obtain the most useful feedback. Keep in mind that a matrix of compulsory questions can be a bit of a deterrent for your audience because, when not structured properly, they do not allow for any extra information to be gathered.


Chances are if someone is completing your survey, they want to give feedback, and if they don't think they can share anything useful, they'll just close the window and move on.


So what's wrong with the survey above?


Let's look at each question one by one.


'''Question 1''' doesn't really achieve anything. Imagine receiving 100 "no" responses. The response alone does not provide any useful information as to why the participant did not enjoy the event. You would be left wondering about the reason for the "no" responses and also left wondering what to do with the responses. We'll look at a possible improvement to this in a moment.


'''Question 2''' is worse than the first. Referring back to the 3 features of a good survey, we see that questions need to be clear and precise. I'm not an expert in Wi-Fi, but I'm fairly certain that there are better ways of measuring this. What's more, it doesn't allow for a meaningful answer to a question like, "What will you do with the knowledge that 33% of people rated your Wi-Fi as being good vs only 23%?" The 3 features of a good survey also states that the predefined answers need to be appropriate for the question.


It's fairly obvious that using a scale for this question won't help you improve on the quality of your Wi-Fi. There is a definite need for this question to have space for people to add additional information. How could someone report a specific problem without being able to elaborate?


In this case it would be almost impossible to have enough information to properly address the issues that the participant(s) had with the Wi-Fi. Surveys are all about obtaining useful information that you can work with or learn from.


'''Questions 3 & 4''' would have the same results as the first two questions. They only allow for a "yes" or "no" response, and neither provides an opportunity to add details. We provide suggestions after this section on how to improve on these types of questions.


'''Question 5''', the final question, is another ineffective one. Asking for the level of satisfaction about something is not very useful, as every person has different interests, and so everyone will likely have different opinions about each speaker. It's another example of where a "scale" question is being used and shouldn't be.


Have a look at the improved survey below.


<syntaxhighlight lang="php">Did you make use of the in-house Wi-Fi?


( ) Yes


( ) No


Did you experience any problems with the Wi-Fi?


( ) No problems at all


( ) A couple of small issues, nothing major


( ) One or two severe issues


( ) The Wi-Fi was almost totally unusable.


If you experienced problems, could you briefly describe them? (Text field)


Did you have any problems getting to the event?


( ) Yes


( ) No


How did you come to our event?


( ) Train


( ) Car


( ) Bus


( ) Light Rail (IE Tube, Tram)


( ) Walk


Did you use the map from our website?


( ) Yes


( ) No


If you looked at the map, was it detailed enough?


( ) Yes


( ) It gave me a rough idea. I used another map for more detail though.


( ) Not detailed at all


If you didn't use the map, why not?


( ) Not enough detail


( ) I used a satnav/Google maps instead.


( ) I didn't even know it existed!


Generally speaking, were the speakers interesting? Did you enjoy the presentations?


( ) Nearly all were interesting and thoroughly enjoyable


( ) Mainly enjoyable, but a handful of less interesting talks.


( ) A 50 - 50 split


( ) More dull than interesting


( ) Didn't find any interesting


Please elaborate on your answer to the question above. Feel free to reference any


particular people/talks. (Text field)


If we could improve the range of talks, or you have any other interesting ideas regarding


the talks, list them below (Text field)


If you have any other recommendations or ideas, please list them below. (Text field)</syntaxhighlight>


This survey may be a little longer, but it is a lot easier to answer and interpret the responses. Asking two or three questions about each of the topics means that, when it comes to processing the results, you can do a little more analysis. For example, imagine that in response to the first survey question you received 30 people saying they had problems making it to the event.


This would have been as much information as you could extract from the results, but with the new set of answers it would be possible to deduce which forms of transport presented people with problems. What's more, you could go on to see whether they were using the map provided or another form of navigation, and use this to target improvements in the future.


''' Keep in mind, that after 50 questions, the user is most likely to stop reading'''


Other important additions are the text field questions. These allow your participants to give specific feedback which you can draw from. It's a good idea to not make these compulsory, as they may put people off answering.


To conclude, when writing a survey, you should aim to create one that asks specific questions to obtain more useful information for analysis. Also, remember that it is helpful to gather a little extra background information, as it can be used to better analyze the responses.


It is also important to phrase your questions properly. If people need to answer the questions, and they don't understand them they will close the window and move on. If possible, have someone else proofread your survey before making it publicly available to ensure that the questions are clear.

==Survey Bias== 


In conducting market research, an important key in obtaining unbiased responses is to avoid asking survey participants questions that may influence the responses they provide. Avoiding survey bias helps eliminate responses that may invalidate or skew the data collected.
It is quite easy and common for a company or individual without the proper market research training/knowledge to err in this way. This applies to many things, such as the way a question is phrased, to the types of responses that are available to choose from, to the way that an interviewer presents the questions if data is being collected by phone or in-person.


The following is an example of a biased question:


<syntaxhighlight lang="php">How much did you enjoy the event?


( )Very much


( )Just a little


( )Not very much


( )Not at all</syntaxhighlight>


At first glance, it appears that there is no problem with the structure of this question. After all, the respondent has choices ranging from "very much" to "not at all." However, the problem is in the way the question is phrased. By asking the participant "How much" he or she enjoyed the event, the person conducting the survey has already established a bias by assuming that the respondent enjoyed the event in some way or another, which may not be the case.


The following example would be a better way to ask the question in a way that does not influence the participant's response:


<syntaxhighlight lang="php">How would you rate your overall enjoyment of the event on a scale of 1 - 5: 1 = "Not at all" and 5 = "Completely enjoyed"


1 2 3 4 5


( ) ( ) ( ) ( ) ( )</syntaxhighlight>


Rephrasing the question allows the respondent to answer using a scale that makes it easy for him or her to specify the enjoyment level, and makes it easy for the person conducting the survey to tabulate and compare the results with other respondents. Of course, more questions should be added to gather specifics on what the participants enjoyed or didn't enjoy.


This is just one example of how minor changes in wording can improve your survey.
</translate>

Survey participants

2023-02-08T19:52:03Z

Mazi: URL fix

<languages /> <translate>

__TOC__

=Introduction= 


The Survey Participants functionality allows you to invite a group of people to participate in your survey, keep track of who has completed the survey, and ensure that each person can only participate once. The survey participants table feature allows you to do the following:
*Import a list of names and email addresses for participants from a [[Survey_participants#Import participants from a CSV file|CSV]] file or a [[Survey_participants#Import participants from an LDAP query|LDAP query]];
*Generate a unique token code for each participant (invitation code);
*Send an email invitation to each person on your list (by group or individually);
*Send a reminder email to each person on your list who has not yet responded (by group or individually);
*Track who has responded from your survey participants list;
*Restrict access for people who have not received a token, and those with a token who have already responded;
*Edit/change any details in your list;
*Create email templates for invitations & reminders.


Once the survey is switched to ''Closed-access'' mode '''only the people that provide a unique token code (that has not been already used) can access the survey'''. (You need to create a survey participants table first for the respective survey).


If you enable the [[Participant settings|Allow public registration]] option from the '''Survey participants table''' panel, the survey participants will be able to register for your survey by receiving an automatically generated token code.


{{Note|Some tokens-related settings are stored in the [[Participant settings|participant settings]] panel.}}

=How to create a survey participants table= 


to ''initialize'' a survey participants table: '''Settings''' > '''Survey menu''' > '''Survey participants''':


<center>[[File:Survey_participants_settings_tab.png]]</center>


The following message will be displayed:


<center>[[File:Switch-to-closed-access-mode-2.png]]</center>


If you ''initialize a participant table'', the survey will be accessible only to those participants who provide a token code in the registration process (either manually or by URL). This way, the survey will be switched to closed-access mode.


Once initialized, a window will be displayed confirming the creation of the survey participants table.

==Reactivate a survey participants table== 


When you delete a survey participants table, a backup is created. It can later be reactivated if you wish to use that specific survey participants table in another survey.


<center>[[File:Restore old token tables.png]]</center>

=The survey participants table management tools= 


A ''survey participant summary'' will be displayed if the survey participants table was previously created. This is the default screen:


<center>[[File:Survey participant summary.png]]</center>


*'''Total records:''' The number of survey participants from the survey participants table;
*'''Total with no unique token:''' Displays the number of users without an assigned token code;
*'''Total invitations sent:''' Shows the number of invitations that have been sent to your survey participants from the '''Survey participants''' table by using the Invitations option from the [[Survey participants#Invitations & reminders|Invitations & reminders]] menu;
*'''Total opted out:''' Displays the total number of survey participants that have decided [[Email_templates#Participant opt-out|to opt out]] from the survey;
*'''Total screened out:''' Used to screen and exclude potential participants who do not match certain criteria.
*'''Total surveys completed:''' Shows the number of the surveys that have been completed by those users who have been allocated a token code.


Above the '''Survey participant summary''' table, you will find the '''survey participants table management tools''':


<center>[[File:token-menu2.png]]</center>


*[[Survey participants#Display participants|Display participants]]: Displays a survey participants table with all the current participants. From the browse screen you can edit or delete individual entries from the table as well as perform a number of other useful functions (see the [[Survey participants#Display participants|Display participants wiki]] section below for more details);
*[[Survey participants#Create...|Create...]]: Allows the survey administrator to add respondents into the survey participants table either via the '''Add participant''' option or via the '''Import participants''' function;
*[[Survey participants#Manage attributes|Manage attributes]]: Allows the survey administrator to add additional fields to the survey participants table to store custom participant data;
*[[Survey participants#Export|Export]]: To export the token tables and use them in other surveys, use this function. The file will be saved in the .CSV format;
*[[Survey participants#Invitations & reminders|Survey participants]]: Allows you to invite or remind your participants from the survey participants table to fill out your online survey;
*[[Survey participants#Generate tokens|Generate tokens]]: Allows the survey administrator to quickly allocate a random unique token code to each user from the survey participants table that does not have one;
*[[Survey participants#View in CPDB|View in CPDB]]: Provides quick access to your LimeSurvey installation [[Central Participant Database|central participant database]] (CPDB). From there you can allocate CPDB users as survey participants to any survey.

==Display participants== 


Shows the entries list from the survey participants table and allows the user to:
*[[Survey participants#Sort the survey participants|sort the survey participants]];
*[[Survey participants#Filter the survey participants|filter the survey participants]];
*[[Survey participants#Perform certain actions to an individual entry|perform certain actions to an individual entry]];
*[[Survey participants#Perform a specific action to more than one entry|perform certain actions to more than one entry]].


<center>[[File:token-actions.png]]</center>

===Sort survey participants=== 


The second row of the table includes various criteria that can help the survey administrator sort the entries. If you click on any of the columns/criteria from the table, the screen will be refreshed, showing the survey participants ordered in accordance to the criterion you just clicked on. Click twice on it to get the results displayed in a descending order.


<center>[[File:Display participants - sort.png]]</center>

===Filter survey participants=== 


To filter survey participants, choose the column that you want to filter. Then type in the values/strings that you want to filter on in the empty box below the desired column.


<center>[[File:Display participants - filter.png]]</center>


For example, type "OK" in the email status field to return only those participants that have a valid email address.


<div class="simplebox">[[File:help.png]] '''Hint:''' You can also use operators when filtering the survey participants (e.g.,: >, <, >=, <=, = ). </div>


{{Alert|title=Attention|text=To filter "invitation sent", "reminder sent", and "survey completed" columns, use "=N" or "<>N", meaning "equal No" and "not equal No", respectively.}}

===Perform a specific action to an individual entry=== 


The '''Action''' column is where you can find all the actions that are available for each individual entry from the survey participants table. The possible actions that can be performed are:


<center>[[File:Display participants - participant action.png]]</center>


*'''View response details:''' If the survey is a "tracked" (i.e., not anonymous) survey, another button will appear, allowing you to view the response from this individual entry;
*'''Launch the survey with this token:''' Used to execute a survey by using the generated token code;
*'''Send email invitation:''' Use this option to send an email invitation to the respective participant to complete the survey;
*'''Edit the survey participant:''' Click to change survey participant data;
*'''Delete survey participant:''' Click to delete that particular entry;
*'''View this person in the central participant database''': An icon will be displayed if the respective entry can also be found in the central participant database.

===Perform a specific action to more than one entry=== 


On the bottom-left part of the table, you will find the '''Selected participant(s)...''' button that allows you to perform certain actions at a macro level:


<center>[[File:Display participants - participants actions.png]]</center>


*'''Send email invitations:''' Send email invitations to the selected survey participants;
*'''Send email reminder:''' Send email reminders to the selected survey participants;
*'''Add participants to central database:''' To use some of the token entries in another survey, add the selected participants to the [[Central Participant Database|central participant database]]. From there, you have the option to add the participants to any survey you wish. For more details, continue reading the [[Central_Participant_Database#Share_this_participant|Share this participant]] wiki page.


{{Box|Before executing any of the functions mentioned above, do not forget to select the survey participants upon which the action will be performed.}}

==Create...== 


To have more participants listed in the survey participants table, you can add new ones or import them from a CSV file or LDAP query.


<center>[[File:Survey participants - Create....png]]</center>

===Add participant=== 


A typical token entry contains the following fields:


<center>[[File:token_editing2.png]]</center>


*'''ID:''' An integer that is automatically assigned to each survey participant;
*'''Completed?''': Disabled by default. If enabled, it would contain the date when the survey was completed. No invitations or reminders are sent to the respective users if this is enabled. It is automatically enabled if the respective survey participant completed the survey using his or her assigned token code;
*'''First name:''' The first name of the survey participant;
*'''Last name:''' The last name of the survey participant;
*'''Token:''' This is the invitation code. It can be manually or automatically generated (via the '''Generate tokens''' button);
*'''Language:''' Here you can select the default language of the survey for the respective participant;
*'''Email:''' The email address of the participant;
*'''Email status:''' This field helps you track invalid email addresses. For instance, if the survey administrator received email error notifications from this email, then they can set this field to anything other than "OK" (for instance "user unknown" or "mailbox quota exceeded"). Marking this field with an email status other than "OK" will help skip this entry when sending invitation or reminder emails. Note that this is completely manual, unless you decide to implement a script which updates this field automatically;
*'''Invitation sent?:''' If enabled, contains the date when the invitation email was sent;
*'''Reminder sent?:''' If enabled, contains the date when the reminder email was sent;
*'''Uses left:''' Counts the number of times the token can be used. ''Note:'' When increasing this value (default = 1) for a user who has already filled out the survey (which sets uses left to 0), you also have to switch the '''Completed''' field from "Yes" to "No";
*'''Valid from:''' & '''Until:'''You can set a date/time range for when this token can be used. You can leave these empty if you don't want to limit the participation time frame for certain users. If the user is answering the survey and the participation time ends, then the user is locked out immediately and won't be able to finish the survey.


Note that the '''Add survey participant''' panel has two tabs: the '''General tab''' and the '''Additional attributes''' tab. The additional attributes tab offers you access to your custom attributes - read the following [[Survey participants#Manage attributes|wiki section]] for more details.

===Create dummy participants=== 


A dummy participant can be used when you do not want to send tokens by email to survey participants, but give them token codes by other means. For example, students doing class evaluations could be given a paper with an invitation code to be entered at the beginning of the online survey. This way, the likelihood of receiving more responses and feedback increases.


Click '''''Create dummy participants''''' and the following page will be displayed:


<center>[[File:Survey participants - create a dummy participant.png]]</center>


The ''Number of participants'' field allows you to enter the number of dummy participants you want to add to your survey participants table. The explanation of the other fields can be found in the [[Survey participants#Add participant|Add participant]] wiki subsection.


After completing the fields, press '''Save''' located in the upper-right part of the screen.


To check whether they were added or not, check the Survey participants table:


<center>[[File:Dummy variables - simple example.png]]</center>

===Import participants from a CSV file=== 


The import function allows you to import information from a [[Survey participants#Import participants from a CSV file|CSV file]] or [[Survey participants#Import participants from a LDAP query|LDAP query]].


<center>[[File:survey participants - import csv.png]]</center>


*'''Choose the CSV file to upload:''' Pick the CSV file you wish to import. To eliminate any possible errors, we recommend that you import a standard CSV (comma delimited) file with optional double quotes around values (default for OpenOffice and Excel).


'''The first line must contain the field names'''. It <u>must</u> also contain the following fields: ''firstname, lastname, email''.


They have to contain at least one character. Simply adding double quotes and no characters between them will not work!


The other fields are optional: ''emailstatus, token, language, validfrom, validuntil, attribute_1, attribute_2, attribute_3, usesleft, ... .''


{{Hint|Text=To obtain a full list of token field names, [[Survey participants#Export|export an existing survey participants table]].}}


{{Hint|Text=The date format for the "validfrom" and "validuntil" fields in the CSV token inport file is "YYYY-MM-DD HH:MM".}}


*'''Character set of the file:''' Select the option that fits the characters used in the CSV file;
*'''Separator used:''' You can let LimeSurvey automatically discover the used separator in your CSV or select either the ''comma'' separator or the ''semicolon'' one;
*'''Filter blank email addresses:''' If enabled, the survey participants without an email address will not be imported into your survey participants table;
*'''Allow invalid email addresses:''' If disabled, this function will look into the email addresses fields and check whether the addresses have the structure of an email or not (e.g.: a@a.net);
*'''Display attribute warnings:''' If enabled, after the importing process warnings will be displayed in case there is something wrong with the fields. For example. you might get an attribute warning if nothing is provided in any of the mandatory fields or if an email is incorrectly introduced in the CSV file.


*'''Filter duplicate records:''' If enabled, you can set which fields are used to identify duplicates. By default First name, Last name & Email-address are preselected. If a duplicate is found while importing, the related line is omitted.


*'''Duplicates are determined by:''' Select the fields that you want to filter on for duplicates.


You can also import customized attributes when importing a CSV file. You will have to define what attributes will be added. You can do it like this:


<code>email,attribute_1 <Casenr>, token, attribute_2 <Title>, attribute_3 <destination>, lastname,firstname,attribute_4 <Sender></code>


Once you are done choosing the desired importing settings, do not forget to click on the '''Upload''' button.

====Troubleshooting the import of survey participants==== 


A common error when users try to import tokens is an invalid CSV file. This is often caused by Microsoft Excel. Many users have a list of email addresses saved as an XLS document. A file can be saved as CSV in Excel. However, depending on the locale of the OS, Microsoft Excel may use semi-colons (;) as comma separator, while a standard CSV file uses commas (,) as separators. If you do not know which one you use, open the file with a standard text editor and verify which separator was used.


Recommended free raw text editors are: [http://www.pspad.com/ PSPad], [http://www.flos-freeware.ch/notepad2.html NotePad2] or [http://notepad-plus-plus.org/ Notepad++] for Windows, and [http://www.barebones.com/products/textwrangler/ TextWrangler] for Macintosh.


{{Box|LimeSurvey should also detect semicolons as separators. However, in case the import process is not properly working, replace the semicolons with commas. Double quotes should also be added around values.}}

===Import participants from a LDAP query=== 


{{Alert|title=Attention|text=This option is recommended only to those users with advanced knowledge in LDAP queries.}}


This import function allows you to import information from a LDAP query (tested on openLdap, but should work in any LDAP compliant directory including ActiveDirectory). The following options are available on the ''Import survey participants from LDAP'' page:


<center>[[File:Import survey participants from LDAP.png]]</center>


* Queries are manually defined by the system administrator in the config-ldap.php file.
* Duplicates are identified by First Name, Last Name & Email-Address. If a duplicate is found while importing, the related line is omitted (unless you have unchecked the ''Filter Duplicates'' checkbox).


{{Note|For more details about the LDAP settings in LimeSurvey, read the [[LDAP settings|following wiki page]].}}

==Manage attributes== 


This option allows you to add/edit the additional fields of your survey participants table. The extra fields are used to store custom survey participants data.


<center>[[File:Survey participants - Add attributes.png]]</center>


Type in the number of new attribute fields you want to add to your survey participants table. Click the '''Add fields''' button. The following page will be displayed:


<center>[[File:token_manage.png]]</center>


The attribute fields table contains the following fields:
*'''Attribute field:''' The value typed here can be used when you want to perform different operations with the respective custom attribute field such as applying [[Setting conditions|conditions]] based on attribute fields or when exporting results for non-anonymous surveys.
*'''Field description:''' Used to replace the '''attribute field''' name. By giving a custom name to each attribute field, they will look nicer in the administration panel, when you browse tokens, when creating conditions based on attribute fields or when you export results for non-anonymous surveys.
*'''Mandatory?:''' If enabled, the respective attribute field must be filled in by the survey administrator. Otherwise, the respondent cannot be registered into the survey participants table.
*'''Show during registration?:''' If the survey participants have to register before completing a survey, certain details will be requested from them. If disabled, the respective attribute field won't appear on the survey registration page.
*'''Field caption:''' Use this fields to add more details about the role/usage of the respective attribute field.
*'''CPDB mapping:''' Maps the attribute in order to connect it to its corresponding attribute from the central participant database.
*'''Example data:''' Contains string examples from different fields. For example, if you want to ask for the gender of the survey participant, then you will see in the '''Example data''' field examples such as male, female, no answer etc.


Once you have finished filling in the boxes, do not forget to click the '''Save''' button located in the bottom-left part of the screen.


<div class="simplebox">[[File:help.png]] Detailed instructions on how to add additional attribute fields and use conditions based on these values can be found on this blog post: "[http://www.limesurvey-consulting.com/limesurvey-conditions-based-on-token-attributes/ Conditions based on token attributes]".</div>


To add more fields, go to the bottom of the page, and type in the '''Number of attribute fields to add''' box the desired number and click the '''Add fields''' button.


If you want to delete a custom attribute, go to the bottom of the page and select from the drop-down list situated under the '''Delete this attribute''' field the attribute you want to delete. Once selected, click '''Delete attribute''' and confirm the deletion.

==Export== 


To export a survey participants table, click the "Export" button located on the token management tools toolbar. Before exporting the survey participants list, select the desired export options.


<center>[[File:Survey participants - export.png]]</center>


*'''Survey status:'''
**''All tokens:'' Exports all survey participants from the survey participants table;
**''Completed:'' Exports only those survey participants that have completed the survey;
**''Not completed:'' Exports survey participants that have not yet completed the survey;
**''Not started:'' Exports the survey participants that have not yet started the survey;
**''Started but not yet completed:'' Exports survey participants that have already started the survey, but have not completed it.
*'''Invitation status:''' Exports participants according to the invitation status: ''all'', ''invited'', and ''not invited'';
*'''Reminder status:''' Exports participants according to the reminder status: ''all'', ''Reminder(s) sent'', ''No reminder(s) sent'';
*'''Filter by language:''' When you create a survey, you can add additional languages besides the base language. Those additional languages can be used to export survey participants according to the language they are assigned to;
*'''Filter by email address:''' Exports entries which contain the string in the respective email address. For example, you can use it if some of your survey participants use the work email addresses from "Company A". Type ''@companya.com'' and export only the users that have received a work email address from the respective company;
*'''Delete exported participants:''' If enabled, the exported users will be deleted from your survey participants table.


Once you have selected the exporting options, click the '''Download CSV file''' button located in the upper right part of the screen.


<div class="simplebox">
When you export your survey participants, the fields are exported in the following order:
<code>tid,firstname,lastname,email,emailstatus,token,language code,attribute_1,attribute_2,...</code></div>

==Invitations & reminders== 


''Invitations & Reminders'' allows you to manage the LimeSurvey invitations system. You can send invitations or reminders to participants displayed in your [[Survey participants#Display participants|survey participants table]]. An [[Email bounce tracking system|email bounce tracking system]] can be used to help you track and mark the emails that were not delivered to the recipients (survey participants).

===Send email invitation=== 


From the survey participants table you can send email invitations in bulk to all participants who have not been sent one.


<center>[[File:token-invite.png]]</center>


You can skip survey participants who have an email status that is not "OK" by enabling the '''Bypass token with failing email addresses''' option.


To overcome the [[Survey_participants#Add_participant|validity settings]] of all of your entries, enable the '''Bypass date control before sending email''' function. This way, the LimeSurvey email function will not take into account the date/time range when a token would be allowed to be used.

==== Resending invitations==== 


Use this functionality to send invitations again to certain survey participants. When you use the '''send invitations''' function, only an email address that ''has not previously received an invitation'' will get one. This means that if you add new email addresses to the survey participants list after the first invitations are sent, only these new addresses will receive an invitation the second time you send invitations.


This means that you can also edit an email address in a particular table entry that you received a bounced email from and then send it only to this edited address. Do this by turning off the '''Invitation sent''' field and then click '''send invitations''' again.

===Send email reminder=== 


Sends bulk email reminders to all participants from the survey participants table who have not yet responded, but have been sent their first invitation.


<center>[[File:token-remind.png]]</center>


When sending reminders you can:
* '''Bypass tokens with failing email addresses:''' those entries with a failing email address will be skipped - they will not receive an email;
* '''Min days between reminders:''' skip tokens if a reminder has been "recently" sent;
* '''Max reminders:''' skip tokens if a given number of reminders have already been sent;
* '''Bypass date control before sending email:''' skip those entries that are not within the time-frame that they can be used.


<div class="simplebox">[[File:help.png]] '''Note:''' A reminder will be sent only to those participants where the "Completed" field is turned off (this means the respondent has either not taken or completed the survey).</div>

==== Sending emails by batch==== 


When sending a large number of emails at the same time, LimeSurvey will only send the first batch of N emails (this threshold is set by the administrator from the [[Global settings#Email settings|email settings]], located in the global settings of your LimeSurvey installation).

=== Confirmation email=== 


If you are using tokens and a participant fills out the survey, a confirmation email is sent to their email address.


If you do not want this message sent, deactivate this functionality from [[Participant settings|the general settings of your survey]].

==Start bounce processing== 


When sending an email, the LimeSurvey email bounce tracking system automatically adds a survey-id and token-id to the mail header. These "custom headers" are added to each invitation email that is sent through your LimeSurvey installation to survey participants. When the email is bounced back, the original header along with the "''Delivery notification''" header is received. The system then checks for new emails and parses the emails that have these custom headers and marks the wrong email address in the survey participants table.

===Bounce settings=== 


'''Bounce settings''' options:


<center>[[File:surveyBounseSettings.png]]</center>


For a short description of each field, check [[Global settings#Bounce settings|the following wiki section]]. To use the LimeSurvey installation ''Global settings'', go to '''Used bounce settings''' and select the '''Use global settings''' option.


{{Note|For more in-depth explanations, check our wiki on [[Email bounce tracking system|email bounce tracking system]].}}


Click the [[Email_bounce_tracking_system#Setting_up_the_system|following link]] for more information on how to correctly configure this feature.

==Edit email templates== 


To find out more about what placeholders you can use or how you can edit the LimeSurvey email templates, read our wiki section on [[Email templates|email templates]].

==Generate tokens== 


With the help of this function, unique tokens can be created for all the individual entries from the survey participants table that have not yet received a token code.


<center>[[File:Survey participants - Generate tokens.png]]</center>

==View in CPDB== 


The last option on the tokens management toolbar is the '''View in CPDB''' option. This allows the survey administrator to see the participants that exist in both the central participant database and the survey participants list.


In the following example, we have the following survey participants list:


<center>[[File:Survey participants list - view in cpdb.png]]</center>


The users with ID 1 and 2 have been shared from the central participant database. To check this, go to the survey participants table management toolbar and click '''View in CPDB'''


<center>[[File:View in CPDB - filters.png]]</center>


As you can see, the '''View in CPDB''' function basically applies a filter to determine which users from the CPDB are present in the respective survey.

=Delete table= 


To delete your survey participants table, click the '''Display participants''' button and look for the '''Delete participants table''' button located in the upper-right part of the screen.


<center>[[File:Delete survey participants table.png]]</center>


A window will pop up, asking for the final confirmation.


<center>[[File:Confirmation - delete survey participants table.png]]</center>


Please note that this will not delete the table from your LimeSurvey installation. A backup will be created. In order to access it, you need system administrator rights.


If you do wish to completely remove it, use the [[Check data integrity|check data integrity]] option that is located in the '''Configuration''' dialog.

=Additional hints & tips= 


Feel free to add any hints and tips to the list below. The ones listed were posted by members of our community:
*[[Survey participants#Allowing public registration|Allowing public registration]]
*[[Survey participants#Captchas in public registration|Captchas in public registration]]
*[[Survey participants#Can a survey using tokens ensure anonymous responses?|Can a survey using tokens ensure anonymous responses?]]
*[[Survey participants#A tip for generating a large number of fake e-mail addresses|A tip for generating a large number of fake e-mail addresses]]
*[[Survey participants#Spam problems|Spam problems]]
*[[Survey participants#Pseudonymised participation|Pseudonymised participation]]

==Allowing public registration== 


You can also open your survey to the public by utilizing the type of respondent control available when using tokens. To do this, initialize your survey participants table and choose to [[Participant settings|allow public registration]] in the main survey setup. People who visit your survey's URL without a token will be given the opportunity to register. (This setting can be later changed from the [[Participant settings|participant settings]] section that is located in the settings menu of the survey).


If a participant provides an email address that is not already in the current database, an entry in the survey participants table will be created and they will be emailed an invitation containing their unique token code. All tokens provided to "registering" visitors will begin with the letter "'''R'''".

==CAPTCHAs in public registration== 


To protect your survey from robot registrations, a CAPTCHA feature can be activated for all the registration, save, and load forms. For more details, read our wiki on [[Participant settings|participant settings]].

==Can a survey using tokens ensure anonymous responses?== 


'''Yes''', tokens can be used both for anonymous and non-anonymous surveys. This is determined when creating a survey. If a survey is not anonymous (or 'tracked') then the token list can be used to find the responses that an individual has made to the survey. If the survey is anonymous, then no link (technically: foreign key relationship) is available between the respondents from the survey participants table and their corresponding answers.


To enable or disable anonymized responses, check the [[Participant settings|participant settings]] wiki section.

==A Tip for generating a large number of fake e-mail addresses== 


Sometimes you may need a large number of fake e-mail addresses and tokens. You can use functions in a spreadsheet (e.g. OpenOffice Calc) to generate them. Let's assume you want thousands of addresses in a form: 1@test.com, 2@test.com, 3@test.com, and so on. Type "1" in A1. Insert function =A1+1 in A2, then copy A2 down as many times as you need so that you obtain a list of consecutive numbers. In B1 use the concatenation function to join A1 and "@test.com", which is ''=CONCATENATE(A1;"@test.com")''. Then copy B1 down so that each A cell has a correspondent (you can also generate similarly fake names). Finally, save the file as CSV in order to import it to LimeSurvey.


With the launch of LimeSurvey 1.91, you can use the "Generate dummy token" functionality. However, the dummy entries do not contain any email address.

==Spam problems== 


Users often complain about not receiving invitations or reminder emails because their email spam filters identified the message from LimeSurvey as spam.


The fact that an email is treated as spam depends mostly on the spam filter being used and its settings. A spam filter usually checks the sender address, and the email subject and content. Changing its settings could solve the way in which the users' email providers treat the messages from LimeSurvey.


Some possible issues and solutions are listed in the following [https://www.survey-consulting.com/how-to-prevent-limesurvey-email-invitations-or-reminders-being-treated-as-spam/ Limesurvey Consulting blog post].


LimeSurvey automatically tries to determine the URL for the invitation link by looking at the URL that you logged into the LimeSurvey administration with. However, with some server (mis)configurations this might not work properly and you will have to set this manually.


You can edit "application/config/config.php" to change the default base URL value. Add a ''hostInfo'' property, as shown below, to the existing 'components' array.


<syntaxhighlight lang="php"> 'components' => array(
...
'config' => array(
.......
'publicurl' => 'http://www.example.com',
........
),
)
</syntaxhighlight>


<div class="simplebox">[[File:help.png]]For more details on how to edit the configuration file of your LimeSurvey installation, read our wiki on [[Optional settings|LimeSurvey optional settings]].</div>


Regarding the source of the problem, LimeSurvey tried to determine the domain from the server PHP variable: $_SERVER<nowiki>[</nowiki>'HTTP_HOST'] or $_SERVER<nowiki>[</nowiki>'SERVER_NAME'].


Some web server software do not properly seem to provide this information or are misconfigured.

==Pseudonymised participation== 


With the dummy tokens, you may create a form of pseudonymised participation by exporting the created dummy tokens and then combining them with your participant list externally. That way, LimeSurvey can be used as a survey platform without putting personal information of your participants into the system.


The only downside is that you will have to distribute the participation tokens yourself.

</translate>

Survey quotas

2022-12-15T12:18:11Z

Mazi: Better set expiry date then deactivate

<languages />
<translate>

__TOC__

=Introduction= 


A quota is used to set a limit on responses from defined groups of people on an active survey. Some common attributes used in defining quotas are gender, age, race, province/state, etc. To access the survey quotas panel, from the '''Settings''' ''Survey menu'', select the survey '''Quotas''' tab.


<center>[[File:Survey menu - Survey quotas.png]]</center>


{{Alert|title=Attention|text= You can only verify that Quotas have been set correctly when the survey is activated. So, if you set a quota with a limit of "0" and the survey is not activated, you will not be able to check whether it is working or not.}}

=How do quotas work?= 


To understand how the LimeSurvey quota system works, think of a survey that contains a "Yes or No" question and an Array question, each of them belonging to two different question groups. You set a quota on this survey that contains a restriction of 20 users who have answered "Yes" to this question. The quota will be checked every time someone answers "Yes" to that question.


Depending on [[General_settings#General_settings_panel|the format of your survey]] (how the questions are displayed to your participants), the '''check''' happens either when you submit:


*'''the whole survey answers at once:''' If the format of the survey is ''all in one'', the questions (regardless of the question group they belong to) will be displayed on the same page. Therefore, the user has to click the submit button in order to trigger the quota limit check;


*'''the answers to a question group:''' If the format of the survey is group by group, then the quota is activated when the survey participant has responded to all the questions that belong to the question group where the answer that contains the quota system check is located. Therefore, the quota may be triggered before the end of the survey if, for example, the question group is located in the beginning of the survey.


*'''the answer to a question:''' If the format of the survey is question by question, each question will be displayed separately, each of them being allocated a page. In this case, if you select the answer that the quota is applied to, the quota system will be automatically triggered once you click the ''Next/Submit'' button.


{{Note|To change the format of a survey, access the [[General settings|general settings of your survey]].}}


If "''No''" is chosen, the quota system is not triggered. Therefore, the survey will not restrict anyone from responding to the rest of the questions, unless otherwise specified.


To set a limit on the number of "''No''" responses, you need to add an additional quota, restricting the number of participants who choose "''No''".


<div class="simplebox">[[File:help.png]] '''Note:''' If you would like your participants to answer certain survey questions according to a previous answer, use the LimeSurvey [[ExpressionScript - Presentation|ExpressionScript]].</div>

==Using more answers and quotas== 


'''Example''': You want to conduct a survey where you want to limit it to 25 male and 30 female participants. In this case, you will have to apply two quota limits: one on males and one on females. This will give you a maximum of 25 males who can complete the survey, and a maximum of 30 females who can complete the survey..


Let's suppose now that you want 50 answers from males and 50 answers from females. Please note that each answer that triggers the quota must be introduced in its own quota box. Adding the two answers in the same box will result in collecting 50 answers, regardless of the respondents' gender distribution (e.g., the distribution can be 40 males and 10 females, or 20 males and 30 females, and so on). Continue reading this wiki page and see the [[Survey quotas#Examples|examples]] subsection get a grasp on the usage of the quota system.

==Activating the quota system while the survey responses table is not empty== 


Note that a quota system does not necessarily have to be added before you activate your survey. If you decide to activate the quota system at a later date, it will start to check the survey responses table and look for those entries that are marked as ''complete''. Then, it checks to determine if the quota condition has been met or not. If it has been met, the next survey responses/entries received will be marked as ''incomplete''.


For example, if you have previously gathered 1000 responses from women and you introduced after a couple of weeks the quota limit of 800 for women, the next responses that you receive from women will be marked ''incomplete''. The other 200 answers will appear in the survey responses table as ''complete'' because the quota was applied after the answers were collected.


<center>[[File:Survey_quotas_-_survey_responses_2.png]]</center>


The quota system does not store any answers and it does not record the number of the submitted survey answers! Think of it as a filter that is applied on the survey responses table. Basically, it looks into the '''completed''' column and those question columns that contain the answers to which one or more quotas are applied to.

=Supported question types= 


The quota system can be applied only to the following types of questions at the moment:
*Gender
*Multiple Choice
*Array - 5 Point Choice
*Array - 10 Point Choice
*Language Switch
*Yes/No
*List (Radio)
*List (Dropdown)
*List with comments
*Equation

=Survey quotas panel= 


Once you click the '''Survey quotas''' tab from the survey menu, the following page will be displayed:


<center>[[FIle:Survey quotas - panel.png]]</center>


To see the full set of options of this panel, add one survey quota. Then, the survey quota page will look like the following:


<center>[[File:Survey quotas - image 2.png]]</center>


The following options are available:
*'''[[Survey quotas#Quick CSV report|Add new quota]]:''' Located on the bottom right part of the survey quotas table, it allows users to add new quotas. Once quotas are displayed on the table, you can start implementing them to certain questions/subquestions answers.


*'''[[Survey quotas#Add an answer|Add an answer]]:''' Before adding an answer, you need to add a quota where the answer(s) will be stored in. The quota limit will be applied <u>only</u> to those answers displayed in the quota box.


*'''Edit quota:''' Click the green pencil located under the '''Action''' column of the survey quotas table to edit the fields of a quota


*'''Delete quota:''' Click the red trash button located under the '''Action''' column of the survey quotas table to delete the respective quota entry;


*'''[[Survey quotas#Quota validation|Quota validation]]:''' Click the last button located under the '''Action''' column of the survey quotas table to quickly check the quota message displayed to the respondents, the URL (and/or a short description of it) where they will be redirected.


*'''[[Survey quotas#Quick CSV report|Quick CSV report]]:''' Exports a summary of the quotas under the form of a comma-delimited CSV table.


*'''Selected quota(s)...:''' Works like an aggregator. Select multiple quotas and use this button to apply one of the actions described below to the selected group of quotas.


<center>[[File:Survey quotas - Selected quota(s).png]]</center>


**''Activate:'' Use this button to activate a quota. The active ones have the quota name, action, and URL written in white font on a green background.


<center>[[File:Active quota.png]]</center>


**''Deactivate:'' Use this button to deactivate a quota. The deactivated ones have the quota name, action, and URL written in black font on a grey background.


<center>[[File:Deactivated quota.png]]</center>


**''Change texts:'' Use this button to quickly change the quota message, URL, and URL description of a group of a quotas. You may use this function to redirect respondents to a certain link once different quota conditions were met.


<center>[[File:Survey quotas - change texts.png]]</center>


**''Delete:'' If you want to delete a group of quotas by a few clicks, tick the ones you want to delete, click the selected quota(s) button, and select the '''Delete''' option.

==Add new quota== 


'''For a fully working quota you must first "add a quota", and then "add answers" to that quota.'''


Once you click the '''Add new quota''' button, the following page will be displayed:


<center>[[File:Add_new_quota_panel.png]]</center>


{{Note|The fields marked with a star are required fields.}}


The following options are available:


*'''Quota Name:''' The name of the quota that will be displayed on the survey quotas table. It should describe the quota it will represent.


*'''Quota Limit:''' The maximum number of completed surveys that will be stored in the responses table and marked as ''complete''. See above the wiki section on [[Survey_quotas#How do quotas work|how do quotas work]] to better understand the mechanism employed by LimeSurvey.


*'''Quota Action:''' If the quota is triggered, then one of two actions will happen:
**''Terminate survey:'' This action immediately terminates and closes the survey.
**''Allow user to modify his last answers before terminate survey:'' Useful action when you want your participants to choose different options. In this way, you can force some of them choose another solution or option. For example, when incentives are offered, you can use a quota on each option so that not everyone chooses the same incentive.


*'''Autoload URL:''' This tells LimeSurvey to automatically redirect the participant to the URL when the quota action occurs.


*'''Quota Message:''' Write the text you want to be displayed to participants if the quota action is triggered. The message will be displayed if the '''Autoload URL''' is disabled.


*'''URL:''' The URL displayed to survey participants after the quota action is triggered. The users can also be automatically redirected to this URL if "Autoload URL" is enabled. You can use [[URL fields]] in this section.


*'''URL Description:''' A short URL description can be added in order to show to the other survey administrators the purpose of the URL for example.

===Add an answer=== 


Once the quota has been created, you can start adding answers. To add answers, access the Survey quotas panel. Look into the survey quotas table and select the '''Add answer''' option from the quota box that you want to add the respective answer to.


<center>[[File:Survey quotas table - add answer.png]]</center>


A new page will be displayed asking you to select the question the quota will be applied to.


<center>[[File:Add answer - part 1.png]]</center>


{{Box|Please remember that only certain types of questions accept quotas. [[Survey quotas#Supported question types|Click here]] to revisit the supported question types list.}}


Click '''Next'''. The answers of the question you selected one step before will be displayed. Now, you have to choose which answer you want the quota to be applied to.


<center>[[File:Add answer - part 2.png]]</center>


In this example, the "''Male''" answer will have the quota applied to it. Whenever participants choose this option, the quota system registers the answer. Once the quota limit is reached, the stored survey answers will be saved in the survey responses table, but it will be marked 'incomplete''.

==Quick CSV report== 


The quick CSV report function is used to export the survey quotas table in a comma-delimited CSV file. It includes the following fields:
*'''Quota name:''' The name of the quotas;
*'''Limit''': If the quota is active, it represents the maximum number of survey responses that can be marked as ''complete'' in the survey responses table;
*'''Completed:''' The number of survey answers marked as ''complete'' in the survey responses table. Please note that an answer is marked as ''incomplete'' if the quota is triggered.
*'''Remaining:''' The number of answers that can still be collected in the survey responses table and marked as ''complete'' there.

=Quota and tokens= 


When tokens are used in a survey and a participant is ''screened out'' due to a quota, then the respective token entry from the survey responses table is marked with the letter "Q" in the '''completed''' column from the survey responses table. The token is invalidated in this way and the survey participant cannot restart the survey.

=Examples= 


The following examples are used to better explain the role of quotas and their usage within the LimeSurvey environment. Before viewing the following examples, please take into account that:


*Answers added in the same quota are summed up. For example, if answers A and B from the available responses of a survey question are added to quota Q1, the quota limit '''sums up''' the number of users who pick up A and B as their answers. Therefore, there is a high probability that the distribution of A and B answers will be uneven (dependent on the characteristics or preferences of your respondents).


*Answers added in different quotas act as if there is a logical operator "AND" between them. Let's suppose that A is added to Q1 and B to Q2. If A is chosen and Q1 is reached, then respondents won't get their answers marked ''complete'' in the survey responses table. However, the survey participants that choose B are still allowed to continue as long as Q2 is not reached. Once it is reached, participants who further choose A or B as answers to that specific question will have their answers marked ''incomplete'' in the survey responses table.


<center>[[File:Survey quotas - survey responses.png]]</center>

==Adding more answers to different quotas== 


Let's assume that you are doing a survey about LimeSurvey and you would like to receive feedback from your participants. You would like to receive 1000 answers from students (PhD student, graduate, undergraduate) and another 1000 from non-students (unemployed persons, full/part-time working persons or other). In order to do this, create two quotas: '''Students quota''' and '''Non-students quota'''.


<center>[[File:Survey quotas - example - add survey quotas.png]]</center>


Now, start adding answers to each quota box following the steps described above in the [[Survey quotas#Add an answer|wiki section]]. The quota boxes should look like this:


<center>[[File:Survey quotas - example - add answers.png]]</center>


By using this method, you limit the number of responses you receive from the two defined groups: students and non-student groups. Now, activate the survey and start testing the quotas. If you first reach 1000 answers from the '''non-students''' group, the next answers you receive from this category will be marked as 'incomplete'' in the survey responses table. Only answers that come from the students group will still be accepted. Once it also reaches 1000, no more answers will be registered as ''complete'' in the survey responses table.


{{Box|However, the survey can still be accessed by the participants! Set an expiry date (e.g. yesterday) once you see that the quota limit has been reached.}}

==Adding a URL link== 


To add a URL link to a quota, please continue reading the [[URL fields|URL fields]] wiki section.

==Using of equation question for quota in other question type== 


You can use [[Question_type_-_Equation|Equation Question]] to set a value to [[Survey_quotas#Supported_question_types|supported question types]] and [[Expression_Manager#Using_Assignment_Operator|assignment operator]].


The 2 question can be hidden, quota is checked if all question are hidden or when one question is in submitted page.


For example , to set a quota to a text question (user write ok or not) on a Y/N question: <code>{QuotaQuestion=if(strtolower(Q00.NAOK) == 'ok', 'Y', 'N')</code>


[[File:QuotaEquation.png]]


You can import and activate this sample survey [[File:Limesurvey_survey_quotaEquationAndOptOut.zip]] (remember to unzip the file and activate the survey).

==Limiting max number of responses in survey using a hidden question== 


Like using an equation to set a value to an answer, quota for default values are checked if a question is hidden. This allows you to set a maximum number of response in a specific survey. You put a quota on the default answer in a hidden question and put this question in a simple group.


You can import and activate this sample survey [[File:Quota_by_default_value_sample_survey.zip]] (remember to unzip the file and activate the survey).

</translate>

Email templates/de

2022-09-14T11:00:54Z

Mazi: Created page with "Klicken Sie auf die Registerkarte „Registrierung“, um Details dieser Email zu bearbeiten. Sie können verschiedene Email-Platzhalter..."

<languages />

=Einleitung=

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen werden verwendet um Teilnehmern personalisierte Einladungen, Bestätigungen und Erinnerungen per E-Mail zu schicken. Dies ist von der Umfrageteilnehmerverwaltung aus möglich. Sie können hier auch die Basis und die ausführliche Admin-Benachrichtigung an den Umfrageadministrator anpassen.
</div>

<div class="mw-translate-fuzzy">
Um zur Einstellungsansicht zu kommen, öffnen Sie den Reiter '''Einstellungen''' und klicken Sie auf den '''E-Mail Vorlagen''' Menüpunkt.
</div>

<center>[[File:Location email templates.png]]</center>

<div class="mw-translate-fuzzy">
<div class="simplebox">[[File:help.png]] Wenn Sie Superadministratorprivilegien haben (wenn Sie Zugriff auf die [[Globale Einstellungen| globalen Einstellungen Ihrer LimeSurvey Installation]]), können Sie den Standard HTML-Editor für all Ihre LimeSurvey Nutzer einstellen. Weitere Informationen hierzu bekommen Sie [[Global_settings#General|in diesem Artikel]].</div>
</div>

<div class="mw-translate-fuzzy">
{{Alert|title=Attention|text=WEnn Sie den HTML editor nutzen möchten, vergessen Sie nicht '''Benutze HTML-Format für Einladungs-E-Mails''' zu aktivieren. Diese Einstellung finden Sie im Reiter '''Einstellungen''' in Ihrer Umfrage, unter dem Punkt [[Teilnehmereinstellungen]].}}
</div>

<div class="mw-translate-fuzzy">
=E-mail Vorlagen Ansicht=
</div>

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen Ansicht sieht so aus:
</div>

<center>[[File:Email templates panel.png]]</center>

<div class="mw-translate-fuzzy">
Wie in dem Screenshot zu sehen ist, wird der "HTML Quellcode" Editormodus genutzt. Diesen können Sie in Ihren [[First_login_-_your_user_preferences#HTML_editor_mode| persönlichen Einstellungen]] ändern.
</div>

<div class="mw-translate-fuzzy">
{{Note|Um möglichst einfach mit den Textfeldern zu arbeiten, gehen Sie in Ihre Profileinstellungen und ändern den HTML Editor Modus zu ''inline HTML Editor''.}}
</div>

<div class="mw-translate-fuzzy">
Wie Sie sehen können gibt es fünf Typen von E-Mails deren Vorlagen Sie bearbeiten können:
*[[Email templates#Invitation|Einladung]]
*[[Email templates#Reminder|Erinnerung]]
*[[Email templates#Confirmation|Bestätigung]]
*[[Email templates#Registration|Registierung]]
*[[Email templates#Basic & detailed admin notifications|Basis & Ausführliche Admin Benachrichtigung]]
</div>

==Einladung==

<div class="mw-translate-fuzzy">
Das Einladungssystem ist nützlich, wenn Sie E-Mails in großen Mengen an alle Befragten aus Ihrer [[Survey participants/de#E-Mail-Einladung senden|Umfrageteilnehmertabelle]] senden möchten, die noch keine Einladung zum Ausfüllen Ihrer Umfrage erhalten haben.
</div>

<div class="mw-translate-fuzzy">
Im Bereich E-Mail-Vorlagen können Sie die Nachricht bearbeiten, die diese Umfrageteilnehmer erreicht. Lesen Sie den folgenden Abschnitt [[Email templates/de#E-Mail-Platzhalter|Wiki-Unterabschnitt]], um zu überprüfen, welche E-Mail-Platzhalter verwendet werden können. Sie können auch [[ExpressionScript - Presentation/de|ExpressionScript]] verwenden, um die Anpassung Ihrer Einladungs-E-Mail-Vorlage zu verbessern.
</div>

== Erinnerung ==

Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die [[Survey_participants#Send_email_reminder|Teilnehmer aus der Umfrageteilnehmertabelle]] an die Beantwortung der Umfrage zu erinnern.

You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.

<div class="simplebox">[[File:help.png]] '''Hinweis:''' Eine Erinnerung wird nur an diejenigen Teilnehmer in der [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]] verschickt, bei denen das Feld „Abgeschlossen“ noch leer ist. Dies bedeutet, dass der Befragte entweder noch gar nicht an der Umfrage teilgenommen oder sie zumindest noch nicht abgeschlossen hat.</div>

==Bestätigung==

Wenn Zugangsschlüssel verwendet werden und ein Teilnehmer die Umfrage ausfüllt, wird eine Bestätigungs-Email an seine Email-Adresse gesendet. Sie können diese Funktion im Bereich [[Teilnehmereinstellungen]] deaktivieren.

Klicken Sie auf die Registerkarte '''Bestätigung''', wenn Sie die Email-Vorlage bearbeiten möchten. Überprüfen Sie die [[E-Mail-Vorlagen#E-Mail-Platzhalter|E-Mail-Platzhalter]], um zu sehen, welche PLatzhalter in dieser Email verwendet werden können. Sie können auch das [[ExpressionScript - Presentation|ExpressionScript]] verwenden, um Ihre Email anzupassen.

==Registrierung==

Wenn Sie Ihre Umfrage im geschlossenen Modus durchführen, gibt es gibt eine [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]]). Das bedeutet, dass nur diejenigen Teilnehmer, die dort eingetragen und einen Zugangsschlüssel zugewiesen haben bekommen, die jeweiligen Umfrage ausfüllen können. Wenn Sie den Teilnehmern erlauben, sich [[Teilnehmereinstellungen|öffentlich für Ihre Umfrage zu registrieren]], wird automatisch ein neuer Eintrag in der Umfrageteilnehmertabelle erstellt, sobald der Befragte seinen Namen und seine Email-Adresse im Rahmen der Registrierung eingetragen hat. LimeSurvey sendet dann dem jeweiligen Befragten automatisch eine '''Registrierungs-E-Mail''', die die URL mit dem Zugangsschlüssel des Nutzers enthält.

Klicken Sie auf die Registerkarte „Registrierung“, um Details dieser Email zu bearbeiten. Sie können verschiedene [[E-Mail-Vorlagen#E-Mail-Platzhalter|Email-Platzhalter]] im Textr verwenden. Das [[ExpressionScript - Presentation|ExpressionScript]] Feature kann ebenfalls genutzt werden, um Inhalte weiter anzupassen.

<div class="mw-translate-fuzzy">
== Grundlegende und detaillierte Administratorbenachrichtigungen ==
</div>

To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.

By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.

However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.

<div class="mw-translate-fuzzy">
= E-Mail-Vorlagenfelder =
</div>

Each email template contains:

*'''The subject of the email:''' The title of the email/batch of emails you want to send;

*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;

<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>

*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.

<center>[[File:Validate email - email templates.png]]</center>

<div class="mw-translate-fuzzy">
= E-Mail-Platzhalter =
</div>

{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}

In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.

Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].

{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|-
|{ADMINNAME}||Name of Survey Admin
|-
|{SURVEYNAME}||Title of your survey
|-
|{SURVEYDESCRIPTION}||Description of your survey
|}

The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:

{|class="wikitable"
|{EMAIL}||Email of the recipient
|-
|{FIRSTNAME}||First Name
|-
|{LASTNAME}||Last Name
|-
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{ATTRIBUTE_1}||Attribute 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...and so on for more attribute fields)
|}

If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).

{|class="wikitable"
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}

{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}

These email placeholders can also be used in the confirmation and admin notification email templates.

Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!

Some of the placeholders that can be used only in the admin notification panels are mentioned below:

{|class="wikitable"
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
|-
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
|-
|{STATISTICSURL}||Click this URL to access the statistics of the survey
|-
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
|}

<div class="simplebox">[[File:help.png]] '''Hints:'''
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>

{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}

<div class="mw-translate-fuzzy">
== Teilnehmer-Opt-out ==
</div>

When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].

==Barebone URL==

URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

<div class="mw-translate-fuzzy">
= Ersetzungsfunktion verwenden =
</div>

Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.

The below example uses a plain link to the survey instead of a long url:

1) First, access the email templates panel and choose ''Invitation''.

2) Write the text you want to appear as a link to start the survey.

3) Then select that text.

[[File:mark_text_to_hyperlink.jpg]]

4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.

[[File:add_link_placeholder_choose_other.jpg]]

Now, when you send out your invitation emails, the link to start the survey will be shorter.

<div class="mw-translate-fuzzy">
= E-Mail-Anhänge =
</div>

<div class="mw-translate-fuzzy">
== Dateiaktionen ==
</div>

When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:

[[File:Upload_files_-_email_templates.png]]

Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.

You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.

Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:

[[File:Files_table_-_email_templates.png]]

To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.

To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.

All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.

With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.

If you want to delete a file, click the red trash button located under the Action column and save the changes.

{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}

<div class="mw-translate-fuzzy">
== Bildanhang ==
</div>

You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.

<center>[[File:Image-email-embed.png]]</center>

{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}

Translations:Email templates/119/de

2022-09-14T11:00:53Z

Mazi: Created page with "Klicken Sie auf die Registerkarte „Registrierung“, um Details dieser Email zu bearbeiten. Sie können verschiedene Email-Platzhalter..."

Klicken Sie auf die Registerkarte „Registrierung“, um Details dieser Email zu bearbeiten. Sie können verschiedene [[E-Mail-Vorlagen#E-Mail-Platzhalter|Email-Platzhalter]] im Textr verwenden. Das [[ExpressionScript - Presentation|ExpressionScript]] Feature kann ebenfalls genutzt werden, um Inhalte weiter anzupassen.

Email templates/de

2022-09-14T10:57:29Z

Mazi: Created page with "Wenn Sie Ihre Umfrage im geschlossenen Modus durchführen, gibt es gibt eine Umfrageteilnehmer-Tabelle). Das bedeutet, dass nur diejenigen Teilnehmer, di..."

<languages />

=Einleitung=

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen werden verwendet um Teilnehmern personalisierte Einladungen, Bestätigungen und Erinnerungen per E-Mail zu schicken. Dies ist von der Umfrageteilnehmerverwaltung aus möglich. Sie können hier auch die Basis und die ausführliche Admin-Benachrichtigung an den Umfrageadministrator anpassen.
</div>

<div class="mw-translate-fuzzy">
Um zur Einstellungsansicht zu kommen, öffnen Sie den Reiter '''Einstellungen''' und klicken Sie auf den '''E-Mail Vorlagen''' Menüpunkt.
</div>

<center>[[File:Location email templates.png]]</center>

<div class="mw-translate-fuzzy">
<div class="simplebox">[[File:help.png]] Wenn Sie Superadministratorprivilegien haben (wenn Sie Zugriff auf die [[Globale Einstellungen| globalen Einstellungen Ihrer LimeSurvey Installation]]), können Sie den Standard HTML-Editor für all Ihre LimeSurvey Nutzer einstellen. Weitere Informationen hierzu bekommen Sie [[Global_settings#General|in diesem Artikel]].</div>
</div>

<div class="mw-translate-fuzzy">
{{Alert|title=Attention|text=WEnn Sie den HTML editor nutzen möchten, vergessen Sie nicht '''Benutze HTML-Format für Einladungs-E-Mails''' zu aktivieren. Diese Einstellung finden Sie im Reiter '''Einstellungen''' in Ihrer Umfrage, unter dem Punkt [[Teilnehmereinstellungen]].}}
</div>

<div class="mw-translate-fuzzy">
=E-mail Vorlagen Ansicht=
</div>

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen Ansicht sieht so aus:
</div>

<center>[[File:Email templates panel.png]]</center>

<div class="mw-translate-fuzzy">
Wie in dem Screenshot zu sehen ist, wird der "HTML Quellcode" Editormodus genutzt. Diesen können Sie in Ihren [[First_login_-_your_user_preferences#HTML_editor_mode| persönlichen Einstellungen]] ändern.
</div>

<div class="mw-translate-fuzzy">
{{Note|Um möglichst einfach mit den Textfeldern zu arbeiten, gehen Sie in Ihre Profileinstellungen und ändern den HTML Editor Modus zu ''inline HTML Editor''.}}
</div>

<div class="mw-translate-fuzzy">
Wie Sie sehen können gibt es fünf Typen von E-Mails deren Vorlagen Sie bearbeiten können:
*[[Email templates#Invitation|Einladung]]
*[[Email templates#Reminder|Erinnerung]]
*[[Email templates#Confirmation|Bestätigung]]
*[[Email templates#Registration|Registierung]]
*[[Email templates#Basic & detailed admin notifications|Basis & Ausführliche Admin Benachrichtigung]]
</div>

==Einladung==

<div class="mw-translate-fuzzy">
Das Einladungssystem ist nützlich, wenn Sie E-Mails in großen Mengen an alle Befragten aus Ihrer [[Survey participants/de#E-Mail-Einladung senden|Umfrageteilnehmertabelle]] senden möchten, die noch keine Einladung zum Ausfüllen Ihrer Umfrage erhalten haben.
</div>

<div class="mw-translate-fuzzy">
Im Bereich E-Mail-Vorlagen können Sie die Nachricht bearbeiten, die diese Umfrageteilnehmer erreicht. Lesen Sie den folgenden Abschnitt [[Email templates/de#E-Mail-Platzhalter|Wiki-Unterabschnitt]], um zu überprüfen, welche E-Mail-Platzhalter verwendet werden können. Sie können auch [[ExpressionScript - Presentation/de|ExpressionScript]] verwenden, um die Anpassung Ihrer Einladungs-E-Mail-Vorlage zu verbessern.
</div>

== Erinnerung ==

Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die [[Survey_participants#Send_email_reminder|Teilnehmer aus der Umfrageteilnehmertabelle]] an die Beantwortung der Umfrage zu erinnern.

You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.

<div class="simplebox">[[File:help.png]] '''Hinweis:''' Eine Erinnerung wird nur an diejenigen Teilnehmer in der [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]] verschickt, bei denen das Feld „Abgeschlossen“ noch leer ist. Dies bedeutet, dass der Befragte entweder noch gar nicht an der Umfrage teilgenommen oder sie zumindest noch nicht abgeschlossen hat.</div>

==Bestätigung==

Wenn Zugangsschlüssel verwendet werden und ein Teilnehmer die Umfrage ausfüllt, wird eine Bestätigungs-Email an seine Email-Adresse gesendet. Sie können diese Funktion im Bereich [[Teilnehmereinstellungen]] deaktivieren.

Klicken Sie auf die Registerkarte '''Bestätigung''', wenn Sie die Email-Vorlage bearbeiten möchten. Überprüfen Sie die [[E-Mail-Vorlagen#E-Mail-Platzhalter|E-Mail-Platzhalter]], um zu sehen, welche PLatzhalter in dieser Email verwendet werden können. Sie können auch das [[ExpressionScript - Presentation|ExpressionScript]] verwenden, um Ihre Email anzupassen.

==Registrierung==

Wenn Sie Ihre Umfrage im geschlossenen Modus durchführen, gibt es gibt eine [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]]). Das bedeutet, dass nur diejenigen Teilnehmer, die dort eingetragen und einen Zugangsschlüssel zugewiesen haben bekommen, die jeweiligen Umfrage ausfüllen können. Wenn Sie den Teilnehmern erlauben, sich [[Teilnehmereinstellungen|öffentlich für Ihre Umfrage zu registrieren]], wird automatisch ein neuer Eintrag in der Umfrageteilnehmertabelle erstellt, sobald der Befragte seinen Namen und seine Email-Adresse im Rahmen der Registrierung eingetragen hat. LimeSurvey sendet dann dem jeweiligen Befragten automatisch eine '''Registrierungs-E-Mail''', die die URL mit dem Zugangsschlüssel des Nutzers enthält.

Click the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[ExpressionScript - Presentation|ExpressionScript]] can provide further customization to the body text you wish to use.

<div class="mw-translate-fuzzy">
== Grundlegende und detaillierte Administratorbenachrichtigungen ==
</div>

To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.

By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.

However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.

<div class="mw-translate-fuzzy">
= E-Mail-Vorlagenfelder =
</div>

Each email template contains:

*'''The subject of the email:''' The title of the email/batch of emails you want to send;

*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;

<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>

*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.

<center>[[File:Validate email - email templates.png]]</center>

<div class="mw-translate-fuzzy">
= E-Mail-Platzhalter =
</div>

{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}

In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.

Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].

{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|-
|{ADMINNAME}||Name of Survey Admin
|-
|{SURVEYNAME}||Title of your survey
|-
|{SURVEYDESCRIPTION}||Description of your survey
|}

The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:

{|class="wikitable"
|{EMAIL}||Email of the recipient
|-
|{FIRSTNAME}||First Name
|-
|{LASTNAME}||Last Name
|-
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{ATTRIBUTE_1}||Attribute 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...and so on for more attribute fields)
|}

If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).

{|class="wikitable"
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}

{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}

These email placeholders can also be used in the confirmation and admin notification email templates.

Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!

Some of the placeholders that can be used only in the admin notification panels are mentioned below:

{|class="wikitable"
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
|-
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
|-
|{STATISTICSURL}||Click this URL to access the statistics of the survey
|-
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
|}

<div class="simplebox">[[File:help.png]] '''Hints:'''
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>

{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}

<div class="mw-translate-fuzzy">
== Teilnehmer-Opt-out ==
</div>

When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].

==Barebone URL==

URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

<div class="mw-translate-fuzzy">
= Ersetzungsfunktion verwenden =
</div>

Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.

The below example uses a plain link to the survey instead of a long url:

1) First, access the email templates panel and choose ''Invitation''.

2) Write the text you want to appear as a link to start the survey.

3) Then select that text.

[[File:mark_text_to_hyperlink.jpg]]

4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.

[[File:add_link_placeholder_choose_other.jpg]]

Now, when you send out your invitation emails, the link to start the survey will be shorter.

<div class="mw-translate-fuzzy">
= E-Mail-Anhänge =
</div>

<div class="mw-translate-fuzzy">
== Dateiaktionen ==
</div>

When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:

[[File:Upload_files_-_email_templates.png]]

Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.

You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.

Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:

[[File:Files_table_-_email_templates.png]]

To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.

To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.

All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.

With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.

If you want to delete a file, click the red trash button located under the Action column and save the changes.

{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}

<div class="mw-translate-fuzzy">
== Bildanhang ==
</div>

You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.

<center>[[File:Image-email-embed.png]]</center>

{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}

Translations:Email templates/118/de

2022-09-14T10:57:27Z

Mazi: Created page with "Wenn Sie Ihre Umfrage im geschlossenen Modus durchführen, gibt es gibt eine Umfrageteilnehmer-Tabelle). Das bedeutet, dass nur diejenigen Teilnehmer, di..."

Wenn Sie Ihre Umfrage im geschlossenen Modus durchführen, gibt es gibt eine [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]]). Das bedeutet, dass nur diejenigen Teilnehmer, die dort eingetragen und einen Zugangsschlüssel zugewiesen haben bekommen, die jeweiligen Umfrage ausfüllen können. Wenn Sie den Teilnehmern erlauben, sich [[Teilnehmereinstellungen|öffentlich für Ihre Umfrage zu registrieren]], wird automatisch ein neuer Eintrag in der Umfrageteilnehmertabelle erstellt, sobald der Befragte seinen Namen und seine Email-Adresse im Rahmen der Registrierung eingetragen hat. LimeSurvey sendet dann dem jeweiligen Befragten automatisch eine '''Registrierungs-E-Mail''', die die URL mit dem Zugangsschlüssel des Nutzers enthält.

Email templates/de

2022-09-14T10:53:48Z

Mazi:

<languages />

=Einleitung=

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen werden verwendet um Teilnehmern personalisierte Einladungen, Bestätigungen und Erinnerungen per E-Mail zu schicken. Dies ist von der Umfrageteilnehmerverwaltung aus möglich. Sie können hier auch die Basis und die ausführliche Admin-Benachrichtigung an den Umfrageadministrator anpassen.
</div>

<div class="mw-translate-fuzzy">
Um zur Einstellungsansicht zu kommen, öffnen Sie den Reiter '''Einstellungen''' und klicken Sie auf den '''E-Mail Vorlagen''' Menüpunkt.
</div>

<center>[[File:Location email templates.png]]</center>

<div class="mw-translate-fuzzy">
<div class="simplebox">[[File:help.png]] Wenn Sie Superadministratorprivilegien haben (wenn Sie Zugriff auf die [[Globale Einstellungen| globalen Einstellungen Ihrer LimeSurvey Installation]]), können Sie den Standard HTML-Editor für all Ihre LimeSurvey Nutzer einstellen. Weitere Informationen hierzu bekommen Sie [[Global_settings#General|in diesem Artikel]].</div>
</div>

<div class="mw-translate-fuzzy">
{{Alert|title=Attention|text=WEnn Sie den HTML editor nutzen möchten, vergessen Sie nicht '''Benutze HTML-Format für Einladungs-E-Mails''' zu aktivieren. Diese Einstellung finden Sie im Reiter '''Einstellungen''' in Ihrer Umfrage, unter dem Punkt [[Teilnehmereinstellungen]].}}
</div>

<div class="mw-translate-fuzzy">
=E-mail Vorlagen Ansicht=
</div>

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen Ansicht sieht so aus:
</div>

<center>[[File:Email templates panel.png]]</center>

<div class="mw-translate-fuzzy">
Wie in dem Screenshot zu sehen ist, wird der "HTML Quellcode" Editormodus genutzt. Diesen können Sie in Ihren [[First_login_-_your_user_preferences#HTML_editor_mode| persönlichen Einstellungen]] ändern.
</div>

<div class="mw-translate-fuzzy">
{{Note|Um möglichst einfach mit den Textfeldern zu arbeiten, gehen Sie in Ihre Profileinstellungen und ändern den HTML Editor Modus zu ''inline HTML Editor''.}}
</div>

<div class="mw-translate-fuzzy">
Wie Sie sehen können gibt es fünf Typen von E-Mails deren Vorlagen Sie bearbeiten können:
*[[Email templates#Invitation|Einladung]]
*[[Email templates#Reminder|Erinnerung]]
*[[Email templates#Confirmation|Bestätigung]]
*[[Email templates#Registration|Registierung]]
*[[Email templates#Basic & detailed admin notifications|Basis & Ausführliche Admin Benachrichtigung]]
</div>

==Einladung==

<div class="mw-translate-fuzzy">
Das Einladungssystem ist nützlich, wenn Sie E-Mails in großen Mengen an alle Befragten aus Ihrer [[Survey participants/de#E-Mail-Einladung senden|Umfrageteilnehmertabelle]] senden möchten, die noch keine Einladung zum Ausfüllen Ihrer Umfrage erhalten haben.
</div>

<div class="mw-translate-fuzzy">
Im Bereich E-Mail-Vorlagen können Sie die Nachricht bearbeiten, die diese Umfrageteilnehmer erreicht. Lesen Sie den folgenden Abschnitt [[Email templates/de#E-Mail-Platzhalter|Wiki-Unterabschnitt]], um zu überprüfen, welche E-Mail-Platzhalter verwendet werden können. Sie können auch [[ExpressionScript - Presentation/de|ExpressionScript]] verwenden, um die Anpassung Ihrer Einladungs-E-Mail-Vorlage zu verbessern.
</div>

== Erinnerung ==

Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die [[Survey_participants#Send_email_reminder|Teilnehmer aus der Umfrageteilnehmertabelle]] an die Beantwortung der Umfrage zu erinnern.

You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.

<div class="simplebox">[[File:help.png]] '''Hinweis:''' Eine Erinnerung wird nur an diejenigen Teilnehmer in der [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]] verschickt, bei denen das Feld „Abgeschlossen“ noch leer ist. Dies bedeutet, dass der Befragte entweder noch gar nicht an der Umfrage teilgenommen oder sie zumindest noch nicht abgeschlossen hat.</div>

==Bestätigung==

Wenn Zugangsschlüssel verwendet werden und ein Teilnehmer die Umfrage ausfüllt, wird eine Bestätigungs-Email an seine Email-Adresse gesendet. Sie können diese Funktion im Bereich [[Teilnehmereinstellungen]] deaktivieren.

Klicken Sie auf die Registerkarte '''Bestätigung''', wenn Sie die Email-Vorlage bearbeiten möchten. Überprüfen Sie die [[E-Mail-Vorlagen#E-Mail-Platzhalter|E-Mail-Platzhalter]], um zu sehen, welche PLatzhalter in dieser Email verwendet werden können. Sie können auch das [[ExpressionScript - Presentation|ExpressionScript]] verwenden, um Ihre Email anzupassen.

==Registrierung==

If '''closed-access mode''' is enabled (there is a [[Survey participants|survey participants table]], which means that only those participants who have an allocated entry and a unique token code associated to it can complete the respective survey. If you allow participants [[Participant settings|to publicly register to your survey]], a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a '''registration email'''. It contains the URL with the token that needs to be accessed by the newly registered user.

Click the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[ExpressionScript - Presentation|ExpressionScript]] can provide further customization to the body text you wish to use.

<div class="mw-translate-fuzzy">
== Grundlegende und detaillierte Administratorbenachrichtigungen ==
</div>

To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.

By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.

However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.

<div class="mw-translate-fuzzy">
= E-Mail-Vorlagenfelder =
</div>

Each email template contains:

*'''The subject of the email:''' The title of the email/batch of emails you want to send;

*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;

<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>

*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.

<center>[[File:Validate email - email templates.png]]</center>

<div class="mw-translate-fuzzy">
= E-Mail-Platzhalter =
</div>

{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}

In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.

Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].

{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|-
|{ADMINNAME}||Name of Survey Admin
|-
|{SURVEYNAME}||Title of your survey
|-
|{SURVEYDESCRIPTION}||Description of your survey
|}

The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:

{|class="wikitable"
|{EMAIL}||Email of the recipient
|-
|{FIRSTNAME}||First Name
|-
|{LASTNAME}||Last Name
|-
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{ATTRIBUTE_1}||Attribute 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...and so on for more attribute fields)
|}

If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).

{|class="wikitable"
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}

{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}

These email placeholders can also be used in the confirmation and admin notification email templates.

Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!

Some of the placeholders that can be used only in the admin notification panels are mentioned below:

{|class="wikitable"
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
|-
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
|-
|{STATISTICSURL}||Click this URL to access the statistics of the survey
|-
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
|}

<div class="simplebox">[[File:help.png]] '''Hints:'''
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>

{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}

<div class="mw-translate-fuzzy">
== Teilnehmer-Opt-out ==
</div>

When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].

==Barebone URL==

URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

<div class="mw-translate-fuzzy">
= Ersetzungsfunktion verwenden =
</div>

Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.

The below example uses a plain link to the survey instead of a long url:

1) First, access the email templates panel and choose ''Invitation''.

2) Write the text you want to appear as a link to start the survey.

3) Then select that text.

[[File:mark_text_to_hyperlink.jpg]]

4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.

[[File:add_link_placeholder_choose_other.jpg]]

Now, when you send out your invitation emails, the link to start the survey will be shorter.

<div class="mw-translate-fuzzy">
= E-Mail-Anhänge =
</div>

<div class="mw-translate-fuzzy">
== Dateiaktionen ==
</div>

When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:

[[File:Upload_files_-_email_templates.png]]

Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.

You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.

Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:

[[File:Files_table_-_email_templates.png]]

To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.

To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.

All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.

With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.

If you want to delete a file, click the red trash button located under the Action column and save the changes.

{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}

<div class="mw-translate-fuzzy">
== Bildanhang ==
</div>

You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.

<center>[[File:Image-email-embed.png]]</center>

{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}

Translations:Email templates/117/de

2022-09-14T10:53:47Z

Mazi:

==Registrierung==

Email templates/de

2022-09-14T10:53:30Z

Mazi: Created page with "Klicken Sie auf die Registerkarte '''Bestätigung''', wenn Sie die Email-Vorlage bearbeiten möchten. Überprüfen Sie die E-Mail-Vorlagen#E-Mail-Platzhalter|E-Mail-Platzhal..."

<languages />

=Einleitung=

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen werden verwendet um Teilnehmern personalisierte Einladungen, Bestätigungen und Erinnerungen per E-Mail zu schicken. Dies ist von der Umfrageteilnehmerverwaltung aus möglich. Sie können hier auch die Basis und die ausführliche Admin-Benachrichtigung an den Umfrageadministrator anpassen.
</div>

<div class="mw-translate-fuzzy">
Um zur Einstellungsansicht zu kommen, öffnen Sie den Reiter '''Einstellungen''' und klicken Sie auf den '''E-Mail Vorlagen''' Menüpunkt.
</div>

<center>[[File:Location email templates.png]]</center>

<div class="mw-translate-fuzzy">
<div class="simplebox">[[File:help.png]] Wenn Sie Superadministratorprivilegien haben (wenn Sie Zugriff auf die [[Globale Einstellungen| globalen Einstellungen Ihrer LimeSurvey Installation]]), können Sie den Standard HTML-Editor für all Ihre LimeSurvey Nutzer einstellen. Weitere Informationen hierzu bekommen Sie [[Global_settings#General|in diesem Artikel]].</div>
</div>

<div class="mw-translate-fuzzy">
{{Alert|title=Attention|text=WEnn Sie den HTML editor nutzen möchten, vergessen Sie nicht '''Benutze HTML-Format für Einladungs-E-Mails''' zu aktivieren. Diese Einstellung finden Sie im Reiter '''Einstellungen''' in Ihrer Umfrage, unter dem Punkt [[Teilnehmereinstellungen]].}}
</div>

<div class="mw-translate-fuzzy">
=E-mail Vorlagen Ansicht=
</div>

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen Ansicht sieht so aus:
</div>

<center>[[File:Email templates panel.png]]</center>

<div class="mw-translate-fuzzy">
Wie in dem Screenshot zu sehen ist, wird der "HTML Quellcode" Editormodus genutzt. Diesen können Sie in Ihren [[First_login_-_your_user_preferences#HTML_editor_mode| persönlichen Einstellungen]] ändern.
</div>

<div class="mw-translate-fuzzy">
{{Note|Um möglichst einfach mit den Textfeldern zu arbeiten, gehen Sie in Ihre Profileinstellungen und ändern den HTML Editor Modus zu ''inline HTML Editor''.}}
</div>

<div class="mw-translate-fuzzy">
Wie Sie sehen können gibt es fünf Typen von E-Mails deren Vorlagen Sie bearbeiten können:
*[[Email templates#Invitation|Einladung]]
*[[Email templates#Reminder|Erinnerung]]
*[[Email templates#Confirmation|Bestätigung]]
*[[Email templates#Registration|Registierung]]
*[[Email templates#Basic & detailed admin notifications|Basis & Ausführliche Admin Benachrichtigung]]
</div>

==Einladung==

<div class="mw-translate-fuzzy">
Das Einladungssystem ist nützlich, wenn Sie E-Mails in großen Mengen an alle Befragten aus Ihrer [[Survey participants/de#E-Mail-Einladung senden|Umfrageteilnehmertabelle]] senden möchten, die noch keine Einladung zum Ausfüllen Ihrer Umfrage erhalten haben.
</div>

<div class="mw-translate-fuzzy">
Im Bereich E-Mail-Vorlagen können Sie die Nachricht bearbeiten, die diese Umfrageteilnehmer erreicht. Lesen Sie den folgenden Abschnitt [[Email templates/de#E-Mail-Platzhalter|Wiki-Unterabschnitt]], um zu überprüfen, welche E-Mail-Platzhalter verwendet werden können. Sie können auch [[ExpressionScript - Presentation/de|ExpressionScript]] verwenden, um die Anpassung Ihrer Einladungs-E-Mail-Vorlage zu verbessern.
</div>

== Erinnerung ==

Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die [[Survey_participants#Send_email_reminder|Teilnehmer aus der Umfrageteilnehmertabelle]] an die Beantwortung der Umfrage zu erinnern.

You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.

<div class="simplebox">[[File:help.png]] '''Hinweis:''' Eine Erinnerung wird nur an diejenigen Teilnehmer in der [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]] verschickt, bei denen das Feld „Abgeschlossen“ noch leer ist. Dies bedeutet, dass der Befragte entweder noch gar nicht an der Umfrage teilgenommen oder sie zumindest noch nicht abgeschlossen hat.</div>

==Bestätigung==

Wenn Zugangsschlüssel verwendet werden und ein Teilnehmer die Umfrage ausfüllt, wird eine Bestätigungs-Email an seine Email-Adresse gesendet. Sie können diese Funktion im Bereich [[Teilnehmereinstellungen]] deaktivieren.

Klicken Sie auf die Registerkarte '''Bestätigung''', wenn Sie die Email-Vorlage bearbeiten möchten. Überprüfen Sie die [[E-Mail-Vorlagen#E-Mail-Platzhalter|E-Mail-Platzhalter]], um zu sehen, welche PLatzhalter in dieser Email verwendet werden können. Sie können auch das [[ExpressionScript - Presentation|ExpressionScript]] verwenden, um Ihre Email anzupassen.

== Registrierung ==

If '''closed-access mode''' is enabled (there is a [[Survey participants|survey participants table]], which means that only those participants who have an allocated entry and a unique token code associated to it can complete the respective survey. If you allow participants [[Participant settings|to publicly register to your survey]], a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a '''registration email'''. It contains the URL with the token that needs to be accessed by the newly registered user.

Click the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[ExpressionScript - Presentation|ExpressionScript]] can provide further customization to the body text you wish to use.

<div class="mw-translate-fuzzy">
== Grundlegende und detaillierte Administratorbenachrichtigungen ==
</div>

To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.

By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.

However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.

<div class="mw-translate-fuzzy">
= E-Mail-Vorlagenfelder =
</div>

Each email template contains:

*'''The subject of the email:''' The title of the email/batch of emails you want to send;

*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;

<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>

*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.

<center>[[File:Validate email - email templates.png]]</center>

<div class="mw-translate-fuzzy">
= E-Mail-Platzhalter =
</div>

{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}

In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.

Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].

{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|-
|{ADMINNAME}||Name of Survey Admin
|-
|{SURVEYNAME}||Title of your survey
|-
|{SURVEYDESCRIPTION}||Description of your survey
|}

The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:

{|class="wikitable"
|{EMAIL}||Email of the recipient
|-
|{FIRSTNAME}||First Name
|-
|{LASTNAME}||Last Name
|-
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{ATTRIBUTE_1}||Attribute 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...and so on for more attribute fields)
|}

If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).

{|class="wikitable"
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}

{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}

These email placeholders can also be used in the confirmation and admin notification email templates.

Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!

Some of the placeholders that can be used only in the admin notification panels are mentioned below:

{|class="wikitable"
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
|-
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
|-
|{STATISTICSURL}||Click this URL to access the statistics of the survey
|-
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
|}

<div class="simplebox">[[File:help.png]] '''Hints:'''
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>

{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}

<div class="mw-translate-fuzzy">
== Teilnehmer-Opt-out ==
</div>

When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].

==Barebone URL==

URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

<div class="mw-translate-fuzzy">
= Ersetzungsfunktion verwenden =
</div>

Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.

The below example uses a plain link to the survey instead of a long url:

1) First, access the email templates panel and choose ''Invitation''.

2) Write the text you want to appear as a link to start the survey.

3) Then select that text.

[[File:mark_text_to_hyperlink.jpg]]

4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.

[[File:add_link_placeholder_choose_other.jpg]]

Now, when you send out your invitation emails, the link to start the survey will be shorter.

<div class="mw-translate-fuzzy">
= E-Mail-Anhänge =
</div>

<div class="mw-translate-fuzzy">
== Dateiaktionen ==
</div>

When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:

[[File:Upload_files_-_email_templates.png]]

Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.

You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.

Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:

[[File:Files_table_-_email_templates.png]]

To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.

To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.

All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.

With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.

If you want to delete a file, click the red trash button located under the Action column and save the changes.

{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}

<div class="mw-translate-fuzzy">
== Bildanhang ==
</div>

You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.

<center>[[File:Image-email-embed.png]]</center>

{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}

Translations:Email templates/116/de

2022-09-14T10:53:29Z

Klicken Sie auf die Registerkarte '''Bestätigung''', wenn Sie die Email-Vorlage bearbeiten möchten. Überprüfen Sie die [[E-Mail-Vorlagen#E-Mail-Platzhalter|E-Mail-Platzhalter]], um zu sehen, welche PLatzhalter in dieser Email verwendet werden können. Sie können auch das [[ExpressionScript - Presentation|ExpressionScript]] verwenden, um Ihre Email anzupassen.

Email templates/de

2022-09-14T10:52:43Z

Mazi: Created page with "Wenn Zugangsschlüssel verwendet werden und ein Teilnehmer die Umfrage ausfüllt, wird eine Bestätigungs-Email an seine Email-Adresse gesendet. Sie können diese Funktion im..."

<languages />

=Einleitung=

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen werden verwendet um Teilnehmern personalisierte Einladungen, Bestätigungen und Erinnerungen per E-Mail zu schicken. Dies ist von der Umfrageteilnehmerverwaltung aus möglich. Sie können hier auch die Basis und die ausführliche Admin-Benachrichtigung an den Umfrageadministrator anpassen.
</div>

<div class="mw-translate-fuzzy">
Um zur Einstellungsansicht zu kommen, öffnen Sie den Reiter '''Einstellungen''' und klicken Sie auf den '''E-Mail Vorlagen''' Menüpunkt.
</div>

<center>[[File:Location email templates.png]]</center>

<div class="mw-translate-fuzzy">
<div class="simplebox">[[File:help.png]] Wenn Sie Superadministratorprivilegien haben (wenn Sie Zugriff auf die [[Globale Einstellungen| globalen Einstellungen Ihrer LimeSurvey Installation]]), können Sie den Standard HTML-Editor für all Ihre LimeSurvey Nutzer einstellen. Weitere Informationen hierzu bekommen Sie [[Global_settings#General|in diesem Artikel]].</div>
</div>

<div class="mw-translate-fuzzy">
{{Alert|title=Attention|text=WEnn Sie den HTML editor nutzen möchten, vergessen Sie nicht '''Benutze HTML-Format für Einladungs-E-Mails''' zu aktivieren. Diese Einstellung finden Sie im Reiter '''Einstellungen''' in Ihrer Umfrage, unter dem Punkt [[Teilnehmereinstellungen]].}}
</div>

<div class="mw-translate-fuzzy">
=E-mail Vorlagen Ansicht=
</div>

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen Ansicht sieht so aus:
</div>

<center>[[File:Email templates panel.png]]</center>

<div class="mw-translate-fuzzy">
Wie in dem Screenshot zu sehen ist, wird der "HTML Quellcode" Editormodus genutzt. Diesen können Sie in Ihren [[First_login_-_your_user_preferences#HTML_editor_mode| persönlichen Einstellungen]] ändern.
</div>

<div class="mw-translate-fuzzy">
{{Note|Um möglichst einfach mit den Textfeldern zu arbeiten, gehen Sie in Ihre Profileinstellungen und ändern den HTML Editor Modus zu ''inline HTML Editor''.}}
</div>

<div class="mw-translate-fuzzy">
Wie Sie sehen können gibt es fünf Typen von E-Mails deren Vorlagen Sie bearbeiten können:
*[[Email templates#Invitation|Einladung]]
*[[Email templates#Reminder|Erinnerung]]
*[[Email templates#Confirmation|Bestätigung]]
*[[Email templates#Registration|Registierung]]
*[[Email templates#Basic & detailed admin notifications|Basis & Ausführliche Admin Benachrichtigung]]
</div>

==Einladung==

<div class="mw-translate-fuzzy">
Das Einladungssystem ist nützlich, wenn Sie E-Mails in großen Mengen an alle Befragten aus Ihrer [[Survey participants/de#E-Mail-Einladung senden|Umfrageteilnehmertabelle]] senden möchten, die noch keine Einladung zum Ausfüllen Ihrer Umfrage erhalten haben.
</div>

<div class="mw-translate-fuzzy">
Im Bereich E-Mail-Vorlagen können Sie die Nachricht bearbeiten, die diese Umfrageteilnehmer erreicht. Lesen Sie den folgenden Abschnitt [[Email templates/de#E-Mail-Platzhalter|Wiki-Unterabschnitt]], um zu überprüfen, welche E-Mail-Platzhalter verwendet werden können. Sie können auch [[ExpressionScript - Presentation/de|ExpressionScript]] verwenden, um die Anpassung Ihrer Einladungs-E-Mail-Vorlage zu verbessern.
</div>

== Erinnerung ==

Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die [[Survey_participants#Send_email_reminder|Teilnehmer aus der Umfrageteilnehmertabelle]] an die Beantwortung der Umfrage zu erinnern.

You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.

<div class="simplebox">[[File:help.png]] '''Hinweis:''' Eine Erinnerung wird nur an diejenigen Teilnehmer in der [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]] verschickt, bei denen das Feld „Abgeschlossen“ noch leer ist. Dies bedeutet, dass der Befragte entweder noch gar nicht an der Umfrage teilgenommen oder sie zumindest noch nicht abgeschlossen hat.</div>

==Bestätigung==

Wenn Zugangsschlüssel verwendet werden und ein Teilnehmer die Umfrage ausfüllt, wird eine Bestätigungs-Email an seine Email-Adresse gesendet. Sie können diese Funktion im Bereich [[Teilnehmereinstellungen]] deaktivieren.

Click the '''Confirmation''' tab if you want to edit the email template. Check the [[Email templates#Email placeholders|email placeholders]] to see which ones can be used in this type of email. You may also use the [[ExpressionScript - Presentation|ExpressionScript]] to customize your email.

== Registrierung ==

If '''closed-access mode''' is enabled (there is a [[Survey participants|survey participants table]], which means that only those participants who have an allocated entry and a unique token code associated to it can complete the respective survey. If you allow participants [[Participant settings|to publicly register to your survey]], a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a '''registration email'''. It contains the URL with the token that needs to be accessed by the newly registered user.

Click the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[ExpressionScript - Presentation|ExpressionScript]] can provide further customization to the body text you wish to use.

<div class="mw-translate-fuzzy">
== Grundlegende und detaillierte Administratorbenachrichtigungen ==
</div>

To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.

By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.

However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.

<div class="mw-translate-fuzzy">
= E-Mail-Vorlagenfelder =
</div>

Each email template contains:

*'''The subject of the email:''' The title of the email/batch of emails you want to send;

*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;

<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>

*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.

<center>[[File:Validate email - email templates.png]]</center>

<div class="mw-translate-fuzzy">
= E-Mail-Platzhalter =
</div>

{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}

In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.

Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].

{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|-
|{ADMINNAME}||Name of Survey Admin
|-
|{SURVEYNAME}||Title of your survey
|-
|{SURVEYDESCRIPTION}||Description of your survey
|}

The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:

{|class="wikitable"
|{EMAIL}||Email of the recipient
|-
|{FIRSTNAME}||First Name
|-
|{LASTNAME}||Last Name
|-
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{ATTRIBUTE_1}||Attribute 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...and so on for more attribute fields)
|}

If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).

{|class="wikitable"
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}

{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}

These email placeholders can also be used in the confirmation and admin notification email templates.

Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!

Some of the placeholders that can be used only in the admin notification panels are mentioned below:

{|class="wikitable"
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
|-
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
|-
|{STATISTICSURL}||Click this URL to access the statistics of the survey
|-
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
|}

<div class="simplebox">[[File:help.png]] '''Hints:'''
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>

{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}

<div class="mw-translate-fuzzy">
== Teilnehmer-Opt-out ==
</div>

When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].

==Barebone URL==

URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

<div class="mw-translate-fuzzy">
= Ersetzungsfunktion verwenden =
</div>

Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.

The below example uses a plain link to the survey instead of a long url:

1) First, access the email templates panel and choose ''Invitation''.

2) Write the text you want to appear as a link to start the survey.

3) Then select that text.

[[File:mark_text_to_hyperlink.jpg]]

4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.

[[File:add_link_placeholder_choose_other.jpg]]

Now, when you send out your invitation emails, the link to start the survey will be shorter.

<div class="mw-translate-fuzzy">
= E-Mail-Anhänge =
</div>

<div class="mw-translate-fuzzy">
== Dateiaktionen ==
</div>

When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:

[[File:Upload_files_-_email_templates.png]]

Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.

You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.

Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:

[[File:Files_table_-_email_templates.png]]

To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.

To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.

All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.

With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.

If you want to delete a file, click the red trash button located under the Action column and save the changes.

{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}

<div class="mw-translate-fuzzy">
== Bildanhang ==
</div>

You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.

<center>[[File:Image-email-embed.png]]</center>

{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}

Translations:Email templates/115/de

2022-09-14T10:52:42Z

Wenn Zugangsschlüssel verwendet werden und ein Teilnehmer die Umfrage ausfüllt, wird eine Bestätigungs-Email an seine Email-Adresse gesendet. Sie können diese Funktion im Bereich [[Teilnehmereinstellungen]] deaktivieren.

Email templates/de

2022-09-14T10:52:10Z

Mazi: Created page with "==Bestätigung=="

<languages />

=Einleitung=

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen werden verwendet um Teilnehmern personalisierte Einladungen, Bestätigungen und Erinnerungen per E-Mail zu schicken. Dies ist von der Umfrageteilnehmerverwaltung aus möglich. Sie können hier auch die Basis und die ausführliche Admin-Benachrichtigung an den Umfrageadministrator anpassen.
</div>

<div class="mw-translate-fuzzy">
Um zur Einstellungsansicht zu kommen, öffnen Sie den Reiter '''Einstellungen''' und klicken Sie auf den '''E-Mail Vorlagen''' Menüpunkt.
</div>

<center>[[File:Location email templates.png]]</center>

<div class="mw-translate-fuzzy">
<div class="simplebox">[[File:help.png]] Wenn Sie Superadministratorprivilegien haben (wenn Sie Zugriff auf die [[Globale Einstellungen| globalen Einstellungen Ihrer LimeSurvey Installation]]), können Sie den Standard HTML-Editor für all Ihre LimeSurvey Nutzer einstellen. Weitere Informationen hierzu bekommen Sie [[Global_settings#General|in diesem Artikel]].</div>
</div>

<div class="mw-translate-fuzzy">
{{Alert|title=Attention|text=WEnn Sie den HTML editor nutzen möchten, vergessen Sie nicht '''Benutze HTML-Format für Einladungs-E-Mails''' zu aktivieren. Diese Einstellung finden Sie im Reiter '''Einstellungen''' in Ihrer Umfrage, unter dem Punkt [[Teilnehmereinstellungen]].}}
</div>

<div class="mw-translate-fuzzy">
=E-mail Vorlagen Ansicht=
</div>

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen Ansicht sieht so aus:
</div>

<center>[[File:Email templates panel.png]]</center>

<div class="mw-translate-fuzzy">
Wie in dem Screenshot zu sehen ist, wird der "HTML Quellcode" Editormodus genutzt. Diesen können Sie in Ihren [[First_login_-_your_user_preferences#HTML_editor_mode| persönlichen Einstellungen]] ändern.
</div>

<div class="mw-translate-fuzzy">
{{Note|Um möglichst einfach mit den Textfeldern zu arbeiten, gehen Sie in Ihre Profileinstellungen und ändern den HTML Editor Modus zu ''inline HTML Editor''.}}
</div>

<div class="mw-translate-fuzzy">
Wie Sie sehen können gibt es fünf Typen von E-Mails deren Vorlagen Sie bearbeiten können:
*[[Email templates#Invitation|Einladung]]
*[[Email templates#Reminder|Erinnerung]]
*[[Email templates#Confirmation|Bestätigung]]
*[[Email templates#Registration|Registierung]]
*[[Email templates#Basic & detailed admin notifications|Basis & Ausführliche Admin Benachrichtigung]]
</div>

==Einladung==

<div class="mw-translate-fuzzy">
Das Einladungssystem ist nützlich, wenn Sie E-Mails in großen Mengen an alle Befragten aus Ihrer [[Survey participants/de#E-Mail-Einladung senden|Umfrageteilnehmertabelle]] senden möchten, die noch keine Einladung zum Ausfüllen Ihrer Umfrage erhalten haben.
</div>

<div class="mw-translate-fuzzy">
Im Bereich E-Mail-Vorlagen können Sie die Nachricht bearbeiten, die diese Umfrageteilnehmer erreicht. Lesen Sie den folgenden Abschnitt [[Email templates/de#E-Mail-Platzhalter|Wiki-Unterabschnitt]], um zu überprüfen, welche E-Mail-Platzhalter verwendet werden können. Sie können auch [[ExpressionScript - Presentation/de|ExpressionScript]] verwenden, um die Anpassung Ihrer Einladungs-E-Mail-Vorlage zu verbessern.
</div>

== Erinnerung ==

Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die [[Survey_participants#Send_email_reminder|Teilnehmer aus der Umfrageteilnehmertabelle]] an die Beantwortung der Umfrage zu erinnern.

You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.

<div class="simplebox">[[File:help.png]] '''Hinweis:''' Eine Erinnerung wird nur an diejenigen Teilnehmer in der [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]] verschickt, bei denen das Feld „Abgeschlossen“ noch leer ist. Dies bedeutet, dass der Befragte entweder noch gar nicht an der Umfrage teilgenommen oder sie zumindest noch nicht abgeschlossen hat.</div>

==Bestätigung==

If tokens are used and a participant fills out the survey, a confirmation email will be sent to his/her email address. You can deactivate this functionality from the [[Participant settings]] panel.

Click the '''Confirmation''' tab if you want to edit the email template. Check the [[Email templates#Email placeholders|email placeholders]] to see which ones can be used in this type of email. You may also use the [[ExpressionScript - Presentation|ExpressionScript]] to customize your email.

== Registrierung ==

If '''closed-access mode''' is enabled (there is a [[Survey participants|survey participants table]], which means that only those participants who have an allocated entry and a unique token code associated to it can complete the respective survey. If you allow participants [[Participant settings|to publicly register to your survey]], a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a '''registration email'''. It contains the URL with the token that needs to be accessed by the newly registered user.

Click the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[ExpressionScript - Presentation|ExpressionScript]] can provide further customization to the body text you wish to use.

<div class="mw-translate-fuzzy">
== Grundlegende und detaillierte Administratorbenachrichtigungen ==
</div>

To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.

By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.

However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.

<div class="mw-translate-fuzzy">
= E-Mail-Vorlagenfelder =
</div>

Each email template contains:

*'''The subject of the email:''' The title of the email/batch of emails you want to send;

*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;

<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>

*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.

<center>[[File:Validate email - email templates.png]]</center>

<div class="mw-translate-fuzzy">
= E-Mail-Platzhalter =
</div>

{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}

In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.

Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].

{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|-
|{ADMINNAME}||Name of Survey Admin
|-
|{SURVEYNAME}||Title of your survey
|-
|{SURVEYDESCRIPTION}||Description of your survey
|}

The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:

{|class="wikitable"
|{EMAIL}||Email of the recipient
|-
|{FIRSTNAME}||First Name
|-
|{LASTNAME}||Last Name
|-
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{ATTRIBUTE_1}||Attribute 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...and so on for more attribute fields)
|}

If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).

{|class="wikitable"
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}

{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}

These email placeholders can also be used in the confirmation and admin notification email templates.

Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!

Some of the placeholders that can be used only in the admin notification panels are mentioned below:

{|class="wikitable"
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
|-
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
|-
|{STATISTICSURL}||Click this URL to access the statistics of the survey
|-
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
|}

<div class="simplebox">[[File:help.png]] '''Hints:'''
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>

{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}

<div class="mw-translate-fuzzy">
== Teilnehmer-Opt-out ==
</div>

When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].

==Barebone URL==

URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

<div class="mw-translate-fuzzy">
= Ersetzungsfunktion verwenden =
</div>

Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.

The below example uses a plain link to the survey instead of a long url:

1) First, access the email templates panel and choose ''Invitation''.

2) Write the text you want to appear as a link to start the survey.

3) Then select that text.

[[File:mark_text_to_hyperlink.jpg]]

4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.

[[File:add_link_placeholder_choose_other.jpg]]

Now, when you send out your invitation emails, the link to start the survey will be shorter.

<div class="mw-translate-fuzzy">
= E-Mail-Anhänge =
</div>

<div class="mw-translate-fuzzy">
== Dateiaktionen ==
</div>

When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:

[[File:Upload_files_-_email_templates.png]]

Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.

You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.

Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:

[[File:Files_table_-_email_templates.png]]

To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.

To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.

All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.

With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.

If you want to delete a file, click the red trash button located under the Action column and save the changes.

{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}

<div class="mw-translate-fuzzy">
== Bildanhang ==
</div>

You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.

<center>[[File:Image-email-embed.png]]</center>

{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}

Translations:Email templates/114/de

2022-09-14T10:52:09Z

Mazi: Created page with "==Bestätigung=="

==Bestätigung==

Email templates/de

2022-09-14T10:51:58Z

Mazi: Created page with "<div class="simplebox">File:help.png '''Hinweis:''' Eine Erinnerung wird nur an diejenigen Teilnehmer in der Umfrageteilnehmer-Tabelle verschickt, be..."

<languages />

=Einleitung=

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen werden verwendet um Teilnehmern personalisierte Einladungen, Bestätigungen und Erinnerungen per E-Mail zu schicken. Dies ist von der Umfrageteilnehmerverwaltung aus möglich. Sie können hier auch die Basis und die ausführliche Admin-Benachrichtigung an den Umfrageadministrator anpassen.
</div>

<div class="mw-translate-fuzzy">
Um zur Einstellungsansicht zu kommen, öffnen Sie den Reiter '''Einstellungen''' und klicken Sie auf den '''E-Mail Vorlagen''' Menüpunkt.
</div>

<center>[[File:Location email templates.png]]</center>

<div class="mw-translate-fuzzy">
<div class="simplebox">[[File:help.png]] Wenn Sie Superadministratorprivilegien haben (wenn Sie Zugriff auf die [[Globale Einstellungen| globalen Einstellungen Ihrer LimeSurvey Installation]]), können Sie den Standard HTML-Editor für all Ihre LimeSurvey Nutzer einstellen. Weitere Informationen hierzu bekommen Sie [[Global_settings#General|in diesem Artikel]].</div>
</div>

<div class="mw-translate-fuzzy">
{{Alert|title=Attention|text=WEnn Sie den HTML editor nutzen möchten, vergessen Sie nicht '''Benutze HTML-Format für Einladungs-E-Mails''' zu aktivieren. Diese Einstellung finden Sie im Reiter '''Einstellungen''' in Ihrer Umfrage, unter dem Punkt [[Teilnehmereinstellungen]].}}
</div>

<div class="mw-translate-fuzzy">
=E-mail Vorlagen Ansicht=
</div>

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen Ansicht sieht so aus:
</div>

<center>[[File:Email templates panel.png]]</center>

<div class="mw-translate-fuzzy">
Wie in dem Screenshot zu sehen ist, wird der "HTML Quellcode" Editormodus genutzt. Diesen können Sie in Ihren [[First_login_-_your_user_preferences#HTML_editor_mode| persönlichen Einstellungen]] ändern.
</div>

<div class="mw-translate-fuzzy">
{{Note|Um möglichst einfach mit den Textfeldern zu arbeiten, gehen Sie in Ihre Profileinstellungen und ändern den HTML Editor Modus zu ''inline HTML Editor''.}}
</div>

<div class="mw-translate-fuzzy">
Wie Sie sehen können gibt es fünf Typen von E-Mails deren Vorlagen Sie bearbeiten können:
*[[Email templates#Invitation|Einladung]]
*[[Email templates#Reminder|Erinnerung]]
*[[Email templates#Confirmation|Bestätigung]]
*[[Email templates#Registration|Registierung]]
*[[Email templates#Basic & detailed admin notifications|Basis & Ausführliche Admin Benachrichtigung]]
</div>

==Einladung==

<div class="mw-translate-fuzzy">
Das Einladungssystem ist nützlich, wenn Sie E-Mails in großen Mengen an alle Befragten aus Ihrer [[Survey participants/de#E-Mail-Einladung senden|Umfrageteilnehmertabelle]] senden möchten, die noch keine Einladung zum Ausfüllen Ihrer Umfrage erhalten haben.
</div>

<div class="mw-translate-fuzzy">
Im Bereich E-Mail-Vorlagen können Sie die Nachricht bearbeiten, die diese Umfrageteilnehmer erreicht. Lesen Sie den folgenden Abschnitt [[Email templates/de#E-Mail-Platzhalter|Wiki-Unterabschnitt]], um zu überprüfen, welche E-Mail-Platzhalter verwendet werden können. Sie können auch [[ExpressionScript - Presentation/de|ExpressionScript]] verwenden, um die Anpassung Ihrer Einladungs-E-Mail-Vorlage zu verbessern.
</div>

== Erinnerung ==

Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die [[Survey_participants#Send_email_reminder|Teilnehmer aus der Umfrageteilnehmertabelle]] an die Beantwortung der Umfrage zu erinnern.

You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.

<div class="simplebox">[[File:help.png]] '''Hinweis:''' Eine Erinnerung wird nur an diejenigen Teilnehmer in der [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]] verschickt, bei denen das Feld „Abgeschlossen“ noch leer ist. Dies bedeutet, dass der Befragte entweder noch gar nicht an der Umfrage teilgenommen oder sie zumindest noch nicht abgeschlossen hat.</div>

==Confirmation==

If tokens are used and a participant fills out the survey, a confirmation email will be sent to his/her email address. You can deactivate this functionality from the [[Participant settings]] panel.

Click the '''Confirmation''' tab if you want to edit the email template. Check the [[Email templates#Email placeholders|email placeholders]] to see which ones can be used in this type of email. You may also use the [[ExpressionScript - Presentation|ExpressionScript]] to customize your email.

== Registrierung ==

If '''closed-access mode''' is enabled (there is a [[Survey participants|survey participants table]], which means that only those participants who have an allocated entry and a unique token code associated to it can complete the respective survey. If you allow participants [[Participant settings|to publicly register to your survey]], a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a '''registration email'''. It contains the URL with the token that needs to be accessed by the newly registered user.

Click the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[ExpressionScript - Presentation|ExpressionScript]] can provide further customization to the body text you wish to use.

<div class="mw-translate-fuzzy">
== Grundlegende und detaillierte Administratorbenachrichtigungen ==
</div>

To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.

By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.

However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.

<div class="mw-translate-fuzzy">
= E-Mail-Vorlagenfelder =
</div>

Each email template contains:

*'''The subject of the email:''' The title of the email/batch of emails you want to send;

*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;

<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>

*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.

<center>[[File:Validate email - email templates.png]]</center>

<div class="mw-translate-fuzzy">
= E-Mail-Platzhalter =
</div>

{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}

In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.

Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].

{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|-
|{ADMINNAME}||Name of Survey Admin
|-
|{SURVEYNAME}||Title of your survey
|-
|{SURVEYDESCRIPTION}||Description of your survey
|}

The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:

{|class="wikitable"
|{EMAIL}||Email of the recipient
|-
|{FIRSTNAME}||First Name
|-
|{LASTNAME}||Last Name
|-
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{ATTRIBUTE_1}||Attribute 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...and so on for more attribute fields)
|}

If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).

{|class="wikitable"
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}

{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}

These email placeholders can also be used in the confirmation and admin notification email templates.

Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!

Some of the placeholders that can be used only in the admin notification panels are mentioned below:

{|class="wikitable"
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
|-
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
|-
|{STATISTICSURL}||Click this URL to access the statistics of the survey
|-
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
|}

<div class="simplebox">[[File:help.png]] '''Hints:'''
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>

{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}

<div class="mw-translate-fuzzy">
== Teilnehmer-Opt-out ==
</div>

When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].

==Barebone URL==

URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

<div class="mw-translate-fuzzy">
= Ersetzungsfunktion verwenden =
</div>

Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.

The below example uses a plain link to the survey instead of a long url:

1) First, access the email templates panel and choose ''Invitation''.

2) Write the text you want to appear as a link to start the survey.

3) Then select that text.

[[File:mark_text_to_hyperlink.jpg]]

4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.

[[File:add_link_placeholder_choose_other.jpg]]

Now, when you send out your invitation emails, the link to start the survey will be shorter.

<div class="mw-translate-fuzzy">
= E-Mail-Anhänge =
</div>

<div class="mw-translate-fuzzy">
== Dateiaktionen ==
</div>

When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:

[[File:Upload_files_-_email_templates.png]]

Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.

You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.

Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:

[[File:Files_table_-_email_templates.png]]

To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.

To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.

All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.

With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.

If you want to delete a file, click the red trash button located under the Action column and save the changes.

{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}

<div class="mw-translate-fuzzy">
== Bildanhang ==
</div>

You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.

<center>[[File:Image-email-embed.png]]</center>

{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}

Translations:Email templates/113/de

2022-09-14T10:51:57Z

Mazi: Created page with "<div class="simplebox">File:help.png '''Hinweis:''' Eine Erinnerung wird nur an diejenigen Teilnehmer in der Umfrageteilnehmer-Tabelle verschickt, be..."

<div class="simplebox">[[File:help.png]] '''Hinweis:''' Eine Erinnerung wird nur an diejenigen Teilnehmer in der [[Umfrageteilnehmer|Umfrageteilnehmer-Tabelle]] verschickt, bei denen das Feld „Abgeschlossen“ noch leer ist. Dies bedeutet, dass der Befragte entweder noch gar nicht an der Umfrage teilgenommen oder sie zumindest noch nicht abgeschlossen hat.</div>

Email templates/de

2022-09-14T10:50:44Z

Mazi: Created page with "Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die Teilnehmer aus der Umfrageteilnehmertabelle an di..."

<languages />

=Einleitung=

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen werden verwendet um Teilnehmern personalisierte Einladungen, Bestätigungen und Erinnerungen per E-Mail zu schicken. Dies ist von der Umfrageteilnehmerverwaltung aus möglich. Sie können hier auch die Basis und die ausführliche Admin-Benachrichtigung an den Umfrageadministrator anpassen.
</div>

<div class="mw-translate-fuzzy">
Um zur Einstellungsansicht zu kommen, öffnen Sie den Reiter '''Einstellungen''' und klicken Sie auf den '''E-Mail Vorlagen''' Menüpunkt.
</div>

<center>[[File:Location email templates.png]]</center>

<div class="mw-translate-fuzzy">
<div class="simplebox">[[File:help.png]] Wenn Sie Superadministratorprivilegien haben (wenn Sie Zugriff auf die [[Globale Einstellungen| globalen Einstellungen Ihrer LimeSurvey Installation]]), können Sie den Standard HTML-Editor für all Ihre LimeSurvey Nutzer einstellen. Weitere Informationen hierzu bekommen Sie [[Global_settings#General|in diesem Artikel]].</div>
</div>

<div class="mw-translate-fuzzy">
{{Alert|title=Attention|text=WEnn Sie den HTML editor nutzen möchten, vergessen Sie nicht '''Benutze HTML-Format für Einladungs-E-Mails''' zu aktivieren. Diese Einstellung finden Sie im Reiter '''Einstellungen''' in Ihrer Umfrage, unter dem Punkt [[Teilnehmereinstellungen]].}}
</div>

<div class="mw-translate-fuzzy">
=E-mail Vorlagen Ansicht=
</div>

<div class="mw-translate-fuzzy">
Die E-Mail Vorlagen Ansicht sieht so aus:
</div>

<center>[[File:Email templates panel.png]]</center>

<div class="mw-translate-fuzzy">
Wie in dem Screenshot zu sehen ist, wird der "HTML Quellcode" Editormodus genutzt. Diesen können Sie in Ihren [[First_login_-_your_user_preferences#HTML_editor_mode| persönlichen Einstellungen]] ändern.
</div>

<div class="mw-translate-fuzzy">
{{Note|Um möglichst einfach mit den Textfeldern zu arbeiten, gehen Sie in Ihre Profileinstellungen und ändern den HTML Editor Modus zu ''inline HTML Editor''.}}
</div>

<div class="mw-translate-fuzzy">
Wie Sie sehen können gibt es fünf Typen von E-Mails deren Vorlagen Sie bearbeiten können:
*[[Email templates#Invitation|Einladung]]
*[[Email templates#Reminder|Erinnerung]]
*[[Email templates#Confirmation|Bestätigung]]
*[[Email templates#Registration|Registierung]]
*[[Email templates#Basic & detailed admin notifications|Basis & Ausführliche Admin Benachrichtigung]]
</div>

==Einladung==

<div class="mw-translate-fuzzy">
Das Einladungssystem ist nützlich, wenn Sie E-Mails in großen Mengen an alle Befragten aus Ihrer [[Survey participants/de#E-Mail-Einladung senden|Umfrageteilnehmertabelle]] senden möchten, die noch keine Einladung zum Ausfüllen Ihrer Umfrage erhalten haben.
</div>

<div class="mw-translate-fuzzy">
Im Bereich E-Mail-Vorlagen können Sie die Nachricht bearbeiten, die diese Umfrageteilnehmer erreicht. Lesen Sie den folgenden Abschnitt [[Email templates/de#E-Mail-Platzhalter|Wiki-Unterabschnitt]], um zu überprüfen, welche E-Mail-Platzhalter verwendet werden können. Sie können auch [[ExpressionScript - Presentation/de|ExpressionScript]] verwenden, um die Anpassung Ihrer Einladungs-E-Mail-Vorlage zu verbessern.
</div>

== Erinnerung ==

Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die [[Survey_participants#Send_email_reminder|Teilnehmer aus der Umfrageteilnehmertabelle]] an die Beantwortung der Umfrage zu erinnern.

You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.

<div class="simplebox">[[File:help.png]] '''Note:''' A reminder will be sent only to those participants in the [[Survey participants|survey participants table]] where the "''Completed''" field is turned off. This means the respondent has either not taken or completed the survey.</div>

==Confirmation==

If tokens are used and a participant fills out the survey, a confirmation email will be sent to his/her email address. You can deactivate this functionality from the [[Participant settings]] panel.

Click the '''Confirmation''' tab if you want to edit the email template. Check the [[Email templates#Email placeholders|email placeholders]] to see which ones can be used in this type of email. You may also use the [[ExpressionScript - Presentation|ExpressionScript]] to customize your email.

== Registrierung ==

If '''closed-access mode''' is enabled (there is a [[Survey participants|survey participants table]], which means that only those participants who have an allocated entry and a unique token code associated to it can complete the respective survey. If you allow participants [[Participant settings|to publicly register to your survey]], a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a '''registration email'''. It contains the URL with the token that needs to be accessed by the newly registered user.

Click the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[ExpressionScript - Presentation|ExpressionScript]] can provide further customization to the body text you wish to use.

<div class="mw-translate-fuzzy">
== Grundlegende und detaillierte Administratorbenachrichtigungen ==
</div>

To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.

By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.

However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.

<div class="mw-translate-fuzzy">
= E-Mail-Vorlagenfelder =
</div>

Each email template contains:

*'''The subject of the email:''' The title of the email/batch of emails you want to send;

*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;

<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>

*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.

<center>[[File:Validate email - email templates.png]]</center>

<div class="mw-translate-fuzzy">
= E-Mail-Platzhalter =
</div>

{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}

In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.

Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].

{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|-
|{ADMINNAME}||Name of Survey Admin
|-
|{SURVEYNAME}||Title of your survey
|-
|{SURVEYDESCRIPTION}||Description of your survey
|}

The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:

{|class="wikitable"
|{EMAIL}||Email of the recipient
|-
|{FIRSTNAME}||First Name
|-
|{LASTNAME}||Last Name
|-
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{ATTRIBUTE_1}||Attribute 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...and so on for more attribute fields)
|}

If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).

{|class="wikitable"
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}

{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}

These email placeholders can also be used in the confirmation and admin notification email templates.

Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!

Some of the placeholders that can be used only in the admin notification panels are mentioned below:

{|class="wikitable"
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
|-
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
|-
|{STATISTICSURL}||Click this URL to access the statistics of the survey
|-
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
|}

<div class="simplebox">[[File:help.png]] '''Hints:'''
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>

{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}

<div class="mw-translate-fuzzy">
== Teilnehmer-Opt-out ==
</div>

When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].

==Barebone URL==

URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

<div class="mw-translate-fuzzy">
= Ersetzungsfunktion verwenden =
</div>

Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.

The below example uses a plain link to the survey instead of a long url:

1) First, access the email templates panel and choose ''Invitation''.

2) Write the text you want to appear as a link to start the survey.

3) Then select that text.

[[File:mark_text_to_hyperlink.jpg]]

4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.

[[File:add_link_placeholder_choose_other.jpg]]

Now, when you send out your invitation emails, the link to start the survey will be shorter.

<div class="mw-translate-fuzzy">
= E-Mail-Anhänge =
</div>

<div class="mw-translate-fuzzy">
== Dateiaktionen ==
</div>

When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:

[[File:Upload_files_-_email_templates.png]]

Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.

You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.

Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:

[[File:Files_table_-_email_templates.png]]

To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.

To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.

All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.

With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.

If you want to delete a file, click the red trash button located under the Action column and save the changes.

{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}

<div class="mw-translate-fuzzy">
== Bildanhang ==
</div>

You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.

<center>[[File:Image-email-embed.png]]</center>

{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}

Translations:Email templates/111/de

2022-09-14T10:50:43Z

Mazi: Created page with "Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die Teilnehmer aus der Umfrageteilnehmertabelle an di..."

Die Funktion „Erinnerung“ bietet Umfrageadministratoren die Möglichkeit, die [[Survey_participants#Send_email_reminder|Teilnehmer aus der Umfrageteilnehmertabelle]] an die Beantwortung der Umfrage zu erinnern.

Email templates

2022-09-14T10:48:58Z

Mazi:

<languages />
<translate>

=Introduction= 


The email templates are used to send personalized invitations, reminders, confirmations, and registration emails to your participants (from the survey participants table). You can also edit the standard basic (or detailed) admin notifications that are sent to the survey administrators.


Email Templates: '''Settings''' > '''Survey menu''' > '''Email templates'''


<center>[[File:Location email templates.png]]</center>


<div class="simplebox">[[File:help.png]] If you have the superadministrator permission (you have access to the [[Global settings|global settings of your LimeSurvey installation]]), you can change the Default HTML editor mode for all of your LimeSurvey users. For further details, continue reading [[Global_settings#General|the following wiki subsection]].</div>


{{Alert|title=Attention|text=If you want to use the popup/inline HTML editor, do not forget to enable the '''HTML format for token emails'''! This is located in the '''Settings menu''' of your survey, under the [[Participant settings]] tab.}}

=Email Templates Panel= 


The email templates panel:


<center>[[File:Email templates panel.png]]</center>


In the above screenshot the "HTML source" editor mode is used. To change it, go to your [[First_login_-_your_user_preferences#HTML_editor_mode|personal account settings]].


{{Note|To edit the text fields, go to your account settings and choose the ''inline HTML editor mode''.}}


Five types of emails can be sent to users or admins:
*[[Email templates#Invitation|Invitation]]
*[[Email templates#Reminder|Reminder]]
*[[Email templates#Confirmation|Confirmation]]
*[[Email templates#Registration|Registration]]
*[[Email templates#Basic & detailed admin notifications|Basic & detailed admin notifications]]

==Invitation== 


This functionality is used to send emails in bulk to all survey participants in the [[Survey participants#Send email invitation|survey participants table]] who have not yet received an invitation to complete your survey.


From the email templates panel, you can edit the message sent to survey participants. To check which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. You can also use the [[ExpressionScript - Presentation|ExpressionScript]] to further customize your invitation email template.

==Reminder== 


The ''Reminder'' functionality provides a way for survey administrators to remind the [[Survey_participants#Send_email_reminder|participants from the survey participants table]] to answer the survey.


You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.


<div class="simplebox">[[File:help.png]] '''Note:''' A reminder will be sent only to those participants in the [[Survey participants|survey participants table]] where the "''Completed''" field is turned off. This means the respondent has either not taken or completed the survey.</div>

==Confirmation== 


If tokens are used and a participant fills out the survey, a confirmation email will be sent to his/her email address. You can deactivate this functionality from the [[Participant settings]] panel.


Click the '''Confirmation''' tab if you want to edit the email template. Check the [[Email templates#Email placeholders|email placeholders]] to see which ones can be used in this type of email. You may also use the [[ExpressionScript - Presentation|ExpressionScript]] to customize your email.

==Registration== 


If '''closed-access mode''' is enabled (there is a [[Survey participants|survey participants table]], which means that only those participants who have an allocated entry and a unique token code associated to it can complete the respective survey. If you allow participants [[Participant settings|to publicly register to your survey]], a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a '''registration email'''. It contains the URL with the token that needs to be accessed by the newly registered user.


Click the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[ExpressionScript - Presentation|ExpressionScript]] can provide further customization to the body text you wish to use.

==Basic & Detailed Admin Notifications== 


To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.


By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.


However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.

=Email Templates Fields= 


Each email template contains:


*'''The subject of the email:''' The title of the email/batch of emails you want to send;


*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;


<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>


*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.


<center>[[File:Validate email - email templates.png]]</center>

=Email Placeholders= 


{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}


In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.


Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].


{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|-
|{ADMINNAME}||Name of Survey Admin
|-
|{SURVEYNAME}||Title of your survey
|-
|{SURVEYDESCRIPTION}||Description of your survey
|}


The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:


{|class="wikitable"
|{EMAIL}||Email of the recipient
|-
|{FIRSTNAME}||First Name
|-
|{LASTNAME}||Last Name
|-
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{EMAILSTATUS}|| Used for skipping emails on email sending. Default email status is "OK".
|-
|{LANGUAGE}|| Used to define the language to be used for emails and survey URL when using multilingual surveys
|-
|{SENT}|| Invitation send date
|-
|{REMINDERSENT }|| Reminder send date
|-
|{REMINDERCOUNT}|| Number of reminders already sent
|-
|{COMPLETED }|| Survey completion date
|-
|{TID}|| Internal ID at token table
|-
|{ATTRIBUTE_1}||Attribute 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...and so on for more attribute fields)
|}


If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).


{|class="wikitable"
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}


{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}


These email placeholders can also be used in the confirmation and admin notification email templates.


Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!


Some of the placeholders that can be used only in the admin notification panels are mentioned below:


{|class="wikitable"
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
|-
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
|-
|{STATISTICSURL}||Click this URL to access the statistics of the survey
|-
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
|}


<div class="simplebox">[[File:help.png]] '''Hints:'''
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>


{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}

==Participant Opt-out== 


When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].

==Barebone URL== 


URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

=Using Replacement Function= 


Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.


The below example uses a plain link to the survey instead of a long url:


1) First, access the email templates panel and choose ''Invitation''.


2) Write the text you want to appear as a link to start the survey.


3) Then select that text.


[[File:mark_text_to_hyperlink.jpg]]


4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.


[[File:add_link_placeholder_choose_other.jpg]]


Now, when you send out your invitation emails, the link to start the survey will be shorter.

= Email Attachments = 

== File Actions == 


When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:


[[File:Upload_files_-_email_templates.png]]


Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.


You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.


Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:


[[File:Files_table_-_email_templates.png]]


To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.


To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.


All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.


With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.


If you want to delete a file, click the red trash button located under the Action column and save the changes.


{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}

== Image Attachment == 


You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.


<center>[[File:Image-email-embed.png]]</center>


{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}
</translate>

Email templates

2022-09-14T10:47:48Z

Mazi: Added additional placeholder according to discussion at https://bugs.limesurvey.org/view.php?id=18345#c71701

<languages />
<translate>

=Introduction= 


The email templates are used to send personalized invitations, reminders, confirmations, and registration emails to your participants (from the survey participants table). You can also edit the standard basic (or detailed) admin notifications that are sent to the survey administrators.


Email Templates: '''Settings''' > '''Survey menu''' > '''Email templates'''


<center>[[File:Location email templates.png]]</center>


<div class="simplebox">[[File:help.png]] If you have the superadministrator permission (you have access to the [[Global settings|global settings of your LimeSurvey installation]]), you can change the Default HTML editor mode for all of your LimeSurvey users. For further details, continue reading [[Global_settings#General|the following wiki subsection]].</div>


{{Alert|title=Attention|text=If you want to use the popup/inline HTML editor, do not forget to enable the '''HTML format for token emails'''! This is located in the '''Settings menu''' of your survey, under the [[Participant settings]] tab.}}

=Email Templates Panel= 


The email templates panel:


<center>[[File:Email templates panel.png]]</center>


In the above screenshot the "HTML source" editor mode is used. To change it, go to your [[First_login_-_your_user_preferences#HTML_editor_mode|personal account settings]].


{{Note|To edit the text fields, go to your account settings and choose the ''inline HTML editor mode''.}}


Five types of emails can be sent to users or admins:
*[[Email templates#Invitation|Invitation]]
*[[Email templates#Reminder|Reminder]]
*[[Email templates#Confirmation|Confirmation]]
*[[Email templates#Registration|Registration]]
*[[Email templates#Basic & detailed admin notifications|Basic & detailed admin notifications]]

==Invitation== 


This functionality is used to send emails in bulk to all survey participants in the [[Survey participants#Send email invitation|survey participants table]] who have not yet received an invitation to complete your survey.


From the email templates panel, you can edit the message sent to survey participants. To check which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. You can also use the [[ExpressionScript - Presentation|ExpressionScript]] to further customize your invitation email template.

==Reminder== 


The ''Reminder'' functionality provides a way for survey administrators to remind the [[Survey_participants#Send_email_reminder|participants from the survey participants table]] to answer the survey.


You can edit the default format of the reminder email from the ''Email templates panel''. To verify which email placeholders can be used, continue reading the following [[Email templates#Email placeholders|wiki subsection]]. The [[ExpressionScript - Presentation|ExpressionScript]] can help you customize the text body of this email template.


<div class="simplebox">[[File:help.png]] '''Note:''' A reminder will be sent only to those participants in the [[Survey participants|survey participants table]] where the "''Completed''" field is turned off. This means the respondent has either not taken or completed the survey.</div>

==Confirmation== 


If tokens are used and a participant fills out the survey, a confirmation email will be sent to his/her email address. You can deactivate this functionality from the [[Participant settings]] panel.


Click the '''Confirmation''' tab if you want to edit the email template. Check the [[Email templates#Email placeholders|email placeholders]] to see which ones can be used in this type of email. You may also use the [[ExpressionScript - Presentation|ExpressionScript]] to customize your email.

==Registration== 


If '''closed-access mode''' is enabled (there is a [[Survey participants|survey participants table]], which means that only those participants who have an allocated entry and a unique token code associated to it can complete the respective survey. If you allow participants [[Participant settings|to publicly register to your survey]], a new entry in your survey participants table will be created once the respondent has submitted his or her name and email address. A script that runs in the background will automatically send the respective respondent a '''registration email'''. It contains the URL with the token that needs to be accessed by the newly registered user.


Click the '''registration''' tab to edit the format of this email. Don't forget to take a look first at which [[Email templates#Email placeholders|email placeholders]] can be used within the text body. The [[ExpressionScript - Presentation|ExpressionScript]] can provide further customization to the body text you wish to use.

==Basic & Detailed Admin Notifications== 


To get admin notifications, click the [[Notifications & data|Data management]] tab and type in an email address in the "''Send basic admin notification email to''" field and another one (or the same) in the "''Send detailed admin notification email to''" field.


By default, the only difference between the two is related to the extra placeholder {ANSWERTABLE} that is included in the detailed admin notification email template. This allows the user who receives these kinds of emails to also check the submitted answers. They do not have to access the LimeSurvey installation.


However, by using the [[ExpressionScript - Presentation|ExpressionScript]] and the [[Email templates#Email placeholders|email placeholders]] you can customize these two email templates.

=Email Templates Fields= 


Each email template contains:


*'''The subject of the email:''' The title of the email/batch of emails you want to send;


*'''The email body:''' A text box that contains the text message you want to send to the participants. It may contain text, images, and [[Email templates#Email placeholders|email placeholders]]. The [[ExpressionScript - Presentation|ExpressionScript]] can also be used to further customize the message you want to deliver;


<div class="simplebox">[[File:help.png]] '''Note:''' Another tab is displayed above the tab with the email templates tab if your survey uses [[General settings|additional languages]]. If you click any language tab other than the default language tab, the email templates will load the corresponding texts in the respective language. Access each email template in order to start editing them. Do not forget to click the '''Save''' button located in the upper-right part of the screen to save your changes.</div>


*'''Email actions:''' Two actions are available:
**''Reset this template:'' Once clicked, the HTML code is reset. No text is deleted;
**''Validate expressions:'' Checks the logic of the email - whether the placeholders are correctly used or not. We highly recommend using it before sending a batch of emails. This way you can see whether the placeholders are correctly defined or not. In the below example, a small typo exists - it is emphasized in red.


<center>[[File:Validate email - email templates.png]]</center>

=Email Placeholders= 


{{Alert|title=Attention|text=Please note that some email placeholders can be used only within certain email templates! Read below for further details.}}


In the default email templates, different email placeholders are used either in the body and/or the subject of the email. Their role is to connect the email you want to send to each participant in your [[Survey participants|survey participants list]]. The data from the survey participants table (e.g., email, first name, last name, token, etc.) is automatically taken and put into different unique emails before being sent to each participant from your survey participants list.


Below are the email placeholders that can be used within the body message of your invitation and reminder [[Email templates|email templates]]. When sending out the emails, these email placeholders will be replaced in the preview of your invitation/reminder email with data from your survey and [[Survey participants|survey participants table]].


{|class="wikitable"
|{ADMINEMAIL}||Email of the Survey admin
|-
|{ADMINNAME}||Name of Survey Admin
|-
|{SURVEYNAME}||Title of your survey
|-
|{SURVEYDESCRIPTION}||Description of your survey
|}


The following placeholders are allowed in invitation/reminder email templates (subject '''and/or''' body fields) and they will be replaced when sending out the emails:


{|class="wikitable"
|{EMAIL}||Email of the recipient
|-
|{FIRSTNAME}||First Name
|-
|{LASTNAME}||Last Name
|-
|{SURVEYURL}||The URL to start the survey - if you are sending HTML emails, a full URL will be displayed to the survey participant
|-
|@@SURVEYURL@@||The URL to start the survey - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)
|-
|{OPTOUTURL}||The URL to deactivate sending of emails for the respective survey - a full link will be displayed in the HTML version of the email template
|-
|{OPTINURL}||If a user is blacklisted and wants to participate in the respective survey, they have to click the opt-in URL to receive survey invitations/reminders again.
|-
|{GLOBALOPTOUTURL}||The URL for a respondent to opt-out of central participant list for this site - a full link will be displayed in the HTML version of the email template
|-
|{TOKEN}||The token to access the survey
|-
|{USESLEFT}|| The number of uses left for the token
|-
|{VALIDFROM}|| The date the token is valid from
|-
|{VALIDUNTIL}|| The date the token is valid until
|-
|{EMAILSTATUS}|| Used for skipping emails on email sending. Default email status is "OK"
|-
|{LANGUAGE}|| To define the language version do be used for emails and survey URL when using multilingual surveys
|-
|{SENT}|| Invitation send date
|-
|{REMINDERSENT }|| Remindersend date
|-
|{REMINDERCOUNT}|| Number of reminders already sent
|-
|{COMPLETED }|| Survey completion date
|-
|{TID}|| Internal ID at token table
|-
|{ATTRIBUTE_1}||Attribute 1
|-
|{ATTRIBUTE_2}||Attribute 2 (...and so on for more attribute fields)
|}


If your survey is '''not''' anonymous, the email placeholders can be used in order to add specific entry/participant data into the [[text elements|Survey text elements]] panel (e.g., survey description, welcome message, end message).


{|class="wikitable"
|{TOKEN:EMAIL}||Displays the email of the participant from the survey participants table
|-
|{TOKEN:FIRSTNAME}||Displays the first name of the participant from the survey participants table
|-
|{TOKEN:LASTNAME}||Displays the last name of the participant from the survey participants table
|-
|{TOKEN}||Displays the token code of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_1}||Displays "Attribute 1" of the participant from the survey participants table
|-
|{TOKEN:ATTRIBUTE_2}||Displays "Attribute 2" of the participant from the survey participants table (and so on for more attribute fields)
|}


{{Note|To find out more about attributes, read the following [[Survey_participants#Manage_attributes|wiki section]].}}


These email placeholders can also be used in the confirmation and admin notification email templates.


Certain placeholders can be used only within the the admin notification templates. Please note that one email per response will be sent to the email address of the administrator!


Some of the placeholders that can be used only in the admin notification panels are mentioned below:


{|class="wikitable"
|{VIEWRESPONSEURL}||Displays an URL that redirects you to the respondent's submitted answer
|-
|{EDITRESPONSEURL}||Displays an URL that redirects you to a LimeSurvey page from where you can edit the responses submitted by the respective survey participant
|-
|{STATISTICSURL}||Click this URL to access the statistics of the survey
|-
|{ANSWERTABLE}||If you want to display the submitted answers of the participant in the admin notification email, use this email placeholder. This way, you no longer need to access your LimeSurvey installation in order to check the submitted answers of the respective respondent (as the {VIEWRESPONSEURL} placeholder does).
|}


<div class="simplebox">[[File:help.png]] '''Hints:'''
* If your survey is using anonymized responses, then token-related placeholders will not work in the notification email template.
* You can use [[ExpressionScript - Presentation|ExpressionScript]] to use expressions for tailoring an email{{NewIn|1.92}}. Please have a look at the [[ExpressionScript How-tos|ExpressionScript how-tos]] for an example.
* Also have a look at the examples on using [[Questions - introduction#Information from survey participants table|Information from survey participants table]].</div>


{{Box|Before sending the emails, we highly recommend the [[Email templates#Email templates fields|validation of your email templates]] - click on the validate expressions button located under the email text body.}}

==Participant Opt-out== 


When you use the '''{OPTOUTURL}''' tag in your invitation/reminder email, your participants can opt out of this particular survey by clicking the related URL in the email - so you don't send them reminder emails. A participant that opts out of your survey will have the email status 'OptOut' set in the [[Survey participants|survey participants list]].

==Barebone URL== 


URL placeholders have their corresponding Barebone URL. E.g., @@SURVEYURL@@: you can use @@OPTOUTURL@@, @@OPTINURL@@ …

=Using Replacement Function= 


Some specific keywords can be used within your email templates. For example, certain keywords can be used to replaces the token URL address.


The below example uses a plain link to the survey instead of a long url:


1) First, access the email templates panel and choose ''Invitation''.


2) Write the text you want to appear as a link to start the survey.


3) Then select that text.


[[File:mark_text_to_hyperlink.jpg]]


4) Add the placeholder for the plain link @@SURVEYURL@@ and choose other from the protocol-select-box.


[[File:add_link_placeholder_choose_other.jpg]]


Now, when you send out your invitation emails, the link to start the survey will be shorter.

= Email Attachments = 

== File Actions == 


When clicking '''Add file''' the following window will be displayed asking you to choose the document from the files folder that you want to send via email:


[[File:Upload_files_-_email_templates.png]]


Attachments can be added at the bottom of the email template editing interface. Please note that email attachments are uploaded on a per survey basis.


You can also upload, on the spot, a file from the desktop to your LimeSurvey installation by clicking the '''upload''' button and then selecting the file you want to attach to the respective email template.


Once selected, double click it and the file will be immediately displayed in the '''Files''' table, below the '''Add File''' button:


[[File:Files_table_-_email_templates.png]]


To have it permanently attached to the respective email template, do not forget to click the '''Save''' button located in the upper-right part of the window.


To determine if an attachment should be sent on an individual basis, it is possible to add a relevance equation to each attachment.


All functions supported by the [[ExpressionScript - Presentation|ExpressionScript]] can be used, as well as token attributes if the survey uses tokens.


With notification or confirmation templates, it is also possible to use [[ExpressionScript - Presentation#Access_to_Variables|question codes]] used in the survey.


If you want to delete a file, click the red trash button located under the Action column and save the changes.


{{Alert|title=Attention|text=* When a file can not be found on the file system, the email will be sent without an attachment.
*Exporting/importing a survey does not export/import the attached uploaded files. However, the settings for attachments will be maintained, as well as the relevance equations.}}

== Image Attachment == 


You can attach an image/images if you send HTML emails. To do this, you need to update the URL source of the image by settings its path to your public directory of your LimeSurvey instance.


<center>[[File:Image-email-embed.png]]</center>


{{Alert|The source must be relative to your public directory on the server. If you LimeSurvey instance is installed in a subdirectory, the image will not be shown in your HTML editor.}}
</translate>

TwoFactorAdminLogin

2022-05-25T18:50:06Z

Mazi: Fixed limestore and download link

<languages />
<translate>

__TOC__

=Introduction=

'''2-Factor-Authentication''' (2FA) is a way to add additional security to your account. It is called "two-factor-authentication" because two verification methods are used to access your account. The first "factor" is your usual password that is standard for any account. The second "factor" is a verification code retrieved from a 2FA application either from your computer or mobile device. For more details about 2FA and its importance, please visit the following [https://en.wikipedia.org/wiki/Multi-factor_authentication article].

If enabled, a 6 digits code (default value) has to be introduced when you log in to your LimeSurvey instance:

<center>[[File:2FA_login.png]]</center>

To learn more about this functionality, please continue reading below.

=How to install the 2FA plugin=

==LimeSurvey Cloud==

If you are using LimeSurvey Cloud (hosting provided by [https://limesurvey.org LimeSurvey GmbH]), just visit the [[Plugin manager|Plugin Manager]] page and enable it from there (see below for more details).

==LimeSurvey CE==

At the moment, the plugin is not a core component of LimeSurvey CE (Community Edition). To download it, access [https://account.limesurvey.org/limestore LimeStore] and [https://account.limesurvey.org/limestore/extensiondetails/49/plugin/two-factor-administration-login download the plugin from here].

{{Note|To be able to download it, you need a [https://www.limesurvey.org/editions-and-prices/limesurvey-ce/editions-and-prices-community Premium account].}}

Once downloaded, unzip it, and move the folder into the plugins-related folder inside your LimeSurvey instance.

{{Note|To understand the difference between LimeSurvey Cloud and LimeSurvey CE, please visit this [[LimeSurvey_PRO_vs_LimeSurvey_CE|wiki section]].}}

{{Note|For LimeSurvey 3.x, the folder name inside plugins has to be ''TwoFactorAdminLogin''.}}

=Activate the 2FA plugin=

To activate your 2FA plugin, access your LimeSurvey instance, and activate it from your [[Plugin manager|Plugin Manager]]:

<center>[[File:2fa_activate.png]]</center>

To check the default settings, please click on "Configure".

==Plugin settings==

The configuration page contains the following settings:

<center>[[File:2FA plugin configuration.png]]</center>

*'''Issuer:''' The text typed in this box will be displayed in the app as issuer name.
*'''Digits:''' The number of digits the resulting codes will be. Please leave it at 6 for Google Authenticator.
*'''TimePeriod:''' The number of seconds a code will be valid. If you use Google Authenticator, please leave it to 30.
*'''Discrepancy:''' The amount of discrepancy is allowed for the client after the TimePeriod expires (seconds)

*'''Algorithm:''' The algorithm used to generate a hash:
**''SHA1 (Default)''
**''SHA256''
**''MD5''

*'''Force 2FA:''' If you enable it, all instance users have to create a 2FA token after they log in again into the LimeSurvey instance.

Don't forget to click on "Save" after updating your 2FA configuration.

=2-Factor-Settings=

Once you activated the plugin, a new menu item will be displayed on the top bar:

<center>[[File:2fa_location.png]]</center>

The dropdown menu includes the following two options:

*[[TwoFactorAdminLogin#2FA-Setting|2FA-Setting]]: Users can enable and manage their 2FA settings.
*[[TwoFactorAdminLogin#2FA-Administration|2FA-Administration]]: With the right permission, you can visualize whether the other instance users use 2FA or not.

==2FA-Setting==

If you haven't created any 2FA-token yet, the following page will be displayed:

<center>[[File:2fa_register.png]]</center>

If you decide to create a 2FA-token, click on "Register 2FA now". You will be prompted by the following message box:

<center>[[File:2fa_user_settings.png]]</center>

To enable 2FA:
#Select the 2FA authentication method. By default, five different 2FA types are provided: Google Authenticator (default), Authy, YubiKey, Authenticator Plus, Duo, and HDE OTP.
#Scan the QR-code with your mobile phone. For a list of application recommendations, check this [https://en.wikipedia.org/wiki/Help:Two-factor_authentication#Enabling_2FA_on_smartphones_and_tablet_computers article].
#Enter the confirmation key displayed in your 2FA application.

{{Note|From a technical perspective, you can use any 2FA application that supports TOTP (Time-based One-Time Password algorithm). For more information on what TOTP is, please check this [https://en.wikipedia.org/wiki/Time-based_One-time_Password_algorithm article].}}

To confirm the creation of your 2FA-token, click on "Create 2FA binding".

<hr width="50%" style="margin:auto">

Once done, the following two options will be displayed in your personal 2FA settings:

<center>[[File:2fa_unset.png]]</center>

* '''Unset 2FA:''' Confirm your action to delete the 2FA-token associated to your account.

{{Note|Please note that you will need to re-authenticate again if "Force 2FA" is enabled from the plugin settings.}}

* '''Reset 2FA:''' If this option is selected, you will be asked to scan the new QR-code and introduce the new confirmation Key.

==2FA-Administration==

With the necessary permissions, you can have access to the 2FA user management panel from where you can check how many users activated 2FA.

<center>[[File:2fa_user_management.png]]</center>

*'''Action:''' A red trash button is displayed in this column next to the users that have enabled 2FA. If someone asks to get the 2FA-token reset because he/she cannot log in anymore into your instance, you can delete the 2FA-token associated with his/her account from here.
*'''Username:''' All the instance users are listed under this column.
*'''Full name:'''The full name typed in here by your users is displayed in this field.
*'''Email:''' The email address corresponding to your users.
*'''2FA-Method:''' The 2FA-method chosen by each user.
*'''2FA enabled:''' If "1", it means that 2FA is enabled for the respective user.

=FAQs=

==I am a super administrator and locked myself out. How can I delete my 2FA-token?==

You will need access to your database and truncate the 2FA-related column.

==How can I enforce 2FA to all my users?==

Enable "Force 2FA" from the plugin configuration menu.

==From where can I download the plugin?==

Please access [https://www.limesurvey.org/limestore LimeStore] and [https://www.limesurvey.org/limestore?view=extensiondetails&id=49 download the plugin from download it from here]. To be able to download it, you need to hold a Premium package

==I use LimeSurvey Cloud. Do I have to purchase the plugin?==

No. The plugin is already part of the core LimeSurvey plugins - you can enable it by accessing the plugin menu.

</translate>

Authentication plugins

2020-10-26T15:14:18Z

Mazi:

This is an overview of the authentication plugins currently shipped with LimeSurvey. If you want to extend or develop your own authentication plugin, please see [[Authentication_plugin development]]

== Internal database ==
This plugin is the default and can not be disabled. It uses the built in LimeSurvey database. It is a fall-back mechanism so that you can always login to the installation when needed.

== LDAP ==
By activating this plugin you can perform basic authentication against an LDAP server. Make sure your PHP configuration has LDAP support enabled.

'''Enabling and configuring settings for plugin AuthLDAP v2.05+'''

Enable LDAP in PHP.INI.
Verify that [http://php.net/manual/en/function.phpinfo.php phpinfo.php] shows that LDAP is enabled.
The location of LimeSurvey's built-in phpinfo.php is: Upper Right Menu -- Configuration -- Settings -- Global Settings. Then, below the table, you will have a link for "Show PHPInfo".

Go to LimeSurvey Plugin Manager.

Configure LDAP plugin.

=== Simple Example settings ===
* Ldap server e.g. ldap://ldap.mydomain.com: ldap://ldap.mydomain.com

* Port number (default when omitted is 389):

* LDAP version (LDAPv2 = 2), e.g. 3: 3

* Username prefix cn= or uid=: cn=

* Username suffix e.g. @mydomain.com or remaining part of ldap query: ,OU=people,DC=mydomain,DC=com

* Create a LimeSurvey administrator with the same name as a AD(active directory) user account.

* Log in using the AD credentials(username and password).

=== Example settings AD2008 & 2.05+ ===

'''Settings working with Active Directory 2008 and 2.05+ (build 140520) with AuthLDAP plugin '''.

==== Authentication with LDAP and ''userPrincipalName'' attribute ====

'''Note''': Authentication with ''userPrincipalName'' attribute (ie: firstname.lastname@example.intra). Create a LimeSurvey user with the same name as a AD(active directory) user account :

''Username'': '''firstname.lastname@example.intra'''

''Email'': '''firstname.lastname@example.intra'''

''Full name'': '''Firstname LASTNAME'''

Then configure the plugin : ''Plugin Manager > LDAP > Configure''.

''Ldap server e.g. ldap://ldap.example.intra'': '''ldap://ldap.example.intra'''

''Port number (default when omitted is 389)'': '''389'''

''LDAP version (LDAPv2 = 2), e.g. 3'': '''LDAPv3'''

''Username prefix cn= or uid=: cn='': '''empty'''

''Username suffix e.g. @example.intra or remaining part of ldap query'': '''empty'''

Log in using the AD credentials (username: '''firstname.lastname@example.intra''' and password).

==== Authentication with LDAP and ''sAMaccountName'' attribute ====

'''Note''': Authentication with ''sAMaccountName'' attribute (ie: firstname.lastname). Create a LimeSurvey user with the same name as a AD(active directory) user account :

''Username'': '''firstname.lastname'''

''Email'': '''firstname.lastname@example.intra'''

''Full name'': '''Firstname LASTNAME'''

Then configure the plugin : ''Plugin Manager > LDAP > Configure''.

''Ldap server e.g. ldap://ldap.example.com'': '''ldap://ldap.example.intra'''

''Port number (default when omitted is 389)'': '''389'''

''LDAP version (LDAPv2 = 2), e.g. 3'': '''LDAPv3'''

''Username prefix cn= or uid=: cn='': '''empty'''

''Username suffix e.g. @example.com or remaining part of ldap query'': '''@example.intra'''

Log in using the AD credentials (username: '''firstname.lastname''' and password).

==== Authentication with LDAPS and ''sAMaccountName'' attribute ====

'''Note''': Authentication with ''sAMaccountName'' attribute (ie: firstname.lastname). Create a LimeSurvey user with the same name as a AD(active directory) user account :

''Username'': '''firstname.lastname'''

''Email'': '''firstname.lastname@example.intra'''

''Full name'': '''Firstname LASTNAME'''

Then configure the plugin : ''Plugin Manager > LDAP > Configure''.

''Ldap server e.g. ldap://ldap.example.com'': '''ldaps://ldap.example.intra'''

''Port number (default when omitted is 389)'': '''636'''

''LDAP version (LDAPv2 = 2), e.g. 3'': '''LDAPv3'''

''Username prefix cn= or uid=: cn='': '''empty'''

''Username suffix e.g. @example.intra or remaining part of ldap query'': '''@example.intra'''

Log in using the AD credentials (username: '''firstname.lastname''' and password).

=== Example settings OpenLDAP & 2.05+ ===

'''Settings working with OpenLDAP and 2.05+ (git version Feb. 2015) with AuthLDAP plugin '''.

==== Authentication with LDAP and ''uid'' attribute ====

'''Note''': Authentication with ''uid'' attribute. Create a LimeSurvey user with the same name as a the LDAP user account.

Then configure the plugin : ''Plugin Manager > LDAP > Configure''.

* ''Ldap server e.g. ldap://ldap.mydomain.com'': '''ldap://ldap.mydomain.com'''
* ''Port number (default when omitted is 389)'': '''(389 or leave blank)'''
* ''LDAP version (LDAPv2 = 2), e.g. 3'': '''LDAPv3'''
* ''Select true if referrals must be followed (use false for ActiveDirectory)'': '''(leave blank)'''
* ''Check to enable Start-TLS encryption When using LDAPv3'': '''False'''
* ''Select how to perform authentication'': '''Search and bind'''
* ''Attribute to compare to the given login can be uid, cn, mail, ...'': '''uid'''
* ''Base DN for the user search operation'': '''ou=people,dc=mydomain,dc=com'''
* ''Optional extra LDAP filter to be ANDed to the basic (searchuserattribute=username) filter. Don't forget the outmost enclosing parentheses'': '''(leave blank)'''
* ''Optional DN of the LDAP account used to search for the end-user's DN. An anonymous bind is performed if empty.'': '''cn=admin,dc=mydomain,dc=com'''
* ''Password of the LDAP account used to search for the end-user's DN if previoulsy set.'': '''password''' (appears!)
* ''Check to make default authentication method'': '''(as you wish)'''

Log in using the LDAP credentials (username: '''user''' and password).

==== Authentication with OpenLDAP, ''uid'' attribute, and group restriction [2.62+] ====

Some applications require a separate LDAP query (beyond the user search and bind to check password) to determine if the user has sufficient authorization. For example, let's assume that LDAP has a <code>Groups</code> OU that includes an entry identified by <code>cn=limeusers</code> and our policy is that for a user to be authorized to use LimeSurvey that entry must include an attribute of the form <code>memberUid=<i>username</i></code> where ''username'' is the username (uid) entered by the user attempting to login. To configure LDAP for that, set up basic ''uid'' authentication as above and then set the following additional (optional) parameters:

* ''Optional base DN for group restriction'': <code>ou=Groups,dc=mydomain,dc=com</code>
* ''Optional filter for group restriction'': <code>(&(cn=limeusers)(memberUid=$username))</code>

Note:
# <code>$username</code> is a magic value (in the context of the filter parameter) that is replaced by the username entered by the user when logging in.
# Although intended for testing group membership as above, this optional "group restriction" capability can be used to add any authorization check that can be expressed as a separate filtered search like this.
# Before specifying a group restriction this way, verify that basic LDAP authentication is working correctly.
# If either of the group restriction parameters is empty then the group restriction step will not be applied.

== Webserver authentication ==

This plugin leaves authentication to the webserver and reads the result from a configurable server setting. This method has been around for a while, and was configured from config.php. If you used this authentication, you should enable the plugin in the plugins menu and move your configuration from config.php to the plugin's settings. Feel free to contact the team via the bugtracker or irc-channel if it no longer functions the way it did before.

[[Category:Plugins]]

Question types/de

2020-09-11T07:05:54Z

Mazi: Fixed broken link

<languages />
__TOC__

=Einführung=

Diese Seite bietet Ihnen einen Überblick über alle verfügbaren Fragetypen.

<div class="simplebox"> [[File: help.png]] Das LimeSurvey-Downloadpaket enthält eine Beispielumfrage, die alle Fragetypen enthält. Sie finden es in Ihrem Verzeichnis ''/docs/demosurveys/''. Sie können diese Umfrage importieren, um sich einen Überblick zu verschaffen. </div>

Bitte beachten Sie, dass Sie [[Question groups - introduction/de|Fragengruppen]] erstellen müssen, bevor sie Fragen erstellen können.

=Fragetypen (Allgemeines)=

Wenn Sie einen Frage anlegen/bearbeiten, können Sie über die Registerkarte '''Allgemeine Optionen''' den Fragentyp festlegen:

<center>[[File:Fragetyp ändern.png]]</center>

Wählen dann Sie im Menü ''Fragetyp wählen'' den gewünschten Fragetyp aus:

<center>[[File:Fragetyp auswählen.png]]</center>

{{Note|Grundlegende Informationen zu Fragen finden Sie [[Questions - introduction|hier]].}}

<hr width="50%" style="margin:auto">

Die folgenden Kategorien von Fragetypen können in einer Umfrage verwendet werden:

*[[Question types/de#Einfachauswahl|Einfachauswahl]]
*[[Question types/de#Textfragen|Textfragen]]
*[[Question types/de#Maskenfragen|Maskenfragen]]
*[[Question types/de#Matrixfragen|Matrixfragen]]
*[[Question types/de#Mehrfachauswahl|Mehrfachauswahl]]

==Teilfragen==

Üblicherweise hat eine Frage nur Antwortoptionen. Es gibt aber bestimmte Fragetypen (wie die Matrix) die eigentlich eine Zusammenfassung mehrerer Teilfragen sind, wobei jede Teilfrage vom Teilnehmer der Umfrage einzeln beantwortet werden kann (beispielsweise unter Nutzung einer vordefinierten Skala von Antwortoptionen).

[[File:F_AFL.png]]

Ein etwas komplexeres Beispiel ist der Fragetyp 'Matrix (Texte)', in dem der Teilnehmer die Möglichkeit zur Texteingabe für bestimmte Kombinationen hat. In diesem Fall ist diese Eingabe die 'Antwort' und die Zeilen- bzw. Spaltenbezeichnungen stellen die Teilfragen dar.

[[File:SC_MFT.png]]

=Matrixfragen=

Im Prinzip ist der Fragentyp Matrix eine andere Darstellung des von Listenfragen. Die Matrix ermöglicht die Darstellung von Teilfragen in Spalten, wobei für jede Zeile dieselben Antwortoptionen angeboten werden. Der Text kann eine spezifische Frage sein oder auch nur eine Beschreibung.

Bei der Ausgabe gibt es keinen Unterschied zum Fragentyp Liste (Einfachauswahl).

Die flexibelsten Matrix-Fragetypen sind ''Matrix'', ''Matrix (Texte)'' und '' Matrix (Zahlen)''. LimeSurvey unterstützt jedoch auch einige Matrix-Fragetypen mit vordefinierten Antwortoptionen (z. B. ''Matrix (5 Punkte Auswahl)'', ''Matrix (Zunahme/Gleich/Abnahme)'').

<div class='simplebox'> [[File: help.png]] Um die Grundlagen von Array-Fragen schnell zu verstehen, überprüfen Sie das folgende (englische) [https://www.youtube.com/watch?v=7134QebOQzY Video-Tutorial]. </div>

==Matrix==

{{:Question type - Array/de|transcludesection=short_description}}

'''Example 1:''' [[Media:Question tpye - Array using flexible labels.zip|Question type - Array using flexible labels.zip]]

'''Example 2:''' [[Media:Question type - Array - Semantic Differential Question Type.zip|Question type - Array - Semantic Differential Question Type.zip]]

Mehr Informationen finden Sie [[Question type - Array/de|hier]].

==Matrix (5 Punkte Auswahl)==

{{:Question type - Array (5 point choice)/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Array (5 point choice)/de|hier]].

==Matrix (10 Punkte Auswahl)==

{{:Question type - Array (10 point choice)/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Array (10 point choice)/de|hier]].

==Matrix (Ja/Nein/Unsicher)==

{{:Question type - Array (Yes-No-Uncertain)/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Array (Yes-No-Uncertain)/de|hier]].

==Matrix (Zunahme/Gleich/Abnahme)==

{{:Question type - Array (Increase-Same-Decrease)/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Array (Increase-Same-Decrease)/de|hier]].

==Matrix nach Spalte==

{{:Question type - Array by column/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Array by column/de|hier]].

==Dual Matrix==

{{:Question type - Array dual scale/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Array dual scale/de|hier]].

== Matrix (Zahlen) ==

{{:Question type - Array (Numbers)/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Array (Numbers)/de|hier]].

== Matrix (Texte) ==

{{:Question type - Array (Texts)/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Array (Texts)/de|hier]].

=Maskenfragen=

Unter der Kategorie Masenkenfragen werden jene Fragen verstanden, bei denen die Antworten vordefiniert sind.

==Datum/Zeit==

{{:Question type - Date/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Date/de|hier]].

==Datei-Upload==

{{:Question type - File upload/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - File upload/de|hier]].

==Geschlecht==

{{:Question type - Gender/de|transcludesection=short_description}}

-

Mehr Informationen finden Sie [[Question type - Gender/de|hier]].

==Sprachwechsel==

{{:Question type - Language switch/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Language switch/de|hier]].

==Zahleneingabe==

{{:Question type - Numerical input/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Numerical input/de|hier]].

==Mehrfache numerische Eingabe==

{{:Question type - Multiple numerical input/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Multiple numerical input/de|hier]].

==Reihenfolge==

{{:Question type - Ranking/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Ranking/de|hier]].

== Textanzeige ==

{{:Question type - Text display/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Text display/de|hier]].

== Ja/Nein ==

{{:Question type - Yes-No/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Yes-No/de|hier]].

==Gleichung==

{{:Question type - Equation/de|transcludesection=short_description}}

Mehr Informationen finden Sie [[Question type - Equation/de|hier]].

=Mehrfachauswahl=

Es gibt Fragen, bei denen die Teilnehmer mehrere Antwortmöglichkeiten aus einer Auswahl auswählen sollen. Dies können Sie über den Fragetyp ''Mehrfachauswahl'' erreichen.

== Mehrfachauswahl ==

{{:Question type - Multiple choice|transcludesection=short_description}}

Find out [[Question type - Multiple choice|more about the Multiple Choice Question type...]]

== Mehrfachauswahl mit Kommentar ==

{{:Question type - Multiple choice with comments|transcludesection=short_description}}

Find out [[Question type - Multiple choice with comments|more about the Multiple Choice With Comments question type...]]

=Einfachauswahl=

Single choice questions are those where the participant can only pick a single predefined answer option.

===5 point choice===

{{:Question type - 5 point choice|transcludesection=short_description}}

Find out [[Question type - 5 point choice|more about the 5 Point Choice question type...]]

===List (Dropdown)===

{{:Question type - List (Dropdown)|transcludesection=short_description}}

Find out [[Question type - List (Dropdown)|more about the List Dropdown question type...]]

===List (Radio)===

{{:Question type - List (Radio)|transcludesection=short_description}}

Find out [[Question type - List (Radio)|more about the List Radio question type...]]

===List with comment===

{{:Question type - List with comment|transcludesection=short_description}}

Find out [[Question type - List with comment |more about the List with comment question type...]]

=Textfragen=

LimeSurvey provides a number of possible variations of the standard text field. All of these can be defined further using the attributes of the question which permit to restrict the number of characters as well as the size of the field.

Furthermore text input can be validated by [[Using regular expressions|using regular expressions]].

===Short free text===

{{:Question type - Short free text|transcludesection=short_description}}

Find out [[Question type - Short free text|more about the Short Free Text question type...]]

===Long free text===

{{:Question type - Long free text|transcludesection=short_description}}

Find out [[Question type - Long free text|more about the Long Free Text question type...]]

===Huge free text===

{{:Question type - Huge free text|transcludesection=short_description}}

Find out [[Question type - Huge free text|more about the Huge Free Text question type...]]

===Multiple short text===

{{:Question type - Multiple short text|transcludesection=short_description}}
Find out [[Question type - Multiple short text|more about the Multiple Short Text question type...]]

=Fragen-Design=

<div class="mw-translate-fuzzy">
Es ist möglich, in der Regel das Frage Layout/Design durch die Verwendung von CSS zu bearbeiten. Mehr Informationen finden Sie unter [[The template editor/de|Fragenlayout mit CSS]].
</div>

Translations:Question types/79/de

2020-09-11T07:05:53Z

Mazi: Fixed broken link

Mehr Informationen finden Sie [[Question type - Equation/de|hier]].

Theme editor

2020-09-07T06:17:34Z

Mazi: Added CSS details for eqaution question type

<languages /> <translate>

=Introduction= 


LimeSurvey has an advanced theme and style system providing to developers an efficient way to customize the survey appearance. Since LS3, we're not speaking anymore about '''"templates"''' like in previous versions, but about '''"themes"'''. The '''themes''' allow control over the look and feel of pages during a survey. A survey administrator can select a default theme that will be used for each survey to further personalize it and improve its look and feel. '''Themes''' come with options that provide to admin without coding skill a simple way to add a logo on the welcome page, to change the background colors, to select a font, etc.


LimeSurvey comes with 3 themes right out of the box. These initial themes are defined by directories located in the LimeSurvey installation "themes/survey/" directory. Each theme has its own directory. Within the main directory of a theme you'll find a configuration file in XML, and numerous directories containing the views '''themes (.twig)''', '''cascading style sheets (.css)''', '''scripts''', '''images''' ('''.jpg''' or '''.png'''), and maybe others.


Since LimeSurvey 2.50, the theme engine use [http://getbootstrap.com/docs/3.3/ Bootstrap 3] as CSS framework. Bootstrap 3 being a standard framework, developers will find a lot of documentation, tutorials and forum threads about it on Internet.


Since LimeSurvey 3, the theme engine use [https://twig.symfony.com Twig], so the theme developers can change the logic of the survey rendering in a safe and easy way. Twig replace the old system of replacement keywords that was used in the previous versions. The logic that was used to generate the HTML of the keywords are now available inside the theme's views.


Snippet from Vanilla Theme:


<syntaxhighlight lang="twig" enclose="div">
<div class="{{ aSurveyInfo.class.answercontainer }} col-xs-12" {{ aSurveyInfo.attr.answercontainer }}>
{# NOTE: If you want to customize the question rendering, use a question theme #}
{{ aQuestion.answer | raw }}
</div>
</syntaxhighlight>


Themes, being HTML and Twig code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most of them reference a common cascading style sheets (CSS) file that defines the font style, color, size, background, and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Theme file. Finally, special keywords in curly braces are replaced with text defined in the survey for each language translation correspondent (for example, the 'Survey Title' or 'Question Text' for each language defined).


If you create a new custom theme, please consider contributing it back to the LimeSurvey community and make it available to others. With your help, we can grow our repository of themes, surveys, and other add-ons to make LimeSurvey even better!
See our [https://www.limesurvey.org/index.php?option=com_sobipro&sid=55:Templates&Itemid=729 LimeSurvey template repository] where you can share your templates.

=Creating a new theme= 


To be able to create a new theme (or edit an existing theme), you need [[Manage users#Set global permissions for a user|Template Editing user permission]] in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.


<div class="simplebox"><span style='color:red'>'''Note of Warning:'''</span> If you change themes, you could also affect all the pre-existing surveys from your LimeSurvey installation. Themes are an advanced feature that require experience and HTML knowledge in order to make them running smoothly.</div>


The preferred way to create a new theme is through the '''Theme Editor''' (see below), which is located in the '''Configuration''' dialog. Some people may like to work directly with theme files so that they can use their favorite text editor instead of the web interface. In this case, still use the Theme Editor to first create your new theme. This will create a new base theme with all the files you need in the ''LimeSurvey_web_root/upload/themes/survey/your_new_template'' directory. From there you can use your text editor to manually adjust the template files.


<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these theme files will be owned by the group and user where the web server is running (may be "www" for some systems). So, make sure you have enough access to edit these files, When you save them, make sure they don't change ownership! In this way, you can still use the web Theme Editing interface if needed.</div><br />


A number of 'public' elements of LimeSurvey can be adjusted by a series of themes. The next section provides a very brief explanation of these templates.


{{Note|Themes files may seem complex. Besides HTML, you might also need to understand CSS, Twig, and JavaScript.}}

=The LimeSurvey Theme editor= 


To ease the understanding and quick update of a Theme, LimeSurvey provides a '''Theme Editor''' in the main '''administrative''' toolbar of the application. This Theme Editor is only available to users [[Manage users#Set global permissions for a user|with the Templates permission]] and to superadministrators.


{{Alert|title=Attention|text=A theme that is not correctly constructed can make a survey (that uses the respective template) inoperable. }}


The LimeSurvey theme editor allows you to edit the contents of your themes online. To start the Theme Editor: click on '''Themes''' link in the '''Configuration''' menu, and then click on the "Theme editor" button next of the theme you want to edit or extend.


[[File:Themes menu.png]]
[[File:Theme editor button.png|''The button to access the theme editor for Bootswatch theme'']]


The template editor page allows you to select the template you would like to edit/view.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]


The following options are available:


*'''Create''': Allows you to create a new template. In order not to start from scratch, the template 'default' is copied.
*'''Import''': Allows you to import a template from a ZIP file.
*'''Export''': Allows you to export the current template to a ZIP file.
*'''Copy''': Allows you to make a new template by copying the current one.
*'''Rename''': Allows you to change the name of the template. It is generally used after copying or importing a template.
*'''Template''': It is a drop-down list that shows all the available templates that are located in your LimeSurvey installation.


*'''Screen''': It is a drop-down list which allows you to choose which particular survey page of that template you want to look at.
*'''Return to admin panel'''.

==Import/export/copy a template== 


When you '''export '''a template, a ZIP-file archive with all the files your template consists of will be created (.pstpl files, images, css files, ...). You can simply '''import''' the exported zip-file into another LimeSurvey installation by using the import feature or you can manually copy the archive into another LimeSurvey installation and extract it into the corresponding [[Theme editor#Template files location|template directory there]].


However, it is preferred to use the LimeSurvey template import/export/copy functions in the template editor.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag. Even though many browsers do not require strict adherence to the W3 HTML standards, the LimeSurvey script needs to find a <body> tag to run certain javascript elements. It is not expected to see many 'keywords' used in the startpage.pstpl file. However, you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file. For example, you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.
*'''survey.pstpl:''' This template is the second used on most pages and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (i.e.: don't leave a table open here because there is nowhere else to close it).
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. Please note that in the survey settings (access the ''Presentation & navigation settings'' by clicking on the '''Presentation''' tab) you can set if the group description should be shown or not. If not, then this file is not included at all.
*'''question.pstpl:''' This file contains the question, answer, and help text sections of your survey. In the "group by group" and "all in one" surveys, this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LimeSurvey 1.87)'''. All keywords from this template are now available directly in question.pstpl.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper necessary for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl and endgroup.pstpl, but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl, but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl, but for the print version of the survey.

== CSS and Javascript== 


Two files that are always used in a template are template.css (for CSS) and template.js (for Javascript).
*'''{TEMPLATECSS}:''' Add lines for default css, template.css, and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js, and all js files needed for LimeSurvey.

=== Using Bootstrap=== 
LimeSurvey has Bootstrap 3 embedded, so you can style all your templates with the well documented Bootstrap classes.
For more information please refer to the [https://getbootstrap.com Bootstrap documentation].


The [https://github.com/flatlogic/awesome-bootstrap-checkbox Awesome-Bootstrap-Checkbox] plugin is also included. With it, you can use the typical Bootstrap color-classes (info,warning,danger,etc.) also with the suffix "-checkbox" or "-radio", though styling checkboxes and radios as you prefer.

=== Replacing default CSS or Javascript=== 


Some questions use specific files for Javascript or CSS. If you need to replace a function, use a cascading system. For javascript function, the last function read is the function used.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''', and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the settings of the survey. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages/'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In version 1.90+, this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight>


<span style='color:red'>'''*'''</span>NOTE: In version 1.91 and earlier, LimeSurvey js files are not included in the template. In version 2, '''you have to use {TEMPLATEJS} in one of your template file''' to add the link to the js file. You can add it in startpage.pstpl or in endpage.pstpl. You can remove the {TEMPLATEURL}/template.js line and you have to replace with {TEMPLATEJS} to update a personal template.

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. You can see the ''Screen part'', JavaScript, and CSS files. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.


<center>[[File:File Control Section.png|center]]</center>


The "Other files" window shows a list of all other files from the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''.


Instead of using a link for each picture, utilize the field string {TEMPLATEURL}. So, instead of:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/files/mypicture.jpg'</syntaxhighlight>
You can use {{NewIn|2.50}}:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}files/mypicture.jpg'</syntaxhighlight>


In LimeSurvey versions before 2.50 use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


A "sample" of the template page you are editing will be visible in the bottom of the screen. There is no way to delete a template from the template editor. This must be done by accessing the underlying directory and deleting manually the files from there. You also have the possibility to select different screen resolutions in order to better evaluate the feel and look of the template.


<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the template editor. If you want to modify them, create a copy first and edit the copy.</div>

==Template files location== 


LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the ''/templates'' directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the ''/upload/templates'' directory.


There should '''ALWAYS''' be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. It comes installed by default.


You can use any image files that you upload into the template management area with the help of this syntax:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type has now a unique class. The mandatory questions have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory, but the user didn't answer it or if there is validation on a question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied, but the user hasn't answered correctly:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two classes, while others may use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question {{ObsoleteIn|3.0}}
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .ls-answers {{NewIn|3.0}}
| All question block
| All question type
|<div class="ls-answers ">, <ul class="ls-answers ">, <table class="ls-answers">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answers are questions too. Then we have a lot of class="question-item answer-item"
|-
! scope="row" | .button-list
| A list of button
| Yes no and Gender question
| <ul class="button-list">
|
|-
! scope="row" | .button-item
| The answer part with a button
| Yes no and Gender question
| <li class="button-item">
|
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question types use multi-list class, like checkbox with comment: class="checkbox-list text-list"
|-
! scope="row" | .checkbox-array {{NewIn|3.0}}
| A array of checkbox
| Array (numbers) with checkbox option
| <table class="checkbox-list">
|
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type (each row)
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-array {{NewIn|3.0}}
| A array of radio item
| Array question type
| <table class="radio-array">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-list
| A list of text input with numeric only answer (each row)
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-array {{NewIn|3.0}}
| The answer part of a numeric input
| Array of number
| <table class="number-array">
|
|-
! scope="row" | .select-list {{ObsoleteIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .dropdown-list {{NewIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select) (each row)
| <table class="dropdown-list">
|
|-
! scope="row" | .dropdown-array {{NewIn|3.0}}
| A array of dropdown
| Array numbers, Dual scale array (select)
| <table class="dropdown-array">
|
|-
! scope="row" | .select-item {{ObsoleteIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .dropdown-item {{NewIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="dropdown-item">, <td class="dropdown-item">
|
|-
! scope="row" | .hide {{ObsoleteIn|3.0}}
| Used for accessibility: hidden with css but read by screenreader, since 2.50 : you can use sr-only from bootstrap
| Short text question
| <label class="hide">
| Can be used for other purposes
|-
! scope="row" | .ls-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is activated
| Button for example
| <div class="ls-js-hidden">
| LimeSurvey core used it, but you can use it too in your template
|-
! scope="row" | .ls-js-hidden-sr {{NewIn|3.0}}
| Used for accessibility: hide it if js is activated, but always show if user use a screenreader
| Button for example
| <a class="ls-js-hidden-sr">
| Button
|-
! scope="row" | .ls-no-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is not activated
| Link
| <a class="ls-no-js-hidden">
| LimeSurvey core used it for inactive link if javascript is not activated
|-
! scope="row" | .ls-label-xs-visibility {{NewIn|3.0}}
| Label to be hidden in big screen, but show with little screen (with no more table) and to screenreader
| label
| <label class="ls-no-js-hidden">
| Used for label inside table cell of array question type
|-
! scope="row" | .ls-input-group-extra {{NewIn|3.0}}
| Same usage of boostrap input-group-addon, but without the border and the background.
| right suffix
| <div class="ls-input-group-extra">
| Used for right and left suffix (global)
|-
! scope="row" | .checkbox {{ObsoleteIn|3.0}}
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .radio {{ObsoleteIn|3.0}}
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even {{ObsoleteIn|2.50}}
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2 {{ObsoleteIn|3.0}}
| Array question type
| Alternation for line
| <tr class="array1">
|
|-
! scope="row" | .ls-odd .ls-even {{NewIn|3.0}}
| Array question type
| Alternation for subquestion and Y axis
| <tr class="ls-odd">
|
|}

=== Some example of question part with classes=== 


'''Text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Equation||.equation||*
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options interact by default so that you can have validation tips hidden. However, they do appear when there are validation errors and disappear again when those errors are rectified.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been met yet; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|defrault type||.em_default||for default tip set ( numeric value etc …)
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above one from ''templates/default/template.css'' (for table-based layouts) or ''/templates/limespired/template.css'' (for CSS-based layouts) into your own style sheet without any impact on your other styles.

==Internet Explorer conditional style sheets== 


Because of the marked discrepancies in rendering between IE6 & IE7 and the other browsers, there are special IE conditional style sheets included for each template.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either ''/templates/default/'' or ''/templates/limespired'' for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put a conditional class for body in startpage.pstpl and use this class in your template.css. This method is used in the citronade template{{ObsoleteIn|2.06}}. Adding a js / no-js class to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use:


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


{{Deprecated|3.0}}


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}.


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded as of LS1.87''') Displays the current question text (The format of {QUESTION} can customised by editing 'question_start.pstpl') Use the following: {QUESTION_TEXT}, {QUESTION_MANDATORY}, {QUESTION_HELP}, {QUESTION_MAN_MESSAGE}, {QUESTION_VALID_MESSAGE}, {QUESTION_INPUT_ERROR_CLASS}, and appropriate wrapping HTML instead of {QUESTION}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SURVEYRESOURCESURL}||All Files||The URL to the current uploaded files for this survey location (useful for referencing image files in your question, group, ....)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{SAVEDID}||All Files||Displays 'Response ID' of user
|-
|-
|{QUEXMLPDF}||All Files||Displays button to export the queXML PDF of questionnaire including answers entered up until the point that has been completed in the survey.
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date, and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes, but it does allow the changing of background colour, text colour, size etc., for the rest of the ranking question)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally, you should use this to make sure that their font size and color is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background color for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the color and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the color and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


Because you can edit all the HTML aspects, there's no reason to surround your templates with a
<syntaxhighlight lang="php" enclose="div"><div class='new_name'></div></syntaxhighlight>
and then define a css for that new_name class.

==Styling the progress bar== 


The progress bar appearance can be modified with CSS.


To change the background color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


LimeSurvey has integrated some user-made patches that permits some special changes. These very advanced features (generally) require changes to the underlying code base of LimeSurvey and should be done carefully in order not to introduce security holes.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling them. In this way, a template author can create his or her own '''template_onload()''' function in the HEAD that replaces the default one.


*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.


{{Note|For further details, see the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey|workaround section]].}}

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, and customizing survey description page.


Video - needed

=Tips & Tricks= 

==Some language specific element== 


If you want to have some language specific sentence in a survey, for example a help at the end of each page, you can add in a .pstl file a sentence and hidding it for other language. If we hide it in the template.css, we can use the pseudo selector :lang, but we use some class for better compatibility.


Below, there are two help sentences, in French and English. Put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css:


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>

==Change the layout of the survey page== 


After editing and saving a template, it applies to a survey list page only if it is selected from the settings of the survey. To make it the default template, go under the '''General tab''' located in the '''Global settings''' of your LimeSurvey installation and choose the desired template. From now on, all the templates that use the "default" option as template plus the ones that are going to be newly created, will use the newly selected default template.


To use your current template for this page, you have to change the according setting from '''Global settings'''. In older versions, this change can be done by editing the $defaulttemplate setting from the config file: copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to <code lang="html">$defaulttemplate = 'yourtemplatename';</code>.

==Import/Export of templates: Mac users== 


<u>Mac users</u>, please note that the Mac OSX default archive utility may have problems with zip folders "generated on the fly".


A workaround is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


Another workaround is to use scripts in their mac-compiled counterparts.

==Replacing the help icon {{ObsoleteIn|2.50}} == 


When a question help text is shown, then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It will then be automatically used instead of the default help icon.

==Replacing an existing logo {{NewIn|2.50}} {{ObsoleteIn|3.0}}== 


'''Note''': In the '''default''' Template of 2.50, there is no preembedded logo. Read further our [[#Adding_your_own_logo |wiki on how to add your own logo]].


1. To edit the logo go to the ''<u>template.css</u>'' file which you can find it here:


<center>[[File:t1.PNG|200px]]</center>


2. Click the search button to find occurrences of logo related styles and search for ''logo''


<center>[[File:2.png|200px]]</center>


3. Edit the main style file.


You will see something similar to:


<center>[[File:t4.PNG|500px]]</center>


If you want to change the image, just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want to change the image size, adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo {{ObsoleteIn|3.0}} == 


1. Find and open the '''startpage.pstpl''' template file.


<center>[[File:startpage.pstpl.png]]</center>


2. After this
<source lang="html4strict" ><div id="topContainer" class="jumbotron"></source>
add this line to '''startpage.pstpl''':
<source lang="html4strict">
<div class="container"><img id='page_logo' src='{TEMPLATEURL}/files/logo.png' class="clearfix pull-right" /></div>
</source>


3. To upload your own logo, go to the template editor and upload your logo.


<center>[[File:uploadyourlogo.png]]</center>


To position your logo, please use one of the following css classes:


*'''If you want the logo to be placed on the left side:'''


<source lang="html">clearfix pull-left</source>


*'''If you want the logo to be placed on the right side:'''


<source lang="html">clearfix pull-right</source>


*'''If you want to center the logo'''


<source lang="html">clearfix center-block</source>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}files/logoImage-{SID}.png"></syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators.
#Name your new favicon "favicon.ico" and place it in your template /files directory.
#Add the following code to your '''startpage.pstpl''' before the </head> tag.


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages), you can use '''.page-odd''' class in your CSS file to change the appearance of odd pages.


An example from default template of LimeSurvey 1.91+:


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


If you do '''not''' want differentiate even and odd pages, find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array, you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


''header_separator'' is used to adress the separator for the header "td". The "dual_scale_separator" is used to address the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list {{ObsoleteIn|3.0}} == 


To hide the "Please contact ..." message on the start page (with the survey list), you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


<syntaxhighlight lang="php" enclose="div">


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages {{ObsoleteIn|3.0}}== 


If you want to remove the survey contact message from error messages, it'll be trickier. You can add the function from below. It calls the '''$(document).ready''' function in the '''template.css''' of your used design template:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for a survey in English language and has to be extended when used for multilingual surveys. But it's an idea/tip on how to solve this.

==How to deal with multilingual question attributes {{ObsoleteIn|2.50}}== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other":


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


Add in the template.css of your template (at ''/limesurvey/upload/templates/<yourtemplatename>/template.css''):


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

==Adding your own logo to the survey list {{ NewIn|3.0}} == 


# First please open the theme editor for the theme you like to use. [[File:OpenThemeEditor.jpg]]
# We recommend to use fruity, it is our best theme currently.
# Then extend the theme and give it a name you will recognize. [[File:ExtendTheme.jpg]]
# In the following view you may upload the logo you want to use. [[File:UploadFileTheme.jpg]]
# Select the editor screen `Survey List´ in the Screen dropdown in the top right corner. [[File:OpenScreenSurveyList.jpg]]
# Then select `layout_survey_list.twig´ in the left side menu. [[File:EditLayoutSurveyListTwig.jpg]]
# In the editor scroll to line 126 and change the marked part to the filename of the image you uploaded to the theme before. [[File:ChangeSurveyListHeaderImageEditor.jpg]]
# Save your file. [[File:ThemeEditorSaveChanges.jpg]]
# Change default theme to your extended theme. [[File:ChangeDefaultTheme.jpg]]

=Custom Question Views {{NewIn|3.0}}= 


<div class="simplebox">'''Note:''' This is a temporary feature to be replaced in the future by question object (it will be very easy to move custom views to question object). It is disabled by default.</div>


As of version 2.5, you can create template-specific custom views for questions and some of their incorporated elements. This is useful if you want to modify the HTML layout of a particular question type for one or more surveys.


*In application/config/config.php, find 'config'=>array and add this line to the array : 'allow_templates_to_overwrite_views'=>1
*In /{your_template}/config.xml, set "overwrite_question_views" to true
*Copy application/views/survey/* to template/{your_view_directory}/survey/
*Note that you only need to copy the files that you intend to modify but the file structure must remain the same as in application/views/survey/

=Insert Custom CSS or JavaScript files for template {{NewIn|2.50}}= 


As of version 2.50, you can use the config.xml file to automatically load plugin files.


*Upload your files to the template /css or /scripts folder
*In /{your_template}/config.xml, add the file paths to the <css> or <js> blocks, something like this:<syntaxhighlight lang="xml" enclose="div"><css>
<filename>css/jquery-ui-custom.css</filename>
<filename>css/bootstrap-slider.css</filename>


<filename>css/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</filename>
<filename>css/flat_and_modern.css</filename>


<filename>css/template.css</filename>


<filename>css/myCustomPlugin.css</filename>
</css>
<js>
<filename>scripts/template.js</filename>
<filename>scripts/bootstrap-slider.js</filename>


<filename>scripts/myCustomPlugin.js</filename>
</js>
</syntaxhighlight>

</translate>
[[Category:Theme]]
[[Category:Twig]]

Statistics

2019-10-29T14:06:39Z

Mazi: Documented usage of custom logo for statistics PDF

<languages /> <translate>


__TOC__

=General= 


The statistics feature is available from the responses toolbar by clicking first on the "Response and Statistics" menu entry located in the last drop-down menu, [[Responses]] (which is only available if a survey has been activated):


<center>[[File:Location_responses_and_statistics.png]]</center>


Look for the Statistics button located on the top toolbar and click on it:


<center>[[File:statistics.png]]</center>


The following page will be loaded:


<center>[[File:Statistics - start page.png]]</center>


The LimeSurvey statistics can be visualized in either the '''expert mode''' or '''simple mode'''. By default, the '''expert mode''' is loaded when you click on the [[Statistics]] button.

=Statistics - expert mode= 


Let's say you've got a survey running, or it is finished and you want to start analyzing the results. LimeSurvey can dump all the results into an Excel spreadsheet or CSV file. You can do whatever you want with the data from the respective file. Alternatively, you can use the statistics feature to have a look at your data and start getting some useful information from it.


The statistics - expert mode feature allows you to 'filter' your data and retrieve numbers and summaries of different fields from it. The statistics script doesn't attempt to do highly complex filtering, but you'd be surprised at the sort of information that can be easily obtained.

==Running quick statistics== 


As it can be observed below, there is a checkbox for each question that can be selected in order to show a response summary for each question, and an icon that when clicked (or if the mouse hovers over it), it gives you the full text of the question. To view the results for a question or questions, check the checkbox(es) at the top of the question(s) and then click "View statistics".


<center>[[File:Select answers and view statistics.png]]</center>


Alternatively, to view the results for all available questions, enable "View summary of all available fields" and then click "View statistics":


<center>[[File:View summary of all available fields.png]]</center>


You will then be given a "Results" table which will indicate the number of cases and a "Field Summary" table for each question selected which summarizes all possible answers in the question(s), their totals, and their corresponding percentage.


<center>[[File:Results view statistics.png]]</center>


{{Note|Please note that the statistics are displayed on the same page because the default [[Statistics#Output format and options|output format]] is HTML. If this is changed to PDF or Excel, then a pop-up will appear once the "View statistics" button is pressed, asking you to save the respective file on your machine.}}

==Filtering data== 


Two types of filters exist: [[Statistics#General filters|general]] and [[Statistics#Response filters|response filters]].

===General filters=== 


As the name suggests, it refers to filters at the general (macro) level:


<center>[[File:General filters - statistics.png]]</center>


The filters can be related to:


* '''Data selection'''
** ''The type of responses:''
*** Complete responses: responses that contain a submission date
*** Incomplete responses: answers that do not contain a submission date
*** All records: the aggregated number of complete and incomplete responses.
** ''Statistics report language:'' if additional languages are used, this filter option is useful to divide respondents based on the language they used to fill out your survey.


{{Note|For a discussion on incomplete responses, see the [[Responses & statistics#Responses summary|response summary]] wiki section.}}


<div class="simplebox"> Two attributes are located within the "Data selection" box:
*'''View summary of all available field:''' it is turned off by default. By enabling it, all the survey questions and groups will be taken into account when running the statistics script
*'''Subtotals based on displayed questions:''' it is deactivated by default. It counts stats for each question based only on the total number of responses for which the question was displayed (good way to filter the unfinished/incomplete responses).</div>


* '''Response ID:''' use the ID number to filter your gathered responses


* '''Submission date:''' displayed only if [[Notifications_%26_data#Save_timings|timings is enabled]]. You can filter the data based on the submission date of your collected responses.


To get the answers filtered according only to the '''general filters''', enable the "View summary of all available field" option and click on the '''View statistics''' button located in the upper-right part of the screen.

===Response filters=== 


Depending on the used [[Question types|question type]], different fields may be used to filter your answers:


* '''By response:''' click on one or more responses in the list under each question to filter the data by those responses (use CTRL/click to select multiple responses in the same question). Note that if you choose to view the summary of all available fields (checkbox at top) you will need to select your response filters before checking that box.


* '''By text:''' you can search the responses to a free text question type (and similar types) by entering a text. If you want to search for a partial string you can use the percentage sign (%) as wildcard. E.g.: If you look for 'Tom%', it will find entries with 'Tomb' and 'Tommy', etc.


* '''By numerical value:''' you can search the responses that contain a certain numerical value if number-based question types are used.


<center>[[File:Response filters - filtering options.png]]</center>


Selecting "View statistics" will then give you the "Results" table, indicating the number of responses matching your criteria, and a "Field Summary" table for each question selected which summarizes all possible answers in the question(s), their totals and their percentage. It is important to note that these results are a subset of your total responses. So, for example, if your criteria display 146 records out of a total 180, the summary will show the breakdown of just those 146 records for that table.


The images below indicate that I have elected to view the stats for "Employment status" of '''''completed records/female/age 18-25'''''. This gives me the results for 6 out of 13 records.


<center>[[File:stats_1a_new.png]]</center>


<center>[[File:stats_1b_new.png]]</center>


<center>[[File:stats_2b.png]]</center>


<center>[[File:stats_2_new.png]]</center>


{{Alert|title=Things to be cautious of|
*If you set criteria on the same question that you ask for a summary, then that question will only present answers matching your criteria. So it is good practice '''not''' to set any criteria on the same question you are getting a summary of.
*To select multiple entries for a question hold down the CTRL button when clicking. To "unselect" the last criteria (if you want to clear all criteria from a question) click on the respective highlighted answer while holding pressed the CTRL button.}}

==Graphs== 


{{Note|For technical reasons the Excel output does '''not''' contain any charts. If the PDF output is selected, charts are limited to pie charts (single choice questions) and bar charts (multiple choice question types).}}


For charting, the library pChart is used, which is completely included and usually doesn't have to be configured.


After the graphs have been generated you can export them easily. Right click on a graph and choose "Save image as", then save the graph as a .png file to your chosen location.


You can also use the "Export images" function to save all the graphs to your machine:


<center>[[File:Export images buttom.png]]</center>


<div class="simplebox"> [[File:help.png]] Please note that LimeSurvey cannot create graphs from certain types of question. For example, the [[Question type - Numerical input|numerical input question type]] cannot be visualized with the help of graphs. However, a simple table with values such as count, sum, standard deviation, average, minimum, median, and maximum is displayed in its case:


<center>[[File:Numerical question type statistics.png]]</center>


To see which questions can make use of statistics and/or graphs, you have to read each question type manual entry from [[Question types|here]]. If tab statistics is available, check which options are displayed under this tab. Three statistics attributes exist: [[QS:Chart type|chart type]], [[QS:Display chart|display chart]], and [[QS:Public statistics|public statistics]].</div>

=="incomplete responses", "no answers" and "not completed/not displayed" counts== 


*'''incomplete responses''': all responses that started to be filled out by respondents, but weren't completed. A response started when the participant clicked the "Next" button in the survey, but did not click the "Submit" button in the end (did not land on the end page of your survey).


Technically speaking, this is when there is no SubmitDate in the [[Responses|response table]] for this entry, but new data set was created already.


*'''no answer''': when the question was displayed, but the participant hasn't given an answer.


Technically speaking, this is when the question is not mandatory, was displayed, received no answer and the user clicked "Next" or "Submit". The consequence is that the database field for this answer is set to "" (empty string). This "no answer" status cannot be really computed for "Date" or pure "Numerical questions" where the database field cannot record a string.


*'''not completed/not displayed''': when the page containing the question was not displayed. This can be because of conditions, or just because the participant left the survey before this page was displayed (or just while this page is displayed, but without clicking the Next button).


Technically speaking, the database field for this question is filled with a NULL value.

==Output format and options== 


The statistics can be displayed under three different formats:


<center>[[File:Output format - statistics.png]]</center>


* '''HTML''' (default option): the statistics are displayed in LimeSurvey
* '''PDF''': a popup will be displayed, asking to save the statistics as a PDF file
* '''Excel''': To further work with your (filtered) data, choose Excel. You can export the file from a spreadsheet application to CSV to work with more advanced statistical tools such as SPSS or R.


The output options can be used to alter the way in which the statistics are displayed. The following options are available:


<center>[[File:Output options - statistics.png]]</center>


*'''Show text responses inline:''' it is disabled by default. It shows the text questions responses without having to click on a browse button (if enabled; useful for the HTML version of output format)


*'''Show graphs:''' it is disabled by default. If enabled, graphs will be displayed


*'''Number of columns:''' two is the default number. If you wish to have statistics and graphs displayed on only one or three columns, choose the desired value from this option. It applies to HTML statistics.


*'''Graph labels:''' choose how the label should look like in the graph.
**''Question code''
**''Question text''
**''Both''


*'''Chart type:''' the following chart type settings are available:
**''As defined in question settings:'' useful if you wish the graph not to be displayed. If this is the case, deactivate it from the question settings and select from the "Statistics" panel this option.
**''Bar chart''
**''Pie chart''
**''Radar chart''
**''Line chart''
**''Polar chart''
**''Doughnut chart''

==Embed custom logo at statistic PDF==
(available for Limesurvey 3.x since 12/2018)

If you want to embed your own logo to the statistics PDF, then make sure a file named exactly "statistics.jpg" is placed within the "images" folder of the [[Custom_Admin_Themes|admin theme]] used for your system. Which admin theme is used can be set at the [[Global_settings#General|Global Settings]].

=Statistics - simple mode= 


The simple mode was created in order to provide simple bar chart statistics that can be quickly exported and saved, and then included into a presentation:


<center>[[File:Simple mode - statistics.png]]</center>


As you can observe, fewer graphs are displayed than in the expert mode. While in the export mode you can display graphs with respect to those who filled out the survey, did not answer it or did not finish completing it, the simple mode displays only statistics that rely on the "countable" data submitted by the respondents (e.g., single or multiple choice questions as well as array questions).


There is only one option to filter the data within the simple mode - via the responses to be included in the statistics. As a result, the statistics may include the complete responses, incomplete responses, or all responses (the aggregated sum of the first two options). This option is located in the upper-right part of the panel.


To switch back to [[Statistics#Statistics - expert mode|expert mode]], look for the "Expert mode" button located in the upper-right part of the screen:


<center>[[File:Switch to expert mode.png]]</center>


{{Note|If you wish to have direct access to the simple mode of Statistics, LimeSurvey allows you to create your own entries in the menu. For more information, check the [[Menu entries configuration|menu entries configuration wiki section]].}}

=Public Statistics= 


LimeSurvey includes the functionality to display simple statistics to the general public or to your participants after they have ended filling out an online survey.


Two components need to be enabled in order to activate and display statistics to your participants. The first one refers to the public statistics of your survey which must be enabled (it is turned off by default). It is located under the [[Presentation]] tab. To also show graphs, look on the same page for the [[Presentation#Show_graphs_in_public_statistics|Show graphs in public statistics attribute]] and enable it (it is disabled by default).


<center>[[File:Presentation - public statistics.png]]</center>


Once you have set your survey to display statistics, you need to indicate question-by-question which statistics you want to be displayed to your respondents. By default, no questions will be displayed. To have them displayed, access the desired question, look for the "Statistics" tab and enable the [[QS:Public statistics|Show in public statistics]] attribute.


<center>[[File:Statistics tab - public statistics.png]]</center>

==What participants see== 


Once you have enabled public statistics and selected some questions to display, an additional option will be visible to participants when they end filling out your survey. In addition to the usual thank you, there will be a link to "View the statistics for this survey":


<center>[[File:Respondent - view statistics.png]]</center>


The survey statistics will be displayed on this page. Graphs can also be displayed by enabling the [[QS:Display chart|Display chart]] question attribute:


<center>[[File:Display statistics to user.png]]</center>


{{Note|Please note that only bar charts can be displayed in public statistics.}}

==Changing the look of the public statistics page== 


The looks of the public statistics page can be modified via template.css (search for "#statsContainer"). However, there is currently no template of it's own that can be edited in the [[Theme editor|LimeSurvey theme editor]].

=Hints & tips= 


Feel free to edit the following wiki sections to let other LimeSurvey users learn about statistics-related hints & tips.

==Wrong font when exporting statistics. What to do?== 


For some languages (like Chinese), the usual font used (Vera) does not cover the needed character set. In that case you can use the setting $chartfontfile to set a new TTF font file in config.php (Check out config-defaults.php for the right setting). For Chinese (Simplified and Traditional), another font has to be used such as the FireFlySung font which can be downloaded from [https://github.com/rougier/freetype-gl/blob/master/fonts/fireflysung.ttf github].

=FAQs= 

==5 point choice question type - what do the values located under the "Sum" column represent?== 


As it can be observed in the below screenshot, the '''"Sum"''' column shows the aggregated values in the following way:


<center>[[File:Sum_column_SC.png]]</center>


The grouping from the '''"Sum"''' column was done in this way because, when rating questions, survey administrators usually interpret the results in this way:


*Y percent of the respondents '''DISLIKE''' item ABC, where Y represents the percentage of those who answered "1" and "2"
*X percent of the respondents '''LIKE''' item ABC, where X represents the percentage of those who answered "4" and "5"
*Z percent of the respondents have a '''NEUTRAL''' opinion about item ABC, where Z represents the percentage of those who answered "3"


{| class="wikitable" style="text-align: left"
!Answer
!Count
!Sum
|-
|1
|0
|50% (the percentage of those who answered "1" and "2")
|-
|2
|2
|
|-
|3
|1
|25% (the percentage of those who selected "3" - the neutral option)
|-
|4
|0
|
|-
|5
|1
|25% (the sum of those who answered "4" and "5")
|-
|Sum (Answers)
|4
|100%
|-
|No answer
|1
|0% (always "0%")
|-
|Not completed or displayed
|0
|0% (always "0%")
|-}

</translate>

Plugin events

2019-10-03T08:07:46Z

Mazi: added details for availability

At version 2.50 build 160425 the following events are available for plugins to subscribe to:

NB: Version 2.60.0 is not the same as version 2.6, which is the new number for version 2.06. 2.60.0 comes after 2.59.1.

== Global Events ==

*[[afterFindSurvey]]
*[[afterPluginLoad]]
*[[afterQuickMenuLoad]]
*[[afterSurveyActivate]]
*[[afterSurveyComplete]]
*[[afterSurveyDeactivate]]
*[[afterSurveyQuestionAssessment]]{{NewIn|v=2.62|b=170207}}
*[[afterSurveyQuota]]{{NewIn|v=2.05|b=141006}}
*[[afterSurveySettingsSave]]
*[[beforeActivate]]
*[[beforeAdminMenuRender]] {{NewIn|v=2.50|b=160426}}
*[[beforeEmail]]{{NewIn|v=4.0.0}}
*[[beforeCloseHtml]]{{NewIn|v=2.60.0}}
*[[beforeControllerAction]]{{NewIn|v=2.50|b=160425}}
*[[beforeDeactivate]]
*[[beforeHasPermission]]{{NewIn|v=2.06}}
*[[beforeLoadResponse]]
*[[beforePermissionSetSave]]
*[[beforePluginManagerMenuRender]]{{NewIn|v=4.0.0}}
*[[beforeQuestionRender]]{{NewIn|v=2.05|b=140922}}
*[[beforeRegister]]{{NewIn|v=2.06}}
*[[beforeRegisterForm]]{{NewIn|v=2.06}}
*[[beforeSideMenuRender]]{{NewIn|v=2.51.0}}
*[[beforeSurveyAdminView]]
*[[beforeSurveyActivate]] {{NewIn|v=3.15|b=181017}}
*[[beforeSurveyBarRender]] {{NewIn|v=3.15|b=181017}}
*[[beforeSurveyDeactivate]]{{NewIn|v=2.5}}
*[[beforeSurveyEmail]]{{NewIn|v=4.0.0}}
*[[beforeSurveyPage]]{{NewIn|v=2.05|b=140109}}
*[[beforeSurveySettings]]
*[[beforeSurveysStartpageRender]]{{DeprecatedIn|v=3.0.0}}
*[[beforeTokenEmail]]{{NewIn|v=2.05|b=140404}}
*[[beforeToolsMenuRender]]
*[[beforeUrlCheck]]{{NewIn|v=3.12.2}}
*[[createNewUser]]
*[[createRandomPassword]]{{NewIn|v=4.0.0|b=190523}}
*[[checkPasswordRequirement]]{{NewIn|v=4.0.0|b=190523}}
*[[ExpressionManagerStart]] WIP {{NewIn|v=4.0.0-dev}}
*[[getGlobalBasePermissions]]]{{NewIn|v=3.0.0}}
*[[getPluginTwigPath]]{{NewIn|v=3.10.0}}
*[[listExportOptions]]
*[[listExportPlugins]]
*[[listQuestionPlugins]]
*[[newDirectRequest]]
*[[newExport]]
*[[NewQuestionAttributes|newQuestionAttributes]]{{NewIn|v=2.50|b=160731}}
*[[newSurveySettings]]
*[[newUnsecureRequest|NewUnsecureRequest]]
*[[onSurveyDenied]]{{NewIn|v=3.0.0}}
*[[setVariableExpressionEnd]]{{NewIn|v=4.0.0}}

== CLI Events ==

This events needs to be called with php cli command.

*[[cron (command)|cron]]{{NewIn|v=2.05|b=140404}}
*[[direct (command)|direct]]{{NewIn|v=2.63.0|b=170304}}

== Authentification related events ==

*[[newLoginForm]]
*[[Authentication plugin development#afterLoginFormSubmit|afterLoginFormSubmit]]
*[[afterSuccessfulLogin]]
*[[newUserLogin]]
*[[newUserSession]]
*[[Authentication plugin development#afterLogout|afterLogout]]
*[[afterFailedLoginAttempt]]
*[[Authentication plugin development#remoteControlLogin|remoteControlLogin]]

== Model Events ==

All models (Survey, Question, etc.) support a series of before & after events.

=== [[Specific model events|Specific Model events]] ===

These include model-specific events (example for Survey model):

* beforeSurveyDelete
* beforeSurveySave
* afterSurveyDelete
* afterSurveySave

=== [[Dynamic model events]]{{NewIn|v=3.15.1}}===

* beforeTokenDelete
* beforeTokenSave
* afterTokenDelete
* afterTokenSave
* beforeResponseDelete
* beforeResponseSave
* afterResponseDelete
* afterResponseSave
* beforeTokenDynamicDelete
* beforeTokenDynamicSave
* afterTokenDynamicDelete
* afterTokenDynamicSave
* beforeSurveyDynamicDelete
* beforeSurveyDynamicSave
* afterSurveyDynamicDelete
* afterSurveyDynamicSave

=== Generic events ===

As well as generic events independent of the model's name:

* [[beforeModelDelete]]
* [[beforeModelSave]]
* [[afterModelDelete]]
* [[afterModelSave]]
* [[beforeModelDeleteMany]]

In all of the above events, the associated model object is available as part of event data:

<code>$model = $this->event->get('model');</code>

[[Category:Development]]
[[Category:Plugins]]

BeforeAdminMenuRender

2019-10-03T08:06:36Z

Mazi: Added documentation

Used as an extension point to add menus to top menu. Check [https://manual.limesurvey.org/Extra_menus_event Extra menus event] for more details.
Available for 2.50_plus_160426 and later.

Workarounds: Survey behaviour

2019-03-14T08:38:29Z

Mazi: /* Randomization */ Added note about outdated workarounds

LimeSurvey users have been very creative in finding out how to change the behavior of a survey. All their workarounds are listed here. You can find some '''similar approaches''' at:
* [[Workarounds: Manipulating a survey at runtime using Javascript]]
* [[Workarounds: Question design, layout and templating]]

<div class="simplebox"><center><br />'''Please keep in mind that these workarounds are not official LimeSurvey extensions - they are solutions that users have created for themselves.<br /><span style='color:#EE0000,#FFFFFF'>Therefore LimeSurvey can't offer guarantees or support for these solutions.</span><br />If you have questions, please contact the users that, thankfully, shared their solutions with the community.'''<br /><br /></center></div>

__TOC__

=Respond multiple times using the same computer=

''Tested with: ''

With this workaround it will be possible to respond multiple times to the same survey. Normally there will be a message saying that the computer already received the answers. To prevent this you have to add the following code to the URL that leads to the survey ''"&newtest;=Y"''.

Example of the "new" url:

<syntaxhighlight lang="php" enclose="div">

http://www.yourdomain.org/limesurvey/index.php?sid=12345&newtest;=Y

</syntaxhighlight>

=Allow Multiple Survey Invitations to the same Email Address to be completed in the Same Browser Session=

''Tested with: ''

'''Problem:''' When Multiple Surveys Invitations are activated during the same browser session, the second and subsequent survey activation results in a system message stating that the survey has already been completed. A user would have to close the browser and reopen in order to complete the next survey inviation.

'''Workaround:''' Edit the Survey Invitation Email (also the reminder) Template. Append "&newtest;=Y" to the {SURVEYURL} line so it looks like this {SURVEYURL}&newtest;=Y

Save the edited templates.

Note: The save of this template edit does not seem to work when using HTML invitations, only text based invitations.

=Add a data field to manually add data=

''Tested with: ''

If you want to add some additional data after a user has finished a survey you can use the dataentry screen of the admin panel. You have to set up the survey as follows:
# Create a question that can store the needed data at the end of the survey.
# Use [[Setting conditions|conditions]] on the previous question so that whatever is answered at the previous question the following question '''doesn't appear'''.
# To enter several questions repeat steps 1-2. Don't forget to adapt the conditions.
# Go to the admin panel, chose the survey from the list and go to ''Dataentry screen for survey''.
# Enter the additional data

=Randomization=

'''Note:''' Most of the workarounds outlined below are pretty outdated. The new Limesurvey versions (>= 3.x) support various randomization features out of the box. These are outlined in more detail at https://survey-consulting.com/how-to-randomize-items-at-limesurvey.

==Totally random survey order==

''Tested with:''

If you want to use random order globally for all questions in your survey, you can do it like this, depending on what type of question routine you use.
# If you use Group by Group add "shuffle($_SESSION<nowiki>[</nowiki>'grouplist']);" at the end of UpdateSessionGroupList($language) function in index.php
# If you use Question by Question or All-in-one put "shuffle($_SESSION<nowiki>[</nowiki>'fieldarray'])" at the end of buildsurveysession() function in index.php

'''Important:''' This modifications affect all surveys in application, you may want to use an if statement with surveyid to make this work with specific surveys e.g.

<syntaxhighlight lang="php" enclose="div">

if ($surveyid==12345)

{

do_some_shuffling()

}

</syntaxhighlight>
*Saving survey is not possible because this workaround doesn't save random order for specyfic tokens.
*Solution doesn't care about language changes so if you have on in your survey this will not work.
*Using conditions is not possible because conditions rely on a fixed and pre-determined order of questions.

==Randomize the order of ''sequences of groups'' in a survey==

''Tested with: 1.86''

You can randomize the order of subsequences of groups in a survey. E.g., you may have a survey comprising the below group structure
*demographics
*itemgroup1
*itemgroup2
*itemgroup3
*interlude
*itemgroup4
*itemgroup5
*itemgroup6
*closingcomments

and want to separately randomize the presentation order of itemgroup1...3 and itemgroup4...6 while maintaining the position of the other three groups. A working code modification is described in the PDF file [http://bugs.limesurvey.org/file_download.php?file_id=1228&type;=bug randomize_groups] which is downloadable from the Bugtracker at [http://bugs.limesurvey.org/view.php?id=557].
* '''Note:''' The code will randomize the order of subsequent groups in isolation, not across different sequences. Hence in the above example, you might get ''itemgroup1, 3, 2'' but never ''itemgroup1, 4, 2''
* '''Note:''' The survey presentation format must be ''Group by Group'' not ''Question by Question''
* '''Note:''' If you wish to select only a limited number of groups from a larger set, replace

<syntaxhighlight lang="php" enclose="div">$scratcharr = array_merge($scratcharr, $randarr);</syntaxhighlight>with

<syntaxhighlight lang="php" enclose="div">$scratcharr = array_merge($scratcharr, array_slice($randarr,0,x));</syntaxhighlight>

where x is the number of elements/groups that you wish to include. In the example above '''$scratcharr = array_merge($scratcharr, array_slice($randarr,0,2));''' would select two out of the possible three groups in each group set.
* '''Warning:''' The code is compatible with conditions operating on items within a group but most possibly produces erroneous behavior with conditions between groups
* '''Warning:''' In a multi-language survey, the groups get randomized each time the language is changed. A simple workaround is to remove the language changer from the question pages of the survey leaving it on the welcome page only. (Though not totally foolproof this does lower the risk of unnecessary language changes.)

==Randomly show X out of Y question groups==
This workaround allows you to randomly show X out of Y question groups

Tested with: Version 2.06+ Build 150612 Default template

Workaround created by user "OMdev"

*Set up your survey to use JavaScript.
*Create a multi question with y number of answer options. Randomize this question from question settings.
*Select top X number of check boxes by add the following script to the source of this question.
<syntaxhighlight lang="javascript" enclose="div">
<script>
$(function(){
$('body').hide() //Hiding multi select question using JavaScript . You can also hide it with CSS.
var showNumberOfGroups = 2; //enter number of check box to select from top ie number of groups to show randomly.
var $cboxs = $('input:checkbox');
for(var i=0;i<showNumberOfGroups;i++){
$cboxs.eq(i).prop('checked',true);
}
document.getElementById('movenextbtn').click();//auto submitting page.
})
</script>
</syntaxhighlight>
*Add group relevance from the multi select question.

*You can download lss from below link.
https://www.limesurvey.org/en/forum/can-i-do-this-with-limesurvey/102176-show-x-out-of-y-question-groups#126288

==Selective Question Randomization==

''Tested with: 1.82''

With this workaround you are able to select which groups within a survey should have their questions randomized and not kept in order. This workaround also adds a tab in the question ordering page. The extra tab allows you to enable / disable question randomization for the selected group.

A working code and database modification is described in the PDF file [http://bugs.limesurvey.org/file_download.php?file_id=1939&type;=bug selective_random_questions] which is downloadable from the Bugtracker at [http://bugs.limesurvey.org/view.php?id=3107].

'''Note:''' This might not work when adding conditions or assessments to the survey.

==Randomize the order of questions within individual groups - JavaScript solution==

''Tested with: 1.85+ (7557), IE 6/7, Firefox 3.0, Safari 3.2''

This workaround allows you to randomize the order of questions in individual groups. It uses JavaScript/jQuery to apply this randomization to only those groups that you wish and requires no modification of the core files when updating the installation.

The script uses a cookie to "remember" the shuffled order of the questions for the duration of the session so if a respondent navigates away from the group and returns, they will see the same question order. However if the survey is submitted or the session expires the questions will be re-shuffled.

A couple of cautions about the script are:
#If the survey is saved, the questions will be re-shuffled when it is accessed again (as with the PHP solution).
#The question shuffling may play havoc with conditions within a group (as with the PHP solution).
#The script has been tested with all templates shipped with 1.85+ but if you have a custom template with "question" in the ID of division(s) (ie <div id="<span style='color:red'>question</span>Holder">) it may fail - the script looks for all divs with IDs starting with "question" and adds them to an array to be shuffled.

There is a small demonstration [http://www.partnersinc.biz/surveys//index.php?sid=84767&newtest=Y&lang=en here].

Put simply, the script:
#Checks cookies to see if the questions have already been shuffled for this group and session.
#If so - displays the questions in that order.
#If not - creates an array of all of the questions in the group, shuffles the array, sets a cookie with the shuffled array contents, displays the questions in the shuffled order.

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript (see [[Optional settings#Security|documentation here]])..
#Create your group and questions.
#In the source of the group description add the following onload function (see [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|How to use script]]).

Onload code:

<syntaxhighlight lang="php" enclose="div">

<script type="text/javascript" charset="utf-8">

$(document).ready(function() {

function shuffleQuestions() {

// Create an array to hold question IDs

var qArray = new Array();

// Find the group ID of the page

var fieldNames = $( 'input#fieldnames' ).attr('value');

var tmp = fieldNames.split('X');

var sID = tmp[0];

var gID = tmp[1];

// A function to get the value of a cookie by name

function getCookie ( cookieName ) {

var results = document.cookie.match ( '(<div class="simplebox">|;) ?' + cookieName + '=([</div>;]*)(;|$)' );

if ( results ) {

return ( unescape ( results[2] ) );

}

else {

return null;

}

}

// Get the session name

var sessionName = getCookie ( 'PHPSESSID' );

// Check to see if the question order has already been shuffled in this session

var cookieArray = getCookie ( 'sArray' + gID + '_' + sessionName );

// If already shuffled, use that question order

if ( cookieArray ) {

//qArray = $.trim(cookieArray);

qArray = cookieArray.split(',');

}

// If not, go ahead and shuffle

else {

// Load the IDs of all questions on the page into the array

$( 'div[id<div class="simplebox">="question"]' ).each(function(i) {

qArray.push($( this ).attr('id'));

});

// Shuffle the questions array

function shuffle(o){

for(var j, x, i = o.length; i; j = parseInt(Math.random() * i), x = o[--i], o[i] = o[j], o[j] = x);

return o;

}

shuffle(qArray);

// Set a cookie with the value of the shuffled array

var today = new Date();

today.setTime( today.getTime() );

var expires = 2 * 1000 * 60 * 60 * 24; // Expire the cookie in 2 days

var expiresDate = new Date( today.getTime() + (expires) );

document.cookie = 'sArray' + gID + '_' + sessionName + '=' + qArray + ';expires=' + expiresDate.toGMTString();

}

// Wrap the questions in a div

$( 'div[id</div>="question"]' ).wrapAll( document.createElement('div') );

$( 'div[id<div class="simplebox">="question"]:eq(0)' ).parent().attr('id', 'qWrapper');

$( 'div#qWrapper' ).css({

'padding':0,

'margin':0

});

// Insert the questions into the wrapper in the shuffled order

$.each(qArray, function(i, val){

$( 'div#' + val + '' ).appendTo( $( '#qWrapper' ) );

});

}

shuffleQuestions();

});

</script>

</syntaxhighlight>

==Randomise the order of questions ''within'' groups==

''Tested with: ''

You can randomize the order questions of within groups (i.e. without interleaving questions from different groups) like this:

1 Call a custom function from the last line of buildsurveysession() before the return statement in index.php:

<syntaxhighlight lang="php" enclose="div">

$_SESSION['fieldarray'] = withinGroupsShuffle();

</syntaxhighlight>

2. Add these custom functions at the end of the same file:

<syntaxhighlight lang="php" enclose="div">

$currentGid;

function withinGroupsShuffle() {

global $currentGid;

$groupArray = array();

$shuffledArray = array();

foreach ($_SESSION['grouplist'] as $group) {

$currentGid = $group[0];

$groupArray = array_filter($_SESSION['fieldarray'], "questionInGroup");

shuffle($groupArray);

$tmp = $shuffledArray;

$shuffledArray = array_merge($tmp, $groupArray);

$groupArray = array();

}

return $shuffledArray;

}

function questionInGroup($question) {

global $currentGid;

return ($question[5] == $currentGid) ? 1 : 0;

}

</syntaxhighlight>

(''I'm new to PHP, so please make changes if you can make the code shorter or more elegant'')

This could be combined with the method mentioned above for shuffling the order of groups:

<syntaxhighlight lang="php" enclose="div">

shuffle($_SESSION['grouplist']);

</syntaxhighlight>

I don't know how this code affects or is affected by conditions or tokens! This code has the same limitations as the global randomisation above: it applies to all groups in all surveys. It would be nice to add a group-level parameter like randomise_questions = [0|1], but I can't find a mechanism for doing that.

==Randomize all questions in "All In One" mode - even if they are place in groups.==

''Tested with: 1.91, IE 7/8, Firefox 3.6, Safari 3.2''

This workaround will randomize all questions when using "All In One" mode, even if they are place in groups. This may be useful if you want to use group assessments and display all questions on a single page in a random order.

Notes:
*The workaround is tested in the default template and may need slight tweaks for others.
*It is NOT tested with conditions.

Implementation is as follows:
#[[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|Set up your survey to use JavaScript]].
#Add the following script to the source of one of the questions.

<syntaxhighlight lang="php" enclose="div">

<script type="text/javascript" charset="utf-8">

$(document).ready(function() {

shuffleQuestions();

function shuffleQuestions() {

// Hide the group wrappers

$('div[id</div>="group-"]').hide();

// Create and insert a new question wrapper

var qWrapper = '<div id="qWrapper">\

<table class="group"> \

<tbody> \

<tr> \

<td> \

</td> \

</tr> \

</tbody> \

</table>\

</div>';

$('div[id<div class="simplebox">="group-"]:last').after(qWrapper);

$( 'div#qWrapper td' ).css({'padding-top':'10px'});

// Create an array to hold question IDs

var qArray = new Array();

// Load the IDs of all questions on the page into the array

$('div[id</div>="question"]').each(function(i) {

qArray.push($(this).attr('id'));

});

// Shuffle the questions array

function shuffle(o){

for(var j, x, i = o.length; i; j = parseInt(Math.random() * i), x = o[--i], o[i] = o[j], o[j] = x);

return o;

}

shuffle(qArray);

// Insert the questions into the new question wrapper in the shuffled order

$.each(qArray, function(i, val){

$('div#' + val + '').appendTo($('#qWrapper td:first'));

});

}

});

</script></syntaxhighlight>

==Random question sets==
===Pre 2.0===
''Tested with: 1.85+ (7557), IE 6/7, Firefox 3.0, Safari 3.2''

This workaround, in conjunction with the [[Workarounds: Survey behaviour#Randomize the order of questions within individual groups - JavaScript solution|randomizing questions script]], allows you to display a random set of questions in a group.

There is a small demonstration [http://www.partnersinc.biz/surveys//index.php?sid=84767&newtest=Y&lang=en here] (page 2).

JavaScript is used to first shuffle the question order and then hide the number of questions that you stipulate, effectively giving respondents a random question set. So if, as in the demo, you have 5 questions in your group and choose to hide 2, the respondents will be presented with a random 3 questions.

A brief explanation of the script is:
*The questions are shuffled (see [[Workarounds: Survey behaviour#Randomize the order of questions within individual groups - JavaScript solution|randomizing questions]]) and their IDs placed in an array.
*The number of questions to be shown is calculated and their IDs are moved to a new array.
*All questions in the first array are hidden - this effectively hides the first '''''n''''' questions on the page so you'll get a random set of questions displayed.
*An asterisk is prepended to the remaining questions (remove this if your questions are not mandatory).
*When the next/submit button is clicked, all remaining questions are checked for an answer. If any are unanswered, their text is turned red, an alert is popped up and the next/submit is aborted (remove this if your questions are not mandatory).

A cookie is used to "remember" the shuffled order of the questions for the duration of the session so if a respondent navigates away from the group and returns, they will see the same question set. However if the survey is submitted or the session expires, the questions will be re-shuffled and a new set will be displayed. Therefor this workaround should not be used with surveys that can be saved.

A couple of cautions about the script are:
#If the survey is saved, the questions will be re-shuffled when it is accessed again and a new question set will be displayed.
#The question shuffling may play havoc with conditions within a group.
#The script has been tested with all templates shipped with 1.85+ but if you have a custom template with "question" in the ID of division(s) (ie <div id="<span style='color:red'>question</span>Holder">) it may fail - the script looks for all divs with IDs starting with "question" and adds them to an array to be shuffled.
#The script may need to be modified to display the "Mandatory" asterisk in templates other than the default - see below.

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript (see [[Optional settings#Security|documentation here]]).
#Create your group with all questions non-mandatory (we'll make them mandatory later with JavaScript).
#In the source of the group description add the following script (see [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|How to use script here]]).
#Modify the function call at the end of the script for the number of questions to be hidden and the mandatory error text.

<syntaxhighlight lang="javascript" enclose="div"><script type="text/javascript" charset="utf-8">

$(document).ready(function() {

function shuffleQuestions() {
// Create an array to hold question IDs
var qArray = new Array();

// Find the group ID of the page
var fieldNames = $( 'input#fieldnames' ).attr('value');
var tmp = fieldNames.split('X');
var sID = tmp[0];
var gID = tmp[1];

// A function to get the value of a cookie by name
function getCookie ( cookieName ) {
var results = document.cookie.match ( '(<div class="simplebox">|;) ?' + cookieName + '=([</div>;]*)(;|$)' );
if ( results ) {
return ( unescape ( results[2] ) );
}
else {
return null;
}
}

// Get the session name
var sessionName = getCookie ( 'PHPSESSID' );
// Check to see if the question order has already been shuffled in this session
var cookieArray = getCookie ( 'sArray' + gID + '_' + sessionName );
// If already shuffled, use that question order
if ( cookieArray ) {
//qArray = $.trim(cookieArray);
qArray = cookieArray.split(',');
}
// If not, go ahead and shuffle
else {
// Load the IDs of all questions on the page into the array
$( 'div[id<div class="simplebox">="question"]' ).each(function(i) {
qArray.push($( this ).attr('id'));
});
// Shuffle the questions array
function shuffle(o){
for(var j, x, i = o.length; i; j = parseInt(Math.random() * i), x = o[--i], o[i] = o[j], o[j] = x);
return o;
}

shuffle(qArray);

// Set a cookie with the value of the shuffled array
var today = new Date();
today.setTime( today.getTime() );
var expires = 2 * 1000 * 60 * 60 * 24; // Expire the cookie in 2 days
var expiresDate = new Date( today.getTime() + (expires) );
document.cookie = 'sArray' + gID + '_' + sessionName + '=' + qArray + ';expires=' + expiresDate.toGMTString();
}

// Wrap the questions in a div
$( 'div[id</div>="question"]' ).wrapAll( document.createElement('div') );
$( 'div[id<div class="simplebox">="question"]:eq(0)' ).parent().attr('id', 'qWrapper');
$( 'div#qWrapper' ).css({
'padding':0,
'margin':0
});

// Insert the questions into the wrapper in the shuffled order
$.each(qArray, function(i, val){
$( 'div#' + val + '' ).appendTo( $( '#qWrapper' ) );
});
}

shuffleQuestions();

function hideQuestions(numberToHide, mandatoryMsg) {
// Create an array of the IDs of all questions on the page
var questions = new Array();
$( 'div[id</div>="question"]' ).each(function(i) {
questions.push($( this ).attr('id'));
});

// Remove the "shown" questions and place them in a new array
var questionsLength = questions.length;
var shownQuestions = questions.splice(numberToHide,questionsLength-numberToHide);

// Hide the remaining questions
$.each(questions, function(i, val){
$( 'div#' + val + '' ).hide();
});

// Add an asterisk to the "shown" questions
// NOTE: Comment this section out if questions are not mandatory
$( 'td.questiontext' ).prepend( '<span class="asterisk">*</span>');

// Interrupt the submit function and validate mandatory questions
// NOTE: Comment this section out if questions are not mandatory
$('form#limesurvey').submit(function(){
// Override the built-in "disable navigation buttons" feature
$('#moveprevbtn, #movenextbtn, #movesubmitbtn').attr('disabled', '');

// Loop through all "shown" questions and check for answer
var answered = 0;
$.each(shownQuestions, function(i, val){
if ( $( 'div#' + val + ' input.radio:checked' ).length == 0 ) {
$( 'div#' + val + '' ).css('color', 'red');
answered = 1;
}
else {
$( 'div#' + val + '' ).css('color', '');
}
});

if ( answered == 1 ) {
alert ( mandatoryMsg );
return false;
}
else {
return true;
}
});
}

// Call the hide function
// Edit here for number of question to hide and mandatory message
hideQuestions(2, 'Please complete all questions');
});
</script>

</syntaxhighlight>

To add the asterisk to non default templates, replace ''$( 'td.questiontext' ).prepend( '<span class="asterisk">*</span>');'''' with:

- basic - ''$( 'td.be' ).prepend( '<span class="asterisk">*</span>');''

- bluengrey - Not possible to insert asterisk in correct location

- business_grey - ''$( 'div.questiontext' ).prepend( '<span class="asterisk">*</span>');''

- clear_logo - ''$( 'td.be' ).prepend( '<span class="asterisk">*</span>');''

- default - ''$( 'td.questiontext' ).prepend( '<span class="asterisk">*</span>');''

- eirenicon - Not possible to insert asterisk in correct location

- limespired - ''$( 'div.survey-question-text' ).prepend( '<span class="asterisk">*</span>');''

- mint_idea - ''$( 'div.survey-question-text' ).prepend( '<span class="asterisk">*</span>');''

- sherpa - ''$( 'div.survey-question-text' ).prepend( '<span class="asterisk">*</span>');''

- vallendar - Not possible to insert asterisk in correct location

===Version 2.0 And Newer===
Here is a link to a sample survey showing how to do this with Relevance - [[Expression Manager Sample Surveys#Randomly Ask A Specific Number Of Questions In A Group (a sub-set of the questions)]]

==Randomization - ''Assign People Randomly'' To Surveys==

''Tested with: ''

This is a very easy way to assign people randomly to surveys, I think experts do it in other ways, but it works for me.

''LINK.PHP:''
<syntaxhighlight lang="php" enclose="div"><?php
$db = @file("link.txt"); // path to .txt file
$anz = @count($db);
srand((double)microtime()*1000000); // random numbers
$random = rand(1,$anz);
print $db[$random-1];
?>
</syntaxhighlight>

''LINK.TXT:''
<syntaxhighlight lang="php" enclose="div">
<meta http-equiv="refresh" content="1;url=http://www.survey1.com">
<meta http-equiv="refresh" content="1;url=http://www.survey2.com">
</syntaxhighlight>
''Only one link per line!''

''INDEX.PHP:''
<syntaxhighlight lang="php" enclose="div">
<html>
<head><title>title</title>

<?php
include("link.php");
?>

</head>
<body>

<table width=100% height=100%>
<tr>
<td valign=middle>
<center><font size=5>loading ... </font></center>
</td>
</tr>
</table>

</body>
</html>
</syntaxhighlight>

==Random Redirect responders to surveys==
''Tested with: ''

As the workaround above, this one assign randomly (uniform distribution) people to multiple surveys in easier way, but with the same outcome: every survey has the same probability to be accessed by a responder.

1. Copy and paste the code below in a text editor.
2. Replace the URLs with those of your surveys, and save it as index.php
3. Create a new directory in your server.
4. Upload the file in that directory and give the link (http://www.yourdomain.com/newdirectory) to the responders.

<syntaxhighlight lang="php" enclose="div">
<?php
$urls = array("www.site1.com",
"www.site2.com",
"www.site3.com");
$url = $urls[array_rand($urls)];
header("Location: http://$url");
?>
</syntaxhighlight>

=Prefilling survey elements=

There are some ways to pre-fill elements in a survey. The data to prefill an answer can be passed by URL if it matches a certain format.

==Prefilling survey answers using the survey URL==
''Tested with: 1.80 and later''

You can prefill answers to questions in your survey by passing the [[SGQA identifier]], and the answer, as a parameter of your survey URL. This feature will only work where the survey is commenced immediately upon entering the URL (so it won't work if you use CAPTCHA's to restrict access, or the registration page).

You'll need to ensure that the answer you pass is the correct format for the question you are attempting to prefill - for example - multiple option questions should contain a "Y" to check a box. List type questions need the correct answer code. To be certain which codes to pass, complete a survey manually with the prefilled answer(s) you want, and then export the results as question codes and answer codes(not full text). This will give you both the correct SGQA identifier (the name of the column), and the correct format for the answer.

<div class="simplebox">Starting with version 1.92+, you can use [[Expression Manager#Access to Variables|qcode naming]] for the variables in addition to, or instead of, using SGQA naming.</div>

<div class="simplebox">In '''version 2.x''' the link for a prefill have to look like that: http://www.example.com/index.php/survey/index/sid/712544/newtest/Y?712544X99X2151=gelb&712544X99X2152=12345 <br> And if your question code is QCODE and CODE2, you can use it like that : http://www.example.com/index.php/survey/index/sid/712544/newtest/Y?QCODE=gelb&CODE2=12345
It's important to add "newtest/Y" to the link.</div>

'''Example:'''

<div class="simplebox">http://www.example.../index.php?sid=1234&1234X43X123=Y</div>

With 2.0, if your url is like this /survey/sid/1234, you have to use:
<div class="simplebox">http://www.example.../survey/sid/1234/1234X43X123/Y</div>

When the user gets to that question, the "Y" will be prefilled as the answer to question 123 in group 43 in survey 1234.

'''Example Single-Choice:'''

<div class="simplebox">http://www.example.../index.php?sid=1234&1234X43X123=A2</div>

With 2.0, if your url is like this /survey/sid/1234, you have to use:
<div class="simplebox">http://www.example.../survey/sid/1234/1234X43X123/A2</div>

If you like to prefill a single choice question (answer-code A1 - X ), you have to write this. If you export the results of this question, you will see, that this kind of question save the answer code as result in table. Use in any case the capital "X" in the link!

===Prefilling survey answers using the survey URL and hiding the Answer===

Starting with version 1.87 every question has a property 'Always hide this question' which can be used for this purpose.

==Prefilling a date question with the current date==

''Tested with: 1.80RC3''

Workaround created by user "Mazi"

Using the [[Workarounds: Survey behaviour#Prefilling survey answers using the survey URL|workaround mentioned above]] you can prefill the current date for a date question. Instead of using the common link to a survey which looks like this

<div class="simplebox">http://www.yourdomain.org/limesurvey/index.php?sid=53298&newtest;=Y&lang;=de</div>

you create an additional script, let's call it date.php. This script contains the following code:

<syntaxhighlight lang="php" enclose="div">

<?php

$date = date("Y-m-d");

header("Location: http://www.yourdomain.org/limesurvey/index.php?sid=53298&newtest;=Y&lang;=de&53298X15X102=$date");

?>

</syntaxhighlight>

The script determines the current date and calls the survey with a certain URL. The current date is attached as the answer for a certain date question using [http://docs.limesurvey.org/tiki-index.php?page=SGQA+identifier SGQA identifier]. Don't forget to '''adjust the SID and SGQA identifier''' according to your survey/group/question ID!

Upload the new ''date.php'' file into your limesurvey directory. You can then call the survey using this link:

<div class="simplebox">http://www.yourdomain.org/limesurvey/date.php</div>

Things to watch out for:
* Date questions always use the internal date data format of the database which has to be YYYY-MM-DD!
* You have to adjust the SID at the URl.
* Also adjust the SGQA identifier (SIDXGIDXQID) according to your survey.
* This solution doesn't work if you use tokens at your survey.

=Offer option to change answers later=

''Tested with: ''

When having a closed access survey using a token table it is possible to offer the opportunity to change answers later. Normally after having submitted the answers a token is marked as "used". To prevent this do as follows:
* set your survey to question-by-question mode (or group-by-group mode)
* set the survey to Non anonymous + Allow persistence for token answers
* activate survey and create your token table
* add at least one question of type boilerplate (which contains just some text). This is necessaray to give some instructions to the user like "''Your answers have been recorded to the DB, if you're sure you won't modify them, you can submit your response. If unsure, please quit your browser now and get back later with the private URL you've received''.

By not submitting the survey the user is still able to change the answers later.

=Use general password for accessing a survey=

If you don't want to use tokens but a general password to access a survey you can set your survey to "allow public access". Don't create a token table but use the following workaround:
# Create a short text question first
# Create the other questions
# Use conditions on all the other questions. You can use regular expressions to validate the string entered at the short text question. Just validate a certain password. If the password is correct the following questions are shown.
# Create a boilerplate question which just says "invalid password" which is shown if the user entered a wrong password.

=Create token on the fly and Edit completed survey=

Warning: The link for the code link is wrong (June 2013)

When having a close token survey you can create a token on the fly by giving as parameters sid and token.

In addition if someone has already completed a survey he can review his answers and correct them.

[http://bugs.limesurvey.org/view.php?id=2982 Just put this script attached at the bugtracker ticket into limesurveys root directory]

'''Prerequisites''':
# Anonymous answers? No (This survey is NOT anonymous.)
# Enable Token-based answers persistence? Yes
# Switch to closed-acces mode

'''Example''':

<div class="simplebox">http://www.example.com/limesurvey180/newtoken.php?sid=98761&token;=12345</div>

where Survey id = 98761 your survey's id and token=12345 a token (any token actually)
# The first time the token will be created and you you will redirect to anwser the surrvey
# If you wont complete the survey and call the script with the same parameters you will be redirect to the same case in order to finish the survey
# If you finish the survey and call the script with the same parameters you will see restart the survey with your previews answers prefiled so you can change them
# Back to 3

this is valid for all survey in the installation but you can make a filter so it wont be valid for every survey.

'''Reference'''
*You can find the code provided by user "janokary" and a short explanation at the LimeSurvey Bug & Feature Tracker: [http://bugs.limesurvey.org/view.php?id=2982]

=multiple 'completed' with only one token=

''Tested with: 1.71''

Whit a closed survey, each token work only one time. Sometime we need the possibility to complete a particular survey several time with the same token. This works only if you survey is set to non-anonymous answers and to use datestamps.

Here is an example for the survey id '71314'. Don't forget to adapt your own sid.

Edit ''index.php '' to in the function submittokens() replace lines ~ 1312 :

<syntaxhighlight lang="php" enclose="div">

if (bIsTokenCompletedDatestamped($thissurvey))

{

$utquery .= "SET completed='$today'\n";

}

}

else

{

$utquery .= "SET completed='Y'\n";

</syntaxhighlight>with lines :

<syntaxhighlight lang="php" enclose="div">

if (bIsTokenCompletedDatestamped($thissurvey))

{

//multiple token only for survey 71314

if ($surveyid == '71314') {

$utquery .= "SET completed='N'\n";

}else {

$utquery .= "SET completed='$today'\n";

}

}

else

{

//$utquery .= "SET completed='Y'\n";

</syntaxhighlight>

We never update the database with the completed date and time for this survey.

'''Warning''' : a limitation of this code is that you never recieve a confirmation mail for the completed.

=Loop question(s)=

''Tested with: 1.85''

There is no real loop option within LimeSurvey 1.x. To loop a question an initial question to determine the number of loops is needed. Looping is then done using a condition workaround:

1. Create a single choice question asking "How many X do you want to rate", possible answers 1, 2, 3, 4, 5.

2. Create up to 5 following questions asking "Please rate item 1/2/3/...".

3. Check manual -> conditions and read it carefully.

4. Set conditions like

a) "Only show Q3 (Rate item 2) IF Q1 (How many...) was answered 2

OR Q1 (How many...) was answered 3

OR Q1 (How many...) was answered 4

OR Q1 (How many...) was answered 5"

b) "Only show Q4 (Rate item 3) IF Q1 (How many...) was answered 3

OR Q1 (How many...) was answered 4

OR Q1 (How many...) was answered 5"

c) Q5... see above

d) Q6...

Of course Q2 is always shown, the following question will be added by conditions depending on what the user answered at Q1.

=Prevent accidentially closing the survey=

Sometimes you want to ask the user to confirm that they want to close an incomplete survey and/or use the back/reload buttons (which might break LimeSurvey).

A solution can be done in javascript, as discussed in the forum: https://www.limesurvey.org/en/community-services/forums/can-i-do-this-with-limesurvey/96384-prevent-accidentially-closing-the-survey

You can add this functionality in the template.js file:
<syntaxhighlight lang="javascript" enclose="div">

//FEATURES: (2015-03-27) Now with fix for iframes (e.g. file uploader) and the template editor
function goodbye(e) {
if(!$('body', top.document).hasClass('submitted') && !$('#completed').length && !$('.templateeditor', top.document).length) { //check if a button was used to navigate OR the survey is completed OR the template is displayed in the template editor

if(!e) e = window.event;
//e.cancelBubble is supported by IE - this will kill the bubbling process.
e.cancelBubble = true;
e.returnValue = 'Are you sure you want to quit this survey?'; //This is displayed on the dialog for IE

//e.stopPropagation works in Firefox.
if (e.stopPropagation) {
e.stopPropagation();
e.preventDefault();
}

return 'Are you sure you want to quit this survey?'; // For chrome
}
}

window.onbeforeunload = goodbye;

$(document).on('click', '.button, .changelang, [name="move"]', function(event){ //added .changelang here, please add other classes if you know which should be allowed to navigate
$('body', top.document).addClass('submitted');
});
</syntaxhighlight>

=Alternate system for Ranking=

Sometimes default ranking are not usable for your survey. But Expression manager unique function can easily be used for other question type.

* With an 'Array' question where answer are number from 1 to X (X is the max number of choice to rank).
** 'Question validation equation': <code>unique(self)</code>
* With a 'Multiple numerical input' question :
** 'Question validation equation': <code>unique(self) and count(self)==max(self) </code>
** 'Sub-question validation equation': <code>(is_empty(NUMBER_SQ001) or is_int(NUMBER_SQ001)) and (is_empty(NUMBER_SQ002) or is_int(NUMBER_SQ002)) ...</code> to have only integer value set
* With a 'Array (Numbers) ' question :
** 'Question validation equation': <code>unique(self) and count(self)==max(self) </code>

Demonstration can be found here : [http://limesurvey.sondages.pro/714997.html Demonstration of alternate ranking solution] , lss file : [[media:Limesurvey_survey_lotofranking.lss]]

QS:Random order

2019-03-14T08:32:23Z

Mazi: Added link to additional details

<translate>

<languages />
<onlyinclude>

===Random answer order (random_order)=== 


'''Description'''


This attribute causes LimeSurvey to ignore the existing order of answer options/subquestions, and instead it orders them randomly. This option permits the survey creator to diminish the survey bias. Please note that if a question has subquestions, the order of subquestions will be randomized, not the order of the answer options.
Check https://survey-consulting.com/how-to-randomize-items-at-limesurvey/#Randomizing_the_order_of_answersitems for more details.


'''Available options'''
*Yes - Randomize when participant enters survey
*No (default)
</onlyinclude>


[[Category:Question Settings]][[Category:Question Display Options]]

</translate>