LimeSurvey Manual - User contributions [en]

Menu configuration

2018-07-05T13:18:29Z

LimeAJ: Minor grammar correction.

<languages />
<translate>


__TOC__


{{Alert|text=Under construction}}

=General= 


If you would like to create a new menu or add new entries to a preexisting menu, access '''Menu configuration''' from the '''Configuration''' dialog.


<center>[[File:Menu Configuration.png]]</center>


If you are unhappy with the existing survey menus or you wish to create a special survey menu for a certain user group, edit the default ones or create new menus. You can also add new [[Menu entries configuration#Create a menu entry|menu entries]] or [[Menu entries configuration#Edit menu entry|edit the existing ones]].

=Survey Menu= 


Once accessed, you can see in the Menu Configuration panel a table with all the existing survey menus.


<center>[[File:Survey Menus.png]]</center>


Four actions are available:
*[[Menu configuration#Create a menu|Create a menu]]
*[[Menu configuration#Edit a menu|Edit a menu]]
*[[Menu configuration#Delete a menu|Delete a menu]]
*[[Menu configuration#Reset to default values|Reset to default values]]

==Create a menu== 


If you would like to create a new menu, press on the green button ('''+ New''') located in the upper left part of the window. The following window will pop-up:


<center>[[File:Create a New Menu.png|Create a New Menu.png]]</center>


A group of options is available:
*'''Parent''': Use this option to select the parent menu of another survey menu. In this way, a survey menu will be displayed within another menu once clicked. For example, the plugin menu is a survey menu that has as parent menu the ''mainmenu'', being displayed the bottom of it due to its '''order'''.
*'''Survey''': You can choose the survey the menu will be available for. It comes automatically set up for ''All surveys'';
*'''Ordering''': If you use more menus that have the same position, ordering them would help you better organize them.
*'''Title''': The tile of the menu;
*'''Description''': A short summary of the entries that will be added to that menu can be added - useful for other LimeSurvey administrators that wish to later change the configuration of the survey menus;
*'''Position''': Four positions are available:
**''Sidemenu'' : The menu will be located on the left side of the window;
**''Collapsed menu'' : A collapsed menu will display only the icons of the survey menu entries;
**''Top bar'' : The menu is going to be on a bar located in the upper part of the window;
**''Bottom bar'' : The menu is going to be on a bar located in the lower part of the window.

==Edit a menu== 


If you would like to change the details of an already existing menu, click on the green button located in the ''Action'' column. Once done


<center>[[File:Edit existing survey menu.png]]</center>

==Delete a menu== 


If you want to delete a menu, click on the red trash button that corresponds to that respective menu (located in the '''Action''' column). If you click '''Delete now''', all the menu entries of that menu will also be deleted.

==Reset to default values== 


In the case in which you edited the default menus and you want to return back to the default values, click on the '''Reset''' button located in the upper right part of the window. Once clicked, you will be asked to confirm the operation. Please note that all the custom menus will be lost if you decide to proceed.


<center>[[File:Restore default survey menus.png]]</center>


{{Alert|title=Attention|text=Please note that in order to backup your survey menus configuration, create a [[Backup entire database|LimeSurvey database backup]]. A separate option will be introduced in the near future to facilitate only the backup of the survey menus.}}

=Examples= 


Check the following examples to better understand how you can edit survey menus.

== I want the default collapsed menu to become the new sidemenu == 


The default sidemenu (located under the [[Survey settings|survey settings tab]]) is:


<center>[[File:Default survey settings menu.png]]</center>


To change it, access the menu configuration panel. Edit the ''mainmenu'' and change its position from '''sidemenu''' to '''collapsed menu''', and the position of the ''quickmenumenu'' from '''collapsed''' to '''sidemenu'''.


Once the changes are done, the sidemenu of the survey (the options displayed under the settings tab) will become the following one:


<center>[[File:New survey menu example.png]]</center>

== I want to change the icons and add new menu entries to the default main menu == 


To do that, you need to configure the LimeSurvey menu entries. To do that, please continue reading the following [[Menu entries configuration|wiki section]].

</translate>

Survey settings

2017-09-05T13:35:01Z

LimeAJ:

<languages />
<translate>


__TOC__

=Overview= 


Some of these settings can be set when creating a new survey. Click on the Add quick-button [[File:Btn_create_survey.png|100px]] or choose Survey/Create a new survey from the dropdown menu on the top-right and a "Create new survey" screen will appear.


You can edit all of these settings later again by choosing your survey and clicking General settings & texts in the 'Survey properties' dropdown menu of the survey toolbar.

=Settings= 


All survey settings and functions are organized in tabs. The following is a description of each tab and field.

==General== 
#'''Base language''': This sets the base language for the survey. Once saved, you cannot change it later. The language-set is the base language for possible translations of the survey. That way you can have multilingual surveys. During survey creation you cannot add additional languages. You will be able do that if you edit the survey properties again, later.
#'''Additional languages''': To choose additional language. <span class="alert">Only available when survey is created.</span>
#'''Title''': This is the brief descriptive name of the survey (ie: "Enterprise Bargaining Survey 2003", or "Views on Ice Cream"). This title will be displayed on every page of the public survey.
#'''Description''': This allows you to enter a description of the survey. (ie: "A survey to collect your ideas on the next round of enterprise bargaining" or "A survey to find out the popularity of chocolate ice cream"). You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor. By default, description is used on invitation email.
#'''Welcome message''': This allows you to enter a message that will display when a participant first logs into your survey. (ie: "Thank you for taking the time to participate in this survey..") You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor. <span class="alert">Only available at survey creation. After survey creation, it is available in Edit survey text elements.</span>
#'''End message''': This allows you to enter a message that will display when a participant completes your survey. (ie: "Thank you for completing our survey. We will publish results soon."). You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor. <span class="alert">Only available at survey creation. After survey creation, it is available in Edit survey text elements</span>
#'''End URL''': This URL will be presented as a link at the end of the survey, and allows you to direct your participants back to your home page (or, in fact, anywhere). The End URL has to be entered with "http://" at the beginning, eg. http://www.limesurvey.org. <br />You can use they placeholder {SAVEDID}, {TOKEN}, {SID} and {LANG} in this URL.<br />SAVEDID is the id assigned to this particular submission, TOKEN is the token used to participate in the survey, SID is the survey ID and LANG is the language code<br />eg. http://www.limesurvey.org/test.php?var1={SAVEDID}&var2;={TOKEN}&var3;={SID}&lang;={LANG} <br />From version 1.82+ you can use [[URL fields]] with this field to pass parameters from the start URL to then end URL. <br />You can also use {INSERTANS:SGQA} in this URL (since 1.82+). This allows adding the response to a specific question in the survey to the final url. This can be useful for sending a response to an external script (ie an email address collected during the survey). eg: "http://www.limesurvey.org/test.php?email={INSERTANS:1234X56X7}".<span class="alert">Only available at survey creation. After available in Edit survey text elements</span>
#'''URL description''': The description for the link using the End URL.<span class="alert">Only available at survey creation. After available in Edit survey text elements</span>
#'''Administrator''': This is the name of the contact person who administers the survey. It will be included in emails sent out inviting participants to respond.
#'''Admin email''': This is the email address of the administrator (as above) and is used as the 'From:' address on any emails sent.<br />NOTE: many hosting providers' SMTP servers will only accept emails whose 'From:' address is on a local domain, with the added difficulty that any emails that do not conform to this rule are discarded silently, without any visible error message. If this happens to you, ensure that you are using a provider-based email address in the 'Admin email' field. You usually can, if you so desire, set up email forwarding on the provider's side, so that any messages sent there are relayed to your preferred address.
#'''Bounce email''': This is the email address where a delivery error notification email should be sent. By default, this is the same as the administrator's email address. If you want to use a custom script to parse delivery error emails, then use a special Bounce Email address here and automatically process emails reaching this address with your script. This script could then update the Email Status field of the token line corresponding to this email address (see tokens).
#'''Fax to''': This field is used to give a fax number on the "printable survey" - ie: when you want to send someone a hard copy because they cannot use the online survey.


<div class="simplebox">'''Caution''': the HTML WYSIWYG editor doesn't allow you to upload files during the survey creation process. Trying to do so will end up with an error message like: "''This file uploader is disabled''". If you need to upload pictures or any other ressources, please do so after survey creation, by editing the newly created survey.</div>

==Presentation & navigation== 


[[File:Survey-settings_presentation-navigation_tab.png]]


#'''Format''': Choose from "Question by question", "Group by group" or "All in one".
#*'''Question by Question''': Public survey will display one question per page.
#*'''Group by Group''': Public survey will display all questions in a group per page. Group at a time surveys still have a separate "welcome" page and "submit" page, like "Question by Question" surveys.
#*'''All in one''': Public survey will display all questions in one single page. Activated All in one surveys do not have a "welcome" page or "submit" page - the welcome message and submit button all appear on the same page.
#'''Template''': Choose from the installed templates in your system. The default template is rather dull, but functional. More information on creating your own templates is available [[The template editor|here]].
#'''Show welcome screen''': Yes/No. If Yes, then the welcome message defined in Text Elements section will be displayed. Default is Yes.
#'''Navigation delay''': Number of seconds before Previous and Next buttons are enabled. Default 0 seconds
#'''Show <nowiki>[</nowiki><< Prev] button''': This option defaults to yes, however if you set it to "No" then users will not have the option of moving to a previous page while completing the survey.
#'''Show question index / allow jumping''': Yes/No. Default No. When Yes, an index will be displayed on the right side. Users can jump to any section in the survey. In 2.05 the options have changed to Disabled / Incremental / Full. Disabled and Incremental represent the current No and Yes options. Full always shows all groups / questions, this allows the user to freely navigate through the survey. This might not work for all kinds of conditions.
#'''Keyboard-less operation''': By activating this setting there will be a virtual keyboard available for certain question types.
#'''Show progress bar''': Yes/No. Default Yes. Allow the administrator to turn off the Progress bar
#'''Participants may print answers?''': This option defaults to no. When it is set to yes, a participant can print a summary of responses at submit time.
#'''Public statistics''': Yes/No. Default No. If set to "Yes" users who have submitted the survey will be presented a link to statistics of the current survey. The admin can set which questions should be included at these statistics by [[Advanced question settings#public_statistics|applying the according question attribute]].
#'''Show graphs in public statistics''': (''since 1.80'') Determines if public statistics for this survey include graphs or only show a tabular overview. Creating graphs for huge surveys with lots of answers takes some time and server resources so this is the switch to turn them on/off (default setting: ''off'').
#'''Automatically load URL when survey complete''': Yes/No. Default No. If yes, when the survey is submitted, it will automatically redirect to the End URL. The end URL can be defined in the Text Elements Section. Please note that this only works on an active survey.
#'''Show "There are X questions in this survey"''': Yes/No. Default Yes. If Yes, the message will be displayed on the Welcome Screen. This option will not affect the print version.
#'''Show group name and/or group description''': Will control the display of Group Names and Descriptions. This option will not affect the print version. Four Options:
#*'''Show Both''' - Default
#*'''Show Group Names Only'''
#*'''Show group description Only'''
#*'''Hide Both'''
#'''Show question number and/or code''':
#*'''Show Both''' - Default
#*'''Show Question Number Only'''
#*'''Show Question Code Only'''
#*'''Hide Both'''
#'''Show "No answer"''': Yes/No. Default Yes. When Yes, the No Answer will be displayed as the default option for non-mandatory single-select questions. Be aware that if you switch this off, the participant won't be able to unselect a chosen answer option in a non-mandatory question.

==Publication & access control== 
#'''List survey publicly''': Yes/No. Default No. When it is set to yes, your survey will be listed in the 'available surveys' portal
# '''Start date/time''': Set this to some date if you want your survey to start on a certain date. The survey will start on midnight of that day and only then will people be able to answer to it. To disable this just clear the date from the input field.
#'''Expiry date/time''': Set this to some date if you want your survey to expire on a special date. This is the last date on which the public survey script will let people participate. (Example: If you set it for the 31st of December, then people will no longer be able to use the survey script on the 1st of January). To disable this just clear the date from the input field.
#'''Set cookie to prevent repeated participation?''': If you set this to 'Yes', and your survey does not use a tokens table to control participant access, then a cookie will be saved to the client computer of each survey participant once they have submitted a survey. This cookie will stop the same user on that computer from accessing the survey more than once. There are inherent limitations in the 'security' strength of such a system, but, in general, it allows you to retain some control over multiple entries on public surveys.
#'''Use CAPTCHA for''': With this option you can decide when you want a CAPTCHA to be used. Default is to enable CAPTCHA only for the public Registration page, but you can also enable it before accessing the survey, and before Load/Saving partial answers.

==Notification & data management== 


[[File:Survey-settings_notifications-tab.png]]


#'''Send basic admin notification email to:''' and '''Send detailed admin notification email to:''' These fields allow you to send notifications or survey responses to any email addresses once the survey is submitted. You can edit the templates for these emails under 'Email templates'. Multiple recipients can be set by separating the entries with a semicolon (;) - eg "yourname@test.com; myname@test.com;hisname@test.com" OR when using placeholders "yourname@test.com;{INSERTANS:82733X12X73};{TOKEN:EMAIL}". To sedn an email to the administrator email of the survey : you must use {ADMINEMAIL}. There are different ways for entering an address:
##Enter a specific ''email address'' (ie: yourname@test.com)
##Enter a ''SGQA code'' and the response will be sent to an email address entered as an answer to that particular question (use the format {INSERTANS:9999X88X12}, in the same way you would [[Adding a question#Information from previous answers|Re-use information from previous answers]])
##Enter a ''Token code'' (only possible if your survey is ''not'' anonymous) and the response will be sent to an email address retrieved from a token field (use the format {TOKEN:EMAIL} or {TOKEN:ATTRIBUTE_1} in the same way you would [[Adding a question#Information from tokens table|Re-use Information from the Tokens Table]])
##''As of Version 1.92:'' Enter a valid expression conforming to [[Expression Manager|Expression Manager]] syntax. This lets you use question code instead of SGQA syntax (for easier readability), plus conditional logic (e.g. route the notifications to different people depending upon the data entered into the survey).
#'''Date stamp?''': This field allows you to determine whether the survey will datestamp all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response indicating the time and date that the response was made. (See configuration settings for $timeadjust setting.)
#'''Save IP address?''': This field allows you to determine whether the survey will save an IP-address for all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response indicating the ip-address of the participant.
#'''Save referrer URL?''': This field allows you to determine whether the survey will save the referrer URL for all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response where this URL is saved. A referrer URL is the URL from which the user was led to your survey URL.
#'''Enable assessment mode?''': With this setting you can enable/disable [[Assessments|assessments]] for this survey.
#'''Save timings''': If activate then on survey activation a separate table will be created where timings for your questions will be saved, e.g. how long a user stays on one page during taking the survey.
#'''Participant may save and resume later?''': This setting allows a participant to save his responses and resume to answer the survey at a later time. Please note that this makes most sense with open surveys or surveys with anonymized answer. If you are using tokens and the survey is not anonymous in most cases it is better to activate 'Token-based response persistence' in the token tab.
#'''Google Analytics Tracking ID for this survey''': Allows for integration with Google Analytics. The tracking ID can be inserted into templates using {GOOGLE_ANALYTICS_API_KEY}. The full JavaScript that Google Analytics expects (including the key) can be included in templates via {GOOGLE_ANALYTICS_JAVASCRIPT}
#'''Google Analytics Style for this Survey''': Choices are:
##'''Do not use Google Analytics''' - so {GOOGLE_ANALYTICS_JAVASCRIPT} is an empty string
##'''Default Google Analytics''' - {GOOGLE_ANALYTICS_JAVASCRIPT} uses the standard Google Analytics code, inserting the proper Google Analytics Key
##'''SurveyName-<nowiki>[</nowiki>SID]/GroupName''' - {GOOGLE_ANALYTICS_JAVASCRIPT} contains customized Google Analytics code to log the URL as {SURVEYNAME}-<nowiki>[</nowiki>{SID}]/{GROUPNAME}. This can be helpful if you want to analyze navigation paths through your survey, time spent per page, and drop-off rates per page.


'''Google API howto''':
# Register/login on Google Analytics (GA): [http://www.google.com/analytics/ www.google.com/analytics/]
# Create a tracking ID (the site should not point to the survey, but to the part before 'index.php?') The tracking ID should be UA-xxxxx.
# Go to your survey's global settings in LimeSurvey.
# Put the tracking ID in appropriate field (Google Analytics tracking ID). It's probably the best to set GA style to track all pages as you can have more info.
# You don't need to do anything in shipped templates, as the {GOOGLE_ANALYTICS_JAVASCRIPT} part is already there.
# Activate the survey.
# Do the survey.
# Go to GA panel mainsite. (select appropriate account in left-hand upper corner if you have more than one). You should see some graphs with the statistics. Beware of the dates in upper right corner.

==Tokens== 


*'''Anonymized responses?''': This allows you to determine whether responses to your survey are matched up with information from your surveys tokens table, or kept 'anonymous'. The default is 'No'. If you choose 'Yes' then your survey is set to radically anonymize responses - there is really no way to connect answers and participants. Even the admin can't link response data and participant/token data. However you will always be able to specifically view each response entered by your participants in the survey. Thus individual, but anonymous, statistics is still possible to do. '''''Attention:''''': If this feature is activated the response submission date and the token completed date are always set to 1980-01-01 00:00, no matter of other settings. Why? Invalidating the submission date ensures no match with webserver logs where the token key might show up when a survey is started. Invalidating the token completed date makes sure that you can't align the order of submitted responses to the order of the token date/time.


*'''Enable token-based response persistence''': If your survey uses tokens and your responses are not anonymized, you may want to enable this feature. If you turn this on, your participants will be able to leave the survey and resume later at any time without using the 'Resume later' function - for example if they get distracted or their browser crashes. Upon clicking the invitation link again, they will find their survey answers still in place when they return to the survey, and will even find themselves on the same page where they were before leaving.


*'''Allow multiple responses or update responses with one token?''': Default: No. If you activate this setting, participants will be able to return to their survey by clicking the invitation link, even if they have already submitted the survey. If the survey is anonymous or "Enable token-based response persistence" is set to NO, this will add a new response. If the survey is not anonymous and "Enable token-based response persistence" is Yes, the user will update the existing responses.


*'''Allow public registration''': If you use tokens to control access to your survey, the only people who can use the survey are those who have an entry and a unique token from the token table. If you would like to use tokens, but also allow public registration, set this to "Yes". The "Yes" setting will allow a visitor to register his name and email address. The script will create a new entry in your tokens table for this person, then send them an invitation email. The script will ensure that only one person per email address can complete your survey.


*'''Use HTML format for token emails?''': When set to yes, all emails sent by the token management interface (invite, reminder, confirmation) will be formatted as HTML. You'll then be able to use rich formatting for this emails. Default is Yes at survey creation. Caution, when you switch on/off this feature, you'll have to double check that your email templates are still displayed as you want.


*'''Set token length to''': Usually you don't need to change this, the default setting of 15 digits (max. supported value: 35) is fine. If changing this setting please enter a number (X) which should be greater than 5 (if the number entered is <5 it will be converted to the default value of 15). When generating tokens all tokens will use a length of X digits.

==Import== 


Alternatively you can [[Importing a survey structure|import a survey structure]] from this tab on survey creation. You have the option to let LimeSurvey automatically convert relative URLs to local images/media files and INSERTANS tags (recommended).

==Copy== 


Alternatively you can copy an existing survey from this tab on survey creation. You have the option to let LimeSurvey automatically convert relative URLs to local images/media files and INSERTANS tags (recommended). The other options are pretty self-explaining. Please note that when copying a survey the start date and the end date of a survey cleared.

==Panel integration (URL parameters)== 


<div class="simplebox"> Please note that this tab is currently not visible on survey creation but only when you edit the survey settings after saving them for the first time.</div>


On this tab you can set which additional URL parameters will be accepted by your survey (these parameters would be attached to the general survey start URL). This is important if you integrate with a professional survey panel provider that provides the participants for your survey. They usually hand over a unqiue ID with every participant and you will need to save/handle this unique ID for reference. Also with some providers the unique ID of the participant (bdropping out due to quota or finishing the survey) needs to be sent back to the panel provider in the survey end URL.


If you like you can also save the value as a response of a "Short text question" or "Multiple short text question" type (you will be able to select any short text question to save it to). Even if you do NOT save the value of the URL parameter you will be able to use this parameter in the end URL. Please have a look at the documentation of the [[URL_fields#Passthrough_fields_.28LimeSurvey_2.x_or_later.29|End-URL]] for further information.

==Resources== 


This tab lets you manage files (pictures, media files) that were uploaded in the HTML Editor and it is only visible if you edit a survey - not during survey creation.


You can:
* Browse available files
* Export files as a ZIP archive
* Import a ZIP archive of files


Important hints:
* Authorized files extensions are defined in config-defaults.php.
* Files for the survey are in the upload/surveys/<sid> subdirectory.
* Uploaded files will only been seen while browsing resources on this survey (groups, questions, answers) not in other surveys or objects (labels).
* Do not expect this limited visibility to ensure confidentiality of the resources as they are reachable with a simple browser to anyone who know the URL to the file.
* You can't import a ZIP file containing subdirectories.

=Additional languages= 


To add more languages to a survey you have to create and save it - then edit it again. Now you can add and remove additional languages to the survey. If you remove a language from a survey the complete contents of that language in that survey is deleted permanently so be careful what you are doing.


By clicking on the button 'Save and continue' on the first page in the survey settings you will be taken to the language-specific page which lets you change all texts for each language like ''Survey name'', ''Welcome Text'', etc. You can also edit the date format which should be used for a certain language.

</translate>

Survey settings

2017-09-05T13:34:17Z

LimeAJ:

<languages />
<translate>


__TOC__

=Overview= 


Some of these settings can be set when creating a new survey. Click on the Add quick-button [[File:Btn_create_survey.png|100px]] or choose Survey/Create a new survey from the dropdown menu on the top-right and a "Create new survey" screen will appear.


You can edit all of these settings later again by choosing your survey and clicking General settings & texts in the 'Survey properties' dropdown menu of the survey toolbar.

=Settings= 


All survey settings and functions are organized in tabs. The following is a description of each tab and field.

==General== 
#'''Base language''': This sets the base language for the survey. Once saved, you cannot change it later. The language-set is the base language for possible translations of the survey. That way you can have multilingual surveys. During survey creation you cannot add additional languages. You will be able do that if you edit the survey properties again, later.
#'''Additional languages''': To choose additional language. <span class="alert">Only available when survey is created.</span>
#'''Title''': This is the brief descriptive name of the survey (ie: "Enterprise Bargaining Survey 2003", or "Views on Ice Cream"). This title will be displayed on every page of the public survey.
#'''Description''': This allows you to enter a description of the survey. (ie: "A survey to collect your ideas on the next round of enterprise bargaining" or "A survey to find out the popularity of chocolate ice cream"). You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor. By default, description is used on invitation email.
#'''Welcome message''': This allows you to enter a message that will display when a participant first logs into your survey. (ie: "Thank you for taking the time to participate in this survey..") You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor.<span class="alert">Only available at survey creation. After available in Edit survey text elements</span>
#'''End message''': This allows you to enter a message that will display when a participant completes your survey. (ie: "Thank you for completing our survey. We will publish results soon."). You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor.<span class="alert">Only available at survey creation. After survey creation, it is available in Edit survey text elements</span>
#'''End URL''': This URL will be presented as a link at the end of the survey, and allows you to direct your participants back to your home page (or, in fact, anywhere). The End URL has to be entered with "http://" at the beginning, eg. http://www.limesurvey.org. <br />You can use they placeholder {SAVEDID}, {TOKEN}, {SID} and {LANG} in this URL.<br />SAVEDID is the id assigned to this particular submission, TOKEN is the token used to participate in the survey, SID is the survey ID and LANG is the language code<br />eg. http://www.limesurvey.org/test.php?var1={SAVEDID}&var2;={TOKEN}&var3;={SID}&lang;={LANG} <br />From version 1.82+ you can use [[URL fields]] with this field to pass parameters from the start URL to then end URL. <br />You can also use {INSERTANS:SGQA} in this URL (since 1.82+). This allows adding the response to a specific question in the survey to the final url. This can be useful for sending a response to an external script (ie an email address collected during the survey). eg: "http://www.limesurvey.org/test.php?email={INSERTANS:1234X56X7}".<span class="alert">Only available at survey creation. After available in Edit survey text elements</span>
#'''URL description''': The description for the link using the End URL.<span class="alert">Only available at survey creation. After available in Edit survey text elements</span>
#'''Administrator''': This is the name of the contact person who administers the survey. It will be included in emails sent out inviting participants to respond.
#'''Admin email''': This is the email address of the administrator (as above) and is used as the 'From:' address on any emails sent.<br />NOTE: many hosting providers' SMTP servers will only accept emails whose 'From:' address is on a local domain, with the added difficulty that any emails that do not conform to this rule are discarded silently, without any visible error message. If this happens to you, ensure that you are using a provider-based email address in the 'Admin email' field. You usually can, if you so desire, set up email forwarding on the provider's side, so that any messages sent there are relayed to your preferred address.
#'''Bounce email''': This is the email address where a delivery error notification email should be sent. By default, this is the same as the administrator's email address. If you want to use a custom script to parse delivery error emails, then use a special Bounce Email address here and automatically process emails reaching this address with your script. This script could then update the Email Status field of the token line corresponding to this email address (see tokens).
#'''Fax to''': This field is used to give a fax number on the "printable survey" - ie: when you want to send someone a hard copy because they cannot use the online survey.


<div class="simplebox">'''Caution''': the HTML WYSIWYG editor doesn't allow you to upload files during the survey creation process. Trying to do so will end up with an error message like: "''This file uploader is disabled''". If you need to upload pictures or any other ressources, please do so after survey creation, by editing the newly created survey.</div>

==Presentation & navigation== 


[[File:Survey-settings_presentation-navigation_tab.png]]


#'''Format''': Choose from "Question by question", "Group by group" or "All in one".
#*'''Question by Question''': Public survey will display one question per page.
#*'''Group by Group''': Public survey will display all questions in a group per page. Group at a time surveys still have a separate "welcome" page and "submit" page, like "Question by Question" surveys.
#*'''All in one''': Public survey will display all questions in one single page. Activated All in one surveys do not have a "welcome" page or "submit" page - the welcome message and submit button all appear on the same page.
#'''Template''': Choose from the installed templates in your system. The default template is rather dull, but functional. More information on creating your own templates is available [[The template editor|here]].
#'''Show welcome screen''': Yes/No. If Yes, then the welcome message defined in Text Elements section will be displayed. Default is Yes.
#'''Navigation delay''': Number of seconds before Previous and Next buttons are enabled. Default 0 seconds
#'''Show <nowiki>[</nowiki><< Prev] button''': This option defaults to yes, however if you set it to "No" then users will not have the option of moving to a previous page while completing the survey.
#'''Show question index / allow jumping''': Yes/No. Default No. When Yes, an index will be displayed on the right side. Users can jump to any section in the survey. In 2.05 the options have changed to Disabled / Incremental / Full. Disabled and Incremental represent the current No and Yes options. Full always shows all groups / questions, this allows the user to freely navigate through the survey. This might not work for all kinds of conditions.
#'''Keyboard-less operation''': By activating this setting there will be a virtual keyboard available for certain question types.
#'''Show progress bar''': Yes/No. Default Yes. Allow the administrator to turn off the Progress bar
#'''Participants may print answers?''': This option defaults to no. When it is set to yes, a participant can print a summary of responses at submit time.
#'''Public statistics''': Yes/No. Default No. If set to "Yes" users who have submitted the survey will be presented a link to statistics of the current survey. The admin can set which questions should be included at these statistics by [[Advanced question settings#public_statistics|applying the according question attribute]].
#'''Show graphs in public statistics''': (''since 1.80'') Determines if public statistics for this survey include graphs or only show a tabular overview. Creating graphs for huge surveys with lots of answers takes some time and server resources so this is the switch to turn them on/off (default setting: ''off'').
#'''Automatically load URL when survey complete''': Yes/No. Default No. If yes, when the survey is submitted, it will automatically redirect to the End URL. The end URL can be defined in the Text Elements Section. Please note that this only works on an active survey.
#'''Show "There are X questions in this survey"''': Yes/No. Default Yes. If Yes, the message will be displayed on the Welcome Screen. This option will not affect the print version.
#'''Show group name and/or group description''': Will control the display of Group Names and Descriptions. This option will not affect the print version. Four Options:
#*'''Show Both''' - Default
#*'''Show Group Names Only'''
#*'''Show group description Only'''
#*'''Hide Both'''
#'''Show question number and/or code''':
#*'''Show Both''' - Default
#*'''Show Question Number Only'''
#*'''Show Question Code Only'''
#*'''Hide Both'''
#'''Show "No answer"''': Yes/No. Default Yes. When Yes, the No Answer will be displayed as the default option for non-mandatory single-select questions. Be aware that if you switch this off, the participant won't be able to unselect a chosen answer option in a non-mandatory question.

==Publication & access control== 
#'''List survey publicly''': Yes/No. Default No. When it is set to yes, your survey will be listed in the 'available surveys' portal
# '''Start date/time''': Set this to some date if you want your survey to start on a certain date. The survey will start on midnight of that day and only then will people be able to answer to it. To disable this just clear the date from the input field.
#'''Expiry date/time''': Set this to some date if you want your survey to expire on a special date. This is the last date on which the public survey script will let people participate. (Example: If you set it for the 31st of December, then people will no longer be able to use the survey script on the 1st of January). To disable this just clear the date from the input field.
#'''Set cookie to prevent repeated participation?''': If you set this to 'Yes', and your survey does not use a tokens table to control participant access, then a cookie will be saved to the client computer of each survey participant once they have submitted a survey. This cookie will stop the same user on that computer from accessing the survey more than once. There are inherent limitations in the 'security' strength of such a system, but, in general, it allows you to retain some control over multiple entries on public surveys.
#'''Use CAPTCHA for''': With this option you can decide when you want a CAPTCHA to be used. Default is to enable CAPTCHA only for the public Registration page, but you can also enable it before accessing the survey, and before Load/Saving partial answers.

==Notification & data management== 


[[File:Survey-settings_notifications-tab.png]]


#'''Send basic admin notification email to:''' and '''Send detailed admin notification email to:''' These fields allow you to send notifications or survey responses to any email addresses once the survey is submitted. You can edit the templates for these emails under 'Email templates'. Multiple recipients can be set by separating the entries with a semicolon (;) - eg "yourname@test.com; myname@test.com;hisname@test.com" OR when using placeholders "yourname@test.com;{INSERTANS:82733X12X73};{TOKEN:EMAIL}". To sedn an email to the administrator email of the survey : you must use {ADMINEMAIL}. There are different ways for entering an address:
##Enter a specific ''email address'' (ie: yourname@test.com)
##Enter a ''SGQA code'' and the response will be sent to an email address entered as an answer to that particular question (use the format {INSERTANS:9999X88X12}, in the same way you would [[Adding a question#Information from previous answers|Re-use information from previous answers]])
##Enter a ''Token code'' (only possible if your survey is ''not'' anonymous) and the response will be sent to an email address retrieved from a token field (use the format {TOKEN:EMAIL} or {TOKEN:ATTRIBUTE_1} in the same way you would [[Adding a question#Information from tokens table|Re-use Information from the Tokens Table]])
##''As of Version 1.92:'' Enter a valid expression conforming to [[Expression Manager|Expression Manager]] syntax. This lets you use question code instead of SGQA syntax (for easier readability), plus conditional logic (e.g. route the notifications to different people depending upon the data entered into the survey).
#'''Date stamp?''': This field allows you to determine whether the survey will datestamp all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response indicating the time and date that the response was made. (See configuration settings for $timeadjust setting.)
#'''Save IP address?''': This field allows you to determine whether the survey will save an IP-address for all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response indicating the ip-address of the participant.
#'''Save referrer URL?''': This field allows you to determine whether the survey will save the referrer URL for all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response where this URL is saved. A referrer URL is the URL from which the user was led to your survey URL.
#'''Enable assessment mode?''': With this setting you can enable/disable [[Assessments|assessments]] for this survey.
#'''Save timings''': If activate then on survey activation a separate table will be created where timings for your questions will be saved, e.g. how long a user stays on one page during taking the survey.
#'''Participant may save and resume later?''': This setting allows a participant to save his responses and resume to answer the survey at a later time. Please note that this makes most sense with open surveys or surveys with anonymized answer. If you are using tokens and the survey is not anonymous in most cases it is better to activate 'Token-based response persistence' in the token tab.
#'''Google Analytics Tracking ID for this survey''': Allows for integration with Google Analytics. The tracking ID can be inserted into templates using {GOOGLE_ANALYTICS_API_KEY}. The full JavaScript that Google Analytics expects (including the key) can be included in templates via {GOOGLE_ANALYTICS_JAVASCRIPT}
#'''Google Analytics Style for this Survey''': Choices are:
##'''Do not use Google Analytics''' - so {GOOGLE_ANALYTICS_JAVASCRIPT} is an empty string
##'''Default Google Analytics''' - {GOOGLE_ANALYTICS_JAVASCRIPT} uses the standard Google Analytics code, inserting the proper Google Analytics Key
##'''SurveyName-<nowiki>[</nowiki>SID]/GroupName''' - {GOOGLE_ANALYTICS_JAVASCRIPT} contains customized Google Analytics code to log the URL as {SURVEYNAME}-<nowiki>[</nowiki>{SID}]/{GROUPNAME}. This can be helpful if you want to analyze navigation paths through your survey, time spent per page, and drop-off rates per page.


'''Google API howto''':
# Register/login on Google Analytics (GA): [http://www.google.com/analytics/ www.google.com/analytics/]
# Create a tracking ID (the site should not point to the survey, but to the part before 'index.php?') The tracking ID should be UA-xxxxx.
# Go to your survey's global settings in LimeSurvey.
# Put the tracking ID in appropriate field (Google Analytics tracking ID). It's probably the best to set GA style to track all pages as you can have more info.
# You don't need to do anything in shipped templates, as the {GOOGLE_ANALYTICS_JAVASCRIPT} part is already there.
# Activate the survey.
# Do the survey.
# Go to GA panel mainsite. (select appropriate account in left-hand upper corner if you have more than one). You should see some graphs with the statistics. Beware of the dates in upper right corner.

==Tokens== 


*'''Anonymized responses?''': This allows you to determine whether responses to your survey are matched up with information from your surveys tokens table, or kept 'anonymous'. The default is 'No'. If you choose 'Yes' then your survey is set to radically anonymize responses - there is really no way to connect answers and participants. Even the admin can't link response data and participant/token data. However you will always be able to specifically view each response entered by your participants in the survey. Thus individual, but anonymous, statistics is still possible to do. '''''Attention:''''': If this feature is activated the response submission date and the token completed date are always set to 1980-01-01 00:00, no matter of other settings. Why? Invalidating the submission date ensures no match with webserver logs where the token key might show up when a survey is started. Invalidating the token completed date makes sure that you can't align the order of submitted responses to the order of the token date/time.


*'''Enable token-based response persistence''': If your survey uses tokens and your responses are not anonymized, you may want to enable this feature. If you turn this on, your participants will be able to leave the survey and resume later at any time without using the 'Resume later' function - for example if they get distracted or their browser crashes. Upon clicking the invitation link again, they will find their survey answers still in place when they return to the survey, and will even find themselves on the same page where they were before leaving.


*'''Allow multiple responses or update responses with one token?''': Default: No. If you activate this setting, participants will be able to return to their survey by clicking the invitation link, even if they have already submitted the survey. If the survey is anonymous or "Enable token-based response persistence" is set to NO, this will add a new response. If the survey is not anonymous and "Enable token-based response persistence" is Yes, the user will update the existing responses.


*'''Allow public registration''': If you use tokens to control access to your survey, the only people who can use the survey are those who have an entry and a unique token from the token table. If you would like to use tokens, but also allow public registration, set this to "Yes". The "Yes" setting will allow a visitor to register his name and email address. The script will create a new entry in your tokens table for this person, then send them an invitation email. The script will ensure that only one person per email address can complete your survey.


*'''Use HTML format for token emails?''': When set to yes, all emails sent by the token management interface (invite, reminder, confirmation) will be formatted as HTML. You'll then be able to use rich formatting for this emails. Default is Yes at survey creation. Caution, when you switch on/off this feature, you'll have to double check that your email templates are still displayed as you want.


*'''Set token length to''': Usually you don't need to change this, the default setting of 15 digits (max. supported value: 35) is fine. If changing this setting please enter a number (X) which should be greater than 5 (if the number entered is <5 it will be converted to the default value of 15). When generating tokens all tokens will use a length of X digits.

==Import== 


Alternatively you can [[Importing a survey structure|import a survey structure]] from this tab on survey creation. You have the option to let LimeSurvey automatically convert relative URLs to local images/media files and INSERTANS tags (recommended).

==Copy== 


Alternatively you can copy an existing survey from this tab on survey creation. You have the option to let LimeSurvey automatically convert relative URLs to local images/media files and INSERTANS tags (recommended). The other options are pretty self-explaining. Please note that when copying a survey the start date and the end date of a survey cleared.

==Panel integration (URL parameters)== 


<div class="simplebox"> Please note that this tab is currently not visible on survey creation but only when you edit the survey settings after saving them for the first time.</div>


On this tab you can set which additional URL parameters will be accepted by your survey (these parameters would be attached to the general survey start URL). This is important if you integrate with a professional survey panel provider that provides the participants for your survey. They usually hand over a unqiue ID with every participant and you will need to save/handle this unique ID for reference. Also with some providers the unique ID of the participant (bdropping out due to quota or finishing the survey) needs to be sent back to the panel provider in the survey end URL.


If you like you can also save the value as a response of a "Short text question" or "Multiple short text question" type (you will be able to select any short text question to save it to). Even if you do NOT save the value of the URL parameter you will be able to use this parameter in the end URL. Please have a look at the documentation of the [[URL_fields#Passthrough_fields_.28LimeSurvey_2.x_or_later.29|End-URL]] for further information.

==Resources== 


This tab lets you manage files (pictures, media files) that were uploaded in the HTML Editor and it is only visible if you edit a survey - not during survey creation.


You can:
* Browse available files
* Export files as a ZIP archive
* Import a ZIP archive of files


Important hints:
* Authorized files extensions are defined in config-defaults.php.
* Files for the survey are in the upload/surveys/<sid> subdirectory.
* Uploaded files will only been seen while browsing resources on this survey (groups, questions, answers) not in other surveys or objects (labels).
* Do not expect this limited visibility to ensure confidentiality of the resources as they are reachable with a simple browser to anyone who know the URL to the file.
* You can't import a ZIP file containing subdirectories.

=Additional languages= 


To add more languages to a survey you have to create and save it - then edit it again. Now you can add and remove additional languages to the survey. If you remove a language from a survey the complete contents of that language in that survey is deleted permanently so be careful what you are doing.


By clicking on the button 'Save and continue' on the first page in the survey settings you will be taken to the language-specific page which lets you change all texts for each language like ''Survey name'', ''Welcome Text'', etc. You can also edit the date format which should be used for a certain language.

</translate>

Survey settings

2017-09-05T13:26:45Z

LimeAJ:

<languages />
<translate>


__TOC__

=Overview= 


Some of these settings can be set when creating a new survey. Click on the Add quick-button [[File:Btn_create_survey.png|100px]] or choose Survey/Create a new survey from the dropdown menu on the top-right and a "Create new survey" screen will appear.


You can edit all of these settings later again by choosing your survey and clicking General settings & texts in the 'Survey properties' dropdown menu of the survey toolbar.

=Settings= 


All survey settings and functions are organized in tabs. The following is a description of each tab and field.

==General== 
#'''Base language''': This sets the base language for the survey. Once saved, you cannot change it later. The language-set is the base language for possible translations of the survey. That way you can have multilingual surveys. During survey creation you cannot add additional languages. You will be able do that if you edit the survey properties again, later.
#'''Additional languages''': To choose additional language. <span class="alert">Only available when survey is created.</span>
#'''Title''': This is the brief descriptive name of the survey (ie: "Enterprise Bargaining Survey 2003", or "Views on Ice Cream"). This title will be displayed on every page of the public survey.
#'''Description''': This allows you to enter a description of the survey. (ie: "A survey to collect your ideas on the next round of enterprise bargaining" or "A survey to find out the popularity of chocolate ice cream"). You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor. By default, description is used on invitation email.
#'''Welcome message''': This allows you to enter a message that will display when a participant first logs into your survey. (ie: "Thank you for taking the time to participate in this survey..") You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor.<span class="alert">Only available at survey creation. After available in Edit survey text elements</span>
#'''End message''': This allows you to enter a message that will display when a participant completes your survey. (ie: "Thank you for completing our survey. We will publish results soon."). You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor.<span class="alert">Only available at survey creation. After available in Edit survey text elements</span>
#'''End URL''': This URL will be presented as a link at the end of the survey, and allows you to direct your participants back to your home page (or, in fact, anywhere). The End URL has to be entered with "http://" at the beginning, eg. http://www.limesurvey.org. <br />You can use they placeholder {SAVEDID}, {TOKEN}, {SID} and {LANG} in this URL.<br />SAVEDID is the id assigned to this particular submission, TOKEN is the token used to participate in the survey, SID is the survey ID and LANG is the language code<br />eg. http://www.limesurvey.org/test.php?var1={SAVEDID}&var2;={TOKEN}&var3;={SID}&lang;={LANG} <br />From version 1.82+ you can use [[URL fields]] with this field to pass parameters from the start URL to then end URL. <br />You can also use {INSERTANS:SGQA} in this URL (since 1.82+). This allows adding the response to a specific question in the survey to the final url. This can be useful for sending a response to an external script (ie an email address collected during the survey). eg: "http://www.limesurvey.org/test.php?email={INSERTANS:1234X56X7}".<span class="alert">Only available at survey creation. After available in Edit survey text elements</span>
#'''URL description''': The description for the link using the End URL.<span class="alert">Only available at survey creation. After available in Edit survey text elements</span>
#'''Administrator''': This is the name of the contact person who administers the survey. It will be included in emails sent out inviting participants to respond.
#'''Admin email''': This is the email address of the administrator (as above) and is used as the 'From:' address on any emails sent.<br />NOTE: many hosting providers' SMTP servers will only accept emails whose 'From:' address is on a local domain, with the added difficulty that any emails that do not conform to this rule are discarded silently, without any visible error message. If this happens to you, ensure that you are using a provider-based email address in the 'Admin email' field. You usually can, if you so desire, set up email forwarding on the provider's side, so that any messages sent there are relayed to your preferred address.
#'''Bounce email''': This is the email address where a delivery error notification email should be sent. By default, this is the same as the administrator's email address. If you want to use a custom script to parse delivery error emails, then use a special Bounce Email address here and automatically process emails reaching this address with your script. This script could then update the Email Status field of the token line corresponding to this email address (see tokens).
#'''Fax to''': This field is used to give a fax number on the "printable survey" - ie: when you want to send someone a hard copy because they cannot use the online survey.


<div class="simplebox">'''Caution''': the HTML WYSIWYG editor doesn't allow you to upload files during the survey creation process. Trying to do so will end up with an error message like: "''This file uploader is disabled''". If you need to upload pictures or any other ressources, please do so after survey creation, by editing the newly created survey.</div>

==Presentation & navigation== 


[[File:Survey-settings_presentation-navigation_tab.png]]


#'''Format''': Choose from "Question by question", "Group by group" or "All in one".
#*'''Question by Question''': Public survey will display one question per page.
#*'''Group by Group''': Public survey will display all questions in a group per page. Group at a time surveys still have a separate "welcome" page and "submit" page, like "Question by Question" surveys.
#*'''All in one''': Public survey will display all questions in one single page. Activated All in one surveys do not have a "welcome" page or "submit" page - the welcome message and submit button all appear on the same page.
#'''Template''': Choose from the installed templates in your system. The default template is rather dull, but functional. More information on creating your own templates is available [[The template editor|here]].
#'''Show welcome screen''': Yes/No. If Yes, then the welcome message defined in Text Elements section will be displayed. Default is Yes.
#'''Navigation delay''': Number of seconds before Previous and Next buttons are enabled. Default 0 seconds
#'''Show <nowiki>[</nowiki><< Prev] button''': This option defaults to yes, however if you set it to "No" then users will not have the option of moving to a previous page while completing the survey.
#'''Show question index / allow jumping''': Yes/No. Default No. When Yes, an index will be displayed on the right side. Users can jump to any section in the survey. In 2.05 the options have changed to Disabled / Incremental / Full. Disabled and Incremental represent the current No and Yes options. Full always shows all groups / questions, this allows the user to freely navigate through the survey. This might not work for all kinds of conditions.
#'''Keyboard-less operation''': By activating this setting there will be a virtual keyboard available for certain question types.
#'''Show progress bar''': Yes/No. Default Yes. Allow the administrator to turn off the Progress bar
#'''Participants may print answers?''': This option defaults to no. When it is set to yes, a participant can print a summary of responses at submit time.
#'''Public statistics''': Yes/No. Default No. If set to "Yes" users who have submitted the survey will be presented a link to statistics of the current survey. The admin can set which questions should be included at these statistics by [[Advanced question settings#public_statistics|applying the according question attribute]].
#'''Show graphs in public statistics''': (''since 1.80'') Determines if public statistics for this survey include graphs or only show a tabular overview. Creating graphs for huge surveys with lots of answers takes some time and server resources so this is the switch to turn them on/off (default setting: ''off'').
#'''Automatically load URL when survey complete''': Yes/No. Default No. If yes, when the survey is submitted, it will automatically redirect to the End URL. The end URL can be defined in the Text Elements Section. Please note that this only works on an active survey.
#'''Show "There are X questions in this survey"''': Yes/No. Default Yes. If Yes, the message will be displayed on the Welcome Screen. This option will not affect the print version.
#'''Show group name and/or group description''': Will control the display of Group Names and Descriptions. This option will not affect the print version. Four Options:
#*'''Show Both''' - Default
#*'''Show Group Names Only'''
#*'''Show group description Only'''
#*'''Hide Both'''
#'''Show question number and/or code''':
#*'''Show Both''' - Default
#*'''Show Question Number Only'''
#*'''Show Question Code Only'''
#*'''Hide Both'''
#'''Show "No answer"''': Yes/No. Default Yes. When Yes, the No Answer will be displayed as the default option for non-mandatory single-select questions. Be aware that if you switch this off, the participant won't be able to unselect a chosen answer option in a non-mandatory question.

==Publication & access control== 
#'''List survey publicly''': Yes/No. Default No. When it is set to yes, your survey will be listed in the 'available surveys' portal
# '''Start date/time''': Set this to some date if you want your survey to start on a certain date. The survey will start on midnight of that day and only then will people be able to answer to it. To disable this just clear the date from the input field.
#'''Expiry date/time''': Set this to some date if you want your survey to expire on a special date. This is the last date on which the public survey script will let people participate. (Example: If you set it for the 31st of December, then people will no longer be able to use the survey script on the 1st of January). To disable this just clear the date from the input field.
#'''Set cookie to prevent repeated participation?''': If you set this to 'Yes', and your survey does not use a tokens table to control participant access, then a cookie will be saved to the client computer of each survey participant once they have submitted a survey. This cookie will stop the same user on that computer from accessing the survey more than once. There are inherent limitations in the 'security' strength of such a system, but, in general, it allows you to retain some control over multiple entries on public surveys.
#'''Use CAPTCHA for''': With this option you can decide when you want a CAPTCHA to be used. Default is to enable CAPTCHA only for the public Registration page, but you can also enable it before accessing the survey, and before Load/Saving partial answers.

==Notification & data management== 


[[File:Survey-settings_notifications-tab.png]]


#'''Send basic admin notification email to:''' and '''Send detailed admin notification email to:''' These fields allow you to send notifications or survey responses to any email addresses once the survey is submitted. You can edit the templates for these emails under 'Email templates'. Multiple recipients can be set by separating the entries with a semicolon (;) - eg "yourname@test.com; myname@test.com;hisname@test.com" OR when using placeholders "yourname@test.com;{INSERTANS:82733X12X73};{TOKEN:EMAIL}". To sedn an email to the administrator email of the survey : you must use {ADMINEMAIL}. There are different ways for entering an address:
##Enter a specific ''email address'' (ie: yourname@test.com)
##Enter a ''SGQA code'' and the response will be sent to an email address entered as an answer to that particular question (use the format {INSERTANS:9999X88X12}, in the same way you would [[Adding a question#Information from previous answers|Re-use information from previous answers]])
##Enter a ''Token code'' (only possible if your survey is ''not'' anonymous) and the response will be sent to an email address retrieved from a token field (use the format {TOKEN:EMAIL} or {TOKEN:ATTRIBUTE_1} in the same way you would [[Adding a question#Information from tokens table|Re-use Information from the Tokens Table]])
##''As of Version 1.92:'' Enter a valid expression conforming to [[Expression Manager|Expression Manager]] syntax. This lets you use question code instead of SGQA syntax (for easier readability), plus conditional logic (e.g. route the notifications to different people depending upon the data entered into the survey).
#'''Date stamp?''': This field allows you to determine whether the survey will datestamp all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response indicating the time and date that the response was made. (See configuration settings for $timeadjust setting.)
#'''Save IP address?''': This field allows you to determine whether the survey will save an IP-address for all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response indicating the ip-address of the participant.
#'''Save referrer URL?''': This field allows you to determine whether the survey will save the referrer URL for all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response where this URL is saved. A referrer URL is the URL from which the user was led to your survey URL.
#'''Enable assessment mode?''': With this setting you can enable/disable [[Assessments|assessments]] for this survey.
#'''Save timings''': If activate then on survey activation a separate table will be created where timings for your questions will be saved, e.g. how long a user stays on one page during taking the survey.
#'''Participant may save and resume later?''': This setting allows a participant to save his responses and resume to answer the survey at a later time. Please note that this makes most sense with open surveys or surveys with anonymized answer. If you are using tokens and the survey is not anonymous in most cases it is better to activate 'Token-based response persistence' in the token tab.
#'''Google Analytics Tracking ID for this survey''': Allows for integration with Google Analytics. The tracking ID can be inserted into templates using {GOOGLE_ANALYTICS_API_KEY}. The full JavaScript that Google Analytics expects (including the key) can be included in templates via {GOOGLE_ANALYTICS_JAVASCRIPT}
#'''Google Analytics Style for this Survey''': Choices are:
##'''Do not use Google Analytics''' - so {GOOGLE_ANALYTICS_JAVASCRIPT} is an empty string
##'''Default Google Analytics''' - {GOOGLE_ANALYTICS_JAVASCRIPT} uses the standard Google Analytics code, inserting the proper Google Analytics Key
##'''SurveyName-<nowiki>[</nowiki>SID]/GroupName''' - {GOOGLE_ANALYTICS_JAVASCRIPT} contains customized Google Analytics code to log the URL as {SURVEYNAME}-<nowiki>[</nowiki>{SID}]/{GROUPNAME}. This can be helpful if you want to analyze navigation paths through your survey, time spent per page, and drop-off rates per page.


'''Google API howto''':
# Register/login on Google Analytics (GA): [http://www.google.com/analytics/ www.google.com/analytics/]
# Create a tracking ID (the site should not point to the survey, but to the part before 'index.php?') The tracking ID should be UA-xxxxx.
# Go to your survey's global settings in LimeSurvey.
# Put the tracking ID in appropriate field (Google Analytics tracking ID). It's probably the best to set GA style to track all pages as you can have more info.
# You don't need to do anything in shipped templates, as the {GOOGLE_ANALYTICS_JAVASCRIPT} part is already there.
# Activate the survey.
# Do the survey.
# Go to GA panel mainsite. (select appropriate account in left-hand upper corner if you have more than one). You should see some graphs with the statistics. Beware of the dates in upper right corner.

==Tokens== 


*'''Anonymized responses?''': This allows you to determine whether responses to your survey are matched up with information from your surveys tokens table, or kept 'anonymous'. The default is 'No'. If you choose 'Yes' then your survey is set to radically anonymize responses - there is really no way to connect answers and participants. Even the admin can't link response data and participant/token data. However you will always be able to specifically view each response entered by your participants in the survey. Thus individual, but anonymous, statistics is still possible to do. '''''Attention:''''': If this feature is activated the response submission date and the token completed date are always set to 1980-01-01 00:00, no matter of other settings. Why? Invalidating the submission date ensures no match with webserver logs where the token key might show up when a survey is started. Invalidating the token completed date makes sure that you can't align the order of submitted responses to the order of the token date/time.


*'''Enable token-based response persistence''': If your survey uses tokens and your responses are not anonymized, you may want to enable this feature. If you turn this on, your participants will be able to leave the survey and resume later at any time without using the 'Resume later' function - for example if they get distracted or their browser crashes. Upon clicking the invitation link again, they will find their survey answers still in place when they return to the survey, and will even find themselves on the same page where they were before leaving.


*'''Allow multiple responses or update responses with one token?''': Default: No. If you activate this setting, participants will be able to return to their survey by clicking the invitation link, even if they have already submitted the survey. If the survey is anonymous or "Enable token-based response persistence" is set to NO, this will add a new response. If the survey is not anonymous and "Enable token-based response persistence" is Yes, the user will update the existing responses.


*'''Allow public registration''': If you use tokens to control access to your survey, the only people who can use the survey are those who have an entry and a unique token from the token table. If you would like to use tokens, but also allow public registration, set this to "Yes". The "Yes" setting will allow a visitor to register his name and email address. The script will create a new entry in your tokens table for this person, then send them an invitation email. The script will ensure that only one person per email address can complete your survey.


*'''Use HTML format for token emails?''': When set to yes, all emails sent by the token management interface (invite, reminder, confirmation) will be formatted as HTML. You'll then be able to use rich formatting for this emails. Default is Yes at survey creation. Caution, when you switch on/off this feature, you'll have to double check that your email templates are still displayed as you want.


*'''Set token length to''': Usually you don't need to change this, the default setting of 15 digits (max. supported value: 35) is fine. If changing this setting please enter a number (X) which should be greater than 5 (if the number entered is <5 it will be converted to the default value of 15). When generating tokens all tokens will use a length of X digits.

==Import== 


Alternatively you can [[Importing a survey structure|import a survey structure]] from this tab on survey creation. You have the option to let LimeSurvey automatically convert relative URLs to local images/media files and INSERTANS tags (recommended).

==Copy== 


Alternatively you can copy an existing survey from this tab on survey creation. You have the option to let LimeSurvey automatically convert relative URLs to local images/media files and INSERTANS tags (recommended). The other options are pretty self-explaining. Please note that when copying a survey the start date and the end date of a survey cleared.

==Panel integration (URL parameters)== 


<div class="simplebox"> Please note that this tab is currently not visible on survey creation but only when you edit the survey settings after saving them for the first time.</div>


On this tab you can set which additional URL parameters will be accepted by your survey (these parameters would be attached to the general survey start URL). This is important if you integrate with a professional survey panel provider that provides the participants for your survey. They usually hand over a unqiue ID with every participant and you will need to save/handle this unique ID for reference. Also with some providers the unique ID of the participant (bdropping out due to quota or finishing the survey) needs to be sent back to the panel provider in the survey end URL.


If you like you can also save the value as a response of a "Short text question" or "Multiple short text question" type (you will be able to select any short text question to save it to). Even if you do NOT save the value of the URL parameter you will be able to use this parameter in the end URL. Please have a look at the documentation of the [[URL_fields#Passthrough_fields_.28LimeSurvey_2.x_or_later.29|End-URL]] for further information.

==Resources== 


This tab lets you manage files (pictures, media files) that were uploaded in the HTML Editor and it is only visible if you edit a survey - not during survey creation.


You can:
* Browse available files
* Export files as a ZIP archive
* Import a ZIP archive of files


Important hints:
* Authorized files extensions are defined in config-defaults.php.
* Files for the survey are in the upload/surveys/<sid> subdirectory.
* Uploaded files will only been seen while browsing resources on this survey (groups, questions, answers) not in other surveys or objects (labels).
* Do not expect this limited visibility to ensure confidentiality of the resources as they are reachable with a simple browser to anyone who know the URL to the file.
* You can't import a ZIP file containing subdirectories.

=Additional languages= 


To add more languages to a survey you have to create and save it - then edit it again. Now you can add and remove additional languages to the survey. If you remove a language from a survey the complete contents of that language in that survey is deleted permanently so be careful what you are doing.


By clicking on the button 'Save and continue' on the first page in the survey settings you will be taken to the language-specific page which lets you change all texts for each language like ''Survey name'', ''Welcome Text'', etc. You can also edit the date format which should be used for a certain language.

</translate>

RemoteControl 2 API

2017-08-29T18:02:07Z

LimeAJ: /* PHP Example */

__TOC__

=Introduction=

LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or more recent which offers '''various [https://api.limesurvey.org/classes/remotecontrol_handle.html API functions]'''.

LSRC2 makes it possible for developers to control specific functionality of LimeSurvey from any other application, without being restricted to PHP as a programming language.

The following features are planned:
* start a predefined survey (change titles and things)
* add predefined groups or questions
* activate the survey, restrict it to start and endtime
* make it closed,
* add participant data/tokens when you need them
* return the unused tokens to the main application
* get a fieldmap for a survey,
* invite or remind the participants of your survey

...and much more

==Requirements==
* libXML installed

=Setup=

== How to configure LSRC2==

In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to [[Global settings]], choose the tab 'Interfaces' and select one of the two RPC services (XML-RPC or JSON-RPC) service.

== Security==

LSRC2 uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also LSRC2 is protected against brute-force password cracking - like the normal administration login.

=How to use LSRC2=

The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol

LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC version 1 specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.

LSRC2 offers a lot of functions. Please check the automatically generated [http://api.limesurvey.org/classes/remotecontrol_handle.html API Documentation].
LSRC2 offers the following functions:

== Sessions ==

=== get_session_key ===

Using this function you can create a new XML/JSON-RPC session key. This is mandatory for all following LSRC2 function calls.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''Return on success''': (string) session key.

'''Return on error''': for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.

=== release_session_key ===

Using this function you can close a previously opened XML-RPC/JSON-RPC session.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Other functions ==

{{Alert|For all other function , you have to refer to the [http://api.limesurvey.org/classes/remotecontrol_handle.html online API ] . If your LimeSurvey version is outdated, you can publish your API and look at it directly.}}

= Example and helper =

== PHP Example ==

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository]. The library can also get included [https://getcomposer.org/download/ by composer calling]

<source lang=bash>
composer require weberhofer/jsonrpcphp
</source>

or by inclusion of the following lines in your composer.json file:

<source lang=javascript>
{
"require": {
"weberhofer/jsonrpcphp": "~2"
}
}
</source>

This is an example how to connect to limesurvey:

<source lang="php">
<?php

// without composer this line can be used
// require_once 'path/to/your/rpcclient/jsonRPCClient.php';
// with composer support just add the autoloader
include_once 'vendor/autoload.php';

define( 'LS_BASEURL', 'https://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL
define( 'LS_USER', 'rpcuser' );
define( 'LS_PASSWORD', 'mypassword' );

// the survey to process
$survey_id=374699;

// instantiate a new client
$myJSONRPCClient = new \org\jsonrpcphp\JsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );

// receive session key
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );

// receive all ids and info of groups belonging to a given survey
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );
print_r($groups, null );

// release the session key
$myJSONRPCClient->release_session_key( $sessionKey );

</source>

== JAVA example ==
To decode and code your json calls you can use the library gson as you can see in the following example:

<syntaxhighlight lang="java" enclose="div">
import java.io.IOException;
import java.io.UnsupportedEncodingException;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class TestHttpClient {

public static String parse(String jsonLine) {
JsonElement jelement = new JsonParser().parse(jsonLine);
JsonObject jobject = jelement.getAsJsonObject();
String result = jobject.get("result").getAsString();
return result;
}

public static void main(String[] args) throws UnsupportedEncodingException {
DefaultHttpClient client = new DefaultHttpClient();

HttpPost post = new HttpPost("https://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");
post.setHeader("Content-type", "application/json");
post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": [\"YOUR_USERNAME\", \"YOUR_PASSWORD\" ], \"id\": 1}"));
try {
HttpResponse response = client.execute(post);
if(response.getStatusLine().getStatusCode() == 200){
HttpEntity entity = response.getEntity();
String sessionKey = parse(EntityUtils.toString(entity));
post.setEntity( new StringEntity("{\"method\": \"list_groups\", \"params\": [ \""+sessionKey+"\", \"ID_SURVEY\" ], \"id\": 1}"));
response = client.execute(post);
if(response.getStatusLine().getStatusCode() == 200){
entity = response.getEntity();
System.out.println(EntityUtils.toString(entity));
}
}

} catch (IOException e) {
e.printStackTrace();
}
}}

</syntaxhighlight>

== Python example and glue ==

* [https://github.com/TaiSHiNet/lime-py-api LimeSurvey API - Python 2 glue]
* [https://github.com/lindsay-stevens/limesurveyrc2api LimeSurvey API - Basic client library in Python 3]. Includes tests. Listed on Pypi: pip install limesurveyrc2api

The following code runs with Python 2 and requires some adaptation to work with Python 3.

<syntaxhighlight lang="python" enclose="div">
import urllib
import urllib2
import json
import sys
# There is an generic json-rpc implemantation in Python but it dose not work for me in this case so I worte Some functions

def get_session_key():
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"get_session_key\",\"params\":[\"admin\",\"mypassword\"],\"id\":1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def get_question_properties(skey,QuestionID):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"get_question_properties\",\"params\":[\"'+skey+'\",'+QuestionID
+',[\"gid\",\"type\",\"help\",\"language\",\"sid\",\"question_order\",\"question\",\"subquestions\"]],\"id\": 1}')

req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def release_session_key(relkey):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"release_session_key\",\"params\":[\"'+relkey+'\"],\"id\":1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def export_responses2(skey,sid):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"export_responses\",\"params\":[\"'+skey+'\",\"'+sid+'\",\"csv\",\"de\",\"full\"],\
"id\": 1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

mykey=get_session_key()
print export_responses2(mykey,'566237').decode('base64')
get_question_properties(mykey,'574')
print release_session_key(mykey)
</syntaxhighlight>

== NodeJS example ==

This script require request, you can include easily with the command
<source lang=bash>
npm install request
</source>

This is a example how to connect to limesurvey:

<source lang="javascript">
var request = require('request');

//******GLOBAL***************
var SESSIONKEY="";
var options = {
url: "https://xxxxxxxxxxxxxxxx/index.php/admin/remotecontrol",
method: "POST",
headers: {
'user-agent': 'Apache-HttpClient/4.2.2 (java 1.5)',
'host': 'xxxxxxxxxxxxxxxx',
'path': '/index.php/admin/remotecontrol',
'connection': 'keep-alive',
'content-type': 'application/json'
}
};

//*******AUTHENTIFICATION*******
options.body = JSON.stringify({method:'get_session_key',params:['myusername','mypassword'],id:1});

request(options, function(error, response, body){
if (!error && response.statusCode == 200) {
body = JSON.parse(body);

//*********KEEP THE KEY*********
if(SESSIONKEY==="") {
console.log("NEW KEY -->"+body.result);
SESSIONKEY=body.result;
nextFonction();
}
}
else console.log("ERROR -->"+body);
});

</source>

== R example and helper ==

The easiest way to use lsrc2 is by means of the limer package, See https://github.com/cloudyr/limer

Example of usage of this client
<source lang=R>
# first limer (check version: must be recent) must be installed
if(!require("devtools")) {
install.packages("devtools")
library("devtools")
}
install_github("cloudyr/limer")
#############################################################

library(limer)

#change the next options (website, user, password)
options
(lime_api = 'https://www.XXX.nl/index.php/admin/remotecontrol')
options(lime_username = 'user')
options(lime_password = 'password')
#############################################################

# first get a session access key
get_session_key()

# list all surveys. A dataframe is returned
survey_df<-call_limer(method='list_surveys')
print(survey_df)
# sid surveyls_title startdate expires active
#1 999999 XXXX NA 2016-03-08 15:20:30 Y
#2 999998 XXXX NA <NA> Y

#Read the data of the first survey (sid=999999) into a data.frame.
#Notice that the default sLanguageCode = en, so maybe you have to
#specify another language (here: All languages)
data<- get_responses(iSurveyID= 999999, sLanguageCode= '', sResponseType='short')

</source>

= JSON-RPC notes =

The content-type of the HTTP request '''must be application/json'''. Most formatting errors are a failure to set the content-type header. This will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.

<syntaxhighlight lang="php" enclose="div">Request:

HTTP headers:

content-type=application/json

connection=Keep-Alive

host=mylimesurveyhost.com

content-length=67

user-agent=Apache-HttpClient/4.2.2 (java 1.5)

Post body:

{"method":"get_session_key","params":["admin","mypassword"],"id":1}

Response body:

{"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}</syntaxhighlight>

RemoteControl 2 API

2017-08-29T14:25:44Z

LimeAJ: /* JSON-RPC notes */

__TOC__

=Introduction=

LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or more recent which offers '''various [https://api.limesurvey.org/classes/remotecontrol_handle.html API functions]'''.

LSRC2 makes it possible for developers to control specific functionality of LimeSurvey from any other application, without being restricted to PHP as a programming language.

The following features are planned:
* start a predefined survey (change titles and things)
* add predefined groups or questions
* activate the survey, restrict it to start and endtime
* make it closed,
* add participant data/tokens when you need them
* return the unused tokens to the main application
* get a fieldmap for a survey,
* invite or remind the participants of your survey

...and much more

==Requirements==
* libXML installed

=Setup=

== How to configure LSRC2==

In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to [[Global settings]], choose the tab 'Interfaces' and select one of the two RPC services (XML-RPC or JSON-RPC) service.

== Security==

LSRC2 uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also LSRC2 is protected against brute-force password cracking - like the normal administration login.

=How to use LSRC2=

The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol

LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC version 1 specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.

LSRC2 offers a lot of functions. Please check the automatically generated [http://api.limesurvey.org/classes/remotecontrol_handle.html API Documentation].
LSRC2 offers the following functions:

== Sessions ==

=== get_session_key ===

Using this function you can create a new XML/JSON-RPC session key. This is mandatory for all following LSRC2 function calls.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''Return on success''': (string) session key.

'''Return on error''': for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.

=== release_session_key ===

Using this function you can close a previously opened XML-RPC/JSON-RPC session.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Other functions ==

{{Alert|For all other function , you have to refer to the [http://api.limesurvey.org/classes/remotecontrol_handle.html online API ] . If your LimeSurvey version is outdated, you can publish your API and look at it directly.}}

= Example and helper =

== PHP Example ==

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository]. The library can also get included [https://getcomposer.org/download/ by composer calling]

<source lang=bash>
composer require weberhofer/jsonrpcphp
</source>

or by inclusion of the following lines in your composer.json file:

<source lang=javascript>
{
"require": {
"weberhofer/jsonrpcphp": "~2"
}
}
</source>

This is a example how to connect to limesurvey:

<source lang="php">
<?php

// without composer this line can be used
// require_once 'path/to/your/rpcclient/jsonRPCClient.php';
// with composer support just add the autoloader
include_once 'vendor/autoload.php';

define( 'LS_BASEURL', 'https://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL
define( 'LS_USER', 'rpcuser' );
define( 'LS_PASSWORD', 'mypassword' );

// the survey to process
$survey_id=374699;

// instantiate a new client
$myJSONRPCClient = new \org\jsonrpcphp\JsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );

// receive session key
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );

// receive all ids and info of groups belonging to a given survey
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );
print_r($groups, null );

// release the session key
$myJSONRPCClient->release_session_key( $sessionKey );

</source>

== JAVA example ==
To decode and code your json calls you can use the library gson as you can see in the following example:

<syntaxhighlight lang="java" enclose="div">
import java.io.IOException;
import java.io.UnsupportedEncodingException;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class TestHttpClient {

public static String parse(String jsonLine) {
JsonElement jelement = new JsonParser().parse(jsonLine);
JsonObject jobject = jelement.getAsJsonObject();
String result = jobject.get("result").getAsString();
return result;
}

public static void main(String[] args) throws UnsupportedEncodingException {
DefaultHttpClient client = new DefaultHttpClient();

HttpPost post = new HttpPost("https://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");
post.setHeader("Content-type", "application/json");
post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": [\"YOUR_USERNAME\", \"YOUR_PASSWORD\" ], \"id\": 1}"));
try {
HttpResponse response = client.execute(post);
if(response.getStatusLine().getStatusCode() == 200){
HttpEntity entity = response.getEntity();
String sessionKey = parse(EntityUtils.toString(entity));
post.setEntity( new StringEntity("{\"method\": \"list_groups\", \"params\": [ \""+sessionKey+"\", \"ID_SURVEY\" ], \"id\": 1}"));
response = client.execute(post);
if(response.getStatusLine().getStatusCode() == 200){
entity = response.getEntity();
System.out.println(EntityUtils.toString(entity));
}
}

} catch (IOException e) {
e.printStackTrace();
}
}}

</syntaxhighlight>

== Python example and glue ==

* [https://github.com/TaiSHiNet/lime-py-api LimeSurvey API - Python 2 glue]
* [https://github.com/lindsay-stevens/limesurveyrc2api LimeSurvey API - Basic client library in Python 3]. Includes tests. Listed on Pypi: pip install limesurveyrc2api

The following code runs with Python 2 and requires some adaptation to work with Python 3.

<syntaxhighlight lang="python" enclose="div">
import urllib
import urllib2
import json
import sys
# There is an generic json-rpc implemantation in Python but it dose not work for me in this case so I worte Some functions

def get_session_key():
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"get_session_key\",\"params\":[\"admin\",\"mypassword\"],\"id\":1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def get_question_properties(skey,QuestionID):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"get_question_properties\",\"params\":[\"'+skey+'\",'+QuestionID
+',[\"gid\",\"type\",\"help\",\"language\",\"sid\",\"question_order\",\"question\",\"subquestions\"]],\"id\": 1}')

req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def release_session_key(relkey):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"release_session_key\",\"params\":[\"'+relkey+'\"],\"id\":1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def export_responses2(skey,sid):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"export_responses\",\"params\":[\"'+skey+'\",\"'+sid+'\",\"csv\",\"de\",\"full\"],\
"id\": 1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

mykey=get_session_key()
print export_responses2(mykey,'566237').decode('base64')
get_question_properties(mykey,'574')
print release_session_key(mykey)
</syntaxhighlight>

== NodeJS example ==

This script require request, you can include easily with the command
<source lang=bash>
npm install request
</source>

This is a example how to connect to limesurvey:

<source lang="javascript">
var request = require('request');

//******GLOBAL***************
var SESSIONKEY="";
var options = {
url: "https://xxxxxxxxxxxxxxxx/index.php/admin/remotecontrol",
method: "POST",
headers: {
'user-agent': 'Apache-HttpClient/4.2.2 (java 1.5)',
'host': 'xxxxxxxxxxxxxxxx',
'path': '/index.php/admin/remotecontrol',
'connection': 'keep-alive',
'content-type': 'application/json'
}
};

//*******AUTHENTIFICATION*******
options.body = JSON.stringify({method:'get_session_key',params:['myusername','mypassword'],id:1});

request(options, function(error, response, body){
if (!error && response.statusCode == 200) {
body = JSON.parse(body);

//*********KEEP THE KEY*********
if(SESSIONKEY==="") {
console.log("NEW KEY -->"+body.result);
SESSIONKEY=body.result;
nextFonction();
}
}
else console.log("ERROR -->"+body);
});

</source>

== R example and helper ==

The easiest way to use lsrc2 is by means of the limer package, See https://github.com/cloudyr/limer

Example of usage of this client
<source lang=R>
# first limer (check version: must be recent) must be installed
if(!require("devtools")) {
install.packages("devtools")
library("devtools")
}
install_github("cloudyr/limer")
#############################################################

library(limer)

#change the next options (website, user, password)
options
(lime_api = 'https://www.XXX.nl/index.php/admin/remotecontrol')
options(lime_username = 'user')
options(lime_password = 'password')
#############################################################

# first get a session access key
get_session_key()

# list all surveys. A dataframe is returned
survey_df<-call_limer(method='list_surveys')
print(survey_df)
# sid surveyls_title startdate expires active
#1 999999 XXXX NA 2016-03-08 15:20:30 Y
#2 999998 XXXX NA <NA> Y

#Read the data of the first survey (sid=999999) into a data.frame.
#Notice that the default sLanguageCode = en, so maybe you have to
#specify another language (here: All languages)
data<- get_responses(iSurveyID= 999999, sLanguageCode= '', sResponseType='short')

</source>

= JSON-RPC notes =

The content-type of the HTTP request '''must be application/json'''. Most formatting errors are a failure to set the content-type header. This will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.

<syntaxhighlight lang="php" enclose="div">Request:

HTTP headers:

content-type=application/json

connection=Keep-Alive

host=mylimesurveyhost.com

content-length=67

user-agent=Apache-HttpClient/4.2.2 (java 1.5)

Post body:

{"method":"get_session_key","params":["admin","mypassword"],"id":1}

Response body:

{"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}</syntaxhighlight>

RemoteControl 2 API

2017-08-29T14:22:41Z

LimeAJ: /* JSON-RPC notes */

__TOC__

=Introduction=

LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or more recent which offers '''various [https://api.limesurvey.org/classes/remotecontrol_handle.html API functions]'''.

LSRC2 makes it possible for developers to control specific functionality of LimeSurvey from any other application, without being restricted to PHP as a programming language.

The following features are planned:
* start a predefined survey (change titles and things)
* add predefined groups or questions
* activate the survey, restrict it to start and endtime
* make it closed,
* add participant data/tokens when you need them
* return the unused tokens to the main application
* get a fieldmap for a survey,
* invite or remind the participants of your survey

...and much more

==Requirements==
* libXML installed

=Setup=

== How to configure LSRC2==

In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to [[Global settings]], choose the tab 'Interfaces' and select one of the two RPC services (XML-RPC or JSON-RPC) service.

== Security==

LSRC2 uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also LSRC2 is protected against brute-force password cracking - like the normal administration login.

=How to use LSRC2=

The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol

LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC version 1 specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.

LSRC2 offers a lot of functions. Please check the automatically generated [http://api.limesurvey.org/classes/remotecontrol_handle.html API Documentation].
LSRC2 offers the following functions:

== Sessions ==

=== get_session_key ===

Using this function you can create a new XML/JSON-RPC session key. This is mandatory for all following LSRC2 function calls.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''Return on success''': (string) session key.

'''Return on error''': for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.

=== release_session_key ===

Using this function you can close a previously opened XML-RPC/JSON-RPC session.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Other functions ==

{{Alert|For all other function , you have to refer to the [http://api.limesurvey.org/classes/remotecontrol_handle.html online API ] . If your LimeSurvey version is outdated, you can publish your API and look at it directly.}}

= Example and helper =

== PHP Example ==

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository]. The library can also get included [https://getcomposer.org/download/ by composer calling]

<source lang=bash>
composer require weberhofer/jsonrpcphp
</source>

or by inclusion of the following lines in your composer.json file:

<source lang=javascript>
{
"require": {
"weberhofer/jsonrpcphp": "~2"
}
}
</source>

This is a example how to connect to limesurvey:

<source lang="php">
<?php

// without composer this line can be used
// require_once 'path/to/your/rpcclient/jsonRPCClient.php';
// with composer support just add the autoloader
include_once 'vendor/autoload.php';

define( 'LS_BASEURL', 'https://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL
define( 'LS_USER', 'rpcuser' );
define( 'LS_PASSWORD', 'mypassword' );

// the survey to process
$survey_id=374699;

// instantiate a new client
$myJSONRPCClient = new \org\jsonrpcphp\JsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );

// receive session key
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );

// receive all ids and info of groups belonging to a given survey
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );
print_r($groups, null );

// release the session key
$myJSONRPCClient->release_session_key( $sessionKey );

</source>

== JAVA example ==
To decode and code your json calls you can use the library gson as you can see in the following example:

<syntaxhighlight lang="java" enclose="div">
import java.io.IOException;
import java.io.UnsupportedEncodingException;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class TestHttpClient {

public static String parse(String jsonLine) {
JsonElement jelement = new JsonParser().parse(jsonLine);
JsonObject jobject = jelement.getAsJsonObject();
String result = jobject.get("result").getAsString();
return result;
}

public static void main(String[] args) throws UnsupportedEncodingException {
DefaultHttpClient client = new DefaultHttpClient();

HttpPost post = new HttpPost("https://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");
post.setHeader("Content-type", "application/json");
post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": [\"YOUR_USERNAME\", \"YOUR_PASSWORD\" ], \"id\": 1}"));
try {
HttpResponse response = client.execute(post);
if(response.getStatusLine().getStatusCode() == 200){
HttpEntity entity = response.getEntity();
String sessionKey = parse(EntityUtils.toString(entity));
post.setEntity( new StringEntity("{\"method\": \"list_groups\", \"params\": [ \""+sessionKey+"\", \"ID_SURVEY\" ], \"id\": 1}"));
response = client.execute(post);
if(response.getStatusLine().getStatusCode() == 200){
entity = response.getEntity();
System.out.println(EntityUtils.toString(entity));
}
}

} catch (IOException e) {
e.printStackTrace();
}
}}

</syntaxhighlight>

== Python example and glue ==

* [https://github.com/TaiSHiNet/lime-py-api LimeSurvey API - Python 2 glue]
* [https://github.com/lindsay-stevens/limesurveyrc2api LimeSurvey API - Basic client library in Python 3]. Includes tests. Listed on Pypi: pip install limesurveyrc2api

The following code runs with Python 2 and requires some adaptation to work with Python 3.

<syntaxhighlight lang="python" enclose="div">
import urllib
import urllib2
import json
import sys
# There is an generic json-rpc implemantation in Python but it dose not work for me in this case so I worte Some functions

def get_session_key():
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"get_session_key\",\"params\":[\"admin\",\"mypassword\"],\"id\":1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def get_question_properties(skey,QuestionID):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"get_question_properties\",\"params\":[\"'+skey+'\",'+QuestionID
+',[\"gid\",\"type\",\"help\",\"language\",\"sid\",\"question_order\",\"question\",\"subquestions\"]],\"id\": 1}')

req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def release_session_key(relkey):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"release_session_key\",\"params\":[\"'+relkey+'\"],\"id\":1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def export_responses2(skey,sid):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"export_responses\",\"params\":[\"'+skey+'\",\"'+sid+'\",\"csv\",\"de\",\"full\"],\
"id\": 1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

mykey=get_session_key()
print export_responses2(mykey,'566237').decode('base64')
get_question_properties(mykey,'574')
print release_session_key(mykey)
</syntaxhighlight>

== NodeJS example ==

This script require request, you can include easily with the command
<source lang=bash>
npm install request
</source>

This is a example how to connect to limesurvey:

<source lang="javascript">
var request = require('request');

//******GLOBAL***************
var SESSIONKEY="";
var options = {
url: "https://xxxxxxxxxxxxxxxx/index.php/admin/remotecontrol",
method: "POST",
headers: {
'user-agent': 'Apache-HttpClient/4.2.2 (java 1.5)',
'host': 'xxxxxxxxxxxxxxxx',
'path': '/index.php/admin/remotecontrol',
'connection': 'keep-alive',
'content-type': 'application/json'
}
};

//*******AUTHENTIFICATION*******
options.body = JSON.stringify({method:'get_session_key',params:['myusername','mypassword'],id:1});

request(options, function(error, response, body){
if (!error && response.statusCode == 200) {
body = JSON.parse(body);

//*********KEEP THE KEY*********
if(SESSIONKEY==="") {
console.log("NEW KEY -->"+body.result);
SESSIONKEY=body.result;
nextFonction();
}
}
else console.log("ERROR -->"+body);
});

</source>

== R example and helper ==

The easiest way to use lsrc2 is by means of the limer package, See https://github.com/cloudyr/limer

Example of usage of this client
<source lang=R>
# first limer (check version: must be recent) must be installed
if(!require("devtools")) {
install.packages("devtools")
library("devtools")
}
install_github("cloudyr/limer")
#############################################################

library(limer)

#change the next options (website, user, password)
options
(lime_api = 'https://www.XXX.nl/index.php/admin/remotecontrol')
options(lime_username = 'user')
options(lime_password = 'password')
#############################################################

# first get a session access key
get_session_key()

# list all surveys. A dataframe is returned
survey_df<-call_limer(method='list_surveys')
print(survey_df)
# sid surveyls_title startdate expires active
#1 999999 XXXX NA 2016-03-08 15:20:30 Y
#2 999998 XXXX NA <NA> Y

#Read the data of the first survey (sid=999999) into a data.frame.
#Notice that the default sLanguageCode = en, so maybe you have to
#specify another language (here: All languages)
data<- get_responses(iSurveyID= 999999, sLanguageCode= '', sResponseType='short')

</source>

= JSON-RPC notes =

The content-type of the HTTP request must be application/json. Most formatting errors are a failure to set the content-type header will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.

<syntaxhighlight lang="php" enclose="div">Request:

HTTP headers:

content-type=application/json

connection=Keep-Alive

host=mylimesurveyhost.com

content-length=67

user-agent=Apache-HttpClient/4.2.2 (java 1.5)

Post body:

{"method":"get_session_key","params":["admin","mypassword"],"id":1}

Response body:

{"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}</syntaxhighlight>

RemoteControl 2 API

2017-08-28T13:43:22Z

LimeAJ: /* PHP Example */

__TOC__

=Introduction=

LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or more recent which offers '''various [https://api.limesurvey.org/classes/remotecontrol_handle.html API functions]'''.

LSRC2 makes it possible for developers to control specific functionality of LimeSurvey from any other application, without being restricted to PHP as a programming language.

The following features are planned:
* start a predefined survey (change titles and things)
* add predefined groups or questions
* activate the survey, restrict it to start and endtime
* make it closed,
* add participant data/tokens when you need them
* return the unused tokens to the main application
* get a fieldmap for a survey,
* invite or remind the participants of your survey

...and much more

==Requirements==
* libXML installed

=Setup=

== How to configure LSRC2==

In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to [[Global settings]], choose the tab 'Interfaces' and select one of the two RPC services (XML-RPC or JSON-RPC) service.

== Security==

LSRC2 uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also LSRC2 is protected against brute-force password cracking - like the normal administration login.

=How to use LSRC2=

The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol

LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC version 1 specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.

LSRC2 offers a lot of functions. Please check the automatically generated [http://api.limesurvey.org/classes/remotecontrol_handle.html API Documentation].
LSRC2 offers the following functions:

== Sessions ==

=== get_session_key ===

Using this function you can create a new XML/JSON-RPC session key. This is mandatory for all following LSRC2 function calls.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''Return on success''': (string) session key.

'''Return on error''': for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.

=== release_session_key ===

Using this function you can close a previously opened XML-RPC/JSON-RPC session.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Other functions ==

{{Alert|For all other function , you have to refer to the [http://api.limesurvey.org/classes/remotecontrol_handle.html online API ] . If your LimeSurvey version is outdated, you can publish your API and look at it directly.}}

= Example and helper =

== PHP Example ==

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository]. The library can also get included [https://getcomposer.org/download/ by composer calling]

<source lang=bash>
composer require weberhofer/jsonrpcphp
</source>

or by inclusion of the following lines in your composer.json file:

<source lang=javascript>
{
"require": {
"weberhofer/jsonrpcphp": "~2"
}
}
</source>

This is a example how to connect to limesurvey:

<source lang="php">
<?php

// without composer this line can be used
// require_once 'path/to/your/rpcclient/jsonRPCClient.php';
// with composer support just add the autoloader
include_once 'vendor/autoload.php';

define( 'LS_BASEURL', 'https://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL
define( 'LS_USER', 'rpcuser' );
define( 'LS_PASSWORD', 'mypassword' );

// the survey to process
$survey_id=374699;

// instantiate a new client
$myJSONRPCClient = new \org\jsonrpcphp\JsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );

// receive session key
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );

// receive all ids and info of groups belonging to a given survey
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );
print_r($groups, null );

// release the session key
$myJSONRPCClient->release_session_key( $sessionKey );

</source>

== JAVA example ==
To decode and code your json calls you can use the library gson as you can see in the following example:

<syntaxhighlight lang="java" enclose="div">
import java.io.IOException;
import java.io.UnsupportedEncodingException;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class TestHttpClient {

public static String parse(String jsonLine) {
JsonElement jelement = new JsonParser().parse(jsonLine);
JsonObject jobject = jelement.getAsJsonObject();
String result = jobject.get("result").getAsString();
return result;
}

public static void main(String[] args) throws UnsupportedEncodingException {
DefaultHttpClient client = new DefaultHttpClient();

HttpPost post = new HttpPost("https://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");
post.setHeader("Content-type", "application/json");
post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": [\"YOUR_USERNAME\", \"YOUR_PASSWORD\" ], \"id\": 1}"));
try {
HttpResponse response = client.execute(post);
if(response.getStatusLine().getStatusCode() == 200){
HttpEntity entity = response.getEntity();
String sessionKey = parse(EntityUtils.toString(entity));
post.setEntity( new StringEntity("{\"method\": \"list_groups\", \"params\": [ \""+sessionKey+"\", \"ID_SURVEY\" ], \"id\": 1}"));
response = client.execute(post);
if(response.getStatusLine().getStatusCode() == 200){
entity = response.getEntity();
System.out.println(EntityUtils.toString(entity));
}
}

} catch (IOException e) {
e.printStackTrace();
}
}}

</syntaxhighlight>

== Python example and glue ==

* [https://github.com/TaiSHiNet/lime-py-api LimeSurvey API - Python 2 glue]
* [https://github.com/lindsay-stevens/limesurveyrc2api LimeSurvey API - Basic client library in Python 3]. Includes tests. Listed on Pypi: pip install limesurveyrc2api

The following code runs with Python 2 and requires some adaptation to work with Python 3.

<syntaxhighlight lang="python" enclose="div">
import urllib
import urllib2
import json
import sys
# There is an generic json-rpc implemantation in Python but it dose not work for me in this case so I worte Some functions

def get_session_key():
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"get_session_key\",\"params\":[\"admin\",\"mypassword\"],\"id\":1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def get_question_properties(skey,QuestionID):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"get_question_properties\",\"params\":[\"'+skey+'\",'+QuestionID
+',[\"gid\",\"type\",\"help\",\"language\",\"sid\",\"question_order\",\"question\",\"subquestions\"]],\"id\": 1}')

req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def release_session_key(relkey):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"release_session_key\",\"params\":[\"'+relkey+'\"],\"id\":1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def export_responses2(skey,sid):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"export_responses\",\"params\":[\"'+skey+'\",\"'+sid+'\",\"csv\",\"de\",\"full\"],\
"id\": 1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

mykey=get_session_key()
print export_responses2(mykey,'566237').decode('base64')
get_question_properties(mykey,'574')
print release_session_key(mykey)
</syntaxhighlight>

== NodeJS example ==

This script require request, you can include easily with the command
<source lang=bash>
npm install request
</source>

This is a example how to connect to limesurvey:

<source lang="javascript">
var request = require('request');

//******GLOBAL***************
var SESSIONKEY="";
var options = {
url: "https://xxxxxxxxxxxxxxxx/index.php/admin/remotecontrol",
method: "POST",
headers: {
'user-agent': 'Apache-HttpClient/4.2.2 (java 1.5)',
'host': 'xxxxxxxxxxxxxxxx',
'path': '/index.php/admin/remotecontrol',
'connection': 'keep-alive',
'content-type': 'application/json'
}
};

//*******AUTHENTIFICATION*******
options.body = JSON.stringify({method:'get_session_key',params:['myusername','mypassword'],id:1});

request(options, function(error, response, body){
if (!error && response.statusCode == 200) {
body = JSON.parse(body);

//*********KEEP THE KEY*********
if(SESSIONKEY==="") {
console.log("NEW KEY -->"+body.result);
SESSIONKEY=body.result;
nextFonction();
}
}
else console.log("ERROR -->"+body);
});

</source>

== R example and helper ==

The easiest way to use lsrc2 is by means of the limer package, See https://github.com/cloudyr/limer

Example of usage of this client
<source lang=R>
# first limer (check version: must be recent) must be installed
if(!require("devtools")) {
install.packages("devtools")
library("devtools")
}
install_github("cloudyr/limer")
#############################################################

library(limer)

#change the next options (website, user, password)
options
(lime_api = 'https://www.XXX.nl/index.php/admin/remotecontrol')
options(lime_username = 'user')
options(lime_password = 'password')
#############################################################

# first get a session access key
get_session_key()

# list all surveys. A dataframe is returned
survey_df<-call_limer(method='list_surveys')
print(survey_df)
# sid surveyls_title startdate expires active
#1 999999 XXXX NA 2016-03-08 15:20:30 Y
#2 999998 XXXX NA <NA> Y

#Read the data of the first survey (sid=999999) into a data.frame.
#Notice that the default sLanguageCode = en, so maybe you have to
#specify another language (here: All languages)
data<- get_responses(iSurveyID= 999999, sLanguageCode= '', sResponseType='short')

</source>

= JSON-RPC notes =

The content-type of the HTTP request must be application/json. Most formatting errors or a failure to set the content-type header will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.

<syntaxhighlight lang="php" enclose="div">Request:

HTTP headers:

content-type=application/json

connection=Keep-Alive

host=mylimesurveyhost.com

content-length=67

user-agent=Apache-HttpClient/4.2.2 (java 1.5)

Post body:

{"method":"get_session_key","params":["admin","mypassword"],"id":1}

Response body:

{"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}</syntaxhighlight>

Optional settings

2017-08-25T20:01:18Z

LimeAJ:

<languages /> <translate>


__TOC__

The following section is addressed to those of you who would like to edit those configuration settings that could not be modified with the help of the GUI (Graphical User Interface) of the LimeSurvey installation. Please bear in mind that all the changes from the LimeSurvey root directory are done at your own risk. Nevertheless, in the case in which you are experiencing problems/need further guidance, join the [https://www.limesurvey.org/forum discussion forums] or the [irc://irc.freenode.net/limesurvey|IRC IRC channel] for help from the LimeSurvey community.

=Introduction= 


To modify the configuration settings of the installation, you have to edit the optional settings. They can be found in the /application/config/'''config-defaults.php''', which is located in the LimeSurvey root directory. The default settings of the standard installation can be found in config-defaults.php. Some of them can be overridden by using the [[Global settings]|global settings] dialog, while the others will have to be manually edited.


{{Alert|If you want to change these settings, please do not change them in config-defaults.php, but copy the particular setting/line to /application/config/'''config.php''' in <nowiki>'config'=>array( )</nowiki> and change it there. All the newly modified/introduced settings from the config.php file will overridde the default values from config-defaults.php.}}

When an upgrade occurs, only the config-defaults.php settings are changed. Therefore, editing the config.php file will save your customized settings.


To update/add the LimeSurvey settings in /application/'''config/config.php''', you have to update the config array:
<syntaxhighlight lang="php" enclose="pre">
'config'=>array(
'debug'=>0,
'debugsql'=>0,
'LimeSurveySetting'=>'New value', // Update default LimeSurvey config here
)
</syntaxhighlight>

=Yii settings= 
LimeSurvey uses the Yii framework, which has its own configuration parameters in the application/config/'''config.php''' file. You can also access some specific configuration settings of LimeSurvey via the Yii configuration.


The Yii specific settings are set in the components array:
<syntaxhighlight lang="php" enclose="pre">
'components' => array(
'db' => array(
....
),
'Specific settings'=>array(
....
),
),
</syntaxhighlight>

{{Note|For more information about the Yii framework, please access the [http://www.yiiframework.com/doc-2.0/guide-index.html following link.]}}

==Database settings== 
The database settings are written to config.php by the installer file when you install LimeSurvey for the first time. If needed, you can update this part of the config.php file. Please remember that you do this at your own risk!
See also the [http://www.yiiframework.com/doc/blog/1.1/en/prototype.database#establishing-database-connection Yii documentation], and please remember that LimeSurvey supports only the following types of database: mysql, pgsql, dblib, mssql, and sqlsrv.

==Session settings== 
You can set some session parameters in config.php (check the two examples from below). You can uncomment/add the part needed in config.php. See the [http://www.yiiframework.com/doc/api/1.1/CHttpSession Yii Documentation] for other settings.


If you use SSL ('https') for your LimeSurvey installation, adding the following lines to your config.php will increase the security of the session:
<syntaxhighlight lang="php" enclose="pre"> // Set the cookie via SSL
'session' => array (
'cookieParams' => array(
'secure' => true, // use SSL for cookies
'httponly' => true // Cookies may not be used by other protocols - experimental
),
),
</syntaxhighlight>


If you want to fix the domain for a cookie, use the following syntax in config.php:
<syntaxhighlight lang="php" enclose="pre"> // Set the domain for cookie
'session' => array (
'cookieParams' => array(
'domain' => '.example.org',
),
),
</syntaxhighlight>

==Request settings== 
The request settings are important, but the default settings are already optimized for LimeSurvey usage. To read more about them, see the [http://www.yiiframework.com/doc/api/1.1/CHttpRequest Yii Documentation].


For example, the LimeSurvey request settings configuration may be modified in the following way (at your own risk) :
<syntaxhighlight lang="php" enclose="pre"> // Disable CSRF protection
'request' => array(
'enableCsrfValidation'=>false,
),
</syntaxhighlight>
<syntaxhighlight lang="php" enclose="pre"> // Enforce a certain URL base
'request' => array(
'hostInfo' => 'http://www.example.org/'
),
</syntaxhighlight>
<syntaxhighlight lang="php" enclose="pre"> // Set the cookie domain name for CSRF protection
'request' => array(
'csrfCookie' => array( 'domain' => '.example.com' )
),
</syntaxhighlight>


If you need to update only the url for token emails, set your [[Optional_settings#Advanced_path_settings|publicurl]] in your config.php file.

==URL settings== 
To change the default URL settings, update the urlManager:
<syntaxhighlight lang="php" enclose="pre"> // Use short URL
'urlManager' => array(
'urlFormat' => 'path',
'showScriptName' => false,
),
</syntaxhighlight>
You can also add .html after the survey id in the following way:
<syntaxhighlight lang="php" enclose="pre"> // Use short URL
'urlManager' => array(
'urlFormat' => 'path',
'rules' => array (
'<sid:\d+>' => array('survey/index','urlSuffix'=>'.html','matchValue'=>true),
),
'showScriptName' => false,
),
</syntaxhighlight>
For more information, check the [http://www.yiiframework.com/doc/guide/1.1/en/topics.url Yii documentation].

==Logging settings==

Yii provides different solutions to generate logs. To find out more about them, check the [http://www.yiiframework.com/doc/guide/1.1/en/topics.logging logging special topic]. LimeSurvey uses '1' or '2' by default, which allows every web user to see the logs. You can create your own settings using Yii directly.

For example, a quick solution to log errors and warnings in files is:
<syntaxhighlight lang="php" enclose="pre"> // Log error
'log' => array(
'routes' => array(
'fileError' => array(
'class' => 'CFileLogRoute',
'levels' => 'warning, error',
),
),
),
</syntaxhighlight>

{{Hint|Text=The file is saved by default to <code><nowiki>limesurvey/tmp/runtime/application.log</nowiki></code>, which is located in the LimeSurvey root folder.}}
{{Alert|Yii uses runtime path. By default, the logs are web accessible. They may contain a lot of information from your server. It is better to use a directory that cannot be accessed via the web. You can set it in routes or by updating the [[Optional settings#Yii settings#Runtime path|Runtime path]].}}.

==Runtime path==

[http://www.yiiframework.com/doc/guide/1.1/en/basics.convention#directory The runtime path] must be a readable and writable directory for the “web user”. However, the runtime path contains files with potential security information that are located in the public web access area. LimeSurvey collects these files in the temp directory of the LimeSurvey root directory. In order to eliminate the access to such important data, you can set the runtime path outside the public web access by editing the respective lines in the /application/config/config.php file:

<syntaxhighlight lang="php" enclose="pre">
return array(
'components' => array(
[…]
'runtimePath'=>'/var/limesurvey/runtime/',
'config'=>array(
[…]
)
)
)
</syntaxhighlight>

=General settings= 


*'''sitename''': Gives your survey site a name. This name will appear in the survey list overview and in the administration header. The default value is 'LimeSurvey' and it can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''siteadminemail:''' This is the default email address of the site administrator and it is used for system messages and contact options. This setting is used only as default value and can be overridden in the [[Global settings|global settings]] dialog.
*'''siteadminbounce:''' This is the email address where bounced emails will be sent to. This setting is used only as default value and can be overridden by the [[Global settings|global settings]] dialog.
*'''siteadminname:''' The real name of the site administrator. This setting is used only as default value and can be overridden in the [[Global settings|global settings]] dialog).
*'''proxy_host_name:''' This is the host name of your proxy server (it has to be mentioned if you are behind a proxy and you want to update LimeSurvey using [[ComfortUpdate|ComfortUpdate]]).
*'''proxy_host_port:''' This is the port of your proxy server (it has to be mentioned if you are behind a proxy and you want to update LimeSurvey using [[ComfortUpdate|ComfortUpdate]]).

= Security= 


* '''maxLoginAttempt''': This is the number of attempts a user has to enter the correct password before he or she gets her or his IP address blocked/locked out. The default value is 3 and it can be modified from config.php.
* '''timeOutTime''': If the user enters the password incorrectly for <maxLoginAttempt>, she or he gets locked out for <timeOutTime> seconds. The default value is 10 minutes and it can be modified from config.php.
* '''surveyPreview_require_Auth''': Set to true by default. If you set this to 'false', any person can test your survey using the survey URL, without logging in to the administration panel and without having to activate the survey first. This setting is a default value and can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
* '''usercontrolSameGroupPolicy''': Set to true by default. By default, non-admin users defined in the LimeSurvey management interface will only be able to see users they create or users that belongs to at least one same group. The default value can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''filterxsshtml:''' This setting enables the filtering of suspicious html tags located within surveys, groups, and questions and answer texts in the administration interface. Leave this to 'false' only if you absolutely trust the users you created for the administration of LimeSurvey and if you want to allow these users to be able to use Javascript, Flash Movies, etc. <span class="warning">The super admins never have their HTML filtered</span>. The default value can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''demoMode:''' If this option is set to 'true' in config.php, then LimeSurvey will go into demo mode. The demo mode changes the following things:
** Disables admin user's details and password changing;
** Disables the upload of files on the template editor;
** Disables sending e-mail invitations and reminders;
** Disables the creation of a database dump;
** Disables the ability to modify the following global settings: site name, default language, default HTML leditor mode, XSS filter.

= Resources= 
*'''sessionlifetime:''' Defines the time in seconds after which a survey session expires. It applies only if you are using database sessions. If you do use database sessions, change the parameter in config.php or override the default value from the [[Global settings|global settings]] dialog.
*'''memorylimit:''' This sets how much memory LimeSurvey can access. '128 MB' is the minimum (MB=Megabyte) recommended. If you receive time out errors or have problems generating statistics or exporting files, raise this limit to '256 MB' or higher. If your web server has set a higher limit in config.php, then this setting will be ignored.


<div class="warningbox">'''Please bear in mind that such local settings can always be overruled by the changes done in the global settings dialog'''.</div>


To increase the memory limit to 128M you could also try adding:
*memory_limit = 128M to your server's main php.ini file (recommended, if you have access)
*memory_limit = 128M to a php.ini file in the LimeSurvey root
*php_value memory_limit 128M in a .htaccess file in the LimeSurvey root

=Appearance= 
*'''dropdownthreshold'''{{ObsoleteIn|2.50}}: When "R" is selected for <code>$dropdowns</code>, the administrator is allowed to set a maximum number of options that will be displayed as radio buttons, before converting back to a dropdown list. If there is a question that has a large number of options, displaying all of them at once as radio buttons can look unwieldy, and can become counter-intuitive to users. Setting this to a maximum of, say 25 (which is the default) means that large lists are easier to be used by the administrators for the survey participant.
*'''repeatheadings:''' With the Array type question, often you'll have a lot of subquestions, which - when displayed on screen - take up more than one page. This setting lets you decide how many subquestions should be displayed before repeating the header information for the question. A good setting for this is around 15. If you don't want the headings to repeat at all, set this to 0. This setting is overridden in the [[Global settings|global settings]] dialog {{NewIn|2.05}}.
*'''minrepeatheadings:''' The minimum number of remaining subquestions that are required before repeating the headings in Array questions. The default value is 3 and it can be edited in config.php.
*'''defaulttemplate:''' This setting specifies the default theme used for the 'public list' of surveys. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''defaulthtmleditormode:''' Sets the default mode for the integrated HTML editor. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php. The valid settings are:
** 'inline' - Inline replacement of fields by an HTML editor. Slow but convenient and user friendly;
** 'popup' - Adds an icon that runs the HTML editor in a popup if needed. Faster, but HTML code is displayed in the form;
** 'none'- No HTML editor;
*'''column_style:''' Defines how columns are rendered for survey answers when using [[QS:Display_columns|display_columns]]. It can be edited in the config.php file. The valid settings are:
** 'css' - it uses one of the various CSS methods to create columns (see the template style sheet for details);
** 'ul' - the columns are rendered as multiple floated unordered lists (default);
** 'table' - it uses conventional-tables based layout;
** NULL - it disables the use of columns.

=Language & time= 
*'''defaultlang:''' This should be set to the default language to be used in your administration scripts, and also the default setting for language in the public survey list. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''timeadjust:''' If your web server is in a different time zone to the location where your surveys will be based, put the difference between your server and your home time zone here. For example, I live in Australia, but I use a US web server. The web server is 14 hours behind my local time zone. So my setting here is "14". In other words, it adds 14 hours to the web servers time. This setting is particularly important when surveys timestamp the responses. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.

=Survey behavior= 
*'''deletenonvalues:''' Use this feature with caution. By default (a value of 1), irrelevant questions are NULLed in the database. This ensures that the data in your database is internally consistent. However, there are rare cases where you might want to hold onto irrelevant values, in which case you can set the value to 0. For example, you ask the person his gender, and he accidentally says 'female' and then answers some female-specific questions (questions that are conditioned on being female, so are only relevant for women). Then, he realizes his mistake, backs up, sets the gender to 'male', and continues with the survey. Now, the female-specific questions are irrelevant. If <code>$deletenonvalues==1</code>, those irrelevant values will be cleared (NULLed) in the database. If <code>$deletenonvalues==0</code>, his erroneous answers will not be deleted, so they will still be present in the database when you analyze it.
*'''shownoanswer:''' When a radio button/select type question that contains editable answers (i.e.: List, Array questions) is not mandatory and 'shownoanswer' is set to 1, an additional 'No answer' entry is shown - so that participants may choose to not answer the question. Some people prefer this not to be available. This setting can be overridden from the [[Global settings|global settings]] dialog or edited in config.php. Valid values are:
**'0': No;
**'1': Yes;
**'2': The Survey admin can choose.
*'''printanswershonorsconditions:''' This setting determines if the printanswers feature will display entries from questions that were hidden by conditions-branching (Default: 1 = hide answers from questions hidden by conditions).
*'''hide_groupdescr_allinone:''' This setting is relevant for all-in-one surveys using conditions . When this is set to 'true', the group name and description is hidden if all questions in the group are hidden. The default value is 'true' - hides group name and description when all questions in the group are hidden by conditions. It can be edited in config.php.
*'''showpopups:''' Show popup messages if mandatory or conditional questions have not been answered correctly:
** '1'=Show popup message (default);
** '0'=Show message on page instead;
** '-1'=Do not show the message at all (in this case, users will still see the question-specific tips indicating which questions must be answered).

=Development and debugging= 
*'''debug:''' With this setting, you set the PHP error reporting to E_ALL. This means that every little notice, warning or error related to the script is shown. This setting should be only switched to '1' if you are trying to debug the application for any reason. If you are a developer, switch it to '2'. Don't switch it to '1' or '2' in production since it might cause path disclosure. The default value is '0' and it can be edited in config.php.
*'''debugsql:''' Activate this setting if you want to display all SQL queries executed for the script on the bottom of each page. Very useful for the optimization of the the number of queries. In order to activate it, change the default value to '1' from the config.php file.


In the case in which you experience an error in the application, we strongly recommend to activate the debug setting in order to get a more detailed error that you can submit with the bug report:


<syntaxhighlight lang="php" enclose="pre">
'config'=>array(
'debug'=>2,
'debugsql'=>0,
)
</syntaxhighlight>

= Email settings= 


All the settings from below can be overridden in the [[Global settings|global settings]] dialog.
*'''emailmethod:' This determines how email messages are being sent. The following options are available:
**'mail:' it uses internal PHP mailer;
**'sendmail:' it uses sendmail mailer;
**'smtp:' it uses SMTP relaying. Use this setting when you are running LimeSurvey on a host that is not your mail server.
*'''emailsmtphost:' If you use 'smtp' as <code>$emailmethod</code>, then you have to put your SMTP-server here. If you are using Google mail you might have to add the port number like $emailsmtphost = 'smtp.gmail.com:465'.
*'emailsmtpuser:' If your SMTP-server needs authentication then set this to your user name, otherwise it must be blank.
*'emailsmtppassword:' If your SMTP-server needs authentication then set this to your password, otherwise it must be blank.
*'emailsmtpssl:' Set this to 'ssl' or 'tls' to use SSL/TLS for SMTP connection.
*'maxemails:' When sending invitations or reminders to survey participants, this setting is used to determine how many emails can be sent in one bunch. Different web servers have different email capacities and if your script takes too long to send a bunch of emails, the script could time out and cause errors. Most web servers can send 100 emails at a time within the default 30 second time limit for a PHP script. If you get script timeout errors when sending large numbers of emails, reduce the number in this setting. Clicking the 'send email invitation' button from the token control toolbar (not the button situated on the right of each token) sends the <maxemails> number of invitations, then it displays a list of the addresses of the recipients and a warning that ''there are more emails pending than could be sent in one batch. Continue sending emails by clicking below. There are ### emails still to be sent.'' and provides a "continue button" to proceed with the next batch. I.e., the user determines when to send the next batch after each batch gets emailed. It is not necessary to wait with this screen active. The admin could log out and come back at a later time to send the next batch of invites.

= Statistics and response browsing= 
*'''filterout_incomplete_answers:''' Control the default behavior of filtering incomplete answers when browsing or analyzing responses. For a discussion on incomplete responses see our [[Browsing survey results|browsing survey results wiki]]. Since these records can corrupt the statistics, an option is given to switch this filter on or off in several GUI forms. The parameter can be edited in the config.php. The following options are available:
**'show': Allows you to visualize both complete and incomplete answers;
**'filter': It shows only complete answers;
**'incomplete': Show only incomplete answers.
*'''strip_query_from_referer_url''': This setting determines if the referrer URL saves the parameter or not. The default value is 'false' (in this case, the referrer URL saves all parameters). Alternatively, this value can be set to 'true' and the parameter part of the referrer URL will be removed.
*'''showaggregateddata:''' when activated, additional statistical values such as the arithmetic mean and standard deviation are shown. Furthermore, the data is aggregated to get a faster overview. For example, results of scale 1+2 and 4+5 are added to have a general ranking like "good" (1/2), "average" (3) and "bad" (4/5). This only affects question types "A" (5 point array) and "5" (5 point choice).
* '''PDF Export Settings:''' This feature activates PDF export for printable surveys and Print Answers. The PDF export function is totally experimental and the output is far from being perfect. Unfortunately, no support can be given at the moment - if you want to help to fix it, please get in touch with us.
**'usepdfexport': Set '0' to disable and '1' to enable;
**'pdfdefaultfont': It represents the default font that will be used by the pdf export function. The default value is 'auto'. To change it, you have to set it to one of the [https://tcpdf.org/docs/fonts/ PDF core fonts].
**'alternatepdffontfile': It's an array with language keys and their corresponding font. The default font for each language can be replaced in the config.php file;
**'pdffontsize': it shows the font size for normal texts; For the title of the survey, it is <pdffontsize>+4, while for the group title is <pdffontsize>+2. It can be edited in the config.php file or from the [Global settings|global settings]] dialog;
**'notsupportlanguages': it includes a list with the languages for which no PDF font was found. The list includes Amharic ('am'), Sinhala ('si'), and Thai ('th'), and it can be found in the config-defaults.php file;
**'pdforientation': Set 'L' for Landscape or 'P' for portrait format. It can be edited from the config.php file.
*'"Graph setting"'
**'chartfontfile': Sets the font file name that is used to create the statistical charts. The file has to be located in the fonts directory, located in the LimeSurvey root folder. It can be edited in the config.php file;
**'alternatechartfontfile': It's an array with language keys and their corresponding font. It can be edited in the config.php file.
*'''showsgqacode:''' This setting is used at the printable survey feature and defaults to 'false''. If you set ''showsgqacode = 'true';'', the IDs of each question - and answer if applicable - will be shown. These IDs match the column heading at the Lime_survey_12345 table, which holds the answer data for a certain survey. These IDs can be used for a code book for manual database queries.

= [[LDAP settings]]= 


As this is an extensive topic we have moved [[LDAP settings]] to [[LDAP settings|another page.]]

= Authentication= 


Starting with LimeSurvey 2.05, authentication will be handled by plugins. As a result, the information below might be outdated. See [[Plugins]] for most up to date information.

== Authentication delegation to the webserver== 


System administrators may want to have their '''survey administrators''' authenticated against a central authentication system (Active Directory, openLdap, Radius, ...) rather than using the internal LimeSurvey database. An easy way to do this is to setup your web server software to use this external authentication system, and then ask LimeSurvey to trust the user identity reported by the web server. In order to enable this feature, you have to:
* set '''auth_webserver''' to 'true' in config.php;
* enable authentication from the web server side.


Please note that:
* LimeSurvey will then bypass its own authentication process (by using the login name reported by the web server without asking for a password);
* this can only replace the LimeSurvey GUI authentication system, '''not the survey invitation system''' (participant interface).

== Authentication delegation with no automatic user import== 


Please note that <u>Authentication Delegation doesn't bypass the LimeSurvey authorization system by default</u> - meaning that, even if you don't have to manage passwords in LimeSurvey, you still need to define the users in the LimeSurvey database and assign them the correct set of rights in order to let them access the administration panel.


A user is then granted access to LimeSurvey if and only if:
* he has been authenticated to the web server;
* his login name is defined as a user in the LimeSurvey user database (the user is then granted the privileges of the user defined in the LimeSurvey user database).

== Authentication delegation with automatic user import== 


When managing a huge user database, it is sometimes easier to auto-import users in the LimeSurvey database:
*'''auth_webserver_autocreate_user''': If set to 'true', LimeSurvey will try to auto-import users authenticated by the web server but not already in its users DB.
*'''auth_webserver_autocreate_profile''': An array describing the default profile that will be assigned to the user, including the full (fake) name, email, and privileges.


If you want to customize the user profile so that it matches the logged-in user, you'll have to develop a simple function called '''hook_get_autouserprofile''' - with this function you can retrieve from a central user account database (for instance, from a LDAP directory) the true full name, names, and email of a particular user. You can even customize his privileges on the system based on the groups he is allocated in the external database.


The '''hook_get_auth_webserver_profile''' function takes the user login name as the only argument and can return:
* False or an empty array - in this case the user is denied access to LimeSurvey;
* an array containing all common userprofile entries as described in the <code>$WebserverAuth_autouserprofile</code>

</translate><syntaxhighlight lang="php" enclose="div">function hook_get_auth_webserver_profile($user_name)
{
// Retrieve user's data from your database backend (for instance LDAP) here
... get $user_name_from_backend
... get $user_email_from_backend
... get $user_lang_from_backend
... from groups defined in your backend set $user_admin_status_frombackend_0_or_1
return Array(
'full_name' => "$user_name_from_backend",
'email' => "$user_email_from_backend",
'lang' => '$user_lang_from_backend',
'htmleditormode' => 'inline',
'templatelist' => 'default,basic,MyOrgTemplate',
'create_survey' => 1,
'create_user' => 0,
'delete_user' => 0,
'superadmin' => $user_admin_status_frombackend_0_or_1,
'configurator' =>0,
'manage_template' => 0,
'manage_label' => 0);
}

// If user should be denied access, return an empty array

// return Array();</syntaxhighlight><translate>

{{Alert|The optionnal 'hook_get_auth_webserver_profile' function is for advanced user usage only! For further details, please read the comments from the config-defaults.php file.}}

== User name mapping== 


In the case in which some users have an external user name that is different from their LimeSurvey user name, you may find useful to use a user name mapping. This is done in LimeSurvey by using the '''auth_webserver_user_map''' parameter. For instance, imagine you don't have an 'admin' user name defined in your external authentication database. Then, in order to login to LimeSurvey as admin, you'll have to map your external user name (let's call it 'myname') to the admin login name in LimeSurvey. The corresponding setup is:

</translate>
<syntaxhighlight lang="php" enclose="div">'config'=>array(
...
'auth_webserver_user_map' => array ('myname' => 'admin');
)</syntaxhighlight><translate>


After a successful authentication with the 'myname' login and web server password, you'll be directly authorized to use LimeSurvey as the 'admin' user.


This obviously has serious security implications, so use it with care, and please protect your config.php from write access by the web server.

== Use one-time passwords== 


A user can open the LimeSurvey login page at default.com/limesurvey/admin and type the username and the one-time password which was previously written into the users table (column one_time_pw) by an external application.


This setting has to be turned on (<code>config['use_one_time_passwords'] = true;</code>) to enable the usage of one-time passwords (default = false). More information can be found in the [[Manage users#Use one-time passwords|"Manage Users" section]].

= Advanced path settings= 


*'''homeurl:''' This should be set to the URL location of your administration scripts. These are located in the /limesurvey/admin folder. This should be set to the WEB URL location - for example, "http://www.example.com/limesurvey/html/admin". Don't add a trailing slash to this entry. The default setting in config.php attempts to detect the name of your server automatically using a php variable setting - <code>{$_SERVER<nowiki>[</nowiki>'SERVER_NAME']}</code>. In most cases you can leave this and just modify the remainder of this string to match the directory name you have put the LimeSurvey scripts in.
*'''publicurl:''' This should be set to the URL location of your 'public scripts'. The public scripts are those located in the "limesurvey" folder (or whatever name you gave to the directory that all the other scripts and directories are kept in). '''This settings is available in config.php and it is used when token emails are sent.'''
*'''tempurl:''' This should be set to the URL location of your "/limesurvey/tmp" directory - or to a directory in which you would like LimeSurvey to use to store temporary files, including uploads. This directory must be set to read & write for your webserver (e.g. chmod 755).
*'''imagefiles:''' By default, you should leave this pointing to the URL location of /limesurvey/admin/images - where the images are initially installed. You may, however, prefer to move these images to another location/ If this is the case, point this to the URL directory where they are stored.
*'''homedir:''' This should be set to the physical disk location of your administration scripts - for example "/home/usr/htdocs/limesurvey/admin". Don't add a trailing slash to this entry. The default setting in config.php attempts to detect the default root path of all your documents using the php variable setting <code>{$_SERVER<nowiki>[</nowiki>'DOCUMENT_ROOT']}</code>. In most cases you can leave this and just modify the remainder of this string to match the directory name you have put the LimeSurvey scripts in.
*'''publicdir:''' This should be set to the physical disk location of your 'public scripts'.
*'''tempdir:''' This should be set to the physical disk location of your /limesurvey/tmp directory so that the script can read and write files.
*'''sCKEditorURL:''' url of the fckeditor script.
*'''fckeditexpandtoolbar:''' defines if the fckeditor toolbar should be opened by default.
*'''pdfexportdir:''' This is the directory with the tcpdf.php extensiontcpdf.php.
*'''pdffonts:''' This is the directory for the TCPDF fonts.
</translate>

Optional settings

2017-08-25T19:56:00Z

LimeAJ:

<languages /> <translate>


__TOC__

The following section is addressed to those of you who would like to edit those configuration settings that could not be modified with the help of the GUI (Graphical User Interface) of the LimeSurvey installation. Please bear in mind that all the changes from the LimeSurvey root directory changes are done at your own risk. Nevertheless, in the case in which you are experiencing problems/need further guidance, join the [https://www.limesurvey.org/forum discussion forums] or the [irc://irc.freenode.net/limesurvey|IRC IRC channel] for help from the LimeSurvey community.

=Introduction= 


To modify the configuration settings of the installation, you have to edit the optional settings. They can be found in the /application/config/'''config-defaults.php''', which is located in the LimeSurvey root directory. The default settings of the standard installation can be found in config-defaults.php. Some of them can be overridden by using the [[Global settings]|global settings] dialog, while the others will have to be manually edited.


{{Alert|If you want to change these settings, please do not change them in config-defaults.php, but copy the particular setting/line to /application/config/'''config.php''' in <nowiki>'config'=>array( )</nowiki> and change it there. All the newly modified/introduced settings from the config.php file will overridde the default values from config-defaults.php.}}

When an upgrade occurs, only the config-defaults.php settings are changed. Therefore, editing the config.php file will save your customized settings.


To update/add the LimeSurvey settings in /application/'''config/config.php''', you have to update the config array:
<syntaxhighlight lang="php" enclose="pre">
'config'=>array(
'debug'=>0,
'debugsql'=>0,
'LimeSurveySetting'=>'New value', // Update default LimeSurvey config here
)
</syntaxhighlight>

=Yii settings= 
LimeSurvey uses the Yii framework, which has its own configuration parameters in the application/config/'''config.php''' file. You can also access some specific configuration settings of LimeSurvey via the Yii configuration.


The Yii specific settings are set in the components array:
<syntaxhighlight lang="php" enclose="pre">
'components' => array(
'db' => array(
....
),
'Specific settings'=>array(
....
),
),
</syntaxhighlight>

{{Note|For more information about the Yii framework, please access the [http://www.yiiframework.com/doc-2.0/guide-index.html following link.]}}

==Database settings== 
The database settings are written to config.php by the installer file when you install LimeSurvey for the first time. If needed, you can update this part of the config.php file. Please remember that you do this at your own risk!
See also the [http://www.yiiframework.com/doc/blog/1.1/en/prototype.database#establishing-database-connection Yii documentation], and please remember that LimeSurvey supports only the following types of database: mysql, pgsql, dblib, mssql, and sqlsrv.

==Session settings== 
You can set some session parameters in config.php (check the two examples from below). You can uncomment/add the part needed in config.php. See the [http://www.yiiframework.com/doc/api/1.1/CHttpSession Yii Documentation] for other settings.


If you use SSL ('https') for your LimeSurvey installation, adding the following lines to your config.php will increase the security of the session:
<syntaxhighlight lang="php" enclose="pre"> // Set the cookie via SSL
'session' => array (
'cookieParams' => array(
'secure' => true, // use SSL for cookies
'httponly' => true // Cookies may not be used by other protocols - experimental
),
),
</syntaxhighlight>


If you want to fix the domain for a cookie, use the following syntax in config.php:
<syntaxhighlight lang="php" enclose="pre"> // Set the domain for cookie
'session' => array (
'cookieParams' => array(
'domain' => '.example.org',
),
),
</syntaxhighlight>

==Request settings== 
The request settings are important, but the default settings are already optimized for LimeSurvey usage. To read more about them, see the [http://www.yiiframework.com/doc/api/1.1/CHttpRequest Yii Documentation].


For example, the LimeSurvey request settings configuration may be modified in the following way (at your own risk) :
<syntaxhighlight lang="php" enclose="pre"> // Disable CSRF protection
'request' => array(
'enableCsrfValidation'=>false,
),
</syntaxhighlight>
<syntaxhighlight lang="php" enclose="pre"> // Enforce a certain URL base
'request' => array(
'hostInfo' => 'http://www.example.org/'
),
</syntaxhighlight>
<syntaxhighlight lang="php" enclose="pre"> // Set the cookie domain name for CSRF protection
'request' => array(
'csrfCookie' => array( 'domain' => '.example.com' )
),
</syntaxhighlight>


If you need to update only the url for token emails, set your [[Optional_settings#Advanced_path_settings|publicurl]] in your config.php file.

==URL settings== 
To change the default URL settings, update the urlManager:
<syntaxhighlight lang="php" enclose="pre"> // Use short URL
'urlManager' => array(
'urlFormat' => 'path',
'showScriptName' => false,
),
</syntaxhighlight>
You can also add .html after the survey id in the following way:
<syntaxhighlight lang="php" enclose="pre"> // Use short URL
'urlManager' => array(
'urlFormat' => 'path',
'rules' => array (
'<sid:\d+>' => array('survey/index','urlSuffix'=>'.html','matchValue'=>true),
),
'showScriptName' => false,
),
</syntaxhighlight>
For more information, check the [http://www.yiiframework.com/doc/guide/1.1/en/topics.url Yii documentation].

==Logging settings==

Yii provides different solutions to generate logs. To find out more about them, check the [http://www.yiiframework.com/doc/guide/1.1/en/topics.logging logging special topic]. LimeSurvey uses '1' or '2' by default, which allows every web user to see the logs. You can create your own settings using Yii directly.

For example, a quick solution to log errors and warnings in files is:
<syntaxhighlight lang="php" enclose="pre"> // Log error
'log' => array(
'routes' => array(
'fileError' => array(
'class' => 'CFileLogRoute',
'levels' => 'warning, error',
),
),
),
</syntaxhighlight>

{{Hint|Text=The file is saved by default to <code><nowiki>limesurvey/tmp/runtime/application.log</nowiki></code>, which is located in the LimeSurvey root folder.}}
{{Alert|Yii uses runtime path. By default, the logs are web accessible. They may contain a lot of information from your server. It is better to use a directory that cannot be accessed via the web. You can set it in routes or by updating the [[Optional settings#Yii settings#Runtime path|Runtime path]].}}.

==Runtime path==

[http://www.yiiframework.com/doc/guide/1.1/en/basics.convention#directory The runtime path] must be a readable and writable directory for the “web user”. However, the runtime path contains files with potential security information that are located in the public web access area. LimeSurvey collects these files in the temp directory of the LimeSurvey root directory. In order to eliminate the access to such important data, you can set the runtime path outside the public web access by editing the respective lines in the /application/config/config.php file:

<syntaxhighlight lang="php" enclose="pre">
return array(
'components' => array(
[…]
'runtimePath'=>'/var/limesurvey/runtime/',
'config'=>array(
[…]
)
)
)
</syntaxhighlight>

=General settings= 


*'''sitename''': Gives your survey site a name. This name will appear in the survey list overview and in the administration header. The default value is 'LimeSurvey' and it can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''siteadminemail:''' This is the default email address of the site administrator and it is used for system messages and contact options. This setting is used only as default value and can be overridden in the [[Global settings|global settings]] dialog.
*'''siteadminbounce:''' This is the email address where bounced emails will be sent to. This setting is used only as default value and can be overridden by the [[Global settings|global settings]] dialog.
*'''siteadminname:''' The real name of the site administrator. This setting is used only as default value and can be overridden in the [[Global settings|global settings]] dialog).
*'''proxy_host_name:''' This is the host name of your proxy server (it has to be mentioned if you are behind a proxy and you want to update LimeSurvey using [[ComfortUpdate|ComfortUpdate]]).
*'''proxy_host_port:''' This is the port of your proxy server (it has to be mentioned if you are behind a proxy and you want to update LimeSurvey using [[ComfortUpdate|ComfortUpdate]]).

= Security= 


* '''maxLoginAttempt''': This is the number of attempts a user has to enter the correct password before he or she gets her or his IP address blocked/locked out. The default value is 3 and it can be modified from config.php.
* '''timeOutTime''': If the user enters the password incorrectly for <maxLoginAttempt>, she or he gets locked out for <timeOutTime> seconds. The default value is 10 minutes and it can be modified from config.php.
* '''surveyPreview_require_Auth''': Set to true by default. If you set this to 'false', any person can test your survey using the survey URL, without logging in to the administration panel and without having to activate the survey first. This setting is a default value and can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
* '''usercontrolSameGroupPolicy''': Set to true by default. By default, non-admin users defined in the LimeSurvey management interface will only be able to see users they create or users that belongs to at least one same group. The default value can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''filterxsshtml:''' This setting enables the filtering of suspicious html tags located within surveys, groups, and questions and answer texts in the administration interface. Leave this to 'false' only if you absolutely trust the users you created for the administration of LimeSurvey and if you want to allow these users to be able to use Javascript, Flash Movies, etc. <span class="warning">The super admins never have their HTML filtered</span>. The default value can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''demoMode:''' If this option is set to 'true' in config.php, then LimeSurvey will go into demo mode. The demo mode changes the following things:
** Disables admin user's details and password changing;
** Disables the upload of files on the template editor;
** Disables sending e-mail invitations and reminders;
** Disables the creation of a database dump;
** Disables the ability to modify the following global settings: site name, default language, default HTML leditor mode, XSS filter.

= Resources= 
*'''sessionlifetime:''' Defines the time in seconds after which a survey session expires. It applies only if you are using database sessions. If you do use database sessions, change the parameter in config.php or override the default value from the [[Global settings|global settings]] dialog.
*'''memorylimit:''' This sets how much memory LimeSurvey can access. '128 MB' is the minimum (MB=Megabyte) recommended. If you receive time out errors or have problems generating statistics or exporting files, raise this limit to '256 MB' or higher. If your web server has set a higher limit in config.php, then this setting will be ignored.


<div class="warningbox">'''Please bear in mind that such local settings can always be overruled by the changes done in the global settings dialog'''.</div>


To increase the memory limit to 128M you could also try adding:
*memory_limit = 128M to your server's main php.ini file (recommended, if you have access)
*memory_limit = 128M to a php.ini file in the LimeSurvey root
*php_value memory_limit 128M in a .htaccess file in the LimeSurvey root

=Appearance= 
*'''dropdownthreshold'''{{ObsoleteIn|2.50}}: When "R" is selected for <code>$dropdowns</code>, the administrator is allowed to set a maximum number of options that will be displayed as radio buttons, before converting back to a dropdown list. If there is a question that has a large number of options, displaying all of them at once as radio buttons can look unwieldy, and can become counter-intuitive to users. Setting this to a maximum of, say 25 (which is the default) means that large lists are easier to be used by the administrators for the survey participant.
*'''repeatheadings:''' With the Array type question, often you'll have a lot of subquestions, which - when displayed on screen - take up more than one page. This setting lets you decide how many subquestions should be displayed before repeating the header information for the question. A good setting for this is around 15. If you don't want the headings to repeat at all, set this to 0. This setting is overridden in the [[Global settings|global settings]] dialog {{NewIn|2.05}}.
*'''minrepeatheadings:''' The minimum number of remaining subquestions that are required before repeating the headings in Array questions. The default value is 3 and it can be edited in config.php.
*'''defaulttemplate:''' This setting specifies the default theme used for the 'public list' of surveys. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''defaulthtmleditormode:''' Sets the default mode for the integrated HTML editor. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php. The valid settings are:
** 'inline' - Inline replacement of fields by an HTML editor. Slow but convenient and user friendly;
** 'popup' - Adds an icon that runs the HTML editor in a popup if needed. Faster, but HTML code is displayed in the form;
** 'none'- No HTML editor;
*'''column_style:''' Defines how columns are rendered for survey answers when using [[QS:Display_columns|display_columns]]. It can be edited in the config.php file. The valid settings are:
** 'css' - it uses one of the various CSS methods to create columns (see the template style sheet for details);
** 'ul' - the columns are rendered as multiple floated unordered lists (default);
** 'table' - it uses conventional-tables based layout;
** NULL - it disables the use of columns.

=Language & time= 
*'''defaultlang:''' This should be set to the default language to be used in your administration scripts, and also the default setting for language in the public survey list. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.
*'''timeadjust:''' If your web server is in a different time zone to the location where your surveys will be based, put the difference between your server and your home time zone here. For example, I live in Australia, but I use a US web server. The web server is 14 hours behind my local time zone. So my setting here is "14". In other words, it adds 14 hours to the web servers time. This setting is particularly important when surveys timestamp the responses. This setting can be overridden in the [[Global settings|global settings]] dialog or edited in config.php.

=Survey behavior= 
*'''deletenonvalues:''' Use this feature with caution. By default (a value of 1), irrelevant questions are NULLed in the database. This ensures that the data in your database is internally consistent. However, there are rare cases where you might want to hold onto irrelevant values, in which case you can set the value to 0. For example, you ask the person his gender, and he accidentally says 'female' and then answers some female-specific questions (questions that are conditioned on being female, so are only relevant for women). Then, he realizes his mistake, backs up, sets the gender to 'male', and continues with the survey. Now, the female-specific questions are irrelevant. If <code>$deletenonvalues==1</code>, those irrelevant values will be cleared (NULLed) in the database. If <code>$deletenonvalues==0</code>, his erroneous answers will not be deleted, so they will still be present in the database when you analyze it.
*'''shownoanswer:''' When a radio button/select type question that contains editable answers (i.e.: List, Array questions) is not mandatory and 'shownoanswer' is set to 1, an additional 'No answer' entry is shown - so that participants may choose to not answer the question. Some people prefer this not to be available. This setting can be overridden from the [[Global settings|global settings]] dialog or edited in config.php. Valid values are:
**'0': No;
**'1': Yes;
**'2': The Survey admin can choose.
*'''printanswershonorsconditions:''' This setting determines if the printanswers feature will display entries from questions that were hidden by conditions-branching (Default: 1 = hide answers from questions hidden by conditions).
*'''hide_groupdescr_allinone:''' This setting is relevant for all-in-one surveys using conditions . When this is set to 'true', the group name and description is hidden if all questions in the group are hidden. The default value is 'true' - hides group name and description when all questions in the group are hidden by conditions. It can be edited in config.php.
*'''showpopups:''' Show popup messages if mandatory or conditional questions have not been answered correctly:
** '1'=Show popup message (default);
** '0'=Show message on page instead;
** '-1'=Do not show the message at all (in this case, users will still see the question-specific tips indicating which questions must be answered).

=Development and debugging= 
*'''debug:''' With this setting, you set the PHP error reporting to E_ALL. This means that every little notice, warning or error related to the script is shown. This setting should be only switched to '1' if you are trying to debug the application for any reason. If you are a developer, switch it to '2'. Don't switch it to '1' or '2' in production since it might cause path disclosure. The default value is '0' and it can be edited in config.php.
*'''debugsql:''' Activate this setting if you want to display all SQL queries executed for the script on the bottom of each page. Very useful for the optimization of the the number of queries. In order to activate it, change the default value to '1' from the config.php file.


In the case in which you experience an error in the application, we strongly recommend to activate the debug setting in order to get a more detailed error that you can submit with the bug report:


<syntaxhighlight lang="php" enclose="pre">
'config'=>array(
'debug'=>2,
'debugsql'=>0,
)
</syntaxhighlight>

= Email settings= 


All the settings from below can be overridden in the [[Global settings|global settings]] dialog.
*'''emailmethod:' This determines how email messages are being sent. The following options are available:
**'mail:' it uses internal PHP mailer;
**'sendmail:' it uses sendmail mailer;
**'smtp:' it uses SMTP relaying. Use this setting when you are running LimeSurvey on a host that is not your mail server.
*'''emailsmtphost:' If you use 'smtp' as <code>$emailmethod</code>, then you have to put your SMTP-server here. If you are using Google mail you might have to add the port number like $emailsmtphost = 'smtp.gmail.com:465'.
*'emailsmtpuser:' If your SMTP-server needs authentication then set this to your user name, otherwise it must be blank.
*'emailsmtppassword:' If your SMTP-server needs authentication then set this to your password, otherwise it must be blank.
*'emailsmtpssl:' Set this to 'ssl' or 'tls' to use SSL/TLS for SMTP connection.
*'maxemails:' When sending invitations or reminders to survey participants, this setting is used to determine how many emails can be sent in one bunch. Different web servers have different email capacities and if your script takes too long to send a bunch of emails, the script could time out and cause errors. Most web servers can send 100 emails at a time within the default 30 second time limit for a PHP script. If you get script timeout errors when sending large numbers of emails, reduce the number in this setting. Clicking the 'send email invitation' button from the token control toolbar (not the button situated on the right of each token) sends the <maxemails> number of invitations, then it displays a list of the addresses of the recipients and a warning that ''there are more emails pending than could be sent in one batch. Continue sending emails by clicking below. There are ### emails still to be sent.'' and provides a "continue button" to proceed with the next batch. I.e., the user determines when to send the next batch after each batch gets emailed. It is not necessary to wait with this screen active. The admin could log out and come back at a later time to send the next batch of invites.

= Statistics and response browsing= 
*'''filterout_incomplete_answers:''' Control the default behavior of filtering incomplete answers when browsing or analyzing responses. For a discussion on incomplete responses see our [[Browsing survey results|browsing survey results wiki]]. Since these records can corrupt the statistics, an option is given to switch this filter on or off in several GUI forms. The parameter can be edited in the config.php. The following options are available:
**'show': Allows you to visualize both complete and incomplete answers;
**'filter': It shows only complete answers;
**'incomplete': Show only incomplete answers.
*'''strip_query_from_referer_url''': This setting determines if the referrer URL saves the parameter or not. The default value is 'false' (in this case, the referrer URL saves all parameters). Alternatively, this value can be set to 'true' and the parameter part of the referrer URL will be removed.
*'''showaggregateddata:''' when activated, additional statistical values such as the arithmetic mean and standard deviation are shown. Furthermore, the data is aggregated to get a faster overview. For example, results of scale 1+2 and 4+5 are added to have a general ranking like "good" (1/2), "average" (3) and "bad" (4/5). This only affects question types "A" (5 point array) and "5" (5 point choice).
* '''PDF Export Settings:''' This feature activates PDF export for printable surveys and Print Answers. The PDF export function is totally experimental and the output is far from being perfect. Unfortunately, no support can be given at the moment - if you want to help to fix it, please get in touch with us.
**'usepdfexport': Set '0' to disable and '1' to enable;
**'pdfdefaultfont': It represents the default font that will be used by the pdf export function. The default value is 'auto'. To change it, you have to set it to one of the [https://tcpdf.org/docs/fonts/ PDF core fonts].
**'alternatepdffontfile': It's an array with language keys and their corresponding font. The default font for each language can be replaced in the config.php file;
**'pdffontsize': it shows the font size for normal texts; For the title of the survey, it is <pdffontsize>+4, while for the group title is <pdffontsize>+2. It can be edited in the config.php file or from the [Global settings|global settings]] dialog;
**'notsupportlanguages': it includes a list with the languages for which no PDF font was found. The list includes Amharic ('am'), Sinhala ('si'), and Thai ('th'), and it can be found in the config-defaults.php file;
**'pdforientation': Set 'L' for Landscape or 'P' for portrait format. It can be edited from the config.php file.
*'"Graph setting"'
**'chartfontfile': Sets the font file name that is used to create the statistical charts. The file has to be located in the fonts directory, located in the LimeSurvey root folder. It can be edited in the config.php file;
**'alternatechartfontfile': It's an array with language keys and their corresponding font. It can be edited in the config.php file.
*'''showsgqacode:''' This setting is used at the printable survey feature and defaults to 'false''. If you set ''showsgqacode = 'true';'', the IDs of each question - and answer if applicable - will be shown. These IDs match the column heading at the Lime_survey_12345 table, which holds the answer data for a certain survey. These IDs can be used for a code book for manual database queries.

= [[LDAP settings]]= 


As this is an extensive topic we have moved [[LDAP settings]] to [[LDAP settings|another page.]]

= Authentication= 


Starting with LimeSurvey 2.05, authentication will be handled by plugins. As a result, the information below might be outdated. See [[Plugins]] for most up to date information.

== Authentication delegation to the webserver== 


System administrators may want to have their '''survey administrators''' authenticated against a central authentication system (Active Directory, openLdap, Radius, ...) rather than using the internal LimeSurvey database. An easy way to do this is to setup your web server software to use this external authentication system, and then ask LimeSurvey to trust the user identity reported by the web server. In order to enable this feature, you have to:
* set '''auth_webserver''' to 'true' in config.php;
* enable authentication from the web server side.


Please note that:
* LimeSurvey will then bypass its own authentication process (by using the login name reported by the web server without asking for a password);
* this can only replace the LimeSurvey GUI authentication system, '''not the survey invitation system''' (participant interface).

== Authentication delegation with no automatic user import== 


Please note that <u>Authentication Delegation doesn't bypass the LimeSurvey authorization system by default</u> - meaning that, even if you don't have to manage passwords in LimeSurvey, you still need to define the users in the LimeSurvey database and assign them the correct set of rights in order to let them access the administration panel.


A user is then granted access to LimeSurvey if and only if:
* he has been authenticated to the web server;
* his login name is defined as a user in the LimeSurvey user database (the user is then granted the privileges of the user defined in the LimeSurvey user database).

== Authentication delegation with automatic user import== 


When managing a huge user database, it is sometimes easier to auto-import users in the LimeSurvey database:
*'''auth_webserver_autocreate_user''': If set to 'true', LimeSurvey will try to auto-import users authenticated by the web server but not already in its users DB.
*'''auth_webserver_autocreate_profile''': An array describing the default profile that will be assigned to the user, including the full (fake) name, email, and privileges.


If you want to customize the user profile so that it matches the logged-in user, you'll have to develop a simple function called '''hook_get_autouserprofile''' - with this function you can retrieve from a central user account database (for instance, from a LDAP directory) the true full name, names, and email of a particular user. You can even customize his privileges on the system based on the groups he is allocated in the external database.


The '''hook_get_auth_webserver_profile''' function takes the user login name as the only argument and can return:
* False or an empty array - in this case the user is denied access to LimeSurvey;
* an array containing all common userprofile entries as described in the <code>$WebserverAuth_autouserprofile</code>

</translate><syntaxhighlight lang="php" enclose="div">function hook_get_auth_webserver_profile($user_name)
{
// Retrieve user's data from your database backend (for instance LDAP) here
... get $user_name_from_backend
... get $user_email_from_backend
... get $user_lang_from_backend
... from groups defined in your backend set $user_admin_status_frombackend_0_or_1
return Array(
'full_name' => "$user_name_from_backend",
'email' => "$user_email_from_backend",
'lang' => '$user_lang_from_backend',
'htmleditormode' => 'inline',
'templatelist' => 'default,basic,MyOrgTemplate',
'create_survey' => 1,
'create_user' => 0,
'delete_user' => 0,
'superadmin' => $user_admin_status_frombackend_0_or_1,
'configurator' =>0,
'manage_template' => 0,
'manage_label' => 0);
}

// If user should be denied access, return an empty array

// return Array();</syntaxhighlight><translate>

{{Alert|The optionnal 'hook_get_auth_webserver_profile' function is for advanced user usage only! For further details, please read the comments from the config-defaults.php file.}}

== User name mapping== 


In the case in which some users have an external user name that is different from their LimeSurvey user name, you may find useful to use a user name mapping. This is done in LimeSurvey by using the '''auth_webserver_user_map''' parameter. For instance, imagine you don't have an 'admin' user name defined in your external authentication database. Then, in order to login to LimeSurvey as admin, you'll have to map your external user name (let's call it 'myname') to the admin login name in LimeSurvey. The corresponding setup is:

</translate>
<syntaxhighlight lang="php" enclose="div">'config'=>array(
...
'auth_webserver_user_map' => array ('myname' => 'admin');
)</syntaxhighlight><translate>


After a successful authentication with the 'myname' login and web server password, you'll be directly authorized to use LimeSurvey as the 'admin' user.


This obviously has serious security implications, so use it with care, and please protect your config.php from write access by the web server.

== Use one-time passwords== 


A user can open the LimeSurvey login page at default.com/limesurvey/admin and type the username and the one-time password which was previously written into the users table (column one_time_pw) by an external application.


This setting has to be turned on (<code>config['use_one_time_passwords'] = true;</code>) to enable the usage of one-time passwords (default = false). More information can be found in the [[Manage users#Use one-time passwords|"Manage Users" section]].

= Advanced path settings= 


*'''homeurl:''' This should be set to the URL location of your administration scripts. These are located in the /limesurvey/admin folder. This should be set to the WEB URL location - for example, "http://www.example.com/limesurvey/html/admin". Don't add a trailing slash to this entry. The default setting in config.php attempts to detect the name of your server automatically using a php variable setting - <code>{$_SERVER<nowiki>[</nowiki>'SERVER_NAME']}</code>. In most cases you can leave this and just modify the remainder of this string to match the directory name you have put the LimeSurvey scripts in.
*'''publicurl:''' This should be set to the URL location of your 'public scripts'. The public scripts are those located in the "limesurvey" folder (or whatever name you gave to the directory that all the other scripts and directories are kept in). '''This settings is available in config.php and it is used when token emails are sent.'''
*'''tempurl:''' This should be set to the URL location of your "/limesurvey/tmp" directory - or to a directory in which you would like LimeSurvey to use to store temporary files, including uploads. This directory must be set to read & write for your webserver (e.g. chmod 755).
*'''imagefiles:''' By default, you should leave this pointing to the URL location of /limesurvey/admin/images - where the images are initially installed. You may, however, prefer to move these images to another location/ If this is the case, point this to the URL directory where they are stored.
*'''homedir:''' This should be set to the physical disk location of your administration scripts - for example "/home/usr/htdocs/limesurvey/admin". Don't add a trailing slash to this entry. The default setting in config.php attempts to detect the default root path of all your documents using the php variable setting <code>{$_SERVER<nowiki>[</nowiki>'DOCUMENT_ROOT']}</code>. In most cases you can leave this and just modify the remainder of this string to match the directory name you have put the LimeSurvey scripts in.
*'''publicdir:''' This should be set to the physical disk location of your 'public scripts'.
*'''tempdir:''' This should be set to the physical disk location of your /limesurvey/tmp directory so that the script can read and write files.
*'''sCKEditorURL:''' url of the fckeditor script.
*'''fckeditexpandtoolbar:''' defines if the fckeditor toolbar should be opened by default.
*'''pdfexportdir:''' This is the directory with the tcpdf.php extensiontcpdf.php.
*'''pdffonts:''' This is the directory for the TCPDF fonts.
</translate>

RemoteControl 2 API

2017-08-25T15:56:14Z

LimeAJ: /* PHP Example */

__TOC__

=Introduction=

LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or more recent which offers '''various [https://api.limesurvey.org/classes/remotecontrol_handle.html API functions]'''.

LSRC2 makes it possible for developers to control specific functionality of LimeSurvey from any other application, without being restricted to PHP as a programming language.

The following features are planned:
* start a predefined survey (change titles and things)
* add predefined groups or questions
* activate the survey, restrict it to start and endtime
* make it closed,
* add participant data/tokens when you need them
* return the unused tokens to the main application
* get a fieldmap for a survey,
* invite or remind the participants of your survey

...and much more

==Requirements==
* libXML installed

=Setup=

== How to configure LSRC2==

In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to [[Global settings]], choose the tab 'Interfaces' and select one of the two RPC services (XML-RPC or JSON-RPC) service.

== Security==

LSRC2 uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also LSRC2 is protected against brute-force password cracking - like the normal administration login.

=How to use LSRC2=

The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol

LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC version 1 specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.

LSRC2 offers a lot of functions. Please check the automatically generated [http://api.limesurvey.org/classes/remotecontrol_handle.html API Documentation].
LSRC2 offers the following functions:

== Sessions ==

=== get_session_key ===

Using this function you can create a new XML/JSON-RPC session key. This is mandatory for all following LSRC2 function calls.

<source lang=php>
function get_session_key(string $username, string $password)
</source>

'''Return on success''': (string) session key.

'''Return on error''': for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.

=== release_session_key ===

Using this function you can close a previously opened XML-RPC/JSON-RPC session.

<source lang=php>
function release_session_key(string $sSessionKey)
</source>

{| class="wikitable"
! Parameter !! Description
|-
| sSessionKey || Auth credentials
|-
|}

'''Return''': Always 'OK' (string)

== Other functions ==

{{Alert|For all other function , you have to refer to the [http://api.limesurvey.org/classes/remotecontrol_handle.html online API ] . If your LimeSurvey version is outdated, you can publish your API and look at it directly.}}

= Example and helper =

== PHP Example ==

To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository]. The library can also get included by composer calling

<source lang=bash>
composer require weberhofer/jsonrpcphp
</source>

or by inclusion of the following lines in your composer.json file:

<source lang=javascript>
{
"require": {
"weberhofer/jsonrpcphp": "~2"
}
}
</source>

This is a example how to connect to limesurvey:

<source lang="php">
<?php

// without composer this line can be used
// require_once 'path/to/your/rpcclient/jsonRPCClient.php';
// with composer support just add the autoloader
include_once 'vendor/autoload.php';

define( 'LS_BASEURL', 'https://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL
define( 'LS_USER', 'rpcuser' );
define( 'LS_PASSWORD', 'mypassword' );

// the survey to process
$survey_id=374699;

// instantiate a new client
$myJSONRPCClient = new \org\jsonrpcphp\JsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );

// receive session key
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );

// receive all ids and info of groups belonging to a given survey
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );
print_r($groups, null );

// release the session key
$myJSONRPCClient->release_session_key( $sessionKey );

</source>

== JAVA example ==
To decode and code your json calls you can use the library gson as you can see in the following example:

<syntaxhighlight lang="java" enclose="div">
import java.io.IOException;
import java.io.UnsupportedEncodingException;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class TestHttpClient {

public static String parse(String jsonLine) {
JsonElement jelement = new JsonParser().parse(jsonLine);
JsonObject jobject = jelement.getAsJsonObject();
String result = jobject.get("result").getAsString();
return result;
}

public static void main(String[] args) throws UnsupportedEncodingException {
DefaultHttpClient client = new DefaultHttpClient();

HttpPost post = new HttpPost("https://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");
post.setHeader("Content-type", "application/json");
post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": [\"YOUR_USERNAME\", \"YOUR_PASSWORD\" ], \"id\": 1}"));
try {
HttpResponse response = client.execute(post);
if(response.getStatusLine().getStatusCode() == 200){
HttpEntity entity = response.getEntity();
String sessionKey = parse(EntityUtils.toString(entity));
post.setEntity( new StringEntity("{\"method\": \"list_groups\", \"params\": [ \""+sessionKey+"\", \"ID_SURVEY\" ], \"id\": 1}"));
response = client.execute(post);
if(response.getStatusLine().getStatusCode() == 200){
entity = response.getEntity();
System.out.println(EntityUtils.toString(entity));
}
}

} catch (IOException e) {
e.printStackTrace();
}
}}

</syntaxhighlight>

== Python example and glue ==

* [https://github.com/TaiSHiNet/lime-py-api LimeSurvey API - Python 2 glue]
* [https://github.com/lindsay-stevens/limesurveyrc2api LimeSurvey API - Basic client library in Python 3]. Includes tests. Listed on Pypi: pip install limesurveyrc2api

The following code runs with Python 2 and requires some adaptation to work with Python 3.

<syntaxhighlight lang="python" enclose="div">
import urllib
import urllib2
import json
import sys
# There is an generic json-rpc implemantation in Python but it dose not work for me in this case so I worte Some functions

def get_session_key():
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"get_session_key\",\"params\":[\"admin\",\"mypassword\"],\"id\":1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def get_question_properties(skey,QuestionID):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"get_question_properties\",\"params\":[\"'+skey+'\",'+QuestionID
+',[\"gid\",\"type\",\"help\",\"language\",\"sid\",\"question_order\",\"question\",\"subquestions\"]],\"id\": 1}')

req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def release_session_key(relkey):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"release_session_key\",\"params\":[\"'+relkey+'\"],\"id\":1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

def export_responses2(skey,sid):
req = urllib2.Request(url='https://myurl/index.php/admin/remotecontrol',\
data='{\"method\":\"export_responses\",\"params\":[\"'+skey+'\",\"'+sid+'\",\"csv\",\"de\",\"full\"],\
"id\": 1}')
req.add_header('content-type', 'application/json')
req.add_header('connection', 'Keep-Alive')
try:
f = urllib2.urlopen(req)
myretun = f.read()
#print myretun
j=json.loads(myretun)
return j['result']
except :
e = sys.exc_info()[0]
print ( "<p>Error: %s</p>" % e )

mykey=get_session_key()
print export_responses2(mykey,'566237').decode('base64')
get_question_properties(mykey,'574')
print release_session_key(mykey)
</syntaxhighlight>

== NodeJS example ==

This script require request, you can include easily with the command
<source lang=bash>
npm install request
</source>

This is a example how to connect to limesurvey:

<source lang="javascript">
var request = require('request');

//******GLOBAL***************
var SESSIONKEY="";
var options = {
url: "https://xxxxxxxxxxxxxxxx/index.php/admin/remotecontrol",
method: "POST",
headers: {
'user-agent': 'Apache-HttpClient/4.2.2 (java 1.5)',
'host': 'xxxxxxxxxxxxxxxx',
'path': '/index.php/admin/remotecontrol',
'connection': 'keep-alive',
'content-type': 'application/json'
}
};

//*******AUTHENTIFICATION*******
options.body = JSON.stringify({method:'get_session_key',params:['myusername','mypassword'],id:1});

request(options, function(error, response, body){
if (!error && response.statusCode == 200) {
body = JSON.parse(body);

//*********KEEP THE KEY*********
if(SESSIONKEY==="") {
console.log("NEW KEY -->"+body.result);
SESSIONKEY=body.result;
nextFonction();
}
}
else console.log("ERROR -->"+body);
});

</source>

== R example and helper ==

The easiest way to use lsrc2 is by means of the limer package, See https://github.com/cloudyr/limer

Example of usage of this client
<source lang=R>
# first limer (check version: must be recent) must be installed
if(!require("devtools")) {
install.packages("devtools")
library("devtools")
}
install_github("cloudyr/limer")
#############################################################

library(limer)

#change the next options (website, user, password)
options
(lime_api = 'https://www.XXX.nl/index.php/admin/remotecontrol')
options(lime_username = 'user')
options(lime_password = 'password')
#############################################################

# first get a session access key
get_session_key()

# list all surveys. A dataframe is returned
survey_df<-call_limer(method='list_surveys')
print(survey_df)
# sid surveyls_title startdate expires active
#1 999999 XXXX NA 2016-03-08 15:20:30 Y
#2 999998 XXXX NA <NA> Y

#Read the data of the first survey (sid=999999) into a data.frame.
#Notice that the default sLanguageCode = en, so maybe you have to
#specify another language (here: All languages)
data<- get_responses(iSurveyID= 999999, sLanguageCode= '', sResponseType='short')

</source>

= JSON-RPC notes =

The content-type of the HTTP request must be application/json. Most formatting errors or a failure to set the content-type header will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.

<syntaxhighlight lang="php" enclose="div">Request:

HTTP headers:

content-type=application/json

connection=Keep-Alive

host=mylimesurveyhost.com

content-length=67

user-agent=Apache-HttpClient/4.2.2 (java 1.5)

Post body:

{"method":"get_session_key","params":["admin","mypassword"],"id":1}

Response body:

{"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}</syntaxhighlight>

Authentication plugins

2017-08-14T18:33:15Z

LimeAJ: /* LDAP */

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

Authentication plugins

2017-08-14T18:33:05Z

LimeAJ: /* LDAP */

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

LimeSurvey Manual

2017-08-14T17:33:35Z

LimeAJ:

<languages />
<translate>

<div align="center" style= "margin-top:1em;background-color:#eeffee;-webkit-box-shadow: 0 10px 6px -6px #777;-moz-box-shadow: 0 10px 6px -6px #777;box-shadow: 0 10px 6px -6px #777;">
<span style='font-size:188%'>'''Help us to update this manual!'''</span><br>
<span style=''> This manual is a Wiki - just log in with your LimeSurvey.org account and start editing!</span>
</div>
=General= 


<div style="clear:right;float:right;"><div class="simplebox">
Main Chapters:
*[[Installation]]
*[[Administering LimeSurvey]]
*[[Getting started]]
*[[Creating surveys - introduction]]
*[[Managing surveys]]
*[[Not categorized and advanced features]]
*[[General FAQ]]
*[[LimeSurvey glossary]]
*[[How to design a good survey (guide)]]
*[[Workarounds]]
*[[License]]
*[[Version change log]]
*[[Plugins]]
</div></div>


[https://www.limesurvey.com/ LimeSurvey] allows users to quickly create intuitive, powerful, online question-and-answer surveys that can work for tens to thousands of participants without much effort. The survey software itself is self-guiding for the respondents who are participating. This manual is thus focused at how to install the application, administer the installation, and support survey creators, administrators and report generation users alike.


There has been a big ramp-up in development the last few years leading to many new features and changes. Make sure to upgrade to the [https://www.limesurvey.org/about-limesurvey/download latest version] to make use of the capabilities highlighted here.


Look to the far right for the main chapters of the manual. Otherwise, scroll down further to see the complete table of contents here and go directly to the topic you are interested in.


Still having trouble finding what you want? Don't forget the general '''search box''', our [[General FAQ]] and [[Workarounds]] list, look in our [https://www.limesurvey.org/en/forum/ discussion forums], and check the irc #limesurvey in freenode.


Remember that [https://www.limesurvey.org/ LimeSurvey] is an open-source, free software application. See something missing or incorrect? Then help us fix it. This documentation is a Wiki that can be edited by you or anyone else. Or [https://donate.limesurvey.org donate] to help support the core development group trying to make a difference.

= Manual - Table of contents= 


*[[Installation]]
**[[Optional settings]]
**[[Upgrading from a previous version]]
***[[ComfortUpdate]]
**[[Installation using a command line interface (CLI)]]
**[[Transferring an installation]]
**[[Installation FAQ]]
***[[Installation security hints]]
*[[Getting started]]
**[[First login - your user preferences]]
*[[Administering LimeSurvey]]
**[[Global settings]]
**[[Manage users]]
**[[Manage user groups]]
**[[Label sets]]
**[[The template editor]]
**[[Localisation]]
**[[Survey status screen]]
**[[Central participants database]]
*[[Creating surveys - introduction]]
**[[Survey settings]]
***[[Importing a survey structure]]
***[[Survey security settings]]
**[[Creating a question group]]
***[[Change group order]]
**[[Adding a question]]
***[[Question types]]
****[[Question type - Array]]
****[[Question type - Array by column]]
****[[Question type - Array dual scale]]
****[[Question type - Array (5 point choice)]]
****[[Question type - Array (10 point choice)]]
****[[Question type - Array (Increase-Same-Decrease)]]
****[[Question type - Array (Numbers)]]
****[[Question type - Array (Texts)]]
****[[Question type - Array (Yes-No-Uncertain)]]
****[[Question type - Date]]
****[[Question type - Equation]]
****[[Question type - File upload]]
****[[Question type - Gender]]
****[[Question type - Language switch]]
****[[Question type - Numerical input]]
****[[Question type - Multiple numerical input]]
****[[Question type - Ranking]]
****[[Question type - Text display]]
****[[Question type - Yes-No]]
****[[Question type - Multiple choice]]
****[[Question type - Multiple choice with comments]]
****[[Question type - 5 point choice]]
****[[Question type - List (Dropdown)]]
****[[Question type - List (Radio)]]
****[[Question type - List with comment]]
****[[Question type - Short free text]]
****[[Question type - Long free text]]
****[[Question type - Huge free text]]
****[[Question type - Multiple short text]]
***[[Change question order]]
***[[Question preview]]
***[[Adding answers or subquestions]]
**[[Setting conditions]]
***[[Expression Manager]]
****[[Expression Manager for developers]]
****[[Expression Manager how-tos]]
****[[Expression Manager roadmap]]
****[[Expression Manager examples]]
****[[Expression Manager sample surveys]]
***[[Show logic file]]
**[[Assessments]]
**[[Quotas]]
**[[Email templates]]
*[[Managing surveys]]
**[[Testing a survey]]
**[[Activating a survey]]
**[[Running a survey safely]]
**[[Browsing survey results]]
**[[Closing a survey]]
**[[Changing an active survey]]
**[[Survey participants]] (was: Tokens)
***[[Email bounce tracking system]]
**[[Iterate survey]]
**[[Data entry]]
**[[Statistics]]
**[[Exporting results]]
**[[Exporting a survey structure]]
***[[Tab Separated Value survey structure]]
**[[QueXML PDF Export]]
**[[Quick-translation]]
*[[Not categorized and advanced features]]
**[[SGQA identifier]]
**[[Using regular expressions]]
**[[URL fields]]
**[[RemoteControl 2 API]]
*[[General FAQ]]
*[[Troubleshooting]]
*[[LimeSurvey glossary]]
*[[How to design a good survey (guide)]]
*[[Workarounds]]
**[[Workarounds: Question design, layout and templating]]
**[[Workarounds: Manipulating a survey at runtime using Javascript]]
**[[Workarounds: Survey behaviour]]
**[[Workarounds: Further solutions provided by LimeSurvey users]]
*[[License]]
*[[Version change log]]
*[[Plugins]]
**[[Authentication plugins]]
**[[Available third party plugins]]

=LimeSurvey development= 
*[[Development overview]] - General pages about LimeSurvey development
*[[LimeSurvey 2.x development documentation]]

=Translating LimeSurvey= 


If you want to '''add new translations''' or '''correct a translation''' please follow these instructions:
*[[Translating LimeSurvey|How to translate LimeSurvey]]

=Semester of Code participation= 
*[[Semester of Code 2014]]

=Google Summer of Code / Code-In participation= 
*[[Project ideas for GSoC 2015]]
*[[Project Ideas for GSoC 2013]]
*[[LimeSurvey Google Code-in 2012]]
*[[LimeSurvey Google Code-in 2011]]
*[[LimeSurvey GSoC 2011]]/[[GSoC getting started]]
*[[LimeSurvey GSoC 2010]]
*[[LimeSurvey GSoC 2009]]

</translate>

Authentication plugins

2017-08-14T17:08:35Z

LimeAJ: /* LDAP */

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.

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

Authentication plugins

2017-08-14T17:06:44Z

LimeAJ: /* LDAP */

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

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

Authentication plugins

2017-08-14T17:06:27Z

LimeAJ: /* LDAP */

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

Authentication plugins

2017-08-14T14:53:43Z

LimeAJ: /* Internal database */

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 phpinfo.php shows that LDAP is enabled.
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]]

Expression Manager

2017-07-28T20:38:00Z

LimeAJ:

<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 70 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 if you have to re-order questions. EM uses a Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).


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


[[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 in 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 multiple 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', TOKENs, and INSERTANS values
#*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 sub-question-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
#*.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 (1 if true, 0 if false)
#*.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, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*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

==How Backwards Compatible is EM with 1.91+?== 


LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.


One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=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 [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager 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" enclose="div">{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
|}


Note, 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, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

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


You can use all expression manager system for this purpose. It's better to use an [[Question_type_-_Equation|Equation question]] type to this purpose.


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}||{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 sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.


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 sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....


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 sub-question 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 sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==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 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||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[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)
|-
|[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)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|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 <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> 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 prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. 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]]== 

==[[Expression Manager HowTos|Use Cases and HowTos]]== 

==[[Expression Manager Examples|Step-by-Step Examples]].== 

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

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

</translate>

Expression Manager

2017-07-28T20:37:40Z

LimeAJ: Improved explanation of the meaning for "NAOK".

<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 70 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 if you have to re-order questions. EM uses a Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).


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


[[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 in 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 multiple 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', TOKENs, and INSERTANS values
#*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 sub-question-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
#*.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 (1 if true, 0 if false)
#*.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, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*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

==How Backwards Compatible is EM with 1.91+?== 


LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.


One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=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 [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager 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" enclose="div">{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
|}


Note, 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, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

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


You can use all expression manager system for this purpose. It's better to use an [[Question_type_-_Equation|Equation question]] type to this purpose.


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}||{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 sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.


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 sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....


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 sub-question 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 sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==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 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||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[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)
|-
|[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)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|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 <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> 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 prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. 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]]== 

==[[Expression Manager HowTos|Use Cases and HowTos]]== 

==[[Expression Manager Examples|Step-by-Step Examples]].== 

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

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

</translate>

Expression Manager

2017-07-04T17:22:48Z

LimeAJ:

<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 70 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 if you have to re-order questions. EM uses a Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).


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


[[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 in 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 multiple 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', TOKENs, and INSERTANS values
#*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 sub-question-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
#*.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 (1 if true, 0 if false)
#*.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, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*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

==How Backwards Compatible is EM with 1.91+?== 


LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.


One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=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 [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager 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" enclose="div">{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
|}


Note, 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, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

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


You can use all expression manager system for this purpose. It's better to use an [[Question_type_-_Equation|Equation question]] type to this purpose.


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}||{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 sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.


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 sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....


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 sub-question 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 sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Usage of NAOK== 


NAOK --> Not Available / 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 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||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[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)
|-
|[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)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|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 <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> 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 prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. 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]]== 

==[[Expression Manager HowTos|Use Cases and HowTos]]== 

==[[Expression Manager Examples|Step-by-Step Examples]].== 

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

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

</translate>

Question signature

2017-06-29T17:29:25Z

LimeAJ: added missing "by"

=Question signature=

Since question types can no longer be uniquely identified by their object names, we have created a signature scheme.

While in a single limesurvey instance question objects must be uniquely named, there might be different plugins defining the question objects with the same name.

To make sure we can identify what the type of a question is, we derive a unique identifier (GUID) from a signature.

Each question object MUST therefore define a protected static $signature field. This field is used to derive the signature using a hashing approach.

It is the developer's task to make this signature as unique as possible, yet, it MUST never change. If the signature of a question object changes it is recognized as a new question type, while this is not necessarily a problem, the fact that the old question type is no longer available is. Since LimeSurvey cannot find the old question type it will not be able to execute, import, or maybe even edit, surveys containing this now unknown question type.

An example of a signature is shown below:

<syntaxhighlight lang="php" enclose="div">

protected static $signature = array(

'orignalAuthor' => 'Sam Mousa',

'originalName' => 'Yes / No',

'startDev' => '2013-30-1'

);

</syntaxhighlight>

Note that you are free to use any format / data type you want. The GUID is derived using the following code:

<syntaxhighlight lang="php" enclose="div">

/**
* This function derives a unique identifier for identifying a question type.
*/

public static function getGUID()

{

// We use json_encode because it is faster than serialize.

return md5(json_encode(static::$signature));

}

</syntaxhighlight>

Expression Manager

2017-06-07T13:40:03Z

LimeAJ:

<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 70 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 if you have to re-order questions. EM uses a Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).


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


[[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 in 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 multiple 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', TOKENs, and INSERTANS values
#*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 sub-question-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
#*.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 (1 if true, 0 if false)
#*.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, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*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

==How Backwards Compatible is EM with 1.91+?== 


LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.


One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=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 [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager 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" enclose="div">{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
|}


Note, 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, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

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


You can use all expression manager system for this purpose. It's better to use an [[Question_type_-_Equation|Equation question]] type to this purpose.


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}||{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 sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.


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 sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....


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 sub-question 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 sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Usage of NAOK== 


NAOK --> Not Available / 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 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||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[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)
|-
|[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)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|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 <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> 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 prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. 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]]== 

==[[Expression Manager HowTos|Use Cases and HowTos]]== 

==[[Expression Manager Examples|Step-by-Step Examples]].== 

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

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

</translate>

Expression Manager

2017-06-07T13:38:35Z

LimeAJ:

<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 70 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 if you have to re-order questions. EM uses a Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).


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


[[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 in 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 multiple 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', TOKENs, and INSERTANS values
#*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 sub-question-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
#*.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 (1 if true, 0 if false)
#*.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, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*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

==How Backwards Compatible is EM with 1.91+?== 


LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.


One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=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 [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager 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" enclose="div">{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
|}


Note, 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, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

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


You can use all expression manager system for this purpose. It's better to use an [[Question_type_-_Equation|Equation question]] type to this purpose.


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}||{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 sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.


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 sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....


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 sub-question 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 sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Usage of NAOK== 


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 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||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[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)
|-
|[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)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|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 <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> 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 prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. 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]]== 

==[[Expression Manager HowTos|Use Cases and HowTos]]== 

==[[Expression Manager Examples|Step-by-Step Examples]].== 

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

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

</translate>

Question signature

2017-06-05T18:29:52Z

LimeAJ: /* Question signature */

=Question signature=

Since question types can no longer be uniquely identified their object names, we have created a signature scheme.

While in a single limesurvey instance question objects must be uniquely named, there might be different plugins defining the question objects with the same name.

To make sure we can identify what the type of a question is, we derive a unique identifier (GUID) from a signature.

Each question object MUST therefore define a protected static $signature field. This field is used to derive the signature using a hashing approach.

It is the developer's task to make this signature as unique as possible, yet, it MUST never change. If the signature of a question object changes it is recognized as a new question type, while this is not necessarily a problem, the fact that the old question type is no longer available is. Since LimeSurvey cannot find the old question type it will not be able to execute, import, or maybe even edit, surveys containing this now unknown question type.

An example of a signature is shown below:

<syntaxhighlight lang="php" enclose="div">

protected static $signature = array(

'orignalAuthor' => 'Sam Mousa',

'originalName' => 'Yes / No',

'startDev' => '2013-30-1'

);

</syntaxhighlight>

Note that you are free to use any format / data type you want. The GUID is derived using the following code:

<syntaxhighlight lang="php" enclose="div">

/**
* This function derives a unique identifier for identifying a question type.
*/

public static function getGUID()

{

// We use json_encode because it is faster than serialize.

return md5(json_encode(static::$signature));

}

</syntaxhighlight>

Expression Manager

2017-05-31T19:58:59Z

LimeAJ: grammar correction

<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 70 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 if you have to re-order questions. EM uses a Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).


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


[[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 in 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 multiple 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', TOKENs, and INSERTANS values
#*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 sub-question-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
#*.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 (1 if true, 0 if false)
#*.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, sub-question-level relevance (for array_filter and array_filter_exclude), and generated validation equation (for preg and any validation rules like min/max sum/number of values), and all non-blank question attributes.
#*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

==How Backwards Compatible is EM with 1.91+?== 


LimeSurvey 1.92 is fully backwards-compatible with 1.91+ with one exception/caveat: 1.92 handles less-than / greater-than comparisons against empty values differently than 1.91+.


One of the LimeSurvey demo surveys uses a set of conditions that translates to this relevance equation: {(age < 16) or (age == 20) or ... or (age == 80)}. In LimeSurvey 1.91+, (age < 16) is FALSE when there is no answer (the value is blank). However, in LimeSurey 1.92, (age < 16) is TRUE when there is no answer, since both PHP and JavaScript treat blank as 0 in mathematical comparisons. Thus, 1.91+ would hide that question when age was unanswered, but 1.92 would show it. We went to great pains to prevent this, but since we needed to have the Expressions generate identical results in PHP and JavaScript, there was no way to make 1.92 treat "" < 16 as FALSE. Fortunately, there is an easy work-around for this. If you want (age < 16) to be FALSE, then use this expression instead: {(!is_empty(age) and age < 16)}. You can use the new [[Show Logic File|Survey Logic File]] view to quickly identify and fix any such comparisons in your survey.

=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 [[Expression Manager Sample Surveys|sample surveys]].
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager 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" enclose="div">{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
|}


Note, 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, as that makes your intent more clear, and avoids unexpected results if you were expecting strings but got numbers instead (or vice versa).

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


You can use all expression manager system for this purpose. It's better to use an [[Question_type_-_Equation|Equation question]] type to this purpose.


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}||{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 sub-questions have been answered, or summing the scores. Other times, you want to process just certain rows or columns of a question (such as getting the row or column sums and storing them in the database). These reserved variables make that process relatively painless.


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 sub-questions matching pattern X are selected. Note that search is done on complete code identifier, then sq_X match and include subquestions nX, X, Xn (e.g. if you use sq_1, subquestions a1, 1a, 1, 11 or 001 was included). Put attention at dual scale question type where subquestions code are QCODE_SQCODE_1 and QCODE_SQCODE_1 and to ranking question type where subquestions code are QCODE_1,QCODE_2 ....


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 sub-question 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 sub-questions (e.g. single response questions). In those cases, prefixing a variable with 'that' is overkill, and you run the risk of getting unexpected results.

==Usage of NAOK== 


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 :Exprssion 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 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||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)
|-
|[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)
|-
|[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)||returns the text corresponding to the selected option for answer X||this is the same as X.shown
|-
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||
|-
|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 <span> element. Every time a value changes, it recomputes the expression that should appear in that <span> 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 prior page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. 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]]== 

==[[Expression Manager HowTos|Use Cases and HowTos]]== 

==[[Expression Manager Examples|Step-by-Step Examples]].== 

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

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

</translate>

Assessments

2017-05-29T19:12:56Z

LimeAJ: Added some location information, to make it easier for people that don't know fully the navigation of the settings.

<languages /> <translate>

__TOC__


<div class="simplebox">Note: Starting in Version 1.92, you can create more sophisticated assessments and reports using [[Expression Manager|Expression Manager]]. It lets you access all variable types, and easily generate tailored reports at any point in the survey (not just the end). Using the new Equation question type, you can have LimeSurvey automatically save your assessment calculate and/or report to the database</div>

=General= 


LimeSurvey has the ability to create "assessments" on your survey - even for multilingual surveys. Assessments are rules which evaluate the responses to a survey immediately after it is submitted, and then display text blocks to the participant based on that evaluation.


An english sample survey demonstrating the use of assessments at LimeSurvey is available for download. You can import this survey at your LimeSurvey system for testing ("import" tab at survey creation page): [[File:Limesurvey_sample_survey_Assessment.lss]]


As an example, consider the following: You have two questions in your survey, the first question asks if the user smokes: "Do you smoke?". The question has 3 possible answers, "Yes more than 10 per day" with an answer code of "10", "Yes, but less than 10 per day" with an answer code of "5" and "No, I don't smoke at all" with an answer code of "1".


The second question "Do you exercise?" has three possible answers; "Yes, I exercise for at least half an hour three times a week" with a value of "1", "Yes, I exercise every now and then" with a value of "5" and "No, I don't ever do any exercise" with an answer code/value of "10".


If we were to add the totals of the values for each possible answer at the end of the survey, we'd have a good indication of the general health of the respondent. Someone who smokes and doesn't ever do any exercise will have scored 10 in each of their answers, giving a sum of 20 when we add the values together. Someone who doesn't smoke and exercises regularly will have scored 1 in each of the answers with a total of 2 when we add the values together.

=How to use= 

==Activate assessments== 


To be able to see and edit assessments for answers visit the survey settings and change the setting '''Use assessments?''' in the '''[[Creating_a_new_survey#Notification_.26_data_management|Notification & data management]]''' tab to 'On'. After that you will be presented with additional fields when editing answers.


In [[Label sets|label sets]] these fields are always visible.

==Set assessment values for each answer/label== 


[[File:Assesment_value_set.png|thumb|Set the assessment value]]


The assessments tool allows you to set some rules based on the summed assessment values of the questions in the survey, either for the total survey, or for each group within the survey. If you now edit an answer of a question you will see an additional field right beside each code field where you can set an assessment value for this answer.

==How question types are evaluated== 


There are certain [[question types]] which will not be assessed or will be assessed in a special way. Most question types that are not being assessed are convenience question types and can be replaced with a assessable question type - for example a 5 point choice can always be replaced with a simple radio single select question type.

===Question types being assessed=== 
*Array (Flexible labels) dual scale
*Array (Flexible labels)
*Array (Flexible labels) by column
*List (Flexible labels) (Dropdown)
*List (Flexible labels) (Radio)
*List (Dropdown)
*List (Radio)
*List with comment
*Multiple options
*Multiple options with comments

===Question types not being assessed by values set in answers or label set=== 
*Array (Multi Flexible) (Numbers)


With this question type the chosen values in the select boxes will used as the value for assessment.

===Question types not being assessed=== 
* 5 point choice
* Array (5 point choice)
* Array (10 point choice)
* Array (Increase, Same, Decrease)
* Array (Multi flexible) (Text)
* Array (Yes/No/Uncertain)
* Boilerplate question
* Date
* Gender
* Huge free text
* Language switch
* Long free text
* Multiple numerical input
* Numerical input
* Ranking
* Short free text
* Yes/No

==Define assessment rules== 


Now you want to define rules on the assessment values - to do this click the assessment icon [[File:assessments.png]] in one of the menus on the survey administration toolbar. From this screen you can view, edit or delete existing assessments or create new assessments.


In the "Add/Edit" box you can choose the following:
*Scope: The scope of the assessment. Choose either "Total" which will create an assessment based on the sum of all the answers in the entire survey, or "Group" which will create an assessment based on the sum of all the answers in a group (chosen in the next row)
*Group: If the scope of this assessment is for the current "Group", this is where you choose which group to assess.
*Minimum: The minimum "sum" of answers to which this assessment will apply
*Maximum: The maximum "sum" of answers to which this assessment will apply
*Heading: The heading of the assessment which will display if this assessment is shown
*Message: The actual message for this assessment. Inside the message you can use the tags {PERC} or {TOTAL} to show the related score in that particular message.


You can create as many assessments as you like, and you can create more than one assessment to display for a given score.


It is important to note that if you use assessments, you must ensure that you have not chosen to autoload the URL at the end of the survey in the general survey setup, because the assessments only show on the final "completed" page after submitting a survey. This is located in the "Edit survey text elements and settings", under the "Presentation & navigation" settings, and finally a toggle button called "Automatically load URL when survey completes:".

==Assessment placeholders== 


When using assessments the following placeholders are available:
* {PERC}: Displays the score of the current group. Only available at assessment message
* {TOTAL}: Displays the total score. Only available at assessment message
* {ASSESSMENT_CURRENT_TOTAL}{{NewIn|1.86}}: This placeholder can be used within a survey to display the current total score. Keep in mind that the score is only updated when clicking "next" so this is useless in an all-in-one survey. For now, you must create at least one assessment rule for the placeholder to work.

=Tips & tricks= 
* If you '''only want to use the {ASSESSMENT_CURRENT_TOTAL} placeholder''' {{NewIn|1.86}} within a survey without showing an assessment message at the end of the survey you can:
** Use an [[Creating_a_new_survey#General|end URL]] and [[Creating_a_new_survey#Presentation_.26_navigation| activate the auto load end URL setting]] for your survey. Then the user will be directly forwarded to the given URL.

=Video tutorials= 
*[http://www.youtube.com/watch?v=Xe1ipbkJdIw Assessments & Conditions]
</translate>

Assessments

2017-05-29T17:38:23Z

LimeAJ: Value of button is On/Off, instead of Yes/No.

<languages /> <translate>

__TOC__


<div class="simplebox">Note: Starting in Version 1.92, you can create more sophisticated assessments and reports using [[Expression Manager|Expression Manager]]. It lets you access all variable types, and easily generate tailored reports at any point in the survey (not just the end). Using the new Equation question type, you can have LimeSurvey automatically save your assessment calculate and/or report to the database</div>

=General= 


LimeSurvey has the ability to create "assessments" on your survey - even for multilingual surveys. Assessments are rules which evaluate the responses to a survey immediately after it is submitted, and then display text blocks to the participant based on that evaluation.


An english sample survey demonstrating the use of assessments at LimeSurvey is available for download. You can import this survey at your LimeSurvey system for testing ("import" tab at survey creation page): [[File:Limesurvey_sample_survey_Assessment.lss]]


As an example, consider the following: You have two questions in your survey, the first question asks if the user smokes: "Do you smoke?". The question has 3 possible answers, "Yes more than 10 per day" with an answer code of "10", "Yes, but less than 10 per day" with an answer code of "5" and "No, I don't smoke at all" with an answer code of "1".


The second question "Do you exercise?" has three possible answers; "Yes, I exercise for at least half an hour three times a week" with a value of "1", "Yes, I exercise every now and then" with a value of "5" and "No, I don't ever do any exercise" with an answer code/value of "10".


If we were to add the totals of the values for each possible answer at the end of the survey, we'd have a good indication of the general health of the respondent. Someone who smokes and doesn't ever do any exercise will have scored 10 in each of their answers, giving a sum of 20 when we add the values together. Someone who doesn't smoke and exercises regularly will have scored 1 in each of the answers with a total of 2 when we add the values together.

=How to use= 

==Activate assessments== 


To be able to see and edit assessments for answers visit the survey settings and change the setting '''Use assessments?''' in the '''[[Creating_a_new_survey#Notification_.26_data_management|Notification & data management]]''' tab to 'On'. After that you will be presented with additional fields when editing answers.


In [[Label sets|label sets]] these fields are always visible.

==Set assessment values for each answer/label== 


[[File:Assesment_value_set.png|thumb|Set the assessment value]]


The assessments tool allows you to set some rules based on the summed assessment values of the questions in the survey, either for the total survey, or for each group within the survey. If you now edit an answer of a question you will see an additional field right beside each code field where you can set an assessment value for this answer.

==How question types are evaluated== 


There are certain [[question types]] which will not be assessed or will be assessed in a special way. Most question types that are not being assessed are convenience question types and can be replaced with a assessable question type - for example a 5 point choice can always be replaced with a simple radio single select question type.

===Question types being assessed=== 
*Array (Flexible labels) dual scale
*Array (Flexible labels)
*Array (Flexible labels) by column
*List (Flexible labels) (Dropdown)
*List (Flexible labels) (Radio)
*List (Dropdown)
*List (Radio)
*List with comment
*Multiple options
*Multiple options with comments

===Question types not being assessed by values set in answers or label set=== 
*Array (Multi Flexible) (Numbers)


With this question type the chosen values in the select boxes will used as the value for assessment.

===Question types not being assessed=== 
* 5 point choice
* Array (5 point choice)
* Array (10 point choice)
* Array (Increase, Same, Decrease)
* Array (Multi flexible) (Text)
* Array (Yes/No/Uncertain)
* Boilerplate question
* Date
* Gender
* Huge free text
* Language switch
* Long free text
* Multiple numerical input
* Numerical input
* Ranking
* Short free text
* Yes/No

==Define assessment rules== 


Now you want to define rules on the assessment values - to do this click the assessment icon [[File:assessments.png]] in one of the menus on the survey administration toolbar. From this screen you can view, edit or delete existing assessments or create new assessments.


In the "Add/Edit" box you can choose the following:
*Scope: The scope of the assessment. Choose either "Total" which will create an assessment based on the sum of all the answers in the entire survey, or "Group" which will create an assessment based on the sum of all the answers in a group (chosen in the next row)
*Group: If the scope of this assessment is for the current "Group", this is where you choose which group to assess.
*Minimum: The minimum "sum" of answers to which this assessment will apply
*Maximum: The maximum "sum" of answers to which this assessment will apply
*Heading: The heading of the assessment which will display if this assessment is shown
*Message: The actual message for this assessment. Inside the message you can use the tags {PERC} or {TOTAL} to show the related score in that particular message.


You can create as many assessments as you like, and you can create more than one assessment to display for a given score.


It is important to note that if you use assessments, you must ensure that you have not chosen to autoload the URL at the end of the survey in the general survey setup, because the assessments only show on the final "completed" page after submitting a survey.

==Assessment placeholders== 


When using assessments the following placeholders are available:
* {PERC}: Displays the score of the current group. Only available at assessment message
* {TOTAL}: Displays the total score. Only available at assessment message
* {ASSESSMENT_CURRENT_TOTAL}{{NewIn|1.86}}: This placeholder can be used within a survey to display the current total score. Keep in mind that the score is only updated when clicking "next" so this is useless in an all-in-one survey. For now, you must create at least one assessment rule for the placeholder to work.

=Tips & tricks= 
* If you '''only want to use the {ASSESSMENT_CURRENT_TOTAL} placeholder''' {{NewIn|1.86}} within a survey without showing an assessment message at the end of the survey you can:
** Use an [[Creating_a_new_survey#General|end URL]] and [[Creating_a_new_survey#Presentation_.26_navigation| activate the auto load end URL setting]] for your survey. Then the user will be directly forwarded to the given URL.

=Video tutorials= 
*[http://www.youtube.com/watch?v=Xe1ipbkJdIw Assessments & Conditions]
</translate>

Questions - introduction

2017-03-30T13:24:14Z

LimeAJ: by using CSS --> with CSS

<languages /> <translate>


__TOC__

=Introduction= 


Once you have [[Creating a question group|created your groups]], you can start adding questions within each group. Create a new question by clicking on the add icon [[File:add.png]] on the right hand side of the "Group" menu bar.


When adding a question, you will be asked for a "Question Code", the "Question", "Help" and a "(Question Types|question type)". All new questions are assigned to the Group you were viewing when you clicked "Add Question", however you can change the group the question belongs to at a later point.

=Field descriptions= 
*'''Question code:''' Your ID, or number or code for the question. This field is only for quick identification for a question in export or for evaluation. Try to be consistent with your coding in this field. Planning makes your evaluation a lot easier at a later time. This field is normally not displayed to people taking the survey.


<div class="simplebox">Note: The question Code must be unique across the same survey, must start with a letter, and only contain letters and numbers. If you ever tried to export your data to SPSS or R, you discovered that the qcode becomes the value label, so you have to make code unique. For the time-being, LimeSurvey will support legacy code values, but the [[Show Logic File|Show Logic File]] button will color-code such questions so that you know you should change their names.</div>
*'''Question:''' This is the actual question being asked. There is no real limit to the length of the question here, however if you want to explain how to fill out the question, leave that for the "Help" field. HTML-code can be used, e.g., for including images:<br /><nowiki><img src="http://www.yourdomain.com/yourpics/pic.jpg"></nowiki>. The HTML WYSIWYG editor usually helps with the most important tasks, like including images, etc.
*'''Help:''' This is an optional field. It is useful if a question needs some explanation, or you want to explain how it should be answered. When you put text in this field, a "Question Mark" icon appears on the survey entry screens with the help text right beside.
*'''Question type:''' This determines the type of response the survey allows. View the [[Question types]] section for a description of the various options available.
*'''Validation:''' This feature is available on all free text type or numeric questions. You can use standard [[Using regular expressions|Regular Expressions]] in this field to validate the responses to the question, and if the responses don't validate against this expression, the user will be prompted to try again before they can progress.


*'''Other?:''' Depending upon your chosen 'question type' this option may appear. It allows you to specify that an "other" option be presented in some of the list question types.
*'''Mandatory?:''' For all question types this setting allows you to require users to answer the question, before they can move on to the next question. For ranking question this means all items have to be ranked.


*'''Relevance''': This is the Boolean equation that specifies the conditions for this question. If it evaluates to true, the question is show; otherwise it is hidden and since it is irrelevant, data for that question is NULLed in the database. Details about how to use Relevance can be found on the [[Expression Manager|Expression Manager]] pages.


*'''Show advanced question settings:''' The advanced question settings are different for each question type. Please consult the documentation for your particular [[Question types|question type]]

=Importing a question= 


At the bottom of the New Question Form you will find a file selection box to import a question file. Here you can import any question file (*.lsq or *.csv (old format)) you previously exported - for example this is useful if you want to reuse a question from another survey.


<div class="simplebox">Important: If you import a question there will always be a new question created. The original question will not be overwritten. If you want to copy a question inside the same survey it is easier to select the existing question and then use the "Copy current question" button.</div>

=Information from tokens table= 


You can insert information/text from the tokens table into your question so that it can show context related information. For LimeSurvey to do this, the survey needs to be set as NOT Anonymous (ie: tracked), and it needs to have a tokens table.<br /><br />The fields available for this are:<br />


{|
|{TOKEN:FIRSTNAME}||inserts the value from the "firstname" field in the tokens table
|-
|{TOKEN:LASTNAME}||inserts the value from the "lastname" field in the tokens table
|-
|{TOKEN:EMAIL}||inserts the value from the "email" field in the tokens table
|-
|{TOKEN:ATTRIBUTE_1}||inserts the value from the "attribute_1" field in the tokens table
|-
|{TOKEN:ATTRIBUTE_2}||inserts the value from the "attribute_2" field in the tokens table
|}


To use this functionality you must type the field text into your question exactly as listed above.
Example:


Hello {TOKEN:FIRSTNAME}. We sent an email to you using this address {TOKEN:EMAIL}. Is this correct?


Another example with more customisation, but using JavaScript (please see [[Optional settings |Optional settings]] on how to allow JavaScript when setting up questions and why it's not always a good idea. To use JavaScript you will need to deactivate the XSS filter in the [[Global settings]]):


<syntaxhighlight lang="php" enclose="div">Hello {TOKEN:FIRSTNAME}. We sent an email to you using this address {TOKEN:EMAIL}. Is this correct?
What do you as a {TOKEN:ATTRIBUTE_1} think about your
<script type="text/javascript" language="Javascript">;
var job='{TOKEN:ATTRIBUTE_1}';
if (job=='worker') {
document.write ('bosses')
} else {
document.write('workers')
}
</script>
?
</syntaxhighlight>


<div class="simplebox">Starting in Version 1.92, you can use [[Expression Manager|Expression Manager]] to do such tailoring without needing JavaScript. The equivalent in Version 1.92 is the following:</div>


<syntaxhighlight lang="php" enclose="div">What do you as a {TOKEN:ATTRIBUTE_1} think about your {if(TOKEN:ATTRIBUTE_1=='worker','bosses','workers')}?</syntaxhighlight>

=Information from previous answers= 


There is currently also the capacity to insert the answer of previous questions into the text of an answer:
*You can refer to answers on the same page, and even dynamically update tailored messages as responses change on the page.
*You can use question code naming - for more details, see the [[Expression Manager|Expression Manager]] documentation</div>


A wizard has been integrated in the Wysiwyg HTML editor (FCKeditor), so that you can easilly insert previous question/answer codes: this plugin is called the LimeReplacementFields. In order to use this feature, in the FCKeditor, click on the "lime between brackets" icon, and select a question from the select box. Only answers from previous pages are displayed.

[[File:Editor_replacementfields_button.png]]


<div class="simplebox">LimeReplacementFields notice: when you want to delete a reference to a {name} tag, please select all chars from the openning bracket to the closing bracket and press delete: DO NOT erase it char by char with the Delete or Backspace key otherwise the field will appear again.</div>

=Styling Questions= 


It is possible to generally edit the question layout/design with CSS using [[The template editor|the template editor]].

</translate>

Questions - introduction

2017-03-30T13:20:45Z

LimeAJ: grammar correction

<languages /> <translate>


__TOC__

=Introduction= 


Once you have [[Creating a question group|created your groups]], you can start adding questions within each group. Create a new question by clicking on the add icon [[File:add.png]] on the right hand side of the "Group" menu bar.


When adding a question, you will be asked for a "Question Code", the "Question", "Help" and a "(Question Types|question type)". All new questions are assigned to the Group you were viewing when you clicked "Add Question", however you can change the group the question belongs to at a later point.

=Field descriptions= 
*'''Question code:''' Your ID, or number or code for the question. This field is only for quick identification for a question in export or for evaluation. Try to be consistent with your coding in this field. Planning makes your evaluation a lot easier at a later time. This field is normally not displayed to people taking the survey.


<div class="simplebox">Note: The question Code must be unique across the same survey, must start with a letter, and only contain letters and numbers. If you ever tried to export your data to SPSS or R, you discovered that the qcode becomes the value label, so you have to make code unique. For the time-being, LimeSurvey will support legacy code values, but the [[Show Logic File|Show Logic File]] button will color-code such questions so that you know you should change their names.</div>
*'''Question:''' This is the actual question being asked. There is no real limit to the length of the question here, however if you want to explain how to fill out the question, leave that for the "Help" field. HTML-code can be used, e.g., for including images:<br /><nowiki><img src="http://www.yourdomain.com/yourpics/pic.jpg"></nowiki>. The HTML WYSIWYG editor usually helps with the most important tasks, like including images, etc.
*'''Help:''' This is an optional field. It is useful if a question needs some explanation, or you want to explain how it should be answered. When you put text in this field, a "Question Mark" icon appears on the survey entry screens with the help text right beside.
*'''Question type:''' This determines the type of response the survey allows. View the [[Question types]] section for a description of the various options available.
*'''Validation:''' This feature is available on all free text type or numeric questions. You can use standard [[Using regular expressions|Regular Expressions]] in this field to validate the responses to the question, and if the responses don't validate against this expression, the user will be prompted to try again before they can progress.


*'''Other?:''' Depending upon your chosen 'question type' this option may appear. It allows you to specify that an "other" option be presented in some of the list question types.
*'''Mandatory?:''' For all question types this setting allows you to require users to answer the question, before they can move on to the next question. For ranking question this means all items have to be ranked.


*'''Relevance''': This is the Boolean equation that specifies the conditions for this question. If it evaluates to true, the question is show; otherwise it is hidden and since it is irrelevant, data for that question is NULLed in the database. Details about how to use Relevance can be found on the [[Expression Manager|Expression Manager]] pages.


*'''Show advanced question settings:''' The advanced question settings are different for each question type. Please consult the documentation for your particular [[Question types|question type]]

=Importing a question= 


At the bottom of the New Question Form you will find a file selection box to import a question file. Here you can import any question file (*.lsq or *.csv (old format)) you previously exported - for example this is useful if you want to reuse a question from another survey.


<div class="simplebox">Important: If you import a question there will always be a new question created. The original question will not be overwritten. If you want to copy a question inside the same survey it is easier to select the existing question and then use the "Copy current question" button.</div>

=Information from tokens table= 


You can insert information/text from the tokens table into your question so that it can show context related information. For LimeSurvey to do this, the survey needs to be set as NOT Anonymous (ie: tracked), and it needs to have a tokens table.<br /><br />The fields available for this are:<br />


{|
|{TOKEN:FIRSTNAME}||inserts the value from the "firstname" field in the tokens table
|-
|{TOKEN:LASTNAME}||inserts the value from the "lastname" field in the tokens table
|-
|{TOKEN:EMAIL}||inserts the value from the "email" field in the tokens table
|-
|{TOKEN:ATTRIBUTE_1}||inserts the value from the "attribute_1" field in the tokens table
|-
|{TOKEN:ATTRIBUTE_2}||inserts the value from the "attribute_2" field in the tokens table
|}


To use this functionality you must type the field text into your question exactly as listed above.
Example:


Hello {TOKEN:FIRSTNAME}. We sent an email to you using this address {TOKEN:EMAIL}. Is this correct?


Another example with more customisation, but using JavaScript (please see [[Optional settings |Optional settings]] on how to allow JavaScript when setting up questions and why it's not always a good idea. To use JavaScript you will need to deactivate the XSS filter in the [[Global settings]]):


<syntaxhighlight lang="php" enclose="div">Hello {TOKEN:FIRSTNAME}. We sent an email to you using this address {TOKEN:EMAIL}. Is this correct?
What do you as a {TOKEN:ATTRIBUTE_1} think about your
<script type="text/javascript" language="Javascript">;
var job='{TOKEN:ATTRIBUTE_1}';
if (job=='worker') {
document.write ('bosses')
} else {
document.write('workers')
}
</script>
?
</syntaxhighlight>


<div class="simplebox">Starting in Version 1.92, you can use [[Expression Manager|Expression Manager]] to do such tailoring without needing JavaScript. The equivalent in Version 1.92 is the following:</div>


<syntaxhighlight lang="php" enclose="div">What do you as a {TOKEN:ATTRIBUTE_1} think about your {if(TOKEN:ATTRIBUTE_1=='worker','bosses','workers')}?</syntaxhighlight>

=Information from previous answers= 


There is currently also the capacity to insert the answer of previous questions into the text of an answer:
*You can refer to answers on the same page, and even dynamically update tailored messages as responses change on the page.
*You can use question code naming - for more details, see the [[Expression Manager|Expression Manager]] documentation</div>


A wizard has been integrated in the Wysiwyg HTML editor (FCKeditor), so that you can easilly insert previous question/answer codes: this plugin is called the LimeReplacementFields. In order to use this feature, in the FCKeditor, click on the "lime between brackets" icon, and select a question from the select box. Only answers from previous pages are displayed.

[[File:Editor_replacementfields_button.png]]


<div class="simplebox">LimeReplacementFields notice: when you want to delete a reference to a {name} tag, please select all chars from the openning bracket to the closing bracket and press delete: DO NOT erase it char by char with the Delete or Backspace key otherwise the field will appear again.</div>

=Styling Questions= 


It is possible to generally edit the question layout/design by using CSS using [[The template editor|the template editor]].

</translate>

Questions - introduction

2017-03-30T13:20:17Z

LimeAJ: grammar correction

<languages /> <translate>


__TOC__

=Introduction= 


Once you have [[Creating a question group|created your groups]], you can start adding questions within each group. Create a new question by clicking on the add icon [[File:add.png]] on the right hand side of the "Group" menu bar.


When adding a question, you will be asked for a "Question Code", the "Question", "Help" and a "(Question Types|question type)". All new questions are assigned to the Group you were viewing when you clicked "Add Question", however you can change the group the question belongs too at a later point.

=Field descriptions= 
*'''Question code:''' Your ID, or number or code for the question. This field is only for quick identification for a question in export or for evaluation. Try to be consistent with your coding in this field. Planning makes your evaluation a lot easier at a later time. This field is normally not displayed to people taking the survey.


<div class="simplebox">Note: The question Code must be unique across the same survey, must start with a letter, and only contain letters and numbers. If you ever tried to export your data to SPSS or R, you discovered that the qcode becomes the value label, so you have to make code unique. For the time-being, LimeSurvey will support legacy code values, but the [[Show Logic File|Show Logic File]] button will color-code such questions so that you know you should change their names.</div>
*'''Question:''' This is the actual question being asked. There is no real limit to the length of the question here, however if you want to explain how to fill out the question, leave that for the "Help" field. HTML-code can be used, e.g., for including images:<br /><nowiki><img src="http://www.yourdomain.com/yourpics/pic.jpg"></nowiki>. The HTML WYSIWYG editor usually helps with the most important tasks, like including images, etc.
*'''Help:''' This is an optional field. It is useful if a question needs some explanation, or you want to explain how it should be answered. When you put text in this field, a "Question Mark" icon appears on the survey entry screens with the help text right beside.
*'''Question type:''' This determines the type of response the survey allows. View the [[Question types]] section for a description of the various options available.
*'''Validation:''' This feature is available on all free text type or numeric questions. You can use standard [[Using regular expressions|Regular Expressions]] in this field to validate the responses to the question, and if the responses don't validate against this expression, the user will be prompted to try again before they can progress.


*'''Other?:''' Depending upon your chosen 'question type' this option may appear. It allows you to specify that an "other" option be presented in some of the list question types.
*'''Mandatory?:''' For all question types this setting allows you to require users to answer the question, before they can move on to the next question. For ranking question this means all items have to be ranked.


*'''Relevance''': This is the Boolean equation that specifies the conditions for this question. If it evaluates to true, the question is show; otherwise it is hidden and since it is irrelevant, data for that question is NULLed in the database. Details about how to use Relevance can be found on the [[Expression Manager|Expression Manager]] pages.


*'''Show advanced question settings:''' The advanced question settings are different for each question type. Please consult the documentation for your particular [[Question types|question type]]

=Importing a question= 


At the bottom of the New Question Form you will find a file selection box to import a question file. Here you can import any question file (*.lsq or *.csv (old format)) you previously exported - for example this is useful if you want to reuse a question from another survey.


<div class="simplebox">Important: If you import a question there will always be a new question created. The original question will not be overwritten. If you want to copy a question inside the same survey it is easier to select the existing question and then use the "Copy current question" button.</div>

=Information from tokens table= 


You can insert information/text from the tokens table into your question so that it can show context related information. For LimeSurvey to do this, the survey needs to be set as NOT Anonymous (ie: tracked), and it needs to have a tokens table.<br /><br />The fields available for this are:<br />


{|
|{TOKEN:FIRSTNAME}||inserts the value from the "firstname" field in the tokens table
|-
|{TOKEN:LASTNAME}||inserts the value from the "lastname" field in the tokens table
|-
|{TOKEN:EMAIL}||inserts the value from the "email" field in the tokens table
|-
|{TOKEN:ATTRIBUTE_1}||inserts the value from the "attribute_1" field in the tokens table
|-
|{TOKEN:ATTRIBUTE_2}||inserts the value from the "attribute_2" field in the tokens table
|}


To use this functionality you must type the field text into your question exactly as listed above.
Example:


Hello {TOKEN:FIRSTNAME}. We sent an email to you using this address {TOKEN:EMAIL}. Is this correct?


Another example with more customisation, but using JavaScript (please see [[Optional settings |Optional settings]] on how to allow JavaScript when setting up questions and why it's not always a good idea. To use JavaScript you will need to deactivate the XSS filter in the [[Global settings]]):


<syntaxhighlight lang="php" enclose="div">Hello {TOKEN:FIRSTNAME}. We sent an email to you using this address {TOKEN:EMAIL}. Is this correct?
What do you as a {TOKEN:ATTRIBUTE_1} think about your
<script type="text/javascript" language="Javascript">;
var job='{TOKEN:ATTRIBUTE_1}';
if (job=='worker') {
document.write ('bosses')
} else {
document.write('workers')
}
</script>
?
</syntaxhighlight>


<div class="simplebox">Starting in Version 1.92, you can use [[Expression Manager|Expression Manager]] to do such tailoring without needing JavaScript. The equivalent in Version 1.92 is the following:</div>


<syntaxhighlight lang="php" enclose="div">What do you as a {TOKEN:ATTRIBUTE_1} think about your {if(TOKEN:ATTRIBUTE_1=='worker','bosses','workers')}?</syntaxhighlight>

=Information from previous answers= 


There is currently also the capacity to insert the answer of previous questions into the text of an answer:
*You can refer to answers on the same page, and even dynamically update tailored messages as responses change on the page.
*You can use question code naming - for more details, see the [[Expression Manager|Expression Manager]] documentation</div>


A wizard has been integrated in the Wysiwyg HTML editor (FCKeditor), so that you can easilly insert previous question/answer codes: this plugin is called the LimeReplacementFields. In order to use this feature, in the FCKeditor, click on the "lime between brackets" icon, and select a question from the select box. Only answers from previous pages are displayed.

[[File:Editor_replacementfields_button.png]]


<div class="simplebox">LimeReplacementFields notice: when you want to delete a reference to a {name} tag, please select all chars from the openning bracket to the closing bracket and press delete: DO NOT erase it char by char with the Delete or Backspace key otherwise the field will appear again.</div>

=Styling Questions= 


It is possible to generally edit the question layout/design by using CSS using [[The template editor|the template editor]].

</translate>