https://www.limesurvey.org/api.php?action=feedcontributions&feedformat=atom&user=AdminLimeSurvey Manual - User contributions [en]2026-08-10T16:31:42ZUser contributionsMediaWiki 1.43.9https://www.limesurvey.org/manual/index.php?title=Using_regular_expressions&diff=143443Using regular expressions2019-06-28T10:04:28Z<p>Admin: </p>
<hr />
<div><languages /> <translate><br />
<br />
<!--T:1--><br />
__TOC__<br />
<br />
<!--T:2--><br />
Regular Expressions must start and finish with a forward slash ("/"). You can find a good library of regular expressions at http://www.regexlib.net/. These patterns will almost always work if they are surrounded by forward slashes.<br />
<br />
<!--T:3--><br />
To test your regex you can [https://regex101.com/ use this regex tester].<br />
<br />
<!--T:4--><br />
{{Note|To improve this wiki section, we kindly ask you to add your successfully tested regular expression(s) to provide a better understanding of this feature to the new LimeSurvey (potential) users.}}<br />
<br />
<!--T:5--><br />
{{Alert|title=Attention|text= Please note that all the below examples are written on one line!}}<br />
<br />
<br />
=Important: Regular Expressions in conditions= <!--T:6--><br />
<br />
<br />
<!--T:7--><br />
Note that when using regular expressions in the condition editor, do NOT include the beginning and ending slash.<br />
<br />
<br />
=Email validation= <!--T:8--><br />
<br />
<br />
<!--T:123--><br />
Update (12/2018): Since these days domain names cannot only hold special characters like “ü” but also use more than 3 characters as domain name like .''tech'' or .''company'', the below email regex only checks if “@” and “.” exists within the entered email address.<br />
<source lang="html"><br />
/^.+?@.+?\..+$/<br />
</source><br />
At this outdated regex the domain name is limited to 3 characters which doesn't cover all available domains:<br />
<source lang="html"><br />
/^(\w[-._+\w]*\w@\w[-._\w]*\w\.\w{2,3})$/<br />
</source><br />
<br />
=Postcodes= <!--T:13--><br />
<br />
==Australian postcodes:== <!--T:14--><br />
<br />
<!--T:15--><br />
<source lang="html">/^[0-9]{4}/</source><br />
<br />
==Brazilian postcodes== <!--T:16--><br />
<br />
<!--T:17--><br />
<source lang="html">/^[0-9]{2}\.[0-9]{3}-[0-9]{3}$/</source><br />
<br />
==Canadian postcodes== <!--T:18--><br />
<br />
<!--T:19--><br />
<source lang="html">/^[a-zA-Z]\d{1}[a-zA-Z](\-| |)\d{1}[a-zA-Z]\d{1}$/</source><br />
<br />
==US postal codes== <!--T:20--><br />
<br />
<!--T:21--><br />
<source lang="html">/^[0-9]{5}([- /]?[0-9]{4})?$/</source><br />
<br />
For the postal code to start with zero, use:<br />
<br />
<source lang="html">/^[0-9]{5}(?:-[0-9]{4})?$/</source><br />
<br />
==UK postcodes== <!--T:22--><br />
<br />
<!--T:23--><br />
<source lang="html">/^[A-Z][A-Z]?[0-9][A-Z0-9]? ?[0-9][ABDEFGHJLNPQRSTUWXYZ]{2}$/i</source><br />
<br />
<!--T:24--><br />
Note that this is not very exact, and a more exact validation is much more complex. For example, see [https://stackoverflow.com/questions/164979/uk-postcode-regex-comprehensive StackOverflow answer] and [https://en.wikipedia.org/wiki/Talk:Postcodes_in_the_United_Kingdom#Regular_Expressions Wikipedia] for more information.<br />
<br />
==French postcodes== <!--T:133--> <br />
<br />
<!--T:134--><br />
<source lang="html">/(^[0-8]\d\d{3}$)|(^9[0-5]\d{3}$)|(^97[1-6]\d{2}$)|(^98[46-8]\d{2}$)/</source><br />
<br />
<!--T:27--><br />
The above expression is very precise and it will check whether or not the French Department exists (first two digits), including overseas Departments and overseas Territories (DOM-TOM).<br />
<br />
<br />
=Phone numbers= <!--T:25--><br />
<br />
<br />
==US phone numbers== <!--T:26--><br />
<br />
<!--T:135--><br />
<source lang="html">/^(?:\([2-9]\d{2}\)\ ?|[2-9]\d{2}(?:\-?|\ ?))[2-9]\d{2}[- ]?\d{4}$/</source><br />
<br />
<!--T:28--><br />
or<br />
<br />
<!--T:29--><br />
<source lang="html">/^[\(\)\.\- ]{0,}[0-9]{3}[\(\)\.\- ]{0,}[0-9]{3}[\(\)\.\- ]{0,}[0-9]{4}[\(\)\.\- ]{0,}$/</source><br />
<br />
<!--T:30--><br />
This second option will match all phone Canadian and US phone numbers that include non-digit symbols including:<br />
<br />
<!--T:31--><br />
<source lang="html"> . ( ) - (space)</source><br />
<br />
<!--T:32--><br />
This will allow you to match phone numbers which resemble below:<br />
*(555)555 5555<br />
*555.555.5555<br />
*555 555 5555<br />
*(555)-555-5555<br />
*555-555-5555<br />
*555555555<br />
<br />
==Australian phone numbers== <!--T:33--><br />
<br />
<!--T:34--><br />
The following patterns match all various Australian mobile and landline phone numbers including with "+61" country prefix:<br />
*(02) 9123 6535<br />
*03 1234-5345<br />
*0412 345 678<br />
*+61 2 3456 789<br />
<br />
<!--T:35--><br />
But not:<br />
* 234 3450 234<br />
*a234 534 3432<br />
*134567<br />
*123456789013<br />
<br />
<!--T:36--><br />
Brackets, white space and hypens are ignored.<br />
<br />
<!--T:37--><br />
The 'Very precise:' versions listed here match against the first four or five digits in a number to ensure that they are valid Australian numbers.<br />
<br />
<!--T:38--><br />
The 'Not very precise:' only match against the first and second digit so may allow invaid numbers.<br />
<br />
===All Australian phone numbers (mobile and landline - area code required)=== <!--T:39--><br />
<br />
<!--T:40--><br />
Very precise:<br />
<br />
<!--T:41--><br />
<source lang="html">/^\(?(?:\+?61|0)(?:(?:2\)?[ -]?(?:3[ -]?[38]|[46-9][ -]?[0-9]|5[ -]?[0-35-9])|3\)?(?:4[ -]?[0-57-9]|[57-9][ -]?[0-9]|6[ -]?[1-67])|7\)?[ -]?(?:[2-4][ -]?[0-9]|5[ -]?[2-7]|7[ -]?6)|8\)?[ -]?(?:5[ -]?[1-4]|6[ -]?[0-8]|[7-9][ -]?[0-9]))(?:[ -]?[0-9]){6}|4\)?[ -]?(?:(?:[01][ -]?[0-9]|2[ -]?[0-57-9]|3[ -]?[1-9]|4[ -]?[7-9]|5[ -]?[018])[ -]?[0-9]|3[ -]?0[ -]?[0-5])(?:[ -]?[0-9]){5})$/<br />
</source><br />
<br />
<!--T:42--><br />
Not very precise:<br />
<br />
<!--T:43--><br />
<source lang="html">/^(?:\+?61|0)[2-478](?:[ -]?[0-9]){8}$/</source><br />
<br />
===All Australian phone numbers (landlines only - area code required)=== <!--T:44--><br />
<br />
<!--T:45--><br />
Very precise:<br />
<br />
<!--T:46--><br />
<source lang="html">/^\(?(?:\+?61|0)(?:2\)?[ -]?(?:3[ -]?[38]|[46-9][ -]?[0-9]|5[ -]?[0-35-9])|3\)?(?:4[ -]?[0-57-9]|[57-9][ -]?[0-9]|6[ -]?[1-67])|7\)?[ -]?(?:[2-4][ -]?[0-9]|5[ -]?[2-7]|7[ -]?6)|8\)?[ -]?(?:5[ -]?[1-4]|6[ -]?[0-8]|[7-9][ -]?[0-9]))(?:[ -]?[0-9]){6}$/</source><br />
<br />
<!--T:47--><br />
Not very precise:<br />
<br />
<!--T:48--><br />
<source lang="html">/^(?:\+?61|\(?0)[2378]\)?(?:[ -]?[0-9]){8}$/</source><br />
<br />
===New South Wales landline phone numbers (area code optional)=== <!--T:49--><br />
<br />
<!--T:50--><br />
Very precise:<br />
<br />
<!--T:51--><br />
<source lang="html">/^(?:\(?(?:\+?61|0)2\)?[ -]?)?(?:3[ -]?[38]|[46-9][ -]?[0-9]|5[ -]?[0-35-9])(?:[ -]?[0-9]){6}$/</source><br />
<br />
<!--T:52--><br />
Not very precise:<br />
<br />
<!--T:53--><br />
<source lang="html">/^(?:\(?(?:\+?61|0)2\)?(?:[ -]?[0-9]){7}[0-9]$/</source><br />
<br />
===Victorian and Tasmanian landline phone numbers (area code optional)=== <!--T:54--><br />
<br />
<!--T:55--><br />
Very precise:<br />
<br />
<!--T:56--><br />
<source lang="html">/^(?:\(?(?:\+?61|0)3\)?[ -]?)?(?:4[ -]?[0-57-9]|[57-9][ -]?[0-9]|6[ -]?[1-67])(?:[ -]?[0-9]){6}$/</source><br />
<br />
<!--T:57--><br />
Not very precise:<br />
<br />
<!--T:58--><br />
<source lang="html">/^(?:\(?(?:\+?61|0)3\)?(?:[ -]?[0-9]){7}[0-9]$/</source><br />
<br />
===Queensland landline phone numbers (area code optional)=== <!--T:59--><br />
<br />
<!--T:60--><br />
Very precise:<br />
<br />
<!--T:61--><br />
<source lang="html">/^(?:\(?(?:\+?61|0)7\)?[ -]?)?(?:[2-4][ -]?[0-9]|5[ -]?[2-7]|7[ -]?6)(?:[ -]?[0-9]){6}$/</source><br />
<br />
<!--T:62--><br />
Not very precise:<br />
<br />
<!--T:63--><br />
<source lang="html">/^(?:\(?(?:\+?61|0)7\)?(?:[ -]?[0-9]){7}[0-9]$/</source><br />
<br />
===South Australia, Northern Territory, Western Australia landline phone numbers (area code optional)=== <!--T:64--><br />
<br />
<!--T:65--><br />
Very precise:<br />
<br />
<!--T:66--><br />
<source lang="html">/^(?:\(?(?:\+?61|0)8\)?[ -]?)?(?:5[1-4]|6[0-8]|[7-9][0-9])$/</source><br />
<br />
<!--T:67--><br />
Not very precise:<br />
<br />
<!--T:68--><br />
<source lang="html">/^(?:\(?(?:\+?61|0)8\)?(?:[ -]?[0-9]){7}[0-9]$/</source><br />
<br />
===Australian mobile phone numbers only=== <!--T:69--><br />
<br />
<!--T:70--><br />
Very precise:<br />
<br />
<!--T:71--><br />
<source lang="html">/^(?:\+?61|0)4 ?(?:(?:[01] ?[0-9]|2 ?[0-57-9]|3 ?[1-9]|4 ?[7-9]|5 ?[018]) ?[0-9]|3 ?0 ?[0-5])(?: ?[0-9]){5}$/</source><br />
<br />
<!--T:72--><br />
Not very precise:<br />
<br />
<!--T:73--><br />
<source lang="html">/^(?:\(?(?:\+?61|0)4\)?(?:[ -]?[0-9]){7}[0-9]$/</source><br />
<br />
==Belgian phone number== <!--T:74--><br />
<source lang="html">/^((\+|00)32\s?|0)(\d\s?\d{3}|\d{2}\s?\d{2})(\s?\d{2}){2}$/</source><br />
==Belgian mobile phone number==<br />
<source lang="html">/^((\+|00)32\s?|0)4(60|[789]\d)(\s?\d{2}){3}$/</source><br />
==French phone number==<br />
<source lang="html">/^((\+|00)33\s?|0)[1-59](\s?\d{2}){4}$/</source><br />
==French mobile phone number==<br />
<source lang="html">/^((\+|00)33\s?|0)[67](\s?\d{2}){4}$/</source><br />
==Luxemburg phone number==<br />
<source lang="html">/^((\+|00\s?)352)?(\s?\d{2}){3,4}$/</source><br />
==Luxemburg mobile phone number==<br />
<source lang="html">/^((\+|00\s?)352)?\s?6[269]1(\s?\d{3}){2}$/</source><br />
=German marks (with optional plus or minus)=<br />
<source lang="html">/^[1-6]{1}[\+|\-]?$/</source><br />
<br />
<br />
=Age validation= <!--T:136--><br />
<br />
<br />
<!--T:137--><br />
Example: Age 20-99<br />
<source lang="html">/([2-9][0-9])/</source><br />
<br />
<!--T:124--><br />
Example: Age 18-35<br />
<source lang="html">/(1[8-9]|2[0-9]|3[0-5])/</source><br />
<br />
<!--T:125--><br />
Example: Age 19-65<br />
<source lang="html">/^(1[8-9]|[2-5][0-9]|6[0-5])$/</source><br />
<br />
<br />
=Number validation= <!--T:138--> <br />
<br />
<br />
==Numbers from 1 to 99999== <!--T:126--><br />
<source lang="html">/^([1-9]|[1-9][0-9]|[1-9][0-9][0-9]|[1-9][0-9][0-9][0-9]|[1-9][0-9][0-9][0-9][0-9])$/</source><br />
<source lang="html">/^[1-9][0-9]{0,4}$/ does the same as above but should run a little faster</source><br />
==Numbers from 1 to 999, 1.000 to 999.999 to 999.999.999==<br />
<source lang="html">/^[1-9][0-9]{0,2}(?:\.[0-9]{3}){0,2}$/</source><br />
Accepts numbers from 1 to 999, 1.000 to 999.999 to 999.999.999 but<br />
rejects numbers like 999.1.1 , 94.22.22, 999.1.22, 999.11.1, 999.1.333<br />
<br />
==Number validation with optional decimal (for price)== <!--T:127--><br />
Accepts numbers from 0 to 199, with 2 decimal optional:<br />
<source lang="html">/^([1][0-9][0-9]|[1-9][0-9]|[0-9])((\.)[0-9][0-9])?$/</source><br />
<br />
==Number validation with thousand separator==<br />
Space as separator, no minus<br />
<source lang="html">/^(?!0)\d{1,3}(\ \d{3})*$/</source><br />
Dot as separator, minus allowed<br />
<source lang="html">/^-?(?!0)\d{1,3}(\.\d{3})*$/</source><br />
<br />
<!--T:128--><br />
It forces two decimal points and accepts numbers from 1.00 to 999,999,999.00 with an optional comma delimiting thousands/millions<br />
including all of the following: 1.00, 1,000.00, 12,345.67, 12345,02, 123,456,468.00, 1234566.00, 123456789.00<br />
but not 1,23.00, 12,3.4 or 1234,43.04<br />
<source lang="html">/^[1-9][0-9]{0,2}(?:,?[0-9]{3}){0,3}\.[0-9]{2}$/</source><br />
<br />
Similar to the above: Forces two decimal points but accepts a "0" before decimal separator ",".<br />
<source lang="html">/[0-9]{0,2}(?:,?[0-9]{3}){0,3}\.[0-9]{2}$/</source><br />
<br />
<!--T:129--><br />
Same as above, but the two decimal points are optional:<br />
<source lang="html">/^[1-9][0-9]{0,2}(?:,?[0-9]{3}){0,3}(?:\.[0-9]{2})?$/ </source><br />
<br />
==Month (1-12)== <!--T:75--><br />
<br />
<!--T:76--><br />
If you want to ask for the month a person was born you can validate the input as follows:<br />
<br />
<!--T:77--><br />
<source lang="html">/^[0]*[1-9]$|^[0]*1[0-2]$/</source><br />
<br />
=Minimum width (set to 3 in this example)= <!--T:78--><br />
<br />
<br />
<!--T:79--><br />
<source lang="html">/^.{3,}$/</source><br />
<br />
<br />
=Currency= <!--T:80--><br />
<br />
<br />
==US currency (dollar sign and cents optional)== <!--T:81--><br />
<br />
<!--T:82--><br />
<source lang="html">/^\$?\d+(\.(\d{2}))?$/</source><br />
<br />
<!--T:132--><br />
Check for comma usage:<br />
<source lang="html">/^\$?\d{1,3}(\d+(?!,))?(,\d{3})*(\.\d{2})?$/</source><br />
<br />
==Swiss price== <!--T:83--><br />
<br />
<!--T:84--><br />
A number with two decimal numbers after the decimal point of which the last one is either a 5 or a 0:<br />
<br />
<!--T:85--><br />
<source lang="html">/^(\d+)(\.\d(05)?)?$/</source><br />
<br />
<br />
=Validate score= <!--T:86--><br />
<br />
<br />
==1-10== <!--T:87--><br />
<br />
<!--T:88--><br />
<source lang="html">/^[1-9]{1}$|^10$/</source><br />
<br />
==1-100== <!--T:89--><br />
<br />
<!--T:90--><br />
<source lang="html">/^[1-9]?[0-9]{1}$|^100$/</source><br />
<br />
<br />
=Text validation= <!--T:91--><br />
<br />
<br />
<!--T:92--><br />
The [[Question type - Multiple short text|multiple short text question type]] doesn't support minimum or maximum answers at the moment. One way around this is to use a [[Question type - Long free text|long free text question type]] with a regular expression.<br />
<br />
<!--T:93--><br />
The below expression tests for at least one word per line for at least 3 lines and no more than 10 lines:<br />
<br />
<!--T:94--><br />
<source lang="html">/(?:[^,.;:?!& \n\r]+(?: [^,.;:?!& \n\r]+)*)(?:[,.;:?!& \n\r]?(?:\n|\r|\n\r|\r\n)(?:[^,.;:?!& \n\r]+(?: [^,.;:?!& \n\r]+)*)){2,10}/is</source><br />
<br />
<!--T:95--><br />
If you want, say five words per line, you could change the first and last star/asterisk to {4,}:<br />
<br />
<!--T:96--><br />
<source lang="html">/(?:[^,.;:?!& \n\r]+(?: [^,.;:?!& \n\r]+){4,})(?:[,.;:?!& \n\r]?(?:\n|\r|\n\r|\r\n)(?:[^,.;:?!& \n\r]+(?: [^,.;:?!& \n\r]+){4,})){2,10}/is</source><br />
<br />
<!--T:97--><br />
If you wanted one or more words per line (between line 1 and line 5), you can change the content located within the last curly braces to '''0,4''' (note you use 0 because you're already matching the first line).<br />
<br />
<!--T:98--><br />
<source lang="html">/(?:[^,.;:?!& \n\r]+(?: [^,.;:?!& \n\r]+)*)(?:[,.;:?!& \n\r]?(?:\n|\r|\n\r|\r\n)(?:[^,.;:?!& \n\r]+(?: [^,.;:?!& \n\r]+)*)){0,4}/is</source><br />
<br />
==Word count== <!--T:99--><br />
<br />
<!--T:100--><br />
The following restricts the number of words allowed to a minimum of 1 and a maximum of 200:<br />
<br />
<!--T:101--><br />
<source lang="html">/^[-\w]+(?:\W+[-\w]+){0,199}\W*$/</source><br />
<br />
<!--T:102--><br />
To increase the minimum change the zero part of {0,199}.<br />
<br />
<!--T:103--><br />
To increase or decrease the maximum change the "199" part of {0,199}.<br />
<br />
=Time validation= <!--T:104--><br />
<br />
<br />
<!--T:105--><br />
There are a number of ways to write time formats. Some of the possible options are 12 hour or 24 hour, with seconds or without. Although it is an option to use the [[Question type - Date|date question type]] (it can also capture time) you can use the [[Question type - Short free text|short free text question type]] with one of the below validation regular expressions.<br />
<br />
<!--T:106--><br />
The following three validation strings test for 24 hour time (in order of appearances) without seconds, with optional seconds lastly with seconds required:<br />
<br />
<!--T:107--><br />
<source lang="html">/^(?:[01][0-9]|2[0-3]):[0-5][0-9]$/</source><br />
<br />
<!--T:108--><br />
<source lang="html">/^(?:[01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9])?$/</source><br />
<br />
<!--T:109--><br />
<source lang="html">/^(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$/</source><br />
<br />
<!--T:130--><br />
The following three match 12 hour time, as above with seconds, optional seconds and with seconds required:<br />
<br />
<!--T:110--><br />
<source lang="html">/^(?">00:[0-5][0-9] (?:am|AM)|(?:0[1-9]|1[01]):[0-5][0-9] (?:[ap]m|[AP]M)|12:[0-5][0-9] (?:pm|PM))$/</source><br />
<br />
<!--T:111--><br />
<source lang="html">/^(?:00:[0-5][0-9](?::[0-5][0-9])? (?:am|AM)|(?:0[1-9]|1[01]):[0-5][0-9](?::[0-5][0-9])? (?:[ap]m|[AP]M)|12:[0-5][0-9](?::[0-5][0-9])? (?:pm|PM))$/</source><br />
<br />
<!--T:112--><br />
<source lang="html">/^(?:00:[0-5][0-9]:[0-5][0-9] (?:am|AM)|(?:0[1-9]|1[01]):[0-5][0-9]:[0-5][0-9] (?:[ap]m|[AP]M)|12:[0-5][0-9]:[0-5][0-9] (?:pm|PM))$/</source><br />
<br />
<!--T:131--><br />
The following three match either 12 or 24 hour time as above with seconds, optional seconds and with seconds required:<br />
<br />
<!--T:113--><br />
<source lang="html">/^(?:(?:00:[0-5][0-9] (?:am|AM)|(?:0[1-9]|1[01]):[0-5][0-9] (?:[ap]m|[AP]M)|12:[0-5][0-9] (?:pm|PM))|(?:[01][0-9]|2[0-3]):[0-5][0-9])$/</source><br />
<br />
<!--T:114--><br />
<source lang="html">/^(?:(?:00:[0-5][0-9](?[0-5][0-9])? (?:am|AM)|(?:0[1-9]|1[01]):[0-5][0-9](?[0-5][0-9])? (?:[ap]m|[AP]M)|12:[0-5][0-9](?[0-5][0-9])? (?:pm|PM))|(?:[01][0-9]|2[0-3]):[0-5][0-9](?[0-5][0-9])?)$/</source><br />
<br />
<!--T:115--><br />
<source lang="html">/^(?:(?:00:[0-5][0-9]:[0-5][0-9] (?:am|AM)|(?:0[1-9]|1[01]):[0-5][0-9]:[0-5][0-9] (?:[ap]m|[AP]M)|12:[0-5][0-9]:[0-5][0-9] (?:pm|PM))|(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9])$/</source><br />
<br />
=US states= <!--T:116--><br />
<br />
<br />
<!--T:117--><br />
To validate for one state use the following (example is Texas):<br />
*TX uppercase only: <source lang="html">/^(TX)$/</source><br />
*tx lowercase only: <source lang="html">/^(tx)$/</source><br />
*TX upper or lowercase: <source lang="html">/^([T|t][X|x])$/</source><br />
<br />
<br />
=Profanity Filter= <!--T:118--><br />
<br />
<br />
<!--T:119--><br />
To filter profanity words from an answer:<br />
<br />
<!--T:120--><br />
<source lang="html">/^(?i)((?!\bENTERPROFANITYHERE\b).)*$(?-i)/</source><br />
<br />
<!--T:121--><br />
Replace "ENTERPROFANITYHERE" with your bad word.<br />
<br />
<!--T:122--><br />
The \b will allow passing of words such as "assassination" and "hello" if you enter "ass" or "hell" as your profanity word. This also works if you are trying to omit other words, names etc. from answers.<br />
<br />
<br />
=Helpful links= <!--T:139--><br />
<br />
<br />
<!--T:140--><br />
In the beginning of this wiki section, we recommend you to use https://regex101.com/ to test/create regular expressions. You can also use https://www.regextester.com/ to create expressions in case you are unhappy about the first option.<br />
<br />
</translate></div>Adminhttps://www.limesurvey.org/manual/index.php?title=QS:Relevance&diff=57535QS:Relevance2013-10-10T08:04:57Z<p>Admin: AL-HARBI:HACKER</p>
<hr />
<div><translate><br />
<!--T:1--><br />
<languages /><br />
<onlyinclude><br />
<br />
===Relevance equation=== <!--T:2--><br />
<br />
<!--T:3--><br />
{{FeatureStarting|v=1.92}} <br />
<br />
<!--T:4--><br />
'''Description'''<br />
<br />
<!--T:5--><br />
All questions let you specify a relevance equation. This is the successor to conditions and support much more complex conditional logic.<br />
<br />
<!--T:6--><br />
'''Syntax Highlighting'''<br />
<br />
<!--T:7--><br />
Whenever you save the relevance equation, it will be evaluated and syntax-highlighted. Any errors will be color coded so that you can quickly detect and fix them.<br />
<br />
<!--T:8--><br />
'''Valid values'''<br />
<br />
<!--T:11--><br />
Any equation, using [[Expression Manager|Expression Manager]] syntax, without surrounding curly braces.<br />
<br />
<!--T:9--><br />
'''Examples'''<br />
<br />
<!--T:12--><br />
Here are good examples of [[Expression Manager HowTos#Syntax Highlighting|syntax highlighting]]<br />
<br />
<!--T:10--><br />
</onlyinclude><br />
[[Category:Question Settings]][[Category:Core Question Settings]]<br />
</translate><br />
xv1@Outlook.sa</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Project_Ideas_for_GSoC_2013&diff=2532Project Ideas for GSoC 20132013-03-11T21:19:49Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Welcome=<br />
<br />
Welcome Google Summer of Code Student aspirants (:razz:)<br />
<br />
This page lists project ideas developed by the LimeSurvey Community. These tend to be areas that will get the most support as projects since they have been developed by people who know the project and what it needs the most. '''However''', if you have your own idea for a project discuss your awesome idea with us in our [http://www.limesurvey.org/en/forum forums], [https://lists.sourceforge.net/lists/listinfo/limesurvey-developers mailing list] or at [http://www.limesurvey.org/en/support/live-chat #limesurvey on irc.freenode.net]. Then submit your proposal. Good Luck (:biggrin:)<br />
<br />
----<br />
<br />
=Project ideas=<br />
<br />
----<br />
<br />
==Refactor all question types to a modular OOP format==<br />
<br />
If you look at the LimeSurvey source code (yii branch) you will notice that the code for the question types is strewn across the application.<br />
<br />
The goal of this task is to rewrite all question types to be objects, primarily inherited from one or more base question objects. A question type should have methods for display (several types of display like front ent/printable survey), response saving, configuration, statistics, etc.<br />
<br />
'''Skills'''<br />
*Extensive knowledge of PHP & Yii framework<br />
*Very good kownledge of LimeSurvey inner workings<br />
*Very good OOP knowledge<br />
<br />
'''Difficulty'''<br />
*Hard<br />
<br />
'''Probable Mentors'''<br />
<br />
Carsten Schmitz (c_schmitz)<br />
<br />
----<br />
<br />
==Implement a fully featured XML-RPC API + API tests + unit test==<br />
<br />
LimeSurvey urgently needs an API so all administration functions (and later even survey-taking functions) can be accessed without using the GUI. In addition you will be implementing an according unit test framework and implement unit & API tests across the whole application so we can make sure at any point in the development process that the application is functioning as it should.<br />
<br />
'''Skills'''<br />
*Good PHP, SQL, Yii knowledge<br />
*Good knowledge of the LimeSurvey administration and code<br />
<br />
'''Difficulty'''<br />
*Hard<br />
<br />
'''Probable Mentors'''<br />
<br />
c_schmitz<br />
<br />
----<br />
<br />
==User Interface Improvements and Backend Tidy Ups==<br />
<br />
Help improve LimeSurvey's usability and flexibility through a range of small tasks such as:<br />
* develop improved 'bulk' question handling UI<br />
* Tidy up input values on public surveys by moving required values from html inputs to javascript variables<br />
<br />
The idea is to provide ways of updating and modifying multiple questions, or multiple groups in one go. Often in a survey a user will need to make parallel changes to 5 or 6 questions all at once across a range of different groups. Being able to select various elements of questions, and then select a range of questions to edit would dramatically improve LimeSurvey's usability from the administrators perspective.<br />
<br />
'''Skills'''<br />
<br />
PHP, SQL, Yii, Authentication protocols (openID, CAS, LDAP-bind, ...)<br />
<br />
'''Difficulty'''<br />
<br />
Medium<br />
<br />
'''Probable Mentors'''<br />
<br />
Jason Cleeland (jcleeland)<br />
<br />
----<br />
<br />
==Implement a plugin framework for authentication/languages/ import/export modules==<br />
<br />
The idea is to design and implement a modular "framework" for LimeSurvey as well as convert the existing functionality to according modules. The framework will define the API each plugin type must (or may) implement and propose basic methods that can be used by plugins (for instance how to store the plugins parameters in DB, etc.).<br />
<br />
The plugin framework should be in parts similar to the framework used by Joomla (XML description files in the plugin packages)<br />
<br />
Example description for authentication moduls:<br />
<br />
Currently authentication is only used for the survey-administration GUI and not the participants interface (tokens are used for this). With the new authentication framework it should be possible to define several authentication backends for frontend (survey participation) and backend (administration)<br />
<br />
A generic authentication framework must define the following services:<br />
* User authentication: this interface must return the identity of the authenticated user if authentication is successful.<br />
** Authentication may not always be based on a simple user/password form, so the proposed framework must be generic enough to enable authentication based on other schemes (using any numbers or interaction-pages between the server and the end-user or any other contextual parameter such as Referrer, session variable...<br />
* User provisioning:<br />
** when activated on the survey administration interface, an authentication module might be able to create a newly authenticated user into the LimeSurvey internal DB (which is required for setting the user rights on the platform). The newly created user can be assigned a default profile or a per-user profile (queried from an external database).<br />
** when activated on the participants interface, the authentication module will provision the token table of the corresponding survey // alternatively the general-purpose cross-survey participants-database as described in the above GSoC idea.<br />
<br />
'''Skills'''<br />
<br />
PHP, SQL, Yii<br />
<br />
'''Difficulty'''<br />
<br />
Hard<br />
<br />
'''Probable Mentors'''<br />
<br />
c_schmitz<br />
<br />
Diogo Gon&ccedil;alves (dionet)<br />
<br />
'''Want to know more'''<br />
<br />
Please read the [http://docs.limesurvey.org/tiki-index.php?page=GSOC+2010++Authentication+framework#FAQ FAQ about this project]<br />
<br />
----<br />
<br />
==Custom Report Generation==<br />
<br />
The task is to make a module which will generate custom reports. Module should be able to do these things(at least) :-<br />
*Creating various types of reports i.e. using tables, pie charts, graphs and bar-charts to name few.<br />
*The resulting charts and other illustrations should be easy to read and understand, and should include the ability to export into standard office suites.<br />
*Reports can be general or survey specific.<br />
**General in the sense that it should show basic findings of a general survey graphically like number of users completing the survey, average time taken to complete the survey, average number of correct responses etc.<br />
**Survey specific results should also be addressed properly e.g. how many users choose first option as there answer of a particular question, how many users didn't answer a specific question etc.<br />
<br />
'''Skills'''<br />
<br />
OOP experience in PHP and experience with a PHP framework like CakePHP or CodeIgniter, jQuery. Strong mathematical background will help!<br />
<br />
'''Difficulty'''<br />
<br />
Moderate<br />
<br />
'''Probable mentors'''<br />
<br />
Carsten Schmitz (c_schmitz)<br />
<br />
Jason Cleeland (jcleeland)<br />
<br />
Diogo Gon&ccedil;alves (dionet)<br />
<br />
----<br />
<br />
==Adding new questions/subquestions and groups dynamically==<br />
<br />
Currently in LimeSurvey once a survey is activate we can not<br />
*Add or delete groups<br />
*Add or delete questions<br />
*Add or delete subquestions or change their codes<br />
<br />
The idea is to cover these shortcomings. And in addition, all those participants who have already taken that survey must also be notified about the changes. You should also work out in detail what happens to existing results when a survey is changed that way.<br />
<br />
'''Skills'''<br />
<br />
Experience with the PHP framework Yii and knowledge of inner working of LimeSurvey is must!<br />
<br />
'''Difficulty'''<br />
<br />
Moderate<br />
<br />
'''Probable mentors'''<br />
<br />
Jason Cleeland (jcleeland)<br />
<br />
Diogo Gon&ccedil;alves (dionet)<br />
<br />
----<br />
<br />
==Enhance Expression Manager==<br />
<br />
Starting with LimeSurvey 1.92, all of the front-end (survey-taking) processing is now managed using Expression Manager (EM). EM implements a safe subset of PHP syntax so that authors can write complex equations. It is integrated into LimeSuvey to control navigation (branching via relevance), validation, and tailoring/piping of content. Although it is quite powerful, users are already asking for enhancements.<br />
#Add a GUI for Expression Manager<br />
**Background: LimeSurvey has a nice GUI for building conditions, but it does not support complex equations such as those available within EM. EM does have robust syntax highlighting after an equation is saved, which makes it easy to fix any syntax errors. Hoever, users would like a GUI to ease authoring of equations.<br />
**Strategy - use CodeMirror - see [http://bugs.limesurvey.org/view.php?id=5279 here]<br />
***Create CodeMirror syntax file to do appropriate syntax highlighting (use C as base language), ensuring that CodeMirror knows the set of valid operators<br />
***Use CodeMirror API to let it know the names of registered function and variable names<br />
***Utilize auto-complete, ideally letting users see and choose among the availalbe function syntaxes (e.g. when a function can take several paameters).<br />
***Auto-completion of variable names should show the question and question type to make it easier for users to pick the correct variable.<br />
#Support sub-question-level Relevance<br />
**Background: EM already supports user-entered relevance equations at the group and question levels. It also generates sub-question-level relevance for features like array_filter. Users would like to be able ot add additional relevance criteria at the sub-question level.<br />
**Strategy:<br />
***Add a relevance column to the display of sub-questions, and ensure entered relevance is saved the to database (the data model is already OK)<br />
***Refactor createFieldMap() (or its successor) to read sub-question-level relevance into the run-time data structures so that passed to EM<br />
***Enhance EM's sub-question-level data structures to hold sub-question-level releavance<br />
***Update EM's _ValidateQuestion() and JavaScript generation functions to AND any manually-entered sub-question-level relevance equations with that auto-generated for array_filter and array_filter_exclude<br />
***Update ShowSurveyLogicFile() to show sub-question-level relevance equations ***Rigorously unit and regresssion test these changes.<br />
#Add Sub-question-level Validation<br />
**Background: The question-level validation supports regular-expression-based validation of each sub-question. Users would like to have sub-question-level validation to implement things like a question for collecting user contact information, where there are different validation criteria for address parts (e.g. city, state, postal code) and phone numbers.<br />
**Strategy: Similar to sub-question-level relevance<br />
***Add data entry fields for regular expression validation at the sub-question level, and ensure saved to database (which already has a preg field at the sub-question level)<br />
***Ensure EM gets access to the new preg values (via upgrade to createFieldMap)<br />
***Upgrade EM _ValidateQuesation() and function for generation of validation equations to include these new critiera. EM already supports validation at the sub-question level (and changes the CSS style to show fields that fail this validation)<br />
***Upgrade ShowSurveyLogicFile() to show sub-question-level validation rules<br />
***Rigorously unit and regresssion test these changes.<br />
#Add Sub-question-level mandatory criteria<br />
**Background: Many users have asked, via the forums, for ways to make parts of a multi-part questions mandatory, but make other parts optional. LimeSurvey already provides many options, such as minimum and maxium numbers of answers; but users have asked for more fine-grained control, and currently can only achieve that via custom JavaScript.<br />
**Strategy: Similar to sub-question-level relevance<br />
***Add checkbox to indicate mandatory status at the sub-question level<br />
#Add native support for input-masks at the question and sub-question level<br />
**Background: One of the commonly used work-arounds deals with input masks, such as the jQuery meimomask plugin.<br />
**Strategy:<br />
***Add mask attribute at question and sub-question level<br />
***Have EM generate needed JavaScript code to create and manage those masks<br />
#Add EM reporting functions (tables)<br />
**Background: There is commonly request for enhancemnt of the print answers table at the end of the survey. Some users want to generate custom reports mid-survey.<br />
**Strategy:<br />
***Implement showAllResponsesExcept(attributeList,attributeTitleList,questionList) function. questionList = 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.<br />
***Implement showTheseResponses(attributeList,attributeTitleList,questionList) function. questionList = 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.<br />
#Add better EM support for operations on array type questions<br />
**Background: Many of the EM validation rules are effectively statements like count the number of empty sub-questions, or sum the values of the sub-questions. EM generates these functions itself, so there is no burden on the user, even if there ar dozens of sub-quetions. However, manual editing of these questions is cumbersom. Users could benefit from special variables to access all of the elements of a question so that they could write functions like (sum(this) == 10)) and have it be expanded to (sum(q1_1, q1_2, ..., q1_N) == 10). Note, there is already a "this" variable, but it does not apply to sub-questions.<br />
**Strategy:<br />
***Extend EM so that "this" variable gets expanded into a comma separate list of sub-question references if there are sub-questions. Have this expansion carry the suffix, so this.valueNAOK would become q_1.valueNAOK, q_2.valueNAOK, ..., q_N.valueNAOK.<br />
***This macro expansion should occur in group.php (e.g. in the process of generating JavaScript), rather than having this variable be resolved at run-time within JavaScript.<br />
***Provide similar array-expansion macros for all variables (not just "this") - such as qcode_vars.*. This would also functions like sum(qcode_vars.NAOK), count(qcode_vars.NAOK), implode(' ', qcode_vars.valueNAOK)<br />
***For questions with comments, create macros like qcode_vars_nc and qcode_vars_oc for no-comments and only-comments<br />
***For arrays that might need row or column-level processing, create aliases like qcode_rowname_vars and qcode_colname_vars so can expand each. This would let us replace the current system for generating row and column sums with equations like sum(qcode_rowname_vars.NAOK) and be sure that the sums will honor array_filter and array_filter_exclude.<br />
#Add EM functions to validate data entry against value sets managed by Enterprise Vocabulary Systems<br />
**Background: Healthcare and biological sciences increasing use large controlled vocabularies, terminologies, or ontologies. Data entry systems for such domains require validation against those vocabularies. Large open-source projects, like [https://cabig.nci.nih.gov/community/tools/LexEVS_Server LexEVS] and [http://apelon.com/Products/DTS/tabid/97/Default.aspx Apelon DTS] provide open APIs to access that content. Such tools let one validate diagnostic codes, and even do incremental search into those vocabularies as one types. The main open projects are standardizing on the [http://hssp.wikispaces.com/cts2 CTS-2] (Clinical Terminology Services-2) specification.<br />
**Strategy:<br />
***Create EM-compatible PHP and JavaScript functions to access CTS-2 compliant EVS systems<br />
***Should include question and sub-question-level validation rules to validate the final entry. Currently, thre are em_validation_q and em_validation_sq advanced quation attributes for validating questions and sub-questions based upon calls to external functions. It may be desirable to support custom sub-question-level validation to validate each sub-question against different value sets. If so, can follow the model of adding sub-question-level validation and relevance. Alternatively, may be desirable to add sub-question-level advanced question options (if LimeSurvey community feels that there may be enough such extensions that such customization should be stored in a general attribute table rather than making the questions table wider).<br />
***Should also include ability to do incremetal searches into the value sets<br />
<br />
'''Skills'''<br />
<br />
PHP, SQL, PHP Debugging (e.g. xdebug), Yii, LimeSurvey's Expression Manager and code-base in general<br />
<br />
'''Difficulty'''<br />
<br />
Medium to Hard<br />
<br />
'''Probable Mentors'''<br />
<br />
Thomas White (TMSWhite)<br />
<br />
----<br />
<br />
==Optimize LimeSurvey for Long Surveys (and better performance and maintenance in general)==<br />
<br />
Although LimeSurvey is excellent for short and mid-length surveys, it is not optimized for surveys with hundreds or thousands of questions - such as those used by epidemiologists or in clinical trials. This project would tackle each of those main limitations. Those sub-tasks, and the development strategy include:<br />
#Support for more than 1000 database columns<br />
**Background: LS creates a horizontal table for survey data collection, and such tables often are limited to at most 1000 columns<br />
**Strategies:<br />
***Remove unneeded columns from horizontal table (e.g. type 'X')<br />
***Conditionally remove unneeded equation columns (e.g. let users specify a prefix for variable names that should not be stored)<br />
***Add option for Entity Attribute Value data model for data collection (which can support unlimited number of columns. See details [http://bugs.limesurvey.org/view.php?id=5289 here].<br />
#Memory and Code Optimization<br />
**Background: LS loads the survey definition data model into several different data structures, such that it uses at least twice as much storage as it really needs. Expression Manager now holds all of the instrument definition data, so the other data stores are no longer needed.<br />
**Strategy<br />
***Remove need for buildsurveysession() - gap analysis to add in any missing content to EM<br />
***Remove need for createFieldMap() - similar gap analysis<br />
***Normalize EM data structures to avoid internal duplication (and refactor code to use normalized structures) (and document new data structures so that future developers know which to use, and how to use them)<br />
****gInfo - renaming of groupSeqInfo, plus add missing group-level attributes (relevance, description)<br />
****qInfo - renaming of questionSeq2relevance, plus add any missing attributes from $fieldarray; remove aid, sqid; move grelevance to gInfo<br />
****aInfo - for storing answer arrays?<br />
****sqInfo - renaming of q2subqInfo, indexed on sgqa(?); remove content gleaned from gInfo and qInfo<br />
****gStatus - renaming of indexGseq - make hold only dynamic values; so move gtext and gname to gInfo; also remove gRelInfo, keeping any unique variables it contains<br />
****qStatus - renaming of indexQseq - make hold only dynamic values; so move qtext, qhelp, gtext, gname to qInfo<br />
****sqStatus - renaming of subQrelInfo - make hold only dynamic values<br />
****groupRelevanceInfo - consolidate into indexGseq?<br />
****knownVars - instead of copying content, use reference to gInfo and qInfo (e.g. remove question, relevance, grelevance, qcode, ansList, ansArray, onlynum).<br />
****varNameAttr - remove; generate on the fly from gInfo, qInfo, and knownVars<br />
****alias2varName - remove; generate on the fly from knownVars<br />
***Refactor EM so that stores normalized copies of secondary language text<br />
***Optionally load only current group for each page transition rather than holding entire survey definition in memory<br />
***Refactor EM for consistent variable naming<br />
****e.g. questionId => qid; groupNum => gid; groupSeq => gseq; questionSeq => qseq<br />
#Run-Time Performance Optimization<br />
**Background: qanda.php loads the content to create the questions and answers. It used to do this by separate database queries per question.<br />
**Strategy<br />
***Refactor qanda.php to remove queries (like for "other", or sub-question text) - have it get that information from EM<br />
***Refactor LS so that language switching does not require a re-load of the core logic, but just the new language content (and that it gets this from EM)<br />
***Refactor replacements.php and EM<br />
****Should only need to call replacements.php once per page, so set those valeus as locally static in EM per page.<br />
****Refactor group.php to pass {QUESTION_*} via replacements array, rather than as globals passed to templatereplace<br />
#Design-Time Performance Optimization<br />
**Background: LS used to only load the information from the data model that was needed for the given question or group. EM had to load the entire data model to properly syntax highlight everything. This can lead to some performance degradation in very long surveys<br />
**Strategy:<br />
***Add methods to EM to just load changes to model as questions or groups are added, removed, or updated<br />
***Pass those updates into EM internals so that syntax highlighting continues to be correct<br />
***Ensure that admin pages only call the subset of EM functions needed to do accurate syntax highlighting.<br />
#Optimizations for Rapid Development<br />
**Background: LS has a nice GUI for editing single questions at a time. However, it is not optimized to make changes to multiple questions at a time. Some competitor systems let authors design surveys using an Excel template (e.g. so that they can do bulk find and replace, or easily copy similar portions or answer lists). Short of a full-blown AJAX-enabled admin system, this has the highest throughput potential<br />
**Strategy:<br />
***Create an Excel data model that would work for importing surveys<br />
***Create import and validation routines from that model<br />
***A similar model, which could be extended for LS, is noted [http://bugs.limesurvey.org/view.php?id=5105 here].<br />
#Performance Validation<br />
**Load test surveys of varying lenghts<br />
**Identify performance and memory bottlenecks<br />
**Idenfity minimum memory requirements for certain survey lengths and concurrent user volumes<br />
**Propose strategy to overcome those performance issues<br />
<br />
'''Skills'''<br />
<br />
PHP, SQL, PHP Debugging (e.g. xdebug), Yii, LimeSurvey's Expression Manager and code-base in general, Load testing tool (e.g. webload), PHP Profiler<br />
<br />
'''Difficulty'''<br />
<br />
Medium to Hard<br />
<br />
'''Probable Mentors'''<br />
<br />
Thomas White (TMSWhite)<br />
<br />
----<br />
<br />
==Idea template==<br />
<br />
Describe the idea here in general terms<br />
<br />
'''Skills'''<br />
<br />
Explain what sort of coding skills would be needed for a student to implement this project<br />
<br />
'''Difficulty'''<br />
<br />
Explain the level of difficulty involved<br />
<br />
'''Probable Mentors'''<br />
<br />
Put your name (and tag) here if you are willing to mentor a student for this idea<br />
<br />
----<br />
<br />
=More information=<br />
<br />
==Getting started==<br />
<br />
[[GSoC getting started|Check out our 'Get started' page]] for setting up the development environment, coding standards, and all the other important stuff that you need to know before the real fun begins!<br />
<br />
==Frequently Asked Questions==<br />
<br />
Check out [[GSoC FAQ|our GSoC FAQ page.]]</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Survey_settings&diff=4106Survey settings2013-03-08T21:04:41Z<p>Admin: </p>
<hr />
<div><br />
<div style="float:right;"><div class="simplebox">Additional pages:{toc}</div></div><br />
<br />
__TOC__<br />
<br />
=Overview=<br />
<br />
To create a new survey, click on the Add button [[File:add.png]] on the right side of the administration button bar and a "Create New Survey" screen will appear. You can edit most of these settings later again by click the 'Edit survey settings' icon [[File:token_manage_30.png]] in the 'Survey properties' dropdown menu of the survey toolbar.<br />
<br />
=Settings=<br />
<br />
All survey settings and functions are organized in tabs. The following is a description of each tab and field.<br />
<br />
==General==<br />
#'''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.<br />
#'''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.<br />
#'''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.<br />
#'''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.<br />
#'''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.<br />
#'''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}"<br />
#'''URL description''': The description for the link using the End URL.<br />
#'''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.<br />
#'''Admin email''': This is the email address of the administrator (as above) and is used as the 'reply to:' address on any emails sent. You can also enter several email addresses separated with a semicolon - that way survey administrator notifications are sent to more than one person. (Example: "firstaddress@test.com;secondaddress@test.com")<br />
#'''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).<br />
#'''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.<br />
<br />
<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><br />
<br />
==Presentation & navigation==<br />
#'''Format''': Choose from "Question by question", "Group by group" or "All in one".<br />
**'''Question by Question''': Public survey will display one question per page.<br />
**'''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 "One at a time" surveys.<br />
**'''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.<br />
#'''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 in the LimeSurvey [[Templates / The Template Editor]] Guide.<br />
#'''Show welcome screen''': Yes/No. If Yes, then the welcome message defined in Text Elements section will be displayed. Default is Yes.<br />
#'''Navigation delay''': Number of seconds before Previous and Next buttons are enabled. Default 0 seconds<br />
#'''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.<br />
#'''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.<br />
#'''Keyboard-less operation''': By activating this setting there will be a virtual keyboard available for certain question types.<br />
#'''Show progress bar''': Yes/No. Default Yes. Allow the administrator to turn off the Progress bar<br />
#'''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.<br />
#'''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]].<br />
#'''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'').<br />
#'''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.<br />
#'''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.<br />
#'''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:<br />
**'''Show Both''' - Default<br />
**'''Show Group Names Only'''<br />
**'''Show group description Only'''<br />
**'''Hide Both'''<br />
#'''Show question number and/or code''':<br />
**'''Show Both''' - Default<br />
**'''Show Question Number Only'''<br />
**'''Show Question Code Only'''<br />
**'''Hide Both'''<br />
#'''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 partticipant won't be able to unselect a chosen answer option in a non-mandatory question.<br />
<br />
==Publication & access control==<br />
#'''List survey publicly''': Yes/No. Default No. When it is set to yes, your survey will be listed in the 'available surveys' portal<br />
# '''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.<br />
#'''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.<br />
#'''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.<br />
#'''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.<br />
<br />
==Notification & data management==<br />
#'''Send basic admin notification email to:''' and '''Send detailed admin notification email to:''' These fields allow you to send notifications or survey responses to additional email addresses once the survey is submitted. You can edit the templates for these emails under 'Email templates'. Multiple recipients can be set by seperating 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}". Make sure that at least your administrator email is set properly in the survey settings - otherwise no email will be sent or there will be an 'Invalid address:' message when a participant finishes a survey. Please note that there are three different ways for entering an address:<br />
##Enter a specific ''email address'' (ie: yourname@test.com)<br />
##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 [http://docs.limesurvey.org/tiki-index.php?page=Adding+a+question&structure;=English+Instructions+for+LimeSurvey#Information_from_previous_answers Re-use information from previous answers]<br />
##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 [http://docs.limesurvey.org/tiki-index.php?page=Adding+a+question&structure;=English+Instructions+for+LimeSurvey#Information_from_tokens_table Re-use Information from the Tokens Table]<br />
##''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).<br />
#'''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.)<br />
#'''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.<br />
#'''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.<br />
#'''Enable assessment mode?''': With this setting you can enable/disable [[Assessments|assessments]] for this survey.<br />
#'''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.<br />
#'''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.<br />
#'''Google Analytics API Key for this survey''': Allows for integration with Google Analytics. The API key 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}<br />
#'''Google Analytics Style for this Survey''': Choices are:<br />
##'''Do not use Google Analytics''' - so {GOOGLE_ANALYTICS_JAVASCRIPT} is an empty string<br />
##'''Default Google Analytics''' - {GOOGLE_ANALYTICS_JAVASCRIPT} uses the standard Google Analytics code, inserting the proper Google Analytics Key<br />
##'''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.<br />
<br />
'''Google API howto''':<br />
# Register/login on Google Analytics (GA): [http://www.google.com/analytics/ www.google.com/analytics/]<br />
# Create a key (the site should not point to the survey, but to the part before 'index.php?') The key should be UA-xxxxx.<br />
# Go to your survey's global settings in Limesurvey.<br />
# Put the key in appropriate field (Google Analytics API Key). It's probably the best to set GA Style to track all pages as you can have more info.<br />
# You don't need to do anything in shipped templates, as the {GOOGLE_ANALYTICS_JAVASCRIPT} part is already there.<br />
# Activate the survey.<br />
# Do the survey.<br />
# 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.<br />
<br />
==Tokens==<br />
#'''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.<br />
#'''Allow editing of answers after completion?''': Default: No If you activate this setting the participants may return to his survey by clicking the invitation link, even if he already submitted the survey. This only works with non-anonymized surveys.<br />
#'''Enable token-based response persistence''': If your survey uses tokens and your responses are not anonymized, then you may want to enable this feature. If you turn this on, then your participants can leave your survey and resume later at any time without using the 'Resume later' function - for example if he/she gets distracted or his browser crashes. Upon clicking the invitation link again he will find his survey answers so far still in place when returns to the survey and will even continue on the last page seen.<br />
#'''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.<br />
#'''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.<br />
#'''Set token length to''': Usually you don't need to change this, the default setting of 15 digits (max. supported value: 99) 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.<br />
<br />
==Import==<br />
<br />
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).<br />
<br />
==Copy==<br />
<br />
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.<br />
<br />
==Panel integration (URL parameters)==<br />
<br />
<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><br />
<br />
On this tab you can set which additional URL parameters will be accepted by your survey. 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 End-URL for further information.<br />
<br />
==Resources==<br />
<br />
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.<br />
<br />
You can:<br />
* Browse available files<br />
* Export files as a ZIP archive<br />
* Import a ZIP archive of files<br />
<br />
Important hints:<br />
* Authorized files extensions are defined in config-defaults.php.<br />
* Files for the survey are in the upload/surveys/<sid> subdirectory.<br />
* Uploaded files will only been seen while browsing resources on this survey (groups, questions, answers) not in other surveys or objects (labels).<br />
* 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.<br />
* You can't import a ZIP file containing subdirectories.<br />
<br />
=2nd Step - Additional languages=<br />
<br />
To add more language 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.<br />
<br />
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.<br />
<br />
Previous [[Creating surveys - Introduction]]<br />
<br />
Next [[Importing a survey structure]]</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Alternatives_to_the_LimeSurvey_import_function&diff=1539Alternatives to the LimeSurvey import function2013-03-08T21:03:05Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Import using the administration interface=<br />
<br />
If you have previously exported a survey structure, you can import it from the "New Survey" screen. Click on the browse button to choose the SQL/CSV file, and then click on the button. The import process reads the following formats:<br />
*v1.50 or later .CSV files created by LimeSurvey<br />
*v1.90 or later .LSS files created by LimeSurvey<br />
<br />
That way you can import old surveys from previous version. The import 'intelligently' re-numbers the survey, group, question, answer and condition IDs so that they all match each other - '''no existing surveys will be overwritten'''. See section on [[Exporting a survey structure]] for more information.<br />
<br />
=Import using the commandline utility=<br />
<br />
Since version 1.50 it is possible to import surveys from the command line (or shell). To use this functionality you have to have access to the shell and the PHP interpreter has to be configured to allow shell execution of scripts.<br />
<br />
This functionality is useful when you have timeout problems with the web version that could happen when you have very long surveys to import.<br />
<br />
To use it, in the shell go to the limesurvey/admin folder and execute:<br />
<br />
php cmdline_importsurvey <File to import> <nowiki>[</nowiki><user> <password>]<br />
*<File to import> has to be one of the described above<br />
*<user> has to be a user with the right to create surveys<br />
*<password> the password for the user <br/>*<user> and <password> are only required if the control access is active<br />
<br />
If you need to see the parameters you can execute:<br />
<br />
php cmdline_importsurvey -h<br />
<br />
=Importing surveys from other applications=<br />
<br />
We are often getting requests to import a survey from other applications or survey providers. The problem is that providers like SurveyMonkey lock you in - it is not possible to export the survey structure from SurveyMonkey, only the response data. So you can see that using non-open propietary software or providers can be a bad idea in the first place.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=LimeSurvey_roadmap&diff=2081LimeSurvey roadmap2013-03-04T19:03:22Z<p>Admin: </p>
<hr />
<div><br />
Contents:__TOC__<br />
<br />
=General=<br />
<br />
This page lists future development and release goals. We will update this regularly with more details as they become available. Goals cannot be fulfill by itself so if you want to give a helping hand please get in touch! Following you will find our first public project status and any future project status will replace this one. All project statuses can/will be found on the[[Past project statuses]] page.<br />
<br />
=LimeSurvey project status January 4th, 2013=<br />
<br />
LimeSurvey 2.0+ is currently considered to be stable - due to the recent switch to the Yii framework there are certain issues coming up regarding cross-DB compatibilities which are addressed by regular releases of new builds. LimeSurvey 2.1 is currenty in development and will show the start of a plugin-architecture.<br />
<br />
=Timeline=<br />
<br />
{|<br />
|Est. date||Goal||Remarks/features<br />
|-<br />
|15 April 2013||Release 2.1 alpha version||-Improved plug-in system<br/>-Question types are now plugins<br />
|-<br />
|Unknown||Release 2.2||- New question designer<br/><br />
|-<br />
|Unknown||Release 2.3||- Locking<br/>- Trans-process caching<br />
|-<br />
|<br />
|}</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_-_LimeSurvey_CE&diff=1574Installation - LimeSurvey CE2013-03-03T15:31:41Z<p>Admin: </p>
<hr />
<div><br />
<div style="float:right;"><div class="simplebox">Additional pages:{toc}</div></div> {maketoc title="On this page:"}<br />
<br />
<div class="simplebox"> Note: These installation instructions are for version 2.0 or later. Older instructions for 1.92 can be found here [[Installation Version 1.92 or older|here]] </div><br />
<br />
=General=<br />
<br />
The LimeSurvey project offers two ways of installating LimeSurvey:<br />
*On your webserver:<br />
<br />
+In that case just follow the instructions on this page starting with step 1.<br />
*On your local Windows PC:<br />
<br />
+You usually only want to install LimeSurvey on your local PC if you want to create surveys locally (mainly for speed or test reasons) and upload them later to your live LimeSurvey installation on a web server. For this we have prepared a special package for LimeSurvey which includes the web server, the database and the LimeSurvey application and [[Installation of the LimeSurvey XAMPP package|instructions how to install it]].<br />
<br />
=1. Make sure you can use LimeSurvey on your website=<br />
<br />
Make sure your server meets the following additional requirements. Most of these requirements will also be checked during the installation.<br />
<br />
Required:<br />
* Minimum 80 MB disk space<br />
* MySQL 4.1.0 or later '''OR''' Microsoft SQL Server 2005 or later '''OR''' Postgres 8.1 or later<br />
* PHP 5.1.6 or later with the following modules/libraries enabled:<br />
** mbstring (Multibyte String Functions) extension library (see also [http://docs.limesurvey.org/tiki-index.php?page=Installation+FAQ#What_is_this_mbstring_Multibyte_String_Functions_library_ Installation FAQ])<br />
** PDO database driver for MySQL (pdo_mysql or pdo_mysqli) or Postgres (pdo_pgsql) or MSSQL (pdo_sqlsrv)<br />
** For PHP versions <5.2 you will need to have the PECL JSON library( see [http://pecl.php.net/package/json]) installed<br />
** Also we assume in general that all PHP default libraries are enabled (like hash, session, etc.).<br />
<br />
<div class="simplebox"> Please note that LimeSurvey 2.x uses different database drivers than 1.x . If you get a message not No DBO driver was found during the installation you will have to contact your webspace provider and ask them to activate one of the aforementioned database driver libraries. </div><br />
<br />
Optional PHP Extensions:<br />
* '''GD-Library''' '''with FreeType support''' installed is needed for captchas or nice charts in statistics - see [http://de3.php.net/manual/en/image.setup.php PHP GD-Library Extension documentation]<br />
* '''IMAP''' (pretty standard) is needed for the [[Email bounce tracking system]] - see [http://www.php.net/manual/en/imap.setup.php PHP IMAP Extension documentation]<br />
* '''LDAP''' installed is needed to import tokens using LDAP - see [http://de.php.net/manual/en/ldap.installation.php PHP LDAP Documentation]<br />
* '''Zip''' (pretty standard) for template upload and import resources Zip archives - see [http://www.php.net/manual/en/zip.setup.php PHP Zip Extension documentation]<br />
* '''Zlib''' (pretty standard) is needed for the [[ComfortUpdate]] - see [http://www.php.net/manual/en/zlib.setup.php PHP Zlib Extension documentation]<br />
<br />
In most cases your webspace provider or system administrator will be able to help you out on these optional components.<br />
<br />
If you want to try LimeSurvey on your local machine we recommend [http://www.apachefriends.org/en/xampp.html XAMPP] which is an easy to install software package containing a complete web server with Apache, MySQL, PHP and Perl. LimeSurvey will run on XAMPP with no configuration needed.<br />
<br />
If you want to run Microsoft's IIS server take a look at "[[Installation of LimeSurvey on a Windows XP machine]]" and "[[Installation on XP with IIS]]".<br />
<br />
==1.1 Hosting for LimeSurvey==<br />
<br />
LimeSurvey should work with most hosting companies which provide PHP and MYSQL. If you want a ready-installed version of LimeSurvey consider using LimeService, else check out our [[LimeSurvey-compatible hosting companies|list of LimeSurvey-compatible hosting companies]].<br />
<br />
=2. Download the LimeSurvey package=<br />
<br />
[http://www.limesurvey.org/en/download Download] the latest stable LimeSurvey zip package (there are also gzip, bz2 and 7zip packages available for your convenience) and save it to your local disk.<br />
<br />
=3. Unpack the LimeSurvey package=<br />
<br />
Uncompress the zip file into a dedicated directory/folder using your preferred compression software. When you uncompress the file make sure that you uncompress the directory structure with the files (this is default behavior for most compression programs). The path name for the installation directory should not include '''(''' or ''')''' characters, but may include the '''space''' character<br />
<br />
=4. Collect information about your server=<br />
<br />
You will need to know the following things to install LimeSurvey on your web server correctly:<br />
*Your intended website URL where your scripts will reside (e.g: ''http://my.domain.com/limesurvey'')<br />
*The physical disk location on your server where your scripts will reside (ie: ''/home/usr/htdocs/limesurvey'')<br />
*The IP/net location of your database server (ie: ''localhost'')<br />
*If your database server uses a non-standard port find out which port it is.<br />
*Your username and password for your database server<br />
*With most providers you can't let the script create the database but have to do it yourself. If you are using such a provider please create a database (for example ''limesurvey'') yourself.<br />
<br />
=5. Upload the files to your web server=<br />
<br />
Using your FTP program, connect to your web server and create a directory to store your scripts. Then upload the files using the directory structure they are in. Make sure you '''upload the files in binary mode''' (check the settings of your FTP program). Please note that uploading in ASCII mode can lead to uncommon errors (e.g. 'class not found' error during installation), also images may not be uploaded correctly.<br />
<br />
=7.1 Set Directory permissions=<br />
<br />
For the script to work properly it needs certain access to some directories - this applies especially to Linux/*nix systems.<br />
*The '''"/limesurvey/tmp"''' directory and all its subdirectories and files are used for imports & uploads and should be set to ''Read & Write'' for your webserver.<br />
*The '''"/limesurvey/upload/"''' directory and all its subdirectories and files must also have ''Read & Write'' for your webserver in order to enable picture and media files upload.<br />
*The '''"/limesurvey/application/config/"''' directory also needs ''Read & Write'' permissions for your webserver.<br />
*The other directories can be set to ''Read Only'' or in Linux/Unix. You may wish to set the permissions on each file within the /limesurvey/admin directory to ''Read Only''.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Hint:''' If you are using Linux then depending on your webserver configuration you will have to chmod the rights on the writable folders to 755 or 777. Try 755 first - if it does not work 'upgrade' to 777.</div><br />
<br />
=7.2 Create a database user=<br />
<br />
LimeSurvey will create a database and the tables inside it. To be able to do this it will need the username and password of a database user. In general we recommend to create a database user with the following permissions:<br />
<br />
- MySQL: SELECT, CREATE, INSERT, UPDATE, DELETE, ALTER, DROP, INDEX<br />
<br />
- PostgreSQL: SELECT, INSERT, UPDATE, DELETE, TRUNCATE, TRIGGER<br />
<br />
- Microsoft SQL Server:<br />
<br />
=8. Run the installation script=<br />
<br />
'''Go to "http://your.domain.com/limesurvey/admin"'''. If you configured everything correctly the LimeSurvey installer should be starting - just follow the instructions. You will be asked if to create the database and/or create the tables inside the database. Limesurvey then creates the needed tables in the database.<br />
<br />
=9. Connect to the administration script for the first time=<br />
<br />
After the installer has finished you are done! Open your browser and enter the URL of your admin.php script. Assuming you used LimeSurvey as the directory name to store the files in, this will be something like "http://your.domain.com/limesurvey/admin/admin.php".<br />
<br />
You should get a login screen. The default login credentials (if not changed during in the installation) are<br />
<br />
<div class="simplebox"> User: admin<br />
<br />
Password: password<br />
<br />
</div><br />
<br />
You will be prompted to change the default password after you logged in. Have fun!<br />
<br />
=10. What if I have problems...=<br />
<br />
Like all computer programs, most of the time things will work just like the instructions say, but sometimes they just won't. There are too many possible reasons for things not going according to plan to describe here. If you have trouble, first check out the [[Installation FAQ]]. If you don't find your answer there please post your problem and any error messages in the [http://www.limesurvey.org/en/forum LimeSurvey forums] on limesurvey.org or join the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel]:<br />
<br />
<div class="simplebox"><center>'''[http://www.limesurvey.org/en/community-services/live-chat Direct link to the official LimeSurvey IRC Channel]'''</center></div></div>Adminhttps://www.limesurvey.org/manual/index.php?title=Question_type_-_Array_dual_scale&diff=2652Question type - Array dual scale2013-02-21T18:19:09Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Short description=<br />
<br />
This type provides two scales of answer options for each subquestion. A heading can be set for each scale using the advanced settings:<br />
<br />
[[File:1_DSC.jpg]]<br />
<br />
You can set a special question attribute to use this question type with dropdown boxes:<br />
<br />
[[File:1_DSC_DD.jpg]]<br />
<br />
----<br />
<br />
Download english sample question: [[Media:1_-_Dual_Scale.csv|1_-_Dual_Scale.csv]]<br />
<br />
Download english sample question: [[Media:1_-_Dual_Scale_Drop_Down.csv|1_-_Dual_Scale_Drop_Down.csv]]<br />
<br />
=Core settings=<br />
<br />
{INCLUDE(page="Core question settings",start="!mandatory",stop="---")}{INCLUDE}<br />
<br />
==These Core Settings are available in Version 1.92 and beyond==<br />
<br />
{INCLUDE(page="Core question settings",start="!relevance",stop="---")}{INCLUDE}<br />
<br />
=Advanced settings=<br />
<br />
{INCLUDE(page="Advanced question settings",start="!answer_width",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!random_order",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!random_group",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!hidden",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!dualscale_headerA",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!dualscale_headerB",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!use_dropdown",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!dropdown_separators",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!dropdown_prepostfix",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!array_filter",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!array_filter_exclude",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!page_break",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!public_statistics",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!scale_export",stop="---")}{INCLUDE}<br />
<br />
==These Advanced Settings are available in Version 1.92 and beyond==<br />
<br />
{INCLUDE(page="Advanced question settings",start="!array_filter_style",stop="---")}{INCLUDE}<br />
<br />
{INCLUDE(page="Advanced question settings",start="!min_answers",stop="---")}{INCLUDE}<br />
<br />
<div class="simplebox">With Array dual scale an completed answer is an answer at each scale.</div><br />
<br />
{INCLUDE(page="Advanced question settings",start="!max_answers",stop="---")}{INCLUDE}<br />
<br />
<div class="simplebox">With Array dual scale an completed answer is an answer at each scale.</div></div>Adminhttps://www.limesurvey.org/manual/index.php?title=Expression_Manager&diff=4464Expression Manager2013-02-07T15:12:42Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
<div class="simplebox"> Note: This feature is only available in LimeSurvey 1.92 or later. </div><br />
<br />
=Quick Start Tutorial=<br />
<br />
==Overview==<br />
<br />
When customizing your surveys, you typically need a way to specify the following:<br />
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked<br />
#'''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).<br />
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern<br />
<br />
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).<br />
<br />
The following sections show the main places where Expression Manager is used<br />
<br />
==Relevance (Controlling Navigation/Branching)==<br />
<br />
Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses an Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).<br />
<br />
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, weight_kg 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).<br />
<br />
[[File:tutorial1.jpg]]<br />
<br />
Relevance is shown and editable in the following places:<br />
<br />
===Viewing / Editing Question-Level Relevance===<br />
<br />
This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.<br />
<br />
[[File:tutorial2.jpg]]<br />
<br />
This is the edit screen for the BMI question.<br />
<br />
[[File:tutorial3.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
===Viewing / Editing Group-Level Relevance===<br />
<br />
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).<br />
<br />
[[File:tutorial4.jpg]]<br />
<br />
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.<br />
<br />
Here is the screen for editing the group-level relevance for that question:<br />
<br />
[[File:tutorial5.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
==Tailoring/Piping==<br />
<br />
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.<br />
<br />
===Conditional Equations===<br />
<br />
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.<br />
<br />
[[File:tailoring7.jpg]]<br />
<br />
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.<br />
<br />
BMI computes the weight formula as {weight_kg / (height_m * height_m)}.<br />
<br />
Lastly, the report conditionally tailors the message for the subject, telling him what he entered (e.g. "You said you are 2 meters tall and weight 70 kg."<br />
<br />
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<br />
<br />
[[File:tailoring8.jpg]]<br />
<br />
From the edit window for this question, you can see two things:<br />
#Tailoring must surround expressions with Curly Braces<br />
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.<br />
<br />
[[File:tailoring9.jpg]]<br />
<br />
===Tailored Questions, Answers, and Reports===<br />
<br />
<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 <span> tag which is not valid inside select options.</div><br />
<br />
This example shows the BMI report.<br />
<br />
[[File:tailoring10.jpg]]<br />
<br />
Here is the edit window for the same question.<br />
<br />
[[File:tailoring11.jpg]]<br />
<br />
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.<br />
<br />
[[File:tailoring12.jpg]]<br />
<br />
You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.<br />
<br />
The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.<br />
<br />
=Introduction=<br />
<br />
LimeSurvey 1.92 and later 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).<br />
<br />
This wiki page is the definitive reference for Expression Manager syntax and functionality.<br />
<br />
==Key Definitions==<br />
#'''Expression''': Anything surrounded by curly braces<br />
**As long as there is no white space immediately after the opening brace or before the closing curly brace<br />
**The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.<br />
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text<br />
**You have access to all 'replacement fields', TOKENs, and INSERTANS values<br />
**You also have easier access to questions, answers, and their properties.<br />
#'''Relevance''' Equation: A new question attribute controlling question visiblity<br />
**If there is a relevance equation, then the question is only shown if the relevance evaluates to true.<br />
**Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance<br />
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database<br />
**It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"<br />
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+<br />
**Stands for Survey-Group-Question-Answer<br />
**SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.<br />
**These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed<br />
#'''Question Code''': This is the preferred variable name for EM<br />
**This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic<br />
**Although not required to be unique in <= 1.91+, it must be unique if you want to use EM<br />
**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".<br />
**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.<br />
<br />
==Do I have to use EM?==<br />
<br />
The short answer is No (but also yes).<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Can I mix use of Conditions and Relevance?==<br />
<br />
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.<br />
<br />
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.<br />
<br />
==How should I choose between Conditions and Relevance?==<br />
<br />
Here is a list of pros and cons of each style:<br />
<br />
{|<br />
|Style||Pros||Cons<br />
|-<br />
|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<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.<br />
<br />
==What are some other benefits of using EM?==<br />
<br />
Here are some of the other reasons you might want to use EM.<br />
#Calculations - you can create any calculation you can think of:<br />
**You have access to all common mathematical operators and functions<br />
**You have access to 70+ mathematical, date, and string processing functions<br />
**It is fairly easy for developers to add new functions if users need them<br />
#Storing Calculations to Database<br />
**You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.<br />
**You use the Equation question type to accomplish this.<br />
#Assessments<br />
**You can now create assessments or scale scores from any question type, not just the subset that used to be supported<br />
**You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page<br />
**You have more control over the reports generated based upon those assessment scores<br />
**You can store assessment scores in the database without needing JavaScript<br />
**You can hide assessment scores without needing JavaScript or CSS<br />
#Replacement Fields<br />
**Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.<br />
**This also avoids the common need to edit questions to change the SGQA code to make everything work.<br />
#Tailoring - you can conditionally display text based upon other values<br />
**Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")<br />
**Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 chldren")<br />
**Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.<br />
#New Variable Attributes - you can access the following to do your tailoring:<br />
** (no suffix) - an alias for qcode.code<br />
**.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<br />
**.NAOK - same as .code, but can be part of calculations or lists even if irrelevant<br />
**.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question<br />
**.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant<br />
**.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)<br />
**.qid - the question ID<br />
**.gid - the group ID<br />
**.sgqa - the SGQA value for the question<br />
**.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another<br />
**.qseq - the question sequence (starting from 0)<br />
**.gseq - the group sequence (starting from 0)<br />
**.mandatory - whether the question is mandatory (Y/N)<br />
**.question - the text of the question<br />
**.relevance - the relevance equation for the question<br />
**.grelevance - the relevance equation for the group<br />
**.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)<br />
**.type - the question type (the one character code)<br />
#Dynamic On-Page Changes<br />
**All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page<br />
**So, you have questions dynamically appear/disappear based upon whether they are relevant<br />
**Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.<br />
#New Data Entry Screen<br />
**In addition to using the current data-entry system, you can just use Survey-All-In-One.<br />
**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<br />
**This can be critical if your data entry person needs to see the tailoring, which is also dynamic.<br />
#Eliminates the need for most custom JavaScript<br />
**EM easily supports complicated computations, scoring, tailoring and conditional logic.<br />
**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.<br />
<br />
==What are some other helpful new features enabled by EM?==<br />
<br />
Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:<br />
#You can create more complex validation criteria<br />
**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.<br />
**EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.<br />
#Easy Re-ordering (or deleting) of Questions and Groups<br />
**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.<br />
**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.<br />
**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).<br />
#The Question/Group Navigation Index is always available and accurate<br />
**Prior to version 1.92, these indexes were not available if there were complex conditions<br />
**With EM, we can guarantee that they are accurate.<br />
**Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)<br />
***When jumping forwards, EM will re-validate all of the intervening questions/groups.<br />
***If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent<br />
***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.<br />
#Auto-conversion of Conditions to Relevance<br />
**When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them<br />
**Whenever you import a survey, relevance equations will be created as needed<br />
**Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.<br />
#Convenient Syntax Highlighting<br />
**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.<br />
**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.<br />
**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).<br />
***The list of answer choices uses this syntax: 'answers':{key:val, ... }.<br />
***''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.<br />
***''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)<br />
***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).<br />
#Easy review of entire survey logic and content<br />
**There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.<br />
**It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)<br />
**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.<br />
**Eveything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)<br />
**The syntax-highligting supports rapid navigation and editing of the survey.<br />
***If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.<br />
***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.<br />
***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)<br />
**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<br />
<br />
==How Backwards Compatible is EM with 1.91+?==<br />
<br />
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+.<br />
<br />
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.<br />
<br />
=Getting Started=<br />
<br />
The best way to get started with EM is to:<br />
*Install 1.92+ from http://www.limesurvey.org/en/download .<br />
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].<br />
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].<br />
*Explore the EM documentation (this page)<br />
*Examine the built-in EM test suite<br />
**From any survey, under tools, select the EM option<br />
**Availalbe Functions lists the 70+ functions and syntax<br />
**Unit Tests of Isolsted Expressions<br />
***shows examples of using all EM functions and operators, and the PHP and JavaScript results<br />
***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.<br />
<br />
=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=<br />
<br />
==Conditions => Relevance==<br />
<br />
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.<br />
<br />
==Assessments => Equations and Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Replacements => Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
==Equations==<br />
<br />
Equations were not supported without fancy JavaScript.<br />
<br />
==Equation Question Type==<br />
<br />
Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.<br />
<br />
=How Will Expression Manager Replace/Extend That Functionality?=<br />
<br />
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.<br />
<br />
==New Terminology When Referring to Expression Manager (EM)==<br />
<br />
EM "thinks" of its functionality in the following terms:<br />
*'''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).<br />
*'''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.<br />
*'''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.<br />
<br />
===Relevance and Cascading Relevance===<br />
<br />
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 diplayed. 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.<br />
<br />
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.<br />
<br />
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:<br />
<br />
{|<br />
|Question Code||Relevance||Question<br />
|-<br />
|Q1||1||What is your name?<br />
|-<br />
|Q2||Q1||{Q1}, how old are you?<br />
|-<br />
|Q3||Q2||So, you are {Q2} years old. Are you married?<br />
|-<br />
|Q4||Q3 == "Y"||{Q1}, how long have you been married?<br />
|-<br />
|Q5||Q4||How many children do you have, {Q1}?<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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 and 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.<br />
<br />
===Group-Level Relevance===<br />
<br />
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 deterimine 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.<br />
<br />
===Tailoring / Piping===<br />
<br />
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).<br />
<br />
Using these equations, you can do things such as:<br />
#Conditionally show tailored messages to the respondants based upon prior responses<br />
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself<br />
#Conjugate verbs and decline nouns within questions, answers, and reports.<br />
#Show summaries of responses before the "Show your answers" page at the end of the survey<br />
<br />
===Equations===<br />
<br />
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.<br />
<br />
This solves a common request for storing Assessment scores within the database<br />
<br />
==Syntax==<br />
<br />
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).<br />
<br />
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:<br />
<br />
<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),<br />
<br />
'',<br />
<br />
if(PFTotals >= -5 && PFTotals <= -4,<br />
<br />
'Very Soft',<br />
<br />
if(PFTotals >= -3 && PFTotals <= -2,<br />
<br />
'Soft',<br />
<br />
if(PFTotals == -1,<br />
<br />
'Somewhat Soft',<br />
<br />
if(PFTotals == 0,<br />
<br />
'Moderate',<br />
<br />
if(PFTotals == 1,<br />
<br />
'Somewhat Hard',<br />
<br />
if(PFTotals >= 2 && PFTotals <= 3,<br />
<br />
'Hard',<br />
<br />
if(PFTotals >= 4 && PFTotals <= 5,<br />
<br />
'Very Hard',<br />
<br />
''<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)}<br />
<br />
</syntaxhighlight><br />
<br />
Expression Manager supports the following syntax:<br />
*All standard mathematical operators (e.g. +,-,*,/,!)<br />
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)<br />
*Parentheses (so you can group sub-expressions)<br />
*Conditional operators (e.g. &&,| | and these equivalents: and,or)<br />
*Single and double-quoted strings (which can each embed strings with the other quote type)<br />
*Comma operator (so can have a list of expressions and just return the final result)<br />
*Assignment operator (=)<br />
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes<br />
*Pre-defined functions (there are already 70+, and it is easy to add more)<br />
<br />
EM syntax follows normal operator precedence:<br />
<br />
{|<br />
|Level||Operator(s)||Description<br />
|-<br />
|1||()||parentheses for grouping or calling functions<br />
|-<br />
|2||! - +||unary operators: not, negation, unary-plus<br />
|-<br />
|3||* /||times, divide<br />
|-<br />
|4||+ -||plus, minus<br />
|-<br />
|5||< <= > >= lt le gt ge||relative comparisons<br />
|-<br />
|6||== != eq ne||equality comparisons<br />
|-<br />
|7||and||logical AND<br />
|-<br />
|8||or||logical OR<br />
|-<br />
|9||=||assignment operator<br />
|-<br />
|10||,||comma operator<br />
|-<br />
|<br />
|}<br />
<br />
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).<br />
<br />
===Caution about using Assignment Operator (=)===<br />
<br />
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 sould 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.<br />
<br />
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 "==")<br />
<br />
The main reasons you may want to use assignment are:<br />
*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.<br />
*You need to forcibly change the response to a previous question based upon a later response<br />
<br />
==Access to Variables==<br />
<br />
Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:<br />
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5)<br />
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")<br />
*All {XXX} values used by templates<br />
<br />
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.<br />
<br />
Furthermore, Expression Manager lets you access many properties of the Question:<br />
<br />
{|<br />
|Syntax||Meaning||Example||Example Result<br />
|-<br />
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'<br />
|-<br />
|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'<br />
|-<br />
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'<br />
|-<br />
|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'<br />
|-<br />
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'<br />
|-<br />
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'<br />
|-<br />
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'<br />
|-<br />
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'<br />
|-<br />
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337<br />
|-<br />
|Qcode.type||the question type||{gender.type}||'G'<br />
|-<br />
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'<br />
|-<br />
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3<br />
|-<br />
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5<br />
|-<br />
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1<br />
|-<br />
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus)||1<br />
|-<br />
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'<br />
|-<br />
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'<br />
|-<br />
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'<br />
|-<br />
|<br />
|}<br />
<br />
=== Security issue===<br />
<br />
For security issue, text entered by user are filtered. Some caracter are replaced by HTML entities.<br />
* & by &amp;<br />
* < by &lt;<br />
* > by &gt;<br />
<br />
==Qcode Variable Naming==<br />
<br />
Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:<br />
<br />
QuestionCode . '_' . AnswerID . '_' . ScaleId<br />
<br />
{|<br />
|Type||Description||Code||SubQs||Answer Options||Scales||Answer Code||Answer Shown||Relevance<br />
|-<br />
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}<br />
|-<br />
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}<br />
|-<br />
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}<br />
|-<br />
|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'}<br />
|-<br />
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}<br />
|-<br />
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}<br />
|-<br />
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}<br />
|-<br />
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}<br />
|-<br />
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}<br />
|-<br />
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}<br />
|-<br />
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||<br />
|-<br />
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||<br />
|-<br />
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}<br />
|-<br />
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}<br />
|-<br />
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}<br />
|-<br />
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}<br />
|-<br />
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}<br />
|-<br />
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}<br />
|-<br />
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}<br />
|-<br />
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20_comment}||{Q20.shown}||{Q20=='B'}<br />
|-<br />
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}<br />
|-<br />
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}<br />
|-<br />
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_D_comment}||{Q23_D.shown}||{!is_empty(Q23)}<br />
|-<br />
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}<br />
|-<br />
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q')}<br />
|-<br />
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}<br />
|-<br />
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}<br />
|-<br />
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}<br />
|-<br />
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}<br />
|-<br />
|<br />
|}<br />
<br />
==The reserved 'this', 'self', and 'that' variables==<br />
<br />
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.<br />
<br />
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).<br />
<br />
The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:<br />
*self<br />
*self.''suffix''<br />
*self.''sub-selector''<br />
*self.''sub-selector''.''suffix''<br />
<br />
''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)<br />
<br />
''sub-selector'' is one of:<br />
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)<br />
*nocomments - only subquestions that are not comments<br />
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected.<br />
<br />
Examples:<br />
*Has any part of a question been answered? {count(self.NAOK)>0}<br />
*What is the assessment score for this question? {sum(self.value)}<br />
<br />
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.<br />
*What is the grand total? {sum(self.NAOK)}<br />
*What is the total of row B? {sum(self.sq_B.NAOK)}<br />
*What is the total of column 3? {sum(self.sq_3.NAOK)}<br />
<br />
The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:<br />
*that.''qname''<br />
*that.''qname''.''suffix''<br />
*that.''qname''.''sub-selector''<br />
*that.''qname''.''sub-selector''.''suffix''<br />
<br />
''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''<br />
<br />
Examples:<br />
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}<br />
*What is the assessment score for q2? (sum(that.q2.NAOK)}<br />
*What is the grand total of q3? {sum(that.q3.NAOK)}<br />
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}<br />
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}<br />
<br />
The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.<br />
<br />
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'<br />
<br />
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.<br />
<br />
==Access to Functions==<br />
<br />
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.<br />
<br />
===Implemented Functions===<br />
<br />
The following functions are currently available:<br />
<br />
{|<br />
|Function||Meaning||Syntax<br />
|-<br />
[http://www.php.net/manual/en/function.abs.php ||abs]||Absolute value||number abs(number)<br />
|-<br />
[http://www.php.net/manual/en/function.acos.php ||acos]||Arc cosine||number acos(number)<br />
|-<br />
[http://www.php.net/manual/en/function.addslashes.php ||addslashes]||Quote string with slashes||string addslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.asin.php ||asin]||Arc sine||number asin(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan.php ||atan]||Arc tangent||number atan(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan2.php ||atan2]||Arc tangent of two variables||number atan2(number, number)<br />
|-<br />
[http://www.php.net/manual/en/function.ceil.php ||ceil]||Round fractions up||number ceil(number)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.cos.php ||cos]||Cosine||number cos(number)<br />
|-<br />
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)<br />
|-<br />
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)<br />
|-<br />
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.date.php ||date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[http://www.php.net/manual/en/function.exp.php ||exp]||Calculates the exponent of e||number exp(number)<br />
|-<br />
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)<br />
|-<br />
[http://www.php.net/manual/en/function.floor.php ||floor]||Round fractions down||number floor(number)<br />
|-<br />
[http://www.php.net/manual/en/function.gmdate.php ||gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.idate.php ||idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)<br />
|-<br />
[http://www.php.net/manual/en/function.implode.php ||implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)<br />
|-<br />
[http://www.php.net/manual/en/function.intval.php ||intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])<br />
|-<br />
[http://www.php.net/manual/en/function.empty.php ||is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.is-nan.php ||is_nan]||Finds whether a value is not a number||bool is_nan(var)<br />
|-<br />
[http://www.php.net/manual/en/function.is-null.php ||is_null]||Finds whether a variable is NULL||bool is_null(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
|join {MOUSEOVER(label="v")}In last 2.0 version{MOUSEOVER}||Join elements as a new string||join(arg1, arg2, ... argN)<br />
|-<br />
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)<br />
|-<br />
[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)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.max.php ||max]||Find highest value||number max(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.min.php ||min]||Find lowest value||number min(arg1, arg2, ... argN)<br />
|-<br />
[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 ]]]]]])<br />
|-<br />
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)<br />
|-<br />
[http://www.php.net/manual/en/function.nl2br.php ||nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)<br />
|-<br />
[http://www.php.net/manual/en/function.number-format.php ||number_format]||Format a number with grouped thousands||string number_format(number)<br />
|-<br />
|pi||Get value of pi||number pi()<br />
|-<br />
[http://www.php.net/manual/en/function.pow.php ||pow]||Exponential expression||number pow(base, exp)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.quotemeta.php ||quotemeta]||Quote meta characters||string quotemeta(string)<br />
|-<br />
[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)<br />
|-<br />
|regexMatch||compare a string to a [[Using regular expressions||regular expression]]||bool regexMatch(pattern,input)<br />
|-<br />
[http://www.php.net/manual/en/function.round.php ||round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.sin.php ||sin]||Sine||number sin(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.sprintf.php ||sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.sqrt.php ||sqrt]||Square root||number sqrt(arg)<br />
|-<br />
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.str-repeat.php ||str_repeat]||Repeat a string||string str_repeat(input, multiplier)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.strcasecmp.php ||strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)<br />
|-<br />
[http://www.php.net/manual/en/function.strcmp.php ||strcmp]||Binary safe string comparison||int strcmp(str1, str2)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.stripos.php ||stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.stripslashes.php ||stripslashes]||Un-quotes a quoted string||string stripslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.stristr.php ||stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])<br />
|-<br />
[http://www.php.net/manual/en/function.strlen.php ||strlen]||Get string length||int strlen(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strpos.php ||strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.strrev.php ||strrev]||Reverse a string||string strrev(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strstr.php ||strstr]||Find first occurrence of a string||string strstr(haystack, needle)<br />
|-<br />
[http://www.php.net/manual/en/function.strtolower.php ||strtolower]||Make a string lowercase||string strtolower(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strtoupper.php ||strtoupper]||Make a string uppercase||string strtoupper(string)<br />
|-<br />
[http://www.php.net/manual/en/function.substr.php ||substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])<br />
|-<br />
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)<br />
|-<br />
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.tan.php ||tan]||Tangent||number tan(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.time.php ||time]||Return current UNIX timestamp||number time()<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.ucwords.php ||ucwords]||Uppercase the first character of each word in a string||string ucwords(string)<br />
|-<br />
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)<br />
|-<br />
|<br />
|}<br />
<br />
===Functions that are Planned or Being Considered===<br />
<br />
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.<br />
<br />
{|<br />
|Syntax||Meaning||Comments<br />
|-<br />
|e()||returns the value of e||<br />
|-<br />
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||<br />
|-<br />
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||<br />
|-<br />
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown<br />
|-<br />
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||<br />
|-<br />
|getRelevance(X)||returns the relevance equation for question X||<br />
|-<br />
|getStartTime()||returns the date corresponding to the system time when the interview was started||<br />
|-<br />
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||<br />
|-<br />
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||<br />
|-<br />
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||<br />
|-<br />
|isInvalid(X)||returns true if the answer is of type *INVALID*||<br />
|-<br />
|isNA(X)||returns true if the answer is of type *NA*||<br />
|-<br />
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||<br />
|-<br />
|isRefused(X)||returns true if the answer is of type *REFUSED*||<br />
|-<br />
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||<br />
|-<br />
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||<br />
|-<br />
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||<br />
|-<br />
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||<br />
|-<br />
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||<br />
|-<br />
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||<br />
|-<br />
|mean(X,...)||returns the mean of a list of values||<br />
|-<br />
|numAnsOptions(X)||returns the number of answer options that question X has||<br />
|-<br />
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||<br />
|-<br />
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||<br />
|-<br />
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||<br />
|-<br />
|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.||<br />
|-<br />
|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.||<br />
|-<br />
|<br />
|}<br />
<br />
==Expression Manager Knows Which Variables are Local==<br />
<br />
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).<br />
<br />
==Cascading Conditions==<br />
<br />
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<br />
<br />
{|<br />
|Operator||Example||a||b||Result<br />
|-<br />
|+ (unary)||+a||N/A|| ||false<br />
|-<br />
|- (unary)||-a||N/A|| ||false<br />
|-<br />
|!||!a||N/A|| ||false<br />
|-<br />
|== (or eq)||a == b||N/A||5||false<br />
|-<br />
|== (or eq)||a == b||N/A||0||false<br />
|-<br />
|== (or eq)||a == b||N/A||N/A||false<br />
|-<br />
|!= (or ne)||a != b||N/A||5|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||N/A|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||0||false<br />
|-<br />
|> (or gt)||a > b||N/A||5|| false<br />
|-<br />
|>= (or ge)||a >= b||N/A||5||false<br />
|-<br />
|< (or lt)||a < b||N/A||5||false<br />
|-<br />
|<= (or le)||a <= b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||5||false<br />
|-<br />
|+||a + b||N/A||5||false<br />
|-<br />
|-||a - b||N/A||5||false<br />
|-<br />
|*||a * b||N/A||5||false<br />
|-<br />
|/||a / b||5||N/A||false<br />
|-<br />
|()||(a)||N/A|| ||false<br />
|-<br />
|(exp)||(a && b)||N/A||5||false<br />
|-<br />
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false<br />
|-<br />
|function||sum(a,b,b)||N/A||5||false<br />
|-<br />
|function||max(a,b)||N/A||5||false<br />
|-<br />
|function||min(a,b)||N/A||5||false<br />
|-<br />
|function||implode(', ',a,b,a,b)||N/A||5||false<br />
|-<br />
|function||if(a,a,b)||N/A||5||false<br />
|-<br />
|function||is_empty(a)||N/A|| ||false<br />
|-<br />
|function||is_empty(a)||0 (or blank)|| ||true<br />
|-<br />
|function||!is_empty(a)||N/A|| ||false<br />
|-<br />
|<br />
|}<br />
<br />
===Overriding Cascading Conditions===<br />
<br />
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.<br />
<br />
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<br />
#q1 is not added to the LEManyNA() clause<br />
#LEMval('q1') will continue to check whether the response is relevant, and will return '' if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression.<br />
<br />
So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).<br />
<br />
The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converage 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.<br />
<br />
==How does Expression Manager Support Conditional Micro-Tailoring?==<br />
<br />
Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):<br />
<br />
{|<br />
|Question Code||Relevance||Question Type||Question<br />
|-<br />
|name||1||text||What is your name?<br />
|-<br />
|age||1||text||How old are you?<br />
|-<br />
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}<br />
|-<br />
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.<br />
|-<br />
|kids||!badage||yesno||Do you have children?<br />
|-<br />
|parents||1||expr||{!badage && kids=='Y'}<br />
|-<br />
|numKids||parents||text||How many children do you have?<br />
|-<br />
|kid1||parents && numKids >= 1||text||How old is your first child?<br />
|-<br />
|kid2||parents && numKids >= 2||text||How old is your second child?<br />
|-<br />
|kid3||parents && numKids >= 3||text||How old is your third child?<br />
|-<br />
|kid4||parents && numKids >= 4||text||How old is your fourth child?<br />
|-<br />
|kid5||parents && numKids >= 5||text||How old is your fifth child?<br />
|-<br />
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}<br />
|-<br />
|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}<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==<br />
<br />
{|<br />
|Old Feature||New Feature||Comments<br />
|-<br />
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables<br />
|-<br />
|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<br />
|-<br />
|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\})<br />
|-<br />
|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<br />
|-<br />
|<br />
|}<br />
<br />
=Syntax Highlighting=<br />
<br />
To help with entering and validating expressions, EM provides syntax highlighting with the following features:<br />
<br />
==Types and Meanings of Syntax Highlighting==<br />
<br />
{|<br />
|Color||Sample||Meaning||Tooltip||Comments<br />
|-<br />
|tan background||<span style='color:#eee8aa,#eee8aa'>Sample</span>||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<br />
|-<br />
|blue bold text||'''<span style='color:blue,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|grey text||<span style='color:grey,#eee8aa'>'Sample'</span>||string||none||single and double-quoted strings are shown in grey text<br />
|-<br />
|bold maroon text||'''<span style='color:maroon,#eee8aa'>Sample</span>'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. 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.<br />
|-<br />
|bold cyan text||'''<span style='color:#4C88BE,#eee8aa'>Sample</span>'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan 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.<br />
|-<br />
|bold green text||'''<span style='color:green,#eee8aa'>Sample</span>'''||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 pageis 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.<br />
|-<br />
|bold pink text||'''<span style='color:#FF00FF,#eee8aa'>Sample</span>'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior pageis 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.<br />
|-<br />
|bold tan text||'''<span style='color:#996600,#eee8aa'>Sample</span>'''||a lime relacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE} are shown in bold tan text. The tooltip shows the current value.<br />
|-<br />
|red text||'''<span style='color:red,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|normal black text||<span style='color:black,#eee8aa'>Sample</span>||punctuation||none||All other punctionation within the expression is shown as normal black text.<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
=Relationship to LimeSurvey Ideas / Feature Requests=<br />
<br />
Expression Manager provides complete or partial solutions to each of the following:<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1 Conditions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/3/ Answercounts]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/5 Advanced reporting for assessments]<br />
**partial: Equations let one store the Assessment value in the database, and micro-tailoring can generate simple formatted reports. Authors can access those Equation values if they have more complex reporting needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/6 Assessment reports]<br />
**partial: Since Equations store the Assessment score, it should be possible to use Statistics to show distributions of those scores, and Quotas to limit the number of responses with those scores.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/7 Store assessment results for further evaluation]<br />
**Equations let one store the Assessment value in the database, completely solving this problem<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/22/ More advanced condition rules]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/28 Open Answertable up so that we can alter formatting]<br />
**partial: All of the question attributes are available, so authors can create custom AnswerTable equivalents as a Question. Once implatemented, they can also use the showTheseResponses() or showAllResponsesExecpt() functions<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/37 Export survey results with full questions to include images]<br />
**since Tailoring has access to the full question text, it can include images in the export<br />
**if subjects choose Print Your Answers after finishing the survey, those printouts will be fully tailored<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/63 List of question codes and SGQA identifiers]<br />
**The Show Survey Logic view shows that mapping (plus much more information)<br />
**In addition, you no longer have to use SGQA codes to refer to variables - you can use the Question code/title.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/69 Branch/jump to another question (earlier or later) based on current question]<br />
**You can use the Navigation Index for this in most cases<br />
**Once implemented, you can use the JumpTo() function. Like the Navigation Index, if you try to jump forward, it will stop on an intervening page if there are any of the relevant mandatory questions are unanswered, or if any relevant questions fail validation tests.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/86 set quota for total responses]<br />
**If the final question is an Equation that flags a survey as completed (so is NULL if a respondant does not get to that page), you can use Quotas on that question to control the number of completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/101 Review all conditions]<br />
**The [[Show Logic File|Show Logic File]] view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/105 Review all questions + Review all groups]<br />
**The [[Show Logic File|Show Logic File]] view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/107 How to visualize questions, logic & conditions]<br />
**The [[Show Logic File|Show Logic File]] view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/113 Offline Surveys]<br />
**Running a survey with all of the questions on the same page would let you do off-line data collection (e.g. email the html page and associated JavaScript). However, you would still want a way to submit the results so that they did not get lost. It may be possible to use Save As HTML to save partially completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/120 Remove INSERTANS from question text at survey results]<br />
**INSERTANS is no longer needed. You can refer to a variable by its SGQA code (without prefixing it with INSERTANS:), or by its question code.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/137 Informed Consent and Authorization Functionality]<br />
**You can show show the informed consent on the welcome page, then ask any additional questions needed (to ensure they meet the study inclusion/exclusion criteria), and ask them a Yes/No question whether they give their consent. Then, make all of the remaining questions conditional on that yesNo. For example, if the question is named ''consent'', you would set the relevance to the remaining questions to ''consent == "Y"'' (possibly ''and''ing that with whatever additional conditions you needed to support your branching needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/199 Show codes instead of of answers using INSERTANS]<br />
**{Qcode} returns the code instead of the response text (which you can get via {INSERTANS:SGQA}, or {Qcode.shown}<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/204 Need group mean or calculations for assessments]<br />
**Say you have N variables of which N-X were answered, you could compute the mean of the answered variables as {sum(var1, var2, ..., varN) / count(var1, var2, ..., varN)}<br />
**Computing the mean across a set of respondants would require extension of the Quota functionality.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/222 To insert a language dependent text]<br />
**Tailoring lets you conjugate verbs and decline nouns in each language<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/225 Surveyors should approve their answers]<br />
**Custom Questions with tailoring, or the showAllResponsesExcept() function will let Surveyors see all of the questions and responses before clicking Submit. If the Navigation Menu option is enabled, it is easy to go back and correct answers.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Suppliment to #answernnXnnXnnn method of targetting form elements]<br />
**You can now refer to questions and answers by their Question Code, so there is no longer a need to modify SGQA values.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/262 More flexibility with hidden questions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/265 Remove specific conditions from multiple questions]<br />
**You can now use Relevance, which is easier to manage than Conditions. If needed, they can all be exported from the database, edited in a spreadsheet, and re-imported.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/268 Cross Survey Reporting]<br />
**By using question codes that are unique across your surveys and versions, you can consolidate data from multiple surveys and/or compare them<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/275 Simplifying integration with other tools]<br />
**Expression Manager uses Question Codes instead of SGQA, making it easier to integrate with other tools.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Expose assessment score to 3rd party app processing]<br />
**This can be done with Equation question type<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/309 Multiple thank you pages]<br />
**This can be supported via conditional relevance branching and tailoring<br />
<br />
=Additional Reading=<br />
<br />
==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==<br />
<br />
==[[Expression Manager HowTos|Use Cases and HowTos]]==<br />
<br />
==[[Expression Manager Examples|Step-by-Step Examples]].==<br />
<br />
==[[Expression Manager for developers|Reference for Developers]]==<br />
<br />
==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==</div>Adminhttps://www.limesurvey.org/manual/index.php?title=General_FAQ&diff=1339General FAQ2013-02-05T22:22:26Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Getting started=<br />
<br />
If you don't want to read half the manual to get a feeling what can be done with Limesurvey we recommend to watch some videos (see below).<br />
<br />
After that the [[Creating surveys - Introduction]] manual page might be a good start.<br />
<br />
==I need a quick introduction for LimeSurvey==<br />
<br />
For a first start have a look at our very basic [[LimeSurvey Video-Tutorial]].<br />
<br />
There is [http://vimeo.com/4951738 another tutorial] which shows you how to get started with using Lime Survey to conduct online surveys. In [http://vimeo.com/4951738 this video] we'll create our first survey, deliver it to a user and then view the submitted results.<br />
<br />
There are some '''more videos on YouTube''':<br />
<br />
'''''Limesurvey:'''''<br />
*[http://www.youtube.com/watch?v=96WdtqDmRVw Planning a survey]<br />
*[http://www.youtube.com/watch?v=6GH-S3YAHRg Creating a survey]<br />
*[http://www.youtube.com/watch?v=61p1Yre4GFM Entering questions]<br />
*[http://www.youtube.com/watch?v=5eiZHw9mjDg Using label sets]<br />
*[http://www.youtube.com/watch?v=5fI9Fyk5UCk Exporting data from LimeSurvey]<br />
<br />
'''''Old PHP-surveyor videos:'''''<br />
*[http://www.youtube.com/watch?v=c8OiA0bv8Rk Getting to the phpsurveyors Admin Pages]<br />
*[http://www.youtube.com/watch?v=KOq45Val3v8 Creating a new group in a survey]<br />
*[http://www.youtube.com/watch?v=bXGQeP8f7kQ Creating a new question for phpsurveyor]<br />
*[http://www.youtube.com/watch?v=1mzZ3KCaGAc Testing a newly created/modified Survey]<br />
*[http://www.youtube.com/watch?v=6Y2L23y6bps Add respondent]<br />
*[http://www.youtube.com/watch?v=NcnK5YsfB8g Emailing to the respondents]<br />
<br />
=Survey design and layout=<br />
<br />
==How do I get rid of the <span style='color:red'>*</span> (red asterisk) of mandatory questions?==<br />
<br />
In '''LimeSurvey Version 1.80 and above''' the red asterisk of mandatory questions is set within the template.css file ("asterisk" class). To hide it:<br />
*Open the template editor<br />
*Create a copy of the template you wish to modify<br />
*Select the "template.css" file and search for the asterix class<br />
*Add the following line at the end of the asterix class".asterisk {display: none;}".<br />
*Save template.css<br />
*Clear your browser cache so that the edited template.css is reloaded and not taken from cache.<br />
<br />
In '''LimeSurvey Version 1.53''' the red asterisk of mandatory questions is set within the css "asterisk" class. To hide it:<br />
*Open the template editor<br />
*Select the template you wish to modify so that the asterisk doesn't show<br />
*Select the "startpage.pstpl" file<br />
*Add the css ".asterisk {display: none;}" into the css stylesheet area.<br />
<br />
'''Earlier Versions'''<br />
*Open qanda.php in your text editor<br />
*Search for the string "asterisk"<br />
*Comment out this line with two slashes "//" at the beginning of the line<br />
*Example:<br />
**original: $qtitle = '<span class=\'asterisk\'>'.$clang->gT('*').'</span>'.$qtitle;<br />
**modified: // $qtitle = '<span class=\'asterisk\'>'.$clang->gT('*').'</span>'.$qtitle;<br />
<br />
==How can I embed a flash file?==<br />
<br />
First go to [[Global settings]] and deactivate the XSS-filter. Please also read up in the implications deactivating that filter. The following steps won't work if the filter is active.<br />
#Navigate to the place in your survey where you want insert your Flash file. This can be anywhere where you can use the integrated HTML editor, for example in questions, subquestions, answers, survey welcome/end text and many more.<br />
#Open the [http://docs.limesurvey.org/tiki-index.php?page=First+Login+%2F+You+user+preferences&structure;=English+Instructions+for+LimeSurvey#Popup:_The_normal_text_editor_is_used_but_the_HTML_editor_is_available_as_a_pop_up_option. full-screen editor mode] by clicking the 'LimeFitWin' button on the editor tool-bar.<br />
#On the full-screen editor tool-bar you will find a little button with a Flash symbol. Click on it. A dialog will open.<br />
#In this dialog you can give either the path to an existing Flash file somewhere OR you click the 'Browse server' button.<br />
#If you clicked the 'Browse server' button you will be presented with a file browser and on the bottom an file upload field. Choose now an existing file or upload a file first.<br />
<br />
That's it! If you find this description incomplete please update it accordingly.<br />
<br />
==How to remove one of these texts from my survey==<br />
<br />
==="There are X questions"===<br />
<br />
==="A note on privacy..."===<br />
<br />
===question code===<br />
<br />
All these texts are inserted at the template you are using by [http://docs.limesurvey.org/tiki-index.php?page=Template+editor&structure;=English+Instructions+for+LimeSurvey#Replacements_Field_Strings placeholders]. You can easily remove them. Go to the [http://docs.limesurvey.org/tiki-index.php?page=Template+editor&structure;=English+Instructions+for+LimeSurvey Template Editor] and remove the {THEREAREXQUESTIONS} / {PRIVACYMESSAGE} / {QUESTION_CODE} placeholder(s).<br />
<br />
=Survey configuration=<br />
<br />
==How do I create a survey which is open to everyone?==<br />
<br />
To make a survey public to everyone you should:<br />
* not [http://docs.limesurvey.org/tiki-index.php?page=Tokens&structure;=English+Instructions+for+LimeSurvey#How_to_activate_tokens_ create a token table] (if there is one, drop it)<br />
* at survey settings set "[http://docs.limesurvey.org/tiki-index.php?page=Creating+a+new+survey&structure;=English+Instructions+for+LimeSurvey#Publication_amp_Access_control Only users with tokens may enter the survey]" = no (old setting)<br />
* at survey settings set "[http://docs.limesurvey.org/tiki-index.php?page=Creating+a+new+survey&structure;=English+Instructions+for+LimeSurvey#Publication_amp_Access_control allow public registration]" = no<br />
* at survey settings set "[http://docs.limesurvey.org/tiki-index.php?page=Creating+a+new+survey&structure;=English+Instructions+for+LimeSurvey#Presentation_amp_Navigation list this survey publicly]"<br />
<br />
Your survey should then be listed at the root page of your limesurvey installation. You can publish the link to the survey on your website/blog and everyone can take the survey without restrictions.<br />
<br />
==How can I stop the system from sending confirmation emails==<br />
<br />
If you are [http://docs.limesurvey.org/tiki-index.php?page=Tokens&structure;=English+Instructions+for+LimeSurvey#Email_settings using tokens] and a participant fills out the survey, a confirmation email is sent to his/her email address. If you don't want this message to be sent just delete the whole ''confirmation email'' subject and message. You have to [http://docs.limesurvey.org/tiki-index.php?page=First+Login+%2F+You+user+preferences&structure;=English+Instructions+for+LimeSurvey#X._Source_code_mode: switch to source code mode] to be able to delete all the text. Save the empty message and no confirmation emails should be sent anymore.<br />
<br />
=Help, I accidentally...=<br />
<br />
==I forgot my admin password. How do I reset it?==<br />
# For version 1.47 to 1.53 only: Download [[Media:resetadminpw.php|this file]] and copy it to /<your limesurveydir>/admin/install/ .<br />
# For version 1.7 or later: Restore your /<your limesurveydir>/admin/install/ directory from the download package<br />
# Execute resetadminpw.php using your browser by pointing it to <syntaxhighlight lang="php" enclose="div">http://www.your_domain.com/your_limesurvey_dir/admin/install/resetadminpw.php</syntaxhighlight><br />
# After removing the /install directory again you should be able to login with $defaultuser (Default: admin) and $defaultpass (Default: password) set in config.php.<br />
<br />
==How can I restore data from a deactivated survey?==<br />
<br />
We recommend to always use the time-out option instead of deactivating a survey. If you closed your survey accidentally it is important that you don't change anything in the survey.<br />
<br />
Then, and only then the following steps will work:<br />
#Activate your survey again<br />
#Go to the "Browse responses for this survey" menu.<br />
#Click at the "Import answers from a deactivated survey table" button.<br />
#Choose your source table.<br />
#Click at the "Import responses" button.<br />
<br />
==I deleted a question/question group/survey!==<br />
<br />
This is bad luck. If you delete it, it is really gone. In that case only a backup will help you (which of course you did regularly, didn't you?).<br />
<br />
=Hard- and Software requirements=<br />
<br />
For general requirements please refer to our [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Make_sure_you_can_use_LimeSurvey_on_your_website installation instructions].<br />
<br />
==What limitations does LimeSurvey have...==<br />
<br />
=== ...regarding speed===<br />
<br />
There is no existing speed limit on LimeSurvey. It all depends on how fast your server and your connection is. If you expect a large number of users within a short time and you are not sure if your server can handle this check our forum for according topics about other users' experience.<br />
<br />
=== ...regarding survey size===<br />
<br />
Note: 'Survey size' refers to the maximmum number of questions (and answers) in your survey - '''don't confuse this with the number of replies on your survey (there is no limitation on that)'''. Theoretically there would also be no limit on the maximum number of questions/answers in LimeSurvey. But the database engine you are using has several limits. The most important one is the limit on the number of fields(columns) in the result table.<br />
*MySQL ISAM: The sum of the lengths of the VARCHAR and CHAR columns in a table may be up to 64KB.<br />
*MySQL InnoDB: Maximum number of 1000 columns<br />
*MS SQL Server 2000: Maximum number of 1024 columns<br />
*Postgres: Maximum number of 250-1600 columns depending on column types. The maximum number of columns can be quadrupled by increasing the default block size to 32k. See [[Installation FAQ]] and [http://www.postgresql.org/docs/faqs.FAQ.html#item4.4 PostgreSQL FAQ].<br />
<br />
The mySQL ISAM engine is the most tricky one (see [http://dev.mysql.com/doc/refman/5.0/en/column-count-limit.html mysql documentation for more information]). As it allows only up to 65,535 bytes per row and utf8 characters can require up to three bytes per character the maximum may be only 21,844 characters (but this depends on your DB encoding).<br />
<br />
You can roughly calculate the size of your survey like this:<br />
*Every multiple numerical question: 20 chars '''for each answer'''<br />
*Every multiple choice & array question answers: 5 chars '''for each answer'''<br />
*Every other question type: 5 chars<br />
*Add 10% for the usual overhead<br />
<br />
==How to increase the maximum number of columns in PostgreSQL==<br />
<br />
In case your survey contains too many questions you can define a different block size in PostgreSQL so it is possible to create more columns. This might be tricky because you have to recompile PostgreSQL and set BLCKSZ to a higher value, like 16kiB or 32kiB. Watch for the configuration option "--with-blocksize=BLOCKSIZE". For details see the archives of the PostgreSQL mailing list or ask there (pgsql-patches(at)postgresql(dot)org).<br />
<br />
Instructions for Debian (thanks to Martin Pitt):<br />
<br />
<syntaxhighlight lang="c" enclose="div"> sudo apt-get build-dep postgresql-8.3<br />
<br />
apt-get source postgresql-8.3<br />
<br />
cd postgresql-8.3-*<br />
<br />
debian/rules patch<br />
<br />
sensible-editor build-tree/postgresql-8.3.5/src/include/pg_config_manual.h<br />
<br />
dpkg-buildpackage -us -uc -b -nc</syntaxhighlight><br />
<br />
==Survey participants get kicked out to the Surveys List page part way through. What can I do?==<br />
<br />
If you have a particularly long survey, and you find that your users can access a survey, and get part way through completing it, but then seem to get kicked out to the Surveys List page check your PHP settings. If your host is using the '''Suhosin extension for Apache''' it may be set to be too limiting on a couple of settings.<br />
<br />
For example the two settings "suhosin.post.max_vars" and "suhosin.request.max_vars" are both set to a value of 200 by default. Increase those settings both to 400 or higher so users can complete and submit long surveys.<br />
<br />
If you still have problems, try switching the module to simulation_mode (and so basically deactivate it), as the maximum value always depends on your particular survey.<br />
<br />
==Fatal error: Allowed memory size==<br />
<br />
Depending on your server configuration you might run into memory problems being reported by an error like ''"Fatal error: Allowed memory size of 8388608 bytes exhausted (tried to allocate 233472 bytes) in /path/to/htdocs/limesurvey/filename.php on line 7296"''.<br />
<br />
You can try to raise the limit by [http://docs.limesurvey.org/Optional+settings&structure;=English+Instructions+for+LimeSurvey#Resources adding an optional setting to Limesurvey's config file].<br />
<br />
Please mind that such local settings by an application can always be overruled by global server settings. To increase the memory limit to 128M directly on your server you could try adding:<br />
*memory_limit = 128M to your server's main php.ini file (recommended, if you have access)<br />
*memory_limit = 128M to a php.ini file in the LimeSurvey root<br />
*php_value memory_limit 32M in a .htaccess file in the LimeSurvey root<br />
*ini_set('memory_limit', '128M'); in your config.php<br />
<br />
=Email problems=</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_security_hints&diff=1705Installation security hints2013-02-01T14:35:02Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
==General==<br />
<br />
LimeSurvey relies on its own security system which is activated by default. The authors of this software takes no responsibility and makes no claims in relation to the appropriateness or secureness of this software. However we take security issues very serious and react quickly - if you know of any security problems with LimeSurvey please let us know: info@limesurvey.org or open a bug report at our [http://bugs.limesurvey.org bug tracker] (please mark it as private).<br />
<br />
==Linux file permissions==<br />
<br />
If you are using a Linux server, setting according file permissions is required to secure your LimeSurey installation.<br />
<br />
===Basic facts about Linux/*nix file permissions===<br />
<br />
A Linux/*nix operating system is multi-user. This means that, apart from your personal account, other user accounts may exist on the system and you should take care of what permissions you give to other users.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Hint:''' Setting file permissions is especially important in order to secure configuration files holding critical data such as passwords.</div><br />
<br />
''Note however that the 'root' account will always be granted permission to access your files (no matter what file permissions you set) as it is the super-admin user.''<br />
<br />
The webserver (which runs LimeSurvey), is also running under a given identity (user). On Linux, this is usually the 'www','www-data' (on Debian/Ubuntu), 'apache' or 'nobody' user. However, some hosting companies use systems (such as suexec) which make it possible to run LimeSurvey scripts with your personal user. Of course the webserver user must have the right to read LimeSurvey files. However, only a small subset of LimeSurvey subdirectories must be writeable by the webserver user.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Hint''': It is very valuable to revoke write permission for the webserver user to these LimeSurvey subdirectories that do not require it. Indeed, even if a LimeSurvey vulnerability might be discovered, the main files will still be protected from an illicit modification thanks to the file system permissions.</div><br />
<br />
===Setting file permissions on a self-managed Linux system===<br />
<br />
If you're managing your webserver and operating system configuration (you are the owner of the physical server or are renting a virtual server on which you have root access), you can follow these recommendations.<br />
<br />
You can first set the owner and group of your LimeSurvey files so that it will ease the file permissions setup.<br />
<br />
A possible strategy is to set the owner of the LimeSurvey files to your personal username, and the group of the LimeSurvey files to the webserver group. Usually this webserver group only contains the webserver account (and possibly another webmaster account).<br />
<br />
For instance if your username is 'myaccount' and the webserver user is 'apache' in the 'apache' group, then, from a shell access, you can use the following command:<br />
<br />
$ chown -R myaccount:apache limesurvey/<br />
<br />
Then set the file and subdirectories permissions.<br />
<br />
For the script to work properly it needs write access to some directories:<br />
*The "/limesurvey/tmp" directory and its subdirectories are used for imports/uploads and should be set to ''Read & Write'' for your webserver.<br />
*The upload/ directory and all its subdirectories must also have ''Read & Write'' for your webserver in order to enable picture and media files upload.<br />
* All other directories and files can be set to ''Read Only''<br />
<br />
<div class="simplebox">[[File:help.png]] '''Hint:''' Supposing you've followed the above recommendations on owner/group, these settings can be applied by the following commands:<br />
<br />
$ chmod -R o-r-w-x limesurvey/<br />
<br />
$ chmod -R -w limesurvey/<br />
<br />
$ chmod -R 770 limesurvey/tmp<br />
<br />
$ chmod -R 770 limesurvey/upload<br />
<br />
</div><br />
<br />
===Setting file permissions on a hosted webserver===<br />
<br />
Giving a standard procedure to secure a web application on a hosted environment is rather difficult because hosted environments differ in so many ways.<br />
<br />
As in the managed server case, for the script to work properly it needs write access to some directories:<br />
*The "/limesurvey/tmp" directory is used for imports/uploads and should be set to ''Read & Write'' for your webserver.<br />
*The upload/ directory and all its sub directories must also have ''Read & Write'' for your webserver in order to enable picture and media files upload.<br />
* The other directories and files should be set to ''Read Only''<br />
<br />
<div class="simplebox">[[File:help.png]] '''Hint:'''<br />
* Depending on your webserver configuration you will have to chmod the rights on the writable folders to 755 or 777 to make it writable for the webserver. Try 755 first - if it does not work 'upgrade' to 777.<br />
* You can also try to remove read access to config.php to others by setting this file's permissions to 750 - if it does not work 'upgrade' to 755.</div><br />
<br />
==Windows file permissions==<br />
<br />
If you are using a windows server your should ensure that the admin folder allows the owner of the webserver process to write files to this directory, however all other files can be set to read-only and execute.<br />
<br />
==Other security issues==<br />
<br />
The /application/config/config.php file contains a user name and password for your database server. This poses certain security issues, particularly if you are using a login that has high level administrative access to your database. In the event of some error returning the content of this php file to a user's browser, your database password and other details could be compromised. One way to minimize risk (a little) is set up a specific login that only has specific rights to your limesurvey database.<br />
<br />
Another way to secure this information is to put the certain information from the /application/config/config.php file in a non-web directory, i.e. for Apache users this is the directory above the htdocs (aka public_html or www) folder. So you will use config.php, but have one line in it - a line that includes the file with ACTUAL configuration information (ex: <?php return include("/home/hostfolder/safedata/configreal.php"); ?>). Remove all actual configuration information from /application/config/config.php, and paste it into the other file (configreal.php) that is included by /application/config/config.php. This other file should be located in a non-Web directory. Then /application/config/config.php will not contain database passwords, etc. - just the name of the file that DOES contain the database info. This avoids having to change all the other files that include /application/config/config.php, since they can still include it, and it will include the real config information. However you will need to edit configreal.php and change the follow parameters<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
'basePath' => dirname(dirname('''FILE''')),<br />
<br />
'runtimePath' => dirname(dirname(dirname('''FILE'''))).DIRECTORY_SEPARATOR.'tmp'.DIRECTORY_SEPARATOR.'runtime',<br />
<br />
[...]<br />
<br />
'urlManager' => array(<br />
<br />
[...]<br />
<br />
'rules' => require('routes.php'),<br />
<br />
[...]<br />
<br />
);<br />
<br />
</syntaxhighlight><br />
<br />
to use absolute directory paths to work properly. Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
'basePath' => '/var/www/htdocs/limesurvey',<br />
<br />
'runtimePath' => '/var/www/htdocs/limesurvey/tmp/runtime',<br />
<br />
[...]<br />
<br />
'urlManager' => array(<br />
<br />
[...]<br />
<br />
'rules' => require('/var/www/htdocs/limesurvey/config/routes.php'),<br />
<br />
[...]<br />
<br />
);<br />
<br />
</syntaxhighlight><br />
<br />
Also don't use "admin" as the default user. Go to your MySQL database (or other one if you installed LimeSurvey on different database) and change default user name "admin" to whatever you prefer (e.g. "admin_xyz"). It will be now much harder to guess administrator's new user name. Remember, this is one of the two variables intruders can use to gain access. The admin password is the other variable. So choose it with extreme care.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Expression_Manager&diff=4465Expression Manager2013-02-01T11:57:23Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
<div class="simplebox"> Note: This feature is only available in LimeSurvey 1.92 or later. </div><br />
<br />
=Quick Start Tutorial=<br />
<br />
==Overview==<br />
<br />
When customizing your surveys, you typically need a way to specify the following:<br />
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked<br />
#'''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).<br />
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern<br />
<br />
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).<br />
<br />
The following sections show the main places where Expression Manager is used<br />
<br />
==Relevance (Controlling Navigation/Branching)==<br />
<br />
Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses an Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).<br />
<br />
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, weight_kg 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).<br />
<br />
[[File:tutorial1.jpg]]<br />
<br />
Relevance is shown and editable in the following places:<br />
<br />
===Viewing / Editing Question-Level Relevance===<br />
<br />
This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.<br />
<br />
[[File:tutorial2.jpg]]<br />
<br />
This is the edit screen for the BMI question.<br />
<br />
[[File:tutorial3.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
===Viewing / Editing Group-Level Relevance===<br />
<br />
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).<br />
<br />
[[File:tutorial4.jpg]]<br />
<br />
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.<br />
<br />
Here is the screen for editing the group-level relevance for that question:<br />
<br />
[[File:tutorial5.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
==Tailoring/Piping==<br />
<br />
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.<br />
<br />
===Conditional Equations===<br />
<br />
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.<br />
<br />
[[File:tailoring7.jpg]]<br />
<br />
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.<br />
<br />
BMI computes the weight formula as {weight_kg / (height_m * height_m)}.<br />
<br />
Lastly, the report conditionally tailors the message for the subject, telling him what he entered (e.g. "You said you are 2 meters tall and weight 70 kg."<br />
<br />
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<br />
<br />
[[File:tailoring8.jpg]]<br />
<br />
From the edit window for this question, you can see two things:<br />
#Tailoring must surround expressions with Curly Braces<br />
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.<br />
<br />
[[File:tailoring9.jpg]]<br />
<br />
===Tailored Questions, Answers, and Reports===<br />
<br />
<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 <span> tag which is not valid inside select options.</div><br />
<br />
This example shows the BMI report.<br />
<br />
[[File:tailoring10.jpg]]<br />
<br />
Here is the edit window for the same question.<br />
<br />
[[File:tailoring11.jpg]]<br />
<br />
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.<br />
<br />
[[File:tailoring12.jpg]]<br />
<br />
You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.<br />
<br />
The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.<br />
<br />
=Introduction=<br />
<br />
LimeSurvey 1.92 and later 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).<br />
<br />
This wiki page is the definitive reference for Expression Manager syntax and functionality.<br />
<br />
==Key Definitions==<br />
#'''Expression''': Anything surrounded by curly braces<br />
**As long as there is no white space immediately after the opening brace or before the closing curly brace<br />
**The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.<br />
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text<br />
**You have access to all 'replacement fields', TOKENs, and INSERTANS values<br />
**You also have easier access to questions, answers, and their properties.<br />
#'''Relevance''' Equation: A new question attribute controlling question visiblity<br />
**If there is a relevance equation, then the question is only shown if the relevance evaluates to true.<br />
**Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance<br />
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database<br />
**It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"<br />
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+<br />
**Stands for Survey-Group-Question-Answer<br />
**SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.<br />
**These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed<br />
#'''Question Code''': This is the preferred variable name for EM<br />
**This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic<br />
**Although not required to be unique in <= 1.91+, it must be unique if you want to use EM<br />
**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".<br />
**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.<br />
<br />
==Do I have to use EM?==<br />
<br />
The short answer is No (but also yes).<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Can I mix use of Conditions and Relevance?==<br />
<br />
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.<br />
<br />
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.<br />
<br />
==How should I choose between Conditions and Relevance?==<br />
<br />
Here is a list of pros and cons of each style:<br />
<br />
{|<br />
|Style||Pros||Cons<br />
|-<br />
|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<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.<br />
<br />
==What are some other benefits of using EM?==<br />
<br />
Here are some of the other reasons you might want to use EM.<br />
#Calculations - you can create any calculation you can think of:<br />
**You have access to all common mathematical operators and functions<br />
**You have access to 70+ mathematical, date, and string processing functions<br />
**It is fairly easy for developers to add new functions if users need them<br />
#Storing Calculations to Database<br />
**You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.<br />
**You use the Equation question type to accomplish this.<br />
#Assessments<br />
**You can now create assessments or scale scores from any question type, not just the subset that used to be supported<br />
**You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page<br />
**You have more control over the reports generated based upon those assessment scores<br />
**You can store assessment scores in the database without needing JavaScript<br />
**You can hide assessment scores without needing JavaScript or CSS<br />
#Replacement Fields<br />
**Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.<br />
**This also avoids the common need to edit questions to change the SGQA code to make everything work.<br />
#Tailoring - you can conditionally display text based upon other values<br />
**Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")<br />
**Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 chldren")<br />
**Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.<br />
#New Variable Attributes - you can access the following to do your tailoring:<br />
** (no suffix) - an alias for qcode.code<br />
**.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<br />
**.NAOK - same as .code, but can be part of calculations or lists even if irrelevant<br />
**.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question<br />
**.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant<br />
**.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)<br />
**.qid - the question ID<br />
**.gid - the group ID<br />
**.sgqa - the SGQA value for the question<br />
**.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another<br />
**.qseq - the question sequence (starting from 0)<br />
**.gseq - the group sequence (starting from 0)<br />
**.mandatory - whether the question is mandatory (Y/N)<br />
**.question - the text of the question<br />
**.relevance - the relevance equation for the question<br />
**.grelevance - the relevance equation for the group<br />
**.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)<br />
**.type - the question type (the one character code)<br />
#Dynamic On-Page Changes<br />
**All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page<br />
**So, you have questions dynamically appear/disappear based upon whether they are relevant<br />
**Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.<br />
#New Data Entry Screen<br />
**In addition to using the current data-entry system, you can just use Survey-All-In-One.<br />
**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<br />
**This can be critical if your data entry person needs to see the tailoring, which is also dynamic.<br />
#Eliminates the need for most custom JavaScript<br />
**EM easily supports complicated computations, scoring, tailoring and conditional logic.<br />
**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.<br />
<br />
==What are some other helpful new features enabled by EM?==<br />
<br />
Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:<br />
#You can create more complex validation criteria<br />
**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.<br />
**EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.<br />
#Easy Re-ordering (or deleting) of Questions and Groups<br />
**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.<br />
**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.<br />
**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).<br />
#The Question/Group Navigation Index is always available and accurate<br />
**Prior to version 1.92, these indexes were not available if there were complex conditions<br />
**With EM, we can guarantee that they are accurate.<br />
**Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)<br />
***When jumping forwards, EM will re-validate all of the intervening questions/groups.<br />
***If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent<br />
***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.<br />
#Auto-conversion of Conditions to Relevance<br />
**When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them<br />
**Whenever you import a survey, relevance equations will be created as needed<br />
**Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.<br />
#Convenient Syntax Highlighting<br />
**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.<br />
**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.<br />
**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).<br />
***The list of answer choices uses this syntax: 'answers':{key:val, ... }.<br />
***''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.<br />
***''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)<br />
***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).<br />
#Easy review of entire survey logic and content<br />
**There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.<br />
**It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)<br />
**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.<br />
**Eveything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)<br />
**The syntax-highligting supports rapid navigation and editing of the survey.<br />
***If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.<br />
***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.<br />
***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)<br />
**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<br />
<br />
==How Backwards Compatible is EM with 1.91+?==<br />
<br />
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+.<br />
<br />
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.<br />
<br />
=Getting Started=<br />
<br />
The best way to get started with EM is to:<br />
*Install 1.92+ from http://www.limesurvey.org/en/download .<br />
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].<br />
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].<br />
*Explore the EM documentation (this page)<br />
*Examine the built-in EM test suite<br />
**From any survey, under tools, select the EM option<br />
**Availalbe Functions lists the 70+ functions and syntax<br />
**Unit Tests of Isolsted Expressions<br />
***shows examples of using all EM functions and operators, and the PHP and JavaScript results<br />
***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.<br />
<br />
=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=<br />
<br />
==Conditions => Relevance==<br />
<br />
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.<br />
<br />
==Assessments => Equations and Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Replacements => Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
==Equations==<br />
<br />
Equations were not supported without fancy JavaScript.<br />
<br />
==Equation Question Type==<br />
<br />
Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.<br />
<br />
=How Will Expression Manager Replace/Extend That Functionality?=<br />
<br />
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.<br />
<br />
==New Terminology When Referring to Expression Manager (EM)==<br />
<br />
EM "thinks" of its functionality in the following terms:<br />
*'''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).<br />
*'''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.<br />
*'''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.<br />
<br />
===Relevance and Cascading Relevance===<br />
<br />
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 diplayed. 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.<br />
<br />
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.<br />
<br />
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:<br />
<br />
{|<br />
|Question Code||Relevance||Question<br />
|-<br />
|Q1||1||What is your name?<br />
|-<br />
|Q2||Q1||{Q1}, how old are you?<br />
|-<br />
|Q3||Q2||So, you are {Q2} years old. Are you married?<br />
|-<br />
|Q4||Q3 == "Y"||{Q1}, how long have you been married?<br />
|-<br />
|Q5||Q4||How many children do you have, {Q1}?<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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 and 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.<br />
<br />
===Group-Level Relevance===<br />
<br />
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 deterimine 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.<br />
<br />
===Tailoring / Piping===<br />
<br />
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).<br />
<br />
Using these equations, you can do things such as:<br />
#Conditionally show tailored messages to the respondants based upon prior responses<br />
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself<br />
#Conjugate verbs and decline nouns within questions, answers, and reports.<br />
#Show summaries of responses before the "Show your answers" page at the end of the survey<br />
<br />
===Equations===<br />
<br />
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.<br />
<br />
This solves a common request for storing Assessment scores within the database<br />
<br />
==Syntax==<br />
<br />
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).<br />
<br />
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:<br />
<br />
<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),<br />
<br />
'',<br />
<br />
if(PFTotals >= -5 && PFTotals <= -4,<br />
<br />
'Very Soft',<br />
<br />
if(PFTotals >= -3 && PFTotals <= -2,<br />
<br />
'Soft',<br />
<br />
if(PFTotals == -1,<br />
<br />
'Somewhat Soft',<br />
<br />
if(PFTotals == 0,<br />
<br />
'Moderate',<br />
<br />
if(PFTotals == 1,<br />
<br />
'Somewhat Hard',<br />
<br />
if(PFTotals >= 2 && PFTotals <= 3,<br />
<br />
'Hard',<br />
<br />
if(PFTotals >= 4 && PFTotals <= 5,<br />
<br />
'Very Hard',<br />
<br />
''<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)}<br />
<br />
</syntaxhighlight><br />
<br />
Expression Manager supports the following syntax:<br />
*All standard mathematical operators (e.g. +,-,*,/,!)<br />
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)<br />
*Parentheses (so you can group sub-expressions)<br />
*Conditional operators (e.g. &&,| | and these equivalents: and,or)<br />
*Single and double-quoted strings (which can each embed strings with the other quote type)<br />
*Comma operator (so can have a list of expressions and just return the final result)<br />
*Assignment operator (=)<br />
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes<br />
*Pre-defined functions (there are already 70+, and it is easy to add more)<br />
<br />
EM syntax follows normal operator precedence:<br />
<br />
{|<br />
|Level||Operator(s)||Description<br />
|-<br />
|1||()||parentheses for grouping or calling functions<br />
|-<br />
|2||! - +||unary operators: not, negation, unary-plus<br />
|-<br />
|3||* /||times, divide<br />
|-<br />
|4||+ -||plus, minus<br />
|-<br />
|5||< <= > >= lt le gt ge||relative comparisons<br />
|-<br />
|6||== != eq ne||equality comparisons<br />
|-<br />
|7||and||logical AND<br />
|-<br />
|8||or||logical OR<br />
|-<br />
|9||=||assignment operator<br />
|-<br />
|10||,||comma operator<br />
|-<br />
|<br />
|}<br />
<br />
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).<br />
<br />
===Caution about using Assignment Operator (=)===<br />
<br />
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 sould 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.<br />
<br />
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 "==")<br />
<br />
The main reasons you may want to use assignment are:<br />
*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.<br />
*You need to forcibly change the response to a previous question based upon a later response<br />
<br />
==Access to Variables==<br />
<br />
Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:<br />
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5)<br />
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")<br />
*All {XXX} values used by templates<br />
<br />
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.<br />
<br />
Furthermore, Expression Manager lets you access many properties of the Question:<br />
<br />
{|<br />
|Syntax||Meaning||Example||Example Result<br />
|-<br />
|Qcode||an alias for Qcode.code||{implode(',',name,gender)}||'Tom','M'<br />
|-<br />
|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'<br />
|-<br />
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'<br />
|-<br />
|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'<br />
|-<br />
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'<br />
|-<br />
|Qcode.shown||the dispay value for the question||{implode(',',name.shown,gender.shown)}||'Tom','Male'<br />
|-<br />
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'<br />
|-<br />
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'<br />
|-<br />
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337<br />
|-<br />
|Qcode.type||the question type||{gender.type}||'G'<br />
|-<br />
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'<br />
|-<br />
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3<br />
|-<br />
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5<br />
|-<br />
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1<br />
|-<br />
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus)||1<br />
|-<br />
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'<br />
|-<br />
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'<br />
|-<br />
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'<br />
|-<br />
|<br />
|}<br />
<br />
=== Security issue===<br />
<br />
For security issue, text entered by user are filtered. Some caracter are replaced by HTML entities.<br />
* & by &amp;<br />
* < by &lt;<br />
* > by &gt;<br />
<br />
==Qcode Variable Naming==<br />
<br />
Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:<br />
<br />
QuestionCode . '_' . AnswerID . '_' . ScaleId<br />
<br />
{|<br />
|Type||Description||Code||SubQs||Answer Options||Scales||Answer Code||Answer Shown||Relevance<br />
|-<br />
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}<br />
|-<br />
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}<br />
|-<br />
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}<br />
|-<br />
|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'}<br />
|-<br />
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}<br />
|-<br />
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}<br />
|-<br />
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}<br />
|-<br />
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}<br />
|-<br />
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}<br />
|-<br />
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}<br />
|-<br />
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||<br />
|-<br />
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||<br />
|-<br />
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}<br />
|-<br />
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}<br />
|-<br />
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}<br />
|-<br />
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}<br />
|-<br />
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}<br />
|-<br />
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}<br />
|-<br />
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}<br />
|-<br />
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20_comment}||{Q20.shown}||{Q20=='B'}<br />
|-<br />
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}<br />
|-<br />
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}<br />
|-<br />
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_D_comment}||{Q23_D.shown}||{!is_empty(Q23)}<br />
|-<br />
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}<br />
|-<br />
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q')}<br />
|-<br />
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}<br />
|-<br />
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}<br />
|-<br />
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}<br />
|-<br />
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}<br />
|-<br />
|<br />
|}<br />
<br />
==The reserved 'this', 'self', and 'that' variables==<br />
<br />
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.<br />
<br />
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).<br />
<br />
The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:<br />
*self<br />
*self.''suffix''<br />
*self.''sub-selector''<br />
*self.''sub-selector''.''suffix''<br />
<br />
''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)<br />
<br />
''sub-selector'' is one of:<br />
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)<br />
*nocomments - only subquestions that are not comments<br />
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected.<br />
<br />
Examples:<br />
*Has any part of a question been answered? {count(self.NAOK)>0}<br />
*What is the assessment score for this question? {sum(self.value)}<br />
<br />
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.<br />
*What is the grand total? {sum(self.NAOK)}<br />
*What is the total of row B? {sum(self.sq_B.NAOK)}<br />
*What is the total of column 3? {sum(self.sq_3.NAOK)}<br />
<br />
The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:<br />
*that.''qname''<br />
*that.''qname''.''suffix''<br />
*that.''qname''.''sub-selector''<br />
*that.''qname''.''sub-selector''.''suffix''<br />
<br />
''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''<br />
<br />
Examples:<br />
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}<br />
*What is the assessment score for q2? (sum(that.q2.NAOK)}<br />
*What is the grand total of q3? {sum(that.q3.NAOK)}<br />
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}<br />
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}<br />
<br />
The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.<br />
<br />
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'<br />
<br />
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.<br />
<br />
==Access to Functions==<br />
<br />
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.<br />
<br />
===Implemented Functions===<br />
<br />
The following functions are currently available:<br />
<br />
{|<br />
|Function||Meaning||Syntax<br />
|-<br />
[http://www.php.net/manual/en/function.abs.php ||abs]||Absolute value||number abs(number)<br />
|-<br />
[http://www.php.net/manual/en/function.acos.php ||acos]||Arc cosine||number acos(number)<br />
|-<br />
[http://www.php.net/manual/en/function.addslashes.php ||addslashes]||Quote string with slashes||string addslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.asin.php ||asin]||Arc sine||number asin(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan.php ||atan]||Arc tangent||number atan(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan2.php ||atan2]||Arc tangent of two variables||number atan2(number, number)<br />
|-<br />
[http://www.php.net/manual/en/function.ceil.php ||ceil]||Round fractions up||number ceil(number)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.cos.php ||cos]||Cosine||number cos(number)<br />
|-<br />
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)<br />
|-<br />
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)<br />
|-<br />
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.date.php ||date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[http://www.php.net/manual/en/function.exp.php ||exp]||Calculates the exponent of e||number exp(number)<br />
|-<br />
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)<br />
|-<br />
[http://www.php.net/manual/en/function.floor.php ||floor]||Round fractions down||number floor(number)<br />
|-<br />
[http://www.php.net/manual/en/function.gmdate.php ||gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.idate.php ||idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)<br />
|-<br />
[http://www.php.net/manual/en/function.implode.php ||implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)<br />
|-<br />
[http://www.php.net/manual/en/function.intval.php ||intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])<br />
|-<br />
[http://www.php.net/manual/en/function.empty.php ||is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.is-nan.php ||is_nan]||Finds whether a value is not a number||bool is_nan(var)<br />
|-<br />
[http://www.php.net/manual/en/function.is-null.php ||is_null]||Finds whether a variable is NULL||bool is_null(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
|join {MOUSEOVER(label="v")}In last 2.0 version{MOUSEOVER}||Join elements as a new string||join(arg1, arg2, ... argN)<br />
|-<br />
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.log.php ||log]||Natural logarithm||number log(number)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.max.php ||max]||Find highest value||number max(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.min.php ||min]||Find lowest value||number min(arg1, arg2, ... argN)<br />
|-<br />
[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 ]]]]]])<br />
|-<br />
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)<br />
|-<br />
[http://www.php.net/manual/en/function.nl2br.php ||nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)<br />
|-<br />
[http://www.php.net/manual/en/function.number-format.php ||number_format]||Format a number with grouped thousands||string number_format(number)<br />
|-<br />
|pi||Get value of pi||number pi()<br />
|-<br />
[http://www.php.net/manual/en/function.pow.php ||pow]||Exponential expression||number pow(base, exp)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.quotemeta.php ||quotemeta]||Quote meta characters||string quotemeta(string)<br />
|-<br />
[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)<br />
|-<br />
|regexMatch||compare a string to a [[Using regular expressions||regular expression]]||bool regexMatch(pattern,input)<br />
|-<br />
[http://www.php.net/manual/en/function.round.php ||round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.sin.php ||sin]||Sine||number sin(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.sprintf.php ||sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.sqrt.php ||sqrt]||Square root||number sqrt(arg)<br />
|-<br />
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.str-repeat.php ||str_repeat]||Repeat a string||string str_repeat(input, multiplier)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.strcasecmp.php ||strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)<br />
|-<br />
[http://www.php.net/manual/en/function.strcmp.php ||strcmp]||Binary safe string comparison||int strcmp(str1, str2)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.stripos.php ||stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.stripslashes.php ||stripslashes]||Un-quotes a quoted string||string stripslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.stristr.php ||stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])<br />
|-<br />
[http://www.php.net/manual/en/function.strlen.php ||strlen]||Get string length||int strlen(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strpos.php ||strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.strrev.php ||strrev]||Reverse a string||string strrev(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strstr.php ||strstr]||Find first occurrence of a string||string strstr(haystack, needle)<br />
|-<br />
[http://www.php.net/manual/en/function.strtolower.php ||strtolower]||Make a string lowercase||string strtolower(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strtoupper.php ||strtoupper]||Make a string uppercase||string strtoupper(string)<br />
|-<br />
[http://www.php.net/manual/en/function.substr.php ||substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])<br />
|-<br />
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)<br />
|-<br />
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.tan.php ||tan]||Tangent||number tan(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.time.php ||time]||Return current UNIX timestamp||number time()<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.ucwords.php ||ucwords]||Uppercase the first character of each word in a string||string ucwords(string)<br />
|-<br />
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)<br />
|-<br />
|<br />
|}<br />
<br />
===Functions that are Planned or Being Considered===<br />
<br />
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.<br />
<br />
{|<br />
|Syntax||Meaning||Comments<br />
|-<br />
|e()||returns the value of e||<br />
|-<br />
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||<br />
|-<br />
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||<br />
|-<br />
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown<br />
|-<br />
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||<br />
|-<br />
|getRelevance(X)||returns the relevance equation for question X||<br />
|-<br />
|getStartTime()||returns the date corresponding to the system time when the interview was started||<br />
|-<br />
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||<br />
|-<br />
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||<br />
|-<br />
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||<br />
|-<br />
|isInvalid(X)||returns true if the answer is of type *INVALID*||<br />
|-<br />
|isNA(X)||returns true if the answer is of type *NA*||<br />
|-<br />
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||<br />
|-<br />
|isRefused(X)||returns true if the answer is of type *REFUSED*||<br />
|-<br />
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||<br />
|-<br />
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||<br />
|-<br />
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||<br />
|-<br />
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||<br />
|-<br />
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||<br />
|-<br />
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||<br />
|-<br />
|mean(X,...)||returns the mean of a list of values||<br />
|-<br />
|numAnsOptions(X)||returns the number of answer options that question X has||<br />
|-<br />
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||<br />
|-<br />
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||<br />
|-<br />
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||<br />
|-<br />
|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.||<br />
|-<br />
|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.||<br />
|-<br />
|<br />
|}<br />
<br />
==Expression Manager Knows Which Variables are Local==<br />
<br />
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).<br />
<br />
==Cascading Conditions==<br />
<br />
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<br />
<br />
{|<br />
|Operator||Example||a||b||Result<br />
|-<br />
|+ (unary)||+a||N/A|| ||false<br />
|-<br />
|- (unary)||-a||N/A|| ||false<br />
|-<br />
|!||!a||N/A|| ||false<br />
|-<br />
|== (or eq)||a == b||N/A||5||false<br />
|-<br />
|== (or eq)||a == b||N/A||0||false<br />
|-<br />
|== (or eq)||a == b||N/A||N/A||false<br />
|-<br />
|!= (or ne)||a != b||N/A||5|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||N/A|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||0||false<br />
|-<br />
|> (or gt)||a > b||N/A||5|| false<br />
|-<br />
|>= (or ge)||a >= b||N/A||5||false<br />
|-<br />
|< (or lt)||a < b||N/A||5||false<br />
|-<br />
|<= (or le)||a <= b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||5||false<br />
|-<br />
|+||a + b||N/A||5||false<br />
|-<br />
|-||a - b||N/A||5||false<br />
|-<br />
|*||a * b||N/A||5||false<br />
|-<br />
|/||a / b||5||N/A||false<br />
|-<br />
|()||(a)||N/A|| ||false<br />
|-<br />
|(exp)||(a && b)||N/A||5||false<br />
|-<br />
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false<br />
|-<br />
|function||sum(a,b,b)||N/A||5||false<br />
|-<br />
|function||max(a,b)||N/A||5||false<br />
|-<br />
|function||min(a,b)||N/A||5||false<br />
|-<br />
|function||implode(', ',a,b,a,b)||N/A||5||false<br />
|-<br />
|function||if(a,a,b)||N/A||5||false<br />
|-<br />
|function||is_empty(a)||N/A|| ||false<br />
|-<br />
|function||is_empty(a)||0 (or blank)|| ||true<br />
|-<br />
|function||!is_empty(a)||N/A|| ||false<br />
|-<br />
|<br />
|}<br />
<br />
===Overriding Cascading Conditions===<br />
<br />
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.<br />
<br />
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<br />
#q1 is not added to the LEManyNA() clause<br />
#LEMval('q1') will continue to check whether the response is relevant, and will return '' if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression.<br />
<br />
So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).<br />
<br />
The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converage 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.<br />
<br />
==How does Expression Manager Support Conditional Micro-Tailoring?==<br />
<br />
Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):<br />
<br />
{|<br />
|Question Code||Relevance||Question Type||Question<br />
|-<br />
|name||1||text||What is your name?<br />
|-<br />
|age||1||text||How old are you?<br />
|-<br />
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}<br />
|-<br />
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.<br />
|-<br />
|kids||!badage||yesno||Do you have children?<br />
|-<br />
|parents||1||expr||{!badage && kids=='Y'}<br />
|-<br />
|numKids||parents||text||How many children do you have?<br />
|-<br />
|kid1||parents && numKids >= 1||text||How old is your first child?<br />
|-<br />
|kid2||parents && numKids >= 2||text||How old is your second child?<br />
|-<br />
|kid3||parents && numKids >= 3||text||How old is your third child?<br />
|-<br />
|kid4||parents && numKids >= 4||text||How old is your fourth child?<br />
|-<br />
|kid5||parents && numKids >= 5||text||How old is your fifth child?<br />
|-<br />
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}<br />
|-<br />
|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}<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==<br />
<br />
{|<br />
|Old Feature||New Feature||Comments<br />
|-<br />
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables<br />
|-<br />
|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<br />
|-<br />
|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\})<br />
|-<br />
|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<br />
|-<br />
|<br />
|}<br />
<br />
=Syntax Highlighting=<br />
<br />
To help with entering and validating expressions, EM provides syntax highlighting with the following features:<br />
<br />
==Types and Meanings of Syntax Highlighting==<br />
<br />
{|<br />
|Color||Sample||Meaning||Tooltip||Comments<br />
|-<br />
|tan background||<span style='color:#eee8aa,#eee8aa'>Sample</span>||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<br />
|-<br />
|blue bold text||'''<span style='color:blue,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|grey text||<span style='color:grey,#eee8aa'>'Sample'</span>||string||none||single and double-quoted strings are shown in grey text<br />
|-<br />
|bold maroon text||'''<span style='color:maroon,#eee8aa'>Sample</span>'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. 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.<br />
|-<br />
|bold cyan text||'''<span style='color:#4C88BE,#eee8aa'>Sample</span>'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan 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.<br />
|-<br />
|bold green text||'''<span style='color:green,#eee8aa'>Sample</span>'''||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 pageis 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.<br />
|-<br />
|bold pink text||'''<span style='color:#FF00FF,#eee8aa'>Sample</span>'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior pageis 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.<br />
|-<br />
|bold tan text||'''<span style='color:#996600,#eee8aa'>Sample</span>'''||a lime relacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE} are shown in bold tan text. The tooltip shows the current value.<br />
|-<br />
|red text||'''<span style='color:red,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|normal black text||<span style='color:black,#eee8aa'>Sample</span>||punctuation||none||All other punctionation within the expression is shown as normal black text.<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
=Relationship to LimeSurvey Ideas / Feature Requests=<br />
<br />
Expression Manager provides complete or partial solutions to each of the following:<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1 Conditions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/3/ Answercounts]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/5 Advanced reporting for assessments]<br />
**partial: Equations let one store the Assessment value in the database, and micro-tailoring can generate simple formatted reports. Authors can access those Equation values if they have more complex reporting needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/6 Assessment reports]<br />
**partial: Since Equations store the Assessment score, it should be possible to use Statistics to show distributions of those scores, and Quotas to limit the number of responses with those scores.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/7 Store assessment results for further evaluation]<br />
**Equations let one store the Assessment value in the database, completely solving this problem<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/22/ More advanced condition rules]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/28 Open Answertable up so that we can alter formatting]<br />
**partial: All of the question attributes are available, so authors can create custom AnswerTable equivalents as a Question. Once implatemented, they can also use the showTheseResponses() or showAllResponsesExecpt() functions<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/37 Export survey results with full questions to include images]<br />
**since Tailoring has access to the full question text, it can include images in the export<br />
**if subjects choose Print Your Answers after finishing the survey, those printouts will be fully tailored<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/63 List of question codes and SGQA identifiers]<br />
**The Show Survey Logic view shows that mapping (plus much more information)<br />
**In addition, you no longer have to use SGQA codes to refer to variables - you can use the Question code/title.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/69 Branch/jump to another question (earlier or later) based on current question]<br />
**You can use the Navigation Index for this in most cases<br />
**Once implemented, you can use the JumpTo() function. Like the Navigation Index, if you try to jump forward, it will stop on an intervening page if there are any of the relevant mandatory questions are unanswered, or if any relevant questions fail validation tests.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/86 set quota for total responses]<br />
**If the final question is an Equation that flags a survey as completed (so is NULL if a respondant does not get to that page), you can use Quotas on that question to control the number of completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/101 Review all conditions]<br />
**The [[Show Logic File|Show Logic File]] view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/105 Review all questions + Review all groups]<br />
**The [[Show Logic File|Show Logic File]] view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/107 How to visualize questions, logic & conditions]<br />
**The [[Show Logic File|Show Logic File]] view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/113 Offline Surveys]<br />
**Running a survey with all of the questions on the same page would let you do off-line data collection (e.g. email the html page and associated JavaScript). However, you would still want a way to submit the results so that they did not get lost. It may be possible to use Save As HTML to save partially completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/120 Remove INSERTANS from question text at survey results]<br />
**INSERTANS is no longer needed. You can refer to a variable by its SGQA code (without prefixing it with INSERTANS:), or by its question code.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/137 Informed Consent and Authorization Functionality]<br />
**You can show show the informed consent on the welcome page, then ask any additional questions needed (to ensure they meet the study inclusion/exclusion criteria), and ask them a Yes/No question whether they give their consent. Then, make all of the remaining questions conditional on that yesNo. For example, if the question is named ''consent'', you would set the relevance to the remaining questions to ''consent == "Y"'' (possibly ''and''ing that with whatever additional conditions you needed to support your branching needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/199 Show codes instead of of answers using INSERTANS]<br />
**{Qcode} returns the code instead of the response text (which you can get via {INSERTANS:SGQA}, or {Qcode.shown}<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/204 Need group mean or calculations for assessments]<br />
**Say you have N variables of which N-X were answered, you could compute the mean of the answered variables as {sum(var1, var2, ..., varN) / count(var1, var2, ..., varN)}<br />
**Computing the mean across a set of respondants would require extension of the Quota functionality.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/222 To insert a language dependent text]<br />
**Tailoring lets you conjugate verbs and decline nouns in each language<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/225 Surveyors should approve their answers]<br />
**Custom Questions with tailoring, or the showAllResponsesExcept() function will let Surveyors see all of the questions and responses before clicking Submit. If the Navigation Menu option is enabled, it is easy to go back and correct answers.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Suppliment to #answernnXnnXnnn method of targetting form elements]<br />
**You can now refer to questions and answers by their Question Code, so there is no longer a need to modify SGQA values.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/262 More flexibility with hidden questions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/265 Remove specific conditions from multiple questions]<br />
**You can now use Relevance, which is easier to manage than Conditions. If needed, they can all be exported from the database, edited in a spreadsheet, and re-imported.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/268 Cross Survey Reporting]<br />
**By using question codes that are unique across your surveys and versions, you can consolidate data from multiple surveys and/or compare them<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/275 Simplifying integration with other tools]<br />
**Expression Manager uses Question Codes instead of SGQA, making it easier to integrate with other tools.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Expose assessment score to 3rd party app processing]<br />
**This can be done with Equation question type<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/309 Multiple thank you pages]<br />
**This can be supported via conditional relevance branching and tailoring<br />
<br />
=Additional Reading=<br />
<br />
==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==<br />
<br />
==[[Expression Manager HowTos|Use Cases and HowTos]]==<br />
<br />
==[[Expression Manager Examples|Step-by-Step Examples]].==<br />
<br />
==[[Expression Manager for developers|Reference for Developers]]==<br />
<br />
==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Expression_Manager&diff=4466Expression Manager2013-02-01T11:56:14Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
<div class="simplebox"> Note: This feature is only available in LimeSurvey 1.92 or later. </div><br />
<br />
=Quick Start Tutorial=<br />
<br />
==Overview==<br />
<br />
When customizing your surveys, you typically need a way to specify the following:<br />
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked<br />
#'''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).<br />
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern<br />
<br />
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).<br />
<br />
The following sections show the main places where Expression Manager is used<br />
<br />
==Relevance (Controlling Navigation/Branching)==<br />
<br />
Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses an Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).<br />
<br />
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, weight_kg 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).<br />
<br />
[[File:tutorial1.jpg]]<br />
<br />
Relevance is shown and editable in the following places:<br />
<br />
===Viewing / Editing Question-Level Relevance===<br />
<br />
This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.<br />
<br />
[[File:tutorial2.jpg]]<br />
<br />
This is the edit screen for the BMI question.<br />
<br />
[[File:tutorial3.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
===Viewing / Editing Group-Level Relevance===<br />
<br />
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).<br />
<br />
[[File:tutorial4.jpg]]<br />
<br />
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.<br />
<br />
Here is the screen for editing the group-level relevance for that question:<br />
<br />
[[File:tutorial5.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
==Tailoring/Piping==<br />
<br />
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.<br />
<br />
===Conditional Equations===<br />
<br />
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.<br />
<br />
[[File:tailoring7.jpg]]<br />
<br />
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.<br />
<br />
BMI computes the weight formula as {weight_kg / (height_m * height_m)}.<br />
<br />
Lastly, the report conditionally tailors the message for the subject, telling him what he entered (e.g. "You said you are 2 meters tall and weight 70 kg."<br />
<br />
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<br />
<br />
[[File:tailoring8.jpg]]<br />
<br />
From the edit window for this question, you can see two things:<br />
#Tailoring must surround expressions with Curly Braces<br />
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.<br />
<br />
[[File:tailoring9.jpg]]<br />
<br />
===Tailored Questions, Answers, and Reports===<br />
<br />
<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 <span> tag which is not valid inside select options.</div><br />
<br />
This example shows the BMI report.<br />
<br />
[[File:tailoring10.jpg]]<br />
<br />
Here is the edit window for the same question.<br />
<br />
[[File:tailoring11.jpg]]<br />
<br />
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.<br />
<br />
[[File:tailoring12.jpg]]<br />
<br />
You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.<br />
<br />
The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.<br />
<br />
=Introduction=<br />
<br />
LimeSurvey 1.92 and later 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).<br />
<br />
This wiki page is the definitive reference for Expression Manager syntax and functionality.<br />
<br />
==Key Definitions==<br />
#'''Expression''': Anything surrounded by curly braces<br />
**As long as there is no white space immediately after the opening brace or before the closing curly brace<br />
**The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.<br />
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text<br />
**You have access to all 'replacement fields', TOKENs, and INSERTANS values<br />
**You also have easier access to questions, answers, and their properties.<br />
#'''Relevance''' Equation: A new question attribute controlling question visiblity<br />
**If there is a relevance equation, then the question is only shown if the relevance evaluates to true.<br />
**Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance<br />
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database<br />
**It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"<br />
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+<br />
**Stands for Survey-Group-Question-Answer<br />
**SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.<br />
**These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed<br />
#'''Question Code''': This is the preferred variable name for EM<br />
**This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic<br />
**Although not required to be unique in <= 1.91+, it must be unique if you want to use EM<br />
**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".<br />
**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.<br />
<br />
==Do I have to use EM?==<br />
<br />
The short answer is No (but also yes).<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Can I mix use of Conditions and Relevance?==<br />
<br />
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.<br />
<br />
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.<br />
<br />
==How should I choose between Conditions and Relevance?==<br />
<br />
Here is a list of pros and cons of each style:<br />
<br />
{|<br />
|Style||Pros||Cons<br />
|-<br />
|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<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.<br />
<br />
==What are some other benefits of using EM?==<br />
<br />
Here are some of the other reasons you might want to use EM.<br />
#Calculations - you can create any calculation you can think of:<br />
**You have access to all common mathematical operators and functions<br />
**You have access to 70+ mathematical, date, and string processing functions<br />
**It is fairly easy for developers to add new functions if users need them<br />
#Storing Calculations to Database<br />
**You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.<br />
**You use the Equation question type to accomplish this.<br />
#Assessments<br />
**You can now create assessments or scale scores from any question type, not just the subset that used to be supported<br />
**You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page<br />
**You have more control over the reports generated based upon those assessment scores<br />
**You can store assessment scores in the database without needing JavaScript<br />
**You can hide assessment scores without needing JavaScript or CSS<br />
#Replacement Fields<br />
**Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.<br />
**This also avoids the common need to edit questions to change the SGQA code to make everything work.<br />
#Tailoring - you can conditionally display text based upon other values<br />
**Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")<br />
**Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 chldren")<br />
**Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.<br />
#New Variable Attributes - you can access the following to do your tailoring:<br />
** (no suffix) - an alias for qcode.code<br />
**.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<br />
**.NAOK - same as .code, but can be part of calculations or lists even if irrelevant<br />
**.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question<br />
**.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant<br />
**.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)<br />
**.qid - the question ID<br />
**.gid - the group ID<br />
**.sgqa - the SGQA value for the question<br />
**.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another<br />
**.qseq - the question sequence (starting from 0)<br />
**.gseq - the group sequence (starting from 0)<br />
**.mandatory - whether the question is mandatory (Y/N)<br />
**.question - the text of the question<br />
**.relevance - the relevance equation for the question<br />
**.grelevance - the relevance equation for the group<br />
**.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)<br />
**.type - the question type (the one character code)<br />
#Dynamic On-Page Changes<br />
**All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page<br />
**So, you have questions dynamically appear/disappear based upon whether they are relevant<br />
**Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.<br />
#New Data Entry Screen<br />
**In addition to using the current data-entry system, you can just use Survey-All-In-One.<br />
**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<br />
**This can be critical if your data entry person needs to see the tailoring, which is also dynamic.<br />
#Eliminates the need for most custom JavaScript<br />
**EM easily supports complicated computations, scoring, tailoring and conditional logic.<br />
**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.<br />
<br />
==What are some other helpful new features enabled by EM?==<br />
<br />
Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:<br />
#You can create more complex validation criteria<br />
**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.<br />
**EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.<br />
#Easy Re-ordering (or deleting) of Questions and Groups<br />
**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.<br />
**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.<br />
**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).<br />
#The Question/Group Navigation Index is always available and accurate<br />
**Prior to version 1.92, these indexes were not available if there were complex conditions<br />
**With EM, we can guarantee that they are accurate.<br />
**Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)<br />
***When jumping forwards, EM will re-validate all of the intervening questions/groups.<br />
***If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent<br />
***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.<br />
#Auto-conversion of Conditions to Relevance<br />
**When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them<br />
**Whenever you import a survey, relevance equations will be created as needed<br />
**Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.<br />
#Convenient Syntax Highlighting<br />
**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.<br />
**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.<br />
**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).<br />
***The list of answer choices uses this syntax: 'answers':{key:val, ... }.<br />
***''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.<br />
***''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)<br />
***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).<br />
#Easy review of entire survey logic and content<br />
**There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.<br />
**It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)<br />
**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.<br />
**Eveything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)<br />
**The syntax-highligting supports rapid navigation and editing of the survey.<br />
***If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.<br />
***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.<br />
***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)<br />
**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<br />
<br />
==How Backwards Compatible is EM with 1.91+?==<br />
<br />
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+.<br />
<br />
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.<br />
<br />
=Getting Started=<br />
<br />
The best way to get started with EM is to:<br />
*Install 1.92+ from http://www.limesurvey.org/en/download .<br />
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].<br />
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].<br />
*Explore the EM documentation (this page)<br />
*Examine the built-in EM test suite<br />
**From any survey, under tools, select the EM option<br />
**Availalbe Functions lists the 70+ functions and syntax<br />
**Unit Tests of Isolsted Expressions<br />
***shows examples of using all EM functions and operators, and the PHP and JavaScript results<br />
***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.<br />
<br />
=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=<br />
<br />
==Conditions => Relevance==<br />
<br />
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.<br />
<br />
==Assessments => Equations and Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Replacements => Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
==Equations==<br />
<br />
Equations were not supported without fancy JavaScript.<br />
<br />
==Equation Question Type==<br />
<br />
Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.<br />
<br />
=How Will Expression Manager Replace/Extend That Functionality?=<br />
<br />
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.<br />
<br />
==New Terminology When Referring to Expression Manager (EM)==<br />
<br />
EM "thinks" of its functionality in the following terms:<br />
*'''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).<br />
*'''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.<br />
*'''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.<br />
<br />
===Relevance and Cascading Relevance===<br />
<br />
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 diplayed. 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.<br />
<br />
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.<br />
<br />
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:<br />
<br />
{|<br />
|Question Code||Relevance||Question<br />
|-<br />
|Q1||1||What is your name?<br />
|-<br />
|Q2||Q1||{Q1}, how old are you?<br />
|-<br />
|Q3||Q2||So, you are {Q2} years old. Are you married?<br />
|-<br />
|Q4||Q3 == "Y"||{Q1}, how long have you been married?<br />
|-<br />
|Q5||Q4||How many children do you have, {Q1}?<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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 and 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.<br />
<br />
===Group-Level Relevance===<br />
<br />
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 deterimine 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.<br />
<br />
===Tailoring / Piping===<br />
<br />
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).<br />
<br />
Using these equations, you can do things such as:<br />
#Conditionally show tailored messages to the respondants based upon prior responses<br />
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself<br />
#Conjugate verbs and decline nouns within questions, answers, and reports.<br />
#Show summaries of responses before the "Show your answers" page at the end of the survey<br />
<br />
===Equations===<br />
<br />
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.<br />
<br />
This solves a common request for storing Assessment scores within the database<br />
<br />
==Syntax==<br />
<br />
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).<br />
<br />
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:<br />
<br />
<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),<br />
<br />
'',<br />
<br />
if(PFTotals >= -5 && PFTotals <= -4,<br />
<br />
'Very Soft',<br />
<br />
if(PFTotals >= -3 && PFTotals <= -2,<br />
<br />
'Soft',<br />
<br />
if(PFTotals == -1,<br />
<br />
'Somewhat Soft',<br />
<br />
if(PFTotals == 0,<br />
<br />
'Moderate',<br />
<br />
if(PFTotals == 1,<br />
<br />
'Somewhat Hard',<br />
<br />
if(PFTotals >= 2 && PFTotals <= 3,<br />
<br />
'Hard',<br />
<br />
if(PFTotals >= 4 && PFTotals <= 5,<br />
<br />
'Very Hard',<br />
<br />
''<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)}<br />
<br />
</syntaxhighlight><br />
<br />
Expression Manager supports the following syntax:<br />
*All standard mathematical operators (e.g. +,-,*,/,!)<br />
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)<br />
*Parentheses (so you can group sub-expressions)<br />
*Conditional operators (e.g. &&,| | and these equivalents: and,or)<br />
*Single and double-quoted strings (which can each embed strings with the other quote type)<br />
*Comma operator (so can have a list of expressions and just return the final result)<br />
*Assignment operator (=)<br />
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes<br />
*Pre-defined functions (there are already 70+, and it is easy to add more)<br />
<br />
EM syntax follows normal operator precedence:<br />
<br />
{|<br />
|Level||Operator(s)||Description<br />
|-<br />
|1||()||parentheses for grouping or calling functions<br />
|-<br />
|2||! - +||unary operators: not, negation, unary-plus<br />
|-<br />
|3||* /||times, divide<br />
|-<br />
|4||+ -||plus, minus<br />
|-<br />
|5||< <= > >= lt le gt ge||relative comparisons<br />
|-<br />
|6||== != eq ne||equality comparisons<br />
|-<br />
|7||and||logical AND<br />
|-<br />
|8||or||logical OR<br />
|-<br />
|9||=||assignment operator<br />
|-<br />
|10||,||comma operator<br />
|-<br />
|<br />
|}<br />
<br />
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).<br />
<br />
===Caution about using Assignment Operator (=)===<br />
<br />
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 sould 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.<br />
<br />
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 "==")<br />
<br />
The main reasons you may want to use assignment are:<br />
*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.<br />
*You need to forcibly change the response to a previous question based upon a later response<br />
<br />
==Access to Variables==<br />
<br />
Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:<br />
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5)<br />
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")<br />
*All {XXX} values used by templates<br />
<br />
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.<br />
<br />
Furthermore, Expression Manager lets you access many properties of the Question:<br />
<br />
{|<br />
|Syntax||Meaning||Example||Example Result<br />
|-<br />
|Qcode||an alias for Qcode.code||{join(',',name,gender)}||'Tom','M'<br />
|-<br />
|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||{join(',',name.code,gender.code)}||'Tom','M'<br />
|-<br />
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'<br />
|-<br />
|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'<br />
|-<br />
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'<br />
|-<br />
|Qcode.shown||the dispay value for the question||{join(',',name.shown,gender.shown)}||'Tom','Male'<br />
|-<br />
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'<br />
|-<br />
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'<br />
|-<br />
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337<br />
|-<br />
|Qcode.type||the question type||{gender.type}||'G'<br />
|-<br />
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'<br />
|-<br />
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3<br />
|-<br />
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5<br />
|-<br />
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1<br />
|-<br />
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus)||1<br />
|-<br />
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'<br />
|-<br />
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'<br />
|-<br />
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'<br />
|-<br />
|<br />
|}<br />
<br />
=== Security issue===<br />
<br />
For security issue, text entered by user are filtered. Some caracter are replaced by HTML entities.<br />
* & by &amp;<br />
* < by &lt;<br />
* > by &gt;<br />
<br />
==Qcode Variable Naming==<br />
<br />
Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:<br />
<br />
QuestionCode . '_' . AnswerID . '_' . ScaleId<br />
<br />
{|<br />
|Type||Description||Code||SubQs||Answer Options||Scales||Answer Code||Answer Shown||Relevance<br />
|-<br />
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}<br />
|-<br />
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}<br />
|-<br />
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}<br />
|-<br />
|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'}<br />
|-<br />
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}<br />
|-<br />
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}<br />
|-<br />
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}<br />
|-<br />
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}<br />
|-<br />
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}<br />
|-<br />
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}<br />
|-<br />
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||<br />
|-<br />
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||<br />
|-<br />
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}<br />
|-<br />
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}<br />
|-<br />
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}<br />
|-<br />
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}<br />
|-<br />
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}<br />
|-<br />
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}<br />
|-<br />
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}<br />
|-<br />
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20_comment}||{Q20.shown}||{Q20=='B'}<br />
|-<br />
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}<br />
|-<br />
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}<br />
|-<br />
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_D_comment}||{Q23_D.shown}||{!is_empty(Q23)}<br />
|-<br />
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}<br />
|-<br />
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q')}<br />
|-<br />
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}<br />
|-<br />
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}<br />
|-<br />
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}<br />
|-<br />
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}<br />
|-<br />
|<br />
|}<br />
<br />
==The reserved 'this', 'self', and 'that' variables==<br />
<br />
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.<br />
<br />
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).<br />
<br />
The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:<br />
*self<br />
*self.''suffix''<br />
*self.''sub-selector''<br />
*self.''sub-selector''.''suffix''<br />
<br />
''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)<br />
<br />
''sub-selector'' is one of:<br />
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)<br />
*nocomments - only subquestions that are not comments<br />
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected.<br />
<br />
Examples:<br />
*Has any part of a question been answered? {count(self.NAOK)>0}<br />
*What is the assessment score for this question? {sum(self.value)}<br />
<br />
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.<br />
*What is the grand total? {sum(self.NAOK)}<br />
*What is the total of row B? {sum(self.sq_B.NAOK)}<br />
*What is the total of column 3? {sum(self.sq_3.NAOK)}<br />
<br />
The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:<br />
*that.''qname''<br />
*that.''qname''.''suffix''<br />
*that.''qname''.''sub-selector''<br />
*that.''qname''.''sub-selector''.''suffix''<br />
<br />
''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''<br />
<br />
Examples:<br />
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}<br />
*What is the assessment score for q2? (sum(that.q2.NAOK)}<br />
*What is the grand total of q3? {sum(that.q3.NAOK)}<br />
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}<br />
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}<br />
<br />
The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.<br />
<br />
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'<br />
<br />
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.<br />
<br />
==Access to Functions==<br />
<br />
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.<br />
<br />
===Implemented Functions===<br />
<br />
The following functions are currently available:<br />
<br />
{|<br />
|Function||Meaning||Syntax<br />
|-<br />
[http://www.php.net/manual/en/function.abs.php ||abs]||Absolute value||number abs(number)<br />
|-<br />
[http://www.php.net/manual/en/function.acos.php ||acos]||Arc cosine||number acos(number)<br />
|-<br />
[http://www.php.net/manual/en/function.addslashes.php ||addslashes]||Quote string with slashes||string addslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.asin.php ||asin]||Arc sine||number asin(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan.php ||atan]||Arc tangent||number atan(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan2.php ||atan2]||Arc tangent of two variables||number atan2(number, number)<br />
|-<br />
[http://www.php.net/manual/en/function.ceil.php ||ceil]||Round fractions up||number ceil(number)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.cos.php ||cos]||Cosine||number cos(number)<br />
|-<br />
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)<br />
|-<br />
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)<br />
|-<br />
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.date.php ||date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[http://www.php.net/manual/en/function.exp.php ||exp]||Calculates the exponent of e||number exp(number)<br />
|-<br />
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)<br />
|-<br />
[http://www.php.net/manual/en/function.floor.php ||floor]||Round fractions down||number floor(number)<br />
|-<br />
[http://www.php.net/manual/en/function.gmdate.php ||gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.idate.php ||idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)<br />
|-<br />
[http://www.php.net/manual/en/function.implode.php ||implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)<br />
|-<br />
[http://www.php.net/manual/en/function.intval.php ||intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])<br />
|-<br />
[http://www.php.net/manual/en/function.empty.php ||is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.is-nan.php ||is_nan]||Finds whether a value is not a number||bool is_nan(var)<br />
|-<br />
[http://www.php.net/manual/en/function.is-null.php ||is_null]||Finds whether a variable is NULL||bool is_null(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
|join {MOUSEOVER(label="v")}In last 2.0 version{MOUSEOVER}||Join elements as a new string||join(arg1, arg2, ... argN)<br />
|-<br />
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.log.php ||log]||Natural logarithm||number log(number)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.max.php ||max]||Find highest value||number max(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.min.php ||min]||Find lowest value||number min(arg1, arg2, ... argN)<br />
|-<br />
[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 ]]]]]])<br />
|-<br />
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)<br />
|-<br />
[http://www.php.net/manual/en/function.nl2br.php ||nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)<br />
|-<br />
[http://www.php.net/manual/en/function.number-format.php ||number_format]||Format a number with grouped thousands||string number_format(number)<br />
|-<br />
|pi||Get value of pi||number pi()<br />
|-<br />
[http://www.php.net/manual/en/function.pow.php ||pow]||Exponential expression||number pow(base, exp)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.quotemeta.php ||quotemeta]||Quote meta characters||string quotemeta(string)<br />
|-<br />
[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)<br />
|-<br />
|regexMatch||compare a string to a [[Using regular expressions||regular expression]]||bool regexMatch(pattern,input)<br />
|-<br />
[http://www.php.net/manual/en/function.round.php ||round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.sin.php ||sin]||Sine||number sin(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.sprintf.php ||sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.sqrt.php ||sqrt]||Square root||number sqrt(arg)<br />
|-<br />
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.str-repeat.php ||str_repeat]||Repeat a string||string str_repeat(input, multiplier)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.strcasecmp.php ||strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)<br />
|-<br />
[http://www.php.net/manual/en/function.strcmp.php ||strcmp]||Binary safe string comparison||int strcmp(str1, str2)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.stripos.php ||stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.stripslashes.php ||stripslashes]||Un-quotes a quoted string||string stripslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.stristr.php ||stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])<br />
|-<br />
[http://www.php.net/manual/en/function.strlen.php ||strlen]||Get string length||int strlen(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strpos.php ||strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.strrev.php ||strrev]||Reverse a string||string strrev(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strstr.php ||strstr]||Find first occurrence of a string||string strstr(haystack, needle)<br />
|-<br />
[http://www.php.net/manual/en/function.strtolower.php ||strtolower]||Make a string lowercase||string strtolower(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strtoupper.php ||strtoupper]||Make a string uppercase||string strtoupper(string)<br />
|-<br />
[http://www.php.net/manual/en/function.substr.php ||substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])<br />
|-<br />
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)<br />
|-<br />
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.tan.php ||tan]||Tangent||number tan(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.time.php ||time]||Return current UNIX timestamp||number time()<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.ucwords.php ||ucwords]||Uppercase the first character of each word in a string||string ucwords(string)<br />
|-<br />
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)<br />
|-<br />
|<br />
|}<br />
<br />
===Functions that are Planned or Being Considered===<br />
<br />
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.<br />
<br />
{|<br />
|Syntax||Meaning||Comments<br />
|-<br />
|e()||returns the value of e||<br />
|-<br />
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||<br />
|-<br />
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||<br />
|-<br />
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown<br />
|-<br />
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||<br />
|-<br />
|getRelevance(X)||returns the relevance equation for question X||<br />
|-<br />
|getStartTime()||returns the date corresponding to the system time when the interview was started||<br />
|-<br />
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||<br />
|-<br />
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||<br />
|-<br />
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||<br />
|-<br />
|isInvalid(X)||returns true if the answer is of type *INVALID*||<br />
|-<br />
|isNA(X)||returns true if the answer is of type *NA*||<br />
|-<br />
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||<br />
|-<br />
|isRefused(X)||returns true if the answer is of type *REFUSED*||<br />
|-<br />
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||<br />
|-<br />
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||<br />
|-<br />
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||<br />
|-<br />
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||<br />
|-<br />
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||<br />
|-<br />
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||<br />
|-<br />
|mean(X,...)||returns the mean of a list of values||<br />
|-<br />
|numAnsOptions(X)||returns the number of answer options that question X has||<br />
|-<br />
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||<br />
|-<br />
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||<br />
|-<br />
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||<br />
|-<br />
|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.||<br />
|-<br />
|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.||<br />
|-<br />
|<br />
|}<br />
<br />
==Expression Manager Knows Which Variables are Local==<br />
<br />
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).<br />
<br />
==Cascading Conditions==<br />
<br />
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<br />
<br />
{|<br />
|Operator||Example||a||b||Result<br />
|-<br />
|+ (unary)||+a||N/A|| ||false<br />
|-<br />
|- (unary)||-a||N/A|| ||false<br />
|-<br />
|!||!a||N/A|| ||false<br />
|-<br />
|== (or eq)||a == b||N/A||5||false<br />
|-<br />
|== (or eq)||a == b||N/A||0||false<br />
|-<br />
|== (or eq)||a == b||N/A||N/A||false<br />
|-<br />
|!= (or ne)||a != b||N/A||5|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||N/A|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||0||false<br />
|-<br />
|> (or gt)||a > b||N/A||5|| false<br />
|-<br />
|>= (or ge)||a >= b||N/A||5||false<br />
|-<br />
|< (or lt)||a < b||N/A||5||false<br />
|-<br />
|<= (or le)||a <= b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||5||false<br />
|-<br />
|+||a + b||N/A||5||false<br />
|-<br />
|-||a - b||N/A||5||false<br />
|-<br />
|*||a * b||N/A||5||false<br />
|-<br />
|/||a / b||5||N/A||false<br />
|-<br />
|()||(a)||N/A|| ||false<br />
|-<br />
|(exp)||(a && b)||N/A||5||false<br />
|-<br />
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false<br />
|-<br />
|function||sum(a,b,b)||N/A||5||false<br />
|-<br />
|function||max(a,b)||N/A||5||false<br />
|-<br />
|function||min(a,b)||N/A||5||false<br />
|-<br />
|function||implode(', ',a,b,a,b)||N/A||5||false<br />
|-<br />
|function||if(a,a,b)||N/A||5||false<br />
|-<br />
|function||is_empty(a)||N/A|| ||false<br />
|-<br />
|function||is_empty(a)||0 (or blank)|| ||true<br />
|-<br />
|function||!is_empty(a)||N/A|| ||false<br />
|-<br />
|<br />
|}<br />
<br />
===Overriding Cascading Conditions===<br />
<br />
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.<br />
<br />
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<br />
#q1 is not added to the LEManyNA() clause<br />
#LEMval('q1') will continue to check whether the response is relevant, and will return '' if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression.<br />
<br />
So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).<br />
<br />
The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converage 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.<br />
<br />
==How does Expression Manager Support Conditional Micro-Tailoring?==<br />
<br />
Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):<br />
<br />
{|<br />
|Question Code||Relevance||Question Type||Question<br />
|-<br />
|name||1||text||What is your name?<br />
|-<br />
|age||1||text||How old are you?<br />
|-<br />
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}<br />
|-<br />
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.<br />
|-<br />
|kids||!badage||yesno||Do you have children?<br />
|-<br />
|parents||1||expr||{!badage && kids=='Y'}<br />
|-<br />
|numKids||parents||text||How many children do you have?<br />
|-<br />
|kid1||parents && numKids >= 1||text||How old is your first child?<br />
|-<br />
|kid2||parents && numKids >= 2||text||How old is your second child?<br />
|-<br />
|kid3||parents && numKids >= 3||text||How old is your third child?<br />
|-<br />
|kid4||parents && numKids >= 4||text||How old is your fourth child?<br />
|-<br />
|kid5||parents && numKids >= 5||text||How old is your fifth child?<br />
|-<br />
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}<br />
|-<br />
|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}<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==<br />
<br />
{|<br />
|Old Feature||New Feature||Comments<br />
|-<br />
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables<br />
|-<br />
|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<br />
|-<br />
|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\})<br />
|-<br />
|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<br />
|-<br />
|<br />
|}<br />
<br />
=Syntax Highlighting=<br />
<br />
To help with entering and validating expressions, EM provides syntax highlighting with the following features:<br />
<br />
==Types and Meanings of Syntax Highlighting==<br />
<br />
{|<br />
|Color||Sample||Meaning||Tooltip||Comments<br />
|-<br />
|tan background||<span style='color:#eee8aa,#eee8aa'>Sample</span>||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<br />
|-<br />
|blue bold text||'''<span style='color:blue,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|grey text||<span style='color:grey,#eee8aa'>'Sample'</span>||string||none||single and double-quoted strings are shown in grey text<br />
|-<br />
|bold maroon text||'''<span style='color:maroon,#eee8aa'>Sample</span>'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. 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.<br />
|-<br />
|bold cyan text||'''<span style='color:#4C88BE,#eee8aa'>Sample</span>'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan 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.<br />
|-<br />
|bold green text||'''<span style='color:green,#eee8aa'>Sample</span>'''||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 pageis 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.<br />
|-<br />
|bold pink text||'''<span style='color:#FF00FF,#eee8aa'>Sample</span>'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior pageis 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.<br />
|-<br />
|bold tan text||'''<span style='color:#996600,#eee8aa'>Sample</span>'''||a lime relacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE} are shown in bold tan text. The tooltip shows the current value.<br />
|-<br />
|red text||'''<span style='color:red,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|normal black text||<span style='color:black,#eee8aa'>Sample</span>||punctuation||none||All other punctionation within the expression is shown as normal black text.<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
=Relationship to LimeSurvey Ideas / Feature Requests=<br />
<br />
Expression Manager provides complete or partial solutions to each of the following:<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1 Conditions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/3/ Answercounts]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/5 Advanced reporting for assessments]<br />
**partial: Equations let one store the Assessment value in the database, and micro-tailoring can generate simple formatted reports. Authors can access those Equation values if they have more complex reporting needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/6 Assessment reports]<br />
**partial: Since Equations store the Assessment score, it should be possible to use Statistics to show distributions of those scores, and Quotas to limit the number of responses with those scores.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/7 Store assessment results for further evaluation]<br />
**Equations let one store the Assessment value in the database, completely solving this problem<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/22/ More advanced condition rules]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/28 Open Answertable up so that we can alter formatting]<br />
**partial: All of the question attributes are available, so authors can create custom AnswerTable equivalents as a Question. Once implatemented, they can also use the showTheseResponses() or showAllResponsesExecpt() functions<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/37 Export survey results with full questions to include images]<br />
**since Tailoring has access to the full question text, it can include images in the export<br />
**if subjects choose Print Your Answers after finishing the survey, those printouts will be fully tailored<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/63 List of question codes and SGQA identifiers]<br />
**The Show Survey Logic view shows that mapping (plus much more information)<br />
**In addition, you no longer have to use SGQA codes to refer to variables - you can use the Question code/title.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/69 Branch/jump to another question (earlier or later) based on current question]<br />
**You can use the Navigation Index for this in most cases<br />
**Once implemented, you can use the JumpTo() function. Like the Navigation Index, if you try to jump forward, it will stop on an intervening page if there are any of the relevant mandatory questions are unanswered, or if any relevant questions fail validation tests.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/86 set quota for total responses]<br />
**If the final question is an Equation that flags a survey as completed (so is NULL if a respondant does not get to that page), you can use Quotas on that question to control the number of completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/101 Review all conditions]<br />
**The [[Show Logic File|Show Logic File]] view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/105 Review all questions + Review all groups]<br />
**The [[Show Logic File|Show Logic File]] view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/107 How to visualize questions, logic & conditions]<br />
**The [[Show Logic File|Show Logic File]] view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/113 Offline Surveys]<br />
**Running a survey with all of the questions on the same page would let you do off-line data collection (e.g. email the html page and associated JavaScript). However, you would still want a way to submit the results so that they did not get lost. It may be possible to use Save As HTML to save partially completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/120 Remove INSERTANS from question text at survey results]<br />
**INSERTANS is no longer needed. You can refer to a variable by its SGQA code (without prefixing it with INSERTANS:), or by its question code.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/137 Informed Consent and Authorization Functionality]<br />
**You can show show the informed consent on the welcome page, then ask any additional questions needed (to ensure they meet the study inclusion/exclusion criteria), and ask them a Yes/No question whether they give their consent. Then, make all of the remaining questions conditional on that yesNo. For example, if the question is named ''consent'', you would set the relevance to the remaining questions to ''consent == "Y"'' (possibly ''and''ing that with whatever additional conditions you needed to support your branching needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/199 Show codes instead of of answers using INSERTANS]<br />
**{Qcode} returns the code instead of the response text (which you can get via {INSERTANS:SGQA}, or {Qcode.shown}<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/204 Need group mean or calculations for assessments]<br />
**Say you have N variables of which N-X were answered, you could compute the mean of the answered variables as {sum(var1, var2, ..., varN) / count(var1, var2, ..., varN)}<br />
**Computing the mean across a set of respondants would require extension of the Quota functionality.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/222 To insert a language dependent text]<br />
**Tailoring lets you conjugate verbs and decline nouns in each language<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/225 Surveyors should approve their answers]<br />
**Custom Questions with tailoring, or the showAllResponsesExcept() function will let Surveyors see all of the questions and responses before clicking Submit. If the Navigation Menu option is enabled, it is easy to go back and correct answers.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Suppliment to #answernnXnnXnnn method of targetting form elements]<br />
**You can now refer to questions and answers by their Question Code, so there is no longer a need to modify SGQA values.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/262 More flexibility with hidden questions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/265 Remove specific conditions from multiple questions]<br />
**You can now use Relevance, which is easier to manage than Conditions. If needed, they can all be exported from the database, edited in a spreadsheet, and re-imported.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/268 Cross Survey Reporting]<br />
**By using question codes that are unique across your surveys and versions, you can consolidate data from multiple surveys and/or compare them<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/275 Simplifying integration with other tools]<br />
**Expression Manager uses Question Codes instead of SGQA, making it easier to integrate with other tools.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Expose assessment score to 3rd party app processing]<br />
**This can be done with Equation question type<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/309 Multiple thank you pages]<br />
**This can be supported via conditional relevance branching and tailoring<br />
<br />
=Additional Reading=<br />
<br />
==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==<br />
<br />
==[[Expression Manager HowTos|Use Cases and HowTos]]==<br />
<br />
==[[Expression Manager Examples|Step-by-Step Examples]].==<br />
<br />
==[[Expression Manager for developers|Reference for Developers]]==<br />
<br />
==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_security_hints&diff=1706Installation security hints2013-02-01T10:07:54Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
==General==<br />
<br />
LimeSurvey relies on its own security system which is activated by default. The authors of this software takes no responsibility and makes no claims in relation to the appropriateness or secureness of this software. However we take security issues very serious and react quickly - if you know of any security problems with LimeSurvey please let us know: info@limesurvey.org or open a bug report at our [http://bugs.limesurvey.org bug tracker] (please mark it as private).<br />
<br />
==Linux file permissions==<br />
<br />
If you are using a Linux server, setting according file permissions is required to secure your LimeSurey installation.<br />
<br />
===Basic facts about Linux/*nix file permissions===<br />
<br />
A Linux/*nix operating system is multi-user. This means that, apart from your personal account, other user accounts may exist on the system and you should take care of what permissions you give to other users.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Hint:''' Setting file permissions is especially important in order to secure configuration files holding critical data such as passwords.</div><br />
<br />
''Note however that the 'root' account will always be granted permission to access your files (no matter what file permissions you set) as it is the super-admin user.''<br />
<br />
The webserver (which runs LimeSurvey), is also running under a given identity (user). On Linux, this is usually the 'www','www-data' (on Debian/Ubuntu), 'apache' or 'nobody' user. However, some hosting companies use systems (such as suexec) which make it possible to run LimeSurvey scripts with your personal user. Of course the webserver user must have the right to read LimeSurvey files. However, only a small subset of LimeSurvey subdirectories must be writeable by the webserver user.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Hint''': It is very valuable to revoke write permission for the webserver user to these LimeSurvey subdirectories that do not require it. Indeed, even if a LimeSurvey vulnerability might be discovered, the main files will still be protected from an illicit modification thanks to the file system permissions.</div><br />
<br />
===Setting file permissions on a self-managed Linux system===<br />
<br />
If you're managing your webserver and operating system configuration (you are the owner of the physical server or are renting a virtual server on which you have root access), you can follow these recommendations.<br />
<br />
You can first set the owner and group of your LimeSurvey files so that it will ease the file permissions setup.<br />
<br />
A possible strategy is to set the owner of the LimeSurvey files to your personal username, and the group of the LimeSurvey files to the webserver group. Usually this webserver group only contains the webserver account (and possibly another webmaster account).<br />
<br />
For instance if your username is 'myaccount' and the webserver user is 'apache' in the 'apache' group, then, from a shell access, you can use the following command:<br />
<br />
$ chown -R myaccount:apache limesurvey/<br />
<br />
Then set the file and subdirectories permissions.<br />
<br />
For the script to work properly it needs write access to some directories:<br />
*The "/limesurvey/tmp" directory and its subdirectories are used for imports/uploads and should be set to ''Read & Write'' for your webserver.<br />
*The upload/ directory and all its subdirectories must also have ''Read & Write'' for your webserver in order to enable picture and media files upload.<br />
* All other directories and files can be set to ''Read Only''<br />
<br />
<div class="simplebox">[[File:help.png]] '''Hint:''' Supposing you've followed the above recommendations on owner/group, these settings can be applied by the following commands:<br />
<br />
$ chmod -R o-r-w-x limesurvey/<br />
<br />
$ chmod -R -w limesurvey/<br />
<br />
$ chmod -R 770 limesurvey/tmp<br />
<br />
$ chmod -R 770 limesurvey/upload<br />
<br />
</div><br />
<br />
===Setting file permissions on a hosted webserver===<br />
<br />
Giving a standard procedure to secure a web application on a hosted environment is rather difficult because hosted environments differ in so many ways.<br />
<br />
As in the managed server case, for the script to work properly it needs write access to some directories:<br />
*The "/limesurvey/tmp" directory is used for imports/uploads and should be set to ''Read & Write'' for your webserver.<br />
*The upload/ directory and all its sub directories must also have ''Read & Write'' for your webserver in order to enable picture and media files upload.<br />
* The other directories and files should be set to ''Read Only''<br />
<br />
<div class="simplebox">[[File:help.png]] '''Hint:'''<br />
* Depending on your webserver configuration you will have to chmod the rights on the writable folders to 755 or 777 to make it writable for the webserver. Try 755 first - if it does not work 'upgrade' to 777.<br />
* You can also try to remove read access to config.php to others by setting this file's permissions to 750 - if it does not work 'upgrade' to 755.</div><br />
<br />
==Windows file permissions==<br />
<br />
If you are using a windows server your should ensure that the admin folder allows the owner of the webserver process to write files to this directory, however all other files can be set to read-only and execute.<br />
<br />
==Other security issues==<br />
<br />
The /application/config/config.php file contains a user name and password for your database server. This poses certain security issues, particularly if you are using a login that has high level administrative access to your database. In the event of some error returning the content of this php file to a user's browser, your database password and other details could be compromised. One way to minimize risk (a little) is set up a specific login that only has specific rights to your limesurvey database.<br />
<br />
Another way to secure this information is to put the certain information from the /application/config/config.php file in a non-web directory, i.e. for Apache users this is the directory above the htdocs (aka public_html or www) folder. So you will use config.php, but have one line in it - a line that includes the file with ACTUAL configuration information (ex: <?php return include("/home/hostfolder/safedata/configreal.php"); ?>). Remove all actual configuration information from /application/config/config.php, and paste it into the other file (configreal.php) that is included by /application/config/config.php. This other file should be located in a non-Web directory. Then /application/config/config.php will not contain database passwords, etc. - just the name of the file that DOES contain the database info. This avoids having to change all the other files that include /application/config/config.php, since they can still include it, and it will include the real config information. However you will need to edit configreal.php and change the follow parameters<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
'basePath' => dirname(dirname('''FILE''')),<br />
<br />
'runtimePath' => dirname(dirname(dirname('''FILE'''))).DIRECTORY_SEPARATOR.'tmp'.DIRECTORY_SEPARATOR.'runtime',<br />
<br />
[...]<br />
<br />
'urlManager' => array(<br />
<br />
[...]<br />
<br />
'rules' => require('routes.php'),<br />
<br />
[...]<br />
<br />
);<br />
<br />
</syntaxhighlight><br />
<br />
to use absolute directory paths to work properly. Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
'basePath' => '/var/www/htdocs/limesurvey',<br />
<br />
'runtimePath' => '/var/www/htdocs/limesurvey/tmp/runtime',<br />
<br />
[...]<br />
<br />
'urlManager' => array(<br />
<br />
[...]<br />
<br />
'rules' => require('/var/www/htdocs/limesurvey/routes.php'),<br />
<br />
[...]<br />
<br />
);<br />
<br />
</syntaxhighlight><br />
<br />
Also don't use "admin" as the default user. Go to your MySQL database (or other one if you installed LimeSurvey on different database) and change default user name "admin" to whatever you prefer (e.g. "admin_xyz"). It will be now much harder to guess administrator's new user name. Remember, this is one of the two variables intruders can use to gain access. The admin password is the other variable. So choose it with extreme care.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Expression_Manager&diff=1019Expression Manager2013-01-15T08:54:01Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
<div class="simplebox"> Note: This feature is only available in LimeSurvey 1.92 or later. </div><br />
<br />
=Quick Start Tutorial=<br />
<br />
==Overview==<br />
<br />
When customizing your surveys, you typically need a way to specify the following:<br />
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked<br />
#'''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).<br />
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern<br />
<br />
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).<br />
<br />
The following sections show the main places where Expression Manager is used<br />
<br />
==Relevance (Controlling Navigation/Branching)==<br />
<br />
Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses an Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).<br />
<br />
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, weight_kg 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).<br />
<br />
[[File:tutorial1.jpg]]<br />
<br />
Relevance is shown and editable in the following places:<br />
<br />
===Viewing / Editing Question-Level Relevance===<br />
<br />
This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.<br />
<br />
[[File:tutorial2.jpg]]<br />
<br />
This is the edit screen for the BMI question.<br />
<br />
[[File:tutorial3.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
===Viewing / Editing Group-Level Relevance===<br />
<br />
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).<br />
<br />
[[File:tutorial4.jpg]]<br />
<br />
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.<br />
<br />
Here is the screen for editing the group-level relevance for that question:<br />
<br />
[[File:tutorial5.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
==Tailoring/Piping==<br />
<br />
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.<br />
<br />
===Conditional Equations===<br />
<br />
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.<br />
<br />
[[File:tailoring7.jpg]]<br />
<br />
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.<br />
<br />
BMI computes the weight formula as {weight_kg / (height_m * height_m)}.<br />
<br />
Lastly, the report conditionally tailors the message for the subject, telling him what he entered (e.g. "You said you are 2 meters tall and weight 70 kg."<br />
<br />
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<br />
<br />
[[File:tailoring8.jpg]]<br />
<br />
From the edit window for this question, you can see two things:<br />
#Tailoring must surround expressions with Curly Braces<br />
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.<br />
<br />
[[File:tailoring9.jpg]]<br />
<br />
===Tailored Questions, Answers, and Reports===<br />
<br />
<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 <span> tag which is not valid inside select options.</div><br />
<br />
This example shows the BMI report.<br />
<br />
[[File:tailoring10.jpg]]<br />
<br />
Here is the edit window for the same question.<br />
<br />
[[File:tailoring11.jpg]]<br />
<br />
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.<br />
<br />
[[File:tailoring12.jpg]]<br />
<br />
You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.<br />
<br />
The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.<br />
<br />
=Introduction=<br />
<br />
LimeSurvey 1.92 and later 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).<br />
<br />
This wiki page is the definitive reference for Expression Manager syntax and functionality.<br />
<br />
==Key Definitions==<br />
#'''Expression''': Anything surrounded by curly braces<br />
**As long as there is no white space immediately after the opening brace or before the closing curly brace<br />
**The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.<br />
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text<br />
**You have access to all 'replacement fields', TOKENs, and INSERTANS values<br />
**You also have easier access to questions, answers, and their properties.<br />
#'''Relevance''' Equation: A new question attribute controlling question visiblity<br />
**If there is a relevance equation, then the question is only shown if the relevance evaluates to true.<br />
**Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance<br />
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database<br />
**It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"<br />
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+<br />
**Stands for Survey-Group-Question-Answer<br />
**SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.<br />
**These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed<br />
#'''Question Code''': This is the preferred variable name for EM<br />
**This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic<br />
**Although not required to be unique in <= 1.91+, it must be unique if you want to use EM<br />
**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".<br />
**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.<br />
<br />
==Do I have to use EM?==<br />
<br />
The short answer is No (but also yes).<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Can I mix use of Conditions and Relevance?==<br />
<br />
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.<br />
<br />
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.<br />
<br />
==How should I choose between Conditions and Relevance?==<br />
<br />
Here is a list of pros and cons of each style:<br />
<br />
{|<br />
|Style||Pros||Cons<br />
|-<br />
|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<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.<br />
<br />
==What are some other benefits of using EM?==<br />
<br />
Here are some of the other reasons you might want to use EM.<br />
#Calculations - you can create any calculation you can think of:<br />
**You have access to all common mathematical operators and functions<br />
**You have access to 70+ mathematical, date, and string processing functions<br />
**It is fairly easy for developers to add new functions if users need them<br />
#Storing Calculations to Database<br />
**You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.<br />
**You use the Equation question type to accomplish this.<br />
#Assessments<br />
**You can now create assessments or scale scores from any question type, not just the subset that used to be supported<br />
**You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page<br />
**You have more control over the reports generated based upon those assessment scores<br />
**You can store assessment scores in the database without needing JavaScript<br />
**You can hide assessment scores without needing JavaScript or CSS<br />
#Replacement Fields<br />
**Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.<br />
**This also avoids the common need to edit questions to change the SGQA code to make everything work.<br />
#Tailoring - you can conditionally display text based upon other values<br />
**Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")<br />
**Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 chldren")<br />
**Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.<br />
#New Variable Attributes - you can access the following to do your tailoring:<br />
** (no suffix) - an alias for qcode.code<br />
**.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<br />
**.NAOK - same as .code, but can be part of calculations or lists even if irrelevant<br />
**.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question<br />
**.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant<br />
**.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)<br />
**.qid - the question ID<br />
**.gid - the group ID<br />
**.sgqa - the SGQA value for the question<br />
**.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another<br />
**.qseq - the question sequence (starting from 0)<br />
**.gseq - the group sequence (starting from 0)<br />
**.mandatory - whether the question is mandatory (Y/N)<br />
**.question - the text of the question<br />
**.relevance - the relevance equation for the question<br />
**.grelevance - the relevance equation for the group<br />
**.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)<br />
**.type - the question type (the one character code)<br />
#Dynamic On-Page Changes<br />
**All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page<br />
**So, you have questions dynamically appear/disappear based upon whether they are relevant<br />
**Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.<br />
#New Data Entry Screen<br />
**In addition to using the current data-entry system, you can just use Survey-All-In-One.<br />
**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<br />
**This can be critical if your data entry person needs to see the tailoring, which is also dynamic.<br />
#Eliminates the need for most custom JavaScript<br />
**EM easily supports complicated computations, scoring, tailoring and conditional logic.<br />
**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.<br />
<br />
==What are some other helpful new features enabled by EM?==<br />
<br />
Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:<br />
#You can create more complex validation criteria<br />
**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.<br />
**EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.<br />
#Easy Re-ordering (or deleting) of Questions and Groups<br />
**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.<br />
**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.<br />
**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).<br />
#The Question/Group Navigation Index is always available and accurate<br />
**Prior to version 1.92, these indexes were not available if there were complex conditions<br />
**With EM, we can guarantee that they are accurate.<br />
**Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)<br />
***When jumping forwards, EM will re-validate all of the intervening questions/groups.<br />
***If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent<br />
***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.<br />
#Auto-conversion of Conditions to Relevance<br />
**When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them<br />
**Whenever you import a survey, relevance equations will be created as needed<br />
**Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.<br />
#Convenient Syntax Highlighting<br />
**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.<br />
**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.<br />
**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).<br />
***The list of answer choices uses this syntax: 'answers':{key:val, ... }.<br />
***''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.<br />
***''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)<br />
***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).<br />
#Easy review of entire survey logic and content<br />
**There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.<br />
**It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)<br />
**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.<br />
**Eveything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)<br />
**The syntax-highligting supports rapid navigation and editing of the survey.<br />
***If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.<br />
***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.<br />
***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)<br />
**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<br />
<br />
==How Backwards Compatible is EM with 1.91+?==<br />
<br />
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+.<br />
<br />
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 Survey Logic File view to quickly identify and fix any such comparisons in your survey.<br />
<br />
=Getting Started=<br />
<br />
The best way to get started with EM is to:<br />
*Install 1.92+ from http://www.limesurvey.org/en/download .<br />
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].<br />
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].<br />
*Explore the EM documentation (this page)<br />
*Examine the built-in EM test suite<br />
**From any survey, under tools, select the EM option<br />
**Availalbe Functions lists the 70+ functions and syntax<br />
**Unit Tests of Isolsted Expressions<br />
***shows examples of using all EM functions and operators, and the PHP and JavaScript results<br />
***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.<br />
<br />
=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=<br />
<br />
==Conditions => Relevance==<br />
<br />
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.<br />
<br />
==Assessments => Equations and Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Replacements => Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
==Equations==<br />
<br />
Equations were not supported without fancy JavaScript.<br />
<br />
==Equation Question Type==<br />
<br />
Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.<br />
<br />
=How Will Expression Manager Replace/Extend That Functionality?=<br />
<br />
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.<br />
<br />
==New Terminology When Referring to Expression Manager (EM)==<br />
<br />
EM "thinks" of its functionality in the following terms:<br />
*'''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).<br />
*'''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.<br />
*'''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.<br />
<br />
===Relevance and Cascading Relevance===<br />
<br />
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 diplayed. 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.<br />
<br />
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.<br />
<br />
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:<br />
<br />
{|<br />
|Question Code||Relevance||Question<br />
|-<br />
|Q1||1||What is your name?<br />
|-<br />
|Q2||Q1||{Q1}, how old are you?<br />
|-<br />
|Q3||Q2||So, you are {Q2} years old. Are you married?<br />
|-<br />
|Q4||Q3 == "Y"||{Q1}, how long have you been married?<br />
|-<br />
|Q5||Q4||How many children do you have, {Q1}?<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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 and 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.<br />
<br />
===Group-Level Relevance===<br />
<br />
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 deterimine 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.<br />
<br />
===Tailoring / Piping===<br />
<br />
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).<br />
<br />
Using these equations, you can do things such as:<br />
#Conditionally show tailored messages to the respondants based upon prior responses<br />
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself<br />
#Conjugate verbs and decline nouns within questions, answers, and reports.<br />
#Show summaries of responses before the "Show your answers" page at the end of the survey<br />
<br />
===Equations===<br />
<br />
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.<br />
<br />
This solves a common request for storing Assessment scores within the database<br />
<br />
==Syntax==<br />
<br />
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).<br />
<br />
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:<br />
<br />
<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),<br />
<br />
'',<br />
<br />
if(PFTotals >= -5 && PFTotals <= -4,<br />
<br />
'Very Soft',<br />
<br />
if(PFTotals >= -3 && PFTotals <= -2,<br />
<br />
'Soft',<br />
<br />
if(PFTotals == -1,<br />
<br />
'Somewhat Soft',<br />
<br />
if(PFTotals == 0,<br />
<br />
'Moderate',<br />
<br />
if(PFTotals == 1,<br />
<br />
'Somewhat Hard',<br />
<br />
if(PFTotals >= 2 && PFTotals <= 3,<br />
<br />
'Hard',<br />
<br />
if(PFTotals >= 4 && PFTotals <= 5,<br />
<br />
'Very Hard',<br />
<br />
''<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)}<br />
<br />
</syntaxhighlight><br />
<br />
Expression Manager supports the following syntax:<br />
*All standard mathematical operators (e.g. +,-,*,/,!)<br />
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)<br />
*Parentheses (so you can group sub-expressions)<br />
*Conditional operators (e.g. &&,| | and these equivalents: and,or)<br />
*Single and double-quoted strings (which can each embed strings with the other quote type)<br />
*Comma operator (so can have a list of expressions and just return the final result)<br />
*Assignment operator (=)<br />
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes<br />
*Pre-defined functions (there are already 70+, and it is easy to add more)<br />
<br />
EM syntax follows normal operator precedence:<br />
<br />
{|<br />
|Level||Operator(s)||Description<br />
|-<br />
|1||()||parentheses for grouping or calling functions<br />
|-<br />
|2||! - +||unary operators: not, negation, unary-plus<br />
|-<br />
|3||* /||times, divide<br />
|-<br />
|4||+ -||plus, minus<br />
|-<br />
|5||< <= > >= lt le gt ge||relative comparisons<br />
|-<br />
|6||== != eq ne||equality comparisons<br />
|-<br />
|7||and||logical AND<br />
|-<br />
|8||or||logical OR<br />
|-<br />
|9||=||assignment operator<br />
|-<br />
|10||,||comma operator<br />
|-<br />
|<br />
|}<br />
<br />
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).<br />
<br />
===Caution about using Assignment Operator (=)===<br />
<br />
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 sould 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.<br />
<br />
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 "==")<br />
<br />
The main reasons you may want to use assignment are:<br />
*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.<br />
*You need to forcibly change the response to a previous question based upon a later response<br />
<br />
==Access to Variables==<br />
<br />
Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:<br />
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5)<br />
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")<br />
*All {XXX} values used by templates<br />
<br />
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.<br />
<br />
Furthermore, Expression Manager lets you access many properties of the Question:<br />
<br />
{|<br />
|Syntax||Meaning||Example||Example Result<br />
|-<br />
|Qcode||an alias for Qcode.code||{join(',',name,gender)}||'Tom','M'<br />
|-<br />
|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||{join(',',name.code,gender.code)}||'Tom','M'<br />
|-<br />
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'<br />
|-<br />
|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'<br />
|-<br />
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'<br />
|-<br />
|Qcode.shown||the dispay value for the question||{join(',',name.shown,gender.shown)}||'Tom','Male'<br />
|-<br />
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'<br />
|-<br />
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'<br />
|-<br />
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337<br />
|-<br />
|Qcode.type||the question type||{gender.type}||'G'<br />
|-<br />
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'<br />
|-<br />
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3<br />
|-<br />
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5<br />
|-<br />
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1<br />
|-<br />
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus)||1<br />
|-<br />
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'<br />
|-<br />
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'<br />
|-<br />
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'<br />
|-<br />
|<br />
|}<br />
<br />
=== Security issue===<br />
<br />
For security issue, text entered by user are filtered. Some caracter are replaced by HTML entities.<br />
* & by &amp;<br />
* < by &lt;<br />
* > by &gt;<br />
<br />
==Qcode Variable Naming==<br />
<br />
Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:<br />
<br />
QuestionCode . '_' . AnswerID . '_' . ScaleId<br />
<br />
{|<br />
|Type||Description||Code||SubQs||Answer Options||Scales||Answer Code||Answer Shown||Relevance<br />
|-<br />
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}<br />
|-<br />
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}<br />
|-<br />
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}<br />
|-<br />
|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'}<br />
|-<br />
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}<br />
|-<br />
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}<br />
|-<br />
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}<br />
|-<br />
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}<br />
|-<br />
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}<br />
|-<br />
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}<br />
|-<br />
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||<br />
|-<br />
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||<br />
|-<br />
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}<br />
|-<br />
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}<br />
|-<br />
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}<br />
|-<br />
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}<br />
|-<br />
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}<br />
|-<br />
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}<br />
|-<br />
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}<br />
|-<br />
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20_comment}||{Q20.shown}||{Q20=='B'}<br />
|-<br />
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}<br />
|-<br />
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}<br />
|-<br />
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_D_comment}||{Q23_D.shown}||{!is_empty(Q23)}<br />
|-<br />
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}<br />
|-<br />
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q')}<br />
|-<br />
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}<br />
|-<br />
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}<br />
|-<br />
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}<br />
|-<br />
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}<br />
|-<br />
|<br />
|}<br />
<br />
==The reserved 'this', 'self', and 'that' variables==<br />
<br />
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.<br />
<br />
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).<br />
<br />
The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:<br />
*self<br />
*self.''suffix''<br />
*self.''sub-selector''<br />
*self.''sub-selector''.''suffix''<br />
<br />
''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)<br />
<br />
''sub-selector'' is one of:<br />
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)<br />
*nocomments - only subquestions that are not comments<br />
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected.<br />
<br />
Examples:<br />
*Has any part of a question been answered? {count(self.NAOK)>0}<br />
*What is the assessment score for this question? {sum(self.value)}<br />
<br />
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.<br />
*What is the grand total? {sum(self.NAOK)}<br />
*What is the total of row B? {sum(self.sq_B.NAOK)}<br />
*What is the total of column 3? {sum(self.sq_3.NAOK)}<br />
<br />
The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:<br />
*that.''qname''<br />
*that.''qname''.''suffix''<br />
*that.''qname''.''sub-selector''<br />
*that.''qname''.''sub-selector''.''suffix''<br />
<br />
''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''<br />
<br />
Examples:<br />
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}<br />
*What is the assessment score for q2? (sum(that.q2.NAOK)}<br />
*What is the grand total of q3? {sum(that.q3.NAOK)}<br />
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}<br />
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}<br />
<br />
The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.<br />
<br />
The one caveat is that when you use the 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'<br />
<br />
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.<br />
<br />
==Access to Functions==<br />
<br />
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.<br />
<br />
===Implemented Functions===<br />
<br />
The following functions are currently available:<br />
<br />
{|<br />
|Function||Meaning||Syntax<br />
|-<br />
[http://www.php.net/manual/en/function.abs.php ||abs]||Absolute value||number abs(number)<br />
|-<br />
[http://www.php.net/manual/en/function.acos.php ||acos]||Arc cosine||number acos(number)<br />
|-<br />
[http://www.php.net/manual/en/function.addslashes.php ||addslashes]||Quote string with slashes||string addslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.asin.php ||asin]||Arc sine||number asin(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan.php ||atan]||Arc tangent||number atan(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan2.php ||atan2]||Arc tangent of two variables||number atan2(number, number)<br />
|-<br />
[http://www.php.net/manual/en/function.ceil.php ||ceil]||Round fractions up||number ceil(number)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.cos.php ||cos]||Cosine||number cos(number)<br />
|-<br />
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)<br />
|-<br />
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)<br />
|-<br />
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.date.php ||date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[http://www.php.net/manual/en/function.exp.php ||exp]||Calculates the exponent of e||number exp(number)<br />
|-<br />
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)<br />
|-<br />
[http://www.php.net/manual/en/function.floor.php ||floor]||Round fractions down||number floor(number)<br />
|-<br />
[http://www.php.net/manual/en/function.gmdate.php ||gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.idate.php ||idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)<br />
|-<br />
[http://www.php.net/manual/en/function.implode.php ||implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)<br />
|-<br />
[http://www.php.net/manual/en/function.intval.php ||intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])<br />
|-<br />
[http://www.php.net/manual/en/function.empty.php ||is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.is-nan.php ||is_nan]||Finds whether a value is not a number||bool is_nan(var)<br />
|-<br />
[http://www.php.net/manual/en/function.is-null.php ||is_null]||Finds whether a variable is NULL||bool is_null(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.log.php ||log]||Natural logarithm||number log(number)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.max.php ||max]||Find highest value||number max(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.min.php ||min]||Find lowest value||number min(arg1, arg2, ... argN)<br />
|-<br />
[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 ]]]]]])<br />
|-<br />
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)<br />
|-<br />
[http://www.php.net/manual/en/function.nl2br.php ||nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)<br />
|-<br />
[http://www.php.net/manual/en/function.number-format.php ||number_format]||Format a number with grouped thousands||string number_format(number)<br />
|-<br />
|pi||Get value of pi||number pi()<br />
|-<br />
[http://www.php.net/manual/en/function.pow.php ||pow]||Exponential expression||number pow(base, exp)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.quotemeta.php ||quotemeta]||Quote meta characters||string quotemeta(string)<br />
|-<br />
[http://www.php.net/manual/en/function.rand.php ||rand]||Generate a random integer||int rand() OR int rand(min, max)<br />
|-<br />
|regexMatch||compare a string to a [[Using regular expressions||regular expression]]||bool regexMatch(pattern,input)<br />
|-<br />
[http://www.php.net/manual/en/function.round.php ||round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.sin.php ||sin]||Sine||number sin(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.sprintf.php ||sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.sqrt.php ||sqrt]||Square root||number sqrt(arg)<br />
|-<br />
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.str-repeat.php ||str_repeat]||Repeat a string||string str_repeat(input, multiplier)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.strcasecmp.php ||strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)<br />
|-<br />
[http://www.php.net/manual/en/function.strcmp.php ||strcmp]||Binary safe string comparison||int strcmp(str1, str2)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.stripos.php ||stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.stripslashes.php ||stripslashes]||Un-quotes a quoted string||string stripslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.stristr.php ||stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])<br />
|-<br />
[http://www.php.net/manual/en/function.strlen.php ||strlen]||Get string length||int strlen(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strpos.php ||strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.strrev.php ||strrev]||Reverse a string||string strrev(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strstr.php ||strstr]||Find first occurrence of a string||string strstr(haystack, needle)<br />
|-<br />
[http://www.php.net/manual/en/function.strtolower.php ||strtolower]||Make a string lowercase||string strtolower(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strtoupper.php ||strtoupper]||Make a string uppercase||string strtoupper(string)<br />
|-<br />
[http://www.php.net/manual/en/function.substr.php ||substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])<br />
|-<br />
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)<br />
|-<br />
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.tan.php ||tan]||Tangent||number tan(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.time.php ||time]||Return current UNIX timestamp||number time()<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.ucwords.php ||ucwords]||Uppercase the first character of each word in a string||string ucwords(string)<br />
|-<br />
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)<br />
|-<br />
|<br />
|}<br />
<br />
===Functions that are Planned or Being Considered===<br />
<br />
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.<br />
<br />
{|<br />
|Syntax||Meaning||Comments<br />
|-<br />
|e()||returns the value of e||<br />
|-<br />
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||<br />
|-<br />
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||<br />
|-<br />
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown<br />
|-<br />
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||<br />
|-<br />
|getRelevance(X)||returns the relevance equation for question X||<br />
|-<br />
|getStartTime()||returns the date corresponding to the system time when the interview was started||<br />
|-<br />
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||<br />
|-<br />
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||<br />
|-<br />
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||<br />
|-<br />
|isInvalid(X)||returns true if the answer is of type *INVALID*||<br />
|-<br />
|isNA(X)||returns true if the answer is of type *NA*||<br />
|-<br />
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||<br />
|-<br />
|isRefused(X)||returns true if the answer is of type *REFUSED*||<br />
|-<br />
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||<br />
|-<br />
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||<br />
|-<br />
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||<br />
|-<br />
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||<br />
|-<br />
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||<br />
|-<br />
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||<br />
|-<br />
|mean(X,...)||returns the mean of a list of values||<br />
|-<br />
|numAnsOptions(X)||returns the number of answer options that question X has||<br />
|-<br />
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||<br />
|-<br />
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||<br />
|-<br />
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||<br />
|-<br />
|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.||<br />
|-<br />
|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.||<br />
|-<br />
|<br />
|}<br />
<br />
==Expression Manager Knows Which Variables are Local==<br />
<br />
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).<br />
<br />
==Cascading Conditions==<br />
<br />
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<br />
<br />
{|<br />
|Operator||Example||a||b||Result<br />
|-<br />
|+ (unary)||+a||N/A|| ||false<br />
|-<br />
|- (unary)||-a||N/A|| ||false<br />
|-<br />
|!||!a||N/A|| ||false<br />
|-<br />
|== (or eq)||a == b||N/A||5||false<br />
|-<br />
|== (or eq)||a == b||N/A||0||false<br />
|-<br />
|== (or eq)||a == b||N/A||N/A||false<br />
|-<br />
|!= (or ne)||a != b||N/A||5|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||N/A|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||0||false<br />
|-<br />
|> (or gt)||a > b||N/A||5|| false<br />
|-<br />
|>= (or ge)||a >= b||N/A||5||false<br />
|-<br />
|< (or lt)||a < b||N/A||5||false<br />
|-<br />
|<= (or le)||a <= b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||5||false<br />
|-<br />
|+||a + b||N/A||5||false<br />
|-<br />
|-||a - b||N/A||5||false<br />
|-<br />
|*||a * b||N/A||5||false<br />
|-<br />
|/||a / b||5||N/A||false<br />
|-<br />
|()||(a)||N/A|| ||false<br />
|-<br />
|(exp)||(a && b)||N/A||5||false<br />
|-<br />
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false<br />
|-<br />
|function||sum(a,b,b)||N/A||5||false<br />
|-<br />
|function||max(a,b)||N/A||5||false<br />
|-<br />
|function||min(a,b)||N/A||5||false<br />
|-<br />
|function||implode(', ',a,b,a,b)||N/A||5||false<br />
|-<br />
|function||if(a,a,b)||N/A||5||false<br />
|-<br />
|function||is_empty(a)||N/A|| ||false<br />
|-<br />
|function||is_empty(a)||0 (or blank)|| ||true<br />
|-<br />
|function||!is_empty(a)||N/A|| ||false<br />
|-<br />
|<br />
|}<br />
<br />
===Overriding Cascading Conditions===<br />
<br />
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.<br />
<br />
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<br />
#q1 is not added to the LEManyNA() clause<br />
#LEMval('q1') will continue to check whether the response is relevant, and will return '' if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression.<br />
<br />
So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).<br />
<br />
The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converage 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.<br />
<br />
==How does Expression Manager Support Conditional Micro-Tailoring?==<br />
<br />
Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):<br />
<br />
{|<br />
|Question Code||Relevance||Question Type||Question<br />
|-<br />
|name||1||text||What is your name?<br />
|-<br />
|age||1||text||How old are you?<br />
|-<br />
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}<br />
|-<br />
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.<br />
|-<br />
|kids||!badage||yesno||Do you have children?<br />
|-<br />
|parents||1||expr||{!badage && kids=='Y'}<br />
|-<br />
|numKids||parents||text||How many children do you have?<br />
|-<br />
|kid1||parents && numKids >= 1||text||How old is your first child?<br />
|-<br />
|kid2||parents && numKids >= 2||text||How old is your second child?<br />
|-<br />
|kid3||parents && numKids >= 3||text||How old is your third child?<br />
|-<br />
|kid4||parents && numKids >= 4||text||How old is your fourth child?<br />
|-<br />
|kid5||parents && numKids >= 5||text||How old is your fifth child?<br />
|-<br />
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}<br />
|-<br />
|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}<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==<br />
<br />
{|<br />
|Old Feature||New Feature||Comments<br />
|-<br />
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables<br />
|-<br />
|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<br />
|-<br />
|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\})<br />
|-<br />
|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<br />
|-<br />
|<br />
|}<br />
<br />
=Syntax Highlighting=<br />
<br />
To help with entering and validating expressions, EM provides syntax highlighting with the following features:<br />
<br />
==Types and Meanings of Syntax Highlighting==<br />
<br />
{|<br />
|Color||Sample||Meaning||Tooltip||Comments<br />
|-<br />
|tan background||<span style='color:#eee8aa,#eee8aa'>Sample</span>||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<br />
|-<br />
|blue bold text||'''<span style='color:blue,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|grey text||<span style='color:grey,#eee8aa'>'Sample'</span>||string||none||single and double-quoted strings are shown in grey text<br />
|-<br />
|bold maroon text||'''<span style='color:maroon,#eee8aa'>Sample</span>'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. 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.<br />
|-<br />
|bold cyan text||'''<span style='color:#4C88BE,#eee8aa'>Sample</span>'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan 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.<br />
|-<br />
|bold green text||'''<span style='color:green,#eee8aa'>Sample</span>'''||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 pageis 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.<br />
|-<br />
|bold pink text||'''<span style='color:#FF00FF,#eee8aa'>Sample</span>'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior pageis 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.<br />
|-<br />
|bold tan text||'''<span style='color:#996600,#eee8aa'>Sample</span>'''||a lime relacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE} are shown in bold tan text. The tooltip shows the current value.<br />
|-<br />
|red text||'''<span style='color:red,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|normal black text||<span style='color:black,#eee8aa'>Sample</span>||punctuation||none||All other punctionation within the expression is shown as normal black text.<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
=Relationship to LimeSurvey Ideas / Feature Requests=<br />
<br />
Expression Manager provides complete or partial solutions to each of the following:<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1 Conditions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/3/ Answercounts]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/5 Advanced reporting for assessments]<br />
**partial: Equations let one store the Assessment value in the database, and micro-tailoring can generate simple formatted reports. Authors can access those Equation values if they have more complex reporting needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/6 Assessment reports]<br />
**partial: Since Equations store the Assessment score, it should be possible to use Statistics to show distributions of those scores, and Quotas to limit the number of responses with those scores.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/7 Store assessment results for further evaluation]<br />
**Equations let one store the Assessment value in the database, completely solving this problem<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/22/ More advanced condition rules]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/28 Open Answertable up so that we can alter formatting]<br />
**partial: All of the question attributes are available, so authors can create custom AnswerTable equivalents as a Question. Once implatemented, they can also use the showTheseResponses() or showAllResponsesExecpt() functions<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/37 Export survey results with full questions to include images]<br />
**since Tailoring has access to the full question text, it can include images in the export<br />
**if subjects choose Print Your Answers after finishing the survey, those printouts will be fully tailored<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/63 List of question codes and SGQA identifiers]<br />
**The Show Survey Logic view shows that mapping (plus much more information)<br />
**In addition, you no longer have to use SGQA codes to refer to variables - you can use the Question code/title.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/69 Branch/jump to another question (earlier or later) based on current question]<br />
**You can use the Navigation Index for this in most cases<br />
**Once implemented, you can use the JumpTo() function. Like the Navigation Index, if you try to jump forward, it will stop on an intervening page if there are any of the relevant mandatory questions are unanswered, or if any relevant questions fail validation tests.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/86 set quota for total responses]<br />
**If the final question is an Equation that flags a survey as completed (so is NULL if a respondant does not get to that page), you can use Quotas on that question to control the number of completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/101 Review all conditions]<br />
**The Show Logic File view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/105 Review all questions + Review all groups]<br />
**The Show Logic File view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/107 How to visualize questions, logic & conditions]<br />
**The Show Logic File view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/113 Offline Surveys]<br />
**Running a survey with all of the questions on the same page would let you do off-line data collection (e.g. email the html page and associated JavaScript). However, you would still want a way to submit the results so that they did not get lost. It may be possible to use Save As HTML to save partially completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/120 Remove INSERTANS from question text at survey results]<br />
**INSERTANS is no longer needed. You can refer to a variable by its SGQA code (without prefixing it with INSERTANS:), or by its question code.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/137 Informed Consent and Authorization Functionality]<br />
**You can show show the informed consent on the welcome page, then ask any additional questions needed (to ensure they meet the study inclusion/exclusion criteria), and ask them a Yes/No question whether they give their consent. Then, make all of the remaining questions conditional on that yesNo. For example, if the question is named ''consent'', you would set the relevance to the remaining questions to ''consent == "Y"'' (possibly ''and''ing that with whatever additional conditions you needed to support your branching needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/199 Show codes instead of of answers using INSERTANS]<br />
**{Qcode} returns the code instead of the response text (which you can get via {INSERTANS:SGQA}, or {Qcode.shown}<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/204 Need group mean or calculations for assessments]<br />
**Say you have N variables of which N-X were answered, you could compute the mean of the answered variables as {sum(var1, var2, ..., varN) / count(var1, var2, ..., varN)}<br />
**Computing the mean across a set of respondants would require extension of the Quota functionality.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/222 To insert a language dependent text]<br />
**Tailoring lets you conjugate verbs and decline nouns in each language<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/225 Surveyors should approve their answers]<br />
**Custom Questions with tailoring, or the showAllResponsesExcept() function will let Surveyors see all of the questions and responses before clicking Submit. If the Navigation Menu option is enabled, it is easy to go back and correct answers.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Suppliment to #answernnXnnXnnn method of targetting form elements]<br />
**You can now refer to questions and answers by their Question Code, so there is no longer a need to modify SGQA values.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/262 More flexibility with hidden questions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/265 Remove specific conditions from multiple questions]<br />
**You can now use Relevance, which is easier to manage than Conditions. If needed, they can all be exported from the database, edited in a spreadsheet, and re-imported.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/268 Cross Survey Reporting]<br />
**By using question codes that are unique across your surveys and versions, you can consolidate data from multiple surveys and/or compare them<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/275 Simplifying integration with other tools]<br />
**Expression Manager uses Question Codes instead of SGQA, making it easier to integrate with other tools.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Expose assessment score to 3rd party app processing]<br />
**This can be done with Equation question type<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/309 Multiple thank you pages]<br />
**This can be supported via conditional relevance branching and tailoring<br />
<br />
=Additional Reading=<br />
<br />
==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==<br />
<br />
==[[Expression Manager HowTos|Use Cases and HowTos]]==<br />
<br />
==[[Expression Manager Examples|Step-by-Step Examples]].==<br />
<br />
==[[Expression Manager for developers|Reference for Developers]]==<br />
<br />
==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Expression_Manager&diff=1020Expression Manager2012-12-20T08:36:50Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
<div class="simplebox"> Note: This feature is only available in LimeSurvey 1.92 or later. </div><br />
<br />
=Quick Start Tutorial=<br />
<br />
==Overview==<br />
<br />
When customizing your surveys, you typically need a way to specify the following:<br />
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked<br />
#'''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).<br />
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern<br />
<br />
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).<br />
<br />
The following sections show the main places where Expression Manager is used<br />
<br />
==Relevance (Controlling Navigation/Branching)==<br />
<br />
Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses an Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).<br />
<br />
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, weight_kg 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).<br />
<br />
[[File:tutorial1.jpg]]<br />
<br />
Relevance is shown and editable in the following places:<br />
<br />
===Viewing / Editing Question-Level Relevance===<br />
<br />
This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.<br />
<br />
[[File:tutorial2.jpg]]<br />
<br />
This is the edit screen for the BMI question.<br />
<br />
[[File:tutorial3.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
===Viewing / Editing Group-Level Relevance===<br />
<br />
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).<br />
<br />
[[File:tutorial4.jpg]]<br />
<br />
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.<br />
<br />
Here is the screen for editing the group-level relevance for that question:<br />
<br />
[[File:tutorial5.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
==Tailoring/Piping==<br />
<br />
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.<br />
<br />
===Conditional Equations===<br />
<br />
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.<br />
<br />
[[File:tailoring7.jpg]]<br />
<br />
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.<br />
<br />
BMI computes the weight formula as {weight_kg / (height_m * height_m)}.<br />
<br />
Lastly, the report conditionally tailors the message for the subject, telling him what he entered (e.g. "You said you are 2 meters tall and weight 70 kg."<br />
<br />
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<br />
<br />
[[File:tailoring8.jpg]]<br />
<br />
From the edit window for this question, you can see two things:<br />
#Tailoring must surround expressions with Curly Braces<br />
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.<br />
<br />
[[File:tailoring9.jpg]]<br />
<br />
===Tailored Questions, Answers, and Reports===<br />
<br />
<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 <span> tag which is not valid inside select options.</div><br />
<br />
This example shows the BMI report.<br />
<br />
[[File:tailoring10.jpg]]<br />
<br />
Here is the edit window for the same question.<br />
<br />
[[File:tailoring11.jpg]]<br />
<br />
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.<br />
<br />
[[File:tailoring12.jpg]]<br />
<br />
You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.<br />
<br />
The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.<br />
<br />
=Introduction=<br />
<br />
LimeSurvey 1.92 and later 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).<br />
<br />
This wiki page is the definitive reference for Expression Manager syntax and functionality.<br />
<br />
==Key Definitions==<br />
#'''Expression''': Anything surrounded by curly braces<br />
**As long as there is no white space immediately after the opening brace or before the closing curly brace<br />
**The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.<br />
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text<br />
**You have access to all 'replacement fields', TOKENs, and INSERTANS values<br />
**You also have easier access to questions, answers, and their properties.<br />
#'''Relevance''' Equation: A new question attribute controlling question visiblity<br />
**If there is a relevance equation, then the question is only shown if the relevance evaluates to true.<br />
**Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance<br />
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database<br />
**It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"<br />
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+<br />
**Stands for Survey-Group-Question-Answer<br />
**SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.<br />
**These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed<br />
#'''Question Code''': This is the preferred variable name for EM<br />
**This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic<br />
**Although not required to be unique in <= 1.91+, it must be unique if you want to use EM<br />
**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".<br />
**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.<br />
<br />
==Do I have to use EM?==<br />
<br />
The short answer is No (but also yes).<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Can I mix use of Conditions and Relevance?==<br />
<br />
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.<br />
<br />
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.<br />
<br />
==How should I choose between Conditions and Relevance?==<br />
<br />
Here is a list of pros and cons of each style:<br />
<br />
{|<br />
|Style||Pros||Cons<br />
|-<br />
|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<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.<br />
<br />
==What are some other benefits of using EM?==<br />
<br />
Here are some of the other reasons you might want to use EM.<br />
#Calculations - you can create any calculation you can think of:<br />
**You have access to all common mathematical operators and functions<br />
**You have access to 70+ mathematical, date, and string processing functions<br />
**It is fairly easy for developers to add new functions if users need them<br />
#Storing Calculations to Database<br />
**You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.<br />
**You use the Equation question type to accomplish this.<br />
#Assessments<br />
**You can now create assessments or scale scores from any question type, not just the subset that used to be supported<br />
**You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page<br />
**You have more control over the reports generated based upon those assessment scores<br />
**You can store assessment scores in the database without needing JavaScript<br />
**You can hide assessment scores without needing JavaScript or CSS<br />
#Replacement Fields<br />
**Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.<br />
**This also avoids the common need to edit questions to change the SGQA code to make everything work.<br />
#Tailoring - you can conditionally display text based upon other values<br />
**Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")<br />
**Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 chldren")<br />
**Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.<br />
#New Variable Attributes - you can access the following to do your tailoring:<br />
** (no suffix) - an alias for qcode.code<br />
**.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<br />
**.NAOK - same as .code, but can be part of calculations or lists even if irrelevant<br />
**.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question<br />
**.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant<br />
**.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)<br />
**.qid - the question ID<br />
**.gid - the group ID<br />
**.sgqa - the SGQA value for the question<br />
**.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another<br />
**.qseq - the question sequence (starting from 0)<br />
**.gseq - the group sequence (starting from 0)<br />
**.mandatory - whether the question is mandatory (Y/N)<br />
**.question - the text of the question<br />
**.relevance - the relevance equation for the question<br />
**.grelevance - the relevance equation for the group<br />
**.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)<br />
**.type - the question type (the one character code)<br />
#Dynamic On-Page Changes<br />
**All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page<br />
**So, you have questions dynamically appear/disappear based upon whether they are relevant<br />
**Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.<br />
#New Data Entry Screen<br />
**In addition to using the current data-entry system, you can just use Survey-All-In-One.<br />
**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<br />
**This can be critical if your data entry person needs to see the tailoring, which is also dynamic.<br />
#Eliminates the need for most custom JavaScript<br />
**EM easily supports complicated computations, scoring, tailoring and conditional logic.<br />
**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.<br />
<br />
==What are some other helpful new features enabled by EM?==<br />
<br />
Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:<br />
#You can create more complex validation criteria<br />
**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.<br />
**EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.<br />
#Easy Re-ordering (or deleting) of Questions and Groups<br />
**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.<br />
**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.<br />
**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).<br />
#The Question/Group Navigation Index is always available and accurate<br />
**Prior to version 1.92, these indexes were not available if there were complex conditions<br />
**With EM, we can guarantee that they are accurate.<br />
**Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)<br />
***When jumping forwards, EM will re-validate all of the intervening questions/groups.<br />
***If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent<br />
***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.<br />
#Auto-conversion of Conditions to Relevance<br />
**When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them<br />
**Whenever you import a survey, relevance equations will be created as needed<br />
**Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.<br />
#Convenient Syntax Highlighting<br />
**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.<br />
**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.<br />
**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).<br />
***The list of answer choices uses this syntax: 'answers':{key:val, ... }.<br />
***''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.<br />
***''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)<br />
***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).<br />
#Easy review of entire survey logic and content<br />
**There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.<br />
**It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)<br />
**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.<br />
**Eveything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)<br />
**The syntax-highligting supports rapid navigation and editing of the survey.<br />
***If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.<br />
***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.<br />
***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)<br />
**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<br />
<br />
==How Backwards Compatible is EM with 1.91+?==<br />
<br />
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+.<br />
<br />
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 Survey Logic File view to quickly identify and fix any such comparisons in your survey.<br />
<br />
=Getting Started=<br />
<br />
The best way to get started with EM is to:<br />
*Install 1.92+ from http://www.limesurvey.org/en/download .<br />
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].<br />
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].<br />
*Explore the EM documentation (this page)<br />
*Examine the built-in EM test suite<br />
**From any survey, under tools, select the EM option<br />
**Availalbe Functions lists the 70+ functions and syntax<br />
**Unit Tests of Isolsted Expressions<br />
***shows examples of using all EM functions and operators, and the PHP and JavaScript results<br />
***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.<br />
<br />
=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=<br />
<br />
==Conditions => Relevance==<br />
<br />
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.<br />
<br />
==Assessments => Equations and Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Replacements => Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
==Equations==<br />
<br />
Equations were not supported without fancy JavaScript.<br />
<br />
==Equation Question Type==<br />
<br />
Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.<br />
<br />
=How Will Expression Manager Replace/Extend That Functionality?=<br />
<br />
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.<br />
<br />
==New Terminology When Referring to Expression Manager (EM)==<br />
<br />
EM "thinks" of its functionality in the following terms:<br />
*'''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).<br />
*'''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.<br />
*'''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.<br />
<br />
===Relevance and Cascading Relevance===<br />
<br />
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 diplayed. 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.<br />
<br />
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.<br />
<br />
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:<br />
<br />
{|<br />
|Question Code||Relevance||Question<br />
|-<br />
|Q1||1||What is your name?<br />
|-<br />
|Q2||Q1||{Q1}, how old are you?<br />
|-<br />
|Q3||Q2||So, you are {Q2} years old. Are you married?<br />
|-<br />
|Q4||Q3 == "Y"||{Q1}, how long have you been married?<br />
|-<br />
|Q5||Q4||How many children do you have, {Q1}?<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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 and 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.<br />
<br />
===Group-Level Relevance===<br />
<br />
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 deterimine 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.<br />
<br />
===Tailoring / Piping===<br />
<br />
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).<br />
<br />
Using these equations, you can do things such as:<br />
#Conditionally show tailored messages to the respondants based upon prior responses<br />
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself<br />
#Conjugate verbs and decline nouns within questions, answers, and reports.<br />
#Show summaries of responses before the "Show your answers" page at the end of the survey<br />
<br />
===Equations===<br />
<br />
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.<br />
<br />
This solves a common request for storing Assessment scores within the database<br />
<br />
==Syntax==<br />
<br />
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).<br />
<br />
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:<br />
<br />
<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),<br />
<br />
'',<br />
<br />
if(PFTotals >= -5 && PFTotals <= -4,<br />
<br />
'Very Soft',<br />
<br />
if(PFTotals >= -3 && PFTotals <= -2,<br />
<br />
'Soft',<br />
<br />
if(PFTotals == -1,<br />
<br />
'Somewhat Soft',<br />
<br />
if(PFTotals == 0,<br />
<br />
'Moderate',<br />
<br />
if(PFTotals == 1,<br />
<br />
'Somewhat Hard',<br />
<br />
if(PFTotals >= 2 && PFTotals <= 3,<br />
<br />
'Hard',<br />
<br />
if(PFTotals >= 4 && PFTotals <= 5,<br />
<br />
'Very Hard',<br />
<br />
''<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)}<br />
<br />
</syntaxhighlight><br />
<br />
Expression Manager supports the following syntax:<br />
*All standard mathematical operators (e.g. +,-,*,/,!)<br />
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)<br />
*Parentheses (so you can group sub-expressions)<br />
*Conditional operators (e.g. &&,| | and these equivalents: and,or)<br />
*Single and double-quoted strings (which can each embed strings with the other quote type)<br />
*Comma operator (so can have a list of expressions and just return the final result)<br />
*Assignment operator (=)<br />
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes<br />
*Pre-defined functions (there are already 70+, and it is easy to add more)<br />
<br />
EM syntax follows normal operator precedence:<br />
<br />
{|<br />
|Level||Operator(s)||Description<br />
|-<br />
|1||()||parentheses for grouping or calling functions<br />
|-<br />
|2||! - +||unary operators: not, negation, unary-plus<br />
|-<br />
|3||* /||times, divide<br />
|-<br />
|4||+ -||plus, minus<br />
|-<br />
|5||< <= > >= lt le gt ge||relative comparisons<br />
|-<br />
|6||== != eq ne||equality comparisons<br />
|-<br />
|7||and||logical AND<br />
|-<br />
|8||or||logical OR<br />
|-<br />
|9||=||assignment operator<br />
|-<br />
|10||,||comma operator<br />
|-<br />
|<br />
|}<br />
<br />
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).<br />
<br />
===Caution about using Assignment Operator (=)===<br />
<br />
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 sould 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.<br />
<br />
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 "==")<br />
<br />
The main reasons you may want to use assignment are:<br />
*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.<br />
*You need to forcibly change the response to a previous question based upon a later response<br />
<br />
==Access to Variables==<br />
<br />
Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:<br />
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5)<br />
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")<br />
*All {XXX} values used by templates<br />
<br />
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.<br />
<br />
Furthermore, Expression Manager lets you access many properties of the Question:<br />
<br />
{|<br />
|Syntax||Meaning||Example||Example Result<br />
|-<br />
|Qcode||an alias for Qcode.code||{join(',',name,gender)}||'Tom','M'<br />
|-<br />
|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||{join(',',name.code,gender.code)}||'Tom','M'<br />
|-<br />
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'<br />
|-<br />
|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'<br />
|-<br />
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'<br />
|-<br />
|Qcode.shown||the dispay value for the question||{join(',',name.shown,gender.shown)}||'Tom','Male'<br />
|-<br />
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'<br />
|-<br />
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'<br />
|-<br />
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337<br />
|-<br />
|Qcode.type||the question type||{gender.type}||'G'<br />
|-<br />
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'<br />
|-<br />
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3<br />
|-<br />
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5<br />
|-<br />
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1<br />
|-<br />
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus)||1<br />
|-<br />
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'<br />
|-<br />
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'<br />
|-<br />
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'<br />
|-<br />
|<br />
|}<br />
<br />
=== Security issue===<br />
<br />
For security issue, text entered by user are filtered. Some caracter are replaced by HTML entities.<br />
* & by &amp;<br />
* < by &lt;<br />
* > by &gt;<br />
* \n by &lt;br /&gt;<br />
* " by &quot;<br />
* ' by &amp;#39;<br />
* % by &amp;#37;<br />
* ( by &amp;#40;<br />
* ) by &amp;#41;<br />
* + by &amp;#43;<br />
* - by &amp;#45;<br />
<br />
==Qcode Variable Naming==<br />
<br />
Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:<br />
<br />
QuestionCode . '_' . AnswerID . '_' . ScaleId<br />
<br />
{|<br />
|Type||Description||Code||SubQs||Answer Options||Scales||Answer Code||Answer Shown||Relevance<br />
|-<br />
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}<br />
|-<br />
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}<br />
|-<br />
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}<br />
|-<br />
|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'}<br />
|-<br />
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}<br />
|-<br />
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}<br />
|-<br />
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}<br />
|-<br />
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}<br />
|-<br />
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}<br />
|-<br />
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}<br />
|-<br />
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||<br />
|-<br />
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||<br />
|-<br />
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}<br />
|-<br />
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}<br />
|-<br />
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}<br />
|-<br />
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}<br />
|-<br />
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}<br />
|-<br />
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}<br />
|-<br />
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}<br />
|-<br />
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20_comment}||{Q20.shown}||{Q20=='B'}<br />
|-<br />
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}<br />
|-<br />
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}<br />
|-<br />
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_D_comment}||{Q23_D.shown}||{!is_empty(Q23)}<br />
|-<br />
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}<br />
|-<br />
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q')}<br />
|-<br />
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}<br />
|-<br />
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}<br />
|-<br />
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}<br />
|-<br />
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}<br />
|-<br />
|<br />
|}<br />
<br />
==The reserved 'this', 'self', and 'that' variables==<br />
<br />
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.<br />
<br />
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).<br />
<br />
The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:<br />
*self<br />
*self.''suffix''<br />
*self.''sub-selector''<br />
*self.''sub-selector''.''suffix''<br />
<br />
''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)<br />
<br />
''sub-selector'' is one of:<br />
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)<br />
*nocomments - only subquestions that are not comments<br />
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected.<br />
<br />
Examples:<br />
*Has any part of a question been answered? {count(self.NAOK)>0}<br />
*What is the assessment score for this question? {sum(self.value)}<br />
<br />
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.<br />
*What is the grand total? {sum(self.NAOK)}<br />
*What is the total of row B? {sum(self.sq_B.NAOK)}<br />
*What is the total of column 3? {sum(self.sq_3.NAOK)}<br />
<br />
The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:<br />
*that.''qname''<br />
*that.''qname''.''suffix''<br />
*that.''qname''.''sub-selector''<br />
*that.''qname''.''sub-selector''.''suffix''<br />
<br />
''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''<br />
<br />
Examples:<br />
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}<br />
*What is the assessment score for q2? (sum(that.q2.NAOK)}<br />
*What is the grand total of q3? {sum(that.q3.NAOK)}<br />
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}<br />
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}<br />
<br />
The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.<br />
<br />
The one caveat is that when you use the 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'<br />
<br />
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.<br />
<br />
==Access to Functions==<br />
<br />
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.<br />
<br />
===Implemented Functions===<br />
<br />
The following functions are currently available:<br />
<br />
{|<br />
|Function||Meaning||Syntax<br />
|-<br />
[http://www.php.net/manual/en/function.abs.php ||abs]||Absolute value||number abs(number)<br />
|-<br />
[http://www.php.net/manual/en/function.acos.php ||acos]||Arc cosine||number acos(number)<br />
|-<br />
[http://www.php.net/manual/en/function.addslashes.php ||addslashes]||Quote string with slashes||string addslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.asin.php ||asin]||Arc sine||number asin(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan.php ||atan]||Arc tangent||number atan(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan2.php ||atan2]||Arc tangent of two variables||number atan2(number, number)<br />
|-<br />
[http://www.php.net/manual/en/function.ceil.php ||ceil]||Round fractions up||number ceil(number)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.cos.php ||cos]||Cosine||number cos(number)<br />
|-<br />
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)<br />
|-<br />
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)<br />
|-<br />
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.date.php ||date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[http://www.php.net/manual/en/function.exp.php ||exp]||Calculates the exponent of e||number exp(number)<br />
|-<br />
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)<br />
|-<br />
[http://www.php.net/manual/en/function.floor.php ||floor]||Round fractions down||number floor(number)<br />
|-<br />
[http://www.php.net/manual/en/function.gmdate.php ||gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.idate.php ||idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)<br />
|-<br />
[http://www.php.net/manual/en/function.implode.php ||implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)<br />
|-<br />
[http://www.php.net/manual/en/function.intval.php ||intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])<br />
|-<br />
[http://www.php.net/manual/en/function.empty.php ||is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.is-nan.php ||is_nan]||Finds whether a value is not a number||bool is_nan(var)<br />
|-<br />
[http://www.php.net/manual/en/function.is-null.php ||is_null]||Finds whether a variable is NULL||bool is_null(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.log.php ||log]||Natural logarithm||number log(number)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.max.php ||max]||Find highest value||number max(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.min.php ||min]||Find lowest value||number min(arg1, arg2, ... argN)<br />
|-<br />
[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 ]]]]]])<br />
|-<br />
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)<br />
|-<br />
[http://www.php.net/manual/en/function.nl2br.php ||nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)<br />
|-<br />
[http://www.php.net/manual/en/function.number-format.php ||number_format]||Format a number with grouped thousands||string number_format(number)<br />
|-<br />
|pi||Get value of pi||number pi()<br />
|-<br />
[http://www.php.net/manual/en/function.pow.php ||pow]||Exponential expression||number pow(base, exp)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.quotemeta.php ||quotemeta]||Quote meta characters||string quotemeta(string)<br />
|-<br />
[http://www.php.net/manual/en/function.rand.php ||rand]||Generate a random integer||int rand() OR int rand(min, max)<br />
|-<br />
|regexMatch||compare a string to a [[Using regular expressions||regular expression]]||bool regexMatch(pattern,input)<br />
|-<br />
[http://www.php.net/manual/en/function.round.php ||round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.sin.php ||sin]||Sine||number sin(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.sprintf.php ||sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.sqrt.php ||sqrt]||Square root||number sqrt(arg)<br />
|-<br />
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.str-repeat.php ||str_repeat]||Repeat a string||string str_repeat(input, multiplier)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.strcasecmp.php ||strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)<br />
|-<br />
[http://www.php.net/manual/en/function.strcmp.php ||strcmp]||Binary safe string comparison||int strcmp(str1, str2)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.stripos.php ||stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.stripslashes.php ||stripslashes]||Un-quotes a quoted string||string stripslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.stristr.php ||stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])<br />
|-<br />
[http://www.php.net/manual/en/function.strlen.php ||strlen]||Get string length||int strlen(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strpos.php ||strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.strrev.php ||strrev]||Reverse a string||string strrev(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strstr.php ||strstr]||Find first occurrence of a string||string strstr(haystack, needle)<br />
|-<br />
[http://www.php.net/manual/en/function.strtolower.php ||strtolower]||Make a string lowercase||string strtolower(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strtoupper.php ||strtoupper]||Make a string uppercase||string strtoupper(string)<br />
|-<br />
[http://www.php.net/manual/en/function.substr.php ||substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])<br />
|-<br />
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)<br />
|-<br />
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.tan.php ||tan]||Tangent||number tan(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.time.php ||time]||Return current UNIX timestamp||number time()<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.ucwords.php ||ucwords]||Uppercase the first character of each word in a string||string ucwords(string)<br />
|-<br />
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)<br />
|-<br />
|<br />
|}<br />
<br />
===Functions that are Planned or Being Considered===<br />
<br />
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.<br />
<br />
{|<br />
|Syntax||Meaning||Comments<br />
|-<br />
|e()||returns the value of e||<br />
|-<br />
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||<br />
|-<br />
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||<br />
|-<br />
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown<br />
|-<br />
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||<br />
|-<br />
|getRelevance(X)||returns the relevance equation for question X||<br />
|-<br />
|getStartTime()||returns the date corresponding to the system time when the interview was started||<br />
|-<br />
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||<br />
|-<br />
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||<br />
|-<br />
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||<br />
|-<br />
|isInvalid(X)||returns true if the answer is of type *INVALID*||<br />
|-<br />
|isNA(X)||returns true if the answer is of type *NA*||<br />
|-<br />
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||<br />
|-<br />
|isRefused(X)||returns true if the answer is of type *REFUSED*||<br />
|-<br />
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||<br />
|-<br />
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||<br />
|-<br />
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||<br />
|-<br />
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||<br />
|-<br />
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||<br />
|-<br />
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||<br />
|-<br />
|mean(X,...)||returns the mean of a list of values||<br />
|-<br />
|numAnsOptions(X)||returns the number of answer options that question X has||<br />
|-<br />
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||<br />
|-<br />
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||<br />
|-<br />
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||<br />
|-<br />
|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.||<br />
|-<br />
|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.||<br />
|-<br />
|<br />
|}<br />
<br />
==Expression Manager Knows Which Variables are Local==<br />
<br />
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).<br />
<br />
==Cascading Conditions==<br />
<br />
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<br />
<br />
{|<br />
|Operator||Example||a||b||Result<br />
|-<br />
|+ (unary)||+a||N/A|| ||false<br />
|-<br />
|- (unary)||-a||N/A|| ||false<br />
|-<br />
|!||!a||N/A|| ||false<br />
|-<br />
|== (or eq)||a == b||N/A||5||false<br />
|-<br />
|== (or eq)||a == b||N/A||0||false<br />
|-<br />
|== (or eq)||a == b||N/A||N/A||false<br />
|-<br />
|!= (or ne)||a != b||N/A||5|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||N/A|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||0||false<br />
|-<br />
|> (or gt)||a > b||N/A||5|| false<br />
|-<br />
|>= (or ge)||a >= b||N/A||5||false<br />
|-<br />
|< (or lt)||a < b||N/A||5||false<br />
|-<br />
|<= (or le)||a <= b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||5||false<br />
|-<br />
|+||a + b||N/A||5||false<br />
|-<br />
|-||a - b||N/A||5||false<br />
|-<br />
|*||a * b||N/A||5||false<br />
|-<br />
|/||a / b||5||N/A||false<br />
|-<br />
|()||(a)||N/A|| ||false<br />
|-<br />
|(exp)||(a && b)||N/A||5||false<br />
|-<br />
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false<br />
|-<br />
|function||sum(a,b,b)||N/A||5||false<br />
|-<br />
|function||max(a,b)||N/A||5||false<br />
|-<br />
|function||min(a,b)||N/A||5||false<br />
|-<br />
|function||implode(', ',a,b,a,b)||N/A||5||false<br />
|-<br />
|function||if(a,a,b)||N/A||5||false<br />
|-<br />
|function||is_empty(a)||N/A|| ||false<br />
|-<br />
|function||is_empty(a)||0 (or blank)|| ||true<br />
|-<br />
|function||!is_empty(a)||N/A|| ||false<br />
|-<br />
|<br />
|}<br />
<br />
===Overriding Cascading Conditions===<br />
<br />
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.<br />
<br />
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<br />
#q1 is not added to the LEManyNA() clause<br />
#LEMval('q1') will continue to check whether the response is relevant, and will return '' if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression.<br />
<br />
So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).<br />
<br />
The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converage 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.<br />
<br />
==How does Expression Manager Support Conditional Micro-Tailoring?==<br />
<br />
Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):<br />
<br />
{|<br />
|Question Code||Relevance||Question Type||Question<br />
|-<br />
|name||1||text||What is your name?<br />
|-<br />
|age||1||text||How old are you?<br />
|-<br />
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}<br />
|-<br />
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.<br />
|-<br />
|kids||!badage||yesno||Do you have children?<br />
|-<br />
|parents||1||expr||{!badage && kids=='Y'}<br />
|-<br />
|numKids||parents||text||How many children do you have?<br />
|-<br />
|kid1||parents && numKids >= 1||text||How old is your first child?<br />
|-<br />
|kid2||parents && numKids >= 2||text||How old is your second child?<br />
|-<br />
|kid3||parents && numKids >= 3||text||How old is your third child?<br />
|-<br />
|kid4||parents && numKids >= 4||text||How old is your fourth child?<br />
|-<br />
|kid5||parents && numKids >= 5||text||How old is your fifth child?<br />
|-<br />
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}<br />
|-<br />
|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}<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==<br />
<br />
{|<br />
|Old Feature||New Feature||Comments<br />
|-<br />
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables<br />
|-<br />
|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<br />
|-<br />
|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\})<br />
|-<br />
|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<br />
|-<br />
|<br />
|}<br />
<br />
=Syntax Highlighting=<br />
<br />
To help with entering and validating expressions, EM provides syntax highlighting with the following features:<br />
<br />
==Types and Meanings of Syntax Highlighting==<br />
<br />
{|<br />
|Color||Sample||Meaning||Tooltip||Comments<br />
|-<br />
|tan background||<span style='color:#eee8aa,#eee8aa'>Sample</span>||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<br />
|-<br />
|blue bold text||'''<span style='color:blue,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|grey text||<span style='color:grey,#eee8aa'>'Sample'</span>||string||none||single and double-quoted strings are shown in grey text<br />
|-<br />
|bold maroon text||'''<span style='color:maroon,#eee8aa'>Sample</span>'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. 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.<br />
|-<br />
|bold cyan text||'''<span style='color:#4C88BE,#eee8aa'>Sample</span>'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan 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.<br />
|-<br />
|bold green text||'''<span style='color:green,#eee8aa'>Sample</span>'''||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 pageis 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.<br />
|-<br />
|bold pink text||'''<span style='color:#FF00FF,#eee8aa'>Sample</span>'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior pageis 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.<br />
|-<br />
|bold tan text||'''<span style='color:#996600,#eee8aa'>Sample</span>'''||a lime relacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE} are shown in bold tan text. The tooltip shows the current value.<br />
|-<br />
|red text||'''<span style='color:red,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|normal black text||<span style='color:black,#eee8aa'>Sample</span>||punctuation||none||All other punctionation within the expression is shown as normal black text.<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
=Relationship to LimeSurvey Ideas / Feature Requests=<br />
<br />
Expression Manager provides complete or partial solutions to each of the following:<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1 Conditions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/3/ Answercounts]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/5 Advanced reporting for assessments]<br />
**partial: Equations let one store the Assessment value in the database, and micro-tailoring can generate simple formatted reports. Authors can access those Equation values if they have more complex reporting needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/6 Assessment reports]<br />
**partial: Since Equations store the Assessment score, it should be possible to use Statistics to show distributions of those scores, and Quotas to limit the number of responses with those scores.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/7 Store assessment results for further evaluation]<br />
**Equations let one store the Assessment value in the database, completely solving this problem<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/22/ More advanced condition rules]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/28 Open Answertable up so that we can alter formatting]<br />
**partial: All of the question attributes are available, so authors can create custom AnswerTable equivalents as a Question. Once implatemented, they can also use the showTheseResponses() or showAllResponsesExecpt() functions<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/37 Export survey results with full questions to include images]<br />
**since Tailoring has access to the full question text, it can include images in the export<br />
**if subjects choose Print Your Answers after finishing the survey, those printouts will be fully tailored<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/63 List of question codes and SGQA identifiers]<br />
**The Show Survey Logic view shows that mapping (plus much more information)<br />
**In addition, you no longer have to use SGQA codes to refer to variables - you can use the Question code/title.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/69 Branch/jump to another question (earlier or later) based on current question]<br />
**You can use the Navigation Index for this in most cases<br />
**Once implemented, you can use the JumpTo() function. Like the Navigation Index, if you try to jump forward, it will stop on an intervening page if there are any of the relevant mandatory questions are unanswered, or if any relevant questions fail validation tests.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/86 set quota for total responses]<br />
**If the final question is an Equation that flags a survey as completed (so is NULL if a respondant does not get to that page), you can use Quotas on that question to control the number of completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/101 Review all conditions]<br />
**The Show Logic File view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/105 Review all questions + Review all groups]<br />
**The Show Logic File view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/107 How to visualize questions, logic & conditions]<br />
**The Show Logic File view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/113 Offline Surveys]<br />
**Running a survey with all of the questions on the same page would let you do off-line data collection (e.g. email the html page and associated JavaScript). However, you would still want a way to submit the results so that they did not get lost. It may be possible to use Save As HTML to save partially completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/120 Remove INSERTANS from question text at survey results]<br />
**INSERTANS is no longer needed. You can refer to a variable by its SGQA code (without prefixing it with INSERTANS:), or by its question code.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/137 Informed Consent and Authorization Functionality]<br />
**You can show show the informed consent on the welcome page, then ask any additional questions needed (to ensure they meet the study inclusion/exclusion criteria), and ask them a Yes/No question whether they give their consent. Then, make all of the remaining questions conditional on that yesNo. For example, if the question is named ''consent'', you would set the relevance to the remaining questions to ''consent == "Y"'' (possibly ''and''ing that with whatever additional conditions you needed to support your branching needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/199 Show codes instead of of answers using INSERTANS]<br />
**{Qcode} returns the code instead of the response text (which you can get via {INSERTANS:SGQA}, or {Qcode.shown}<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/204 Need group mean or calculations for assessments]<br />
**Say you have N variables of which N-X were answered, you could compute the mean of the answered variables as {sum(var1, var2, ..., varN) / count(var1, var2, ..., varN)}<br />
**Computing the mean across a set of respondants would require extension of the Quota functionality.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/222 To insert a language dependent text]<br />
**Tailoring lets you conjugate verbs and decline nouns in each language<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/225 Surveyors should approve their answers]<br />
**Custom Questions with tailoring, or the showAllResponsesExcept() function will let Surveyors see all of the questions and responses before clicking Submit. If the Navigation Menu option is enabled, it is easy to go back and correct answers.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Suppliment to #answernnXnnXnnn method of targetting form elements]<br />
**You can now refer to questions and answers by their Question Code, so there is no longer a need to modify SGQA values.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/262 More flexibility with hidden questions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/265 Remove specific conditions from multiple questions]<br />
**You can now use Relevance, which is easier to manage than Conditions. If needed, they can all be exported from the database, edited in a spreadsheet, and re-imported.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/268 Cross Survey Reporting]<br />
**By using question codes that are unique across your surveys and versions, you can consolidate data from multiple surveys and/or compare them<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/275 Simplifying integration with other tools]<br />
**Expression Manager uses Question Codes instead of SGQA, making it easier to integrate with other tools.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Expose assessment score to 3rd party app processing]<br />
**This can be done with Equation question type<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/309 Multiple thank you pages]<br />
**This can be supported via conditional relevance branching and tailoring<br />
<br />
=Additional Reading=<br />
<br />
==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==<br />
<br />
==[[Expression Manager HowTos|Use Cases and HowTos]]==<br />
<br />
==[[Expression Manager Examples|Step-by-Step Examples]].==<br />
<br />
==[[Expression Manager for developers|Reference for Developers]]==<br />
<br />
==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Expression_Manager&diff=1021Expression Manager2012-12-20T08:35:36Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
<div class="simplebox"> Note: This feature is only available in LimeSurvey 1.92 or later. </div><br />
<br />
=Quick Start Tutorial=<br />
<br />
==Overview==<br />
<br />
When customizing your surveys, you typically need a way to specify the following:<br />
#'''Navigation/Branching''' - letting a subject's answers change the order in which questions are asked<br />
#'''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).<br />
#'''Validation''' - ensuring that answers pass certain criteria, like min and max values, or matching an input pattern<br />
<br />
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).<br />
<br />
The following sections show the main places where Expression Manager is used<br />
<br />
==Relevance (Controlling Navigation/Branching)==<br />
<br />
Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses an Boolean relevance equation to specify all of the conditions under which a question might be valid. If the question is relevant, then the question is asked, otherwise it is Not Applicable, and the value NULL is stored in the database. This is similar to what can be done via the Conditions editor, but EM lets you easily specify much more complex and powerful criteria (and lets you use the variable name rather than SGQA naming).<br />
<br />
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, weight_kg 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).<br />
<br />
[[File:tutorial1.jpg]]<br />
<br />
Relevance is shown and editable in the following places:<br />
<br />
===Viewing / Editing Question-Level Relevance===<br />
<br />
This equation computes the Body Mass Index (BMI). It is only asked if the person first enters their height and weight.<br />
<br />
[[File:tutorial2.jpg]]<br />
<br />
This is the edit screen for the BMI question.<br />
<br />
[[File:tutorial3.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
===Viewing / Editing Group-Level Relevance===<br />
<br />
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).<br />
<br />
[[File:tutorial4.jpg]]<br />
<br />
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.<br />
<br />
Here is the screen for editing the group-level relevance for that question:<br />
<br />
[[File:tutorial5.jpg]]<br />
<br />
Note that you do not use the curly braces when you enter a Relevance Equation.<br />
<br />
==Tailoring/Piping==<br />
<br />
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.<br />
<br />
===Conditional Equations===<br />
<br />
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.<br />
<br />
[[File:tailoring7.jpg]]<br />
<br />
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.<br />
<br />
BMI computes the weight formula as {weight_kg / (height_m * height_m)}.<br />
<br />
Lastly, the report conditionally tailors the message for the subject, telling him what he entered (e.g. "You said you are 2 meters tall and weight 70 kg."<br />
<br />
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<br />
<br />
[[File:tailoring8.jpg]]<br />
<br />
From the edit window for this question, you can see two things:<br />
#Tailoring must surround expressions with Curly Braces<br />
#Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.<br />
<br />
[[File:tailoring9.jpg]]<br />
<br />
===Tailored Questions, Answers, and Reports===<br />
<br />
<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 <span> tag which is not valid inside select options.</div><br />
<br />
This example shows the BMI report.<br />
<br />
[[File:tailoring10.jpg]]<br />
<br />
Here is the edit window for the same question.<br />
<br />
[[File:tailoring11.jpg]]<br />
<br />
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.<br />
<br />
[[File:tailoring12.jpg]]<br />
<br />
You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
In all of these cases, since the advanced question option is always considered an expression, you do not use curly braces when specifying it.<br />
<br />
The [[Expression Manager Sample Surveys|Sample Surveys]] pages shows many working examples of using expressions for validations.<br />
<br />
=Introduction=<br />
<br />
LimeSurvey 1.92 and later 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).<br />
<br />
This wiki page is the definitive reference for Expression Manager syntax and functionality.<br />
<br />
==Key Definitions==<br />
#'''Expression''': Anything surrounded by curly braces<br />
**As long as there is no white space immediately after the opening brace or before the closing curly brace<br />
**The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.<br />
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text<br />
**You have access to all 'replacement fields', TOKENs, and INSERTANS values<br />
**You also have easier access to questions, answers, and their properties.<br />
#'''Relevance''' Equation: A new question attribute controlling question visiblity<br />
**If there is a relevance equation, then the question is only shown if the relevance evaluates to true.<br />
**Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance<br />
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database<br />
**It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"<br />
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+<br />
**Stands for Survey-Group-Question-Answer<br />
**SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.<br />
**These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed<br />
#'''Question Code''': This is the preferred variable name for EM<br />
**This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic<br />
**Although not required to be unique in <= 1.91+, it must be unique if you want to use EM<br />
**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".<br />
**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.<br />
<br />
==Do I have to use EM?==<br />
<br />
The short answer is No (but also yes).<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Can I mix use of Conditions and Relevance?==<br />
<br />
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.<br />
<br />
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.<br />
<br />
==How should I choose between Conditions and Relevance?==<br />
<br />
Here is a list of pros and cons of each style:<br />
<br />
{|<br />
|Style||Pros||Cons<br />
|-<br />
|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<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
The bottom is that if you are happy with how LimeSurvey 1.91+ works, there is no reason to change what you do.<br />
<br />
==What are some other benefits of using EM?==<br />
<br />
Here are some of the other reasons you might want to use EM.<br />
#Calculations - you can create any calculation you can think of:<br />
**You have access to all common mathematical operators and functions<br />
**You have access to 70+ mathematical, date, and string processing functions<br />
**It is fairly easy for developers to add new functions if users need them<br />
#Storing Calculations to Database<br />
**You can now compute simple and complex calculations and/or scale scores AND have them stored in the database without needing JavaScript.<br />
**You use the Equation question type to accomplish this.<br />
#Assessments<br />
**You can now create assessments or scale scores from any question type, not just the subset that used to be supported<br />
**You can use Tailoring to show running or total assessment scores anywhere needed - even on the same page<br />
**You have more control over the reports generated based upon those assessment scores<br />
**You can store assessment scores in the database without needing JavaScript<br />
**You can hide assessment scores without needing JavaScript or CSS<br />
#Replacement Fields<br />
**Instead of using {INSERTANS:SGQA}, you can just use the Question Code - this makes it easier to read and validate.<br />
**This also avoids the common need to edit questions to change the SGQA code to make everything work.<br />
#Tailoring - you can conditionally display text based upon other values<br />
**Use the appropriate title for a subject, like (e.g. "Hello <nowiki>[</nowiki>Mr./Mrs.] Smith")<br />
**Output gramatically correct sentences based when singular/plural matter: (e.g. "You have 1 child" vs. "You have 2 chldren")<br />
**Appropriately conjugate verbs and decline nouns based upon subject's gender and plurality.<br />
#New Variable Attributes - you can access the following to do your tailoring:<br />
** (no suffix) - an alias for qcode.code<br />
**.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<br />
**.NAOK - same as .code, but can be part of calculations or lists even if irrelevant<br />
**.value - the assessment value for the question if it is relevant (otherwise blank), or the text value if it is not a coded question<br />
**.valueNAOK - same as .value, but can be part of calculations or lists even if irrelevant<br />
**.shown - the answer as displayed to the user (this is what {INSERTANS:xxx} does)<br />
**.qid - the question ID<br />
**.gid - the group ID<br />
**.sgqa - the SGQA value for the question<br />
**.jsName - the correct javascript variable name for the question, regardless whether defined on this page or another<br />
**.qseq - the question sequence (starting from 0)<br />
**.gseq - the group sequence (starting from 0)<br />
**.mandatory - whether the question is mandatory (Y/N)<br />
**.question - the text of the question<br />
**.relevance - the relevance equation for the question<br />
**.grelevance - the relevance equation for the group<br />
**.relevanceStatus - whether or not the question is currently relevant (1 if true, 0 if false)<br />
**.type - the question type (the one character code)<br />
#Dynamic On-Page Changes<br />
**All Relevance, Calculation, and Tailoring works dynamically on a page - so changes in values instantly update the page<br />
**So, you have questions dynamically appear/disappear based upon whether they are relevant<br />
**Questions are also dynamically tailored based upon responses on the page, so you can see running totals, tailored sentences and customized reports.<br />
#New Data Entry Screen<br />
**In addition to using the current data-entry system, you can just use Survey-All-In-One.<br />
**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<br />
**This can be critical if your data entry person needs to see the tailoring, which is also dynamic.<br />
#Eliminates the need for most custom JavaScript<br />
**EM easily supports complicated computations, scoring, tailoring and conditional logic.<br />
**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.<br />
<br />
==What are some other helpful new features enabled by EM?==<br />
<br />
Regardless of whether you continue to use the Conditions Editor or manually compose Relevance Equations, you get these additional benefits:<br />
#You can create more complex validation criteria<br />
**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.<br />
**EM also handles all regular-expression-based validation, so you can robustly combine preg and equation-based question attributes.<br />
#Easy Re-ordering (or deleting) of Questions and Groups<br />
**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.<br />
**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.<br />
**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).<br />
#The Question/Group Navigation Index is always available and accurate<br />
**Prior to version 1.92, these indexes were not available if there were complex conditions<br />
**With EM, we can guarantee that they are accurate.<br />
**Subjects can even jump back, to a prior question, change the answer, then jump forward (or submit)<br />
***When jumping forwards, EM will re-validate all of the intervening questions/groups.<br />
***If any questions become irrelevant, they will be NULLed in the database so that your data is internally consistent<br />
***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.<br />
#Auto-conversion of Conditions to Relevance<br />
**When you upgrade your database, all existing surveys that have conditions will have relevance equations generated for them<br />
**Whenever you import a survey, relevance equations will be created as needed<br />
**Whenever you add, delete, or modify conditions, EM will generate the appropriate relevance equation.<br />
#Convenient Syntax Highlighting<br />
**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.<br />
**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.<br />
**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).<br />
***The list of answer choices uses this syntax: 'answers':{key:val, ... }.<br />
***''key'' has the syntax ''''scale~code'''' where ''scale'' is the answer scale (e.g. for dual scale), and ''code'' is the answer code.<br />
***''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)<br />
***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).<br />
#Easy review of entire survey logic and content<br />
**There is a new Show Survey Logic feature that lets you see everything about the survey (or group or question) on a single page.<br />
**It shows the Group, Question, Sub-Question, and Answer-level details for the selected scope (survey vs. group vs. question)<br />
**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.<br />
**Eveything is syntax-highlighted so that you can see potential syntax errors (like unbalanced parentheses or use of variables before they were declared)<br />
**The syntax-highligting supports rapid navigation and editing of the survey.<br />
***If you click on a variable name, it opens a browser window (or tab) that shows you that question and lets you edit it.<br />
***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.<br />
***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)<br />
**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<br />
<br />
==How Backwards Compatible is EM with 1.91+?==<br />
<br />
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+.<br />
<br />
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 Survey Logic File view to quickly identify and fix any such comparisons in your survey.<br />
<br />
=Getting Started=<br />
<br />
The best way to get started with EM is to:<br />
*Install 1.92+ from http://www.limesurvey.org/en/download .<br />
*Import and explore the [[Expression Manager Sample Surveys|sample surveys]].<br />
*Explore the [[Expression Manager HowTos|use cases and HowTos]] and [[Expression Manager Examples|step-by-step examples]].<br />
*Explore the EM documentation (this page)<br />
*Examine the built-in EM test suite<br />
**From any survey, under tools, select the EM option<br />
**Availalbe Functions lists the 70+ functions and syntax<br />
**Unit Tests of Isolsted Expressions<br />
***shows examples of using all EM functions and operators, and the PHP and JavaScript results<br />
***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.<br />
<br />
=What Functionality does Expression Manager Extend/Replace? (LimeSurvey <= 1.91+)=<br />
<br />
==Conditions => Relevance==<br />
<br />
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.<br />
<br />
==Assessments => Equations and Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Replacements => Micro-Tailoring==<br />
<br />
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.<br />
<br />
==Validation==<br />
<br />
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.<br />
<br />
==Equations==<br />
<br />
Equations were not supported without fancy JavaScript.<br />
<br />
==Equation Question Type==<br />
<br />
Equations could not be saved to the database (e.g. the final score for an assessment) without fancy JavaScript.<br />
<br />
=How Will Expression Manager Replace/Extend That Functionality?=<br />
<br />
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.<br />
<br />
==New Terminology When Referring to Expression Manager (EM)==<br />
<br />
EM "thinks" of its functionality in the following terms:<br />
*'''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).<br />
*'''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.<br />
*'''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.<br />
<br />
===Relevance and Cascading Relevance===<br />
<br />
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 diplayed. 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.<br />
<br />
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.<br />
<br />
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:<br />
<br />
{|<br />
|Question Code||Relevance||Question<br />
|-<br />
|Q1||1||What is your name?<br />
|-<br />
|Q2||Q1||{Q1}, how old are you?<br />
|-<br />
|Q3||Q2||So, you are {Q2} years old. Are you married?<br />
|-<br />
|Q4||Q3 == "Y"||{Q1}, how long have you been married?<br />
|-<br />
|Q5||Q4||How many children do you have, {Q1}?<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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 and 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.<br />
<br />
===Group-Level Relevance===<br />
<br />
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 deterimine 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.<br />
<br />
===Tailoring / Piping===<br />
<br />
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).<br />
<br />
Using these equations, you can do things such as:<br />
#Conditionally show tailored messages to the respondants based upon prior responses<br />
#Create Assessments and show Assessment results (or conditionally branch or show messages) based upon those results, all without using the Assessments module itself<br />
#Conjugate verbs and decline nouns within questions, answers, and reports.<br />
#Show summaries of responses before the "Show your answers" page at the end of the survey<br />
<br />
===Equations===<br />
<br />
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.<br />
<br />
This solves a common request for storing Assessment scores within the database<br />
<br />
==Syntax==<br />
<br />
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).<br />
<br />
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:<br />
<br />
<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),<br />
<br />
'',<br />
<br />
if(PFTotals >= -5 && PFTotals <= -4,<br />
<br />
'Very Soft',<br />
<br />
if(PFTotals >= -3 && PFTotals <= -2,<br />
<br />
'Soft',<br />
<br />
if(PFTotals == -1,<br />
<br />
'Somewhat Soft',<br />
<br />
if(PFTotals == 0,<br />
<br />
'Moderate',<br />
<br />
if(PFTotals == 1,<br />
<br />
'Somewhat Hard',<br />
<br />
if(PFTotals >= 2 && PFTotals <= 3,<br />
<br />
'Hard',<br />
<br />
if(PFTotals >= 4 && PFTotals <= 5,<br />
<br />
'Very Hard',<br />
<br />
''<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)<br />
<br />
)}<br />
<br />
</syntaxhighlight><br />
<br />
Expression Manager supports the following syntax:<br />
*All standard mathematical operators (e.g. +,-,*,/,!)<br />
*All standard comparison operators (e.g. <,<=,==,!=,>,>=, plus these equivalents: lt,le,eq,ne,gt,ge)<br />
*Parentheses (so you can group sub-expressions)<br />
*Conditional operators (e.g. &&,| | and these equivalents: and,or)<br />
*Single and double-quoted strings (which can each embed strings with the other quote type)<br />
*Comma operator (so can have a list of expressions and just return the final result)<br />
*Assignment operator (=)<br />
*Pre-defined variables (to refer to questions, question attributes, and responses) - e.g. all of the SGQA codes<br />
*Pre-defined functions (there are already 70+, and it is easy to add more)<br />
<br />
EM syntax follows normal operator precedence:<br />
<br />
{|<br />
|Level||Operator(s)||Description<br />
|-<br />
|1||()||parentheses for grouping or calling functions<br />
|-<br />
|2||! - +||unary operators: not, negation, unary-plus<br />
|-<br />
|3||* /||times, divide<br />
|-<br />
|4||+ -||plus, minus<br />
|-<br />
|5||< <= > >= lt le gt ge||relative comparisons<br />
|-<br />
|6||== != eq ne||equality comparisons<br />
|-<br />
|7||and||logical AND<br />
|-<br />
|8||or||logical OR<br />
|-<br />
|9||=||assignment operator<br />
|-<br />
|10||,||comma operator<br />
|-<br />
|<br />
|}<br />
<br />
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).<br />
<br />
===Caution about using Assignment Operator (=)===<br />
<br />
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 sould 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.<br />
<br />
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 "==")<br />
<br />
The main reasons you may want to use assignment are:<br />
*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.<br />
*You need to forcibly change the response to a previous question based upon a later response<br />
<br />
==Access to Variables==<br />
<br />
Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:<br />
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5)<br />
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")<br />
*All {XXX} values used by templates<br />
<br />
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.<br />
<br />
Furthermore, Expression Manager lets you access many properties of the Question:<br />
<br />
{|<br />
|Syntax||Meaning||Example||Example Result<br />
|-<br />
|Qcode||an alias for Qcode.code||{join(',',name,gender)}||'Tom','M'<br />
|-<br />
|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||{join(',',name.code,gender.code)}||'Tom','M'<br />
|-<br />
|Qcode.NAOK||same as Qcode - see discussion of NAOK||{gender.NAOK}||'M'<br />
|-<br />
|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'<br />
|-<br />
|Qcode.valueNAOK||same as Qcode.value - see discussion about NAOK||{gender.valueNAOK}||'1'<br />
|-<br />
|Qcode.shown||the dispay value for the question||{join(',',name.shown,gender.shown)}||'Tom','Male'<br />
|-<br />
|Qcode.question||the text of the question||{gender.question}||'What is your gender?'<br />
|-<br />
|Qcode.mandatory||whether the question is mandatory (Y/N)||{gender.mandatory}||'N'<br />
|-<br />
|Qcode.qid||the internal question number (not the sequential number)||{gender.qid}||337<br />
|-<br />
|Qcode.type||the question type||{gender.type}||'G'<br />
|-<br />
|Qcode.jsName||the correct javascript name for the question, regardless whether declared on or off this page||{gender.jsName}||'java1827X3X337'<br />
|-<br />
|Qcode.gid||the internal group number (not the sequential number)||{gender.gid}||3<br />
|-<br />
|Qcode.qseq||the sequential number of the question, starting from 0||{gender.qseq}||5<br />
|-<br />
|Qcode.gseq||the sequential number of the group, starting from 0||{gender.gseq}||1<br />
|-<br />
|Qcode.relevanceStatus||whether the question is currently relevant (0 or 1)||{gender.relevanceStatus)||1<br />
|-<br />
|Qcode.relevance||the question-level relevance equation||{gender.relevance}||'!is_empty(name)'<br />
|-<br />
|Qcode.grelevance||the group-level relevance equation||{gender.grelevance}||'num_children >= 5'<br />
|-<br />
|Qcode.sgqa||the SGQA value for this question||{gender.sgqa}||'1827X3X337'<br />
|-<br />
|<br />
|}<br />
<br />
For security issue, text entered by user are filtered. Some caracter are replaced by HTML entities.<br />
* & by &amp;<br />
* < by &lt;<br />
* > by &gt;<br />
* \n by &lt;br /&gt;<br />
* " by &quot;<br />
* ' by &amp;#39;<br />
* % by &amp;#37;<br />
* ( by &amp;#40;<br />
* ) by &amp;#41;<br />
* + by &amp;#43;<br />
* - by &amp;#45;<br />
<br />
==Qcode Variable Naming==<br />
<br />
Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:<br />
<br />
QuestionCode . '_' . AnswerID . '_' . ScaleId<br />
<br />
{|<br />
|Type||Description||Code||SubQs||Answer Options||Scales||Answer Code||Answer Shown||Relevance<br />
|-<br />
|5||5 Point Choice Radio-Buttons||Q1|| ||1-5|| ||{Q1}||{Q1.shown}||{Q1==3}<br />
|-<br />
|B||Array (10 Point Choice) Radio-Buttons||Q2||L1-L6||1-10|| ||{Q2_L2}||{Q2_L2.shown}||{Q2_L2==7}<br />
|-<br />
|A||Array (5 Point Choice) Radio-Buttons||Q3||1-5||1-5|| ||{Q3_1}||{Q3_1.shown}||{Q3_1>=3}<br />
|-<br />
|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'}<br />
|-<br />
|H||Array (Flexible) - Column Format||Q5||1-5||s,m,t|| ||{Q5_1}||{Q5_1.shown}||{Q5_1=='s'}<br />
|-<br />
|F||Array (Flexible) - Row Format||Q6||F1-F5||1-5|| ||{Q6_F3}||{Q6_F3.shown}||{Q6_F3==4}<br />
|-<br />
|E||Array (Increase/Same/Decrease) Radio-Buttons||Q7||1-7||I,S,D|| ||{Q7_4}||{Q7_4.shown}||{Q7_4=='D'}<br />
|-<br />
|:||Array (Multi Flexi) 1 To 10||Q8||ls1,todo,ls2||min,max,avg|| ||{Q8_ls1_max}||{Q8_ls2_avg.shown}||{Q8_ls2_min==7}<br />
|-<br />
|;||Array (Multi Flexi) Text||Q9||hp,st,sw||1st,2nd,3rd|| ||{Q9_hp_3rd}||{Q9_hp_3rd.shown}||{Q9_hp_3rd=='Peter'}<br />
|-<br />
|C||Array (Yes/Uncertain/No) Radio-Buttons||Q10||1-5||Y,N,U|| ||{Q10_1}||{Q10_1.shown}||{Q10_3=='Y'}<br />
|-<br />
|X||Boilerplate Question||Q11|| || || || ||{Q11.shown}||<br />
|-<br />
|D||Date||Q12|| || || ||{Q12}||{Q12.shown}||<br />
|-<br />
|*||Equation||Q13|| || || ||{Q13}||{Q13.shown}||{Q13>5}<br />
|-<br />
|~124~||File Upload (records number of files uploaded)||Q14|| || || ||{Q14}|| ||{Q14>0}<br />
|-<br />
|G||Gender Drop-Down List||Q15|| ||M,F|| ||{Q15}||{Q15.shown}||{Q15=='M'}<br />
|-<br />
|U||Huge Free Text||Q16|| || || ||{Q16}||{Q16.shown}||{strlen(Q16)>100}<br />
|-<br />
|I||Language Question||Q17|| || || ||{Q17}||{Q17.shown}||{Q17=='en'}<br />
|-<br />
|!||List - Dropdown||Q18|| ||1-5|| ||{Q18}||{Q18.shown}||{Q18==3}<br />
|-<br />
|L||List Drop-Down/Radio-Button List||Q19|| ||A-Z|| ||{Q19}||{Q19.shown}||{Q19=='X'}<br />
|-<br />
|O||List With Comment Drop-Down/Radio-Button List + Textarea||Q20|| ||A-F|| ||{Q20},{Q20_comment}||{Q20.shown}||{Q20=='B'}<br />
|-<br />
|T||Long Free Text||Q21|| || || ||{Q21}||{Q21.shown}||{strstr(Q21,'hello')>0}<br />
|-<br />
|M||Multiple Choice Checkbox||Q22||A-F|| || ||{Q22_E}||{Q22_E.shown}||{Q22_E=='Y'}<br />
|-<br />
|P||Multiple Choice With Comments Checkbox + Text||Q23||A-F|| || ||{Q23_D}, {Q23_D_comment}||{Q23_D.shown}||{!is_empty(Q23)}<br />
|-<br />
|K||Multiple Numerical Question||Q24||self,mom,dad|| || ||{Q24_self}||{Q24_self.shown}||{Q24_self>30}<br />
|-<br />
|Q||Multiple Short Text||Q25||A-F|| || ||{Q25_B}||{Q25_B.shown}||{substr(Q25_B,1,1)=='Q')}<br />
|-<br />
|N||Numerical Question Type||Q26|| || || ||{Q26}||{Q26.shown}||{Q26 > 30}<br />
|-<br />
|R||Ranking Style||Q27||1-4|| || ||{Q27_1}||{Q27_1.shown}||{Q27_1==3}<br />
|-<br />
|S||Short Free Text||Q28|| || || ||{Q28}||{Q28.shown}||{Q28=='mine'}<br />
|-<br />
|Y||Yes/No Radio-Buttons||Q29|| || || ||{Q29}||{Q29.shown}||{Q29=='Y'}<br />
|-<br />
|<br />
|}<br />
<br />
==The reserved 'this', 'self', and 'that' variables==<br />
<br />
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.<br />
<br />
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).<br />
<br />
The 'self' and 'that' variable are more powerful, and serve as macros which are expanded prior to processing equations. The syntax choices are:<br />
*self<br />
*self.''suffix''<br />
*self.''sub-selector''<br />
*self.''sub-selector''.''suffix''<br />
<br />
''suffix'' is any of the normal qcode suffixes (e.g. NAOK, value, shown)<br />
<br />
''sub-selector'' is one of:<br />
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)<br />
*nocomments - only subquestions that are not comments<br />
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected.<br />
<br />
Examples:<br />
*Has any part of a question been answered? {count(self.NAOK)>0}<br />
*What is the assessment score for this question? {sum(self.value)}<br />
<br />
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.<br />
*What is the grand total? {sum(self.NAOK)}<br />
*What is the total of row B? {sum(self.sq_B.NAOK)}<br />
*What is the total of column 3? {sum(self.sq_3.NAOK)}<br />
<br />
The 'that' variable is like the 'self' variable, but lets you refer to other questions. Its syntax is:<br />
*that.''qname''<br />
*that.''qname''.''suffix''<br />
*that.''qname''.''sub-selector''<br />
*that.''qname''.''sub-selector''.''suffix''<br />
<br />
''qname'' is the question name without any sub-question extensions. So, say you create a question 'q1', that is its ''qname''<br />
<br />
Examples:<br />
*Has any part of question q1 been answered? {count(that.q1.NAOK)>0}<br />
*What is the assessment score for q2? (sum(that.q2.NAOK)}<br />
*What is the grand total of q3? {sum(that.q3.NAOK)}<br />
*What is the total of row C in q4? {sum(that.q4.sq_C.NAOK)}<br />
*What is the total of column 2 in q4? {sum(that.q4.sq_2.NAOK)}<br />
<br />
The 'self' and 'that' variables can be used in any relevance, validation, or tailoring.<br />
<br />
The one caveat is that when you use the 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'<br />
<br />
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.<br />
<br />
==Access to Functions==<br />
<br />
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.<br />
<br />
===Implemented Functions===<br />
<br />
The following functions are currently available:<br />
<br />
{|<br />
|Function||Meaning||Syntax<br />
|-<br />
[http://www.php.net/manual/en/function.abs.php ||abs]||Absolute value||number abs(number)<br />
|-<br />
[http://www.php.net/manual/en/function.acos.php ||acos]||Arc cosine||number acos(number)<br />
|-<br />
[http://www.php.net/manual/en/function.addslashes.php ||addslashes]||Quote string with slashes||string addslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.asin.php ||asin]||Arc sine||number asin(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan.php ||atan]||Arc tangent||number atan(number)<br />
|-<br />
[http://www.php.net/manual/en/function.atan2.php ||atan2]||Arc tangent of two variables||number atan2(number, number)<br />
|-<br />
[http://www.php.net/manual/en/function.ceil.php ||ceil]||Round fractions up||number ceil(number)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.cos.php ||cos]||Cosine||number cos(number)<br />
|-<br />
|count||count the number of answered (non-blank)questions in the list||number count(arg1, arg12, ..., argN)<br />
|-<br />
|countif||Count the number of answered questions in the list equal the first argument||number countif(matches, arg1, arg2, ... argN)<br />
|-<br />
|countifop||Count the number of answered questions in the list which pass the criteria (arg op value)||number countifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.date.php ||date]||Format a local date/time||string date(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[http://www.php.net/manual/en/function.exp.php ||exp]||Calculates the exponent of e||number exp(number)<br />
|-<br />
|fixnum||Display numbers with comma as radix separator, if needed||string fixnum(number)<br />
|-<br />
[http://www.php.net/manual/en/function.floor.php ||floor]||Round fractions down||number floor(number)<br />
|-<br />
[http://www.php.net/manual/en/function.gmdate.php ||gmdate]||Format a GMT date/time||string gmdate(format <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.idate.php ||idate]||Format a local time/date as integer||string idate(string <nowiki>[</nowiki>, timestamp=time()])<br />
|-<br />
|if||Excel-style if(test,result_if_true,result_if_false)||if(test,result_if_true,result_if_false)<br />
|-<br />
[http://www.php.net/manual/en/function.implode.php ||implode]||Join array elements with a string||string implode(glue,arg1,arg2,...,argN)<br />
|-<br />
[http://www.php.net/manual/en/function.intval.php ||intval]||Get the integer value of a variable||int intval(number <nowiki>[</nowiki>, base=10])<br />
|-<br />
[http://www.php.net/manual/en/function.empty.php ||is_empty]||Determine whether a variable is considered to be empty||bool is_empty(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.is-nan.php ||is_nan]||Finds whether a value is not a number||bool is_nan(var)<br />
|-<br />
[http://www.php.net/manual/en/function.is-null.php ||is_null]||Finds whether a variable is NULL||bool is_null(var)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
|list||Return comma-separated list of non-blank values||string list(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.log.php ||log]||Natural logarithm||number log(number)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.max.php ||max]||Find highest value||number max(arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.min.php ||min]||Find lowest value||number min(arg1, arg2, ... argN)<br />
|-<br />
[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 ]]]]]])<br />
|-<br />
|modulo-function||The modulo function is '''not supported''' yet. You can use the floor() function instead||floor(x/y)==(x/y)<br />
|-<br />
[http://www.php.net/manual/en/function.nl2br.php ||nl2br]||Inserts HTML line breaks before all newlines in a string||string nl2br(string)<br />
|-<br />
[http://www.php.net/manual/en/function.number-format.php ||number_format]||Format a number with grouped thousands||string number_format(number)<br />
|-<br />
|pi||Get value of pi||number pi()<br />
|-<br />
[http://www.php.net/manual/en/function.pow.php ||pow]||Exponential expression||number pow(base, exp)<br />
|-<br />
[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)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.quotemeta.php ||quotemeta]||Quote meta characters||string quotemeta(string)<br />
|-<br />
[http://www.php.net/manual/en/function.rand.php ||rand]||Generate a random integer||int rand() OR int rand(min, max)<br />
|-<br />
|regexMatch||compare a string to a [[Using regular expressions||regular expression]]||bool regexMatch(pattern,input)<br />
|-<br />
[http://www.php.net/manual/en/function.round.php ||round]||Rounds a number to an optional precision||number round(val <nowiki>[</nowiki>, precision])<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.sin.php ||sin]||Sine||number sin(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.sprintf.php ||sprintf]||Return a formatted string||string sprintf(format, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.sqrt.php ||sqrt]||Square root||number sqrt(arg)<br />
|-<br />
|stddev||Calculate the Sample Standard Deviation for the list of numbers||number stddev(arg1, arg2, ... argN)<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.str-repeat.php ||str_repeat]||Repeat a string||string str_repeat(input, multiplier)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.strcasecmp.php ||strcasecmp]||Binary safe case-insensitive string comparison||int strcasecmp(str1, str2)<br />
|-<br />
[http://www.php.net/manual/en/function.strcmp.php ||strcmp]||Binary safe string comparison||int strcmp(str1, str2)<br />
|-<br />
[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)<br />
|-<br />
[http://www.php.net/manual/en/function.stripos.php ||stripos]||Find position of first occurrence of a case-insensitive string||int stripos(haystack, needle <nowiki>[</nowiki>, offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.stripslashes.php ||stripslashes]||Un-quotes a quoted string||string stripslashes(string)<br />
|-<br />
[http://www.php.net/manual/en/function.stristr.php ||stristr]||Case-insensitive strstr||string stristr(haystack, needle <nowiki>[</nowiki>, before_needle=false])<br />
|-<br />
[http://www.php.net/manual/en/function.strlen.php ||strlen]||Get string length||int strlen(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strpos.php ||strpos]||Find position of first occurrence of a string||int strpos(haystack, needle <nowiki>[</nowiki> offset=0])<br />
|-<br />
[http://www.php.net/manual/en/function.strrev.php ||strrev]||Reverse a string||string strrev(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strstr.php ||strstr]||Find first occurrence of a string||string strstr(haystack, needle)<br />
|-<br />
[http://www.php.net/manual/en/function.strtolower.php ||strtolower]||Make a string lowercase||string strtolower(string)<br />
|-<br />
[http://www.php.net/manual/en/function.strtoupper.php ||strtoupper]||Make a string uppercase||string strtoupper(string)<br />
|-<br />
[http://www.php.net/manual/en/function.substr.php ||substr]||Return part of a string||string substr(string, start <nowiki>[</nowiki>, length])<br />
|-<br />
|sum||Calculate the sum of values in an array||number sum(arg1, arg2, ... argN)<br />
|-<br />
|sumifop||Sum the values of answered questions in the list which pass the criteria (arg op value)||number sumifop(op, value, arg1, arg2, ... argN)<br />
|-<br />
[http://www.php.net/manual/en/function.tan.php ||tan]||Tangent||number tan(arg)<br />
|-<br />
[http://www.php.net/manual/en/function.time.php ||time]||Return current UNIX timestamp||number time()<br />
|-<br />
[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])<br />
|-<br />
[http://www.php.net/manual/en/function.ucwords.php ||ucwords]||Uppercase the first character of each word in a string||string ucwords(string)<br />
|-<br />
|unique||Returns true if all non-empty responses are unique||boolean unique(arg1, ..., argN)<br />
|-<br />
|<br />
|}<br />
<br />
===Functions that are Planned or Being Considered===<br />
<br />
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.<br />
<br />
{|<br />
|Syntax||Meaning||Comments<br />
|-<br />
|e()||returns the value of e||<br />
|-<br />
|formatDate(X,PAT)||return the string value of date X formatted according to Java data format pattern PAT||<br />
|-<br />
|formatNumber(X,PAT)||return the string value of number X formatted according to Java number format pattern PAT||<br />
|-<br />
|getAnsOption(X)||returns the text corresponding to the selected option for answer X||this is the same as X.shown<br />
|-<br />
|getAnsOption(X,Y)||returns the text corresponding to the option at index Y of node X||<br />
|-<br />
|getRelevance(X)||returns the relevance equation for question X||<br />
|-<br />
|getStartTime()||returns the date corresponding to the system time when the interview was started||<br />
|-<br />
|getType(X)||returns the string name of the datatype - e.g. *NA* if isNA()||<br />
|-<br />
|gotoFirst()||jumps to the first relevant set of questions - this violates the normal flow of the system||<br />
|-<br />
|gotoNext()||jumps to the next set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|gotoPrevious()||jumps to the previous set of relevant questions - this violates the normal flow of the system||<br />
|-<br />
|isAsked(X)||returns true if the answer is neither *NA*, *INVALID*, nor *UNASKED*||<br />
|-<br />
|isInvalid(X)||returns true if the answer is of type *INVALID*||<br />
|-<br />
|isNA(X)||returns true if the answer is of type *NA*||<br />
|-<br />
|isNotUnderstood(X)||returns true if the answer if of type *HUH*||<br />
|-<br />
|isRefused(X)||returns true if the answer is of type *REFUSED*||<br />
|-<br />
|isSpecial(X)||returns true if the answer is of type *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN*, or *HUH*||<br />
|-<br />
|isUnknown(X)||returns true if the answer is of type *UNKNOWN*||<br />
|-<br />
|jumpTo(X)||jump to the group containing the named question -- this violates the normal flow of the system||<br />
|-<br />
|jumpToFirstUnasked()||jump to the first unasked question <strike> thus bypassing previous answered questions </strike> this violates the normal flow of the system||<br />
|-<br />
|lastIndexOf(X,Y)||returns the last index (base 0) of string Y in string X. Returns -1 if Y is not contained within X||<br />
|-<br />
|list(X,...)||a string containing a comma separated list of the positive values with "and" separating the last two||<br />
|-<br />
|mean(X,...)||returns the mean of a list of values||<br />
|-<br />
|numAnsOptions(X)||returns the number of answer options that question X has||<br />
|-<br />
|orlist(X,...)||a string containing a comma separated list of the positive values, with "or" separting the last two||<br />
|-<br />
|parseDate(X,PAT)||returns the date value of string X parsed with Java date format pattern PAT||<br />
|-<br />
|parseNumber(X,PAT)||returns the numerical value of string X parsed with Java number format pattern PAT||<br />
|-<br />
|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.||<br />
|-<br />
|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.||<br />
|-<br />
|<br />
|}<br />
<br />
==Expression Manager Knows Which Variables are Local==<br />
<br />
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).<br />
<br />
==Cascading Conditions==<br />
<br />
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<br />
<br />
{|<br />
|Operator||Example||a||b||Result<br />
|-<br />
|+ (unary)||+a||N/A|| ||false<br />
|-<br />
|- (unary)||-a||N/A|| ||false<br />
|-<br />
|!||!a||N/A|| ||false<br />
|-<br />
|== (or eq)||a == b||N/A||5||false<br />
|-<br />
|== (or eq)||a == b||N/A||0||false<br />
|-<br />
|== (or eq)||a == b||N/A||N/A||false<br />
|-<br />
|!= (or ne)||a != b||N/A||5|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||N/A|| false<br />
|-<br />
|!= (or ne)||a != b||N/A||0||false<br />
|-<br />
|> (or gt)||a > b||N/A||5|| false<br />
|-<br />
|>= (or ge)||a >= b||N/A||5||false<br />
|-<br />
|< (or lt)||a < b||N/A||5||false<br />
|-<br />
|<= (or le)||a <= b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||5||false<br />
|-<br />
|and||a and b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||N/A||false<br />
|-<br />
|or||a or b||N/A||5||false<br />
|-<br />
|+||a + b||N/A||5||false<br />
|-<br />
|-||a - b||N/A||5||false<br />
|-<br />
|*||a * b||N/A||5||false<br />
|-<br />
|/||a / b||5||N/A||false<br />
|-<br />
|()||(a)||N/A|| ||false<br />
|-<br />
|(exp)||(a && b)||N/A||5||false<br />
|-<br />
|(exp) op (exp)||(b + b) > (a && b)||N/A||5||false<br />
|-<br />
|function||sum(a,b,b)||N/A||5||false<br />
|-<br />
|function||max(a,b)||N/A||5||false<br />
|-<br />
|function||min(a,b)||N/A||5||false<br />
|-<br />
|function||implode(', ',a,b,a,b)||N/A||5||false<br />
|-<br />
|function||if(a,a,b)||N/A||5||false<br />
|-<br />
|function||is_empty(a)||N/A|| ||false<br />
|-<br />
|function||is_empty(a)||0 (or blank)|| ||true<br />
|-<br />
|function||!is_empty(a)||N/A|| ||false<br />
|-<br />
|<br />
|}<br />
<br />
===Overriding Cascading Conditions===<br />
<br />
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.<br />
<br />
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<br />
#q1 is not added to the LEManyNA() clause<br />
#LEMval('q1') will continue to check whether the response is relevant, and will return '' if it is not (so individual irrelevant responses will be ignored, but they will not void the entire expression.<br />
<br />
So, the solution to the running total problem is to use the equation sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).<br />
<br />
The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then converage 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.<br />
<br />
==How does Expression Manager Support Conditional Micro-Tailoring?==<br />
<br />
Here is an example of micro-tailoring (where Question Type=='expr' means an Equation):<br />
<br />
{|<br />
|Question Code||Relevance||Question Type||Question<br />
|-<br />
|name||1||text||What is your name?<br />
|-<br />
|age||1||text||How old are you?<br />
|-<br />
|badage||!is_empty(age)||expr||{(age<16) or (age>80)}<br />
|-<br />
|agestop||badage||message||Sorry, {name}, you are too {if( (age<16),'young',if( (age>80),'old','middle-aged') ) } for this test.<br />
|-<br />
|kids||!badage||yesno||Do you have children?<br />
|-<br />
|parents||1||expr||{!badage && kids=='Y'}<br />
|-<br />
|numKids||parents||text||How many children do you have?<br />
|-<br />
|kid1||parents && numKids >= 1||text||How old is your first child?<br />
|-<br />
|kid2||parents && numKids >= 2||text||How old is your second child?<br />
|-<br />
|kid3||parents && numKids >= 3||text||How old is your third child?<br />
|-<br />
|kid4||parents && numKids >= 4||text||How old is your fourth child?<br />
|-<br />
|kid5||parents && numKids >= 5||text||How old is your fifth child?<br />
|-<br />
|sumage||1||expr||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}<br />
|-<br />
|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}<br />
|-<br />
|<br />
|}<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Mapping of LimeSurvey 1.91+ to Expression Manager Functionality==<br />
<br />
{|<br />
|Old Feature||New Feature||Comments<br />
|-<br />
|Conditions||Relevance||You can use very complex conditional equations, and access a broader range of variables<br />
|-<br />
|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<br />
|-<br />
|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\})<br />
|-<br />
|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<br />
|-<br />
|<br />
|}<br />
<br />
=Syntax Highlighting=<br />
<br />
To help with entering and validating expressions, EM provides syntax highlighting with the following features:<br />
<br />
==Types and Meanings of Syntax Highlighting==<br />
<br />
{|<br />
|Color||Sample||Meaning||Tooltip||Comments<br />
|-<br />
|tan background||<span style='color:#eee8aa,#eee8aa'>Sample</span>||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<br />
|-<br />
|blue bold text||'''<span style='color:blue,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|grey text||<span style='color:grey,#eee8aa'>'Sample'</span>||string||none||single and double-quoted strings are shown in grey text<br />
|-<br />
|bold maroon text||'''<span style='color:maroon,#eee8aa'>Sample</span>'''||variable set on the same page, but after the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page but after the current question is shown in bold maroon text. This color coding should alert authors to possible errors in question sequencing; but it is allowed since some authors may want this sequence of variables a page, especially for dynamic reports. 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.<br />
|-<br />
|bold cyan text||'''<span style='color:#4C88BE,#eee8aa'>Sample</span>'''||variable set on the same page, prior to the current question||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on the same page and prior to the current question is shown in bold cyan 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.<br />
|-<br />
|bold green text||'''<span style='color:green,#eee8aa'>Sample</span>'''||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 pageis 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.<br />
|-<br />
|bold pink text||'''<span style='color:#FF00FF,#eee8aa'>Sample</span>'''||variable set on a later page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior pageis 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.<br />
|-<br />
|bold tan text||'''<span style='color:#996600,#eee8aa'>Sample</span>'''||a lime relacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE} are shown in bold tan text. The tooltip shows the current value.<br />
|-<br />
|red text||'''<span style='color:red,#eee8aa'>Sample</span>'''||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.<br />
|-<br />
|normal black text||<span style='color:black,#eee8aa'>Sample</span>||punctuation||none||All other punctionation within the expression is shown as normal black text.<br />
|-<br />
|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.<br />
|-<br />
|<br />
|}<br />
<br />
=Relationship to LimeSurvey Ideas / Feature Requests=<br />
<br />
Expression Manager provides complete or partial solutions to each of the following:<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1 Conditions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/3/ Answercounts]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/5 Advanced reporting for assessments]<br />
**partial: Equations let one store the Assessment value in the database, and micro-tailoring can generate simple formatted reports. Authors can access those Equation values if they have more complex reporting needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/6 Assessment reports]<br />
**partial: Since Equations store the Assessment score, it should be possible to use Statistics to show distributions of those scores, and Quotas to limit the number of responses with those scores.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/7 Store assessment results for further evaluation]<br />
**Equations let one store the Assessment value in the database, completely solving this problem<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/22/ More advanced condition rules]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/28 Open Answertable up so that we can alter formatting]<br />
**partial: All of the question attributes are available, so authors can create custom AnswerTable equivalents as a Question. Once implatemented, they can also use the showTheseResponses() or showAllResponsesExecpt() functions<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/37 Export survey results with full questions to include images]<br />
**since Tailoring has access to the full question text, it can include images in the export<br />
**if subjects choose Print Your Answers after finishing the survey, those printouts will be fully tailored<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/63 List of question codes and SGQA identifiers]<br />
**The Show Survey Logic view shows that mapping (plus much more information)<br />
**In addition, you no longer have to use SGQA codes to refer to variables - you can use the Question code/title.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/69 Branch/jump to another question (earlier or later) based on current question]<br />
**You can use the Navigation Index for this in most cases<br />
**Once implemented, you can use the JumpTo() function. Like the Navigation Index, if you try to jump forward, it will stop on an intervening page if there are any of the relevant mandatory questions are unanswered, or if any relevant questions fail validation tests.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/86 set quota for total responses]<br />
**If the final question is an Equation that flags a survey as completed (so is NULL if a respondant does not get to that page), you can use Quotas on that question to control the number of completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/101 Review all conditions]<br />
**The Show Logic File view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/105 Review all questions + Review all groups]<br />
**The Show Logic File view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/107 How to visualize questions, logic & conditions]<br />
**The Show Logic File view shows this (and much more)<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/113 Offline Surveys]<br />
**Running a survey with all of the questions on the same page would let you do off-line data collection (e.g. email the html page and associated JavaScript). However, you would still want a way to submit the results so that they did not get lost. It may be possible to use Save As HTML to save partially completed responses.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/120 Remove INSERTANS from question text at survey results]<br />
**INSERTANS is no longer needed. You can refer to a variable by its SGQA code (without prefixing it with INSERTANS:), or by its question code.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/137 Informed Consent and Authorization Functionality]<br />
**You can show show the informed consent on the welcome page, then ask any additional questions needed (to ensure they meet the study inclusion/exclusion criteria), and ask them a Yes/No question whether they give their consent. Then, make all of the remaining questions conditional on that yesNo. For example, if the question is named ''consent'', you would set the relevance to the remaining questions to ''consent == "Y"'' (possibly ''and''ing that with whatever additional conditions you needed to support your branching needs.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/199 Show codes instead of of answers using INSERTANS]<br />
**{Qcode} returns the code instead of the response text (which you can get via {INSERTANS:SGQA}, or {Qcode.shown}<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/204 Need group mean or calculations for assessments]<br />
**Say you have N variables of which N-X were answered, you could compute the mean of the answered variables as {sum(var1, var2, ..., varN) / count(var1, var2, ..., varN)}<br />
**Computing the mean across a set of respondants would require extension of the Quota functionality.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/222 To insert a language dependent text]<br />
**Tailoring lets you conjugate verbs and decline nouns in each language<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/225 Surveyors should approve their answers]<br />
**Custom Questions with tailoring, or the showAllResponsesExcept() function will let Surveyors see all of the questions and responses before clicking Submit. If the Navigation Menu option is enabled, it is easy to go back and correct answers.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Suppliment to #answernnXnnXnnn method of targetting form elements]<br />
**You can now refer to questions and answers by their Question Code, so there is no longer a need to modify SGQA values.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/262 More flexibility with hidden questions]<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/265 Remove specific conditions from multiple questions]<br />
**You can now use Relevance, which is easier to manage than Conditions. If needed, they can all be exported from the database, edited in a spreadsheet, and re-imported.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/268 Cross Survey Reporting]<br />
**By using question codes that are unique across your surveys and versions, you can consolidate data from multiple surveys and/or compare them<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/275 Simplifying integration with other tools]<br />
**Expression Manager uses Question Codes instead of SGQA, making it easier to integrate with other tools.<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Expose assessment score to 3rd party app processing]<br />
**This can be done with Equation question type<br />
*[http://ideas.limesurvey.org/ideatorrent/idea/309 Multiple thank you pages]<br />
**This can be supported via conditional relevance branching and tailoring<br />
<br />
=Additional Reading=<br />
<br />
==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]==<br />
<br />
==[[Expression Manager HowTos|Use Cases and HowTos]]==<br />
<br />
==[[Expression Manager Examples|Step-by-Step Examples]].==<br />
<br />
==[[Expression Manager for developers|Reference for Developers]]==<br />
<br />
==[[Expression Manager Roadmap|RoadMap/Status/ToDo List]]==</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_en_Francais&diff=1596Installation en Francais2012-12-08T08:55:23Z<p>Admin: </p>
<hr />
<div><br />
<div class="simplebox">Translation in progress.</div><br />
<br />
<div style="float:right;"><div class="simplebox">Pages suppl&eacute;mentaires:{toc}</div></div>__TOC__<br />
<br />
=1. Pr&eacute;requis pour utiliser LimeSurvey sur votre site web=<br />
<br />
Assurez-vous que votre serveur r&eacute;ponde aux exigences suivantes. La plus part de celle-ci seront v&eacute;rifi&eacute;es durant la phase d'installation :<br />
* 80 Mo d'espace libre pour la plateforme proprement dite.<br />
* MySQL 4.1.0 et versions suivantes '''OU''' Microsoft SQL Server 2005 et versions suivantes '''OU''' Postgres 8.1 et versions suivantes<br />
* PHP 5.1.2 et versions suivantes plus ces extensions :<br />
**mbstring (Multibyte String Functions) pour que le syst&egrave;me de traduction fonctionne. Voir aussi ([http://docs.limesurvey.org/tiki-index.php?page=Installation+FAQ#What_is_this_mbstring_Multibyte_String_Functions_library_ Installation FAQ de l'installation])<br />
**Pilote de base de donn&eacute;es PDO pour MySQL (pdo_mysql ou pdo_mysqli), Postgres (pdo_pgsql) ou MSSQL (pdo_sqlsrv) (cela devra &ecirc;tre le cas avec la plupart des h&eacute;bergeurs. Si vous avez vous-m&ecirc;me configur&eacute; votre serveur web, assurez-vous qu'elles sont install&eacute;es et actives)<br />
<br />
<div class="simplebox"> Attention : LimeSurvey 2.x utilise des pilotes de bases de donn&eacute;es diff&eacute;rents de LimeSurvey 1.x. Si vous voyez apparaitre le message "No DBO driver was found during the installation", veuillez demander &agrave; votre h&eacute;bergeur d'activer la/les extensions appropri&eacute;es mentionn&eacute; ci-avant. </div><br />
<br />
Extensions PHP facultatives :<br />
* '''GD''' install&eacute;e avec le '''support FreeType''' est n&eacute;cessaire pour la protection par CAPTCHA et les jolis graphiques (voir la documentation de l'[http://fr.php.net/manual/fr/image.setup.php extension GD])<br />
* '''IMAP''' pour [[Email bounce tracking system]] (voir la documentation de l'[http://www.php.net/manual/en/imap.setup.php extension IMAP])<br />
* '''LDAP''' pour la cr&eacute;ation d'invitations depuis un annuaire LDAP (voir la documentation de l'[http://fr.php.net/manual/fr/book.ldap.php extension LDAP])<br />
* '''ZLIB''' pour la mise &agrave; jour en 3 clics, le t&eacute;l&eacute;chargement de mod&egrave;les, l'importation de ressources ZIP, etc. (voir la documentation de l'[http://www.php.net/manual/en/zlib.setup.php extension Zlib])<br />
<br />
Dans la plupart des cas, votre h&eacute;bergeur ou votre administrateur syst&egrave;me pourra vous assister sur ces points.<br />
<br />
Si vous souhaitez tester LimeSurvey sur votre propre machine, notamment sous Windows, nous vous conseillons l'utilisation de [http://www.apachefriends.org/fr/index.html XAMPP] qui vous installera Apache, MySQL et perl. LimeSurvey fonctionne sur une installation de XAMPP sans configuration particuli&egrave;re.<br />
<br />
Si vous souhaitez utiliser le serveur Microsoft IIS veuillez regarder "[[Installation de LimeSurvey sur une machine sous Windows XP]]"<br />
<br />
==1.1 H&eacute;bergement pour LimeSurvey==<br />
<br />
LimeSurvey devrait fonctionner chez la plupart des h&eacute;bergeurs proposant PHP et MySQL. Si vous souhaitez une installation de LimeSurvey toute pr&ecirc;te, vous pouvez utiliser LimeService, vous pouvez aussi consulter la [[LimeSurvey-compatible hosting companies|liste des h&eacute;bergeurs compatibles avec LimeSurvey]].<br />
*Cas particulier de free.fr: Il serait possible d'installer limesurvey sur les serveurs de pages perso de free.fr selon ce [LimeSurvey sur pages perso free.fr|commentaire sur framasoft]. Cette information n'a pas &eacute;t&eacute; v&eacute;rifi&eacute;e.<br />
<br />
=2. T&eacute;l&eacute;chargement du programme LimeSurvey=<br />
<br />
La derni&egrave;re version stable de Limesurvey se trouve sur la [http://www.limesurvey.org/fr/telechargez page de t&eacute;l&eacute;chargement de LimeSurvey] vous pourrez la t&eacute;l&eacute;chargez sous forme d'un fichier d'installation ZIP. Vous trouverez aussi des fichiers compress&eacute;s en gzip, bz2 ou 7zip.<br />
<br />
=3. D&eacute;compression du fichier d'installation de LimeSurvey=<br />
<br />
D&eacute;compressez le fichier ZIP dans un dossier/r&eacute;pertoire d&eacute;di&eacute; avec votre outil de d&eacute;compression pr&eacute;f&eacute;r&eacute;. Assurez-vous que votre logiciel de d&eacute;compression recr&eacute;e bien la structure des dossiers avec les fichiers (c'est normalement le comportement de ce genre de programmes). Le nom du chemin d'installation ne doit pas contenir les caract&egrave;res '''(''' ou ''')''' mais peut contenir des '''espaces'''.<br />
<br />
=4. Collecte d'informations au sujet de votre serveur=<br />
<br />
Vous devez vous renseigner sur les points suivants pour pouvoir installer correctement LimeSurvey sur votre serveur web :<br />
*L'URL pr&eacute;vue pour se connecter au programme (exemple : 'http://mon.domaine.com/limesurvey').<br />
*L'emplacement physique des fichiers sur le serveur (exemple : '/var/www/htdocs/limesurvey').<br />
*L'adresse IP ou le nom d'h&ocirc;te de votre serveur MySQL (exemple : 'localhost')<br />
*Si votre base de donn&eacute;es n'utilise pas le port par d&eacute;faut, vous devrez conna&icirc;tre sur quel port il &eacute;coute.<br />
*Vos nom d'utilisateur et mot de passe pour l'acc&egrave;s &agrave; votre base de donn&eacute;es.<br />
*La plupart des h&eacute;bergeurs n'autorisent pas les scripts &agrave; cr&eacute;er des bases de donn&eacute;es mais c'est &agrave; vous de le faire manuellement. Si vous &ecirc;tes dans ce cas, n'oubliez pas de cr&eacute;er vous-m&ecirc;me une base de donn&eacute;es (par exemple, 'limesurvey')<br />
<br />
=5. Cette partie n'existe plus=<br />
<br />
=6. Envoi des fichiers sur votre serveur web=<br />
<br />
En utilisant votre client FTP favori, connectez-vous &agrave; votre serveur web et cr&eacute;ez un dossier pour y stocker les fichiers de LimeSurvey. Envoyez dans ce dossier l'ensemble des fichiers de LimeSurvey en respectant la structure des dossiers. Nous vous recommandons d'envoyer les fichiers en mode binaire (r&eacute;glage du programme de FTP). En utilisant le mode ASCII, parfois les images sont mal transf&eacute;r&eacute;es.<br />
<br />
=7. D&eacute;finition des permissions des dossiers=<br />
<br />
Pour que le programme fonctionne correctement, il a besoin d'acc&egrave;s &agrave; certains dossiers. Cela s'applique sp&eacute;cialement aux syst&egrave;mes Linux/*nix.<br />
* le dossier '''"/limesurvey/tmp"''' est utilis&eacute; pour les importations et les exportations et doit &ecirc;tre en ''lecture et &eacute;criture'' pour le serveur web.<br />
* le dossier '''"/limesurvey/upload"''' et ses sous-dossiers doivent aussi &ecirc;tre en ''lecture et &eacute;criture'' pour votre serveur web pour activer l'envoi d'images et de fichiers multim&eacute;dias.<br />
* le dossier '''"/limesurvey/application/config/"''' &agrave; besoin d'&ecirc;tre en ''lecture et &eacute;criture'' pour votre serveur web pour l'activation de la configuration lors de l'installation automatique.<br />
* les autres dossiers peuvent &ecirc;tre en ''lecture seule''. Vous pouvez aussi d&eacute;finir des permissions de ''lecture seule'' pour chaque fichier dans le dossier ''/limesurvey/admin''.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Conseil :''' Si vous utilisez Linux alors en fonction de la configuration de votre serveur web vous devrez chmod&eacute; les droits sur les r&eacute;pertoires en &eacute;critures &agrave; 755 ou 777. Essayez 755 en premier et si cela ne marche pas, "passez" &agrave; 777.</div><br />
<br />
=8. Ex&eacute;cution du script d'installation=<br />
<br />
Rendez-vous &agrave; '''"http://votre.domaine.com/limesurvey/admin/"'''. Si vous avez tout configur&eacute; correctement, suivez les instructions. Vous serez invit&eacute; &agrave; cr&eacute;er la base de donn&eacute;es et/ou les tables dans la base.<br />
<br />
=9. Premi&egrave;re connexion &agrave; l'interface d'administration=<br />
<br />
Vous &ecirc;tes pr&ecirc;t ! Ouvrez votre navigateur et saisissez l'adresse vers le script admin.php. En supposant que vous avez utilis&eacute; limesurvey pour le nom du dossier o&ugrave; vous avez stock&eacute; les fichiers, cela ressemblera &agrave; quelque chose comme-&ccedil;a "http://votre.domaine.com/limesurvey/admin/admin.php".<br />
<br />
Normalement, vous devriez tomber sur un &eacute;cran d'identification. Les valeurs par d&eacute;faut pour pouvoir se connecter sont :<br />
<br />
<div class="simplebox">Utilisateur : admin<br />
<br />
Mot de passe : password</div><br />
<br />
Il vous sera demand&eacute; de changer ce mot de passe apr&egrave;s la premi&egrave;re connexion. Amusez-vous bien !<br />
<br />
=10. En cas de probl&egrave;me...=<br />
<br />
Comme tout programme informatique, les choses se d&eacute;rouleront telles que d&eacute;crites dans les instructions mais, en g&eacute;n&eacute;ral, ce ne sera pas le cas. Il existe de nombreuses de raisons possibles pour que les choses ne se passent pas comme d&eacute;crites ici. Si vous avez des soucis, veuillez d'abord consulter la [[FAQ de l'installation]]. Si vous ne trouvez pas de r&eacute;ponses alors veuillez d&eacute;crire votre probl&egrave;me dans le [http://www.limesurvey.org/component/option,com_fireboard/Itemid,86/lang,fr/ forum de LimeSurvey] sur limesurvey.org.ou essayer de contacter quelqu'un dans le [irc://irc.freenode.net/limesurvey|salon IRC de LimeSurvey] :<br />
<br />
<div class="simplebox"><center>[http://www.limesurvey.org/index.php/Live-Chat.html Lien direct vers le canal IRC officiel de LimeSurvey]</center></div></div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_en_Francais&diff=1597Installation en Francais2012-12-08T08:54:01Z<p>Admin: </p>
<hr />
<div><br />
<div class="simplebox">Translation in progress.</div><br />
<br />
<div style="float:right;"><div class="simplebox">Pages suppl&eacute;mentaires:{toc}</div></div>__TOC__<br />
<br />
=1. Pr&eacute;requis pour utiliser LimeSurvey sur votre site web=<br />
<br />
Assurez-vous que votre serveur r&eacute;ponde aux exigences suivantes. La plus part de celle-ci seront v&eacute;rifi&eacute;es durant la phase d'installation :<br />
* 80 Mo d'espace libre pour la plateforme proprement dite.<br />
* MySQL 4.1.0 et versions suivantes '''OU''' Microsoft SQL Server 2005 et versions suivantes '''OU''' Postgres 8.1 et versions suivantes<br />
* PHP 5.1.2 et versions suivantes plus ces extensions :<br />
**mbstring (Multibyte String Functions) pour que le syst&egrave;me de traduction fonctionne. Voir aussi ([http://docs.limesurvey.org/tiki-index.php?page=Installation+FAQ#What_is_this_mbstring_Multibyte_String_Functions_library_ Installation FAQ de l'installation])<br />
**Pilote de base de donn&eacute;es PDO pour MySQL (pdo_mysql ou pdo_mysqli), Postgres (pdo_pgsql) ou MSSQL (pdo_sqlsrv) (cela devra &ecirc;tre le cas avec la plupart des h&eacute;bergeurs. Si vous avez vous-m&ecirc;me configur&eacute; votre serveur web, assurez-vous qu'elles sont install&eacute;es et actives)<br />
<br />
<div class="simplebox"> Attention : LimeSurvey 2.x utilise des pilotes de bases de donn&eacute;es diff&eacute;rents de LimeSurvey 1.x. Si vous voyez apparaitre le message "No DBO driver was found during the installation", veuillez demander &agrave; votre h&eacute;bergeur d'activer la/les extensions appropri&eacute;es mentionn&eacute; ci-avant. </div><br />
<br />
Extensions PHP facultatives :<br />
* '''GD''' install&eacute;e avec le '''support FreeType''' est n&eacute;cessaire pour la protection par CAPTCHA et les jolis graphiques (voir la documentation de l'[http://fr.php.net/manual/fr/image.setup.php extension GD])<br />
* '''IMAP''' pour [[Email bounce tracking system]] (voir la documentation de l'[http://www.php.net/manual/en/imap.setup.php extension IMAP])<br />
* '''LDAP''' pour la cr&eacute;ation d'invitations depuis un annuaire LDAP (voir la documentation de l'[http://fr.php.net/manual/fr/book.ldap.php extension LDAP])<br />
* '''ZLIB''' pour la mise &agrave; jour en 3 clics, le t&eacute;l&eacute;chargement de mod&egrave;les, l'importation de ressources ZIP, etc. (voir la documentation de l'[http://www.php.net/manual/en/zlib.setup.php extension Zlib])<br />
<br />
Dans la plupart des cas, votre h&eacute;bergeur ou votre administrateur syst&egrave;me pourra vous assister sur ces points.<br />
<br />
Si vous souhaitez tester LimeSurvey sur votre propre machine, notamment sous Windows, nous vous conseillons l'utilisation de [http://www.apachefriends.org/fr/index.html XAMPP] qui vous installera Apache, MySQL et perl. LimeSurvey fonctionne sur une installation de XAMPP sans configuration particuli&egrave;re.<br />
<br />
Si vous souhaitez utiliser le serveur Microsoft IIS veuillez regarder "[[Installation de LimeSurvey sur une machine sous Windows XP]]"<br />
<br />
==1.1 H&eacute;bergement pour LimeSurvey==<br />
<br />
LimeSurvey devrait fonctionner chez la plupart des h&eacute;bergeurs proposant PHP et MySQL. Si vous souhaitez une installation de LimeSurvey toute pr&ecirc;te, vous pouvez utiliser LimeService, vous pouvez aussi consulter la [[LimeSurvey-compatible hosting companies|liste des h&eacute;bergeurs compatibles avec LimeSurvey]].<br />
*Cas particulier de free.fr: Il serait possible d'installer limesurvey sur les serveurs de pages perso de free.fr selon ce [LimeSurvey sur pages perso free.fr|commentaire sur framasoft]. Cette information n'a pas &eacute;t&eacute; v&eacute;rifi&eacute;e.<br />
<br />
=2. T&eacute;l&eacute;chargement du programme LimeSurvey=<br />
<br />
La derni&egrave;re version stable de Limesurvey se trouve sur la [http://www.limesurvey.org/fr/telechargez page de t&eacute;l&eacute;chargement de LimeSurvey] vous pourrez la t&eacute;l&eacute;chargez sous forme d'un fichier d'installation ZIP. Vous trouverez aussi des fichiers compress&eacute;s en gzip, bz2 ou 7zip.<br />
<br />
=3. D&eacute;compression du fichier d'installation de LimeSurvey=<br />
<br />
D&eacute;compressez le fichier ZIP dans un dossier/r&eacute;pertoire d&eacute;di&eacute; avec votre outil de d&eacute;compression pr&eacute;f&eacute;r&eacute;. Assurez-vous que votre logiciel de d&eacute;compression recr&eacute;e bien la structure des dossiers avec les fichiers (c'est normalement le comportement de ce genre de programmes). Le nom du chemin d'installation ne doit pas contenir les caract&egrave;res '''(''' ou ''')''' mais peut contenir des '''espaces'''.<br />
<br />
=4. Collecte d'informations au sujet de votre serveur=<br />
<br />
Vous devez vous renseigner sur les points suivants pour pouvoir installer correctement LimeSurvey sur votre serveur web :<br />
*L'URL pr&eacute;vue pour se connecter au programme (exemple : 'http://mon.domaine.com/limesurvey').<br />
*L'emplacement physique des fichiers sur le serveur (exemple : '/var/www/htdocs/limesurvey').<br />
*L'adresse IP ou le nom d'h&ocirc;te de votre serveur MySQL (exemple : 'localhost')<br />
*Si votre base de donn&eacute;es n'utilise pas le port par d&eacute;faut, vous devrez conna&icirc;tre sur quel port il &eacute;coute.<br />
*Vos nom d'utilisateur et mot de passe pour l'acc&egrave;s &agrave; votre base de donn&eacute;es.<br />
*La plupart des h&eacute;bergeurs n'autorisent pas les scripts &agrave; cr&eacute;er des bases de donn&eacute;es mais c'est &agrave; vous de le faire manuellement. Si vous &ecirc;tes dans ce cas, n'oubliez pas de cr&eacute;er vous-m&ecirc;me une base de donn&eacute;es (par exemple, 'limesurvey')<br />
<br />
=5. Cette partie n'existe plus=<br />
<br />
=6. Envoi des fichiers sur votre serveur web=<br />
<br />
En utilisant votre client FTP favori, connectez-vous &agrave; votre serveur web et cr&eacute;ez un dossier pour y stocker les fichiers de LimeSurvey. Envoyez dans ce dossier l'ensemble des fichiers de LimeSurvey en respectant la structure des dossiers. Nous vous recommandons d'envoyer les fichiers en mode binaire (r&eacute;glage du programme de FTP). En utilisant le mode ASCII, parfois les images sont mal transf&eacute;r&eacute;es.<br />
<br />
=7. D&eacute;finition des permissions des dossiers=<br />
<br />
Pour que le programme fonctionne correctement, il a besoin d'acc&egrave;s &agrave; certains dossiers. Cela s'applique sp&eacute;cialement aux syst&egrave;mes Linux/*nix.<br />
* le dossier '''"/limesurvey/tmp"''' est utilis&eacute; pour les importations et les exportations et doit &ecirc;tre en ''lecture et &eacute;criture'' pour le serveur web.<br />
* le dossier '''"/limesurvey/upload"''' et ses sous-dossiers doivent aussi &ecirc;tre en ''lecture et &eacute;criture'' pour votre serveur web pour activer l'envoi d'images et de fichiers multim&eacute;dias.<br />
* le dossier '''"/limesurvey/application/config/"''' &agrave; besoin d'&ecirc;tre en ''lecture et &eacute;criture'' pour votre serveur web pour l'activation de la configuration lors de l'installation automatique.<br />
* les autres dossiers peuvent &ecirc;tre en ''lecture seule''. Vous pouvez aussi d&eacute;finir des permissions de ''lecture seule'' pour chaque fichier dans le dossier ''/limesurvey/admin''.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Conseil :''' Si vous utilisez Linux alors en fonction de la configuration de votre serveur web vous devrez chmod&eacute; les droits sur les r&eacute;pertoires en &eacute;critures &agrave; 755 ou 777. Essayez 755 en premier et si cela ne marche pas, "passez" &agrave; 777.</div><br />
<br />
=8. Ex&eacute;cution du script d'installation=<br />
<br />
Rendez-vous &agrave; '''"http://votre.domaine.com/limesurvey/admin/"'''. Si vous avez tout configur&eacute; correctement, suivez les instructions. Vous serez invit&eacute; &agrave; cr&eacute;er la base de donn&eacute;es et/ou les tables dans la base.<br />
<br />
=9. Premi&egrave;re connexion &agrave; l'interface d'administration=<br />
<br />
Vous &ecirc;tes pr&ecirc;t ! Ouvrez votre navigateur et saisissez l'adresse vers le script admin.php. En supposant que vous avez utilis&eacute; limesurvey pour le nom du dossier o&ugrave; vous avez stock&eacute; les fichiers, cela ressemblera &agrave; quelque chose comme-&ccedil;a "http://votre.domaine.com/limesurvey/admin/admin.php".<br />
<br />
Normalement, vous devriez tomber sur un &eacute;cran d'identification. Les valeurs par d&eacute;faut pour pouvoir se connecter sont :<br />
<br />
<div class="simplebox">Utilisateur : admin<br />
<br />
Mot de passe : password</div><br />
<br />
Il vous sera demand&eacute; de changer ce mot de passe apr&egrave;s la premi&egrave;re connexion. Amusez-vous bien !<br />
<br />
=10. En cas de probl&egrave;me...=<br />
<br />
Comme tout programme informatique, les choses se d&eacute;rouleront telles que d&eacute;crites dans les instructions mais, en g&eacute;n&eacute;ral, ce ne sera pas le cas. Il existe de nombreuses de raisons possibles pour que les choses ne se passent pas comme d&eacute;crites ici. Si vous avez des soucis, veuillez d'abord consulter la [[FAQ de l'installation]]. Si vous ne trouvez pas de r&eacute;ponses alors veuillez d&eacute;crire votre probl&egrave;me dans le [http://www.limesurvey.org/component/option,com_fireboard/Itemid,86/lang,fr/ forum de LimeSurvey] sur limesurvey.org.ou essayer de contacter quelqu'un dans le [irc://irc.freenode.net/limesurvey|salon IRC de LimeSurvey] :<br />
<br />
<div class="simplebox"><center>[http://www.limesurvey.org/index.php/Live-Chat.html Lien direct vers le canal IRC officiel de LimeSurvey]</center></div><br />
<br />
=Tutoriels vid&eacute;o=<br />
<br />
Ces tutoriels vid&eacute;o n'ont pas &eacute;t&eacute; cr&eacute;&eacute;s et ne sont pas maintenus par notre &eacute;quipe et doivent &ecirc;tre utilis&eacute;s comme "pense-b&ecirc;te". Ils ne remplacent en rien la lecture des instructions ci-dessus !<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu How to install and configure '''LimeSurvey''' v1.01 in Ubuntu Feisty].<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu Upgrading from '''LimeSurvey''' 1.01 to '''LimeSurvey''' 1.52+ build 3304 2007-09-20 in Ubuntu Feisty].</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_en_Francais&diff=1598Installation en Francais2012-12-08T08:53:02Z<p>Admin: </p>
<hr />
<div><br />
<div class="simplebox">Translation in progress.</div><br />
<br />
<div style="float:right;"><div class="simplebox">Pages suppl&eacute;mentaires:{toc}</div></div>__TOC__<br />
<br />
=1. Pr&eacute;requis pour utiliser LimeSurvey sur votre site web=<br />
<br />
Assurez-vous que votre serveur r&eacute;ponde aux exigences suivantes. La plus part de celle-ci seront v&eacute;rifi&eacute;es durant la phase d'installation :<br />
* 80 Mo d'espace libre pour la plateforme proprement dite.<br />
* MySQL 4.1.0 et versions suivantes '''OU''' Microsoft SQL Server 2005 et versions suivantes '''OU''' Postgres 8.1 et versions suivantes<br />
* PHP 5.1.2 et versions suivantes plus ces extensions :<br />
**mbstring (Multibyte String Functions) pour que le syst&egrave;me de traduction fonctionne. Voir aussi ([http://docs.limesurvey.org/tiki-index.php?page=Installation+FAQ#What_is_this_mbstring_Multibyte_String_Functions_library_ Installation FAQ de l'installation])<br />
**Pilote de base de donn&eacute;es PDO pour MySQL (pdo_mysql ou pdo_mysqli), Postgres (pdo_pgsql) ou MSSQL (pdo_sqlsrv) (cela devra &ecirc;tre le cas avec la plupart des h&eacute;bergeurs. Si vous avez vous-m&ecirc;me configur&eacute; votre serveur web, assurez-vous qu'elles sont install&eacute;es et actives)<br />
<br />
<div class="simplebox"> Attention : LimeSurvey 2.x utilise des pilotes de bases de donn&eacute;es diff&eacute;rents de LimeSurvey 1.x. Si vous voyez apparaitre le message "No DBO driver was found during the installation", veuillez demander &agrave; votre h&eacute;bergeur d'activer la/les extensions appropri&eacute;es mentionn&eacute; ci-avant. </div><br />
<br />
Extensions PHP facultatives :<br />
* '''GD''' install&eacute;e avec le '''support FreeType''' est n&eacute;cessaire pour la protection par CAPTCHA et les jolis graphiques (voir la documentation de l'[http://fr.php.net/manual/fr/image.setup.php extension GD])<br />
* '''IMAP''' pour [[Email bounce tracking system]] (voir la documentation de l'[http://www.php.net/manual/en/imap.setup.php extension IMAP])<br />
* '''LDAP''' pour la cr&eacute;ation d'invitations depuis un annuaire LDAP (voir la documentation de l'[http://fr.php.net/manual/fr/book.ldap.php extension LDAP])<br />
* '''ZLIB''' pour la mise &agrave; jour en 3 clics, le t&eacute;l&eacute;chargement de mod&egrave;les, l'importation de ressources ZIP, etc. (voir la documentation de l'[http://www.php.net/manual/en/zlib.setup.php extension Zlib])<br />
<br />
Dans la plupart des cas, votre h&eacute;bergeur ou votre administrateur syst&egrave;me pourra vous assister sur ces points.<br />
<br />
Si vous souhaitez tester LimeSurvey sur votre propre machine, notamment sous Windows, nous vous conseillons l'utilisation de [http://www.apachefriends.org/fr/index.html XAMPP] qui vous installera Apache, MySQL et perl. LimeSurvey fonctionne sur une installation de XAMPP sans configuration particuli&egrave;re.<br />
<br />
Si vous souhaitez utiliser le serveur Microsoft IIS veuillez regarder "[[Installation de LimeSurvey sur une machine sous Windows XP]]"<br />
<br />
==1.1 H&eacute;bergement pour LimeSurvey==<br />
<br />
LimeSurvey devrait fonctionner chez la plupart des h&eacute;bergeurs proposant PHP et MySQL. Si vous souhaitez une installation de LimeSurvey toute pr&ecirc;te, vous pouvez utiliser LimeService, vous pouvez aussi consulter la [[LimeSurvey-compatible hosting companies|liste des h&eacute;bergeurs compatibles avec LimeSurvey]].<br />
*Cas particulier de free.fr: Il serait possible d'installer limesurvey sur les serveurs de pages perso de free.fr selon ce [LimeSurvey sur pages perso free.fr|commentaire sur framasoft]. Cette information n'a pas &eacute;t&eacute; v&eacute;rifi&eacute;e.<br />
<br />
=2. T&eacute;l&eacute;chargement du programme LimeSurvey=<br />
<br />
La derni&egrave;re version stable de Limesurvey se trouve sur la [http://www.limesurvey.org/fr/telechargez page de t&eacute;l&eacute;chargement de LimeSurvey] vous pourrez la t&eacute;l&eacute;chargez sous forme d'un fichier d'installation ZIP. Vous trouverez aussi des fichiers compress&eacute;s en gzip, bz2 ou 7zip.<br />
<br />
=3. D&eacute;compression du fichier d'installation de LimeSurvey=<br />
<br />
D&eacute;compressez le fichier ZIP dans un dossier/r&eacute;pertoire d&eacute;di&eacute; avec votre outil de d&eacute;compression pr&eacute;f&eacute;r&eacute;. Assurez-vous que votre logiciel de d&eacute;compression recr&eacute;e bien la structure des dossiers avec les fichiers (c'est normalement le comportement de ce genre de programmes). Le nom du chemin d'installation ne doit pas contenir les caract&egrave;res '''(''' ou ''')''' mais peut contenir des '''espaces'''.<br />
<br />
=4. Collecte d'informations au sujet de votre serveur=<br />
<br />
Vous devez vous renseigner sur les points suivants pour pouvoir installer correctement LimeSurvey sur votre serveur web :<br />
*L'URL pr&eacute;vue pour se connecter au programme (exemple : 'http://mon.domaine.com/limesurvey').<br />
*L'emplacement physique des fichiers sur le serveur (exemple : '/var/www/htdocs/limesurvey').<br />
*L'adresse IP ou le nom d'h&ocirc;te de votre serveur MySQL (exemple : 'localhost')<br />
*Si votre base de donn&eacute;es n'utilise pas le port par d&eacute;faut, vous devrez conna&icirc;tre sur quel port il &eacute;coute.<br />
*Vos nom d'utilisateur et mot de passe pour l'acc&egrave;s &agrave; votre base de donn&eacute;es.<br />
*La plupart des h&eacute;bergeurs n'autorisent pas les scripts &agrave; cr&eacute;er des bases de donn&eacute;es mais c'est &agrave; vous de le faire manuellement. Si vous &ecirc;tes dans ce cas, n'oubliez pas de cr&eacute;er vous-m&ecirc;me une base de donn&eacute;es (par exemple, 'limesurvey')<br />
<br />
=5. Cette partie n'existe plus=<br />
<br />
=6. Envoi des fichiers sur votre serveur web=<br />
<br />
En utilisant votre client FTP favori, connectez-vous &agrave; votre serveur web et cr&eacute;ez un dossier pour y stocker les fichiers de LimeSurvey. Envoyez dans ce dossier l'ensemble des fichiers de LimeSurvey en respectant la structure des dossiers. Nous vous recommandons d'envoyer les fichiers en mode binaire (r&eacute;glage du programme de FTP). En utilisant le mode ASCII, parfois les images sont mal transf&eacute;r&eacute;es.<br />
<br />
=7. D&eacute;finition des permissions des dossiers=<br />
<br />
Pour que le programme fonctionne correctement, il a besoin d'acc&egrave;s &agrave; certains dossiers. Cela s'applique sp&eacute;cialement aux syst&egrave;mes Linux/*nix.<br />
* le dossier '''"/limesurvey/tmp"''' est utilis&eacute; pour les importations et les exportations et doit &ecirc;tre en ''lecture et &eacute;criture'' pour le serveur web.<br />
* le dossier '''"/limesurvey/upload"''' et ses sous-dossiers doivent aussi &ecirc;tre en ''lecture et &eacute;criture'' pour votre serveur web pour activer l'envoi d'images et de fichiers multim&eacute;dias.<br />
* le dossier '''"/limesurvey/application/config/"''' &agrave; besoin d'&ecirc;tre en ''lecture et &eacute;criture'' pour votre serveur web pour l'activation de la configuration lors de l'installation automatique.<br />
* les autres dossiers peuvent &ecirc;tre en ''lecture seule''. Vous pouvez aussi d&eacute;finir des permissions de ''lecture seule'' pour chaque fichier dans le dossier ''/limesurvey/admin''.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Conseil :''' Si vous utilisez Linux alors en fonction de la configuration de votre serveur web vous devrez chmod&eacute; les droits sur les r&eacute;pertoires en &eacute;critures &agrave; 755 ou 777. Essayez 755 en premier et si cela ne marche pas, "passez" &agrave; 777.</div><br />
<br />
=8. Ex&eacute;cution du script d'installation=<br />
<br />
Rendez-vous &agrave; '''"http://votre.domaine.com/limesurvey/admin/install"'''. Si vous avez tout configur&eacute; correctement, vous serez invit&eacute; &agrave; cr&eacute;er la base de donn&eacute;es et/ou les tables dans la base.<br />
<br />
=9. Premi&egrave;re connexion &agrave; l'interface d'administration=<br />
<br />
Vous &ecirc;tes pr&ecirc;t ! Ouvrez votre navigateur et saisissez l'adresse vers le script admin.php. En supposant que vous avez utilis&eacute; limesurvey pour le nom du dossier o&ugrave; vous avez stock&eacute; les fichiers, cela ressemblera &agrave; quelque chose comme-&ccedil;a "http://votre.domaine.com/limesurvey/admin/admin.php".<br />
<br />
Normalement, vous devriez tomber sur un &eacute;cran d'identification. Les valeurs par d&eacute;faut pour pouvoir se connecter sont :<br />
<br />
<div class="simplebox">Utilisateur : admin<br />
<br />
Mot de passe : password</div><br />
<br />
Il vous sera demand&eacute; de changer ce mot de passe apr&egrave;s la premi&egrave;re connexion. Amusez-vous bien !<br />
<br />
=10. En cas de probl&egrave;me...=<br />
<br />
Comme tout programme informatique, les choses se d&eacute;rouleront telles que d&eacute;crites dans les instructions mais, en g&eacute;n&eacute;ral, ce ne sera pas le cas. Il existe de nombreuses de raisons possibles pour que les choses ne se passent pas comme d&eacute;crites ici. Si vous avez des soucis, veuillez d'abord consulter la [[FAQ de l'installation]]. Si vous ne trouvez pas de r&eacute;ponses alors veuillez d&eacute;crire votre probl&egrave;me dans le [http://www.limesurvey.org/component/option,com_fireboard/Itemid,86/lang,fr/ forum de LimeSurvey] sur limesurvey.org.ou essayer de contacter quelqu'un dans le [irc://irc.freenode.net/limesurvey|salon IRC de LimeSurvey] :<br />
<br />
<div class="simplebox"><center>[http://www.limesurvey.org/index.php/Live-Chat.html Lien direct vers le canal IRC officiel de LimeSurvey]</center></div><br />
<br />
=Tutoriels vid&eacute;o=<br />
<br />
Ces tutoriels vid&eacute;o n'ont pas &eacute;t&eacute; cr&eacute;&eacute;s et ne sont pas maintenus par notre &eacute;quipe et doivent &ecirc;tre utilis&eacute;s comme "pense-b&ecirc;te". Ils ne remplacent en rien la lecture des instructions ci-dessus !<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu How to install and configure '''LimeSurvey''' v1.01 in Ubuntu Feisty].<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu Upgrading from '''LimeSurvey''' 1.01 to '''LimeSurvey''' 1.52+ build 3304 2007-09-20 in Ubuntu Feisty].</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_en_Francais&diff=1599Installation en Francais2012-12-08T08:51:11Z<p>Admin: </p>
<hr />
<div><br />
<div class="simplebox">Translation in progress.</div><br />
<br />
<div style="float:right;"><div class="simplebox">Pages suppl&eacute;mentaires:{toc}</div></div>__TOC__<br />
<br />
=1. Pr&eacute;requis pour utiliser LimeSurvey sur votre site web=<br />
<br />
Assurez-vous que votre serveur r&eacute;ponde aux exigences suivantes. La plus part de celle-ci seront v&eacute;rifi&eacute;es durant la phase d'installation :<br />
* 80 Mo d'espace libre pour la plateforme proprement dite.<br />
* MySQL 4.1.0 et versions suivantes '''OU''' Microsoft SQL Server 2005 et versions suivantes '''OU''' Postgres 8.1 et versions suivantes<br />
* PHP 5.1.2 et versions suivantes plus ces extensions :<br />
**mbstring (Multibyte String Functions) pour que le syst&egrave;me de traduction fonctionne. Voir aussi ([http://docs.limesurvey.org/tiki-index.php?page=Installation+FAQ#What_is_this_mbstring_Multibyte_String_Functions_library_ Installation FAQ de l'installation])<br />
**Pilote de base de donn&eacute;es PDO pour MySQL (pdo_mysql ou pdo_mysqli), Postgres (pdo_pgsql) ou MSSQL (pdo_sqlsrv) (cela devra &ecirc;tre le cas avec la plupart des h&eacute;bergeurs. Si vous avez vous-m&ecirc;me configur&eacute; votre serveur web, assurez-vous qu'elles sont install&eacute;es et actives)<br />
<br />
<div class="simplebox"> Attention : LimeSurvey 2.x utilise des pilotes de bases de donn&eacute;es diff&eacute;rents de LimeSurvey 1.x. Si vous voyez apparaitre le message "No DBO driver was found during the installation", veuillez demander &agrave; votre h&eacute;bergeur d'activer la/les extensions appropri&eacute;es mentionn&eacute; ci-avant. </div><br />
<br />
Extensions PHP facultatives :<br />
* '''GD''' install&eacute;e avec le '''support FreeType''' est n&eacute;cessaire pour la protection par CAPTCHA et les jolis graphiques (voir la documentation de l'[http://fr.php.net/manual/fr/image.setup.php extension GD])<br />
* '''IMAP''' pour [[Email bounce tracking system]] (voir la documentation de l'[http://www.php.net/manual/en/imap.setup.php extension IMAP])<br />
* '''LDAP''' pour la cr&eacute;ation d'invitations depuis un annuaire LDAP (voir la documentation de l'[http://fr.php.net/manual/fr/book.ldap.php extension LDAP])<br />
* '''ZLIB''' pour la mise &agrave; jour en 3 clics, le t&eacute;l&eacute;chargement de mod&egrave;les, l'importation de ressources ZIP, etc. (voir la documentation de l'[http://www.php.net/manual/en/zlib.setup.php extension Zlib])<br />
<br />
Dans la plupart des cas, votre h&eacute;bergeur ou votre administrateur syst&egrave;me pourra vous assister sur ces points.<br />
<br />
Si vous souhaitez tester LimeSurvey sur votre propre machine, notamment sous Windows, nous vous conseillons l'utilisation de [http://www.apachefriends.org/fr/index.html XAMPP] qui vous installera Apache, MySQL et perl. LimeSurvey fonctionne sur une installation de XAMPP sans configuration particuli&egrave;re.<br />
<br />
Si vous souhaitez utiliser le serveur Microsoft IIS veuillez regarder "[[Installation de LimeSurvey sur une machine sous Windows XP]]"<br />
<br />
==1.1 H&eacute;bergement pour LimeSurvey==<br />
<br />
LimeSurvey devrait fonctionner chez la plupart des h&eacute;bergeurs proposant PHP et MySQL. Si vous souhaitez une installation de LimeSurvey toute pr&ecirc;te, vous pouvez utiliser LimeService, vous pouvez aussi consulter la [[LimeSurvey-compatible hosting companies|liste des h&eacute;bergeurs compatibles avec LimeSurvey]].<br />
*Cas particulier de free.fr: Il serait possible d'installer limesurvey sur les serveurs de pages perso de free.fr selon ce [LimeSurvey sur pages perso free.fr|commentaire sur framasoft]. Cette information n'a pas &eacute;t&eacute; v&eacute;rifi&eacute;e.<br />
<br />
=2. T&eacute;l&eacute;chargement du programme LimeSurvey=<br />
<br />
La derni&egrave;re version stable de Limesurvey se trouve sur la [http://www.limesurvey.org/fr/telechargez page de t&eacute;l&eacute;chargement de LimeSurvey] vous pourrez la t&eacute;l&eacute;chargez sous forme d'un fichier d'installation ZIP. Vous trouverez aussi des fichiers compress&eacute;s en gzip, bz2 ou 7zip.<br />
<br />
=3. D&eacute;compression du fichier d'installation de LimeSurvey=<br />
<br />
D&eacute;compressez le fichier ZIP dans un dossier/r&eacute;pertoire d&eacute;di&eacute; avec votre outil de d&eacute;compression pr&eacute;f&eacute;r&eacute;. Assurez-vous que votre logiciel de d&eacute;compression recr&eacute;e bien la structure des dossiers avec les fichiers (c'est normalement le comportement de ce genre de programmes). Le nom du chemin d'installation ne doit pas contenir les caract&egrave;res '''(''' ou ''')''' mais peut contenir des '''espaces'''.<br />
<br />
=4. Collecte d'informations au sujet de votre serveur=<br />
<br />
Vous devez vous renseigner sur les points suivants pour pouvoir installer correctement LimeSurvey sur votre serveur web :<br />
*L'URL pr&eacute;vue pour se connecter au programme (exemple : 'http://mon.domaine.com/limesurvey').<br />
*L'emplacement physique des fichiers sur le serveur (exemple : '/var/www/htdocs/limesurvey').<br />
*L'adresse IP ou le nom d'h&ocirc;te de votre serveur MySQL (exemple : 'localhost')<br />
*Si votre base de donn&eacute;es n'utilise pas le port par d&eacute;faut, vous devrez conna&icirc;tre sur quel port il &eacute;coute.<br />
*Vos nom d'utilisateur et mot de passe pour l'acc&egrave;s &agrave; votre base de donn&eacute;es.<br />
*La plupart des h&eacute;bergeurs n'autorisent pas les scripts &agrave; cr&eacute;er des bases de donn&eacute;es mais c'est &agrave; vous de le faire manuellement. Si vous &ecirc;tes dans ce cas, n'oubliez pas de cr&eacute;er vous-m&ecirc;me une base de donn&eacute;es (par exemple, 'limesurvey')<br />
<br />
=5. Cette partie n'existe plus=<br />
<br />
=6. Envoi des fichiers sur votre serveur web=<br />
<br />
En utilisant votre client FTP favori, connectez-vous &agrave; votre serveur web et cr&eacute;ez un dossier pour y stocker les fichiers de LimeSurvey. Envoyez dans ce dossier l'ensemble des fichiers de LimeSurvey en respectant la structure des dossiers. Nous vous recommandons d'envoyer les fichiers en mode binaire (r&eacute;glage du programme de FTP). En utilisant le mode ASCII, parfois les images sont mal transf&eacute;r&eacute;es.<br />
<br />
=7. D&eacute;finition des permissions des dossiers=<br />
<br />
Pour que le programme fonctionne correctement, il a besoin d'acc&egrave;s &agrave; certains dossiers. Cela s'applique sp&eacute;cialement aux syst&egrave;mes Linux/*nix.<br />
* le dossier '''"/limesurvey/tmp"''' est utilis&eacute; pour les importations et les exportations et doit &ecirc;tre en ''lecture et &eacute;criture'' pour le serveur web.<br />
* le dossier '''"/limesurvey/upload"''' et ses sous-dossiers doivent aussi &ecirc;tre en ''lecture et &eacute;criture'' pour votre serveur web pour activer l'envoi d'images et de fichiers multim&eacute;dias.<br />
* les autres dossiers peuvent &ecirc;tre en ''lecture seule''. Vous pouvez aussi d&eacute;finir des permissions de ''lecture seule'' pour chaque fichier dans le dossier ''/limesurvey/admin''.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Conseil :''' Si vous utilisez Linux alors en fonction de la configuration de votre serveur web vous devrez chmod&eacute; les droits sur les r&eacute;pertoires en &eacute;critures &agrave; 755 ou 777. Essayez 755 en premier et si cela ne marche pas, "passez" &agrave; 777.</div><br />
<br />
=8. Ex&eacute;cution du script d'installation=<br />
<br />
Rendez-vous &agrave; '''"http://votre.domaine.com/limesurvey/admin/install"'''. Si vous avez tout configur&eacute; correctement, vous serez invit&eacute; &agrave; cr&eacute;er la base de donn&eacute;es et/ou les tables dans la base.<br />
<br />
=9. Premi&egrave;re connexion &agrave; l'interface d'administration=<br />
<br />
Vous &ecirc;tes pr&ecirc;t ! Ouvrez votre navigateur et saisissez l'adresse vers le script admin.php. En supposant que vous avez utilis&eacute; limesurvey pour le nom du dossier o&ugrave; vous avez stock&eacute; les fichiers, cela ressemblera &agrave; quelque chose comme-&ccedil;a "http://votre.domaine.com/limesurvey/admin/admin.php".<br />
<br />
Normalement, vous devriez tomber sur un &eacute;cran d'identification. Les valeurs par d&eacute;faut pour pouvoir se connecter sont :<br />
<br />
<div class="simplebox">Utilisateur : admin<br />
<br />
Mot de passe : password</div><br />
<br />
Il vous sera demand&eacute; de changer ce mot de passe apr&egrave;s la premi&egrave;re connexion. Amusez-vous bien !<br />
<br />
=10. En cas de probl&egrave;me...=<br />
<br />
Comme tout programme informatique, les choses se d&eacute;rouleront telles que d&eacute;crites dans les instructions mais, en g&eacute;n&eacute;ral, ce ne sera pas le cas. Il existe de nombreuses de raisons possibles pour que les choses ne se passent pas comme d&eacute;crites ici. Si vous avez des soucis, veuillez d'abord consulter la [[FAQ de l'installation]]. Si vous ne trouvez pas de r&eacute;ponses alors veuillez d&eacute;crire votre probl&egrave;me dans le [http://www.limesurvey.org/component/option,com_fireboard/Itemid,86/lang,fr/ forum de LimeSurvey] sur limesurvey.org.ou essayer de contacter quelqu'un dans le [irc://irc.freenode.net/limesurvey|salon IRC de LimeSurvey] :<br />
<br />
<div class="simplebox"><center>[http://www.limesurvey.org/index.php/Live-Chat.html Lien direct vers le canal IRC officiel de LimeSurvey]</center></div><br />
<br />
=Tutoriels vid&eacute;o=<br />
<br />
Ces tutoriels vid&eacute;o n'ont pas &eacute;t&eacute; cr&eacute;&eacute;s et ne sont pas maintenus par notre &eacute;quipe et doivent &ecirc;tre utilis&eacute;s comme "pense-b&ecirc;te". Ils ne remplacent en rien la lecture des instructions ci-dessus !<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu How to install and configure '''LimeSurvey''' v1.01 in Ubuntu Feisty].<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu Upgrading from '''LimeSurvey''' 1.01 to '''LimeSurvey''' 1.52+ build 3304 2007-09-20 in Ubuntu Feisty].</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_en_Francais&diff=1600Installation en Francais2012-12-08T08:48:43Z<p>Admin: </p>
<hr />
<div><br />
<div class="simplebox">Translation in progress.</div><br />
<br />
<div style="float:right;"><div class="simplebox">Pages suppl&eacute;mentaires:{toc}</div></div>__TOC__<br />
<br />
=1. Pr&eacute;requis pour utiliser LimeSurvey sur votre site web=<br />
<br />
Assurez-vous que votre serveur r&eacute;ponde aux exigences suivantes. La plus part de celle-ci seront v&eacute;rifi&eacute;es durant la phase d'installation :<br />
* 80 Mo d'espace libre pour la plateforme proprement dite.<br />
* MySQL 4.1.0 et versions suivantes '''OU''' Microsoft SQL Server 2005 et versions suivantes '''OU''' Postgres 8.1 et versions suivantes<br />
* PHP 5.1.2 et versions suivantes plus ces extensions :<br />
**mbstring (Multibyte String Functions) pour que le syst&egrave;me de traduction fonctionne. Voir aussi ([http://docs.limesurvey.org/tiki-index.php?page=Installation+FAQ#What_is_this_mbstring_Multibyte_String_Functions_library_ Installation FAQ de l'installation])<br />
**Pilote de base de donn&eacute;es PDO pour MySQL (pdo_mysql ou pdo_mysqli), Postgres (pdo_pgsql) ou MSSQL (pdo_sqlsrv) (cela devra &ecirc;tre le cas avec la plupart des h&eacute;bergeurs. Si vous avez vous-m&ecirc;me configur&eacute; votre serveur web, assurez-vous qu'elles sont install&eacute;es et actives)<br />
<br />
<div class="simplebox"> Attention : LimeSurvey 2.x utilise des pilotes de bases de donn&eacute;es diff&eacute;rents de LimeSurvey 1.x. Si vous voyez apparaitre le message "No DBO driver was found during the installation", veuillez demander &agrave; votre h&eacute;bergeur d'activer la/les extensions appropri&eacute;es mentionn&eacute; ci-avant. </div><br />
<br />
Extensions PHP facultatives :<br />
* '''GD''' install&eacute;e avec le '''support FreeType''' est n&eacute;cessaire pour la protection par CAPTCHA et les jolis graphiques (voir la documentation de l'[http://fr.php.net/manual/fr/image.setup.php extension GD])<br />
* '''IMAP''' pour [[Email bounce tracking system]] (voir la documentation de l'[http://www.php.net/manual/en/imap.setup.php extension IMAP])<br />
* '''LDAP''' pour la cr&eacute;ation d'invitations depuis un annuaire LDAP (voir la documentation de l'[http://fr.php.net/manual/fr/book.ldap.php extension LDAP])<br />
* '''ZLIB''' pour la mise &agrave; jour en 3 clics, le t&eacute;l&eacute;chargement de mod&egrave;les, l'importation de ressources ZIP, etc. (voir la documentation de l'[http://www.php.net/manual/en/zlib.setup.php extension Zlib])<br />
<br />
Dans la plupart des cas, votre h&eacute;bergeur ou votre administrateur syst&egrave;me pourra vous assister sur ces points.<br />
<br />
Si vous souhaitez tester LimeSurvey sur votre propre machine, notamment sous Windows, nous vous conseillons l'utilisation de [http://www.apachefriends.org/fr/index.html XAMPP] qui vous installera Apache, MySQL et perl. LimeSurvey fonctionne sur une installation de XAMPP sans configuration particuli&egrave;re.<br />
<br />
Si vous souhaitez utiliser le serveur Microsoft IIS veuillez regarder "[[Installation de LimeSurvey sur une machine sous Windows XP]]"<br />
<br />
==1.1 H&eacute;bergement pour LimeSurvey==<br />
<br />
LimeSurvey devrait fonctionner chez la plupart des h&eacute;bergeurs proposant PHP et MySQL. Si vous souhaitez une installation de LimeSurvey toute pr&ecirc;te, vous pouvez utiliser LimeService, vous pouvez aussi consulter la [[LimeSurvey-compatible hosting companies|liste des h&eacute;bergeurs compatibles avec LimeSurvey]].<br />
*Cas particulier de free.fr: Il serait possible d'installer limesurvey sur les serveurs de pages perso de free.fr selon ce [LimeSurvey sur pages perso free.fr|commentaire sur framasoft]. Cette information n'a pas &eacute;t&eacute; v&eacute;rifi&eacute;e.<br />
<br />
=2. T&eacute;l&eacute;chargement du programme LimeSurvey=<br />
<br />
La derni&egrave;re version stable de Limesurvey se trouve sur la [http://www.limesurvey.org/fr/telechargez page de t&eacute;l&eacute;chargement de LimeSurvey] vous pourrez la t&eacute;l&eacute;chargez sous forme d'un fichier d'installation ZIP. Vous trouverez aussi des fichiers compress&eacute;s en gzip, bz2 ou 7zip.<br />
<br />
=3. D&eacute;compression du fichier d'installation de LimeSurvey=<br />
<br />
D&eacute;compressez le fichier ZIP dans un dossier/r&eacute;pertoire d&eacute;di&eacute; avec votre outil de d&eacute;compression pr&eacute;f&eacute;r&eacute;. Assurez-vous que votre logiciel de d&eacute;compression recr&eacute;e bien la structure des dossiers avec les fichiers (c'est normalement le comportement de ce genre de programmes). Le nom du chemin d'installation ne doit pas contenir les caract&egrave;res '''(''' ou ''')''' mais peut contenir des '''espaces'''.<br />
<br />
=4. Collecte d'informations au sujet de votre serveur=<br />
<br />
Vous devez vous renseigner sur les points suivants pour pouvoir installer correctement LimeSurvey sur votre serveur web :<br />
*L'URL pr&eacute;vue pour se connecter au programme (exemple : 'http://mon.domaine.com/limesurvey').<br />
*L'emplacement physique des fichiers sur le serveur (exemple : '/var/www/htdocs/limesurvey').<br />
*L'adresse IP ou le nom d'h&ocirc;te de votre serveur MySQL (exemple : 'localhost')<br />
*Si votre base de donn&eacute;es n'utilise pas le port par d&eacute;faut, vous devrez conna&icirc;tre sur quel port il &eacute;coute.<br />
*Vos nom d'utilisateur et mot de passe pour l'acc&egrave;s &agrave; votre base de donn&eacute;es.<br />
*La plupart des h&eacute;bergeurs n'autorisent pas les scripts &agrave; cr&eacute;er des bases de donn&eacute;es mais c'est &agrave; vous de le faire manuellement. Si vous &ecirc;tes dans ce cas, n'oubliez pas de cr&eacute;er vous-m&ecirc;me une base de donn&eacute;es (par exemple, 'limesurvey')<br />
<br />
=5. Configurer LimeSurvey=<br />
<br />
Modifiez le fichier config.php situ&eacute; dans le dossier /limesurvey/ gr&acirc;ce &agrave; votre &eacute;diteur de texte pr&eacute;f&eacute;r&eacute;.<br />
<br />
==5.1 R&eacute;glages obligatoires==<br />
*'''$databasetype''' : d&eacute;finit le type de base de donn&eacute;es utilis&eacute;e. A ce jour, vous pouvez utiliser "mysql" pour une base de donn&eacute;es de type MySQL ou "odbc_mssql" pour une base de type Microsoft SQL server et "postgres" pour une base de type Postgres SQL Server. Seuls ces types ont &eacute;t&eacute; test&eacute;s. (:biggrin:)<br />
*'''$databaselocation''' : d&eacute;finit l'adresse IP ou le nom d'h&ocirc;te de votre serveur de base de donn&eacute;es. Dans la plupart des cas, "localhost" doit convenir.<br />
*'''$databasename''' : d&eacute;finit le nom de la base utilis&eacute;e par LimeSurvey sur votre serveur de base de donn&eacute;es. Si vous avez les permissions suffisantes sur ce serveur, vous pourrez cr&eacute;er une base depuis LimeSurvey. Dans ce cas, indiquez le nom voulu pour cette base ici. Vous pouvez aussi indiquer le nom d'une base cr&eacute;&eacute;e pr&eacute;c&eacute;demment et dans ce cas, assurez-vous que la base ne contient pas d'anciennes tables de LimeSurvey.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Important :''' Si vous utilisez un serveur Microsoft SQL, assurez que votre base utilise une collation non sensible &agrave; la casse (devrait &ecirc;tre la valeur par d&eacute;faut).</div><br />
*'''$databaseuser''' : votre nom d'utilisateur pour l'acc&egrave;s &agrave; la base de donn&eacute;es.<br />
*'''$databasepass''' : votre mot de passe pour l'acc&egrave;s au serveur de base de donn&eacute;es.<br />
*'''$dbprefix''' : vous pouvez laisser ce r&eacute;glage &agrave; blanc (c&agrave;d : $dbprefix="";) si vous utilisez une base d&eacute;di&eacute;e &agrave; LimeSurvey. Si vous voulez ou devez partager votre base entre LimeSurvey et d'autres programmes utilisant la m&ecirc;me base de donn&eacute;es, ajoutez un pr&eacute;fixe pour le nom des tables avec ce r&eacute;glage. Le param&egrave;tre recommand&eacute; est "lime_" mais vous pouvez mettre ce que vous voulez.<br />
<br />
+''Note : La cr&eacute;ation d'une base de donn&eacute;es MySQL est d&eacute;crite dans la [[FAQ de l'installation]].''<br />
*'''$rooturl''' : indique l'adresse URL pour acc&eacute;der &agrave; votre questionnaire. Si vous avez copi&eacute; les fichiers de LimeSurvey dans un dossier ''repertoireLS'' vous devrez renommer ''.../limesurvey'' avec le nom que vous avez choisi (''repertoireLS''). Le r&eacute;glage par d&eacute;faut essaie de trouver &ccedil;a automatiquement pour vous et, la plupart du temps, ce r&eacute;glage ne devra pas &ecirc;tre modifi&eacute; (le code {$_SERVER<nowiki>[</nowiki>'SERVER_NAME']} devrait fonctionner dans la majorit&eacute; des cas). Si cela ne fonctionne pas, vous devrez entrer manuellement l'adresse ici, par exemple "http://www.mydomain.com/limesurvey"). Si vous souhaitez que LimeSurvey utilise SSL, changez http en https (en consid&eacute;rant que les certificats SSL sont correctement install&eacute;s et configur&eacute;s sur votre serveur)<br />
*'''$rootdir''' : doit contenir le chemin physique vers les fichiers du programme. Le r&eacute;glage par d&eacute;faut essaie de trouver cette valeur pour vous et, la plupart du temps, ce r&eacute;glage ne devra pas &ecirc;tre modifi&eacute; (le code "dirname(!!!FILE!!!);" essaie de trouver automatiquement). Si cela ne fonctionne pas, vous devrez entrer manuellement l'emplacement physique des fichiers, par exemple "/home/public_html/limesurvey".)<br />
*'''$defaultuser''' : quand le programme utilise le contr&ocirc;le d'acc&egrave;s, ceci est l'utilisateur par d&eacute;faut cr&eacute;&eacute; quand LimeSurvey initialise la s&eacute;curit&eacute; pour la premi&egrave;re fois.<br />
*'''$defaultpass''' : quand le programme utilise le contr&ocirc;le d'acc&egrave;s, ceci est le mot de passe par d&eacute;faut utilis&eacute; quand LimeSurvey initialise la s&eacute;curit&eacute; pour la premi&egrave;re fois.<br />
<br />
+'''Note''' : ce param&egrave;tre est utilis&eacute; '''seulement''' pour la configuration initiale. Quand l'utilisateur par d&eacute;faut ''$defaultuser'' est d&eacute;j&agrave; cr&eacute;&eacute;, cette option n'est plus utilis&eacute;e. Vous devrez changer votre mot de passe dans la gestion des utilisateurs.<br />
<br />
==5.2 R&eacute;glages optionnels==<br />
<br />
Il existe plusieurs autres r&eacute;glages optionnels que vous pouvez d&eacute;finir dans config.php. Veuillez consultez la page des [[r&eacute;glages optionnels]]. Cependant, pour une configuration de base, poursuivez &agrave; l'&eacute;tape suivante.<br />
<br />
=6. Envoi des fichiers sur votre serveur web=<br />
<br />
En utilisant votre client FTP favori, connectez-vous &agrave; votre serveur web et cr&eacute;ez un dossier pour y stocker les fichiers de LimeSurvey. Envoyez dans ce dossier l'ensemble des fichiers de LimeSurvey en respectant la structure des dossiers. Nous vous recommandons d'envoyer les fichiers en mode binaire (r&eacute;glage du programme de FTP). En utilisant le mode ASCII, parfois les images sont mal transf&eacute;r&eacute;es.<br />
<br />
=7. D&eacute;finition des permissions des dossiers=<br />
<br />
Pour que le programme fonctionne correctement, il a besoin d'acc&egrave;s &agrave; certains dossiers. Cela s'applique sp&eacute;cialement aux syst&egrave;mes Linux/*nix.<br />
* le dossier '''"/limesurvey/tmp"''' est utilis&eacute; pour les importations et les exportations et doit &ecirc;tre en ''lecture et &eacute;criture'' pour le serveur web.<br />
* le dossier '''"/limesurvey/upload"''' et ses sous-dossiers doivent aussi &ecirc;tre en ''lecture et &eacute;criture'' pour votre serveur web pour activer l'envoi d'images et de fichiers multim&eacute;dias.<br />
* les autres dossiers peuvent &ecirc;tre en ''lecture seule''. Vous pouvez aussi d&eacute;finir des permissions de ''lecture seule'' pour chaque fichier dans le dossier ''/limesurvey/admin''.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Conseil :''' Si vous utilisez Linux alors en fonction de la configuration de votre serveur web vous devrez chmod&eacute; les droits sur les r&eacute;pertoires en &eacute;critures &agrave; 755 ou 777. Essayez 755 en premier et si cela ne marche pas, "passez" &agrave; 777.</div><br />
<br />
=8. Ex&eacute;cution du script d'installation=<br />
<br />
Rendez-vous &agrave; '''"http://votre.domaine.com/limesurvey/admin/install"'''. Si vous avez tout configur&eacute; correctement, vous serez invit&eacute; &agrave; cr&eacute;er la base de donn&eacute;es et/ou les tables dans la base.<br />
<br />
=9. Premi&egrave;re connexion &agrave; l'interface d'administration=<br />
<br />
Vous &ecirc;tes pr&ecirc;t ! Ouvrez votre navigateur et saisissez l'adresse vers le script admin.php. En supposant que vous avez utilis&eacute; limesurvey pour le nom du dossier o&ugrave; vous avez stock&eacute; les fichiers, cela ressemblera &agrave; quelque chose comme-&ccedil;a "http://votre.domaine.com/limesurvey/admin/admin.php".<br />
<br />
Normalement, vous devriez tomber sur un &eacute;cran d'identification. Les valeurs par d&eacute;faut pour pouvoir se connecter sont :<br />
<br />
<div class="simplebox">Utilisateur : admin<br />
<br />
Mot de passe : password</div><br />
<br />
Il vous sera demand&eacute; de changer ce mot de passe apr&egrave;s la premi&egrave;re connexion. Amusez-vous bien !<br />
<br />
=10. En cas de probl&egrave;me...=<br />
<br />
Comme tout programme informatique, les choses se d&eacute;rouleront telles que d&eacute;crites dans les instructions mais, en g&eacute;n&eacute;ral, ce ne sera pas le cas. Il existe de nombreuses de raisons possibles pour que les choses ne se passent pas comme d&eacute;crites ici. Si vous avez des soucis, veuillez d'abord consulter la [[FAQ de l'installation]]. Si vous ne trouvez pas de r&eacute;ponses alors veuillez d&eacute;crire votre probl&egrave;me dans le [http://www.limesurvey.org/component/option,com_fireboard/Itemid,86/lang,fr/ forum de LimeSurvey] sur limesurvey.org.ou essayer de contacter quelqu'un dans le [irc://irc.freenode.net/limesurvey|salon IRC de LimeSurvey] :<br />
<br />
<div class="simplebox"><center>[http://www.limesurvey.org/index.php/Live-Chat.html Lien direct vers le canal IRC officiel de LimeSurvey]</center></div><br />
<br />
=Tutoriels vid&eacute;o=<br />
<br />
Ces tutoriels vid&eacute;o n'ont pas &eacute;t&eacute; cr&eacute;&eacute;s et ne sont pas maintenus par notre &eacute;quipe et doivent &ecirc;tre utilis&eacute;s comme "pense-b&ecirc;te". Ils ne remplacent en rien la lecture des instructions ci-dessus !<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu How to install and configure '''LimeSurvey''' v1.01 in Ubuntu Feisty].<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu Upgrading from '''LimeSurvey''' 1.01 to '''LimeSurvey''' 1.52+ build 3304 2007-09-20 in Ubuntu Feisty].</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_en_Francais&diff=1635Installation en Francais2012-12-08T08:47:51Z<p>Admin: </p>
<hr />
<div><br />
<div class="simplebox">Translation in progress.</div><br />
<br />
<div style="float:right;"><div class="simplebox">Pages suppl&eacute;mentaires:{toc}</div></div>__TOC__<br />
<br />
=1. Pr&eacute;requis pour utiliser LimeSurvey sur votre site web=<br />
<br />
Assurez-vous que votre serveur r&eacute;ponde aux exigences suivantes. La plus part de celle-ci seront v&eacute;rifi&eacute;es durant la phase d'installation :<br />
* 80 Mo d'espace libre pour la plateforme proprement dite.<br />
* MySQL 4.1.0 et versions suivantes '''OU''' Microsoft SQL Server 2005 et versions suivantes '''OU''' Postgres 8.1 et versions suivantes<br />
* PHP 5.1.2 et versions suivantes plus ces extensions :<br />
**mbstring (Multibyte String Functions) pour que le syst&egrave;me de traduction fonctionne. Voir aussi ([http://docs.limesurvey.org/tiki-index.php?page=Installation+FAQ#What_is_this_mbstring_Multibyte_String_Functions_library_ Installation FAQ de l'installation])<br />
**Pilote de base de donn&eacute;es PDO pour MySQL (pdo_mysql ou pdo_mysqli), Postgres (pdo_pgsql) ou MSSQL (pdo_sqlsrv) (cela devra &ecirc;tre le cas avec la plupart des h&eacute;bergeurs. Si vous avez vous-m&ecirc;me configur&eacute; votre serveur web, assurez-vous qu'elles sont install&eacute;es et actives)<br />
<br />
<div class="simplebox"> Attention : LimeSurvey 2.x utilise des pilotes de bases de donn&eacute;es diff&eacute;rents de LimeSurvey 1.x. Si vous voyez apparaitre le message "No DBO driver was found during the installation", veuillez demander &agrave; votre h&eacute;bergeur d'activer la/les extensions appropri&eacute;es mentionn&eacute; ci-avant. </div><br />
<br />
Extensions PHP facultatives :<br />
* '''GD''' install&eacute;e avec le '''support FreeType''' est n&eacute;cessaire pour la protection par CAPTCHA et les jolis graphiques (voir la documentation de l'[http://fr.php.net/manual/fr/image.setup.php extension GD])<br />
* '''IMAP''' pour [[Email bounce tracking system]] (voir la documentation de l'[http://www.php.net/manual/en/imap.setup.php extension IMAP])<br />
* '''LDAP''' pour la cr&eacute;ation d'invitations depuis un annuaire LDAP (voir la documentation de l'[http://fr.php.net/manual/fr/book.ldap.php extension LDAP])<br />
* '''ZLIB''' pour la mise &agrave; jour en 3 clics, le t&eacute;l&eacute;chargement de mod&egrave;les, l'importation de ressources ZIP, etc. (voir la documentation de l'[http://www.php.net/manual/en/zlib.setup.php extension Zlib])<br />
<br />
Dans la plupart des cas, votre h&eacute;bergeur ou votre administrateur syst&egrave;me pourra vous assister sur ces points.<br />
<br />
Si vous souhaitez tester LimeSurvey sur votre propre machine, notamment sous Windows, nous vous conseillons l'utilisation de [http://www.apachefriends.org/fr/index.html XAMPP] qui vous installera Apache, MySQL et perl. LimeSurvey fonctionne sur une installation de XAMPP sans configuration particuli&egrave;re.<br />
<br />
Si vous souhaitez utiliser le serveur Microsoft IIS veuillez regarder "[[Installation de LimeSurvey sur une machine sous Windows XP]]"<br />
<br />
==1.1 H&eacute;bergement pour LimeSurvey==<br />
<br />
LimeSurvey devrait fonctionner chez la plupart des h&eacute;bergeurs proposant PHP et MySQL. Si vous souhaitez une installation de LimeSurvey toute pr&ecirc;te, vous pouvez utiliser LimeService, vous pouvez aussi consulter la [[LimeSurvey-compatible hosting companies|liste des h&eacute;bergeurs compatibles avec LimeSurvey]].<br />
*Cas particulier de free.fr: Il serait possible d'installer limesurvey sur les serveurs de pages perso de free.fr selon ce [LimeSurvey sur pages perso free.fr|commentaire sur framasoft]. Cette information n'a pas &eacute;t&eacute; v&eacute;rifi&eacute;e.<br />
<br />
=2. T&eacute;l&eacute;chargement du programme LimeSurvey=<br />
<br />
La derni&egrave;re version stable de Limesurvey se trouve sur la [http://www.limesurvey.org/fr/telechargez T&eacute;l&eacute;charger page de t&eacute;l&eacute;chargement de LimeSurvey] vous pourrez la t&eacute;l&eacute;chargez sous forme d'un fichier d'installation ZIP. Vous trouverez aussi des fichiers compress&eacute;s en gzip, bz2 ou 7zip.<br />
<br />
=3. D&eacute;compression du fichier d'installation de LimeSurvey=<br />
<br />
D&eacute;compressez le fichier ZIP dans un dossier/r&eacute;pertoire d&eacute;di&eacute; avec votre outil de d&eacute;compression pr&eacute;f&eacute;r&eacute;. Assurez-vous que votre logiciel de d&eacute;compression recr&eacute;e bien la structure des dossiers avec les fichiers (c'est normalement le comportement de ce genre de programmes). Le nom du chemin d'installation ne doit pas contenir les caract&egrave;res '''(''' ou ''')''' mais peut contenir des '''espaces'''.<br />
<br />
=4. Collecte d'informations au sujet de votre serveur=<br />
<br />
Vous devez vous renseigner sur les points suivants pour pouvoir installer correctement LimeSurvey sur votre serveur web :<br />
*L'URL pr&eacute;vue pour se connecter au programme (exemple : 'http://mon.domaine.com/limesurvey').<br />
*L'emplacement physique des fichiers sur le serveur (exemple : '/var/www/htdocs/limesurvey').<br />
*L'adresse IP ou le nom d'h&ocirc;te de votre serveur MySQL (exemple : 'localhost')<br />
*Si votre base de donn&eacute;es n'utilise pas le port par d&eacute;faut, vous devrez conna&icirc;tre sur quel port il &eacute;coute.<br />
*Vos nom d'utilisateur et mot de passe pour l'acc&egrave;s &agrave; votre base de donn&eacute;es.<br />
*La plupart des h&eacute;bergeurs n'autorisent pas les scripts &agrave; cr&eacute;er des bases de donn&eacute;es mais c'est &agrave; vous de le faire manuellement. Si vous &ecirc;tes dans ce cas, n'oubliez pas de cr&eacute;er vous-m&ecirc;me une base de donn&eacute;es (par exemple, 'limesurvey')<br />
<br />
=5. Configurer LimeSurvey=<br />
<br />
Modifiez le fichier config.php situ&eacute; dans le dossier /limesurvey/ gr&acirc;ce &agrave; votre &eacute;diteur de texte pr&eacute;f&eacute;r&eacute;.<br />
<br />
==5.1 R&eacute;glages obligatoires==<br />
*'''$databasetype''' : d&eacute;finit le type de base de donn&eacute;es utilis&eacute;e. A ce jour, vous pouvez utiliser "mysql" pour une base de donn&eacute;es de type MySQL ou "odbc_mssql" pour une base de type Microsoft SQL server et "postgres" pour une base de type Postgres SQL Server. Seuls ces types ont &eacute;t&eacute; test&eacute;s. (:biggrin:)<br />
*'''$databaselocation''' : d&eacute;finit l'adresse IP ou le nom d'h&ocirc;te de votre serveur de base de donn&eacute;es. Dans la plupart des cas, "localhost" doit convenir.<br />
*'''$databasename''' : d&eacute;finit le nom de la base utilis&eacute;e par LimeSurvey sur votre serveur de base de donn&eacute;es. Si vous avez les permissions suffisantes sur ce serveur, vous pourrez cr&eacute;er une base depuis LimeSurvey. Dans ce cas, indiquez le nom voulu pour cette base ici. Vous pouvez aussi indiquer le nom d'une base cr&eacute;&eacute;e pr&eacute;c&eacute;demment et dans ce cas, assurez-vous que la base ne contient pas d'anciennes tables de LimeSurvey.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Important :''' Si vous utilisez un serveur Microsoft SQL, assurez que votre base utilise une collation non sensible &agrave; la casse (devrait &ecirc;tre la valeur par d&eacute;faut).</div><br />
*'''$databaseuser''' : votre nom d'utilisateur pour l'acc&egrave;s &agrave; la base de donn&eacute;es.<br />
*'''$databasepass''' : votre mot de passe pour l'acc&egrave;s au serveur de base de donn&eacute;es.<br />
*'''$dbprefix''' : vous pouvez laisser ce r&eacute;glage &agrave; blanc (c&agrave;d : $dbprefix="";) si vous utilisez une base d&eacute;di&eacute;e &agrave; LimeSurvey. Si vous voulez ou devez partager votre base entre LimeSurvey et d'autres programmes utilisant la m&ecirc;me base de donn&eacute;es, ajoutez un pr&eacute;fixe pour le nom des tables avec ce r&eacute;glage. Le param&egrave;tre recommand&eacute; est "lime_" mais vous pouvez mettre ce que vous voulez.<br />
<br />
+''Note : La cr&eacute;ation d'une base de donn&eacute;es MySQL est d&eacute;crite dans la [[FAQ de l'installation]].''<br />
*'''$rooturl''' : indique l'adresse URL pour acc&eacute;der &agrave; votre questionnaire. Si vous avez copi&eacute; les fichiers de LimeSurvey dans un dossier ''repertoireLS'' vous devrez renommer ''.../limesurvey'' avec le nom que vous avez choisi (''repertoireLS''). Le r&eacute;glage par d&eacute;faut essaie de trouver &ccedil;a automatiquement pour vous et, la plupart du temps, ce r&eacute;glage ne devra pas &ecirc;tre modifi&eacute; (le code {$_SERVER<nowiki>[</nowiki>'SERVER_NAME']} devrait fonctionner dans la majorit&eacute; des cas). Si cela ne fonctionne pas, vous devrez entrer manuellement l'adresse ici, par exemple "http://www.mydomain.com/limesurvey"). Si vous souhaitez que LimeSurvey utilise SSL, changez http en https (en consid&eacute;rant que les certificats SSL sont correctement install&eacute;s et configur&eacute;s sur votre serveur)<br />
*'''$rootdir''' : doit contenir le chemin physique vers les fichiers du programme. Le r&eacute;glage par d&eacute;faut essaie de trouver cette valeur pour vous et, la plupart du temps, ce r&eacute;glage ne devra pas &ecirc;tre modifi&eacute; (le code "dirname(!!!FILE!!!);" essaie de trouver automatiquement). Si cela ne fonctionne pas, vous devrez entrer manuellement l'emplacement physique des fichiers, par exemple "/home/public_html/limesurvey".)<br />
*'''$defaultuser''' : quand le programme utilise le contr&ocirc;le d'acc&egrave;s, ceci est l'utilisateur par d&eacute;faut cr&eacute;&eacute; quand LimeSurvey initialise la s&eacute;curit&eacute; pour la premi&egrave;re fois.<br />
*'''$defaultpass''' : quand le programme utilise le contr&ocirc;le d'acc&egrave;s, ceci est le mot de passe par d&eacute;faut utilis&eacute; quand LimeSurvey initialise la s&eacute;curit&eacute; pour la premi&egrave;re fois.<br />
<br />
+'''Note''' : ce param&egrave;tre est utilis&eacute; '''seulement''' pour la configuration initiale. Quand l'utilisateur par d&eacute;faut ''$defaultuser'' est d&eacute;j&agrave; cr&eacute;&eacute;, cette option n'est plus utilis&eacute;e. Vous devrez changer votre mot de passe dans la gestion des utilisateurs.<br />
<br />
==5.2 R&eacute;glages optionnels==<br />
<br />
Il existe plusieurs autres r&eacute;glages optionnels que vous pouvez d&eacute;finir dans config.php. Veuillez consultez la page des [[r&eacute;glages optionnels]]. Cependant, pour une configuration de base, poursuivez &agrave; l'&eacute;tape suivante.<br />
<br />
=6. Envoi des fichiers sur votre serveur web=<br />
<br />
En utilisant votre client FTP favori, connectez-vous &agrave; votre serveur web et cr&eacute;ez un dossier pour y stocker les fichiers de LimeSurvey. Envoyez dans ce dossier l'ensemble des fichiers de LimeSurvey en respectant la structure des dossiers. Nous vous recommandons d'envoyer les fichiers en mode binaire (r&eacute;glage du programme de FTP). En utilisant le mode ASCII, parfois les images sont mal transf&eacute;r&eacute;es.<br />
<br />
=7. D&eacute;finition des permissions des dossiers=<br />
<br />
Pour que le programme fonctionne correctement, il a besoin d'acc&egrave;s &agrave; certains dossiers. Cela s'applique sp&eacute;cialement aux syst&egrave;mes Linux/*nix.<br />
* le dossier '''"/limesurvey/tmp"''' est utilis&eacute; pour les importations et les exportations et doit &ecirc;tre en ''lecture et &eacute;criture'' pour le serveur web.<br />
* le dossier '''"/limesurvey/upload"''' et ses sous-dossiers doivent aussi &ecirc;tre en ''lecture et &eacute;criture'' pour votre serveur web pour activer l'envoi d'images et de fichiers multim&eacute;dias.<br />
* les autres dossiers peuvent &ecirc;tre en ''lecture seule''. Vous pouvez aussi d&eacute;finir des permissions de ''lecture seule'' pour chaque fichier dans le dossier ''/limesurvey/admin''.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Conseil :''' Si vous utilisez Linux alors en fonction de la configuration de votre serveur web vous devrez chmod&eacute; les droits sur les r&eacute;pertoires en &eacute;critures &agrave; 755 ou 777. Essayez 755 en premier et si cela ne marche pas, "passez" &agrave; 777.</div><br />
<br />
=8. Ex&eacute;cution du script d'installation=<br />
<br />
Rendez-vous &agrave; '''"http://votre.domaine.com/limesurvey/admin/install"'''. Si vous avez tout configur&eacute; correctement, vous serez invit&eacute; &agrave; cr&eacute;er la base de donn&eacute;es et/ou les tables dans la base.<br />
<br />
=9. Premi&egrave;re connexion &agrave; l'interface d'administration=<br />
<br />
Vous &ecirc;tes pr&ecirc;t ! Ouvrez votre navigateur et saisissez l'adresse vers le script admin.php. En supposant que vous avez utilis&eacute; limesurvey pour le nom du dossier o&ugrave; vous avez stock&eacute; les fichiers, cela ressemblera &agrave; quelque chose comme-&ccedil;a "http://votre.domaine.com/limesurvey/admin/admin.php".<br />
<br />
Normalement, vous devriez tomber sur un &eacute;cran d'identification. Les valeurs par d&eacute;faut pour pouvoir se connecter sont :<br />
<br />
<div class="simplebox">Utilisateur : admin<br />
<br />
Mot de passe : password</div><br />
<br />
Il vous sera demand&eacute; de changer ce mot de passe apr&egrave;s la premi&egrave;re connexion. Amusez-vous bien !<br />
<br />
=10. En cas de probl&egrave;me...=<br />
<br />
Comme tout programme informatique, les choses se d&eacute;rouleront telles que d&eacute;crites dans les instructions mais, en g&eacute;n&eacute;ral, ce ne sera pas le cas. Il existe de nombreuses de raisons possibles pour que les choses ne se passent pas comme d&eacute;crites ici. Si vous avez des soucis, veuillez d'abord consulter la [[FAQ de l'installation]]. Si vous ne trouvez pas de r&eacute;ponses alors veuillez d&eacute;crire votre probl&egrave;me dans le [http://www.limesurvey.org/component/option,com_fireboard/Itemid,86/lang,fr/ forum de LimeSurvey] sur limesurvey.org.ou essayer de contacter quelqu'un dans le [irc://irc.freenode.net/limesurvey|salon IRC de LimeSurvey] :<br />
<br />
<div class="simplebox"><center>[http://www.limesurvey.org/index.php/Live-Chat.html Lien direct vers le canal IRC officiel de LimeSurvey]</center></div><br />
<br />
=Tutoriels vid&eacute;o=<br />
<br />
Ces tutoriels vid&eacute;o n'ont pas &eacute;t&eacute; cr&eacute;&eacute;s et ne sont pas maintenus par notre &eacute;quipe et doivent &ecirc;tre utilis&eacute;s comme "pense-b&ecirc;te". Ils ne remplacent en rien la lecture des instructions ci-dessus !<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu How to install and configure '''LimeSurvey''' v1.01 in Ubuntu Feisty].<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu Upgrading from '''LimeSurvey''' 1.01 to '''LimeSurvey''' 1.52+ build 3304 2007-09-20 in Ubuntu Feisty].</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_en_Francais&diff=1636Installation en Francais2012-12-08T08:46:13Z<p>Admin: </p>
<hr />
<div><br />
<div class="simplebox">Translation in progress.</div><br />
<br />
<div style="float:right;"><div class="simplebox">Pages suppl&eacute;mentaires:{toc}</div></div>__TOC__<br />
<br />
=1. Pr&eacute;requis pour utiliser LimeSurvey sur votre site web=<br />
<br />
Assurez-vous que votre serveur r&eacute;ponde aux exigences suivantes. La plus part de celle-ci seront v&eacute;rifi&eacute;es durant la phase d'installation :<br />
* 80 Mo d'espace libre pour la plateforme proprement dite.<br />
* MySQL 4.1.0 et versions suivantes '''OU''' Microsoft SQL Server 2005 et versions suivantes '''OU''' Postgres 8.1 et versions suivantes<br />
* PHP 5.1.2 et versions suivantes plus ces extensions :<br />
**mbstring (Multibyte String Functions) pour que le syst&egrave;me de traduction fonctionne. Voir aussi ([http://docs.limesurvey.org/tiki-index.php?page=Installation+FAQ#What_is_this_mbstring_Multibyte_String_Functions_library_ Installation FAQ de l'installation])<br />
**Pilote de base de donn&eacute;es PDO pour MySQL (pdo_mysql ou pdo_mysqli), Postgres (pdo_pgsql) ou MSSQL (pdo_sqlsrv) (cela devra &ecirc;tre le cas avec la plupart des h&eacute;bergeurs. Si vous avez vous-m&ecirc;me configur&eacute; votre serveur web, assurez-vous qu'elles sont install&eacute;es et actives)<br />
<br />
<div class="simplebox"> Attention : LimeSurvey 2.x utilise des pilotes de bases de donn&eacute;es diff&eacute;rents de LimeSurvey 1.x. Si vous voyez apparaitre le message "No DBO driver was found during the installation", veuillez demander &agrave; votre h&eacute;bergeur d'activer la/les extensions appropri&eacute;es mentionn&eacute; ci-avant. </div><br />
<br />
Extensions PHP facultatives :<br />
* '''GD''' install&eacute;e avec le '''support FreeType''' est n&eacute;cessaire pour la protection par CAPTCHA et les jolis graphiques (voir la documentation de l'[http://fr.php.net/manual/fr/image.setup.php extension GD])<br />
* '''IMAP''' pour [[Email bounce tracking system]] (voir la documentation de l'[http://www.php.net/manual/en/imap.setup.php extension IMAP])<br />
* '''LDAP''' pour la cr&eacute;ation d'invitations depuis un annuaire LDAP (voir la documentation de l'[http://fr.php.net/manual/fr/book.ldap.php extension LDAP])<br />
* '''ZLIB''' pour la mise &agrave; jour en 3 clics, le t&eacute;l&eacute;chargement de mod&egrave;les, l'importation de ressources ZIP, etc. (voir la documentation de l'[http://www.php.net/manual/en/zlib.setup.php extension Zlib])<br />
<br />
Dans la plupart des cas, votre h&eacute;bergeur ou votre administrateur syst&egrave;me pourra vous assister sur ces points.<br />
<br />
Si vous souhaitez tester LimeSurvey sur votre propre machine, notamment sous Windows, nous vous conseillons l'utilisation de [http://www.apachefriends.org/fr/index.html XAMPP] qui vous installera Apache, MySQL et perl. LimeSurvey fonctionne sur une installation de XAMPP sans configuration particuli&egrave;re.<br />
<br />
Si vous souhaitez utiliser le serveur Microsoft IIS veuillez regarder "[[Installation de LimeSurvey sur une machine sous Windows XP]]"<br />
<br />
==1.1 H&eacute;bergement pour LimeSurvey==<br />
<br />
LimeSurvey devrait fonctionner chez la plupart des h&eacute;bergeurs proposant PHP et MySQL. Si vous souhaitez une installation de LimeSurvey toute pr&ecirc;te, vous pouvez utiliser LimeService, vous pouvez aussi consulter la [[LimeSurvey-compatible hosting companies|liste des h&eacute;bergeurs compatibles avec LimeSurvey]].<br />
*Cas particulier de free.fr: Il serait possible d'installer limesurvey sur les serveurs de pages perso de free.fr selon ce [LimeSurvey sur pages perso free.fr|commentaire sur framasoft]. Cette information n'a pas &eacute;t&eacute; v&eacute;rifi&eacute;e.<br />
<br />
=2. T&eacute;l&eacute;chargement du programme LimeSurvey=<br />
<br />
La derni&egrave;re version stable de Limesurvey se trouve sur la [http://www.limesurvey.org/en/download Download page de t&eacute;l&eacute;chargement de LimeSurvey sur sourceforge (en anglais)] vous pourrez la t&eacute;l&eacute;chargez sous forme d'un fichier d'installation ZIP. Vous trouverez aussi des fichiers compress&eacute;s en gzip, bz2 ou 7zip.<br />
<br />
=3. D&eacute;compression du fichier d'installation de LimeSurvey=<br />
<br />
D&eacute;compressez le fichier ZIP dans un dossier/r&eacute;pertoire d&eacute;di&eacute; avec votre outil de d&eacute;compression pr&eacute;f&eacute;r&eacute;. Assurez-vous que votre logiciel de d&eacute;compression recr&eacute;e bien la structure des dossiers avec les fichiers (c'est normalement le comportement de ce genre de programmes). Le nom du chemin d'installation ne doit pas contenir les caract&egrave;res '''(''' ou ''')''' mais peut contenir des '''espaces'''.<br />
<br />
=4. Collecte d'informations au sujet de votre serveur=<br />
<br />
Vous devez vous renseigner sur les points suivants pour pouvoir installer correctement LimeSurvey sur votre serveur web :<br />
*L'URL pr&eacute;vue pour se connecter au programme (exemple : 'http://mon.domaine.com/limesurvey').<br />
*L'emplacement physique des fichiers sur le serveur (exemple : '/var/www/htdocs/limesurvey').<br />
*L'adresse IP ou le nom d'h&ocirc;te de votre serveur MySQL (exemple : 'localhost')<br />
*Si votre base de donn&eacute;es n'utilise pas le port par d&eacute;faut, vous devrez conna&icirc;tre sur quel port il &eacute;coute.<br />
*Vos nom d'utilisateur et mot de passe pour l'acc&egrave;s &agrave; votre base de donn&eacute;es.<br />
*La plupart des h&eacute;bergeurs n'autorisent pas les scripts &agrave; cr&eacute;er des bases de donn&eacute;es mais c'est &agrave; vous de le faire manuellement. Si vous &ecirc;tes dans ce cas, n'oubliez pas de cr&eacute;er vous-m&ecirc;me une base de donn&eacute;es (par exemple, 'limesurvey')<br />
<br />
=5. Configurer LimeSurvey=<br />
<br />
Modifiez le fichier config.php situ&eacute; dans le dossier /limesurvey/ gr&acirc;ce &agrave; votre &eacute;diteur de texte pr&eacute;f&eacute;r&eacute;.<br />
<br />
==5.1 R&eacute;glages obligatoires==<br />
*'''$databasetype''' : d&eacute;finit le type de base de donn&eacute;es utilis&eacute;e. A ce jour, vous pouvez utiliser "mysql" pour une base de donn&eacute;es de type MySQL ou "odbc_mssql" pour une base de type Microsoft SQL server et "postgres" pour une base de type Postgres SQL Server. Seuls ces types ont &eacute;t&eacute; test&eacute;s. (:biggrin:)<br />
*'''$databaselocation''' : d&eacute;finit l'adresse IP ou le nom d'h&ocirc;te de votre serveur de base de donn&eacute;es. Dans la plupart des cas, "localhost" doit convenir.<br />
*'''$databasename''' : d&eacute;finit le nom de la base utilis&eacute;e par LimeSurvey sur votre serveur de base de donn&eacute;es. Si vous avez les permissions suffisantes sur ce serveur, vous pourrez cr&eacute;er une base depuis LimeSurvey. Dans ce cas, indiquez le nom voulu pour cette base ici. Vous pouvez aussi indiquer le nom d'une base cr&eacute;&eacute;e pr&eacute;c&eacute;demment et dans ce cas, assurez-vous que la base ne contient pas d'anciennes tables de LimeSurvey.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Important :''' Si vous utilisez un serveur Microsoft SQL, assurez que votre base utilise une collation non sensible &agrave; la casse (devrait &ecirc;tre la valeur par d&eacute;faut).</div><br />
*'''$databaseuser''' : votre nom d'utilisateur pour l'acc&egrave;s &agrave; la base de donn&eacute;es.<br />
*'''$databasepass''' : votre mot de passe pour l'acc&egrave;s au serveur de base de donn&eacute;es.<br />
*'''$dbprefix''' : vous pouvez laisser ce r&eacute;glage &agrave; blanc (c&agrave;d : $dbprefix="";) si vous utilisez une base d&eacute;di&eacute;e &agrave; LimeSurvey. Si vous voulez ou devez partager votre base entre LimeSurvey et d'autres programmes utilisant la m&ecirc;me base de donn&eacute;es, ajoutez un pr&eacute;fixe pour le nom des tables avec ce r&eacute;glage. Le param&egrave;tre recommand&eacute; est "lime_" mais vous pouvez mettre ce que vous voulez.<br />
<br />
+''Note : La cr&eacute;ation d'une base de donn&eacute;es MySQL est d&eacute;crite dans la [[FAQ de l'installation]].''<br />
*'''$rooturl''' : indique l'adresse URL pour acc&eacute;der &agrave; votre questionnaire. Si vous avez copi&eacute; les fichiers de LimeSurvey dans un dossier ''repertoireLS'' vous devrez renommer ''.../limesurvey'' avec le nom que vous avez choisi (''repertoireLS''). Le r&eacute;glage par d&eacute;faut essaie de trouver &ccedil;a automatiquement pour vous et, la plupart du temps, ce r&eacute;glage ne devra pas &ecirc;tre modifi&eacute; (le code {$_SERVER<nowiki>[</nowiki>'SERVER_NAME']} devrait fonctionner dans la majorit&eacute; des cas). Si cela ne fonctionne pas, vous devrez entrer manuellement l'adresse ici, par exemple "http://www.mydomain.com/limesurvey"). Si vous souhaitez que LimeSurvey utilise SSL, changez http en https (en consid&eacute;rant que les certificats SSL sont correctement install&eacute;s et configur&eacute;s sur votre serveur)<br />
*'''$rootdir''' : doit contenir le chemin physique vers les fichiers du programme. Le r&eacute;glage par d&eacute;faut essaie de trouver cette valeur pour vous et, la plupart du temps, ce r&eacute;glage ne devra pas &ecirc;tre modifi&eacute; (le code "dirname(!!!FILE!!!);" essaie de trouver automatiquement). Si cela ne fonctionne pas, vous devrez entrer manuellement l'emplacement physique des fichiers, par exemple "/home/public_html/limesurvey".)<br />
*'''$defaultuser''' : quand le programme utilise le contr&ocirc;le d'acc&egrave;s, ceci est l'utilisateur par d&eacute;faut cr&eacute;&eacute; quand LimeSurvey initialise la s&eacute;curit&eacute; pour la premi&egrave;re fois.<br />
*'''$defaultpass''' : quand le programme utilise le contr&ocirc;le d'acc&egrave;s, ceci est le mot de passe par d&eacute;faut utilis&eacute; quand LimeSurvey initialise la s&eacute;curit&eacute; pour la premi&egrave;re fois.<br />
<br />
+'''Note''' : ce param&egrave;tre est utilis&eacute; '''seulement''' pour la configuration initiale. Quand l'utilisateur par d&eacute;faut ''$defaultuser'' est d&eacute;j&agrave; cr&eacute;&eacute;, cette option n'est plus utilis&eacute;e. Vous devrez changer votre mot de passe dans la gestion des utilisateurs.<br />
<br />
==5.2 R&eacute;glages optionnels==<br />
<br />
Il existe plusieurs autres r&eacute;glages optionnels que vous pouvez d&eacute;finir dans config.php. Veuillez consultez la page des [[r&eacute;glages optionnels]]. Cependant, pour une configuration de base, poursuivez &agrave; l'&eacute;tape suivante.<br />
<br />
=6. Envoi des fichiers sur votre serveur web=<br />
<br />
En utilisant votre client FTP favori, connectez-vous &agrave; votre serveur web et cr&eacute;ez un dossier pour y stocker les fichiers de LimeSurvey. Envoyez dans ce dossier l'ensemble des fichiers de LimeSurvey en respectant la structure des dossiers. Nous vous recommandons d'envoyer les fichiers en mode binaire (r&eacute;glage du programme de FTP). En utilisant le mode ASCII, parfois les images sont mal transf&eacute;r&eacute;es.<br />
<br />
=7. D&eacute;finition des permissions des dossiers=<br />
<br />
Pour que le programme fonctionne correctement, il a besoin d'acc&egrave;s &agrave; certains dossiers. Cela s'applique sp&eacute;cialement aux syst&egrave;mes Linux/*nix.<br />
* le dossier '''"/limesurvey/tmp"''' est utilis&eacute; pour les importations et les exportations et doit &ecirc;tre en ''lecture et &eacute;criture'' pour le serveur web.<br />
* le dossier '''"/limesurvey/upload"''' et ses sous-dossiers doivent aussi &ecirc;tre en ''lecture et &eacute;criture'' pour votre serveur web pour activer l'envoi d'images et de fichiers multim&eacute;dias.<br />
* les autres dossiers peuvent &ecirc;tre en ''lecture seule''. Vous pouvez aussi d&eacute;finir des permissions de ''lecture seule'' pour chaque fichier dans le dossier ''/limesurvey/admin''.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Conseil :''' Si vous utilisez Linux alors en fonction de la configuration de votre serveur web vous devrez chmod&eacute; les droits sur les r&eacute;pertoires en &eacute;critures &agrave; 755 ou 777. Essayez 755 en premier et si cela ne marche pas, "passez" &agrave; 777.</div><br />
<br />
=8. Ex&eacute;cution du script d'installation=<br />
<br />
Rendez-vous &agrave; '''"http://votre.domaine.com/limesurvey/admin/install"'''. Si vous avez tout configur&eacute; correctement, vous serez invit&eacute; &agrave; cr&eacute;er la base de donn&eacute;es et/ou les tables dans la base.<br />
<br />
=9. Premi&egrave;re connexion &agrave; l'interface d'administration=<br />
<br />
Vous &ecirc;tes pr&ecirc;t ! Ouvrez votre navigateur et saisissez l'adresse vers le script admin.php. En supposant que vous avez utilis&eacute; limesurvey pour le nom du dossier o&ugrave; vous avez stock&eacute; les fichiers, cela ressemblera &agrave; quelque chose comme-&ccedil;a "http://votre.domaine.com/limesurvey/admin/admin.php".<br />
<br />
Normalement, vous devriez tomber sur un &eacute;cran d'identification. Les valeurs par d&eacute;faut pour pouvoir se connecter sont :<br />
<br />
<div class="simplebox">Utilisateur : admin<br />
<br />
Mot de passe : password</div><br />
<br />
Il vous sera demand&eacute; de changer ce mot de passe apr&egrave;s la premi&egrave;re connexion. Amusez-vous bien !<br />
<br />
=10. En cas de probl&egrave;me...=<br />
<br />
Comme tout programme informatique, les choses se d&eacute;rouleront telles que d&eacute;crites dans les instructions mais, en g&eacute;n&eacute;ral, ce ne sera pas le cas. Il existe de nombreuses de raisons possibles pour que les choses ne se passent pas comme d&eacute;crites ici. Si vous avez des soucis, veuillez d'abord consulter la [[FAQ de l'installation]]. Si vous ne trouvez pas de r&eacute;ponses alors veuillez d&eacute;crire votre probl&egrave;me dans le [http://www.limesurvey.org/component/option,com_fireboard/Itemid,86/lang,fr/ forum de LimeSurvey] sur limesurvey.org.ou essayer de contacter quelqu'un dans le [irc://irc.freenode.net/limesurvey|salon IRC de LimeSurvey] :<br />
<br />
<div class="simplebox"><center>[http://www.limesurvey.org/index.php/Live-Chat.html Lien direct vers le canal IRC officiel de LimeSurvey]</center></div><br />
<br />
=Tutoriels vid&eacute;o=<br />
<br />
Ces tutoriels vid&eacute;o n'ont pas &eacute;t&eacute; cr&eacute;&eacute;s et ne sont pas maintenus par notre &eacute;quipe et doivent &ecirc;tre utilis&eacute;s comme "pense-b&ecirc;te". Ils ne remplacent en rien la lecture des instructions ci-dessus !<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu How to install and configure '''LimeSurvey''' v1.01 in Ubuntu Feisty].<br />
* OSS Watch [http://wiki.oss-watch.ac.uk/LimeSurveyInUbuntu Upgrading from '''LimeSurvey''' 1.01 to '''LimeSurvey''' 1.52+ build 3304 2007-09-20 in Ubuntu Feisty].</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Upgrading_from_a_previous_version&diff=3561Upgrading from a previous version2012-11-16T16:21:26Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Before you start...=<br />
<br />
<span style='color:#FF0000'>... read this because it is very important: '''Always backup the files and the database of your current installation!!'''</span><br />
<br />
You can do this using a database adminstration tool like [http://www.phpmyadmin.net phpMyAdmin] etc. and a file manager! If you don't know how to do this you should better not proceed but ask someone who knows or use the [[ComfortUpdate]] instead.<br />
<br />
=The quick way (for minor version changes)=<br />
<br />
You can use these instructions if you are doing a minor upgrade (for example from 2.00 to 2.01)<br />
*Backup your files and database (did we already mention that?)<br />
*Delete all the old files/directory except for<br />
**/application/config/config.php<br />
**/upload directory<br />
*Copy the new files from the new LimeSurvey package to the existing location.<br />
*'''After the upgrade: Clear your browser cache and cookies!'''<br />
<br />
=The thorough way (for big version jumps)=<br />
<br />
Unfortunately there are a couple of things to consider, so please scan the following instruction closely.<br />
<br />
==Upgrading from version 1.50 or later to any later 2.xx version==<br />
#[http://www.limesurvey.org/download Download] the latest version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. For example in Linux tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory.<br />
### Using phpMyAdmin or similar to export all tables; or use the according '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file, modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
## Open http://<yourdomain>/<yourlimesurveydir>/admin in your browser and follow the instructions (you can use the old config.php as reference). The existing database will be automatically detected and , if necessary, upgraded after confirmation.<br />
# Check if any special manual checks apply as listed below<br />
# '''Now clear your browser cache and cookies!'''<br />
# You are done (:biggrin:).<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 2.xx''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed). The upgrade process tries to replace the template.js inclusion by the placeholder {TEMPLATEJS}. If you have javascript issue with your custom template, verify if your template have the placeholder {TEMPLATEJS} in startpage.pstpl.<br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from version 1.50 or later to any later 1.xx version==<br />
#[http://www.limesurvey.org/download Download] the desired version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. e.g. tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory<br />
### Using phpMyAdmin or similar to export all tables; or using the '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file ,modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## Edit or replace the '''config.php''' file:<br />
### If your previous version was < 1.70: Edit the new '''config.php''' to reflect changed settings in the backup '''config.php''' file. '''Do not just overwrite the new '''config.php''' with your old one!'''<br />
### If your previous version was >= 1.70: Simply replace the new '''config.php''' with your backup '''config.php''' (as the file format has not changed).<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
# Finishing the installation<br />
## Once you open the URL to your LimeSurvey administration the database tables will be updated after confirmation<br />
## Remove or rename the '''/admin/install''' directory as/if instructed by the installation script<br />
## Check if any special, manual checks apply as listed below<br />
# You are done (:biggrin:). If you notice any problems after the upgrade: Clear your browser cache and cookies!<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 1.92''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from a version earlier than v1.50 (v1.0 through v1.44)==<br />
<br />
Since the data structure and a lot of other things were changed, '''upgrading from any version previous to v1.50 is NOT possible'''. If you have old survey structure files with a *.sql extension the only way to get these into a newer version is to install [http://www.limesurvey.org/en/archived-releases/finish/24-archived-releases/289-limesurvey150zip version 1.50], import the .sql file(s) there, then upgrade that version to the most recent LimeSurvey version. See the also then page [[Transferring an installation]] for more details.<br />
<br />
=Upgrade FAQ=<br />
<br />
==What is the most actual LimeSurvey version that still supports PHP4?==<br />
<br />
The last release offering PHP4 support was version 1.82+.<br />
<br />
==Can I upgrade even if I have active surveys?==<br />
<br />
Yes, you can. Exceptions may be mentioned in the thorough instructions above. We strongly advise to test your surveys after upgrade to check if your design templates still work alright.<br />
<br />
==What is best way to port LimeSurvey *.sql survey structure files to the latest version?==<br />
<br />
Install version 1.50, import the file and export the survey structure to the newer .csv format. The latest version still can read the .csv survey structure format.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Upgrading_from_a_previous_version&diff=3562Upgrading from a previous version2012-11-16T16:19:56Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Before you start...=<br />
<br />
<span style='color:#FF0000'>... read this because it is very important: '''Always backup the files and the database of your current installation!!'''</span><br />
<br />
You can do this using a database adminstration tool like [http://www.phpmyadmin.net phpMyAdmin] etc. and a file manager! If you don't know how to do this you should better not proceed but ask someone who knows or use the [[ComfortUpdate]] instead.<br />
<br />
=The quick way (for minor version changes)=<br />
<br />
You can use this instruction if you are doing a minor upgrade (for example from 2.00 to 2.01)<br />
*Backup your files and database (did we already mention that?)<br />
*Delete all the old files/directory except for<br />
**/application/config/config.php<br />
**/upload directory<br />
*Copy the new files from the new LimeSurvey package to the existing location.<br />
*'''After the upgrade: Clear your browser cache and cookies!'''<br />
<br />
=The thorough way (for big version jumps)=<br />
<br />
Unfortunately there are a couple of things to consider, so please scan the following instruction closely.<br />
<br />
==Upgrading from version 1.50 or later to any later 2.xx version==<br />
#[http://www.limesurvey.org/download Download] the latest version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. For example in Linux tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory.<br />
### Using phpMyAdmin or similar to export all tables; or use the according '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file, modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
## Open http://<yourdomain>/<yourlimesurveydir>/admin in your browser and follow the instructions (you can use the old config.php as reference). The existing database will be automatically detected and , if necessary, upgraded after confirmation.<br />
# Check if any special manual checks apply as listed below<br />
# '''Now clear your browser cache and cookies!'''<br />
# You are done (:biggrin:).<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 2.xx''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed). The upgrade process tries to replace the template.js inclusion by the placeholder {TEMPLATEJS}. If you have javascript issue with your custom template, verify if your template have the placeholder {TEMPLATEJS} in startpage.pstpl.<br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from version 1.50 or later to any later 1.xx version==<br />
#[http://www.limesurvey.org/download Download] the desired version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. e.g. tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory<br />
### Using phpMyAdmin or similar to export all tables; or using the '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file ,modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## Edit or replace the '''config.php''' file:<br />
### If your previous version was < 1.70: Edit the new '''config.php''' to reflect changed settings in the backup '''config.php''' file. '''Do not just overwrite the new '''config.php''' with your old one!'''<br />
### If your previous version was >= 1.70: Simply replace the new '''config.php''' with your backup '''config.php''' (as the file format has not changed).<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
# Finishing the installation<br />
## Once you open the URL to your LimeSurvey administration the database tables will be updated after confirmation<br />
## Remove or rename the '''/admin/install''' directory as/if instructed by the installation script<br />
## Check if any special, manual checks apply as listed below<br />
# You are done (:biggrin:). If you notice any problems after the upgrade: Clear your browser cache and cookies!<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 1.92''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from a version earlier than v1.50 (v1.0 through v1.44)==<br />
<br />
Since the data structure and a lot of other things were changed, '''upgrading from any version previous to v1.50 is NOT possible'''. If you have old survey structure files with a *.sql extension the only way to get these into a newer version is to install [http://www.limesurvey.org/en/archived-releases/finish/24-archived-releases/289-limesurvey150zip version 1.50], import the .sql file(s) there, then upgrade that version to the most recent LimeSurvey version. See the also then page [[Transferring an installation]] for more details.<br />
<br />
=Upgrade FAQ=<br />
<br />
==What is the most actual LimeSurvey version that still supports PHP4?==<br />
<br />
The last release offering PHP4 support was version 1.82+.<br />
<br />
==Can I upgrade even if I have active surveys?==<br />
<br />
Yes, you can. Exceptions may be mentioned in the thorough instructions above. We strongly advise to test your surveys after upgrade to check if your design templates still work alright.<br />
<br />
==What is best way to port LimeSurvey *.sql survey structure files to the latest version?==<br />
<br />
Install version 1.50, import the file and export the survey structure to the newer .csv format. The latest version still can read the .csv survey structure format.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Upgrading_from_a_previous_version&diff=3563Upgrading from a previous version2012-11-16T16:19:41Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Before you start...=<br />
<br />
<span style='color:#FF0000'>... read this because it is very important: '''Always backup the files and the database of your current installation!!'''</span><br />
<br />
You can do this using a database adminstration tool like [http://www.phpmyadmin.net phpMyAdmin] etc. and a file manager! If you don't know how to do this you should better not proceed but ask someone who knows or use the [[ComfortUpdate]] instead.<br />
<br />
=The quick way (for minor version changes)=<br />
<br />
You can use this instruction if you are doing a minor upgrade (for example from 2.00 to 2.01)<br />
*Backup your files and database (did we already mention that?)<br />
*Delete all the old files/directory except for<br />
**/application/config/config.php<br />
**/upload directory<br />
*Copy the new files from the new LimeSurvey package to the existing location.<br />
*'''After the upgrade: Clear your browser cache and cookies!'''<br />
<br />
=The thorough way (for big version jumps)=<br />
<br />
Unfortunately there are a couple of things to consider, so please scan the following instruction closely.<br />
<br />
==Upgrading from version 1.50 or later to any later 2.xx version==<br />
#[http://www.limesurvey.org/download Download] the latest version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. For example in Linux tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory.<br />
### Using phpMyAdmin or similar to export all tables; or use the according '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file, modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
## Open http://<yourdomain>/<yourlimesurveydir>/admin in your browser and follow the instructions (you can use the old config.php as reference). The existing database will be automatically detected and , if necessary, upgraded after confirmation.<br />
# Check if any special manual checks apply as listed below<br />
# '''Now clear your browser cache and cookies!'''<br />
# You are done (:biggrin:).<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 2.xx''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed). The upgrade process tries to replace the template.js inclusion by the placeholder {TEMPLATEJS}. If you have javascript issue with your custom template, verify if your template have the placeholder {TEMPLATEJS} in startpage.pstpl.<br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from version 1.50 or later to any later 1.xx version==<br />
#[http://www.limesurvey.org/download Download] the desired version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. e.g. tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory<br />
### Using phpMyAdmin or similar to export all tables; or using the '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file ,modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## Edit or replace the '''config.php''' file:<br />
### If your previous version was < 1.70: Edit the new '''config.php''' to reflect changed settings in the backup '''config.php''' file. '''Do not just overwrite the new '''config.php''' with your old one!'''<br />
### If your previous version was >= 1.70: Simply replace the new '''config.php''' with your backup '''config.php''' (as the file format has not changed).<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
# Finishing the installation<br />
## Once you open the URL to your LimeSurvey administration the database tables will be updated after confirmation<br />
## Remove or rename the '''/admin/install''' directory as/if instructed by the installation script<br />
## Check if any special, manual checks apply as listed below<br />
# You are done (:biggrin:). If you notice any problems after the upgrade: Clear your browser cache and cookies!<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 1.92''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from a version earlier than v1.50 (v1.0 through v1.44)==<br />
<br />
Since the data structure and a lot of other things were changed, '''upgrading from any version previous to v1.50 is NOT possible'''. If you have old survey structure files with a *.sql extension the only way to get these into a newer version is to install [http://www.limesurvey.org/en/archived-releases/finish/24-archived-releases/289-limesurvey150zip version 1.50], import the .sql file(s) there, then upgrade that version to the most recent LimeSurvey version. See the also then page [[Transferring an installation]] for more details.<br />
<br />
=Upgrade FAQ=<br />
<br />
==What is the most actual LimeSurvey version that still supports PHP4?==<br />
<br />
The last release offering PHP4 support was version 1.82+.<br />
<br />
==Can I upgrade even if I have active surveys?==<br />
<br />
Yes, you can. Exceptions may be mentioned in the thorough instructions above. We strongly advise to test your surveys after upgrade to check if your design templates still work alright.<br />
<br />
==What is best way to port LimeSurvey *.sql survey structure files to the latest version?==<br />
<br />
Install version 1.50, import the file and export the survey structure to the newer .csv format. The latest version still can read the .csv survey structure format.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Upgrading_from_a_previous_version&diff=3564Upgrading from a previous version2012-11-16T16:18:31Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Before you start...=<br />
<br />
<span style='color:#FF0000'>... read this because it is very important: '''Always backup the files and the database of your current installation!!'''</span><br />
<br />
You can do this using a database adminstration tool like [http://www.phpmyadmin.net phpMyAdmin] etc. and a file manager! If you don't know how to do this you should better not proceed but ask someone who knows or use the [[ComfortUpdate]] instead.<br />
<br />
=The quick way (for minor version changes)=<br />
<br />
You can use this instruction if you are doing a minor upgrade (for example from 2.00 to 2.01)<br />
*Backup your files and database (did we already mention that?)<br />
*Delete all the old files/directory except for<br />
**/application/config/config.php<br />
**/upload directory<br />
*Copy the new files from the new LimeSurvey package to the existing location.<br />
*'''After the upgrade: Clear your browser cache and cookies!'''<br />
<br />
=The thorough way (for big version jumps)=<br />
<br />
Unfortunately there are a couple of things to consider, so please scan the following instruction closely.<br />
<br />
==Upgrading from version 1.50 or later to any later 2.xx version==<br />
#[http://www.limesurvey.org/download Download] the latest version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. For example in Linux tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory.<br />
### Using phpMyAdmin or similar to export all tables; or use the according '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file, modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
## Open http://<yourdomain>/<yourlimesurveydir>/admin in your browser and follow the instructions (you can use the old config.php as reference). The existing database will be automatically detected and , if necessary, upgraded after confirmation.<br />
# Check if any special manual checks apply as listed below<br />
# '''Now clear your browser cache and cookies!'''<br />
# You are done (:biggrin:).<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 2.xx''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed). The upgrade process tries to replace the template.js inclusion by the placeholder {TEMPLATEJS}. If you have javascript issue with your custom template, verify if your template have the placeholder {TEMPLATEJS} in startpage.pstpl.<br />
<br />
<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from version 1.50 or later to any later 1.xx version==<br />
#[http://www.limesurvey.org/download Download] the desired version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. e.g. tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory<br />
### Using phpMyAdmin or similar to export all tables; or using the '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file ,modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## Edit or replace the '''config.php''' file:<br />
### If your previous version was < 1.70: Edit the new '''config.php''' to reflect changed settings in the backup '''config.php''' file. '''Do not just overwrite the new '''config.php''' with your old one!'''<br />
### If your previous version was >= 1.70: Simply replace the new '''config.php''' with your backup '''config.php''' (as the file format has not changed).<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
# Finishing the installation<br />
## Once you open the URL to your LimeSurvey administration the database tables will be updated after confirmation<br />
## Remove or rename the '''/admin/install''' directory as/if instructed by the installation script<br />
## Check if any special, manual checks apply as listed below<br />
# You are done (:biggrin:). If you notice any problems after the upgrade: Clear your browser cache and cookies!<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 1.92''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from a version earlier than v1.50 (v1.0 through v1.44)==<br />
<br />
Since the data structure and a lot of other things were changed, '''upgrading from any version previous to v1.50 is NOT possible'''. If you have old survey structure files with a *.sql extension the only way to get these into a newer version is to install [http://www.limesurvey.org/en/archived-releases/finish/24-archived-releases/289-limesurvey150zip version 1.50], import the .sql file(s) there, then upgrade that version to the most recent LimeSurvey version. See the also then page [[Transferring an installation]] for more details.<br />
<br />
=Upgrade FAQ=<br />
<br />
==What is the most actual LimeSurvey version that still supports PHP4?==<br />
<br />
The last release offering PHP4 support was version 1.82+.<br />
<br />
==Can I upgrade even if I have active surveys?==<br />
<br />
Yes, you can. Exceptions may be mentioned in the thorough instructions above. We strongly advise to test your surveys after upgrade to check if your design templates still work alright.<br />
<br />
==What is best way to port LimeSurvey *.sql survey structure files to the latest version?==<br />
<br />
Install version 1.50, import the file and export the survey structure to the newer .csv format. The latest version still can read the .csv survey structure format.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Coding_guidelines&diff=3130Coding guidelines2012-11-16T14:51:02Z<p>Admin: </p>
<hr />
<div><br />
Contents:__TOC__<br />
<br />
=General=<br />
<br />
'''This is a free development, everything you do can be useful for others. If the feature is very personal there is a way to turn it into a universal solution. This is the challenge!'''<br />
<br />
<div class="simplebox">"The difficulty within a solution is to solve it in a simple way"<br />
<br />
(Lance Burton, magician)</div><br />
<br />
Some general rules:<br />
*Be efficient and save resources (memory and runtime). Things might work for a small survey but also try out your new feature with a survey that has 400 question, 5 languages and 20,000 responses (Yes, there are surveys like this out there).<br />
*Keep a fluid dialog with the others coders, they have their own thoughts about what you are doing.<br />
*Ask if you are in doubt.<br />
<br />
=Naming convention=<br />
*Use the Hungarian Rule for variables:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
[t]NameOfVariable<br />
<br />
| <strike>-</strike><strike>+</strike>----<br />
<br />
| +--> Descriptive name<br />
<br />
+--> Datatype stored (for example start with "a" if it is an array)<br />
<br />
</syntaxhighlight><br />
<br />
Examples:<br />
<br />
aQuestionAttributes: Array to store the questions attributes, Mixed values<br />
<br />
dSurveyEnds: Date when the survey ends<br />
<br />
sContditionsOutput: String used to create the JS for conditions<br />
*In case a function is declared '''do not''' use the Hungarian rule for the function name, instead use "Lower CamelCase":<br />
<br />
function questionsRetrieve( $iQID, $iSurvey)<br />
*What about files? Unless Yii requires it in some way always name your files in lowercase - this prevents problems on systems using case-aware filesystems<br />
<br />
=Documentation=<br />
<br />
Please refer to this introduction: [[How to document your source code]].<br />
<br />
=Structures=<br />
*Indent using spaces instead of TAB, or be gentle to announce how many spaces are your TABs long. There is wide ranging debate about tabs vs. spaces, many people prefer using tabs, others prefer spaces, others are happy with a mix of tabs and spaces. Because LimeSurvey is developed collaboratively, we ask that you leave your preference and follow this standard.<br />
*The opening curly brace must be below the structure opening:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
if (condition)<br />
<br />
{<br />
<br />
...<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
*Using one line for a simple condition is very "fashionable", a taste of "hacker", but it is not clear at all:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG: if (condition) {do true} else {do false}<br />
<br />
WRONG: if (condition) {do true}<br />
<br />
else {do false}<br />
<br />
RIGHT: if (condition)<br />
<br />
{<br />
<br />
do true<br />
<br />
} else<br />
<br />
{<br />
<br />
do false<br />
<br />
}<br />
<br />
RIGHT: swith $sSelector<br />
<br />
{<br />
<br />
case X:<br />
<br />
...<br />
<br />
break;<br />
<br />
case Y:<br />
<br />
...<br />
<br />
default:<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
NOTE: It&acute;s true that sometimes the "WRONG" way can be useful, but if it makes the straight reading difficult, please use the "RIGHT" way instead. Be gentle with your fellow developers.<br />
*SQL sentences must respect the same rule:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
$sSQL = "SELECT field1, field2, field3 "<br />
<br />
."WHERE condition "<br />
<br />
."AND condition "<br />
<br />
."OR condition "<br />
<br />
."ORDER BY field1, field2";<br />
<br />
</syntaxhighlight><br />
*The same for HTML in views tags:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<table><br />
<br />
<tr><br />
<br />
<td colspan='2'<br />
<br />
height='4'><br />
<br />
<strong><br />
<br />
Some Text<br />
<br />
</strong><br />
<br />
</td><br />
<br />
</tr><br />
<br />
</table><br />
<br />
</syntaxhighlight><br />
<br />
=HTML=<br />
*As you will notice, a very customized HTML element can take a lot of lines (very expensive if you paid each one (:wink:) ) to avoid that, use 'CSS classes'. In general, use classes to aesthetic related stuff: color, borders, backgrounds, font faces, sizes, etc.<br />
*Respect W3C standards, and try to use the HTML understandable for all browsers. If one of them has a special feature, think if this feature is so special to break down the HTML in other browsers.<br />
*Do not use PHP short tags <? ?>. Always use full PHP tags <?php ?><br />
*Any rules of the mentioned before: about CSS, well closed HTML tags and JS respect XHTML standards. Give it a try!.<br />
<br />
=Localization=<br />
<br />
Currently we are using the gT(),eT(),ngT() and neT() functions of the limesurvey_lang object for translations.<br />
<br />
Since LimeSurvey is available in 60 languages it is very important that your original English string (which will be picked up automatically for translation by our translators) is done right from the start. Imagine if we have to correct only one string at a later time - then 60 strings become invalid across the project and need to be re-translated by the poor translator souls.<br />
* gT() is the original translation function. It will return a translated version of the string in the currently selected language. ie: echo ''$clang->gT("Hello");''<br />
* ngT() returns multiple translations of a sentence or phrase for which alternate plural forms may apply. ie: ''echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers)'';<br />
* eT() echos the translation directly. (ie: instead of ''echo $clang->gT("Hello");'' you can use ''$clang->eT("Hello");''<br />
* neT() echos the multiple translations of the sentence or phrase for which alternate plural forms may apply directly.<br />
<br />
Please follow these important rules:<br />
*'''Do not embed margin spaces''' in your translation. Instead use proper CSS formatting<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Visible? ');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Visible?');<br />
*'''Do not capitalize words''' except where grammatically correct (like at the beginning of a sentence or for a brand name). LimeSurvey is not a newspaper.<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Create A New Label Set');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Create a new label set');<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Google Maps API Key');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Google Maps API key');<br />
*'''Do not concatenate''' several translations to form a sentence or concatenate to an additional information (like a number or string). Instead use the sprint() or sprintf() function with placeholders.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The sum must not be bigger than').$iMaxSum;<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The sum must not be bigger than %s'),$iMaxSum);<br />
<br />
This comes from the problem that in other languages the setting of a sentence can be much different and the information $iMaxSum from the example above might be needed in the middle of the sentence.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The user').$sUsername.$clang->gT('was deleted.');<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The user %s was deleted.'),$sUsername);<br />
*'''Use the n*T functions where applicable'''. These functions show a different translation depending the number of items. Currently LimeSurvey only supports the numbers/situations 1 and >1.<br />
<br />
+Example:<br />
<br />
<span style='color:#F00'>Wrong</span>: echo sprintf($clang->gT('Please select at least %s answer(s).'),$iMinimumAnswers);<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers);<br />
<br />
=Bug tracker=<br />
#First consider if the reported issue is really a bug. If it is a feature request please point the reporter to http://ideas.limesurvey.org and set the issue status to 'Closed'.<br />
#If you would like to work on a bug assign it to yourself.<br />
#Try to reproduce the issue.<br />
##If you cannot reproduce ask the user to provide a small example survey to demonstrate the issue. Then set the issue to 'Feedback'. After the user added the necessary information it will automatically be set to 'Assigned' again.<br />
##If the user does not responds for more than a week ask once again for feedback by adding a comment. After a further week without feedback close the issue.<br />
#After you resolved the issue set the status to resolved AND provide the 'Fixed in version' information.<br />
#After you committed your fix add a comment to the resolved issue 'Fixed in rev. <Subversion revision number>'<br />
#After a release the release technician will set all issues to 'Closed' that were fixed for this release. That signals to the reporter that a fix is available in the version and it was just released.<br />
<br />
=Cross-DB compatibility=<br />
<br />
LimeSurvey targets several database types it can run on: MySQL, Postgres and Microsoft SQL Server. This demands certain precautions when coding<br />
<br />
==Parameter binding==<br />
<br />
Yii/PDO supports parameter binding - use it. Don't inject variables directly into the query or into conditions because this might create a security issue.<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('somefield')<br />
<br />
->where("sid = :sid")<br />
<br />
->from('{{sometable}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
If you bind the same value several times do NOT use the same parameter name, instead use a different named parameter for each bind:<br />
<br />
WRONG:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('somefield')<br />
<br />
->where("sid = :sid and parent_sid= :sid ")<br />
<br />
->from('{{sometable}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
RIGHT:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('somefield')<br />
<br />
->where("sid = :sid1 and parent_sid= :sid2 ")<br />
<br />
->from('{{sometable}}')<br />
<br />
->bindParam(":sid1", $surveyid, PDO::PARAM_INT)<br />
<br />
->bindParam(":sid2", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
=Miscellaneous=<br />
*Do not use "global" to access to a declared variable in another process. Pass variables or arrays by reference, use the session or the configuration object.<br />
*If using an auxiliary variable makes clear the code or process, just do it. If you are coding a very complex expression, calling to functions with parameters that are other functions:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG:<br />
<br />
iAResult= fa(fb(p1,p2),fc(fd(p3),p4),p5)<br />
<br />
It will be more readable:<br />
<br />
iAuxB = fb(p1,p2)<br />
<br />
iAuxD = fd(p3)<br />
<br />
iAuxC = fc(iAuxD,p4)<br />
<br />
iAResult = fa(iAuxB, iAuxC, p5)<br />
<br />
</syntaxhighlight><br />
<br />
Anyway, if you are in doubt about someone missing the point or you are afraid that your expression is obscure, take the chance of writing it in a more simple way, even if that involves the use of one or more auxiliary variables.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Coding_guidelines&diff=3131Coding guidelines2012-11-16T13:25:10Z<p>Admin: </p>
<hr />
<div><br />
Contents:__TOC__<br />
<br />
=General=<br />
<br />
'''This is a free development, everything you do can be useful for others. If the feature is very personal there is a way to turn it into a universal solution. This is the challenge!'''<br />
<br />
<div class="simplebox">"The difficulty within a solution is to solve it in a simple way"<br />
<br />
(Lance Burton, magician)</div><br />
<br />
Some general rules:<br />
*Be efficient and save resources (memory and runtime). Things might work for a small survey but also try out your new feature with a survey that has 400 question, 5 languages and 20,000 responses (Yes, there are surveys like this out there).<br />
*Keep a fluid dialog with the others coders, they have their own thoughts about what you are doing.<br />
*Ask if you are in doubt.<br />
<br />
=Naming convention=<br />
*Use the Hungarian Rule for variables:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
[t]NameOfVariable<br />
<br />
| <strike>-</strike><strike>+</strike>----<br />
<br />
| +--> Descriptive name<br />
<br />
+--> Datatype stored (for example start with "a" if it is an array)<br />
<br />
</syntaxhighlight><br />
<br />
Examples:<br />
<br />
aQuestionAttributes: Array to store the questions attributes, Mixed values<br />
<br />
dSurveyEnds: Date when the survey ends<br />
<br />
sContditionsOutput: String used to create the JS for conditions<br />
*In case a function is declared '''do not''' use the Hungarian rule for the function name, instead use "Lower CamelCase":<br />
<br />
function questionsRetrieve( $iQID, $iSurvey)<br />
*What about files? Unless Yii requires it in some way always name your files in lowercase - this prevents problems on systems using case-aware filesystems<br />
<br />
=Documentation=<br />
<br />
Please refer to this introduction: [[How to document your source code]].<br />
<br />
=Structures=<br />
*Indent using spaces instead of TAB, or be gentle to announce how many spaces are your TABs long. There is wide ranging debate about tabs vs. spaces, many people prefer using tabs, others prefer spaces, others are happy with a mix of tabs and spaces. Because LimeSurvey is developed collaboratively, we ask that you leave your preference and follow this standard.<br />
*The opening curly brace must be below the structure opening:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
if (condition)<br />
<br />
{<br />
<br />
...<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
*Using one line for a simple condition is very "fashionable", a taste of "hacker", but it is not clear at all:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG: if (condition) {do true} else {do false}<br />
<br />
WRONG: if (condition) {do true}<br />
<br />
else {do false}<br />
<br />
RIGHT: if (condition)<br />
<br />
{<br />
<br />
do true<br />
<br />
} else<br />
<br />
{<br />
<br />
do false<br />
<br />
}<br />
<br />
RIGHT: swith $sSelector<br />
<br />
{<br />
<br />
case X:<br />
<br />
...<br />
<br />
break;<br />
<br />
case Y:<br />
<br />
...<br />
<br />
default:<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
NOTE: It&acute;s true that sometimes the "WRONG" way can be useful, but if it makes the straight reading difficult, please use the "RIGHT" way instead. Be gentle with your fellow developers.<br />
*SQL sentences must respect the same rule:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
$sSQL = "SELECT field1, field2, field3 "<br />
<br />
."WHERE condition "<br />
<br />
."AND condition "<br />
<br />
."OR condition "<br />
<br />
."ORDER BY field1, field2";<br />
<br />
</syntaxhighlight><br />
*The same for HTML in views tags:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<table><br />
<br />
<tr><br />
<br />
<td colspan='2'<br />
<br />
height='4'><br />
<br />
<strong><br />
<br />
Some Text<br />
<br />
</strong><br />
<br />
</td><br />
<br />
</tr><br />
<br />
</table><br />
<br />
</syntaxhighlight><br />
<br />
=HTML=<br />
*As you will notice, a very customized HTML element can take a lot of lines (very expensive if you paid each one (:wink:) ) to avoid that, use 'CSS classes'. In general, use classes to aesthetic related stuff: color, borders, backgrounds, font faces, sizes, etc.<br />
*Respect W3C standards, and try to use the HTML understandable for all browsers. If one of them has a special feature, think if this feature is so special to break down the HTML in other browsers.<br />
*Do not use PHP short tags <? ?>. Always use full PHP tags <?php ?><br />
*Any rules of the mentioned before: about CSS, well closed HTML tags and JS respect XHTML standards. Give it a try!.<br />
<br />
=Localization=<br />
<br />
Currently we are using the gT(),eT(),ngT() and neT() functions of the limesurvey_lang object for translations.<br />
<br />
Since LimeSurvey is available in 60 languages it is very important that your original English string (which will be picked up automatically for translation by our translators) is done right from the start. Imagine if we have to correct only one string at a later time - then 60 strings become invalid across the project and need to be re-translated by the poor translator souls.<br />
* gT() is the original translation function. It will return a translated version of the string in the currently selected language. ie: echo ''$clang->gT("Hello");''<br />
* ngT() returns multiple translations of a sentence or phrase for which alternate plural forms may apply. ie: ''echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers)'';<br />
* eT() echos the translation directly. (ie: instead of ''echo $clang->gT("Hello");'' you can use ''$clang->eT("Hello");''<br />
* neT() echos the multiple translations of the sentence or phrase for which alternate plural forms may apply directly.<br />
<br />
Please follow these important rules:<br />
*'''Do not embed margin spaces''' in your translation. Instead use proper CSS formatting<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Visible? ');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Visible?');<br />
*'''Do not capitalize words''' except where grammatically correct (like at the beginning of a sentence or for a brand name). LimeSurvey is not a newspaper.<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Create A New Label Set');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Create a new label set');<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Google Maps API Key');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Google Maps API key');<br />
*'''Do not concatenate''' several translations to form a sentence or concatenate to an additional information (like a number or string). Instead use the sprint() or sprintf() function with placeholders.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The sum must not be bigger than').$iMaxSum;<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The sum must not be bigger than %s'),$iMaxSum);<br />
<br />
This comes from the problem that in other languages the setting of a sentence can be much different and the information $iMaxSum from the example above might be needed in the middle of the sentence.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The user').$sUsername.$clang->gT('was deleted.');<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The user %s was deleted.'),$sUsername);<br />
*'''Use the n*T functions where applicable'''. These functions show a different translation depending the number of items. Currently LimeSurvey only supports the numbers/situations 1 and >1.<br />
<br />
+Example:<br />
<br />
<span style='color:#F00'>Wrong</span>: echo sprintf($clang->gT('Please select at least %s answer(s).'),$iMinimumAnswers);<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers);<br />
<br />
=Bug tracker=<br />
#First consider if the reported issue is really a bug. If it is a feature request please point the reporter to http://ideas.limesurvey.org and set the issue status to 'Closed'.<br />
#If you would like to work on a bug assign it to yourself.<br />
#Try to reproduce the issue.<br />
##If you cannot reproduce ask the user to provide a small example survey to demonstrate the issue. Then set the issue to 'Feedback'. After the user added the necessary information it will automatically be set to 'Assigned' again.<br />
##If the user does not responds for more than a week ask once again for feedback by adding a comment. After a further week without feedback close the issue.<br />
#After you resolved the issue set the status to resolved AND provide the 'Fixed in version' information.<br />
#After you committed your fix add a comment to the resolved issue 'Fixed in rev. <Subversion revision number>'<br />
#After a release the release technician will set all issues to 'Closed' that were fixed for this release. That signals to the reporter that a fix is available in the version and it was just released.<br />
<br />
=Cross-DB compatibility=<br />
<br />
LimeSurvey targets several database types it can run on: MySQL, Postgres and Microsoft SQL Server. This demands certain precautions when coding<br />
<br />
==Parameter binding==<br />
<br />
Yii/PDO supports parameter binding - use it. Don't inject variables directly into the query or into conditions.<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('somefield')<br />
<br />
->where("sid = :sid")<br />
<br />
->from('{{sometable}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
If you bind the same value several times do NOT use the same parameter name, instead use a different named parameter for each bind:<br />
<br />
WRONG:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('somefield')<br />
<br />
->where("sid = :sid and parent_sid= :sid ")<br />
<br />
->from('{{sometable}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
RIGHT:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('somefield')<br />
<br />
->where("sid = :sid1 and parent_sid= :sid2 ")<br />
<br />
->from('{{sometable}}')<br />
<br />
->bindParam(":sid1", $surveyid, PDO::PARAM_INT)<br />
<br />
->bindParam(":sid2", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
=Miscellaneous=<br />
*Do not use "global" to access to a declared variable in another process. Pass variables or arrays by reference, use the session or the configuration object.<br />
*If using an auxiliary variable makes clear the code or process, just do it. If you are coding a very complex expression, calling to functions with parameters that are other functions:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG:<br />
<br />
iAResult= fa(fb(p1,p2),fc(fd(p3),p4),p5)<br />
<br />
It will be more readable:<br />
<br />
iAuxB = fb(p1,p2)<br />
<br />
iAuxD = fd(p3)<br />
<br />
iAuxC = fc(iAuxD,p4)<br />
<br />
iAResult = fa(iAuxB, iAuxC, p5)<br />
<br />
</syntaxhighlight><br />
<br />
Anyway, if you are in doubt about someone missing the point or you are afraid that your expression is obscure, take the chance of writing it in a more simple way, even if that involves the use of one or more auxiliary variables.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Coding_guidelines&diff=3132Coding guidelines2012-11-16T13:24:25Z<p>Admin: </p>
<hr />
<div><br />
Contents:__TOC__<br />
<br />
=General=<br />
<br />
'''This is a free development, everything you do can be useful for others. If the feature is very personal there is a way to turn it into a universal solution. This is the challenge!'''<br />
<br />
<div class="simplebox">"The difficulty within a solution is to solve it in a simple way"<br />
<br />
(Lance Burton, magician)</div><br />
<br />
Some general rules:<br />
*Be efficient and save resources (memory and runtime). Things might work for a small survey but also try out your new feature with a survey that has 400 question, 5 languages and 20,000 responses (Yes, there are surveys like this out there).<br />
*Keep a fluid dialog with the others coders, they have their own thoughts about what you are doing.<br />
*Ask if you are in doubt.<br />
<br />
=Naming convention=<br />
*Use the Hungarian Rule for variables:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
[t]NameOfVariable<br />
<br />
| <strike>-</strike><strike>+</strike>----<br />
<br />
| +--> Descriptive name<br />
<br />
+--> Datatype stored (for example start with "a" if it is an array)<br />
<br />
</syntaxhighlight><br />
<br />
Examples:<br />
<br />
aQuestionAttributes: Array to store the questions attributes, Mixed values<br />
<br />
dSurveyEnds: Date when the survey ends<br />
<br />
sContditionsOutput: String used to create the JS for conditions<br />
*In case a function is declared '''do not''' use the Hungarian rule for the function name, instead use "Lower CamelCase":<br />
<br />
function questionsRetrieve( $iQID, $iSurvey)<br />
*What about files? Unless Yii requires it in some way always name your files in lowercase - this prevents problems on systems using case-aware filesystems<br />
<br />
=Documentation=<br />
<br />
Please refer to this introduction: [[How to document your source code]].<br />
<br />
=Structures=<br />
*Indent using spaces instead of TAB, or be gentle to announce how many spaces are your TABs long. There is wide ranging debate about tabs vs. spaces, many people prefer using tabs, others prefer spaces, others are happy with a mix of tabs and spaces. Because LimeSurvey is developed collaboratively, we ask that you leave your preference and follow this standard.<br />
*The opening curly brace must be below the structure opening:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
if (condition)<br />
<br />
{<br />
<br />
...<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
*Using one line for a simple condition is very "fashionable", a taste of "hacker", but it is not clear at all:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG: if (condition) {do true} else {do false}<br />
<br />
WRONG: if (condition) {do true}<br />
<br />
else {do false}<br />
<br />
RIGHT: if (condition)<br />
<br />
{<br />
<br />
do true<br />
<br />
} else<br />
<br />
{<br />
<br />
do false<br />
<br />
}<br />
<br />
RIGHT: swith $sSelector<br />
<br />
{<br />
<br />
case X:<br />
<br />
...<br />
<br />
break;<br />
<br />
case Y:<br />
<br />
...<br />
<br />
default:<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
NOTE: It&acute;s true that sometimes the "WRONG" way can be useful, but if it makes the straight reading difficult, please use the "RIGHT" way instead. Be gentle with your fellow developers.<br />
*SQL sentences must respect the same rule:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
$sSQL = "SELECT field1, field2, field3 "<br />
<br />
."WHERE condition "<br />
<br />
."AND condition "<br />
<br />
."OR condition "<br />
<br />
."ORDER BY field1, field2";<br />
<br />
</syntaxhighlight><br />
*The same for HTML in views tags:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<table><br />
<br />
<tr><br />
<br />
<td colspan='2'<br />
<br />
height='4'><br />
<br />
<strong><br />
<br />
Some Text<br />
<br />
</strong><br />
<br />
</td><br />
<br />
</tr><br />
<br />
</table><br />
<br />
</syntaxhighlight><br />
<br />
=HTML=<br />
*As you will notice, a very customized HTML element can take a lot of lines (very expensive if you paid each one (:wink:) ) to avoid that, use 'CSS classes'. In general, use classes to aesthetic related stuff: color, borders, backgrounds, font faces, sizes, etc.<br />
*Respect W3C standards, and try to use the HTML understandable for all browsers. If one of them has a special feature, think if this feature is so special to break down the HTML in other browsers.<br />
*Do not use PHP short tags <? ?>. Always use full PHP tags <?php ?><br />
*Any rules of the mentioned before: about CSS, well closed HTML tags and JS respect XHTML standards. Give it a try!.<br />
<br />
=Localization=<br />
<br />
Currently we are using the gT(),eT(),ngT() and neT() functions of the limesurvey_lang object for translations.<br />
<br />
Since LimeSurvey is available in 60 languages it is very important that your original English string (which will be picked up automatically for translation by our translators) is done right from the start. Imagine if we have to correct only one string at a later time - then 60 strings become invalid across the project and need to be re-translated by the poor translator souls.<br />
* gT() is the original translation function. It will return a translated version of the string in the currently selected language. ie: echo ''$clang->gT("Hello");''<br />
* ngT() returns multiple translations of a sentence or phrase for which alternate plural forms may apply. ie: ''echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers)'';<br />
* eT() echos the translation directly. (ie: instead of ''echo $clang->gT("Hello");'' you can use ''$clang->eT("Hello");''<br />
* neT() echos the multiple translations of the sentence or phrase for which alternate plural forms may apply directly.<br />
<br />
Please follow these important rules:<br />
*'''Do not embed margin spaces''' in your translation. Instead use proper CSS formatting<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Visible? ');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Visible?');<br />
*'''Do not capitalize words''' except where grammatically correct (like at the beginning of a sentence or for a brand name). LimeSurvey is not a newspaper.<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Create A New Label Set');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Create a new label set');<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Google Maps API Key');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Google Maps API key');<br />
*'''Do not concatenate''' several translations to form a sentence or concatenate to an additional information (like a number or string). Instead use the sprint() or sprintf() function with placeholders.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The sum must not be bigger than').$iMaxSum;<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The sum must not be bigger than %s'),$iMaxSum);<br />
<br />
This comes from the problem that in other languages the setting of a sentence can be much different and the information $iMaxSum from the example above might be needed in the middle of the sentence.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The user').$sUsername.$clang->gT('was deleted.');<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The user %s was deleted.'),$sUsername);<br />
*'''Use the n*T functions where applicable'''. These functions show a different translation depending the number of items. Currently LimeSurvey only supports the numbers/situations 1 and >1.<br />
<br />
+Example:<br />
<br />
<span style='color:#F00'>Wrong</span>: echo sprintf($clang->gT('Please select at least %s answer(s).'),$iMinimumAnswers);<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers);<br />
<br />
=Bug tracker=<br />
#First consider if the reported issue is really a bug. If it is a feature request please point the reporter to http://ideas.limesurvey.org and set the issue status to 'Closed'.<br />
#If you would like to work on a bug assign it to yourself.<br />
#Try to reproduce the issue.<br />
##If you cannot reproduce ask the user to provide a small example survey to demonstrate the issue. Then set the issue to 'Feedback'. After the user added the necessary information it will automatically be set to 'Assigned' again.<br />
##If the user does not responds for more than a week ask once again for feedback by adding a comment. After a further week without feedback close the issue.<br />
#After you resolved the issue set the status to resolved AND provide the 'Fixed in version' information.<br />
#After you committed your fix add a comment to the resolved issue 'Fixed in rev. <Subversion revision number>'<br />
#After a release the release technician will set all issues to 'Closed' that were fixed for this release. That signals to the reporter that a fix is available in the version and it was just released.<br />
<br />
=Cross-DB compatibility=<br />
<br />
LimeSurvey targets several database types it can run on: MySQL, Postgres and Microsoft SQL Server. This demands certain precautions when coding<br />
<br />
==Parameter binding==<br />
<br />
Yii/PDO supports parameter binding - use it. Don't inject variables directly into the query or into conditions.<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('attributedescriptions')<br />
<br />
->where("sid = :sid")<br />
<br />
->from('{{surveys}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
If you bind the same value several times do NOT use the same parameter name, instead use a different named parameter for each bind:<br />
<br />
WRONG:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('sometable')<br />
<br />
->where("sid = :sid and parent_sid= :sid ")<br />
<br />
->from('{{surveys}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
RIGHT:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('sometable')<br />
<br />
->where("sid = :sid1 and parent_sid= :sid2 ")<br />
<br />
->from('{{surveys}}')<br />
<br />
->bindParam(":sid1", $surveyid, PDO::PARAM_INT)<br />
<br />
->bindParam(":sid2", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
=Miscellaneous=<br />
*Do not use "global" to access to a declared variable in another process. Pass variables or arrays by reference, use the session or the configuration object.<br />
*If using an auxiliary variable makes clear the code or process, just do it. If you are coding a very complex expression, calling to functions with parameters that are other functions:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG:<br />
<br />
iAResult= fa(fb(p1,p2),fc(fd(p3),p4),p5)<br />
<br />
It will be more readable:<br />
<br />
iAuxB = fb(p1,p2)<br />
<br />
iAuxD = fd(p3)<br />
<br />
iAuxC = fc(iAuxD,p4)<br />
<br />
iAResult = fa(iAuxB, iAuxC, p5)<br />
<br />
</syntaxhighlight><br />
<br />
Anyway, if you are in doubt about someone missing the point or you are afraid that your expression is obscure, take the chance of writing it in a more simple way, even if that involves the use of one or more auxiliary variables.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Coding_guidelines&diff=3133Coding guidelines2012-11-16T13:17:39Z<p>Admin: </p>
<hr />
<div><br />
Contents:__TOC__<br />
<br />
=General=<br />
<br />
'''This is a free development, everything you do can be useful for others. If the feature is very personal there is a way to turn it into a universal solution. This is the challenge!'''<br />
<br />
<div class="simplebox">"The difficulty within a solution is to solve it in a simple way"<br />
<br />
(Lance Burton, magician)</div><br />
<br />
Some general rules:<br />
*Be efficient and save resources (memory and runtime). Things might work for a small survey but also try out your new feature with a survey that has 400 question, 5 languages and 20,000 responses (Yes, there are surveys like this out there).<br />
*Keep a fluid dialog with the others coders, they have their own thoughts about what you are doing.<br />
*Ask if you are in doubt.<br />
<br />
=Naming convention=<br />
*Use the Hungarian Rule for variables:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
[t]NameOfVariable<br />
<br />
| <strike>-</strike><strike>+</strike>----<br />
<br />
| +--> Descriptive name<br />
<br />
+--> Datatype stored (for example start with "a" if it is an array)<br />
<br />
</syntaxhighlight><br />
<br />
Examples:<br />
<br />
aQuestionAttributes: Array to store the questions attributes, Mixed values<br />
<br />
dSurveyEnds: Date when the survey ends<br />
<br />
sContditionsOutput: String used to create the JS for conditions<br />
*In case a function is declared '''do not''' use the Hungarian rule for the function name, instead use "Lower CamelCase":<br />
<br />
function questionsRetrieve( $iQID, $iSurvey)<br />
*What about files? Unless Yii requires it in some way always name your files in lowercase - this prevents problems on systems using case-aware filesystems<br />
<br />
=Documentation=<br />
<br />
Please refer to this introduction: [[How to document your source code]].<br />
<br />
=Structures=<br />
*Indent using spaces instead of TAB, or be gentle to announce how many spaces are your TABs long. There is wide ranging debate about tabs vs. spaces, many people prefer using tabs, others prefer spaces, others are happy with a mix of tabs and spaces. Because LimeSurvey is developed collaboratively, we ask that you leave your preference and follow this standard.<br />
*The opening curly brace must be below the structure opening:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
if (condition)<br />
<br />
{<br />
<br />
...<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
*Using one line for a simple condition is very "fashionable", a taste of "hacker", but it is not clear at all:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG: if (condition) {do true} else {do false}<br />
<br />
WRONG: if (condition) {do true}<br />
<br />
else {do false}<br />
<br />
RIGHT: if (condition)<br />
<br />
{<br />
<br />
do true<br />
<br />
} else<br />
<br />
{<br />
<br />
do false<br />
<br />
}<br />
<br />
RIGHT: swith $sSelector<br />
<br />
{<br />
<br />
case X:<br />
<br />
...<br />
<br />
break;<br />
<br />
case Y:<br />
<br />
...<br />
<br />
default:<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
NOTE: It&acute;s true that sometimes the "WRONG" way can be useful, but if it makes the straight reading difficult, please use the "RIGHT" way instead. Be gentle with your fellow developers.<br />
*SQL sentences must respect the same rule:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
$sSQL = "SELECT field1, field2, field3 "<br />
<br />
."WHERE condition "<br />
<br />
."AND condition "<br />
<br />
."OR condition "<br />
<br />
."ORDER BY field1, field2";<br />
<br />
</syntaxhighlight><br />
*The same for HTML in views tags:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<table><br />
<br />
<tr><br />
<br />
<td colspan='2'<br />
<br />
height='4'><br />
<br />
<strong><br />
<br />
Some Text<br />
<br />
</strong><br />
<br />
</td><br />
<br />
</tr><br />
<br />
</table><br />
<br />
</syntaxhighlight><br />
<br />
=HTML=<br />
*As you will notice, a very customized HTML element can take a lot of lines (very expensive if you paid each one (:wink:) ) to avoid that, use 'CSS classes'. In general, use classes to aesthetic related stuff: color, borders, backgrounds, font faces, sizes, etc.<br />
*Respect W3C standards, and try to use the HTML understandable for all browsers. If one of them has a special feature, think if this feature is so special to break down the HTML in other browsers.<br />
*Do not use PHP short tags <? ?>. Always use full PHP tags <?php ?><br />
*Any rules of the mentioned before: about CSS, well closed HTML tags and JS respect XHTML standards. Give it a try!.<br />
<br />
=Localization=<br />
<br />
Currently we are using the gT(),eT(),ngT() and neT() functions of the limesurvey_lang object for translations.<br />
<br />
Since LimeSurvey is available in 60 languages it is very important that your original English string (which will be picked up automatically for translation by our translators) is done right from the start. Imagine if we have to correct only one string at a later time - then 60 strings become invalid across the project and need to be re-translated by the poor translator souls.<br />
* gT() is the original translation function. It will return a translated version of the string in the currently selected language. ie: echo ''$clang->gT("Hello");''<br />
* ngT() returns multiple translations of a sentence or phrase for which alternate plural forms may apply. ie: ''echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers)'';<br />
* eT() echos the translation directly. (ie: instead of ''echo $clang->gT("Hello");'' you can use ''$clang->eT("Hello");''<br />
* neT() echos the multiple translations of the sentence or phrase for which alternate plural forms may apply directly.<br />
<br />
Please follow these important rules:<br />
*'''Do not embed margin spaces''' in your translation. Instead use proper CSS formatting<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Visible? ');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Visible?');<br />
*'''Do not capitalize words''' except where grammatically correct (like at the beginning of a sentence or for a brand name). LimeSurvey is not a newspaper.<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Create A New Label Set');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Create a new label set');<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Google Maps API Key');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Google Maps API key');<br />
*'''Do not concatenate''' several translations to form a sentence or concatenate to an additional information (like a number or string). Instead use the sprint() or sprintf() function with placeholders.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The sum must not be bigger than').$iMaxSum;<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The sum must not be bigger than %s'),$iMaxSum);<br />
<br />
This comes from the problem that in other languages the setting of a sentence can be much different and the information $iMaxSum from the example above might be needed in the middle of the sentence.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The user').$sUsername.$clang->gT('was deleted.');<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The user %s was deleted.'),$sUsername);<br />
*'''Use the n*T functions where applicable'''. These functions show a different translation depending the number of items. Currently LimeSurvey only supports the numbers/situations 1 and >1.<br />
<br />
+Example:<br />
<br />
<span style='color:#F00'>Wrong</span>: echo sprintf($clang->gT('Please select at least %s answer(s).'),$iMinimumAnswers);<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers);<br />
<br />
=Bug tracker=<br />
#First consider if the reported issue is really a bug. If it is a feature request please point the reporter to http://ideas.limesurvey.org and set the issue status to 'Closed'.<br />
#If you would like to work on a bug assign it to yourself.<br />
#Try to reproduce the issue.<br />
##If you cannot reproduce ask the user to provide a small example survey to demonstrate the issue. Then set the issue to 'Feedback'. After the user added the necessary information it will automatically be set to 'Assigned' again.<br />
##If the user does not responds for more than a week ask once again for feedback by adding a comment. After a further week without feedback close the issue.<br />
#After you resolved the issue set the status to resolved AND provide the 'Fixed in version' information.<br />
#After you committed your fix add a comment to the resolved issue 'Fixed in rev. <Subversion revision number>'<br />
#After a release the release technician will set all issues to 'Closed' that were fixed for this release. That signals to the reporter that a fix is available in the version and it was just released.<br />
<br />
=Cross-DB compatibility=<br />
<br />
LimeSurvey targets several database types it can run on: MySQL, Postgres and Microsoft SQL Server. This demands certain precautions when coding<br />
<br />
==Parameter binding==<br />
<br />
Yii/PDO supports parameter binding - use it. Don't inject variables directly into the query or into conditions.<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('attributedescriptions')<br />
<br />
->where("sid = :sid")<br />
<br />
->from('{{surveys}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
If you bind the same value several times do NOT use the same parameter name, instead use a different named parameter for each bind:<br />
<br />
WRONG:<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('sometable')<br />
<br />
->where("sid = :sid and parent_sid= :sid ")<br />
<br />
->from('{{surveys}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
RIGHT:<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('sometable')<br />
<br />
->where("sid = :sid1 and parent_sid= :sid2 ")<br />
<br />
->from('{{surveys}}')<br />
<br />
->bindParam(":sid1", $surveyid, PDO::PARAM_INT)<br />
<br />
->bindParam(":sid2", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
=Miscellaneous=<br />
*Do not use "global" to access to a declared variable in another process. Pass variables or arrays by reference, use the session or the configuration object.<br />
*If using an auxiliary variable makes clear the code or process, just do it. If you are coding a very complex expression, calling to functions with parameters that are other functions:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG:<br />
<br />
iAResult= fa(fb(p1,p2),fc(fd(p3),p4),p5)<br />
<br />
It will be more readable:<br />
<br />
iAuxB = fb(p1,p2)<br />
<br />
iAuxD = fd(p3)<br />
<br />
iAuxC = fc(iAuxD,p4)<br />
<br />
iAResult = fa(iAuxB, iAuxC, p5)<br />
<br />
</syntaxhighlight><br />
<br />
Anyway, if you are in doubt about someone missing the point or you are afraid that your expression is obscure, take the chance of writing it in a more simple way, even if that involves the use of one or more auxiliary variables.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Coding_guidelines&diff=3134Coding guidelines2012-11-16T13:16:50Z<p>Admin: </p>
<hr />
<div><br />
Contents:__TOC__<br />
<br />
=General=<br />
<br />
'''This is a free development, everything you do can be useful for others. If the feature is very personal there is a way to turn it into a universal solution. This is the challenge!'''<br />
<br />
<div class="simplebox">"The difficulty within a solution is to solve it in a simple way"<br />
<br />
(Lance Burton, magician)</div><br />
<br />
Some general rules:<br />
*Be efficient and save resources (memory and runtime). Things might work for a small survey but also try out your new feature with a survey that has 400 question, 5 languages and 20,000 responses (Yes, there are surveys like this out there).<br />
*Keep a fluid dialog with the others coders, they have their own thoughts about what you are doing.<br />
*Ask if you are in doubt.<br />
<br />
=Naming convention=<br />
*Use the Hungarian Rule for variables:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
[t]NameOfVariable<br />
<br />
| <strike>-</strike><strike>+</strike>----<br />
<br />
| +--> Descriptive name<br />
<br />
+--> Datatype stored (for example start with "a" if it is an array)<br />
<br />
</syntaxhighlight><br />
<br />
Examples:<br />
<br />
aQuestionAttributes: Array to store the questions attributes, Mixed values<br />
<br />
dSurveyEnds: Date when the survey ends<br />
<br />
sContditionsOutput: String used to create the JS for conditions<br />
*In case a function is declared '''do not''' use the Hungarian rule for the function name, instead use "Lower CamelCase":<br />
<br />
function questionsRetrieve( $iQID, $iSurvey)<br />
*What about files? Unless Yii requires it in some way always name your files in lowercase - this prevents problems on systems using case-aware filesystems<br />
<br />
=Documentation=<br />
<br />
Please refer to this introduction: [[How to document your source code]].<br />
<br />
=Structures=<br />
*Indent using spaces instead of TAB, or be gentle to announce how many spaces are your TABs long. There is wide ranging debate about tabs vs. spaces, many people prefer using tabs, others prefer spaces, others are happy with a mix of tabs and spaces. Because LimeSurvey is developed collaboratively, we ask that you leave your preference and follow this standard.<br />
*The opening curly brace must be below the structure opening:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
if (condition)<br />
<br />
{<br />
<br />
...<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
*Using one line for a simple condition is very "fashionable", a taste of "hacker", but it is not clear at all:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG: if (condition) {do true} else {do false}<br />
<br />
WRONG: if (condition) {do true}<br />
<br />
else {do false}<br />
<br />
RIGHT: if (condition)<br />
<br />
{<br />
<br />
do true<br />
<br />
} else<br />
<br />
{<br />
<br />
do false<br />
<br />
}<br />
<br />
RIGHT: swith $sSelector<br />
<br />
{<br />
<br />
case X:<br />
<br />
...<br />
<br />
break;<br />
<br />
case Y:<br />
<br />
...<br />
<br />
default:<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
NOTE: It&acute;s true that sometimes the "WRONG" way can be useful, but if it makes the straight reading difficult, please use the "RIGHT" way instead. Be gentle with your fellow developers.<br />
*SQL sentences must respect the same rule:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
$sSQL = "SELECT field1, field2, field3 "<br />
<br />
."WHERE condition "<br />
<br />
."AND condition "<br />
<br />
."OR condition "<br />
<br />
."ORDER BY field1, field2";<br />
<br />
</syntaxhighlight><br />
*The same for HTML in views tags:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<table><br />
<br />
<tr><br />
<br />
<td colspan='2'<br />
<br />
height='4'><br />
<br />
<strong><br />
<br />
Some Text<br />
<br />
</strong><br />
<br />
</td><br />
<br />
</tr><br />
<br />
</table><br />
<br />
</syntaxhighlight><br />
<br />
=HTML=<br />
*As you will notice, a very customized HTML element can take a lot of lines (very expensive if you paid each one (:wink:) ) to avoid that, use 'CSS classes'. In general, use classes to aesthetic related stuff: color, borders, backgrounds, font faces, sizes, etc.<br />
*Respect W3C standards, and try to use the HTML understandable for all browsers. If one of them has a special feature, think if this feature is so special to break down the HTML in other browsers.<br />
*Do not use PHP short tags <? ?>. Always use full PHP tags <?php ?><br />
*Any rules of the mentioned before: about CSS, well closed HTML tags and JS respect XHTML standards. Give it a try!.<br />
<br />
=Localization=<br />
<br />
Currently we are using the gT(),eT(),ngT() and neT() functions of the limesurvey_lang object for translations.<br />
<br />
Since LimeSurvey is available in 60 languages it is very important that your original English string (which will be picked up automatically for translation by our translators) is done right from the start. Imagine if we have to correct only one string at a later time - then 60 strings become invalid across the project and need to be re-translated by the poor translator souls.<br />
* gT() is the original translation function. It will return a translated version of the string in the currently selected language. ie: echo ''$clang->gT("Hello");''<br />
* ngT() returns multiple translations of a sentence or phrase for which alternate plural forms may apply. ie: ''echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers)'';<br />
* eT() echos the translation directly. (ie: instead of ''echo $clang->gT("Hello");'' you can use ''$clang->eT("Hello");''<br />
* neT() echos the multiple translations of the sentence or phrase for which alternate plural forms may apply directly.<br />
<br />
Please follow these important rules:<br />
*'''Do not embed margin spaces''' in your translation. Instead use proper CSS formatting<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Visible? ');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Visible?');<br />
*'''Do not capitalize words''' except where grammatically correct (like at the beginning of a sentence or for a brand name). LimeSurvey is not a newspaper.<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Create A New Label Set');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Create a new label set');<br />
<br />
<span style='color:#F00'>Wrong</span>: $clang->eT('Google Maps API Key');<br />
<br />
<span style='color:#060'>Right</span>: $clang->eT('Google Maps API key');<br />
*'''Do not concatenate''' several translations to form a sentence or concatenate to an additional information (like a number or string). Instead use the sprint() or sprintf() function with placeholders.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The sum must not be bigger than').$iMaxSum;<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The sum must not be bigger than %s'),$iMaxSum);<br />
<br />
This comes from the problem that in other languages the setting of a sentence can be much different and the information $iMaxSum from the example above might be needed in the middle of the sentence.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The user').$sUsername.$clang->gT('was deleted.');<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The user %s was deleted.'),$sUsername);<br />
*'''Use the n*T functions where applicable'''. These functions show a different translation depending the number of items. Currently LimeSurvey only supports the numbers/situations 1 and >1.<br />
<br />
+Example:<br />
<br />
<span style='color:#F00'>Wrong</span>: echo sprintf($clang->gT('Please select at least %s answer(s).'),$iMinimumAnswers);<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers);<br />
<br />
=Bug tracker=<br />
#First consider if the reported issue is really a bug. If it is a feature request please point the reporter to http://ideas.limesurvey.org and set the issue status to 'Closed'.<br />
#If you would like to work on a bug assign it to yourself.<br />
#Try to reproduce the issue.<br />
##If you cannot reproduce ask the user to provide a small example survey to demonstrate the issue. Then set the issue to 'Feedback'. After the user added the necessary information it will automatically be set to 'Assigned' again.<br />
##If the user does not responds for more than a week ask once again for feedback by adding a comment. After a further week without feedback close the issue.<br />
#After you resolved the issue set the status to resolved AND provide the 'Fixed in version' information.<br />
#After you committed your fix add a comment to the resolved issue 'Fixed in rev. <Subversion revision number>'<br />
#After a release the release technician will set all issues to 'Closed' that were fixed for this release. That signals to the reporter that a fix is available in the version and it was just released.<br />
<br />
=Cross-DB compatibility=<br />
<br />
LimeSurvey targets several database types it can run on: MySQL, Postgres and Microsoft SQL Server. This demands certain precautions when coding<br />
<br />
==Parameter binding==<br />
<br />
Yii/PDO supports parameter binding. Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('attributedescriptions')<br />
<br />
->where("sid = :sid")<br />
<br />
->from('{{surveys}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
If you bind the same value several times do NOT use the same parameter name, instead use a different named parameter for each bind:<br />
<br />
WRONG:<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('sometable')<br />
<br />
->where("sid = :sid and parent_sid= :sid ")<br />
<br />
->from('{{surveys}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
RIGHT:<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('sometable')<br />
<br />
->where("sid = :sid1 and parent_sid= :sid2 ")<br />
<br />
->from('{{surveys}}')<br />
<br />
->bindParam(":sid1", $surveyid, PDO::PARAM_INT)<br />
<br />
->bindParam(":sid2", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
=Miscellaneous=<br />
*Do not use "global" to access to a declared variable in another process. Pass variables or arrays by reference, use the session or the configuration object.<br />
*If using an auxiliary variable makes clear the code or process, just do it. If you are coding a very complex expression, calling to functions with parameters that are other functions:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG:<br />
<br />
iAResult= fa(fb(p1,p2),fc(fd(p3),p4),p5)<br />
<br />
It will be more readable:<br />
<br />
iAuxB = fb(p1,p2)<br />
<br />
iAuxD = fd(p3)<br />
<br />
iAuxC = fc(iAuxD,p4)<br />
<br />
iAResult = fa(iAuxB, iAuxC, p5)<br />
<br />
</syntaxhighlight><br />
<br />
Anyway, if you are in doubt about someone missing the point or you are afraid that your expression is obscure, take the chance of writing it in a more simple way, even if that involves the use of one or more auxiliary variables.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Manage_users&diff=2164Manage users2012-11-15T19:03:01Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
= User management=<br />
<br />
==Create users==<br />
<br />
To create a new user open the user management ('''main menu''' -> '''Create/Edit users ''' [[File:LimeSurveyBenuzerVerwaltung.jpg]]).<br />
<br />
[[File:LimeSurveyAddUser.jpg]]<br />
* Enter the desired username into the textfield '''Username'''.<br />
* Enter the email address into the textfield '''Email'''. Please note<br />
** If you don't want the user to recieve the confirmation email with a link to the LimeSurvey installation, username and password you can use your own email address to send the confirmation email to you. After that you can change the email address to the address of the user.<br />
** LimeSurvey sends out a confirmation email to the address enterd into '''Email'''. This email address will be used as standard contact email address for surveys created by this user.<br />
* Enter the users full name into the textfield '''Full name''' . Please note<br />
** The full name entered here will be used as standard contact person name for surveys created by this user.<br />
* Click '''Add user'''<br />
<br />
So you created a new user. You will find out more about setting user permissions if you continue reading further.<br />
<br />
==Edit users==<br />
<br />
You can use the pen symbol [[File:LimeSurveyBleistiftSymbol.jpg]] to edit a user.<br />
<br />
You can set a new email address, full name and even change the password. If you have finished what you want to do click '''Save'''.<br />
<br />
==Delete users==<br />
<br />
To delete a user account simply click the delete button [[File:LimeSurveyBenutzerLoeschen.jpg]] in the line with the user account that should be deleted and hit '''OK'''.<br />
<br />
=Global permissions=<br />
<br />
Global permissions apply to the whole LimeSurvey installation. If you want to set permissions only for a specific survey you can use the Survey permissions settings.<br />
<br />
==Setting global permissions for a user==<br />
<br />
To set global permissions for a user just click the key symbol [[File:LimeSurveySchluesselSymbol.jpg]].<br />
<br />
[[File:LimeSurveySetGlobalPermissions.jpg]]<br />
<br />
You can now add or remove the following rights.<br />
* '''SuperAdministrator''': This right can only be added or removed by the user called '''admin''' and grants full rights to the whole LimeSurvey installation. '''Please note:''' This right is very powerful and you should be very carfefully with granting this right.<br />
* '''Create survey''': This right lets the user create a survey as well as start, stop and it . This is the standard permission for people creating their own surveys.<br />
* '''Configurator''': With this right a user can check data integrity, save the SQL database to an sql file and view the php info in the global settings.<br />
* '''Create user''': Having this right a user can create new users and delete users created with this account. The newly created users cannot have higher permissions than the parent. If this has to be done a '''SuperAdministrator''' has to grant the rights.<br />
* '''Use all/manage templates''': It allows the user to use all design templates and edit all non standard templates. A person with this right should have sufficient knowledge in terms of HTML/php, Javascript and CSS. If a user not familar with this things should use a specific design template it would be better to use the template permissions.<br />
* '''Manage labels''': This right grants all rights regarding label sets (create, edit and delete).<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
==Setting template permissions for a user==<br />
<br />
With template permissions you can set which design templates a user can select when creating or editing a survey. It might be a good idea to restrict the design templates a user can select in order to prevent unwanted use of design templates not suitable for a user/survey.<br />
<br />
'''Please note:''' If you have a specific design template for a group of users or customers you might want to restrict the access for them to use only the template created for their purpose.<br />
<br />
To set/edit the template permissions for a user simply click the key symbol for design templates [[File:LimeSurveySchluesselSymbolTemplates.jpg]].<br />
<br />
[[File:LimeSurveySetDesignTemplatesLS.jpg]]<br />
<br />
You can now select the design templates this user can select. After you finished your selection/deselection just hit '''Save settings''' .<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
=Setting permissions for a single survey=<br />
<br />
These permissions only apply for a single survey. If you want to set permissions for the whole system you can use the global permissions.<br />
<br />
'''Please note:''' An existing user account is required to set permissions for a single survey. If the account doesn't exist you have to create it first and then change the survey permissions. You don't have to apply any global rights to the user, it is just necessary that the user account itself exists.<br />
<br />
==Setting user permissions for a single survey==<br />
<br />
To change the survey permissions you have to select '''Survey permissions''' from the '''Survey properties''' menu.<br />
<br />
[[File:LimeSurveySurveyPermissions.jpg]]<br />
<br />
In the next step you select the user you want to change the survey rights and click '''Add user'''.<br />
<br />
[[File:LimeSurveyAddSurveyPermission.jpg]]<br />
<br />
After you click '''Set survey permissions''' the survey permissions matrix for the survey and user will be shown.<br />
<br />
[[File:LimeSurveyUserPermissionMatrix.jpg]]<br />
<br />
In this matrix you can set the rights for the different features and parts. You simply click a checkbox if you want to add or remove this right. If you click a checkbox in the first column all rights for this line will be selected/removed.<br />
<br />
In the other columns you can choose whether a user can do a single actions from this feature/part.<br />
<br />
After you finished editing the survey permissions click '''Save now'''.<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
=Use cases=<br />
<br />
In this part of the article we'll provide a few ideas which use cases may exist and how and which rights would be a good choice.<br />
<br />
==A new person in charge for administrating LimeSurvey will be added==<br />
* login as '''admin'''<br />
* Create a new user account<br />
* Set global permissions for user to '''SuperAdministrator'''<br />
* not necessary: Setting the template permissions ('''SuperAdministrator''' has all permissions for all templates)<br />
* not necessary: Setting the survey permissions ('''SuperAdministrator''' has all permissions for all surveys)<br />
<br />
==A new user wants to create own surveys==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set global permissions for user to '''Create survey'''<br />
* Set template permissions for user to the template/s that should be used by the user/user-group<br />
* not necessary: Setting the survey permissions (The creator of a survey has all permissions for his/her surveys)<br />
<br />
==The creator of a survey needs another person to edit his/her survey==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set '''no global permissions''' for user<br />
* Set '''no template permissions''' for user<br />
* Set the survey permissions the way you want. It depends on what the new user should do and how much permissions he/she needs. If he/she should have all permissions for the survey you can select the first checkboxes in the first column with checkboxes (the one with the '''<<''' or '''>>''' button as header).<br />
<br />
==A person responsible for the survey wants to see the results of the survey and export them==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set '''no global permissions''' for user<br />
* Set '''no template permissions''' for user<br />
* Set survey permissions to: '''Responses''': '''View/read''' and '''export''' , '''Statistics''': '''View/read'''<br />
<br />
[[File:LimeSurveyCusomerOwnStatistics.jpg]]<br />
<br />
----<br />
<br />
To be moved somewhere else once better defined:<br />
<br />
There are several classes of possible people who access a LimeSurvey installation. But only one set of people is actually termed a '''user''' in the code and documentation. So lets understand what these classes of people are so we can better understand the terminology of the program.<br />
<br />
{|<br />
|Class||Description<br />
|-<br />
|Installation Administrator || Those people who create login user accounts to allow others to create, edit, activate and/or view surveys and their results. Often can be given access to edit the templates, labelsets and other key features independent of any particular survey stored.<br />
|-<br />
|Survey Administrator || A person with a login account that is given some management access to a particular survey. Each survey can have its own set of users with specific rights to manipulate the survey. These rights can be as broad as to activate a survey and possibly edit its question base. They can be as minimum as simply able to review the results to date.<br />
|-<br />
|Participant || Those people who simply respond or participate in taking a survey. They may or may not have token access. They do not need a login account to the administrative interface and thus are not termed users.<br />
|-<br />
|Installer || A special class of person who has access to the MySQL (or similar) database server and possibly the command line interface of the computers operating system in order to install and configure the survey software. This person is asked to setup the initial SuperAdmin user account from which other user login accounts can be created.<br />
|-<br />
|Developer || An very special class of person who has access to the source code and can manipulate it to change the programs behavior. Generally only done with versions of the survey that are not available for live, active surveys. <br />
|}<br />
<br />
=Use one-time passwords=<br />
<br />
Since version 1.81 a user can call the limesurvey login at /limesurvey/admin and pass username and a one time password which was previously written into the users table (column one_time_pw) by an external application.<br />
<br />
To enable this login method [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings#Use_one_time_passwords a setting has to be turned on] ($use_one_time_passwords = true;) in config.php.<br />
<br />
The URL has to contain the following variables:<br />
* '''user:''' The username normally used to login into Limesurvey. This username has to exist in the 'users' table of the database.<br />
* '''onepass:''' The plain text password which is then compared to the password in the 'users' table<br />
<br />
A valid URL to login using a one-time password will look like this...<br />
<br />
... for 1.81 to 1.92:<br />
<br />
<div class="simplebox">http://www.yourdomain.org/limesurvey/admin/admin.php?user=myusername&onepass;=secretpassword</div><br />
<br />
...for 2.0 or later:<br />
<br />
<div class="simplebox">http://www.yourdomain.org/limesurvey/index.php/admin/authentication/login?user=myusername&onepass;=secretpassword</div><br />
<br />
'''Things to watch out for:'''<br />
* One time passwords have to be enabled by setting use_one_time_passwords = true; in config.php<br />
* The passed username has to exist in Limesurvey's ''users'' table<br />
* The one time password, which can be set by an external application, has to be stored as [http://de.php.net/md5 MD5 hash] in column ''one_time_pw'' of table ''users''<br />
* The passed plain text password will be hashed using md5() function and will then be compared to the stored hash in column ''one_time_pw'' of table ''users''. Both passwords have to match.<br />
* After the first login with the one time password this password is deleted from the database. The user won't be able to login with this password anymore.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Manage_users&diff=2165Manage users2012-11-15T19:02:27Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
= User management=<br />
<br />
==Create users==<br />
<br />
To create a new user open the user management ('''main menu''' -> '''Create/Edit users ''' [[File:LimeSurveyBenuzerVerwaltung.jpg]]).<br />
<br />
[[File:LimeSurveyAddUser.jpg]]<br />
* Enter the desired username into the textfield '''Username'''.<br />
* Enter the email address into the textfield '''Email'''. Please note<br />
** If you don't want the user to recieve the confirmation email with a link to the LimeSurvey installation, username and password you can use your own email address to send the confirmation email to you. After that you can change the email address to the address of the user.<br />
** LimeSurvey sends out a confirmation email to the address enterd into '''Email'''. This email address will be used as standard contact email address for surveys created by this user.<br />
* Enter the users full name into the textfield '''Full name''' . Please note<br />
** The full name entered here will be used as standard contact person name for surveys created by this user.<br />
* Click '''Add user'''<br />
<br />
So you created a new user. You will find out more about setting user permissions if you continue reading further.<br />
<br />
==Edit users==<br />
<br />
You can use the pen symbol [[File:LimeSurveyBleistiftSymbol.jpg]] to edit a user.<br />
<br />
You can set a new email address, full name and even change the password. If you have finished what you want to do click '''Save'''.<br />
<br />
==Delete users==<br />
<br />
To delete a user account simply click the delete button [[File:LimeSurveyBenutzerLoeschen.jpg]] in the line with the user account that should be deleted and hit '''OK'''.<br />
<br />
=Global permissions=<br />
<br />
Global permissions apply to the whole LimeSurvey installation. If you want to set permissions only for a specific survey you can use the Survey permissions settings.<br />
<br />
==Setting global permissions for a user==<br />
<br />
To set global permissions for a user just click the key symbol [[File:LimeSurveySchluesselSymbol.jpg]].<br />
<br />
[[File:LimeSurveySetGlobalPermissions.jpg]]<br />
<br />
You can now add or remove the following rights.<br />
* '''SuperAdministrator''': This right can only be added or removed by the user called '''admin''' and grants full rights to the whole LimeSurvey installation. '''Please note:''' This right is very powerful and you should be very carfefully with granting this right.<br />
* '''Create survey''': This right lets the user create a survey as well as start, stop and it . This is the standard permission for people creating their own surveys.<br />
* '''Configurator''': With this right a user can check data integrity, save the SQL database to an sql file and view the php info in the global settings.<br />
* '''Create user''': Having this right a user can create new users and delete users created with this account. The newly created users cannot have higher permissions than the parent. If this has to be done a '''SuperAdministrator''' has to grant the rights.<br />
* '''Use all/manage templates''': It allows the user to use all design templates and edit all non standard templates. A person with this right should have sufficient knowledge in terms of HTML/php, Javascript and CSS. If a user not familar with this things should use a specific design template it would be better to use the template permissions.<br />
* '''Manage labels''': This right grants all rights regarding label sets (create, edit and delete).<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
==Setting template permissions for a user==<br />
<br />
With template permissions you can set which design templates a user can select when creating or editing a survey. It might be a good idea to restrict the design templates a user can select in order to prevent unwanted use of design templates not suitable for a user/survey.<br />
<br />
'''Please note:''' If you have a specific design template for a group of users or customers you might want to restrict the access for them to use only the template created for their purpose.<br />
<br />
To set/edit the template permissions for a user simply click the key symbol for design templates [[File:LimeSurveySchluesselSymbolTemplates.jpg]].<br />
<br />
[[File:LimeSurveySetDesignTemplatesLS.jpg]]<br />
<br />
You can now select the design templates this user can select. After you finished your selection/deselection just hit '''Save settings''' .<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
=Setting permissions for a single survey=<br />
<br />
These permissions only apply for a single survey. If you want to set permissions for the whole system you can use the global permissions.<br />
<br />
'''Please note:''' An existing user account is required to set permissions for a single survey. If the account doesn't exist you have to create it first and then change the survey permissions. You don't have to apply any global rights to the user, it is just necessary that the user account itself exists.<br />
<br />
==Setting user permissions for a single survey==<br />
<br />
To change the survey permissions you have to select '''Survey permissions''' from the '''Survey properties''' menu.<br />
<br />
[[File:LimeSurveySurveyPermissions.jpg]]<br />
<br />
In the next step you select the user you want to change the survey rights and click '''Add user'''.<br />
<br />
[[File:LimeSurveyAddSurveyPermission.jpg]]<br />
<br />
After you click '''Set survey permissions''' the survey permissions matrix for the survey and user will be shown.<br />
<br />
[[File:LimeSurveyUserPermissionMatrix.jpg]]<br />
<br />
In this matrix you can set the rights for the different features and parts. You simply click a checkbox if you want to add or remove this right. If you click a checkbox in the first column all rights for this line will be selected/removed.<br />
<br />
In the other columns you can choose whether a user can do a single actions from this feature/part.<br />
<br />
After you finished editing the survey permissions click '''Save now'''.<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
=Use cases=<br />
<br />
In this part of the article we'll provide a few ideas which use cases may exist and how and which rights would be a good choice.<br />
<br />
==A new person in charge for administrating LimeSurvey will be added==<br />
* login as '''admin'''<br />
* Create a new user account<br />
* Set global permissions for user to '''SuperAdministrator'''<br />
* not necessary: Setting the template permissions ('''SuperAdministrator''' has all permissions for all templates)<br />
* not necessary: Setting the survey permissions ('''SuperAdministrator''' has all permissions for all surveys)<br />
<br />
==A new user wants to create own surveys==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set global permissions for user to '''Create survey'''<br />
* Set template permissions for user to the template/s that should be used by the user/user-group<br />
* not necessary: Setting the survey permissions (The creator of a survey has all permissions for his/her surveys)<br />
<br />
==The creator of a survey needs another person to edit his/her survey==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set '''no global permissions''' for user<br />
* Set '''no template permissions''' for user<br />
* Set the survey permissions the way you want. It depends on what the new user should do and how much permissions he/she needs. If he/she should have all permissions for the survey you can select the first checkboxes in the first column with checkboxes (the one with the '''<<''' or '''>>''' button as header).<br />
<br />
==A person responsible for the survey wants to see the results of the survey and export them==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set '''no global permissions''' for user<br />
* Set '''no template permissions''' for user<br />
* Set survey permissions to: '''Responses''': '''View/read''' and '''export''' , '''Statistics''': '''View/read'''<br />
<br />
[[File:LimeSurveyCusomerOwnStatistics.jpg]]<br />
<br />
----<br />
<br />
To be moved somewhere else once better defined:<br />
<br />
There are several classes of possible people who access a LimeSurvey installation. But only one set of people is actually termed a '''user''' in the code and documentation. So lets understand what these classes of people are so we can better understand the terminology of the program.<br />
<br />
{|<br />
|Class||Description<br />
|-<br />
|Installation Administrator || Those people who create login user accounts to allow others to create, edit, activate and/or view surveys and their results. Often can be given access to edit the templates, labelsets and other key features independent of any particular survey stored.<br />
|-<br />
|Survey Administrator || A person with a login account that is given some management access to a particular survey. Each survey can have its own set of users with specific rights to manipulate the survey. These rights can be as broad as to activate a survey and possibly edit its question base. They can be as minimum as simply able to review the results to date.<br />
|-<br />
|Participant || Those people who simply respond or participate in taking a survey. They may or may not have token access. They do not need a login account to the administrative interface and thus are not termed users.<br />
|-<br />
|Installer || A special class of person who has access to the MySQL (or similar) database server and possibly the command line interface of the computers operating system in order to install and configure the survey software. This person is asked to setup the initial SuperAdmin user account from which other user login accounts can be created.<br />
|-<br />
|Developer || An very special class of person who has access to the source code and can manipulate it to change the programs behavior. Generally only done with versions of the survey that are not available for live, active surveys. <br />
|}<br />
<br />
=Use one time passwords=<br />
<br />
Since version 1.81 a user can call the limesurvey login at /limesurvey/admin and pass username and a one time password which was previously written into the users table (column one_time_pw) by an external application.<br />
<br />
To enable this login method [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings#Use_one_time_passwords a setting has to be turned on] ($use_one_time_passwords = true;) in config.php.<br />
<br />
The URL has to contain the following variables:<br />
* '''user:''' The username normally used to login into Limesurvey. This username has to exist in the 'users' table of the database.<br />
* '''onepass:''' The plain text password which is then compared to the password in the 'users' table<br />
<br />
A valid URL to login using a one-time password will look like this...<br />
<br />
... for 1.81 to 1.92:<br />
<br />
<div class="simplebox">http://www.yourdomain.org/limesurvey/admin/admin.php?user=myusername&onepass;=secretpassword</div><br />
<br />
...for 2.0 or later:<br />
<br />
<div class="simplebox">http://www.yourdomain.org/limesurvey/index.php/admin/authentication/login?user=myusername&onepass;=secretpassword</div><br />
<br />
'''Things to watch out for:'''<br />
* One time passwords have to be enabled by setting use_one_time_passwords = true; in config.php<br />
* The passed username has to exist in Limesurvey's ''users'' table<br />
* The one time password, which can be set by an external application, has to be stored as [http://de.php.net/md5 MD5 hash] in column ''one_time_pw'' of table ''users''<br />
* The passed plain text password will be hashed using md5() function and will then be compared to the stored hash in column ''one_time_pw'' of table ''users''. Both passwords have to match.<br />
* After the first login with the one time password this password is deleted from the database. The user won't be able to login with this password anymore.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Manage_users&diff=2166Manage users2012-11-15T18:59:18Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
= User management=<br />
<br />
==Create users==<br />
<br />
To create a new user open the user management ('''main menu''' -> '''Create/Edit users ''' [[File:LimeSurveyBenuzerVerwaltung.jpg]]).<br />
<br />
[[File:LimeSurveyAddUser.jpg]]<br />
* Enter the desired username into the textfield '''Username'''.<br />
* Enter the email address into the textfield '''Email'''. Please note<br />
** If you don't want the user to recieve the confirmation email with a link to the LimeSurvey installation, username and password you can use your own email address to send the confirmation email to you. After that you can change the email address to the address of the user.<br />
** LimeSurvey sends out a confirmation email to the address enterd into '''Email'''. This email address will be used as standard contact email address for surveys created by this user.<br />
* Enter the users full name into the textfield '''Full name''' . Please note<br />
** The full name entered here will be used as standard contact person name for surveys created by this user.<br />
* Click '''Add user'''<br />
<br />
So you created a new user. You will find out more about setting user permissions if you continue reading further.<br />
<br />
==Edit users==<br />
<br />
You can use the pen symbol [[File:LimeSurveyBleistiftSymbol.jpg]] to edit a user.<br />
<br />
You can set a new email address, full name and even change the password. If you have finished what you want to do click '''Save'''.<br />
<br />
==Delete users==<br />
<br />
To delete a user account simply click the delete button [[File:LimeSurveyBenutzerLoeschen.jpg]] in the line with the user account that should be deleted and hit '''OK'''.<br />
<br />
=Global permissions=<br />
<br />
Global permissions apply to the whole LimeSurvey installation. If you want to set permissions only for a specific survey you can use the Survey permissions settings.<br />
<br />
==Setting global permissions for a user==<br />
<br />
To set global permissions for a user just click the key symbol [[File:LimeSurveySchluesselSymbol.jpg]].<br />
<br />
[[File:LimeSurveySetGlobalPermissions.jpg]]<br />
<br />
You can now add or remove the following rights.<br />
* '''SuperAdministrator''': This right can only be added or removed by the user called '''admin''' and grants full rights to the whole LimeSurvey installation. '''Please note:''' This right is very powerful and you should be very carfefully with granting this right.<br />
* '''Create survey''': This right lets the user create a survey as well as start, stop and it . This is the standard permission for people creating their own surveys.<br />
* '''Configurator''': With this right a user can check data integrity, save the SQL database to an sql file and view the php info in the global settings.<br />
* '''Create user''': Having this right a user can create new users and delete users created with this account. The newly created users cannot have higher permissions than the parent. If this has to be done a '''SuperAdministrator''' has to grant the rights.<br />
* '''Use all/manage templates''': It allows the user to use all design templates and edit all non standard templates. A person with this right should have sufficient knowledge in terms of HTML/php, Javascript and CSS. If a user not familar with this things should use a specific design template it would be better to use the template permissions.<br />
* '''Manage labels''': This right grants all rights regarding label sets (create, edit and delete).<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
==Setting template permissions for a user==<br />
<br />
With template permissions you can set which design templates a user can select when creating or editing a survey. It might be a good idea to restrict the design templates a user can select in order to prevent unwanted use of design templates not suitable for a user/survey.<br />
<br />
'''Please note:''' If you have a specific design template for a group of users or customers you might want to restrict the access for them to use only the template created for their purpose.<br />
<br />
To set/edit the template permissions for a user simply click the key symbol for design templates [[File:LimeSurveySchluesselSymbolTemplates.jpg]].<br />
<br />
[[File:LimeSurveySetDesignTemplatesLS.jpg]]<br />
<br />
You can now select the design templates this user can select. After you finished your selection/deselection just hit '''Save settings''' .<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
=Setting permissions for a single survey=<br />
<br />
These permissions only apply for a single survey. If you want to set permissions for the whole system you can use the global permissions.<br />
<br />
'''Please note:''' An existing user account is required to set permissions for a single survey. If the account doesn't exist you have to create it first and then change the survey permissions. You don't have to apply any global rights to the user, it is just necessary that the user account itself exists.<br />
<br />
==Setting user permissions for a single survey==<br />
<br />
To change the survey permissions you have to select '''Survey permissions''' from the '''Survey properties''' menu.<br />
<br />
[[File:LimeSurveySurveyPermissions.jpg]]<br />
<br />
In the next step you select the user you want to change the survey rights and click '''Add user'''.<br />
<br />
[[File:LimeSurveyAddSurveyPermission.jpg]]<br />
<br />
After you click '''Set survey permissions''' the survey permissions matrix for the survey and user will be shown.<br />
<br />
[[File:LimeSurveyUserPermissionMatrix.jpg]]<br />
<br />
In this matrix you can set the rights for the different features and parts. You simply click a checkbox if you want to add or remove this right. If you click a checkbox in the first column all rights for this line will be selected/removed.<br />
<br />
In the other columns you can choose whether a user can do a single actions from this feature/part.<br />
<br />
After you finished editing the survey permissions click '''Save now'''.<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
=Use cases=<br />
<br />
In this part of the article we'll provide a few ideas which use cases may exist and how and which rights would be a good choice.<br />
<br />
==A new person in charge for administrating LimeSurvey will be added==<br />
* login as '''admin'''<br />
* Create a new user account<br />
* Set global permissions for user to '''SuperAdministrator'''<br />
* not necessary: Setting the template permissions ('''SuperAdministrator''' has all permissions for all templates)<br />
* not necessary: Setting the survey permissions ('''SuperAdministrator''' has all permissions for all surveys)<br />
<br />
==A new user wants to create own surveys==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set global permissions for user to '''Create survey'''<br />
* Set template permissions for user to the template/s that should be used by the user/user-group<br />
* not necessary: Setting the survey permissions (The creator of a survey has all permissions for his/her surveys)<br />
<br />
==The creator of a survey needs another person to edit his/her survey==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set '''no global permissions''' for user<br />
* Set '''no template permissions''' for user<br />
* Set the survey permissions the way you want. It depends on what the new user should do and how much permissions he/she needs. If he/she should have all permissions for the survey you can select the first checkboxes in the first column with checkboxes (the one with the '''<<''' or '''>>''' button as header).<br />
<br />
==A person responsible for the survey wants to see the results of the survey and export them==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set '''no global permissions''' for user<br />
* Set '''no template permissions''' for user<br />
* Set survey permissions to: '''Responses''': '''View/read''' and '''export''' , '''Statistics''': '''View/read'''<br />
<br />
[[File:LimeSurveyCusomerOwnStatistics.jpg]]<br />
<br />
----<br />
<br />
To be moved somewhere else once better defined:<br />
<br />
There are several classes of possible people who access a LimeSurvey installation. But only one set of people is actually termed a '''user''' in the code and documentation. So lets understand what these classes of people are so we can better understand the terminology of the program.<br />
<br />
{|<br />
|Class||Description<br />
|-<br />
|Installation Administrator || Those people who create login user accounts to allow others to create, edit, activate and/or view surveys and their results. Often can be given access to edit the templates, labelsets and other key features independent of any particular survey stored.<br />
|-<br />
|Survey Administrator || A person with a login account that is given some management access to a particular survey. Each survey can have its own set of users with specific rights to manipulate the survey. These rights can be as broad as to activate a survey and possibly edit its question base. They can be as minimum as simply able to review the results to date.<br />
|-<br />
|Participant || Those people who simply respond or participate in taking a survey. They may or may not have token access. They do not need a login account to the administrative interface and thus are not termed users.<br />
|-<br />
|Installer || A special class of person who has access to the MySQL (or similar) database server and possibly the command line interface of the computers operating system in order to install and configure the survey software. This person is asked to setup the initial SuperAdmin user account from which other user login accounts can be created.<br />
|-<br />
|Developer || An very special class of person who has access to the source code and can manipulate it to change the programs behavior. Generally only done with versions of the survey that are not available for live, active surveys. <br />
|}<br />
<br />
=Use one time passwords=<br />
<br />
Since version 1.81 a user can call the limesurvey login at /limesurvey/admin and pass username and a one time password which was previously written into the users table (column one_time_pw) by an external application.<br />
<br />
To enable this login method [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings#Use_one_time_passwords a setting has to be turned on] ($use_one_time_passwords = true;) in config.php.<br />
<br />
The URL has to contain the following variables:<br />
* '''user:''' The username normally used to login into Limesurvey. This username has to exist in the 'users' table of the database.<br />
* '''onepass:''' The plain text password which is then compared to the password in the 'users' table<br />
<br />
A valid URL to login using a one-time password will look like this...<br />
<br />
... for 1.81 to 1.92:<br />
<br />
<div class="simplebox">http://www.yourdomain.org/limesurvey/admin/admin.php?user=myusername&onepass;=secretpassword</div><br />
<br />
...for 2.0 or later:<br />
<br />
<div class="simplebox">http://www.yourdomain.org/limesurvey/index.php/admin/authentication/login?user=myusername&onepass;=secretpassword</div><br />
<br />
'''Things to watch out for:'''<br />
* One time passwords have to be enabled by setting $use_one_time_passwords = true; in config.php<br />
* The passed username has to exist in Limesurvey's ''users'' table<br />
* The one time password, which can be set by an external application, has to be stored as [http://de.php.net/md5 MD5 hash] in column ''one_time_pw'' of table ''users''<br />
* The passed plain text password will be hashed using md5() function and will then be compared to the stored hash in column ''one_time_pw'' of table ''users''. Both passwords have to match.<br />
* After the first login with the one time password this password is deleted from the database. The user won't be able to login with this password anymore. If you are confronted with session timeout problems [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings#Survey_Behavior raise the setting for $sessionlifetime] (default is 3600 seconds).</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Manage_users&diff=2167Manage users2012-11-15T18:58:05Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
= User management=<br />
<br />
==Create users==<br />
<br />
To create a new user open the user management ('''main menu''' -> '''Create/Edit users ''' [[File:LimeSurveyBenuzerVerwaltung.jpg]]).<br />
<br />
[[File:LimeSurveyAddUser.jpg]]<br />
* Enter the desired username into the textfield '''Username'''.<br />
* Enter the email address into the textfield '''Email'''. Please note<br />
** If you don't want the user to recieve the confirmation email with a link to the LimeSurvey installation, username and password you can use your own email address to send the confirmation email to you. After that you can change the email address to the address of the user.<br />
** LimeSurvey sends out a confirmation email to the address enterd into '''Email'''. This email address will be used as standard contact email address for surveys created by this user.<br />
* Enter the users full name into the textfield '''Full name''' . Please note<br />
** The full name entered here will be used as standard contact person name for surveys created by this user.<br />
* Click '''Add user'''<br />
<br />
So you created a new user. You will find out more about setting user permissions if you continue reading further.<br />
<br />
==Edit users==<br />
<br />
You can use the pen symbol [[File:LimeSurveyBleistiftSymbol.jpg]] to edit a user.<br />
<br />
You can set a new email address, full name and even change the password. If you have finished what you want to do click '''Save'''.<br />
<br />
==Delete users==<br />
<br />
To delete a user account simply click the delete button [[File:LimeSurveyBenutzerLoeschen.jpg]] in the line with the user account that should be deleted and hit '''OK'''.<br />
<br />
=Global permissions=<br />
<br />
Global permissions apply to the whole LimeSurvey installation. If you want to set permissions only for a specific survey you can use the Survey permissions settings.<br />
<br />
==Setting global permissions for a user==<br />
<br />
To set global permissions for a user just click the key symbol [[File:LimeSurveySchluesselSymbol.jpg]].<br />
<br />
[[File:LimeSurveySetGlobalPermissions.jpg]]<br />
<br />
You can now add or remove the following rights.<br />
* '''SuperAdministrator''': This right can only be added or removed by the user called '''admin''' and grants full rights to the whole LimeSurvey installation. '''Please note:''' This right is very powerful and you should be very carfefully with granting this right.<br />
* '''Create survey''': This right lets the user create a survey as well as start, stop and it . This is the standard permission for people creating their own surveys.<br />
* '''Configurator''': With this right a user can check data integrity, save the SQL database to an sql file and view the php info in the global settings.<br />
* '''Create user''': Having this right a user can create new users and delete users created with this account. The newly created users cannot have higher permissions than the parent. If this has to be done a '''SuperAdministrator''' has to grant the rights.<br />
* '''Use all/manage templates''': It allows the user to use all design templates and edit all non standard templates. A person with this right should have sufficient knowledge in terms of HTML/php, Javascript and CSS. If a user not familar with this things should use a specific design template it would be better to use the template permissions.<br />
* '''Manage labels''': This right grants all rights regarding label sets (create, edit and delete).<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
==Setting template permissions for a user==<br />
<br />
With template permissions you can set which design templates a user can select when creating or editing a survey. It might be a good idea to restrict the design templates a user can select in order to prevent unwanted use of design templates not suitable for a user/survey.<br />
<br />
'''Please note:''' If you have a specific design template for a group of users or customers you might want to restrict the access for them to use only the template created for their purpose.<br />
<br />
To set/edit the template permissions for a user simply click the key symbol for design templates [[File:LimeSurveySchluesselSymbolTemplates.jpg]].<br />
<br />
[[File:LimeSurveySetDesignTemplatesLS.jpg]]<br />
<br />
You can now select the design templates this user can select. After you finished your selection/deselection just hit '''Save settings''' .<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
=Setting permissions for a single survey=<br />
<br />
These permissions only apply for a single survey. If you want to set permissions for the whole system you can use the global permissions.<br />
<br />
'''Please note:''' An existing user account is required to set permissions for a single survey. If the account doesn't exist you have to create it first and then change the survey permissions. You don't have to apply any global rights to the user, it is just necessary that the user account itself exists.<br />
<br />
==Setting user permissions for a single survey==<br />
<br />
To change the survey permissions you have to select '''Survey permissions''' from the '''Survey properties''' menu.<br />
<br />
[[File:LimeSurveySurveyPermissions.jpg]]<br />
<br />
In the next step you select the user you want to change the survey rights and click '''Add user'''.<br />
<br />
[[File:LimeSurveyAddSurveyPermission.jpg]]<br />
<br />
After you click '''Set survey permissions''' the survey permissions matrix for the survey and user will be shown.<br />
<br />
[[File:LimeSurveyUserPermissionMatrix.jpg]]<br />
<br />
In this matrix you can set the rights for the different features and parts. You simply click a checkbox if you want to add or remove this right. If you click a checkbox in the first column all rights for this line will be selected/removed.<br />
<br />
In the other columns you can choose whether a user can do a single actions from this feature/part.<br />
<br />
After you finished editing the survey permissions click '''Save now'''.<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
=Use cases=<br />
<br />
In this part of the article we'll provide a few ideas which use cases may exist and how and which rights would be a good choice.<br />
<br />
==A new person in charge for administrating LimeSurvey will be added==<br />
* login as '''admin'''<br />
* Create a new user account<br />
* Set global permissions for user to '''SuperAdministrator'''<br />
* not necessary: Setting the template permissions ('''SuperAdministrator''' has all permissions for all templates)<br />
* not necessary: Setting the survey permissions ('''SuperAdministrator''' has all permissions for all surveys)<br />
<br />
==A new user wants to create own surveys==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set global permissions for user to '''Create survey'''<br />
* Set template permissions for user to the template/s that should be used by the user/user-group<br />
* not necessary: Setting the survey permissions (The creator of a survey has all permissions for his/her surveys)<br />
<br />
==The creator of a survey needs another person to edit his/her survey==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set '''no global permissions''' for user<br />
* Set '''no template permissions''' for user<br />
* Set the survey permissions the way you want. It depends on what the new user should do and how much permissions he/she needs. If he/she should have all permissions for the survey you can select the first checkboxes in the first column with checkboxes (the one with the '''<<''' or '''>>''' button as header).<br />
<br />
==A person responisble for the survey wants to see the results of the survey and export them==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set '''no global permissions''' for user<br />
* Set '''no template permissions''' for user<br />
* Set survey permissions to: '''Responses''': '''View/read''' and '''export''' , '''Statistics''': '''View/read'''<br />
<br />
[[File:LimeSurveyCusomerOwnStatistics.jpg]]<br />
<br />
----<br />
<br />
Article was translated and used with approval from '''vierundzwanzig''' (24/7 IT-SERVICES GmbH).<br />
<br />
----<br />
<br />
----<br />
<br />
To be moved somewhere else once better defined:<br />
<br />
There are several classes of possible people who access a LimeSurvey installation. But only one set of people is actually termed a '''user''' in the code and documentation. So lets understand what these classes of people are so we can better understand the terminology of the program.<br />
<br />
{|<br />
|Class||Description<br />
|-<br />
|Installation Administrator || Those people who create login user accounts to allow others to create, edit, activate and/or view surveys and their results. Often can be given access to edit the templates, labelsets and other key features independent of any particular survey stored.<br />
|-<br />
|Survey Administrator || A person with a login account that is given some management access to a particular survey. Each survey can have its own set of users with specific rights to manipulate the survey. These rights can be as broad as to activate a survey and possibly edit its question base. They can be as minimum as simply able to review the results to date.<br />
|-<br />
|Participant || Those people who simply respond or participate in taking a survey. They may or may not have token access. They do not need a login account to the administrative interface and thus are not termed users.<br />
|-<br />
|Installer || A special class of person who has access to the MySQL (or similar) database server and possibly the command line interface of the computers operating system in order to install and configure the survey software. This person is asked to setup the initial SuperAdmin user account from which other user login accounts can be created.<br />
|-<br />
|Developer || An very special class of person who has access to the source code and can manipulate it to change the programs behavior. Generally only done with versions of the survey that are not available for live, active surveys. <br />
|}<br />
<br />
=Use one time passwords=<br />
<br />
Since version 1.81 a user can call the limesurvey login at /limesurvey/admin and pass username and a one time password which was previously written into the users table (column one_time_pw) by an external application.<br />
<br />
To enable this login method [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings#Use_one_time_passwords a setting has to be turned on] ($use_one_time_passwords = true;) in config.php.<br />
<br />
The URL has to contain the following variables:<br />
* '''user:''' The username normally used to login into Limesurvey. This username has to exist in the 'users' table of the database.<br />
* '''onepass:''' The plain text password which is then compared to the password in the 'users' table<br />
<br />
A valid URL to login using a one-time password will look like this...<br />
<br />
... for 1.81 to 1.92:<br />
<br />
<div class="simplebox">http://www.yourdomain.org/limesurvey/admin/admin.php?user=myusername&onepass;=secretpassword</div><br />
<br />
...for 2.0 or later:<br />
<br />
<div class="simplebox">http://www.yourdomain.org/limesurvey/index.php/admin/authentication/login?user=myusername&onepass;=secretpassword</div><br />
<br />
'''Things to watch out for:'''<br />
* One time passwords have to be enabled by setting $use_one_time_passwords = true; in config.php<br />
* The passed username has to exist in Limesurvey's ''users'' table<br />
* The one time password, which can be set by an external application, has to be stored as [http://de.php.net/md5 MD5 hash] in column ''one_time_pw'' of table ''users''<br />
* The passed plain text password will be hashed using md5() function and will then be compared to the stored hash in column ''one_time_pw'' of table ''users''. Both passwords have to match.<br />
* After the first login with the one time password this password is deleted from the database. The user won't be able to login with this password anymore. If you are confronted with session timeout problems [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings#Survey_Behavior raise the setting for $sessionlifetime] (default is 3600 seconds).</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Manage_users&diff=2168Manage users2012-11-15T18:57:42Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
= User management=<br />
<br />
==Create users==<br />
<br />
To create a new user open the user management ('''main menu''' -> '''Create/Edit users ''' [[File:LimeSurveyBenuzerVerwaltung.jpg]]).<br />
<br />
[[File:LimeSurveyAddUser.jpg]]<br />
* Enter the desired username into the textfield '''Username'''.<br />
* Enter the email address into the textfield '''Email'''. Please note<br />
** If you don't want the user to recieve the confirmation email with a link to the LimeSurvey installation, username and password you can use your own email address to send the confirmation email to you. After that you can change the email address to the address of the user.<br />
** LimeSurvey sends out a confirmation email to the address enterd into '''Email'''. This email address will be used as standard contact email address for surveys created by this user.<br />
* Enter the users full name into the textfield '''Full name''' . Please note<br />
** The full name entered here will be used as standard contact person name for surveys created by this user.<br />
* Click '''Add user'''<br />
<br />
So you created a new user. You will find out more about setting user permissions if you continue reading further.<br />
<br />
==Edit users==<br />
<br />
You can use the pen symbol [[File:LimeSurveyBleistiftSymbol.jpg]] to edit a user.<br />
<br />
You can set a new email address, full name and even change the password. If you have finished what you want to do click '''Save'''.<br />
<br />
==Delete users==<br />
<br />
To delete a user account simply click the delete button [[File:LimeSurveyBenutzerLoeschen.jpg]] in the line with the user account that should be deleted and hit '''OK'''.<br />
<br />
=Global permissions=<br />
<br />
Global permissions apply to the whole LimeSurvey installation. If you want to set permissions only for a specific survey you can use the Survey permissions settings.<br />
<br />
==Setting global permissions for a user==<br />
<br />
To set global permissions for a user just click the key symbol [[File:LimeSurveySchluesselSymbol.jpg]].<br />
<br />
[[File:LimeSurveySetGlobalPermissions.jpg]]<br />
<br />
You can now add or remove the following rights.<br />
* '''SuperAdministrator''': This right can only be added or removed by the user called '''admin''' and grants full rights to the whole LimeSurvey installation. '''Please note:''' This right is very powerful and you should be very carfefully with granting this right.<br />
* '''Create survey''': This right lets the user create a survey as well as start, stop and it . This is the standard permission for people creating their own surveys.<br />
* '''Configurator''': With this right a user can check data integrity, save the SQL database to an sql file and view the php info in the global settings.<br />
* '''Create user''': Having this right a user can create new users and delete users created with this account. The newly created users cannot have higher permissions than the parent. If this has to be done a '''SuperAdministrator''' has to grant the rights.<br />
* '''Use all/manage templates''': It allows the user to use all design templates and edit all non standard templates. A person with this right should have sufficient knowledge in terms of HTML/php, Javascript and CSS. If a user not familar with this things should use a specific design template it would be better to use the template permissions.<br />
* '''Manage labels''': This right grants all rights regarding label sets (create, edit and delete).<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
==Setting template permissions for a user==<br />
<br />
With template permissions you can set which design templates a user can select when creating or editing a survey. It might be a good idea to restrict the design templates a user can select in order to prevent unwanted use of design templates not suitable for a user/survey.<br />
<br />
'''Please note:''' If you have a specific design template for a group of users or customers you might want to restrict the access for them to use only the template created for their purpose.<br />
<br />
To set/edit the template permissions for a user simply click the key symbol for design templates [[File:LimeSurveySchluesselSymbolTemplates.jpg]].<br />
<br />
[[File:LimeSurveySetDesignTemplatesLS.jpg]]<br />
<br />
You can now select the design templates this user can select. After you finished your selection/deselection just hit '''Save settings''' .<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
=Setting permissions for a single survey=<br />
<br />
These permissions only apply for a single survey. If you want to set permissions for the whole system you can use the global permissions.<br />
<br />
'''Please note:''' An existing user account is required to set permissions for a single survey. If the account doesn't exist you have to create it first and then change the survey permissions. You don't have to apply any global rights to the user, it is just necessary that the user account itself exists.<br />
<br />
==Setting user permissions for a single survey==<br />
<br />
To change the survey permissions you have to select '''Survey permissions''' from the '''Survey properties''' menu.<br />
<br />
[[File:LimeSurveySurveyPermissions.jpg]]<br />
<br />
In the next step you select the user you want to change the survey rights and click '''Add user'''.<br />
<br />
[[File:LimeSurveyAddSurveyPermission.jpg]]<br />
<br />
After you click '''Set survey permissions''' the survey permissions matrix for the survey and user will be shown.<br />
<br />
[[File:LimeSurveyUserPermissionMatrix.jpg]]<br />
<br />
In this matrix you can set the rights for the different features and parts. You simply click a checkbox if you want to add or remove this right. If you click a checkbox in the first column all rights for this line will be selected/removed.<br />
<br />
In the other columns you can choose whether a user can do a single actions from this feature/part.<br />
<br />
After you finished editing the survey permissions click '''Save now'''.<br />
<br />
The most important use cases for granting user rights are collected at the '''use cases''' part of this article.<br />
<br />
=use cases=<br />
<br />
In this part of the article we'll provide a few ideas which use cases may exist and how and which rights would be a good choice.<br />
<br />
==A new person in charge for administrating LimeSurvey will be added==<br />
* login as '''admin'''<br />
* Create a new user account<br />
* Set global permissions for user to '''SuperAdministrator'''<br />
* not necessary: Setting the template permissions ('''SuperAdministrator''' has all permissions for all templates)<br />
* not necessary: Setting the survey permissions ('''SuperAdministrator''' has all permissions for all surveys)<br />
<br />
==A new user wants to create own surveys==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set global permissions for user to '''Create survey'''<br />
* Set template permissions for user to the template/s that should be used by the user/user-group<br />
* not necessary: Setting the survey permissions (The creator of a survey has all permissions for his/her surveys)<br />
<br />
==The creator of a survey needs another person to edit his/her survey==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set '''no global permissions''' for user<br />
* Set '''no template permissions''' for user<br />
* Set the survey permissions the way you want. It depends on what the new user should do and how much permissions he/she needs. If he/she should have all permissions for the survey you can select the first checkboxes in the first column with checkboxes (the one with the '''<<''' or '''>>''' button as header).<br />
<br />
==A person responisble for the survey wants to see the results of the survey and export them==<br />
* login as '''admin''' or user with '''SuperAdministrator''' permission.<br />
* Create a new user account<br />
* Set '''no global permissions''' for user<br />
* Set '''no template permissions''' for user<br />
* Set survey permissions to: '''Responses''': '''View/read''' and '''export''' , '''Statistics''': '''View/read'''<br />
<br />
[[File:LimeSurveyCusomerOwnStatistics.jpg]]<br />
<br />
----<br />
<br />
Article was translated and used with approval from '''vierundzwanzig''' (24/7 IT-SERVICES GmbH).<br />
<br />
----<br />
<br />
----<br />
<br />
To be moved somewhere else once better defined:<br />
<br />
There are several classes of possible people who access a LimeSurvey installation. But only one set of people is actually termed a '''user''' in the code and documentation. So lets understand what these classes of people are so we can better understand the terminology of the program.<br />
<br />
{|<br />
|Class||Description<br />
|-<br />
|Installation Administrator || Those people who create login user accounts to allow others to create, edit, activate and/or view surveys and their results. Often can be given access to edit the templates, labelsets and other key features independent of any particular survey stored.<br />
|-<br />
|Survey Administrator || A person with a login account that is given some management access to a particular survey. Each survey can have its own set of users with specific rights to manipulate the survey. These rights can be as broad as to activate a survey and possibly edit its question base. They can be as minimum as simply able to review the results to date.<br />
|-<br />
|Participant || Those people who simply respond or participate in taking a survey. They may or may not have token access. They do not need a login account to the administrative interface and thus are not termed users.<br />
|-<br />
|Installer || A special class of person who has access to the MySQL (or similar) database server and possibly the command line interface of the computers operating system in order to install and configure the survey software. This person is asked to setup the initial SuperAdmin user account from which other user login accounts can be created.<br />
|-<br />
|Developer || An very special class of person who has access to the source code and can manipulate it to change the programs behavior. Generally only done with versions of the survey that are not available for live, active surveys. <br />
|}<br />
<br />
=Use one time passwords=<br />
<br />
Since version 1.81 a user can call the limesurvey login at /limesurvey/admin and pass username and a one time password which was previously written into the users table (column one_time_pw) by an external application.<br />
<br />
To enable this login method [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings#Use_one_time_passwords a setting has to be turned on] ($use_one_time_passwords = true;) in config.php.<br />
<br />
The URL has to contain the following variables:<br />
* '''user:''' The username normally used to login into Limesurvey. This username has to exist in the 'users' table of the database.<br />
* '''onepass:''' The plain text password which is then compared to the password in the 'users' table<br />
<br />
A valid URL to login using a one-time password will look like this...<br />
<br />
... for 1.81 to 1.92:<br />
<br />
<div class="simplebox">http://www.yourdomain.org/limesurvey/admin/admin.php?user=myusername&onepass;=secretpassword</div><br />
<br />
...for 2.0 or later:<br />
<br />
<div class="simplebox">http://www.yourdomain.org/limesurvey/index.php/admin/authentication/login?user=myusername&onepass;=secretpassword</div><br />
<br />
'''Things to watch out for:'''<br />
* One time passwords have to be enabled by setting $use_one_time_passwords = true; in config.php<br />
* The passed username has to exist in Limesurvey's ''users'' table<br />
* The one time password, which can be set by an external application, has to be stored as [http://de.php.net/md5 MD5 hash] in column ''one_time_pw'' of table ''users''<br />
* The passed plain text password will be hashed using md5() function and will then be compared to the stored hash in column ''one_time_pw'' of table ''users''. Both passwords have to match.<br />
* After the first login with the one time password this password is deleted from the database. The user won't be able to login with this password anymore. If you are confronted with session timeout problems [http://docs.limesurvey.org/tiki-index.php?page=Optional+settings#Survey_Behavior raise the setting for $sessionlifetime] (default is 3600 seconds).</div>Adminhttps://www.limesurvey.org/manual/index.php?title=RemoteControl_2_API&diff=2938RemoteControl 2 API2012-11-15T14:58:32Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Introduction=<br />
<br />
LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or later. The old [RemoteControl] will not be available any longer in version 2.<br />
<br />
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.<br />
<br />
The following features are planned:<br />
* start a predefined survey (change titles and things)<br />
* add predefined groups or questions<br />
* activate the survey, restrict it to start and endtime<br />
* make it closed,<br />
* add participant data/tokens when you need them<br />
* return the unused tokens to the main application<br />
* get a fieldmap for a survey,<br />
* invite or remind the participants of your survey<br />
<br />
...and much more<br />
<br />
==Requirements==<br />
* libXML installed<br />
<br />
=Setup=<br />
<br />
== How to configure LSRC2==<br />
<br />
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 'Services' and select one of the two RPC services (XML-RPC or JSON-RPC) service.<br />
<br />
== Security==<br />
<br />
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.<br />
<br />
=How to use LSRC2=<br />
<br />
The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol<br />
<br />
LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.<br />
<br />
LSRC2 offers the following functions:<br />
<br />
==get_session_key==<br />
<br />
Using this function you can create a new XML-RPC session key. This is mandatory for all following LSRC2 function calls.<br />
<br />
Parameters: username (string), password (string)<br />
<br />
Returns:<br />
*On success: A session key (string)<br />
*On failure: Error Code 1<br />
<br />
==release_session_key==<br />
<br />
Using this function you can close a previously opened XML-RPC/JSON-RPC session.<br />
<br />
Parameters: session key (string)<br />
<br />
Returns:<br />
*Always: 'OK' (string)<br />
<br />
==get_site_settings==<br />
<br />
Function to provide with site settings only to administrators<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) The session key<br />
<br />
sSetttingName (string) - Name of the setting to get<br />
<br />
Returns:<br />
*On success: (string) Setting<br />
*On failure: (string) Error message<br />
<br />
==add_survey==<br />
<br />
RPC Routine to add an empty survey with minimum details<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (int), The wish id of the Survey to add<br />
<br />
sSurveyTitle (string), Title of the new Survey<br />
<br />
sSurveyLanguage (string), Default language of the Survey<br />
<br />
sformat (string), Question appearance format (S|G|A)<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Faulty parameters<br />
**Creation Failed<br />
<br />
==delete_survey==<br />
<br />
RPC Routine to Delete a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string), Auth credentials<br />
<br />
iSurveyID (int), The Survey to delete<br />
<br />
Returns:<br />
*On success: Status =>OK (array)<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
<br />
==import_survey==<br />
<br />
RPC Routine to import a survey from lss,csv,xls or survey zip archive.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sImportData (string) String containing the BASE 64 encoded data of a lss,csv,xls or survey zip archive<br />
<br />
sImportDataType (string), The format of the import file (lss,csv,xls or zip)<br />
<br />
sNewSurveyName (string), The optional new name of the survey (base language)<br />
<br />
DestSurveyID (int), This is the new ID of the survey - if already used a random one will be taken instead<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Import error<br />
<br />
==get_survey_properties==<br />
<br />
RPC Routine to get properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An array with the properties to return<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
{|<br />
| || || || || ||<br />
|-<br />
| sid|| savetimings|| allowprev|| tokenanswerspersistence|| showgroupinfo|| showwelcome<br />
|-<br />
| owner_id|| template|| printanswers|| assessments|| shownoanswer || showprogress<br />
|-<br />
| admin|| language|| ipaddr|| usecaptcha|| showqnumcode|| allowjumps<br />
|-<br />
| active|| additional_languages || refurl|| usetokens|| bouncetime|| navigationdelay<br />
|-<br />
| expires|| datestamp|| datecreated|| bounce_email|| bounceprocessing|| nokeyboard<br />
|-<br />
| startdate|| usecookie|| publicstatistics|| attributedescriptions|| bounceaccounttype|| alloweditaftercompletion<br />
|-<br />
| adminemail|| allowregister|| publicgraphs|| emailresponseto|| bounceaccounthost|| googleanalyticsstyle<br />
|-<br />
| anonymized|| allowsave|| listpublic|| emailnotificationto|| bounceaccountpass|| googleanalyticsapikey<br />
|-<br />
| faxto|| autonumber_start|| htmlemail|| tokenlength|| bounceaccountencryption||<br />
|-<br />
|format|| autoredirect|| sendconfirmation|| showxquestions|| bounceaccountuser|| <br />
|}<br />
<br />
==set_survey_properties==<br />
<br />
RPC Routine to set properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An assosiative array with the name-value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) The result of the change for each property<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
Properties available for changing are all those defined in get_survey_properties with the following exceptions<br />
<br />
{|<br />
|properties not allowed to be modified|| Properties not allowed to be modified when survey active<br />
|-<br />
|sid||anonymized<br />
|-<br />
|language||datestamp<br />
|-<br />
|additional_languages||savetimings<br />
|-<br />
|active||ipaddr<br />
|-<br />
|||refurl<br />
|-<br />
|<br />
|}<br />
<br />
==list_surveys==<br />
<br />
RPC Routine to list the ids and info of surveys belonging to a user.<br />
<br />
* If user is admin he can get surveys of every user (parameter sUser) or all surveys (sUser=null)<br />
<br />
* Else only the syrveys belonging to the user requesting will be shown.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sUser (string) - The users surveys to list<br />
<br />
Returns:<br />
*On success: (array) Survey's properties<br />
*On failure: (array) Failure status<br />
**Invalid user<br />
**Invalid session key<br />
**No permission<br />
**No surveys found<br />
<br />
Survey's properties:<br />
<br />
{|<br />
|property||type<br />
|-<br />
|sid||integer<br />
|-<br />
|surveyls_title||string<br />
|-<br />
|startdate||date<br />
|-<br />
|expires||date<br />
|-<br />
|active||y/n<br />
|-<br />
|<br />
|}<br />
<br />
==activate_survey==<br />
<br />
RPC Routine that launches a newly created survey (sets active -available for users)<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
Returns<br />
*On success: (array) The result of the activation<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Activation Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==export_statistics==<br />
<br />
RPC routine to export statistics of a survey to a user.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
docType (string) - Type of document to generate<br />
<br />
sLanguage (string) Optional language of the survey to use (if not set, default language is selected)<br />
<br />
graph (string) - Optional parameter to enable graphs (0|1)<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid session key<br />
**No permission<br />
<br />
==get_summary==<br />
<br />
RPC routine to get survey summary, regarding token usage and survey participation.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
sStatname (string) - The statistic to return<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**No available data<br />
**No such property<br />
**Invalid session key<br />
**No permission<br />
<br />
Available statistics:<br />
<br />
{|<br />
|Survey stats||Token stats<br />
|-<br />
|completed_responses||token_count<br />
|-<br />
|incomplete_responses||token_invalid<br />
|-<br />
|full_responses||tokens_sent<br />
|-<br />
|||token_opted_out<br />
|-<br />
|||token_completed<br />
|-<br />
|<br />
|}<br />
<br />
==add_language==<br />
<br />
RPC Routine to add a language to an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) - The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the new language to be added. Note: If the language is already in that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==delete_survey_language==<br />
<br />
RPC Routine to delete a language of an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the language to be removed. Note: If the language is not part of that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Cannot remove base language<br />
**Error<br />
**No permission<br />
**Invalid session key<br />
<br />
==get_language_properties==<br />
<br />
RPC Routine to get survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleSettings (array) - An array with the properties to return<br />
<br />
slang (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available parameters:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
| surveyls_survey_id || surveyls_url || surveyls_email_register_subj || email_admin_notification_subj<br />
|-<br />
| surveyls_language || surveyls_urldescription || surveyls_email_register || email_admin_notification<br />
|-<br />
| surveyls_title || surveyls_email_invite_subj || surveyls_email_confirm_subj || email_admin_responses_subj<br />
|-<br />
| surveyls_description || surveyls_email_invite || surveyls_email_confirm || email_admin_responses<br />
|-<br />
| surveyls_welcometext || surveyls_email_remind_subj || surveyls_dateformat || surveyls_numberformat<br />
|-<br />
|surveyls_endtext || surveyls_email_remind || surveyls_attributecaptions || <br />
|}<br />
<br />
==set_language_properties==<br />
<br />
RPC Routine to set survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleData (array) - An assosiative array with the key-value pairs of properties to set. Invalid fieldnames or fields that may not be modified are ignored.<br />
<br />
sLanguage (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) Result for each parameter set<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Allowed Parameters:<br />
<br />
All those defined in get-language_properties except:<br />
*surveyls_language<br />
*surveyls_survey_id<br />
<br />
==add_group==<br />
<br />
RPC Routine to add an empty group with minimum details.<br />
<br />
* Used as a placeholder for importing questions.<br />
<br />
* Returns the groupid of the created group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the surveythat the group will be added<br />
<br />
sGroupTitle (string) - Name of the new group<br />
<br />
sGroupDescription (string) - Optional description of the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Creation Failed<br />
<br />
==delete_group==<br />
<br />
RPC Routine to delete a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey that the group belongs<br />
<br />
sGroupID (int) - Id of the group to delete<br />
<br />
Returns:<br />
*On success: (int) The ID of the deleted group<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid Group ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Group deletion failed<br />
<br />
==import_group==<br />
<br />
RPC Routine to import a group - imports lsg,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey that the group will belong<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sGroupDescription (string) -The format of the importfile in the stream (lsg|csv)<br />
<br />
sNewGroupName (string) - Optional new name for the group<br />
<br />
sNewGroupDescription (string) - Optional new description for the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid extension<br />
**Error: Invalid LimeSurvey group structure XML<br />
**Invalid session key<br />
**No permission<br />
**Import Error<br />
<br />
==get_group_properties==<br />
<br />
RPC Routine to return properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to get properties of<br />
<br />
aGroupSettings (array) - Array containing the properties to request.<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|gid||description<br />
|-<br />
|sid||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==set_group_properties==<br />
<br />
RPC Routine to set properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to set properties to<br />
<br />
aGroupData (array) - Assosiative Array containing key-value pairs of the properties to set.<br />
<br />
Returns:<br />
*On success: (array) The result of each set action<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Group with dependencies - Order cannot be changed<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|||description<br />
|-<br />
|||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_groups==<br />
<br />
RPC Routine to return the ids and info of groups belonging to survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey to get groups of<br />
<br />
Returns:<br />
*On success: (array) The list of the groups<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**No groups found<br />
**Invalid session key<br />
**No permission<br />
<br />
==delete_question==<br />
<br />
RPC Routine to delete a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to delete<br />
<br />
Returns:<br />
*On success: (int)id of the deleted Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
** Invalid question ID<br />
**Survey is active and not editable<br />
**Cannot delete Question. Others rely on this question<br />
**Error<br />
<br />
==import_question==<br />
<br />
RPC Routine to import a question - imports lsq,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey that the new questions belongs<br />
<br />
iGroupID (int) - Id of the group that the new questions belongs<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sImportDataType (string) - Format of the input stream (lsq,csv)<br />
<br />
sMandatory (string) - Optional Mandatory question option (default to No)<br />
<br />
sNewQuestionTitle (string) - Optional new title for the question<br />
<br />
sNewqQuestion (string) - An optional new question<br />
<br />
sNewQuestionHelp (string) - An optional new question help text<br />
<br />
Returns:<br />
*On success: (int) Id of the new Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Invalid group ID<br />
**Survey is active and not editable<br />
**Invalid extension<br />
**Invalid LimeSurvey question structure XML<br />
<br />
==get_question_properties==<br />
<br />
RPC Routine to return properties of a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to get properties of<br />
<br />
aQuestionSettings (array) The properties to get<br />
<br />
sLanguage (string) Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
|gid||type||help||language<br />
|-<br />
|parent_qid||title||other||scale_id<br />
|-<br />
|sid||question||mandatory||same_default<br />
|-<br />
|gid||preg||question_order||relevance<br />
|-<br />
|subquestions||attributes||attributes_lang||answeroptions<br />
|-<br />
|<br />
|}<br />
<br />
==set_question_properties==<br />
<br />
RPC Routine to set question properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iQuestionID (int) - Id of the question to get properties of<br />
<br />
aQuestionData (array) - An array with the particular fieldnames as keys and their values to set on that particular question<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The resilt of the set of each property<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Questions with dependencies - Order cannot be changed<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|help|| ||<br />
|-<br />
|title||other||scale_id<br />
|-<br />
|question||mandatory||same_default<br />
|-<br />
|preg||question_order||relevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_questions==<br />
<br />
RPC Routine to return the ids and info of questions of a survey/group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
iGroupID (int) - Id of the group to get questions of<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The list of the questions<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Invalid survey ID<br />
**Missmatch in surveyid and groupid<br />
**No questions found<br />
<br />
==activate_tokens==<br />
<br />
Activate tokens<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
surveyid (string) The survey ID<br />
<br />
additional_attributes (array of integers) Any additional attribute fields to create. Just give the attribute IDs<br />
<br />
Returns:<br />
*On success: (array) status OK<br />
*On failure: (array) Any other status<br />
<br />
==add_participants==<br />
<br />
Using this function you can add new entries to your token table. You can also set if for these new entries a token key is automatically create<br />
<br />
Parameters:<br />
*session key (string) - The session key<br />
*survey ID (string) - The survey id<br />
*participant data (array) - 2-dimensional array/structure containing your participants data<br />
*createTokenKey (boolean) - Set this to true if you want a token key create automatically for each entry - if your participant data included a [token] field it will be overwritten<br />
<br />
Returns:<br />
*On success: participant data (struct) - structure containing your participants data plus the token ID and (if applicable) the new token<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
<br />
==delete_participants==<br />
<br />
RPC Routine to delete multiple participants of a Survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
aTokenIDs (array) - IId of the tokens/participants to delete<br />
<br />
Returns:<br />
*On success: (array) Array of deletion status for each participant<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
<br />
==get_participant_properties==<br />
<br />
RPC Routine to return settings of a token/participant of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to get token properties<br />
<br />
iTokenID (int) - Id of the participant to check<br />
<br />
aTokenProperties (array) - The properties to get<br />
<br />
Returns:<br />
*On success: (array) Array of requested values<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|tid|| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==set_participant_properties==<br />
<br />
RPC Routine to set properties of a survey participant/token<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to set token properties<br />
<br />
iTokenID (int) - Id of the participant to alter<br />
<br />
aTokenData (array) - Key - value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) Array of results of changing properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
||| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==list_participants==<br />
<br />
RPC Routine to return the ids and info of token/participants of a survey.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to list participants<br />
<br />
iStart (int) - Start id of the token list<br />
<br />
iLimit (int) - Number of participants to return<br />
<br />
bUnused (bool) - If you want unused tokensm, set true<br />
<br />
Returns:<br />
*On success: (array) Array of Participants info<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No Tokens found<br />
<br />
==activate_tokens==<br />
<br />
RPC routine to to initialise the survey's collection of tokens where new participant tokens may be later added<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to list participants<br />
<br />
aAttributeFields (array) - An array of integer describing any additional attribute fields<br />
<br />
Returns:<br />
*On success: (array) Status OK<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Token table could not be created<br />
<br />
==invite_participants==<br />
<br />
RPC Routine to invite participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==remind_participants==<br />
<br />
RPC Routine to send reminder for participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
iMinDaysBetween (int) - Optional parameter days from last reminder<br />
<br />
iMaxReminders (int) - Optional parameter Maximum reminders count<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==add_response==<br />
<br />
Using this function you can add new responses to your survey response table.<br />
<br />
Parameters:<br />
*sSessionKey (string) - The session key<br />
*iSurveyID (integer) - The survey id<br />
*aResponseData (array) - array/structure containing your response data<br />
<br />
Returns:<br />
*On success: response_id (integer) - Returns the id of the inserted survey response<br />
*On failure: (array) with error description<br />
<br />
==export_responses==<br />
<br />
Export response data to pdf,csv,xls,doc<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
SurveyID (int) - Id of the Survey<br />
<br />
DocumentType (string) - pdf,csv,xls,doc<br />
<br />
sLanguageCode (string) - Optional The language to be used - if not given then the base language will be used<br />
<br />
CompletionStatus (string) - Optional 'complete','incomplete' or 'all' selection of responses - defaults to complete<br />
<br />
HeadingType (string) - 'code','full' or 'abbreviated'. type of question heading. Optional defaults to 'code'<br />
<br />
ResponseType (string) - 'short' or 'long' response type.Optional defaults to 'short'<br />
<br />
FromResponse (int) - Optional start number of response<br />
<br />
ToResponse (int) - Optional end number of responses<br />
<br />
Return:<br />
<br />
On success: Requested file as base 64-encoded string.<br />
<br />
On failure: Array with error information<br />
<br />
Note: If you have huge response sets try only to request a certain number of records at a time otherwise the server may run out of memory.<br />
<br />
=Testing=<br />
<br />
To test you will have to activate JSON-RPC in global settings. To run a simple self-test go to<br />
<br />
http://path_to_your_limesurvey_installation/index.php/admin/remotecontrol/test . This will import the example survey, do various things with it and delete it afterwards.<br />
<br />
The test assumes that you still are using the standard user 'admin' with password 'password'.<br />
<br />
The client function for this test can be found in /application/controller/admin/remotecontrol.php and the particular function is called test().<br />
<br />
=PHP Example=<br />
<br />
To include JSON-RPC in your application, you can write an application based on the tiny jsonRPCClient from [http://jsonrpcphp.org/ | jsonrpcphp.org]<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<?php<br />
<br />
require_once 'jsonRPCClient.php';<br />
<br />
define( 'LS_BASEURL', 'http://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL<br />
<br />
define( 'LS_USER', 'rpcuser' );<br />
<br />
define( 'LS_PASSWORD', 'mypassword' );<br />
<br />
// the survey to process<br />
<br />
$survey_id=374699;<br />
<br />
// instanciate a new client<br />
<br />
$myJSONRPCClient = new jsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );<br />
<br />
// receive session key<br />
<br />
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );<br />
<br />
// receive all ids and info of groups belonging to a given survey<br />
<br />
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );<br />
<br />
print_r($groups, null );<br />
<br />
// release the session key<br />
<br />
$myJSONRPCClient->release_session_key( $sessionKey );<br />
<br />
?><br />
<br />
</syntaxhighlight><br />
<br />
=Changes=<br />
<br />
2.0a Only three functions are supported right now: getSessionKey, releaseSessionKey, deleteSurvey<br />
<br />
2.0b Added function add_participants<br />
<br />
2.0RC5 Added import_survey, activate_survey, activate_tokens<br />
<br />
2.0 (build 121030) Added subquestions, attributes, attributes_lang and answeroptions properties for get_question_properties</div>Adminhttps://www.limesurvey.org/manual/index.php?title=RemoteControl_2_API&diff=2940RemoteControl 2 API2012-11-15T14:24:26Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Introduction=<br />
<br />
LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or later. The old [RemoteControl] will not be available any longer in version 2.<br />
<br />
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.<br />
<br />
The following features are planned:<br />
* start a predefined survey (change titles and things)<br />
* add predefined groups or questions<br />
* activate the survey, restrict it to start and endtime<br />
* make it closed,<br />
* add participant data/tokens when you need them<br />
* return the unused tokens to the main application<br />
* get a fieldmap for a survey,<br />
* invite or remind the participants of your survey<br />
<br />
...and much more<br />
<br />
==Requirements==<br />
* libXML installed<br />
<br />
=Setup=<br />
<br />
== How to configure LSRC2==<br />
<br />
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 'Services' and select one of the two RPC services (XML-RPC or JSON-RPC) service.<br />
<br />
== Security==<br />
<br />
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.<br />
<br />
=How to use LSRC2=<br />
<br />
The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol<br />
<br />
LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.<br />
<br />
LSRC2 offers the following functions:<br />
<br />
==get_session_key==<br />
<br />
Using this function you can create a new XML-RPC session key. This is mandatory for all following LSRC2 function calls.<br />
<br />
Parameters: username (string), password (string)<br />
<br />
Returns:<br />
*On success: A session key (string)<br />
*On failure: Error Code 1<br />
<br />
==release_session_key==<br />
<br />
Using this function you can close a previously opened XML-RPC/JSON-RPC session.<br />
<br />
Parameters: session key (string)<br />
<br />
Returns:<br />
*Always: 'OK' (string)<br />
<br />
==get_site_settings==<br />
<br />
Function to provide with site settings only to administrators<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) The session key<br />
<br />
sSetttingName (string) - Name of the setting to get<br />
<br />
Returns:<br />
*On success: (string) Setting<br />
*On failure: (string) Error message<br />
<br />
==add_survey==<br />
<br />
RPC Routine to add an empty survey with minimum details<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (int), The wish id of the Survey to add<br />
<br />
sSurveyTitle (string), Title of the new Survey<br />
<br />
sSurveyLanguage (string), Default language of the Survey<br />
<br />
sformat (string), Question appearance format (S|G|A)<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Faulty parameters<br />
**Creation Failed<br />
<br />
==delete_survey==<br />
<br />
RPC Routine to Delete a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string), Auth credentials<br />
<br />
iSurveyID (int), The Survey to delete<br />
<br />
Returns:<br />
*On success: Status =>OK (array)<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
<br />
==import_survey==<br />
<br />
RPC Routine to import a survey from lss,csv,xls or survey zip archive.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sImportData (string) String containing the BASE 64 encoded data of a lss,csv,xls or survey zip archive<br />
<br />
sImportDataType (string), The format of the import file (lss,csv,xls or zip)<br />
<br />
sNewSurveyName (string), The optional new name of the survey (base language)<br />
<br />
DestSurveyID (int), This is the new ID of the survey - if already used a random one will be taken instead<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Import error<br />
<br />
==get_survey_properties==<br />
<br />
RPC Routine to get properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An array with the properties to return<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
{|<br />
| || || || || ||<br />
|-<br />
| sid|| savetimings|| allowprev|| tokenanswerspersistence|| showgroupinfo|| showwelcome<br />
|-<br />
| owner_id|| template|| printanswers|| assessments|| shownoanswer || showprogress<br />
|-<br />
| admin|| language|| ipaddr|| usecaptcha|| showqnumcode|| allowjumps<br />
|-<br />
| active|| additional_languages || refurl|| usetokens|| bouncetime|| navigationdelay<br />
|-<br />
| expires|| datestamp|| datecreated|| bounce_email|| bounceprocessing|| nokeyboard<br />
|-<br />
| startdate|| usecookie|| publicstatistics|| attributedescriptions|| bounceaccounttype|| alloweditaftercompletion<br />
|-<br />
| adminemail|| allowregister|| publicgraphs|| emailresponseto|| bounceaccounthost|| googleanalyticsstyle<br />
|-<br />
| anonymized|| allowsave|| listpublic|| emailnotificationto|| bounceaccountpass|| googleanalyticsapikey<br />
|-<br />
| faxto|| autonumber_start|| htmlemail|| tokenlength|| bounceaccountencryption||<br />
|-<br />
|format|| autoredirect|| sendconfirmation|| showxquestions|| bounceaccountuser|| <br />
|}<br />
<br />
==set_survey_properties==<br />
<br />
RPC Routine to set properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An assosiative array with the name-value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) The result of the change for each property<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
Properties available for changing are all those defined in get_survey_properties with the following exceptions<br />
<br />
{|<br />
|properties not allowed to be modified|| Properties not allowed to be modified when survey active<br />
|-<br />
|sid||anonymized<br />
|-<br />
|language||datestamp<br />
|-<br />
|additional_languages||savetimings<br />
|-<br />
|active||ipaddr<br />
|-<br />
|||refurl<br />
|-<br />
|<br />
|}<br />
<br />
==list_surveys==<br />
<br />
RPC Routine to list the ids and info of surveys belonging to a user.<br />
<br />
* If user is admin he can get surveys of every user (parameter sUser) or all surveys (sUser=null)<br />
<br />
* Else only the syrveys belonging to the user requesting will be shown.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sUser (string) - The users surveys to list<br />
<br />
Returns:<br />
*On success: (array) Survey's properties<br />
*On failure: (array) Failure status<br />
**Invalid user<br />
**Invalid session key<br />
**No permission<br />
**No surveys found<br />
<br />
Survey's properties:<br />
<br />
{|<br />
|property||type<br />
|-<br />
|sid||integer<br />
|-<br />
|surveyls_title||string<br />
|-<br />
|startdate||date<br />
|-<br />
|expires||date<br />
|-<br />
|active||y/n<br />
|-<br />
|<br />
|}<br />
<br />
==activate_survey==<br />
<br />
RPC Routine that launches a newly created survey (sets active -available for users)<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
Returns<br />
*On success: (array) The result of the activation<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Activation Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==export_statistics==<br />
<br />
RPC routine to export statistics of a survey to a user.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
docType (string) - Type of document to generate<br />
<br />
sLanguage (string) Optional language of the survey to use (if not set, default language is selected)<br />
<br />
graph (string) - Optional parameter to enable graphs (0|1)<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid session key<br />
**No permission<br />
<br />
==get_summary==<br />
<br />
RPC routine to get survey summary, regarding token usage and survey participation.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
sStatname (string) - The statistic to return<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**No available data<br />
**No such property<br />
**Invalid session key<br />
**No permission<br />
<br />
Available statistics:<br />
<br />
{|<br />
|Survey stats||Token stats<br />
|-<br />
|completed_responses||token_count<br />
|-<br />
|incomplete_responses||token_invalid<br />
|-<br />
|full_responses||tokens_sent<br />
|-<br />
|||token_opted_out<br />
|-<br />
|||token_completed<br />
|-<br />
|<br />
|}<br />
<br />
==add_language==<br />
<br />
RPC Routine to add a language to an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) - The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the new language to be added. Note: If the language is already in that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==delete_survey_language==<br />
<br />
RPC Routine to delete a language of an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the language to be removed. Note: If the language is not part of that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Cannot remove base language<br />
**Error<br />
**No permission<br />
**Invalid session key<br />
<br />
==get_language_properties==<br />
<br />
RPC Routine to get survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleSettings (array) - An array with the properties to return<br />
<br />
slang (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available parameters:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
| surveyls_survey_id || surveyls_url || surveyls_email_register_subj || email_admin_notification_subj<br />
|-<br />
| surveyls_language || surveyls_urldescription || surveyls_email_register || email_admin_notification<br />
|-<br />
| surveyls_title || surveyls_email_invite_subj || surveyls_email_confirm_subj || email_admin_responses_subj<br />
|-<br />
| surveyls_description || surveyls_email_invite || surveyls_email_confirm || email_admin_responses<br />
|-<br />
| surveyls_welcometext || surveyls_email_remind_subj || surveyls_dateformat || surveyls_numberformat<br />
|-<br />
|surveyls_endtext || surveyls_email_remind || surveyls_attributecaptions || <br />
|}<br />
<br />
==set_language_properties==<br />
<br />
RPC Routine to set survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleData (array) - An assosiative array with the key-value pairs of properties to set. Invalid fieldnames or fields that may not be modified are ignored.<br />
<br />
sLanguage (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) Result for each parameter set<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Allowed Parameters:<br />
<br />
All those defined in get-language_properties except:<br />
*surveyls_language<br />
*surveyls_survey_id<br />
<br />
==add_group==<br />
<br />
RPC Routine to add an empty group with minimum details.<br />
<br />
* Used as a placeholder for importing questions.<br />
<br />
* Returns the groupid of the created group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the surveythat the group will be added<br />
<br />
sGroupTitle (string) - Name of the new group<br />
<br />
sGroupDescription (string) - Optional description of the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Creation Failed<br />
<br />
==delete_group==<br />
<br />
RPC Routine to delete a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey that the group belongs<br />
<br />
sGroupID (int) - Id of the group to delete<br />
<br />
Returns:<br />
*On success: (int) The ID of the deleted group<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid Group ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Group deletion failed<br />
<br />
==import_group==<br />
<br />
RPC Routine to import a group - imports lsg,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey that the group will belong<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sGroupDescription (string) -The format of the importfile in the stream (lsg|csv)<br />
<br />
sNewGroupName (string) - Optional new name for the group<br />
<br />
sNewGroupDescription (string) - Optional new description for the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid extension<br />
**Error: Invalid LimeSurvey group structure XML<br />
**Invalid session key<br />
**No permission<br />
**Import Error<br />
<br />
==get_group_properties==<br />
<br />
RPC Routine to return properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to get properties of<br />
<br />
aGroupSettings (array) - Array containing the properties to request.<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|gid||description<br />
|-<br />
|sid||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==set_group_properties==<br />
<br />
RPC Routine to set properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to set properties to<br />
<br />
aGroupData (array) - Assosiative Array containing key-value pairs of the properties to set.<br />
<br />
Returns:<br />
*On success: (array) The result of each set action<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Group with dependencies - Order cannot be changed<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|||description<br />
|-<br />
|||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_groups==<br />
<br />
RPC Routine to return the ids and info of groups belonging to survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey to get groups of<br />
<br />
Returns:<br />
*On success: (array) The list of the groups<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**No groups found<br />
**Invalid session key<br />
**No permission<br />
<br />
==delete_question==<br />
<br />
RPC Routine to delete a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to delete<br />
<br />
Returns:<br />
*On success: (int)id of the deleted Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
** Invalid question ID<br />
**Survey is active and not editable<br />
**Cannot delete Question. Others rely on this question<br />
**Error<br />
<br />
==import_question==<br />
<br />
RPC Routine to import a question - imports lsq,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey that the new questions belongs<br />
<br />
iGroupID (int) - Id of the group that the new questions belongs<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sImportDataType (string) - Format of the input stream (lsq,csv)<br />
<br />
sMandatory (string) - Optional Mandatory question option (default to No)<br />
<br />
sNewQuestionTitle (string) - Optional new title for the question<br />
<br />
sNewqQuestion (string) - An optional new question<br />
<br />
sNewQuestionHelp (string) - An optional new question help text<br />
<br />
Returns:<br />
*On success: (int) Id of the new Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Invalid group ID<br />
**Survey is active and not editable<br />
**Invalid extension<br />
**Invalid LimeSurvey question structure XML<br />
<br />
==get_question_properties==<br />
<br />
RPC Routine to return properties of a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to get properties of<br />
<br />
aQuestionSettings (array) The properties to get<br />
<br />
sLanguage (string) Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
|gid||type||help||language<br />
|-<br />
|parent_qid||title||other||scale_id<br />
|-<br />
|sid||question||mandatory||same_default<br />
|-<br />
|gid||preg||question_order||relevance<br />
|-<br />
|subquestions||attributes||attributes_lang||answeroptions<br />
|-<br />
|<br />
|}<br />
<br />
==set_question_properties==<br />
<br />
RPC Routine to set question properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iQuestionID (int) - Id of the question to get properties of<br />
<br />
aQuestionData (array) - An array with the particular fieldnames as keys and their values to set on that particular question<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The resilt of the set of each property<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Questions with dependencies - Order cannot be changed<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|help|| ||<br />
|-<br />
|title||other||scale_id<br />
|-<br />
|question||mandatory||same_default<br />
|-<br />
|preg||question_order||relevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_questions==<br />
<br />
RPC Routine to return the ids and info of questions of a survey/group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
iGroupID (int) - Id of the group to get questions of<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The list of the questions<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Invalid survey ID<br />
**Missmatch in surveyid and groupid<br />
**No questions found<br />
<br />
==activate_tokens==<br />
<br />
Activate tokens<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
surveyid (string) The survey ID<br />
<br />
additional_attributes (array of integers) Any additional attribute fields to create. Just give the attribute IDs<br />
<br />
Returns:<br />
*On success: (array) status OK<br />
*On failure: (array) Any other status<br />
<br />
==add_participants==<br />
<br />
Using this function you can add new entries to your token table. You can also set if for these new entries a token key is automatically create<br />
<br />
Parameters:<br />
*session key (string) - The session key<br />
*survey ID (string) - The survey id<br />
*participant data (array) - 2-dimensional array/structure containing your participants data<br />
*createTokenKey (boolean) - Set this to true if you want a token key create automatically for each entry - if your participant data included a [token] field it will be overwritten<br />
<br />
Returns:<br />
*On success: participant data (struct) - structure containing your participants data plus the token ID and (if applicable) the new token<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
<br />
==delete_participants==<br />
<br />
RPC Routine to delete multiple participants of a Survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
aTokenIDs (array) - IId of the tokens/participants to delete<br />
<br />
Returns:<br />
*On success: (array) Array of deletion status for each participant<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
<br />
==get_participant_properties==<br />
<br />
RPC Routine to return settings of a token/participant of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to get token properties<br />
<br />
iTokenID (int) - Id of the participant to check<br />
<br />
aTokenProperties (array) - The properties to get<br />
<br />
Returns:<br />
*On success: (array) Array of requested values<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|tid|| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==set_participant_properties==<br />
<br />
RPC Routine to set properties of a survey participant/token<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to set token properties<br />
<br />
iTokenID (int) - Id of the participant to alter<br />
<br />
aTokenData (array) - Key - value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) Array of results of changing properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
||| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==list_participants==<br />
<br />
RPC Routine to return the ids and info of token/participants of a survey.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to list participants<br />
<br />
iStart (int) - Start id of the token list<br />
<br />
iLimit (int) - Number of participants to return<br />
<br />
bUnused (bool) - If you want unused tokensm, set true<br />
<br />
Returns:<br />
*On success: (array) Array of Participants info<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No Tokens found<br />
<br />
==activate_tokens==<br />
<br />
RPC routine to to initialise the survey's collection of tokens where new participant tokens may be later added<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to list participants<br />
<br />
aAttributeFields (array) - An array of integer describing any additional attribute fields<br />
<br />
Returns:<br />
*On success: (array) Status OK<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Token table could not be created<br />
<br />
==invite_participants==<br />
<br />
RPC Routine to invite participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==remind_participants==<br />
<br />
RPC Routine to send reminder for participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
iMinDaysBetween (int) - Optional parameter days from last reminder<br />
<br />
iMaxReminders (int) - Optional parameter Maximum reminders count<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==add_response==<br />
<br />
Using this function you can add new responses to your survey response table.<br />
<br />
Parameters:<br />
*sSessionKey (string) - The session key<br />
*iSurveyID (integer) - The survey id<br />
*aResponseData (array) - array/structure containing your response data<br />
<br />
Returns:<br />
*On success: response_id (integer) - Returns the id of the inserted survey response<br />
*On failure: (array) with error description<br />
<br />
==export_responses==<br />
<br />
Export response data to pdf,csv,xls,doc<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
SurveyID (int) - Id of the Survey<br />
<br />
DocumentType (string) - pdf,csv,xls,doc<br />
<br />
sLanguageCode (string) - Optional The language to be used - if not given then the base language will be used<br />
<br />
CompletionStatus (string) - Optional 'complete','incomplete' or 'all' selection of responses - defaults to complete<br />
<br />
HeadingType (string) - 'code','full' or 'abbreviated'. type of question heading. Optional defaults to 'code'<br />
<br />
ResponseType (string) - 'short' or 'long' response type.Optional defaults to 'short'<br />
<br />
FromResponseID (int) - Optional start number of response<br />
<br />
ToResponseID (int) - Optional end number of responses<br />
<br />
Return:<br />
<br />
On success: Requested file as base 64-encoded string.<br />
<br />
On failure: Array with error information<br />
<br />
Note: If you have huge response sets try only to request a certain number of records at a time otherwise the server may run out of memory.<br />
<br />
=Testing=<br />
<br />
To test you will have to activate JSON-RPC in global settings. To run a simple self-test go to<br />
<br />
http://path_to_your_limesurvey_installation/index.php/admin/remotecontrol/test . This will import the example survey, do various things with it and delete it afterwards.<br />
<br />
The test assumes that you still are using the standard user 'admin' with password 'password'.<br />
<br />
The client function for this test can be found in /application/controller/admin/remotecontrol.php and the particular function is called test().<br />
<br />
=PHP Example=<br />
<br />
To include JSON-RPC in your application, you can write an application based on the tiny jsonRPCClient from [http://jsonrpcphp.org/ | jsonrpcphp.org]<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<?php<br />
<br />
require_once 'jsonRPCClient.php';<br />
<br />
define( 'LS_BASEURL', 'http://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL<br />
<br />
define( 'LS_USER', 'rpcuser' );<br />
<br />
define( 'LS_PASSWORD', 'mypassword' );<br />
<br />
// the survey to process<br />
<br />
$survey_id=374699;<br />
<br />
// instanciate a new client<br />
<br />
$myJSONRPCClient = new jsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );<br />
<br />
// receive session key<br />
<br />
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );<br />
<br />
// receive all ids and info of groups belonging to a given survey<br />
<br />
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );<br />
<br />
print_r($groups, null );<br />
<br />
// release the session key<br />
<br />
$myJSONRPCClient->release_session_key( $sessionKey );<br />
<br />
?><br />
<br />
</syntaxhighlight><br />
<br />
=Changes=<br />
<br />
2.0a Only three functions are supported right now: getSessionKey, releaseSessionKey, deleteSurvey<br />
<br />
2.0b Added function add_participants<br />
<br />
2.0RC5 Added import_survey, activate_survey, activate_tokens<br />
<br />
2.0 (build 121030) Added subquestions, attributes, attributes_lang and answeroptions properties for get_question_properties</div>Adminhttps://www.limesurvey.org/manual/index.php?title=URL_fields&diff=3589URL fields2012-11-14T18:25:34Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
==General==<br />
<br />
At the end of a survey, or when a quota causes a survey to terminate, there is the option of setting a URL. This URL is presented to the participant who has finished the survey on the completed page, or you can optionally set the participant to be automatically redirected to the URL.<br />
<br />
There are a number of fields available to be used to enhance the functionality of this URL.<br />
<br />
===Basic fields===<br />
<br />
You can use {SAVEDID}, {TOKEN}, {SID} and {LANG} (since 1.71+) in this URL.<br />
* SAVEDID is the id assigned to this particular submission,<br />
* TOKEN is the token used to participate in the survey,<br />
* SID is the survey ID, and<br />
* LANG is the language code<br />
<br />
'''Example'''<br />
<br />
http://www.limesurvey.org/test.php?var1={SAVEDID}&var2;={TOKEN}&var3;={SID}&lang;={LANG} (external link)<br />
<br />
===Answer fields===<br />
<br />
You can also use {INSERTANS:SGQA} in this URL (since 1.82+).<br />
* {INSERTANS: SGQA} 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).<br />
<br />
'''Example'''<br />
<br />
"http://www.limesurvey.org/test.php?email={INSERTANS:1234X56X7}"<br />
<br />
===Expressions===<br />
<br />
You can also use any Expression Manager expression (since 1.92+).<br />
<br />
'''Example'''<br />
<br />
"http://www.limesurvey.org/test.php?gender={if(sex=='Male','M','F')}&name;={name}<br />
<br />
===Passthrough fields (LimeSurvey 2.x or later)===<br />
<br />
Starting with version 2.0 you can now define any additional parameters that should be passed to the end URl in the survey settings (Tab "Panel integration"). To use such a parameter in the end URL just insert the tag {PASSTHRU:<paramname>} where <paramname> is the name of your input parameter.<br />
<br />
Example:<br />
<br />
You defined in the Panel integration tab a parameter named 'foobar'. The survey is started with a link like<br />
<br />
http://localhost/limesurvey/index.php/survey/index/sid/12345/lang/eb?foobar=XYZ123<br />
<br />
where XYZ123 is the value you want to pass.<br />
<br />
A survey exit URL of "http://www.limesurvey.org/test.php?foobarout={PASSTHRU:foobar}" would then convert to "http://www.limesurvey.org/test.php?foobarout=XYZ123"<br />
<br />
===Passthrough fields (LimeSurvey 1.92 and older)===<br />
<br />
You can also use a 'passthrough' field name and data value in the end URL.<br />
<br />
In some instances you may want to pass a value to the survey at initialization, and then have that value passed through to an external script at the end (for example a marketing firms subsid).<br />
<br />
'''Example'''<br />
<br />
In this case you'd start the survey with the query url "index.php?sid=12345&passthru;=subsid&subsid;=9999".<br />
<br />
In your URL you would use {PASSTHRULABEL} and {PASSTHRUVALUE} to reuse these values at the end of the survey.<br />
<br />
A URL of "http://www.limesurvey.org/test.php?{PASSTHRULABEL}={PASSTHRUVALUE}" would then convert to "http://www.limesurvey.org/test.php?subsid=9999"<br />
<br />
===Places to use URL fields===<br />
<br />
URL fields can be used in the general survey exit URL (see [[Creating a new survey]] ), and in the URL setting for each individual quota (see [[Quotas]] ).</div>Adminhttps://www.limesurvey.org/manual/index.php?title=URL_fields&diff=3590URL fields2012-11-14T18:25:07Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
==General==<br />
<br />
At the end of a survey, or when a quota causes a survey to terminate, there is the option of setting a URL. This URL is presented to the participant who has finished the survey on the completed page, or you can optionally set the participant to be automatically redirected to the URL.<br />
<br />
There are a number of fields available to be used to enhance the functionality of this URL.<br />
<br />
===Basic fields===<br />
<br />
You can use {SAVEDID}, {TOKEN}, {SID} and {LANG} (since 1.71+) in this URL.<br />
* SAVEDID is the id assigned to this particular submission,<br />
* TOKEN is the token used to participate in the survey,<br />
* SID is the survey ID, and<br />
* LANG is the language code<br />
<br />
'''Example'''<br />
<br />
http://www.limesurvey.org/test.php?var1={SAVEDID}&var2;={TOKEN}&var3;={SID}&lang;={LANG} (external link)<br />
<br />
===Answer fields===<br />
<br />
You can also use {INSERTANS:SGQA} in this URL (since 1.82+).<br />
* {INSERTANS: SGQA} 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).<br />
<br />
'''Example'''<br />
<br />
"http://www.limesurvey.org/test.php?email={INSERTANS:1234X56X7}"<br />
<br />
===Expressions===<br />
<br />
You can also use any Expression Manager expression (since 1.92+).<br />
<br />
'''Example'''<br />
<br />
"http://www.limesurvey.org/test.php?gender={if(sex=='Male','M','F')}&name;={name}<br />
<br />
===Passthrough fields (LimeSurvey 2.x or later)===<br />
<br />
Starting with version 2.0 you can now define any additional parameters that should be passed to the end URl in the survey settings (Tab "Panel integration"). To use such a paramter in the end URL just insert the tag {PASSTHRU:<paramname>} where <paramname> is the name of your input parameter.<br />
<br />
Example:<br />
<br />
You defined in the Panel integration tab a parameter named 'foobar'. The survey is started with a link like<br />
<br />
http://localhost/limesurvey/index.php/survey/index/sid/12345/lang/eb?foobar=XYZ123<br />
<br />
where XYZ123 is the value you want to pass.<br />
<br />
A survey exit URL of "http://www.limesurvey.org/test.php?foobarout={PASSTHRU:foobar}" would then convert to "http://www.limesurvey.org/test.php?foobarout=XYZ123"<br />
<br />
===Passthrough fields (LimeSurvey 1.92 and older)===<br />
<br />
You can also use a 'passthrough' field name and data value in the end URL.<br />
<br />
In some instances you may want to pass a value to the survey at initialization, and then have that value passed through to an external script at the end (for example a marketing firms subsid).<br />
<br />
'''Example'''<br />
<br />
In this case you'd start the survey with the query url "index.php?sid=12345&passthru;=subsid&subsid;=9999".<br />
<br />
In your URL you would use {PASSTHRULABEL} and {PASSTHRUVALUE} to reuse these values at the end of the survey.<br />
<br />
A URL of "http://www.limesurvey.org/test.php?{PASSTHRULABEL}={PASSTHRUVALUE}" would then convert to "http://www.limesurvey.org/test.php?subsid=9999"<br />
<br />
===Places to use URL fields===<br />
<br />
URL fields can be used in the general survey exit URL (see [[Creating a new survey]] ), and in the URL setting for each individual quota (see [[Quotas]] ).</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Upgrading_from_a_previous_version&diff=3565Upgrading from a previous version2012-10-02T12:21:46Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Before you start...=<br />
<br />
<span style='color:#FF0000'>... read this because it is very important: '''Always backup the files and the database of your current installation!!'''</span><br />
<br />
You can do this using a database adminstration tool like [http://www.phpmyadmin.net phpMyAdmin] etc. and a file manager! If you don't know how to do this you should better not proceed but ask someone who knows or use the [[ComfortUpdate]] instead.<br />
<br />
=The quick way (for minor version changes)=<br />
<br />
You can use this instruction if you are doing a minor upgrade (for example from 2.00 to 2.01)<br />
*Backup your files and database (did we already mention that?)<br />
*Delete all the old files/directory except for<br />
**/application/config/config.php<br />
**/upload directory<br />
*Copy the new files from the new LimeSurvey package to the existing location.<br />
*'''After the upgrade: Clear your browser cache and cookies!'''<br />
<br />
=The thorough way (for big version jumps)=<br />
<br />
Unfortunately there are a couple of things to consider, so please scan the following instruction closely.<br />
<br />
==Upgrading from version 1.50 or later to any later 2.xx version==<br />
#[http://www.limesurvey.org/download Download] the latest version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. For example in Linux tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory.<br />
### Using phpMyAdmin or similar to export all tables; or use the according '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file, modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
## The upgrade process try to replace the template.js inclusion by the placeholder {TEMPLATEJS}. If you have javascript issue with your custom template, verify if your template have the placeholder {TEMPLATEJS} in startpage.pstpl.<br />
## Open http://<yourdomain>/<yourlimesurveydir>/admin in your browser and follow the instructions (you can use the old config.php as reference). The existing database will be automatically detected and , if necessary, upgraded after confirmation.<br />
# Check if any special manual checks apply as listed below<br />
# '''Now clear your browser cache and cookies!'''<br />
# You are done (:biggrin:).<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 2.xx''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from version 1.50 or later to any later 1.xx version==<br />
#[http://www.limesurvey.org/download Download] the desired version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. e.g. tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory<br />
### Using phpMyAdmin or similar to export all tables; or using the '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file ,modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## Edit or replace the '''config.php''' file:<br />
### If your previous version was < 1.70: Edit the new '''config.php''' to reflect changed settings in the backup '''config.php''' file. '''Do not just overwrite the new '''config.php''' with your old one!'''<br />
### If your previous version was >= 1.70: Simply replace the new '''config.php''' with your backup '''config.php''' (as the file format has not changed).<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
# Finishing the installation<br />
## Once you open the URL to your LimeSurvey administration the database tables will be updated after confirmation<br />
## Remove or rename the '''/admin/install''' directory as/if instructed by the installation script<br />
## Check if any special, manual checks apply as listed below<br />
# You are done (:biggrin:). If you notice any problems after the upgrade: Clear your browser cache and cookies!<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 1.92''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from a version earlier than v1.50 (v1.0 through v1.44)==<br />
<br />
Since the data structure and a lot of other things were changed, '''upgrading from any version previous to v1.50 is NOT possible'''. If you have old survey structure files with a *.sql extension the only way to get these into a newer version is to install [http://www.limesurvey.org/en/archived-releases/finish/24-archived-releases/289-limesurvey150zip version 1.50], import the .sql file(s) there, then upgrade that version to the most recent LimeSurvey version. See the also then page [[Transferring an installation]] for more details.<br />
<br />
=Upgrade FAQ=<br />
<br />
==What is the most actual LimeSurvey version that still supports PHP4?==<br />
<br />
The last release offering PHP4 support was version 1.82+.<br />
<br />
==Can I upgrade even if I have active surveys?==<br />
<br />
Yes, you can. Exceptions may be mentioned in the thorough instructions above. We strongly advise to test your surveys after upgrade to check if your design templates still work alright.<br />
<br />
==What is best way to port LimeSurvey *.sql survey structure files to the latest version?==<br />
<br />
Install version 1.50, import the file and export the survey structure to the newer .csv format. The latest version still can read the .csv survey structure format.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Theme_editor&diff=3358Theme editor2012-09-27T17:08:38Z<p>Admin: </p>
<hr />
<div><br />
{maketoc title="Contents:"}<br />
<br />
=Introduction=<br />
<br />
LimeSurvey has a basic template and style system providing a theme-like capability found in many browser-based applications. They are simply termed '''Templates''' here. The Templates allow control over the look and feel of pages during a survey. A survey administrator can select the template to use for each survey to thus personalize that survey's look and feel. Changes to a Template can be as simple as adding a unique logo on the welcome page, changing background colors, or maybe new text colors for specific types of questions.<br />
<br />
LimeSurvey comes with a set of templates right out of the box. These initial templates are defined by directories within the LimeSurvey installation "templates" directory. Each template has it's own directory. Within the main directory of a template are numerous files: '''templates (.pstpl)''', '''cascading style sheets (.css)''', '''images''' ('''.jpg''' or '''.png''') and maybe others.<br />
<br />
Like in other theme-based systems, fragments of HTML code are stored in the .pstpl template files. These fragments are read in and used to construct the page to display to the end user during the operation of a survey. Often '''keywords''' surrounded by curly braces are included in the files that are then replaced with the relevant text. The following gives an example of a template file content and its result when used in a survey page:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><center><font face='verdana' color='red'>{SURVEYNAME}</font><br /><br />
<br />
<font face='verdana' color='blue'><u>{SURVEYDESCRIPTION}</u></center></syntaxhighlight><br />
<br />
One gets a result that looks like:<br />
<br />
<div class="simplebox"><center>'''<span style='color:red'>My New Survey</span>'''</center><br />
<br />
<center><u><span style='color:#0000ff'>This is a survey written by me to find out what sort of chocolate people like.</span></u></center></div><br />
<br />
Templates, being HTML code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most reference a common cascading style sheets (CSS) file that defines the font style, color, size, background and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe once how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Template file. Finally, special Keywords in curly braces are replaced with text defined in the Survey for each of its corresponding language translations (for example, the Survey Title or Question Text for each language defined).<br />
<br />
If you create a new custom template, please consider contributing it back to the LimeSurvey community, and make it available to others. With your help, we can grow our repository of templates, surveys, and other ad-ons, to make LimeSurvey even better! See the shared [http://www.limesurvey.org/component/remository/lang,en-gb/ Template Repository]<br />
<br />
=Creating a new Template=<br />
<br />
To be able to create a new template (or edit an existing template), you need Template Editing user permission in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.<br />
<br />
<div class="simplebox">'''Note of Warning:''' As template changes can affect all surveys in an installation, changes should be limited to those skilled in understanding general concepts in the code base. Templates are an advanced feature that can take some experimentation to get correct if you are not familiar with HTML code methods.</div><br />
<br />
The preferred way to create a new template is through the Template Editor (see below) via the web Admin interface. Some people may like to work directly with template files so that they can use their favorite text editor instead of the web interface. In this case, still use the Template Editor to first create your new template. This will create a new base template with all the files you need in the LimeSurvey_web_root/upload/templates/your_new_template directory. From there you can use your text editor to manually adjust the template files.<br />
<br />
<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these template files will be owned by the group and user who the web server is running as (may be "www" for some systems). So make sure you have access to edit these files, and when you save them make sure they don't change ownership, so you can still use the web Template Editing interface if needed</div><br />
<br />
Template files may seem complex to understand at first. You have to likely understand HTML code, possibly Styles and Style Sheets, and have access to the underlying LimeSurvey installation files if the template files and directories are not editable. Copy an existing template to a new directory to play around with the content. This may help make the concept clearer.<br />
<br />
A number of the 'public' elements of LimeSurvey can be adjusted by a series of templates. This section provides a very brief explanation of these templates, however more detailed information - especially regarding the editing/creation of new templates is available under [[Templates + Styles]].<br />
<br />
=The LimeSurvey Template Editor=<br />
<br />
To ease the understanding and quick update of a Template, LimeSurvey provides a '''Template Editor''' in the main '''administrative''' toolbar of the application. This Template Editor is only available to users given the privilege in the User Security settings. A template effects all surveys and can render a survey inoperable if not constructed properly. So Template editing is thought best restricted to a very limited, knowledgeable set of users. Having permission to enter the Template Editor is not enough though.<br />
<br />
The LimeSurvey Template Editor allows you to edit the contents of your templates online. Start the Template Editor by clicking on the "Template Editor" icon [[File:templates.png]] in the LimeSurvey Administration toolbar (Templates). The main screen is similar to the LimeSurvey Survey Administration screen. It allows you to select the template to edit/view. Once this has been selected you can then select from one of the different public survey pages. You are then presented with a list of the template files that make up that particular page.<br />
<br />
==The Template Menu==<br />
*'''Edit Icon:''' The "edit" icon indicates whether or not the template is editable. A blurred out icon indicates that the template is read only; a clickable icon indicates you may make modifications. To change the icon from blurred to clear, you have to modify the template's permissions.<br />
*'''Rename this template:''' Allows you to change the name of the template. Generally used after copying an existing template or importing a template by manipulating the underlying directories.<br />
*'''Export Template:''' Allows you to export the current template to a .zip-File.<br />
*'''Copy Template:''' Allows you to make a new template by copying the current one.<br />
<br />
The "Screen" drop-down list on the right allows you to choose which particular survey page you are currently looking at.<br />
<br />
==Import/Export/Copy a Template==<br />
<br />
When you '''export '''a template, this will create a zip-file archive with all the files your template consists of (.pstpl files, images, css files, ...). You can simply '''import '''the exported zip-file at other Limesurvey systems by using the import feature or you can manually copy the archive to another installation and extract it into the corresponding template directory there. If you copy the template in the same installation, you will need to rename the folder to create another named copy of that template.<br />
<br />
If the file and directory permissions are open for the LimeSurvey application to write, then you can use the programs '''copy '''and rename features to make a local copy of a template.<br />
<br />
==Page Structure / Template Use==<br />
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, navigator.pstpl, endpage.pstpl<br />
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl, navigator.pstpl, endpage.pstpl<br />
*'''The Submit Page:''' startpage.pstpl, survey.pstpl, submit.pstpl, (privacy.pstpl), navigator.pstpl, endpage.pstpl<br />
*'''The Final Page:''' startpage.pstpl, completed.pstpl, endpage.pstpl<br />
<br />
==Template Files==<br />
<br />
The following template files are used to produce your public survey and must exist in any new template folder you create:<br />
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag, even though many browsers do not require strict adherence to the W3 HTML stanards, the LimeSurvey script needs to find a <body> tag, to run certain javascript elements. It is not expected that many 'keywords' will be used in the startpage.pstpl file, however you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file, so you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.<br />
*'''survey.pstpl:''' This template is the second used on most pages, and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (ie: don't leave a table open here because there is nowhere else to close it)<br />
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.<br />
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.<br />
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. It is separate to the startgroup.pstpl file because in a "question by question" survey it will be displayed on its own unique page in between groups, whereas in a "group by group" or "all in one" survey it provides a header to the subsequent questions. groupdescription.pstpl does not have a corresponding 'closing' template file, so all tags should be closed.<br />
*'''question.pstpl:''' This file contains the question, answer and help text sections of your survey, and in the "group by group" and "all in one" surveys this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.<br />
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LS1.87)'''. All keywords from this template are now available directly in question.pstpl. NOTE: templates using question_start.pstpl will still work at least for a couple more versions of LS 1.x<br />
*'''submit.pstpl (and privacy.pstpl):''' This page is the penultimate page for all types of survey (except the "all in one" type) where the participant is given an option to review questions before submitting their responses. It provides privacy information where a survey is anonymous, which it extracts from the '''privacy.pstpl''' file.<br />
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.<br />
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file<br />
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.<br />
*'''printanswers.pstpl:''' This file has the HTML wrapper for the print version of the survey.<br />
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl endgroup.pstpl but for the print version of the survey.<br />
*'''print_question.pstpl:''' This file is the same as question.pstpl but for the print version of the survey.<br />
*'''print_survey.pstpl:''' This file is the same as survey.pstpl but for the print version of the survey.<br />
<br />
== CSS and Javascript==<br />
<br />
Two files are allways used for template : template.css for css and template.js for javascript.<br />
*'''{TEMPLATECSS}:''' Add lines for default css, template.css and template-rtl.css for rtl language.<br />
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js and all js files needed for LimeSurvey.<br />
<br />
=== Replacing default css or javascript===<br />
<br />
Some question use specific files for javascript or css. You can use your own files. All files used in your survey included in ./scripts or in .//styles-public can be replaced, just put a file with the same name in your template.<br />
<br />
==Other Template Files==<br />
<br />
The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''' and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.<br />
<br />
==Standard Pages==<br />
<br />
There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the survey's settings. The table below indicates which template files are used in constructing each of these pages.<br />
<br />
{|<br />
| '''Survey Pages:'''<br/>'''Template Files'''||Survey<br/>List||Welcome||Question||Completed||Clear All||Register||Load||Save||Print<br/>Answers||Print<br/>Survey<br />
|-<br />
|SurveyList|| [[File:check.gif]]|| || || || || || || || ||<br />
|-<br />
|Welcome|| || [[File:check.gif]]|| || || || || || || ||<br />
|-<br />
|Privacy|| || [[File:check.gif]]|| || || || || || || ||<br />
|-<br />
|Navigator|| || [[File:check.gif]]|| [[File:check.gif]]|| || || || || || ||<br />
|-<br />
|Survey|| || || [[File:check.gif]]|| || || [[File:check.gif]]|| || || ||<br />
|-<br />
|StartGroup|| || || [[File:check.gif]]|| || || || || || ||<br />
|-<br />
|GroupDescription|| || || [[File:check.gif]]|| || || || || || ||<br />
|-<br />
|Question<span style='color:red'>'''*'''</span>|| || || [[File:check.gif]]|| || || || || || ||<br />
|-<br />
|EndGroup|| || || [[File:check.gif]]|| || || || || || ||<br />
|-<br />
|Assessment|| || || || [[File:check.gif]]|| || || || || ||<br />
|-<br />
|Completed|| || || || [[File:check.gif]]|| || || || || ||<br />
|-<br />
|ClearAll|| || || || || [[File:check.gif]]|| || || || ||<br />
|-<br />
|Register|| || || || || || [[File:check.gif]]|| || || ||<br />
|-<br />
|Load|| || || || || || || [[File:check.gif]]|| || ||<br />
|-<br />
|Save|| || || || || || || || [[File:check.gif]]|| ||<br />
|-<br />
|PrintAnswers|| || || || || || || || || [[File:check.gif]]||<br />
|-<br />
|Print Survey || || || || || || || || || || [[File:check.gif]]<br />
|-<br />
|Print Group || || || || || || || || || || [[File:check.gif]]<br />
|-<br />
|Print Question || || || || || || || || || || [[File:check.gif]]<br />
|-<br />
|StartPage<br/>EndPage<br/>Template.css|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| <br />
|}<br />
<br />
<span style='color:red'>'''*'''</span>NOTE: In versions 1.90 and up this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight><br />
<br />
<span style='color:red'>'''*'''</span>NOTE: In version 1.91 and earlier, LimeSurvey js files are not included by the template. In version 2, '''you have to use {TEMPLATEJS} in your one of your template file''' to add the link to the js file. You can add it in startpage.pstpl or in endpage.pstpl. You can remove the {TEMPLATEURL}/template.js line and you have to replace with {TEMPLATEJS} to update a personal template.<br />
<br />
==The File Control Section==<br />
<br />
In the "file control" window on the left, you can click on one of the template files that is used to compile the page. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.<br />
<br />
The "Other Files" window shows a list of all other files in the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''. Note: Instead of a link directly to each picture in your template you can use the field string {TEMPLATEURL}. So instead of:<br />
<br />
<syntaxhighlight lang="php" enclose="div">img src='/limesurvey/templates/yourtemplate/mypicture.jpg'</syntaxhighlight> You can use:<br />
<br />
<syntaxhighlight lang="php" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight><br />
<br />
A "sample" of the template page you are editing will be visible at the bottom of the screen. There is no way to to delete a template from the template editor. This must be done by accessing the underlying directory and deleting the file there.<br />
<br />
<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the Template Editor and should never be changed. If you want to modify them, create a copy first and modify the copy.</div><br />
<br />
==Location of template files==<br />
<br />
LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the /templates directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the /upload/templates directory.<br />
<br />
To create a new template, use the according icon in the template editor.<br />
<br />
There should ALWAYS be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. The "default" directory comes with the package.<br />
<br />
You can use any image files that you upload into the template management area with syntax like this:<br />
<br />
<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight><br />
<br />
=Styling questions with CSS=<br />
<br />
Styling of questions in CSS has become much easier. Each question type now has a unique class. Mandatory question's also have an additional mandatory class. For example, for a non-mandatory question:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><div id="question5" class="gender"><br />
<br />
...<br />
<br />
</div></syntaxhighlight><br />
<br />
and if the question is mandatory<br />
<br />
<syntaxhighlight lang="php" enclose="div"><div id="question5" class="gender mandatory"><br />
<br />
...<br />
<br />
</div></syntaxhighlight><br />
<br />
and if the question is mandatory but the user didn't answer it or if there is validation on a question<br />
<br />
<syntaxhighlight lang="php" enclose="div"><div id="question5" class="gender mandatory input-error"><br />
<br />
...<br />
<br />
</div></syntaxhighlight><br />
<br />
and if the question has validation applied but the user hasn't answered correctly<br />
<br />
<syntaxhighlight lang="php" enclose="div"><div id="question6" class="text-short input-error"><br />
<br />
...<br />
<br />
</div></syntaxhighlight><br />
<br />
==The full list of question classes==<br />
<br />
{|<br />
|'''Question Type'''||'''Question Class'''||'''Question ID'''<br />
|-<br />
|5 point choice||.choice-5-pt-radio||5<br />
|-<br />
|Array (10 point choice)||.array-10-pt||B<br />
|-<br />
|Array (5 point choice)||.array-5-pt||A<br />
|-<br />
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1<br />
|-<br />
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E<br />
|-<br />
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:<br />
|-<br />
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;<br />
|-<br />
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C<br />
|-<br />
|Array (flexible labels)||.array-flexible-row ||F<br />
|-<br />
|Array (flexible labels) by column||.array-flexible-column||H<br />
|-<br />
|Boilerplate question||.boilerplate||X<br />
|-<br />
|Date||.date||D<br />
|-<br />
|Gender||.gender||G<br />
|-<br />
|Huge free text||.text-huge||U<br />
|-<br />
|Language switch||.language||I<br />
|-<br />
|List (dropdown)||.list-dropdown||!<br />
|-<br />
|List (flexible labels) (dropdown)||.list-dropdown-flexible||W<br />
|-<br />
|List (flexible labels) (radio)||.list-radio-flexible||Z<br />
|-<br />
|List (radio)||.list-radio||L<br />
|-<br />
|List with comment||.list-with-comment||O<br />
|-<br />
|Long free text||.text-long||T<br />
|-<br />
|Multiple numerical input||.numeric-multi||K<br />
|-<br />
|Multiple options||.multiple-opt||M<br />
|-<br />
|Multiple options with comments||.multiple-opt-comments||P<br />
|-<br />
|Multiple short text||.multiple-short-txt||Q<br />
|-<br />
|Numerical input||.numeric||N<br />
|-<br />
|Ranking||.ranking||R<br />
|-<br />
|Short free text||.text-short||S<br />
|-<br />
|Yes/No||.yes-no||Y<br />
|-<br />
|<br />
|}<br />
<br />
==The full list of validation classes==<br />
<br />
<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div><br />
<br />
These apply to the help and/or validation tip messages so that each type can be individually styled.<br />
<br />
The .hide-tip option and .input-error options, by default, interact so that you can have validation tips start hidden, but appear when there validation errors, and disappear again when those errors are rectified.<br />
<br />
All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed, and are color-coded to indicate whether the answers pass the validation criteria.<br />
<br />
Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been med; then re-display the page using a harsher color if the person submits the page with lingering validation errors.<br />
<br />
{|<br />
|'''Purpose'''||'''CSS Class'''||'''Description'''<br />
|-<br />
|Mandatory||.mandatory||the question is mandatory<br />
|-<br />
|User input error||.input-error||the question had at least one validation error<br />
|-<br />
|Hide Tip||.hide-tip||added if you use the hide_tip option<br />
|-<br />
|Num answers||.em_num_answers||for for min_answers and max_answers<br />
|-<br />
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max<br />
|-<br />
|Sum range||.em_sum_range||for min/max/equals_num_value<br />
|-<br />
|Regex validation||.em_regex_validation||for regular-expression validation of the question<br />
|-<br />
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option<br />
|-<br />
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option<br />
|-<br />
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.<br />
|-<br />
|<br />
|}<br />
<br />
==Importing styles into your custom template==<br />
<br />
The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* <strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike>----<br />
<br />
START: Question styles <strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike> */</syntaxhighlight><br />
<br />
If you're styling your own custom template, You should be able to copy everything after the above from templates/default/template.css (for tables based layouts) or /templates/limespired/template.css (for CSS based layouts) into your own style sheet without any impact on your other styles.<br />
<br />
==Internet Explorer conditional style sheets==<br />
<br />
Because of the marked discrepancies in rendering between IE6, IE7 and most other browsers, there are special IE conditional style sheets included for each template.<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<br />
<br />
</syntaxhighlight>You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either /templates/default/ or /templates/limespired for Tables base layout and CSS based layout respectively.<br />
<br />
<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div><br />
<br />
===Alternative solution for Internet explorer===<br />
<br />
You can put conditional class for body in startpage.pstpl, and use this class in your template.css<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT}"></syntaxhighlight><br />
<br />
And in template.css use<br />
<br />
<syntaxhighlight lang="php" enclose="div">.ie6{/*specific for internet explorer */}<br />
<br />
.ie{/*specific for all internet explorer */}</syntaxhighlight><br />
<br />
You can see this alternative in citronade template.<br />
<br />
== Right-to-Left (RTL) Languages and justify==<br />
<br />
The text editor within LimeSurvey is able to format RTL Text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.<br />
<br />
==Keywords==<br />
<br />
Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}<br />
<br />
The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)<br />
<br />
{|<br />
|'''::KEYWORD::'''|| '''TEMPLATE FILES::''' || '''::DESCRIPTION::'''<br />
|-<br />
|{SURVEYNAME}||All Files||The survey title<br />
|-<br />
|{SURVEYDESCRIPTION}||All Files||The survey description<br />
|-<br />
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text<br />
|-<br />
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed<br />
|-<br />
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name<br />
|-<br />
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description<br />
|-<br />
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)<br />
|-<br />
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".<br />
|-<br />
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled<br />
|-<br />
|{QUESTION}||Question.pstpl||('''Has been superseeded but the {QUESTION_...} keywords as of LS1.87''') Displays the current question text (The format of {QUESTION} can customised by editing 'question_start.pstpl') Use the following: {QUESTION_TEXT}, {QUESTION_MANDATORY}, {QUESTION_HELP}, {QUESTION_MAN_MESSAGE}, {QUESTION_VALID_MESSAGE} and {QUESTION_INPUT_ERROR_CLASS} and appropriate wrapping HTML instead of {QUESTION})<br />
|-<br />
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question<br />
|-<br />
|{SGQ}||question.pstpl, question text||Can be used in the question text itself, to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)<br />
|-<br />
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question<br />
|-<br />
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)<br />
|-<br />
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code<br />
|-<br />
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)<br />
|-<br />
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question<br />
|-<br />
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question<br />
|-<br />
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error<br />
|-<br />
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions<br />
|-<br />
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question<br />
|-<br />
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question<br />
|-<br />
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)<br />
|-<br />
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question<br />
|-<br />
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.<br />
|-<br />
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question<br />
|-<br />
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.<br />
|-<br />
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)<br />
|-<br />
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link<br />
|-<br />
|{SUBMITBUTTON}||submit.pstpl||Displays the final submit button<br />
|-<br />
|{COMPLETED}||completed.pstpl||Displays the 'completed' messagem for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.<br />
|-<br />
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'<br />
|-<br />
|{PRIVACY}||submit.pstpl||Displays privacy information when survey is anonymous<br />
|-<br />
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [http://docs.limesurvey.org/tiki-index.php?page=LimeSurvey+1.x+Translating+LimeSurvey The text can be edited/translated] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.<br />
|-<br />
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)<br />
|-<br />
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button<br />
|-<br />
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"<br />
|-<br />
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table<br />
|-<br />
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***<br />
|-<br />
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***<br />
|-<br />
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***<br />
|-<br />
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***<br />
|-<br />
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files<br />
|-<br />
|{RESTART}||clearall.pstpl||URL to restart the survey<br />
|-<br />
|{CLOSEWINDOW}||All Files (Preferably in navigator.pstpl)||URL to close current window<br />
|-<br />
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")<br />
|-<br />
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files<br />
|-<br />
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files<br />
|-<br />
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.<br />
|-<br />
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.<br />
|-<br />
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.<br />
|}<br />
<br />
==Input/Buttons==<br />
<br />
Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file, and have some control over the appearance of form buttons and inputs. These class names are as follows:<br />
*'''submit''' (Submit Buttons)<br />
*'''text''' (Text Inputs - for short free text, date and numerical type)<br />
*'''answertext''' (Text of answers)<br />
*'''radio''' (Radio Buttons)<br />
*'''checkbox''' (Check Boxes)<br />
*'''select''' (Select / List Boxes)<br />
*'''textarea''' (Large text inputs - for long free text)<br />
*'''clearall''' (The "Exit and Clear Survey" link)<br />
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes (these are set by relevant section above) but does allow changing of background colour, text colour and size etc for the rest of the ranking question)<br />
*'''graph''' (The "percentage completed" graph table)<br />
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text<br />
*'''question''' (General settings for any question that is displayed within a table. Generally you should use this to make sure that their font size and colour is the same as you have used elsewhere as a default)<br />
*'''mandatory''' (Mandatory questions)<br />
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)<br />
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background colour for these question types. '''Array1''' is also used for the column headings in these question types)<br />
*'''errormandatory''' (Sets the colour and style of the "This question is mandatory" error message)<br />
*'''warningjs''' (Sets the colour and style of the warning message displayed if the participant's browser has javascript disabled)<br />
<br />
There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):<br />
*'''surveycontact''' (The contact message shown on the start page)<br />
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)<br />
<br />
An example of using these classes with style sheets can be found in the "bubblegum" template that comes with the LimeSurvey application.<br />
<br />
Because you can edit all the HTML aspects, there's no reason to surround your templates with a <div class='new_name'> and then define a css for that new_name class.<br />
<br />
==Styling the progress bar==<br />
<br />
'''Before version 1.87:'''<br />
<br />
The chart.jpg file is a simple one pixel image file which is used to create the progress bar image in the 'PERCENTCOMPLETE' table. If the file does not exist, LimeSurvey will use the default 'maroon' coloured image in the public directory. If you want to create a bar to match your own colour scheme, then you should save the color in this file. Remember it should be a '''JPEG''' file, 1 pixel x 1 pixel, in the colour desired.<br />
<br />
'''Version 1.87 and newer:'''<br />
<br />
The progress bar appearance can be modified with CSS.<br />
<br />
To change the background colour of the bar, add something like the following to the end of your template.css file.<br />
<br />
<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {<br />
<br />
background-color: #3300FF;<br />
<br />
}</syntaxhighlight><br />
<br />
To change the border colour of the bar, add something like the following to the end of your template.css file.<br />
<br />
<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,<br />
#progress-wrapper .ui-widget-header {<br />
<br />
border: 1px solid #FF0000;<br />
<br />
}</syntaxhighlight><br />
<br />
==Advanced Features Available to Developers==<br />
<br />
Starting with version 0.99, LimeSurvey has integrated some user-made patches that allow for some special changes. These very advanced features generally require changes to the underlying code base of LimeSurvey and should be done carefully so as not to introduce security holes.<br />
<br />
===Basic CMS Integration support===<br />
<br />
To be able to integrate LimeSurvey into another CMS, use the following options in '''config.php''':<br />
<br />
// Set $embedded to true and specify the header and footer functions if the survey is to be displayed embedded in a CMS<br />
<br />
<nowiki><br />
<br />
$embedded = false;<br />
<br />
$embedded_inc = ""; // path to the header to include if any<br />
<br />
$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog<br />
<br />
$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog<br />
<br />
</nowiki><br />
<br />
Set '''$embedded = true;''' to enable CMS-embedding. By using the '''$embedded_inc''' variable one can include their own '''.php''' files. By setting '''$embedded_headerfunc''' or '''$embedded_footerfunc''', one can call functions from within included files that output the relevant headers or footers instead of LimeSurveys default ones.<br />
<br />
===Support for your own Javascript functions===<br />
<br />
Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling each. This way a template author can create their own '''template_onload()''' function in the HEAD that replaces the default one.<br />
<br />
'''Version 1.87 and newer:'''<br />
*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.<br />
*Enter your script in the source of a question or group description.<br />
*There are more details in the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds%3A+Manipulating+a+survey+at+runtime+using+Javascript&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._in_LimeSurvey_ workaround section].<br />
<br />
=Videos on Templates=<br />
<br />
These videos will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, customizing survey description page, and completed page.<br />
<br />
Part I<br />
<br />
{YOUTUBE(movie="nLsfxMjRXyk?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
Part II<br />
<br />
{YOUTUBE(movie="yrAXStFH34Q?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
Part III<br />
<br />
{YOUTUBE(movie="TYlJXHgt8R0?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
Part IV<br />
<br />
{YOUTUBE(movie="Rml0gqeErVc?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
Part V<br />
<br />
{YOUTUBE(movie="LX24Ix1ylmY?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
Part VI<br />
<br />
{YOUTUBE(movie="-202CqQcW8g?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
=Tips & Tricks=<br />
<br />
==Some language specific element==<br />
<br />
If you want to have some langage specific sentence in a survey, for example an help at end of each page, you can add in a .pstl file a sentence and hidding it for other langage. ANd hidding it in the template.css, we can use psuedo selector :lang, but for best compatibility, we use some class.<br />
<br />
Example for a help sentence at bottom of the page, in french an english, put this on endpage.pstpl:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div><br />
<br />
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight><br />
<br />
ans in template.css<br />
<br />
<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}<br />
<br />
.lang-en .fr{display:none}</syntaxhighlight><br />
<br />
You can use it to for other sentence in your question before 1.92 ( in 1.92, there are better solutions).<br />
<br />
==Change the layout of the survey page==<br />
<br />
When editing a template this template can be assigned to a single survey while the survey list page, which is shown at www.yourdomain.org/limesurveyinstallfolder, lists all your surveys.<br />
<br />
To use your current template for this page you have change the according setting at the Global Settings screen; at older versions this change can be done by editing the $defaulttemplate setting at the config file: Copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to $defaulttemplate = 'yourtemplatename';<br />
<br />
==Import/Export of templates: Mac users==<br />
<br />
Mac users, please note: Mac OSX default archive utility may have problems with zip folders "generated on the fly".<br />
<br />
a work around is to unix'es unzip from the command line:<br />
<br />
$ unzip template.zip -d template<br />
<br />
Archive: template.zip<br />
<br />
inflating: template/startpage<br />
<br />
inflating: ...<br />
<br />
or scripts in their mac-compiled counterparts:<br />
<br />
http://homepage.mac.com/roger_jolly/software/<br />
<br />
==Changing your templates traffic light from red to green==<br />
<br />
If you haven't already, set the admin directory to read/write/execute (777). The files within it, however, may be set to read/execute only (chmod 755).<br />
<br />
GO to file directory ie file manager, find templates directory.<br />
<br />
1 change permission on eg"vallendar" (or any template of your choice) directory to read 777<br />
<br />
2 voila! the red traffic light on "vallendar" is now green.<br />
<br />
3 NOTE: to restrict access for safety, when finished editing template files, change all templates files back to what they were eg 644<br />
<br />
==Replacing the help icon==<br />
<br />
When a question help text is shown then an help.gif image is used from the default template folder.<br />
<br />
You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It then will be automatically used instead of the default help icon.<br />
<br />
==Replacing an existing logo==<br />
<br />
'''Note''': Before uploading new logo delete previous one.<br />
<br />
1. To edit logo go to &bdquo;<u>template.css</u>&rdquo;, you can find it here (see in screen):<br />
<br />
[[File:1.PNG]]<br />
<br />
2. Find and Click Search button, to find place where is logo style text.<br />
<br />
[[File:2.PNG]]<br />
<br />
3. Find in search <u>#logo</u> (It is logo design code)<br />
<br />
[[File:3.PNG]]<br />
<br />
4. Edit style file<br />
<br />
You will see something like this code:<br />
<br />
[[File:4.PNG]] <br />
<br />
If you want change image just replace logo.gif to antoher image link. Like: (<u>logo.png</u>, <u>logo.jpg</u>, <u>logo.swf</u>).<br />
<br />
If you want change image size just change, width and height (in pixels) like:<br />
<br />
<syntaxhighlight lang="php" enclose="div">Width:100px; Height:100px;</syntaxhighlight><br />
<br />
==Adding your own logo==<br />
<br />
1. Find and Open &bdquo;<u>startpage.pstpl</u>&rdquo; template file.<br />
<br />
[[File:5.PNG]] <br />
<br />
2. Write in &bdquo;<u>startpage.pstpl</u>&rdquo; this line:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><img id=&rdquo;page_logo&rdquo; src=&rdquo;{TEMPLATEURL}logo.png&rdquo;><br></syntaxhighlight> After <syntaxhighlight lang="php" enclose="div"><body ... ></syntaxhighlight> tag<br />
<br />
[[File:6.PNG]] <br />
<br />
3. To add logo go to &bdquo;<u>template.css</u>&rdquo;, you can find it here (see in screen):<br />
<br />
[[File:1.PNG]]<br />
<br />
3.1 Go to end of &bdquo;<u>template.css</u>&rdquo; style file.<br />
<br />
3.2 Write in end:<br />
<br />
'''If you want in left side:'''<br />
<br />
<syntaxhighlight lang="php" enclose="div">#page_logo{<br />
<br />
float:left;<br />
<br />
}</syntaxhighlight><br />
<br />
'''If you want in right side:'''<br />
<br />
<syntaxhighlight lang="php" enclose="div">#page_logo{<br />
<br />
float:right;<br />
<br />
}</syntaxhighlight><br />
<br />
'''If you want in center:'''<br />
<br />
<syntaxhighlight lang="php" enclose="div">#page_logo{<br />
<br />
display: block;<br />
<br />
margin-left: auto;<br />
<br />
margin-right: auto;<br />
<br />
}</syntaxhighlight><br />
<br />
==Use the same template with different logos==<br />
<br />
If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}logoImage-{SID}.png"></syntaxhighlight><br />
<br />
==Remove the default help to all question (hide_tip)==<br />
<br />
There are 2 solution to remove the default help, like a [[Advanced question settings|#hide_tip|hide_tip attribute]] but for all question and survey.<br />
# you can remove the {QUESTIONHELP} and is container from the file question.pstl, but it can be a bad idea for screenreader.<br />
# for the default template and some other , add this at the end of tempate.css<br />
<br />
<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight><br />
<br />
== Display custom favicon==<br />
<br />
A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:<br />
#Create a favicon - google will find you lots of free favicon generators<br />
#Name your new favicon "favicon.ico" and place it in your template directory<br />
#Add the following code to your '''startpage.pstpl''' before the </head> tag<br />
<br />
<syntaxhighlight lang="php" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"><br />
<br />
<link rel="icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"></syntaxhighlight><br />
<br />
== Different appearance for survey-/question-pages==<br />
<br />
(''Version 1.91 and newer'')<br />
<br />
If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages) you can use '''.page-odd''' class in your css file to change the appearance of odd pages.<br />
<br />
example from default template of LimeSurvey 1.91+<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
.page-odd table.question-group {<br />
<br />
background-color: #D2F2D3;<br />
<br />
}</syntaxhighlight><br />
<br />
To '''not''' differentiate even and odd pages at the (default) template find all instances of ''.page-odd'' in template.css and remove those styles.<br />
<br />
==Create a vertical separator border for dual scale array==<br />
<br />
To create a vertical separator border for a dual scale array you can add the following lines to your '''template.css'''-file.<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
table.question thead td.header_separator,<br />
<br />
table.question tbody td.dual_scale_separator<br />
<br />
{<br />
<br />
border-right:solid 1px #00A8E1;<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
header_separator is used to adress the separator for the header "td" and "dual_scale_separator" is used to adress the separator column in the dual scale array.<br />
<br />
==Hide the survey contact message shown on the start page/survey list==<br />
<br />
To hide the "Please contact ..." meassage on the start page (with the survey list) you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
$('#surveycontact').hide(); //Hides the survey contact message<br />
<br />
</syntaxhighlight><br />
<br />
==Remove the survey contact message shown on error messages==<br />
<br />
If you want to remove the survey contact message from error messages it'll be trickier. You can add the following function call to the '''$(document).ready''' function in the '''template.css''' of your used design template:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
removeContactAdressFromMessage(); //Removes the survey contact message from error messages<br />
<br />
</syntaxhighlight><br />
<br />
and add the following function to your *template.js* file<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
function removeContactAdressFromMessage()<br />
<br />
{<br />
<br />
if ($('#tokenmessage').length > 0)<br />
<br />
{<br />
<br />
var oldMessage = $('#tokenmessage').html();<br />
<br />
var indexContact = oldMessage.indexOf('Bitte kontaktieren');<br />
<br />
var newMessage = oldMessage.substr(0, indexContact);<br />
<br />
$('#tokenmessage').html(newMessage);<br />
<br />
}<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
It will probably not work for an englisch survey and have to be extended when using for multilingual surveys. But it's an idea/tip how to solve this.<br />
<br />
==How to deal with multilingual question attributes (before version 2.0 at which those were added)==<br />
<br />
If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at Limesurvey 2.0). To work around this, paste in the field to change the label for "other"<br />
<br />
<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight><br />
<br />
At the template.css of your template (at /limesurvey/upload/templates/<yourtemplatename>/template.css) add:<br />
<br />
<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}<br />
<br />
html:lang(fr) .en{display:none}</syntaxhighlight></div>Adminhttps://www.limesurvey.org/manual/index.php?title=Theme_editor&diff=3359Theme editor2012-09-27T17:03:54Z<p>Admin: </p>
<hr />
<div><br />
{maketoc title="Contents:"}<br />
<br />
=Introduction=<br />
<br />
LimeSurvey has a basic template and style system providing a theme-like capability found in many browser-based applications. They are simply termed '''Templates''' here. The Templates allow control over the look and feel of pages during a survey. A survey administrator can select the template to use for each survey to thus personalize that survey's look and feel. Changes to a Template can be as simple as adding a unique logo on the welcome page, changing background colors, or maybe new text colors for specific types of questions.<br />
<br />
LimeSurvey comes with a set of templates right out of the box. These initial templates are defined by directories within the LimeSurvey installation "templates" directory. Each template has it's own directory. Within the main directory of a template are numerous files: '''templates (.pstpl)''', '''cascading style sheets (.css)''', '''images''' ('''.jpg''' or '''.png''') and maybe others.<br />
<br />
Like in other theme-based systems, fragments of HTML code are stored in the .pstpl template files. These fragments are read in and used to construct the page to display to the end user during the operation of a survey. Often '''keywords''' surrounded by curly braces are included in the files that are then replaced with the relevant text. The following gives an example of a template file content and its result when used in a survey page:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><center><font face='verdana' color='red'>{SURVEYNAME}</font><br /><br />
<br />
<font face='verdana' color='blue'><u>{SURVEYDESCRIPTION}</u></center></syntaxhighlight><br />
<br />
One gets a result that looks like:<br />
<br />
<div class="simplebox"><center>'''<span style='color:red'>My New Survey</span>'''</center><br />
<br />
<center><u><span style='color:#0000ff'>This is a survey written by me to find out what sort of chocolate people like.</span></u></center></div><br />
<br />
Templates, being HTML code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most reference a common cascading style sheets (CSS) file that defines the font style, color, size, background and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe once how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Template file. Finally, special Keywords in curly braces are replaced with text defined in the Survey for each of its corresponding language translations (for example, the Survey Title or Question Text for each language defined).<br />
<br />
If you create a new custom template, please consider contributing it back to the LimeSurvey community, and make it available to others. With your help, we can grow our repository of templates, surveys, and other ad-ons, to make LimeSurvey even better! See the shared [http://www.limesurvey.org/component/remository/lang,en-gb/ Template Repository]<br />
<br />
=Creating a new Template=<br />
<br />
To be able to create a new template (or edit an existing template), you need Template Editing user permission in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.<br />
<br />
<div class="simplebox">'''Note of Warning:''' As template changes can affect all surveys in an installation, changes should be limited to those skilled in understanding general concepts in the code base. Templates are an advanced feature that can take some experimentation to get correct if you are not familiar with HTML code methods.</div><br />
<br />
The preferred way to create a new template is through the Template Editor (see below) via the web Admin interface. Some people may like to work directly with template files so that they can use their favorite text editor instead of the web interface. In this case, still use the Template Editor to first create your new template. This will create a new base template with all the files you need in the LimeSurvey_web_root/upload/templates/your_new_template directory. From there you can use your text editor to manually adjust the template files.<br />
<br />
<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these template files will be owned by the group and user who the web server is running as (may be "www" for some systems). So make sure you have access to edit these files, and when you save them make sure they don't change ownership, so you can still use the web Template Editing interface if needed</div><br />
<br />
Template files may seem complex to understand at first. You have to likely understand HTML code, possibly Styles and Style Sheets, and have access to the underlying LimeSurvey installation files if the template files and directories are not editable. Copy an existing template to a new directory to play around with the content. This may help make the concept clearer.<br />
<br />
A number of the 'public' elements of LimeSurvey can be adjusted by a series of templates. This section provides a very brief explanation of these templates, however more detailed information - especially regarding the editing/creation of new templates is available under [[Templates + Styles]].<br />
<br />
=The LimeSurvey Template Editor=<br />
<br />
To ease the understanding and quick update of a Template, LimeSurvey provides a '''Template Editor''' in the main '''administrative''' toolbar of the application. This Template Editor is only available to users given the privilege in the User Security settings. A template effects all surveys and can render a survey inoperable if not constructed properly. So Template editing is thought best restricted to a very limited, knowledgeable set of users. Having permission to enter the Template Editor is not enough though.<br />
<br />
The LimeSurvey Template Editor allows you to edit the contents of your templates online. Start the Template Editor by clicking on the "Template Editor" icon [[File:templates.png]] in the LimeSurvey Administration toolbar (Templates). The main screen is similar to the LimeSurvey Survey Administration screen. It allows you to select the template to edit/view. Once this has been selected you can then select from one of the different public survey pages. You are then presented with a list of the template files that make up that particular page.<br />
<br />
==The Template Menu==<br />
*'''Edit Icon:''' The "edit" icon indicates whether or not the template is editable. A blurred out icon indicates that the template is read only; a clickable icon indicates you may make modifications. To change the icon from blurred to clear, you have to modify the template's permissions.<br />
*'''Rename this template:''' Allows you to change the name of the template. Generally used after copying an existing template or importing a template by manipulating the underlying directories.<br />
*'''Export Template:''' Allows you to export the current template to a .zip-File.<br />
*'''Copy Template:''' Allows you to make a new template by copying the current one.<br />
<br />
The "Screen" drop-down list on the right allows you to choose which particular survey page you are currently looking at.<br />
<br />
==Import/Export/Copy a Template==<br />
<br />
When you '''export '''a template, this will create a zip-file archive with all the files your template consists of (.pstpl files, images, css files, ...). You can simply '''import '''the exported zip-file at other Limesurvey systems by using the import feature or you can manually copy the archive to another installation and extract it into the corresponding template directory there. If you copy the template in the same installation, you will need to rename the folder to create another named copy of that template.<br />
<br />
If the file and directory permissions are open for the LimeSurvey application to write, then you can use the programs '''copy '''and rename features to make a local copy of a template.<br />
<br />
==Page Structure / Template Use==<br />
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, navigator.pstpl, endpage.pstpl<br />
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl, navigator.pstpl, endpage.pstpl<br />
*'''The Submit Page:''' startpage.pstpl, survey.pstpl, submit.pstpl, (privacy.pstpl), navigator.pstpl, endpage.pstpl<br />
*'''The Final Page:''' startpage.pstpl, completed.pstpl, endpage.pstpl<br />
<br />
==Template Files==<br />
<br />
The following template files are used to produce your public survey and must exist in any new template folder you create:<br />
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag, even though many browsers do not require strict adherence to the W3 HTML stanards, the LimeSurvey script needs to find a <body> tag, to run certain javascript elements. It is not expected that many 'keywords' will be used in the startpage.pstpl file, however you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file, so you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.<br />
*'''survey.pstpl:''' This template is the second used on most pages, and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (ie: don't leave a table open here because there is nowhere else to close it)<br />
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.<br />
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.<br />
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. It is separate to the startgroup.pstpl file because in a "question by question" survey it will be displayed on its own unique page in between groups, whereas in a "group by group" or "all in one" survey it provides a header to the subsequent questions. groupdescription.pstpl does not have a corresponding 'closing' template file, so all tags should be closed.<br />
*'''question.pstpl:''' This file contains the question, answer and help text sections of your survey, and in the "group by group" and "all in one" surveys this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.<br />
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LS1.87)'''. All keywords from this template are now available directly in question.pstpl. NOTE: templates using question_start.pstpl will still work at least for a couple more versions of LS 1.x<br />
*'''submit.pstpl (and privacy.pstpl):''' This page is the penultimate page for all types of survey (except the "all in one" type) where the participant is given an option to review questions before submitting their responses. It provides privacy information where a survey is anonymous, which it extracts from the '''privacy.pstpl''' file.<br />
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.<br />
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file<br />
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.<br />
*'''printanswers.pstpl:''' This file has the HTML wrapper for the print version of the survey.<br />
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl endgroup.pstpl but for the print version of the survey.<br />
*'''print_question.pstpl:''' This file is the same as question.pstpl but for the print version of the survey.<br />
*'''print_survey.pstpl:''' This file is the same as survey.pstpl but for the print version of the survey.<br />
<br />
== CSS and Javascript==<br />
<br />
Two files are allways used for template : template.css for css and template.js for javascript.<br />
*'''{TEMPLATECSS}:''' Add lines for default css, template.css and template-rtl.css for rtl language.<br />
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js and all js files needed for LimeSurvey.<br />
<br />
=== Replacing default css or javascript===<br />
<br />
Some question use specific files for javascript or css. You can use your own files. All files used in your survey included in ./scripts or in .//styles-public can be replaced, just put a file with the same name in your template.<br />
<br />
==Other Template Files==<br />
<br />
The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''' and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.<br />
<br />
==Standard Pages==<br />
<br />
There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the survey's settings. The table below indicates which template files are used in constructing each of these pages.<br />
<br />
{|<br />
| '''Survey Pages:'''<br/>'''Template Files'''||Survey<br/>List||Welcome||Question||Completed||Clear All||Register||Load||Save||Print<br/>Answers||Print<br/>Survey<br />
|-<br />
|SurveyList|| [[File:check.gif]]|| || || || || || || || ||<br />
|-<br />
|Welcome|| || [[File:check.gif]]|| || || || || || || ||<br />
|-<br />
|Privacy|| || [[File:check.gif]]|| || || || || || || ||<br />
|-<br />
|Navigator|| || [[File:check.gif]]|| [[File:check.gif]]|| || || || || || ||<br />
|-<br />
|Survey|| || || [[File:check.gif]]|| || || [[File:check.gif]]|| || || ||<br />
|-<br />
|StartGroup|| || || [[File:check.gif]]|| || || || || || ||<br />
|-<br />
|GroupDescription|| || || [[File:check.gif]]|| || || || || || ||<br />
|-<br />
|Question<span style='color:red'>'''*'''</span>|| || || [[File:check.gif]]|| || || || || || ||<br />
|-<br />
|EndGroup|| || || [[File:check.gif]]|| || || || || || ||<br />
|-<br />
|Assessment|| || || || [[File:check.gif]]|| || || || || ||<br />
|-<br />
|Completed|| || || || [[File:check.gif]]|| || || || || ||<br />
|-<br />
|ClearAll|| || || || || [[File:check.gif]]|| || || || ||<br />
|-<br />
|Register|| || || || || || [[File:check.gif]]|| || || ||<br />
|-<br />
|Load|| || || || || || || [[File:check.gif]]|| || ||<br />
|-<br />
|Save|| || || || || || || || [[File:check.gif]]|| ||<br />
|-<br />
|PrintAnswers|| || || || || || || || || [[File:check.gif]]||<br />
|-<br />
|Print Survey || || || || || || || || || || [[File:check.gif]]<br />
|-<br />
|Print Group || || || || || || || || || || [[File:check.gif]]<br />
|-<br />
|Print Question || || || || || || || || || || [[File:check.gif]]<br />
|-<br />
|StartPage<br/>EndPage<br/>Template.css|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| [[File:check.gif]]|| <br />
|}<br />
<br />
<span style='color:red'>'''*'''</span>NOTE: In versions 1.90 and up this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight><br />
<br />
==The File Control Section==<br />
<br />
In the "file control" window on the left, you can click on one of the template files that is used to compile the page. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.<br />
<br />
The "Other Files" window shows a list of all other files in the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''. Note: Instead of a link directly to each picture in your template you can use the field string {TEMPLATEURL}. So instead of:<br />
<br />
<syntaxhighlight lang="php" enclose="div">img src='/limesurvey/templates/yourtemplate/mypicture.jpg'</syntaxhighlight> You can use:<br />
<br />
<syntaxhighlight lang="php" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight><br />
<br />
A "sample" of the template page you are editing will be visible at the bottom of the screen. There is no way to to delete a template from the template editor. This must be done by accessing the underlying directory and deleting the file there.<br />
<br />
<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the Template Editor and should never be changed. If you want to modify them, create a copy first and modify the copy.</div><br />
<br />
==Location of template files==<br />
<br />
LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the /templates directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the /upload/templates directory.<br />
<br />
To create a new template, use the according icon in the template editor.<br />
<br />
There should ALWAYS be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. The "default" directory comes with the package.<br />
<br />
You can use any image files that you upload into the template management area with syntax like this:<br />
<br />
<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight><br />
<br />
=Styling questions with CSS=<br />
<br />
Styling of questions in CSS has become much easier. Each question type now has a unique class. Mandatory question's also have an additional mandatory class. For example, for a non-mandatory question:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><div id="question5" class="gender"><br />
<br />
...<br />
<br />
</div></syntaxhighlight><br />
<br />
and if the question is mandatory<br />
<br />
<syntaxhighlight lang="php" enclose="div"><div id="question5" class="gender mandatory"><br />
<br />
...<br />
<br />
</div></syntaxhighlight><br />
<br />
and if the question is mandatory but the user didn't answer it or if there is validation on a question<br />
<br />
<syntaxhighlight lang="php" enclose="div"><div id="question5" class="gender mandatory input-error"><br />
<br />
...<br />
<br />
</div></syntaxhighlight><br />
<br />
and if the question has validation applied but the user hasn't answered correctly<br />
<br />
<syntaxhighlight lang="php" enclose="div"><div id="question6" class="text-short input-error"><br />
<br />
...<br />
<br />
</div></syntaxhighlight><br />
<br />
==The full list of question classes==<br />
<br />
{|<br />
|'''Question Type'''||'''Question Class'''||'''Question ID'''<br />
|-<br />
|5 point choice||.choice-5-pt-radio||5<br />
|-<br />
|Array (10 point choice)||.array-10-pt||B<br />
|-<br />
|Array (5 point choice)||.array-5-pt||A<br />
|-<br />
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1<br />
|-<br />
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E<br />
|-<br />
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:<br />
|-<br />
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;<br />
|-<br />
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C<br />
|-<br />
|Array (flexible labels)||.array-flexible-row ||F<br />
|-<br />
|Array (flexible labels) by column||.array-flexible-column||H<br />
|-<br />
|Boilerplate question||.boilerplate||X<br />
|-<br />
|Date||.date||D<br />
|-<br />
|Gender||.gender||G<br />
|-<br />
|Huge free text||.text-huge||U<br />
|-<br />
|Language switch||.language||I<br />
|-<br />
|List (dropdown)||.list-dropdown||!<br />
|-<br />
|List (flexible labels) (dropdown)||.list-dropdown-flexible||W<br />
|-<br />
|List (flexible labels) (radio)||.list-radio-flexible||Z<br />
|-<br />
|List (radio)||.list-radio||L<br />
|-<br />
|List with comment||.list-with-comment||O<br />
|-<br />
|Long free text||.text-long||T<br />
|-<br />
|Multiple numerical input||.numeric-multi||K<br />
|-<br />
|Multiple options||.multiple-opt||M<br />
|-<br />
|Multiple options with comments||.multiple-opt-comments||P<br />
|-<br />
|Multiple short text||.multiple-short-txt||Q<br />
|-<br />
|Numerical input||.numeric||N<br />
|-<br />
|Ranking||.ranking||R<br />
|-<br />
|Short free text||.text-short||S<br />
|-<br />
|Yes/No||.yes-no||Y<br />
|-<br />
|<br />
|}<br />
<br />
==The full list of validation classes==<br />
<br />
<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div><br />
<br />
These apply to the help and/or validation tip messages so that each type can be individually styled.<br />
<br />
The .hide-tip option and .input-error options, by default, interact so that you can have validation tips start hidden, but appear when there validation errors, and disappear again when those errors are rectified.<br />
<br />
All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed, and are color-coded to indicate whether the answers pass the validation criteria.<br />
<br />
Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been med; then re-display the page using a harsher color if the person submits the page with lingering validation errors.<br />
<br />
{|<br />
|'''Purpose'''||'''CSS Class'''||'''Description'''<br />
|-<br />
|Mandatory||.mandatory||the question is mandatory<br />
|-<br />
|User input error||.input-error||the question had at least one validation error<br />
|-<br />
|Hide Tip||.hide-tip||added if you use the hide_tip option<br />
|-<br />
|Num answers||.em_num_answers||for for min_answers and max_answers<br />
|-<br />
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max<br />
|-<br />
|Sum range||.em_sum_range||for min/max/equals_num_value<br />
|-<br />
|Regex validation||.em_regex_validation||for regular-expression validation of the question<br />
|-<br />
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option<br />
|-<br />
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option<br />
|-<br />
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.<br />
|-<br />
|<br />
|}<br />
<br />
==Importing styles into your custom template==<br />
<br />
The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* <strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike>----<br />
<br />
START: Question styles <strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike><strike>-</strike> */</syntaxhighlight><br />
<br />
If you're styling your own custom template, You should be able to copy everything after the above from templates/default/template.css (for tables based layouts) or /templates/limespired/template.css (for CSS based layouts) into your own style sheet without any impact on your other styles.<br />
<br />
==Internet Explorer conditional style sheets==<br />
<br />
Because of the marked discrepancies in rendering between IE6, IE7 and most other browsers, there are special IE conditional style sheets included for each template.<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<br />
<br />
</syntaxhighlight>You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either /templates/default/ or /templates/limespired for Tables base layout and CSS based layout respectively.<br />
<br />
<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div><br />
<br />
===Alternative solution for Internet explorer===<br />
<br />
You can put conditional class for body in startpage.pstpl, and use this class in your template.css<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT}"></syntaxhighlight><br />
<br />
And in template.css use<br />
<br />
<syntaxhighlight lang="php" enclose="div">.ie6{/*specific for internet explorer */}<br />
<br />
.ie{/*specific for all internet explorer */}</syntaxhighlight><br />
<br />
You can see this alternative in citronade template.<br />
<br />
== Right-to-Left (RTL) Languages and justify==<br />
<br />
The text editor within LimeSurvey is able to format RTL Text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.<br />
<br />
==Keywords==<br />
<br />
Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}<br />
<br />
The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)<br />
<br />
{|<br />
|'''::KEYWORD::'''|| '''TEMPLATE FILES::''' || '''::DESCRIPTION::'''<br />
|-<br />
|{SURVEYNAME}||All Files||The survey title<br />
|-<br />
|{SURVEYDESCRIPTION}||All Files||The survey description<br />
|-<br />
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text<br />
|-<br />
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed<br />
|-<br />
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name<br />
|-<br />
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description<br />
|-<br />
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)<br />
|-<br />
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".<br />
|-<br />
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled<br />
|-<br />
|{QUESTION}||Question.pstpl||('''Has been superseeded but the {QUESTION_...} keywords as of LS1.87''') Displays the current question text (The format of {QUESTION} can customised by editing 'question_start.pstpl') Use the following: {QUESTION_TEXT}, {QUESTION_MANDATORY}, {QUESTION_HELP}, {QUESTION_MAN_MESSAGE}, {QUESTION_VALID_MESSAGE} and {QUESTION_INPUT_ERROR_CLASS} and appropriate wrapping HTML instead of {QUESTION})<br />
|-<br />
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question<br />
|-<br />
|{SGQ}||question.pstpl, question text||Can be used in the question text itself, to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)<br />
|-<br />
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question<br />
|-<br />
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)<br />
|-<br />
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code<br />
|-<br />
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)<br />
|-<br />
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question<br />
|-<br />
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question<br />
|-<br />
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error<br />
|-<br />
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions<br />
|-<br />
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question<br />
|-<br />
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question<br />
|-<br />
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)<br />
|-<br />
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question<br />
|-<br />
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.<br />
|-<br />
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question<br />
|-<br />
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.<br />
|-<br />
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)<br />
|-<br />
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link<br />
|-<br />
|{SUBMITBUTTON}||submit.pstpl||Displays the final submit button<br />
|-<br />
|{COMPLETED}||completed.pstpl||Displays the 'completed' messagem for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.<br />
|-<br />
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'<br />
|-<br />
|{PRIVACY}||submit.pstpl||Displays privacy information when survey is anonymous<br />
|-<br />
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [http://docs.limesurvey.org/tiki-index.php?page=LimeSurvey+1.x+Translating+LimeSurvey The text can be edited/translated] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.<br />
|-<br />
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)<br />
|-<br />
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button<br />
|-<br />
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"<br />
|-<br />
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table<br />
|-<br />
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***<br />
|-<br />
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***<br />
|-<br />
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***<br />
|-<br />
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***<br />
|-<br />
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files<br />
|-<br />
|{RESTART}||clearall.pstpl||URL to restart the survey<br />
|-<br />
|{CLOSEWINDOW}||All Files (Preferably in navigator.pstpl)||URL to close current window<br />
|-<br />
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")<br />
|-<br />
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files<br />
|-<br />
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files<br />
|-<br />
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.<br />
|-<br />
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.<br />
|-<br />
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.<br />
|}<br />
<br />
==Input/Buttons==<br />
<br />
Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file, and have some control over the appearance of form buttons and inputs. These class names are as follows:<br />
*'''submit''' (Submit Buttons)<br />
*'''text''' (Text Inputs - for short free text, date and numerical type)<br />
*'''answertext''' (Text of answers)<br />
*'''radio''' (Radio Buttons)<br />
*'''checkbox''' (Check Boxes)<br />
*'''select''' (Select / List Boxes)<br />
*'''textarea''' (Large text inputs - for long free text)<br />
*'''clearall''' (The "Exit and Clear Survey" link)<br />
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes (these are set by relevant section above) but does allow changing of background colour, text colour and size etc for the rest of the ranking question)<br />
*'''graph''' (The "percentage completed" graph table)<br />
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text<br />
*'''question''' (General settings for any question that is displayed within a table. Generally you should use this to make sure that their font size and colour is the same as you have used elsewhere as a default)<br />
*'''mandatory''' (Mandatory questions)<br />
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)<br />
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background colour for these question types. '''Array1''' is also used for the column headings in these question types)<br />
*'''errormandatory''' (Sets the colour and style of the "This question is mandatory" error message)<br />
*'''warningjs''' (Sets the colour and style of the warning message displayed if the participant's browser has javascript disabled)<br />
<br />
There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):<br />
*'''surveycontact''' (The contact message shown on the start page)<br />
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)<br />
<br />
An example of using these classes with style sheets can be found in the "bubblegum" template that comes with the LimeSurvey application.<br />
<br />
Because you can edit all the HTML aspects, there's no reason to surround your templates with a <div class='new_name'> and then define a css for that new_name class.<br />
<br />
==Styling the progress bar==<br />
<br />
'''Before version 1.87:'''<br />
<br />
The chart.jpg file is a simple one pixel image file which is used to create the progress bar image in the 'PERCENTCOMPLETE' table. If the file does not exist, LimeSurvey will use the default 'maroon' coloured image in the public directory. If you want to create a bar to match your own colour scheme, then you should save the color in this file. Remember it should be a '''JPEG''' file, 1 pixel x 1 pixel, in the colour desired.<br />
<br />
'''Version 1.87 and newer:'''<br />
<br />
The progress bar appearance can be modified with CSS.<br />
<br />
To change the background colour of the bar, add something like the following to the end of your template.css file.<br />
<br />
<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {<br />
<br />
background-color: #3300FF;<br />
<br />
}</syntaxhighlight><br />
<br />
To change the border colour of the bar, add something like the following to the end of your template.css file.<br />
<br />
<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,<br />
#progress-wrapper .ui-widget-header {<br />
<br />
border: 1px solid #FF0000;<br />
<br />
}</syntaxhighlight><br />
<br />
==Advanced Features Available to Developers==<br />
<br />
Starting with version 0.99, LimeSurvey has integrated some user-made patches that allow for some special changes. These very advanced features generally require changes to the underlying code base of LimeSurvey and should be done carefully so as not to introduce security holes.<br />
<br />
===Basic CMS Integration support===<br />
<br />
To be able to integrate LimeSurvey into another CMS, use the following options in '''config.php''':<br />
<br />
// Set $embedded to true and specify the header and footer functions if the survey is to be displayed embedded in a CMS<br />
<br />
<nowiki><br />
<br />
$embedded = false;<br />
<br />
$embedded_inc = ""; // path to the header to include if any<br />
<br />
$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog<br />
<br />
$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog<br />
<br />
</nowiki><br />
<br />
Set '''$embedded = true;''' to enable CMS-embedding. By using the '''$embedded_inc''' variable one can include their own '''.php''' files. By setting '''$embedded_headerfunc''' or '''$embedded_footerfunc''', one can call functions from within included files that output the relevant headers or footers instead of LimeSurveys default ones.<br />
<br />
===Support for your own Javascript functions===<br />
<br />
Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling each. This way a template author can create their own '''template_onload()''' function in the HEAD that replaces the default one.<br />
<br />
'''Version 1.87 and newer:'''<br />
*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.<br />
*Enter your script in the source of a question or group description.<br />
*There are more details in the [http://docs.limesurvey.org/tiki-index.php?page=Workarounds%3A+Manipulating+a+survey+at+runtime+using+Javascript&structure;=English+Instructions+for+LimeSurvey#How_to_use_Script_eg._JavaScript_etc._in_LimeSurvey_ workaround section].<br />
<br />
=Videos on Templates=<br />
<br />
These videos will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, customizing survey description page, and completed page.<br />
<br />
Part I<br />
<br />
{YOUTUBE(movie="nLsfxMjRXyk?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
Part II<br />
<br />
{YOUTUBE(movie="yrAXStFH34Q?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
Part III<br />
<br />
{YOUTUBE(movie="TYlJXHgt8R0?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
Part IV<br />
<br />
{YOUTUBE(movie="Rml0gqeErVc?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
Part V<br />
<br />
{YOUTUBE(movie="LX24Ix1ylmY?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
Part VI<br />
<br />
{YOUTUBE(movie="-202CqQcW8g?fs=1&amp;hl=en_US&amp;rel=0",width="640",height="385")}{YOUTUBE}<br />
<br />
=Tips & Tricks=<br />
<br />
==Some language specific element==<br />
<br />
If you want to have some langage specific sentence in a survey, for example an help at end of each page, you can add in a .pstl file a sentence and hidding it for other langage. ANd hidding it in the template.css, we can use psuedo selector :lang, but for best compatibility, we use some class.<br />
<br />
Example for a help sentence at bottom of the page, in french an english, put this on endpage.pstpl:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div><br />
<br />
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight><br />
<br />
ans in template.css<br />
<br />
<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}<br />
<br />
.lang-en .fr{display:none}</syntaxhighlight><br />
<br />
You can use it to for other sentence in your question before 1.92 ( in 1.92, there are better solutions).<br />
<br />
==Change the layout of the survey page==<br />
<br />
When editing a template this template can be assigned to a single survey while the survey list page, which is shown at www.yourdomain.org/limesurveyinstallfolder, lists all your surveys.<br />
<br />
To use your current template for this page you have change the according setting at the Global Settings screen; at older versions this change can be done by editing the $defaulttemplate setting at the config file: Copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to $defaulttemplate = 'yourtemplatename';<br />
<br />
==Import/Export of templates: Mac users==<br />
<br />
Mac users, please note: Mac OSX default archive utility may have problems with zip folders "generated on the fly".<br />
<br />
a work around is to unix'es unzip from the command line:<br />
<br />
$ unzip template.zip -d template<br />
<br />
Archive: template.zip<br />
<br />
inflating: template/startpage<br />
<br />
inflating: ...<br />
<br />
or scripts in their mac-compiled counterparts:<br />
<br />
http://homepage.mac.com/roger_jolly/software/<br />
<br />
==Changing your templates traffic light from red to green==<br />
<br />
If you haven't already, set the admin directory to read/write/execute (777). The files within it, however, may be set to read/execute only (chmod 755).<br />
<br />
GO to file directory ie file manager, find templates directory.<br />
<br />
1 change permission on eg"vallendar" (or any template of your choice) directory to read 777<br />
<br />
2 voila! the red traffic light on "vallendar" is now green.<br />
<br />
3 NOTE: to restrict access for safety, when finished editing template files, change all templates files back to what they were eg 644<br />
<br />
==Replacing the help icon==<br />
<br />
When a question help text is shown then an help.gif image is used from the default template folder.<br />
<br />
You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It then will be automatically used instead of the default help icon.<br />
<br />
==Replacing an existing logo==<br />
<br />
'''Note''': Before uploading new logo delete previous one.<br />
<br />
1. To edit logo go to &bdquo;<u>template.css</u>&rdquo;, you can find it here (see in screen):<br />
<br />
[[File:1.PNG]]<br />
<br />
2. Find and Click Search button, to find place where is logo style text.<br />
<br />
[[File:2.PNG]]<br />
<br />
3. Find in search <u>#logo</u> (It is logo design code)<br />
<br />
[[File:3.PNG]]<br />
<br />
4. Edit style file<br />
<br />
You will see something like this code:<br />
<br />
[[File:4.PNG]] <br />
<br />
If you want change image just replace logo.gif to antoher image link. Like: (<u>logo.png</u>, <u>logo.jpg</u>, <u>logo.swf</u>).<br />
<br />
If you want change image size just change, width and height (in pixels) like:<br />
<br />
<syntaxhighlight lang="php" enclose="div">Width:100px; Height:100px;</syntaxhighlight><br />
<br />
==Adding your own logo==<br />
<br />
1. Find and Open &bdquo;<u>startpage.pstpl</u>&rdquo; template file.<br />
<br />
[[File:5.PNG]] <br />
<br />
2. Write in &bdquo;<u>startpage.pstpl</u>&rdquo; this line:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><img id=&rdquo;page_logo&rdquo; src=&rdquo;{TEMPLATEURL}logo.png&rdquo;><br></syntaxhighlight> After <syntaxhighlight lang="php" enclose="div"><body ... ></syntaxhighlight> tag<br />
<br />
[[File:6.PNG]] <br />
<br />
3. To add logo go to &bdquo;<u>template.css</u>&rdquo;, you can find it here (see in screen):<br />
<br />
[[File:1.PNG]]<br />
<br />
3.1 Go to end of &bdquo;<u>template.css</u>&rdquo; style file.<br />
<br />
3.2 Write in end:<br />
<br />
'''If you want in left side:'''<br />
<br />
<syntaxhighlight lang="php" enclose="div">#page_logo{<br />
<br />
float:left;<br />
<br />
}</syntaxhighlight><br />
<br />
'''If you want in right side:'''<br />
<br />
<syntaxhighlight lang="php" enclose="div">#page_logo{<br />
<br />
float:right;<br />
<br />
}</syntaxhighlight><br />
<br />
'''If you want in center:'''<br />
<br />
<syntaxhighlight lang="php" enclose="div">#page_logo{<br />
<br />
display: block;<br />
<br />
margin-left: auto;<br />
<br />
margin-right: auto;<br />
<br />
}</syntaxhighlight><br />
<br />
==Use the same template with different logos==<br />
<br />
If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}logoImage-{SID}.png"></syntaxhighlight><br />
<br />
==Remove the default help to all question (hide_tip)==<br />
<br />
There are 2 solution to remove the default help, like a [[Advanced question settings|#hide_tip|hide_tip attribute]] but for all question and survey.<br />
# you can remove the {QUESTIONHELP} and is container from the file question.pstl, but it can be a bad idea for screenreader.<br />
# for the default template and some other , add this at the end of tempate.css<br />
<br />
<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight><br />
<br />
== Display custom favicon==<br />
<br />
A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:<br />
#Create a favicon - google will find you lots of free favicon generators<br />
#Name your new favicon "favicon.ico" and place it in your template directory<br />
#Add the following code to your '''startpage.pstpl''' before the </head> tag<br />
<br />
<syntaxhighlight lang="php" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"><br />
<br />
<link rel="icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"></syntaxhighlight><br />
<br />
== Different appearance for survey-/question-pages==<br />
<br />
(''Version 1.91 and newer'')<br />
<br />
If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages) you can use '''.page-odd''' class in your css file to change the appearance of odd pages.<br />
<br />
example from default template of LimeSurvey 1.91+<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
.page-odd table.question-group {<br />
<br />
background-color: #D2F2D3;<br />
<br />
}</syntaxhighlight><br />
<br />
To '''not''' differentiate even and odd pages at the (default) template find all instances of ''.page-odd'' in template.css and remove those styles.<br />
<br />
==Create a vertical separator border for dual scale array==<br />
<br />
To create a vertical separator border for a dual scale array you can add the following lines to your '''template.css'''-file.<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
table.question thead td.header_separator,<br />
<br />
table.question tbody td.dual_scale_separator<br />
<br />
{<br />
<br />
border-right:solid 1px #00A8E1;<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
header_separator is used to adress the separator for the header "td" and "dual_scale_separator" is used to adress the separator column in the dual scale array.<br />
<br />
==Hide the survey contact message shown on the start page/survey list==<br />
<br />
To hide the "Please contact ..." meassage on the start page (with the survey list) you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
$('#surveycontact').hide(); //Hides the survey contact message<br />
<br />
</syntaxhighlight><br />
<br />
==Remove the survey contact message shown on error messages==<br />
<br />
If you want to remove the survey contact message from error messages it'll be trickier. You can add the following function call to the '''$(document).ready''' function in the '''template.css''' of your used design template:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
removeContactAdressFromMessage(); //Removes the survey contact message from error messages<br />
<br />
</syntaxhighlight><br />
<br />
and add the following function to your *template.js* file<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
function removeContactAdressFromMessage()<br />
<br />
{<br />
<br />
if ($('#tokenmessage').length > 0)<br />
<br />
{<br />
<br />
var oldMessage = $('#tokenmessage').html();<br />
<br />
var indexContact = oldMessage.indexOf('Bitte kontaktieren');<br />
<br />
var newMessage = oldMessage.substr(0, indexContact);<br />
<br />
$('#tokenmessage').html(newMessage);<br />
<br />
}<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
It will probably not work for an englisch survey and have to be extended when using for multilingual surveys. But it's an idea/tip how to solve this.<br />
<br />
==How to deal with multilingual question attributes (before version 2.0 at which those were added)==<br />
<br />
If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at Limesurvey 2.0). To work around this, paste in the field to change the label for "other"<br />
<br />
<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight><br />
<br />
At the template.css of your template (at /limesurvey/upload/templates/<yourtemplatename>/template.css) add:<br />
<br />
<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}<br />
<br />
html:lang(fr) .en{display:none}</syntaxhighlight></div>Adminhttps://www.limesurvey.org/manual/index.php?title=Central_participants_database_(User_panel)_Development&diff=3084Central participants database (User panel) Development2012-09-22T20:56:50Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
----<br />
<br />
=Database Schema=<br />
<br />
----<br />
<br />
==Central Storage==<br />
<br />
===lime_participants===<br />
<br />
The first table is the actual central table where all the participants&rsquo; entries are stored. The table is as follows<br />
<br />
{|<br />
|participant_id||first_name||last_name|| e_mail||blacklisted_global<br />
|-<br />
|4b3403665fea6||Carsten ||Schmitz||carsten.schmitz@example.com||N<br />
|-<br />
|4b1357665fea6||Jason||Cleeland||js@example.org||N<br />
|-<br />
|4dc14fa0db7f4||Thilabult||Lemer||thilabault.lemer@example.net||N<br />
|}<br />
<br />
{|<br />
|language|| owner_uid|| date_created||date_modified|| max_surveys<br />
|-<br />
|en|| 1|| 2007-11-04 01:00:01|| 2007-11-04 01:00:01||0<br />
|-<br />
|en|| 2|| 2007-11-04 01:00:01|| 2007-11-04 01:00:01||2<br />
|-<br />
|en|| 1|| 2007-11-04 01:00:01|| 2007-11-04 01:00:01||1<br />
|}<br />
<br />
The Fields in table are explained below:<br />
*participant_id : It is the primary key for the table and will be auto-generated.<br />
*first_name : It contains the first name of the participant.<br />
*last_name : It contains the last name of the participant.<br />
*e_mail : It contains the email id of participant.<br />
*language : It contains the language preference of the participant.<br />
*blacklisted_global : It is a field that will be updated if a participant hit a particular URL mentioned in the email sent to him. There will be two URL mentioned in the mail. One will allow the participant to blacklist himself globally from any survey from that server, or from a particular survey. When the user will blacklist himself from the server as a whole, he will be marked against the e-mail address in the above table , when it's survey specific, he will marked with the help of email and the survey_id in the tokens table. If for a particular participant, this field is set, the administrator would be not allowed to add that user to any of the survey's. If a new survey is set, then also administrator will not be allowed to add that particular participant. If the global setting for blacklisting is updated, then all the local tables will be updated accordingly.Once blocked the user will not be allowed to participate either. The user will have another set of URL's in case he/she wishes to unblock himself/herself.<br />
*owner_uid: It will contain the user id of the person who is adding the participant, this will be extracted based on who is logged in, in case the owner field is set to be editable then it can be changed.<br />
*date_created and date_modified are self-explanatory fields.<br />
*max_surveys:The max_locks field will contain a number which will indicate, the max number of surveys to which participant is to be locked for example if it contain 0, the participant is free to be added to any other survey, However if it values is 2, this means that the participant is locked to two surveys so after adding him to two surveys, he shouldn't be added to any third survey.<br />
<br />
The combination of email and owner_uid will be the composite key for this table.<br />
<br />
----<br />
<br />
==Locking Feature==<br />
<br />
In the lock feature there is one tables,lime_survey_info.The lime_participant_info table will contain the information regarding to which survey the participant is added.<br />
<br />
===lime_participant_links===<br />
<br />
The schema of the table is<br />
<br />
{|<br />
|participant_id||survey_id||token_id||date_created<br />
|-<br />
|4b3403665fea6||63273||1||2011-03-08 12:32<br />
|-<br />
|4b1357665fea6||76581||1||2011-03-08 12:32<br />
|}<br />
<br />
This table will be used for two purposes as far as I can see for now,<br />
<br />
1) It will give the clear cut info as to which survey a particular participant is added to.<br />
<br />
2) When a user will try to share a participant, but in the settings it is set that he can't be added to more than two surveys, then a SQL COUNT query will be run for that participant and if that number is equal to the max_locks field an error message will sprung up saying, these participants can't be added to the survey.<br />
<br />
----<br />
<br />
==Token Table==<br />
<br />
===lime_tokens_xxxxxx===<br />
<br />
{|<br />
|participant_id||token||token_id||e_mail_status ||sent||reminder_sent<br />
|-<br />
|4b3403665fea6||afir2ski6wrcyny||1||OK||2011-03-08 12:32||N<br />
|}<br />
<br />
{|<br />
|reminder_count||completed||uses_left||valid_from||valid_until||blacklisted ||att_id<br />
|-<br />
|0|| 2011-03-08 12:32||0||23.03.2011 00:00 ||26.03.2011 00:00|| N||2<br />
|}<br />
<br />
Some minor changes have been done to this table to make it work with the other Central Database System.One of then is that the user information will not be stored in this table, but in the Central Table and will be linked using the participant_id.Also, a blacklisted field is also added that will contain the survey and participant specific blacklist settings.<br />
<br />
The Fields in table are explained below:<br />
*participant_id : This is the key for linking participants in this system.<br />
*token,token_id,e_mail_status,sent,reminder_sent,reminder_count,completed,uses_left,valid_from,valid_until: Same as in the previous system.<br />
*blacklisted: This is the survey specific blacklist field which will contain as to whether the participant has chosen to blacklist himself from this survey or not.<br />
*att_id : This field will contain a id of the attribute that is added into the system. A combination of att_id and participant_id will extract information from lime_participant_attributes table<br />
<br />
----<br />
<br />
==Attribute Control==<br />
<br />
This feature will be using three tables namely :<br />
<br />
1) lime_participant_attributes - Store the actual attribute information<br />
<br />
2) lime_participant_attribute_info - Store the UI information related to the attribute<br />
<br />
3) lime_participant_attribute_values - Store the possible values of the attribute<br />
<br />
===lime_participant_attributes===<br />
<br />
This is the table that will hold the actual values<br />
<br />
{|<br />
| participant_id|| attribute_id|| value|| id<br />
|-<br />
|4b3403665fea6|| 1|| Male|| 1<br />
|-<br />
|4b1357665fea6|| 1|| Male|| 2<br />
|}<br />
<br />
The fields of the table are explained below<br />
* participant_id : Again this is the unique id for the participants.<br />
* attribute_id : Each attribute in the attribute control will have a unique id similar to participant_id and a combination of participant_id and attribute_id will tell give the value of the attribute.<br />
* value : This field contain the actual value of the attribute, in case of textbox, It will contain the value contained in the text box.<br />
<br />
===lime_participant_attribute_info===<br />
<br />
This is the table that will hold the UI related information for attribute control<br />
<br />
{|<br />
| attrbute_id|| attribute_name|| attribute_type|| visible<br />
|-<br />
|1|| sex|| DD|| 1<br />
|}<br />
*attribute_id : The unique id give to each additional attribute.<br />
*attribute_name : This is the label that will be shown in the UI created for additional attribute.<br />
*attribute_type : This field contains the type of UI that needs to be created for this particular attribute<br />
*visible : This field will tell whether that attribute is to be used for the current set of participants or not<br />
<br />
===lime_participant_attribute_values===<br />
<br />
This is the table that will hold all the possible values for the particular attribute. The scehma of this table is<br />
<br />
{|<br />
| attribute_id|| value_id|| p_value<br />
|-<br />
| 1|| 1|| male<br />
|-<br />
| 1|| 2|| male<br />
|-<br />
|2|| 1|| <br />
|}<br />
<br />
The above example will make it more clear, but keep in mind that in case of a text box and date-picker, this field will be empty because any value can be entered in the system. For multi-line text input we will use a different value_id for each text box, for example address.<br />
<br />
----<br />
<br />
==Relationship==<br />
<br />
The relationship between the tables explained above is shown below.<br />
<br />
[[File:Relationsv4.png]]}<br />
<br />
----<br />
<br />
=User Interface=<br />
<br />
In the user interface aspect, the entire participant control that we used to have` in the token menu will now be available globally, but the token will be generated in the survey specific table only. The link for adding participants to the limesurvey installation will be on the front screen.<br />
<br />
[[File:Screen_shot_1.png]]<br />
<br />
When clicked on the Add Participants the following screen will come up<br />
<br />
----<br />
<br />
==Add Participant==<br />
<br />
[[File:Screen_shot_2.jpg]]<br />
<br />
Explanation of the above screenshot is given below:<br />
*ID : This is the autogenerated ID for each participant.<br />
*First Name, Last Name, Email, Language : These fields are self-explanatory.<br />
*Blacklisted: This is the local blacklisted field I explained earlier.<br />
*Locked_with_survey : This is the field that will not allow the participant to be added to any other survey. The "add" link will allow the user to add more than one survey to be locked to. It will open a modal-dialog box. The unlocking will be possible only at the survey level, i.e. the participant could only be unlocked if the user has the access to that particular survey to which the participant is locked.<br />
*Owner: This will be a fixed field by default that will contain the owner&rsquo;s id of the owner who is adding that particular participant to the central database. However this field will only be editable if set in the user control options<br />
*Max Surveys: This field will tell set the number of surveys a particular participant can be added to, for example is the user set it to 0, then the participant can be added to as many as surveys the user wants.If it it set 2 it can be added to the maximum two surveys.<br />
*Sex: This is the additional attribute we set under attribute_control.<br />
<br />
----<br />
<br />
==Import from CSV/LDAP==<br />
<br />
[[File:Screen_shot_3.jpg]]<br />
<br />
The CSV file upload feature is similar to what we used to do under tokens, however with some differences, the differences are mentioned below:<br />
*The language is no longer an optional field, but under the mandatory fields.<br />
*Owner is the fields have the id of the user that is currently logged in and the participants will be added under this field. This field will only be editable if the corresponding option is set in user control.<br />
*Optional attributes are the survey specific fields, and will be added to the survey specified in the above field, along with the participants, this option will be enabled only if the participants are added to the survey table automatically based on the id they are adding.<br />
*locked_with_survey field will have another option, besides the survey. It will be "free" that will allow the participant to be added to any survey. This will be the default value.<br />
*Max Surveys: This field will tell set the number of surveys a particular participant can be added to, for example is the user set it to 0, then the participant can be added to as many as surveys the user wants.If it it set 2 it can be added to the maximum two surveys.<br />
*The LDAP import will work in the same way, and with the same options, I mean the locked to survey, group_id and optional fields.<br />
<br />
----<br />
<br />
==Display Participants==<br />
<br />
[[File:Screen_shot_4.png]]<br />
<br />
Again this screen is only for editing/deleting the participant entries. It is global, and hence nothing survey specific will be found here. If the user clicks on the edit button, then the screen similar to add participant screen will show up, showing the details of the participant, which can be edited there.<br />
<br />
----<br />
<br />
==Blacklist Control==<br />
<br />
[[File:Screen_shot_5.png]]<br />
<br />
All the settings under this page will be stored under the settings_global table. Each of setting is<br />
<br />
explained below<br />
*The first option if set, will mark participant blacklist for all the survey's that are present in the system currently.<br />
*The second option will mark the participant as blacklist for any new survey that is added to the system, if the global field is set.<br />
*The third option will not allow the participant to be even added to the survey if the global blacklist field is set.<br />
*The fourth option will not show the blacklisted participant in the display participant.<br />
*In the fifth option, if the participant blacklist himself/herself globally , he will be deleted from the database .<br />
*The sixth option will decide that whether the URL to blacklist the user will be sent in the invitation.<br />
<br />
----<br />
<br />
==User Control==<br />
<br />
[[File:Screen_shot_6.png]]<br />
<br />
This is the user control, by user I mean the administrator. The three options under this field will be stored in the global table. The options are explained below.<br />
*The first field if enabled or disable this feature completely.<br />
*The second option if set to yes, when the user uploads a csv file or adding a new participant indivisually. *The new participant will be added to the survey of which the user is the owner.<br />
*The third option will set if the owner field is editable or not.<br />
<br />
----<br />
<br />
==Attribute Control==<br />
<br />
[[File:Screen_shot_7.png]]<br />
<br />
This is a new feature I am planning to implement, in this feature I will be allowing the administrator to add a new attribute with a proper UI, rather than just a textbox. The value related to this feature will be stored in attribute_info_table. These are the UI components that I am planning to add for additional attribute<br />
*Drop Down<br />
*Check Box<br />
*Radio<br />
*jQuery DatePicker<br />
*Text Box<br />
<br />
In case of Drop Down,Check Box, Radio the "Add More" will allow the administrator to add more possible values. More advanced UI's can be added once the basic feature is ready.<br />
<br />
----<br />
<br />
==Add to survey==<br />
<br />
[[File:Screen_shot_8.png]]<br />
<br />
The UI is explained below:<br />
*The add group is basically the user id whose participants are to be added to the survey after going through three checks, locked or not, blacklisted or not,has permission or not.<br />
*Lock this group to the survey will lock this particular group to the survey, and will not allow any other<br />
*This field will give all the global attributes that are present with the participants and only relevant attributes are added to the survey<br />
*Allow blacklisted enteries to be added to the survey, if set, otherwise will not allow the blacklist enteries to be added. The main reason for this option is that in case the participant un-blacklist himself from the server, then he/she can participate in that survey. A automatic module can be made that will check for any participant that unblocked himself/herself and can be send invitation after that. I know this feature is not in the top of the list, but with many participants, will be worth it.<br />
<br />
----<br />
<br />
==Sign Up Control==<br />
<br />
[[File:Screen_shot_10.png]]<br />
<br />
This feature will allow the participant to just go on to the home screen, and sign him up. He will be verified against his e-mail. On the front screen there will be a sign up button, that when clicked will open a pop-up asking for the e-mail id. When entered an invitation mail will be sent to him asking for the rest of details. This way we will be sure that we have a valid participant. Once those details are entered, automatically a token will be generated for that user, and he will be redirected to the survey. Alternatively, if the administrator wants, he/she can disable this feature completey, or allow the participating to only participate only when he/she sends the invitation.<br />
<br />
The mock - up of the sign up control is as shown :<br />
<br />
[[File:Screen_shot_9.png]]<br />
<br />
This feature again will have a survey specific settings, which will be stored in the survey's table. The local settings if set ,will override the global settings.<br />
<br />
----<br />
<br />
=CodeIgniter Specific Details=<br />
<br />
Since we are porting LimeSurvey to codeIgniter and any new projects have to be developed according to the CodeIgniter framework. I will try and give the basic outline of the approach I will be following.<br />
<br />
==Controller==<br />
<br />
I as of now, will be adding a single controller for the whole project, and it will be named 'centralDB'. The functions under this controller will be of the form<br />
*addParticipant //Add Participant<br />
*import //Import CSV/LDAP<br />
*displayparticipant //Display the jqgrid<br />
*blcontrol //Blacklist Control<br />
*usercontrol //User Control<br />
*signupcontrol //signupcontrol<br />
<br />
All the controller's listed above will be used for only showing of the view, retrieving previous settings and storing new settings, and for import and displayparticipant functions, it will have major functionality as display participant will also be used for adding the participants to the database, and import will also be providing functionality and not just storing data.<br />
<br />
For Storing data we have functions such as<br />
*storeParticipant<br />
*storeBL<br />
*storeUser<br />
*storeSignup<br />
<br />
These methods will get the post variables from the view and storing it in the database using appropriate model. For displayParticipant and all, there will other functions such as addtosurvey.<br />
<br />
==Models==<br />
<br />
For the models we have<br />
*participants_model<br />
*attribute_model<br />
*token_model(older token table)<br />
*survey_links_model<br />
<br />
I think it's best to compress the three attributes table to one model. Rest of the models are pretty much simple, get and store records.This is the basic structure, what we need to concentrate on is what to do when we are joining tables and getting data from multiple tables.<br />
<br />
==View==<br />
<br />
For the view, I have decided to use the following views. These are<br />
*headercpdb<br />
*addparticipant_view<br />
*displayparticipant_view<br />
*importparticipant_view<br />
*blcontrol_view<br />
*usercontrol_view<br />
*signupcontrol_view<br />
<br />
----<br />
<br />
=Scenario Testing=<br />
<br />
The main purpose of making this proposal on the wiki page is to get the review of the community and suggest us some scenario's where you can see the system failing, so that we can make the changes before it's too late. If you see any shortcomings or any other feedback, please leave a comment and please try and answer these questions<br />
<br />
1) What do you want to do?<br />
<br />
2) Where will the system fail?<br />
<br />
3) Feature Suggestion?<br />
<br />
----<br />
<br />
=Action Plan :)=<br />
<br />
I received my date-sheet and I have exams from 24th of May to 11th of June, So I will be tweaking the action plan a bit in order to get things right :).<br />
<br />
Plan for June<br />
<br />
{|<br />
| Date||What to do ?<br />
|-<br />
|<span style='color:#999'>4-7th ||Talk to Shubham and Diogo during this period, as I think by that time they will be officially clear as to how they will be doing the porting, also, I will decide as to how I should go about it.If everything goes as planned I should be able to complete the add participant UI and the addition of data to the central database(without any features) along with the required validations.</span><br />
|-<br />
|12-15th ||Will add the user_id info(based on the logged in user), along with the datestamp in the central database. Also will be creating the owner control as mentioned in the original proposal along with the required functionality with it. Like automatically adding participants to the token table or not, or editable owner's field or not .<br />
|-<br />
|16-22th June ||Addition and attribute control<br />
|-<br />
|23-28th June ||CSV and LDAP upload with attribute support<br />
|-<br />
|29-10th July ||Add to token table and vice versa with editing logic and max surveys feature<br />
|-<br />
|11-15th July ||Sending email with blacklist control and the required logic<br />
|-<br />
|(12 July - 16 July) || (Midterm Break)<br />
|-<br />
|16-31th July ||sign up addition for participants along with the multiligual attribute support for token system<br />
|-<br />
|1-15th August ||features from if we have time list<br />
|-<br />
|16-22th August ||cleaning up code, video tutorials, testing and bug fixing<br />
|-<br />
|23-31th August ||worst case scenario or else party time ;) <br />
|}<br />
<br />
This is the action plan for the first milestone according to my original proposal, I will create the further action plan once I am done with this target. I will also be updating a weekly progress report here as well as a mail to the administration team of LimeSurvey, about the discussions we have during the week. The actual coding and progress report will start from 12th of June.<br />
<br />
----<br />
<br />
=Weekly Meetings=<br />
<br />
This will contain the logs of the weekly meetings we have:<br />
<br />
12th May 2011 -> http://docs.limesurvey.org/CPDB+Meeting+Log+12-05-2011<br />
<br />
Logs of meeting from the 19th of May will be available at the link below<br />
<br />
http://docs.limesurvey.org/CPDB+Meeting+Logs<br />
<br />
----<br />
<br />
=Scenarios=<br />
<br />
'''Use the following section to describe (as succinctly and clearly as possible) various different scenarios in which the Central Participants Database may be used. These scenarios can assist in clarifying User Interface issues and in initial database design'''<br />
<br />
==Privacy Scenarios==<br />
<br />
'''Single Company Installation'''<br />
<br />
In this scenario, LimeSurvey is installed by a single company for use by that company's staff. The right to view and access data relating to participants is shared by all staff and there is no need to fence data off between users.<br />
<br />
'''Multi User Installation'''<br />
<br />
LimeSurvey is installed at a University and different students or academics are using it to run surveys. Their ethics rules require that they keep their participant data to themselves, so other users cannot see it.<br />
<br />
==Survey Invitation Scenarios==<br />
<br />
'''Pre-existing List, Add it to Participants Database'''<br />
<br />
A user has a list of 500 people in their personal spreadsheet/database that they want to invite to participate in their survey. They create a survey, create a tokens table for it and then import the list (as per existing system). They want to make sure that their list is on the participants database for future use, and that they will be able to select these 500 people easily later on for future surveys.<br />
<br />
'''Pre-existing List, Don't add it to the participants database'''<br />
<br />
A user has a list of 300 people in their personal spreadsheet/database that they want to invite to participate in a survey. They create a survey, create a tokens table table for it and then import the list (as per exising system). They '''don't''' want their list to be added to the central participants database.<br />
<br />
'''Generate attributes for the participants database from answers to a survey'''<br />
<br />
A user has run a survey which asked whether participants live in a capitol city, a major regional centre or a minor regional centre. He wants to transfer the answers from that survey to the participants attributes in the central participants table. He also wants to transfer the annual income results from a question. He already has this information for some of the participants, but wants to update it with the information collected in this survey.<br />
<br />
'''Generate tokens from participants list based on earlier survey'''<br />
<br />
A user creates a new survey and wants to invite all the participants from an earlier survey to this new survey. He needs to be able to select all those who participated in the earlier survey, preferably just those who actually completed it. He might want to add those who didn't complete the earlier survey later on.<br />
<br />
'''Generate tokens from participants list based on their survey history'''<br />
<br />
A user creates a new survey and wants to invite only participants that have not taken part in a survey for the last 2 months. He might also want to exclude all that have participated in a survey with a similar topic in the last 6 months. User will need to view a search form where he can:<br />
<br />
1) Select search criteria from values such as "survey name", "survey completed date"<br />
<br />
2) Fill out matching values (ie: text string for survey name, dates for completion dates)<br />
<br />
3) Make the system search through all participants for matches to the search criteria<br />
<br />
4) See a list of all the matching participants (and the relevant information)<br />
<br />
5) Be able to do something with the resulting list (most likely copy them to a token table)<br />
<br />
'''Generate tokens from participants list based on other attribute'''<br />
<br />
A user creates a new survey and wants to invite all the participants he owns who have an income greater than $50,000 per annum and live in a capital city. User will need to be able to fill out a search form where he is able to:<br />
<br />
1) Select the attribute or attributes to use in his search<br />
<br />
2) Enter a search value/criteria for the search<br />
<br />
3) Make the system search through all the participants he has rights to view, for matches to his search criteria<br />
<br />
4) See a list of all the matching participants (and probably the relevant attribute data)<br />
<br />
5) Do stuff with the list (most likely, copy those participants to a token table for a survey)<br />
<br />
'''Taking care of the panel health'''<br />
<br />
The manager of the central participant list wants to check on the panel health. He wants to know if all participants have been invited to surveys in a certain period of time, how often they have been invited, the ration between invitation and participation, etc. Ideally there would be a system to attribute "points" to each survey and those points would be added to each participant (something like the total km count for a car). Ideally there would also be another field with points that can be reset (e.g. like the day km in a car). This would help to remunerate participants for their participations, without having to "pay" them for every single survey.<br />
<br />
After running the survey for 5 days he realises he needs more, so he then wants to add people who live in major regional centres.<br />
<br />
==Other scenario types?==</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_FAQ&diff=1658Installation FAQ2012-09-21T08:00:29Z<p>Admin: </p>
<hr />
<div><br />
Contents:{maketoc maxdepth=2}<br />
<br />
=During Installation=<br />
<br />
==How can I create a database and a user in mysql with command line access?==<br />
<br />
You have to enter the below commands in your mysql.<br />
<br />
create database '''<your_database_name>''';<br />
<br />
create user '''<your_database_username>''';<br />
<br />
create user '''<your_database_username>'''@localhost;<br />
<br />
set password for '''<your_database_username>''' = PASSWORD(''''<your_database_password>'''');<br />
<br />
set password for '''<your_database_username>'''@localhost = PASSWORD(''''<your_database_password>'''');<br />
<br />
grant all on '''<your_database_name>'''.* to ''''<your_database_username>'''';<br />
<br />
grant all on '''<your_database_name>'''.* to ''''<your_database_username>''''@'localhost';<br />
<br />
You have to replace '''<your_database_name>''', '''<your_database_username>''' and '''<your_database_password>''' in above commands with according values.<br />
<br />
==What if I can't create a database through a script?==<br />
<br />
Normally, the script creates a new database, and then the table structure. However if your server/ISP doesn't give you admin rights to create a new database in MySQL, you will need to contact your server administrator to create the necessary database (or create it yourself). They should create a blank database for you that gives you the appropriate access rights (ie: read/write/create). Enter the name of this database, and your user name and password in the config.php script, and run the /admin/install/index.php script. The script will then create the required tables in the database.<br />
<br />
==What is this mbstring (Multibyte String Functions) library?==<br />
<br />
The mbstring library is a PHP library to be able to convert char sets from one language to another. You need it if you want to run LimeSurvey. To check if it is already installed open the URL<br />
<br />
http://<your_server>/<your_limesurvey_directory>/admin/install/phpinfo.php<br />
<br />
from the web browser. A lot of information will be shown. Search for the string 'mbstring' under the '''Configuration''' section.<br />
<br />
If you find the mbstring section then all should be well and you can continue on with your LimeSurvey installation!<br />
<br />
'''If you don't find the mbstring section''' you might have a problem on your hands.<br />
<br />
There are three possible scenarios:<br />
*If it's your providers server: Ask your provider to activate that extension in PHP or how to activate it - if you have a good administration panel for your server you may be able to activate it yourself.<br />
*If it's your own '''Linux''' server: You may have to re-compile PHP and include the mbstring library. Ask the Linux experts how to do that. In most Linux versions today you can install it using your Linux packet manager.<br />
**If you are using a version of Linux that supports 'yum' (CentOS, RedHat, Fedora):<br />
### Use the terminal (as a super user) and type: '''yum install php-mbstring'''<br />
### Make sure to update /etc/php.ini to update and uncomment the various mbstring params<br />
### Make sure to restart apache after installing it: '''/etc/init.d/httpd restart'''<br />
*If it's your own '''Windows''' server: Search for php.ini on your system, open it with an editor and search for mbstring. Most probably the line that contains that string is commented out with a semicolon. Remove the semicolon, save and restart your web server.<br />
<br />
==When I am entering special chars (Chinese, Cyrillic, Greek, Arabic) into my survey, every character is shown as a question mark?==<br />
<br />
This happens if your database itself is not created to use an UTF-8 charset. This can happen when you have to create the database using a provider administration panel. You can fix this problem by executing the following SQL command on your database (using for example phpMyAdmin)<br />
<br />
ALTER DATABASE `<your_database_name>` DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;<br />
<br />
Replace <your_database_name> with the name of your database. '''You need to do this before installing LimeSurvey.'''<br />
<br />
==Blank page when accessing the Install page==<br />
<br />
The problem is not with the LimeSurvey installation but with the PHP installation.<br />
*Verify you have the MySQL PHP module (php-mysql) installed.<br />
*Verify your PHP install is loading the PHP.ini file your are modifying and not parsing other PHP.INI files on your system.<br />
*Verify the location and permissions of the following setting in your PHP.ini<br />
<br />
<syntaxhighlight lang="c" enclose="div">upload_tmp_dir="/temp"<br />
<br />
session.save_path="/temp"</syntaxhighlight><br />
<br />
==Error messages because of a not existing ressources==<br />
<br />
Sometimes files are not uploaded correctly or were broken during upload. This leads to several different error messages. Most of them refer to a file or function within a file which can't be found.<br />
<br />
'''Solution:''' Re-upload all files using the binary mode of your FTP program.<br />
<br />
=After Database Creation=<br />
<br />
==Blank Page after Database Creation==<br />
<br />
===Symptoms===<br />
* LimeSurvey installed OK, and database was created, but instead of the admin page, you get an empty page<br />
* Web surver log shows "Fatal error: Call to a member function on a non-object in /path/to/limesurvey/admin/login_check.php on line 69"<br />
<br />
===Fix===<br />
<br />
This is probably an incorrect setting for $rooturl or $rootdir in config.php. In particular, config.php attempts to set $rootdir correctly by calling <nowiki>dirname('''FILE''')</nowiki> and while this usually works, it can be upset when LimeSurvey is installed in a user's home or public_html directory and the home directory is mounted over NFS. Try setting $rootdir manually, and in particular, while your shell or pwd command may show a path like "/disks/hostname/home/username/public_html/limesurvey", try using "/home/username/public_html/limesurvey".<br />
<br />
==When accessing admin page, the browser keeps running and will eventually fail to show it==<br />
<br />
===Symptoms===<br />
* LimeSurvey installed OK and database was created. But when you access the admin page, the browser keeps running and will eventually fail to show the page.<br />
* When you check the web server access log, its size has become so big (in some cases, more than 2 GB).<br />
* Inside the access log, you get this message filling the log.<br />
<br />
Warning: fread() [function.fread]: Length parameter must be greater than 0 in /limesurvey/classes/php-gettext/streams.php on line 120<br />
<br />
''Note:'' line number may be different depending on your LimeSurvey version.<br />
<br />
===Fix===<br />
<br />
This may be caused by the mbstring.func_overload setting. Check the setting in your php.ini and set as the following.<br />
<br />
mbstring.func_overload = 0<br />
<br />
''Note:'' This means no function overloading. See PHP manual for this setting: [http://us3.php.net/manual/en/mbstring.overload.php Function Overloading Feature]<br />
<br />
==When accessing admin page, the browser reports Fatal error: Call to a member function gT() on a non-object in login_check.php on line 76==<br />
<br />
===Symptoms===<br />
* LimeSurvey installed OK and database was created. But when rdirected to the admin page, the browser displayed the the listed error.<br />
* $rootdir and $rooturl are correctly set in config.php.<br />
* The disk path name for limesurvey installation directory includes one of the following characters: ()+<br />
<br />
''Note:'' Other characters may also induce the same behaviour<br />
<br />
===Fix===<br />
<br />
Move / rename the limesurvey installation directory so that pathname does not include either the '''(''' or ''')''' characters<br />
<br />
=After Login=<br />
<br />
==Any action in admin page will return you to login screen==<br />
<br />
This may happen for the following two main reasons :<br />
*PHP sessions problems<br />
*UTF8 encoding problems<br />
*IE (6,7 and 8) problems<br />
<br />
<u>PHP Sessions :</u><br />
# Update upload_tmp_dir and session.save_path in php.ini<br />
# Create the configured session and upload directories<br />
# IIS: Assigned permission to create and modify to IIS guest user account<br />
# Apache: Make sure your webserver has permissions to write into the configured directory<br />
# Check if the variable "session.use_cookies" in php.ini is set to 1.<br />
# Check the variable "session.auto_start" in php.ini. If it is set to 1, change it to 0.<br />
<br />
<u>UTF8 Encoding : </u><br />
<br />
If you edit any file (most probably config.php) do not save it as UTF8 to support special language chars! Always save .php files as true ANSI/ISO format. Starting with 1.87 you can set the most important settings inside the application using the 'Global settings' dialog (like site name, administrator name, etc.).<br />
<br />
<u>IE Cookies :</u><br />
<br />
IE (6,7 and 8) does not support underscore "_" in the server hostname. If it is the case, the cookies are not managed and cookie(s) is(are) not set. So change the server hostname under apache or IIS.<br />
<br />
==LimeSurvey and suhosin ("Session has expired")==<br />
<br />
You might, at one point, get a message like :<br />
<br />
<syntaxhighlight lang="php" enclose="div">ERROR<br />
<br />
We are sorry but your session has expired.<br />
<br />
Either you have been inactive for too long, you have cookies disabled for your browser, or there were problems with your connection.</syntaxhighlight><br />
<br />
And if you have Suhosin activated on your server, that's might be the reason why you get this in the middle of a survey.<br />
<br />
NB : when your survey is not active, the behaviour might be different, you could be redirected in the middle of a survey to the public list of surveys. The solution is the same.<br />
<br />
Suhosin is an advanced protection system for PHP installations. Suhosin default configuration can make trouble to LimeSurvey installation.<br />
<br />
First think to test with suhosin log, set suhosin.log.sapi = 511 and suhosin.simulation = on according with [http://www.hardened-php.net/suhosin/configuration.html suhosin documentation].<br />
<br />
The configuration file is usually located in /etc/php5/apache2/conf.d/suhosin.ini but to be sure you can check your phpinfo (Limesurvey administration > Global Settings > Button Show phpinfo > Line : "Additional .ini files parsed") to get the correct path.<br />
<br />
Don't forget to restart your Apache server for the parameters to be taken into account (service apache2 restart).<br />
<br />
When the simulation is on, Suhosin is not blocking anything and the errors are reported into the logs (usually in your syslog : /var/log/syslog). If you appear to get error messages such as "ALERT-SIMULATION - configured POST variable limit exceeded" that's Suhosin alerting...<br />
<br />
This configuration seems to work well with Limesurvey:<br />
<br />
<syntaxhighlight lang="php" enclose="div">suhosin.memory_limit = 128<br />
<br />
suhosin.post.max_value_length = 5000000<br />
<br />
suhosin.post.max_vars = 5000<br />
<br />
suhosin.request.max_value_length = 5000000<br />
<br />
suhosin.request.max_vars = 5000</syntaxhighlight><br />
<br />
With those parameters, you should be able to put the suhosin.simulation back at the "off" value (so that the serveur is protected and limesurvey still works).<br />
<br />
The default values of suhosin are not working well with limesurvey. If you really want to secure your serveur tightly you might want to use the simulation mode to tune the setting and find the good values between 1000 and 5000 for the vars and 1000000 and 5000000 for the value_lenghts.<br />
<br />
==LimeSurvey and suhosin ("quick translate trouble")==<br />
<br />
You can have some problem with the quick translate module when you are on OpenBSD 5.1 with php-5.3.10.<br />
<br />
The symptom is : modification via "Quick translate --> options answer" are not update<br />
<br />
You must downgrade your php version to php-5.2.17p8 and use the suhosin tweak proposed above.<br />
<br />
==I can't change the language!==<br />
<br />
No matter what language you choose, the interface (admin und user) always is in English language. Normally this is caused by a bug in your PHP version. There is no other fix for this than updating your PHP version.<br />
<br />
==Some common errors (IIS focused)==<br />
<br />
===Index.php won't open===<br />
<br />
Possible cause: This might happen if you haven't installed necessary extensions<br />
* You need to install Multi-byte string, and MSSQL (or MySQL) extensions<br />
<br />
Possible cause: ISAPI filter not configured<br />
* In IIS, for the website (you could do it at the directory level) you must configure it to use php5isapi.dll<br />
<br />
===Index.php won't open and "php.exe -i" gives error messages about missing .dll's===<br />
<br />
This may happen if you install too many extensions<br />
* If you install all PHP extensions, PHP will fail because not all dependencies were met (e.g. oracle package needs oracle dll's)<br />
* Install only the extensions that you need<br />
* To test, try running php.exe -i from the command line<br />
<br />
===Message stating database was missing===<br />
<br />
This may happen if you navigate to wrong url<br />
* Make sure you go to limesurvey/admin/install/index.php instead of limesurvey/index.php !<br />
<br />
===Above fixes do not solve the problem===<br />
<br />
This may happen if you have not restarted IIS<br />
* Restart IIS<br />
<br />
Things that were easy to forget:<br />
* .php needs to be associated to php5isapi.dll filter (It did this for me automagically)<br />
* limesurvey/tmp directory needs writer permission for survey uploads<br />
* updating doc_root in php.ini and $rootdir in config.php<br />
<br />
===Missing files ("No such file or directory")===<br />
<br />
When uploading LimeSurvey to your server it might happen that the connection is interrupted so that some files are not transferred or not transferred completely. Depending on the files you can receive error message at different part of LimeSurvey usage. Normally missing files throw errors like<br />
<br />
<div class="simplebox"><br />
<br />
"Warning: require_once(/path/to/your/limesurvey/installation/filename) [function.require-once]: failed to open stream: No such file or directory in /path/to/your/limesurvey/installation/filename on line 12345)" OR<br />
<br />
"Fatal error: require_once() [function.require]: Failed opening required 'require_once(/path/to/your/limesurvey/installation/filename)' (include_path='.:/x/y/z) in /path/to/your/limesurvey/installation/filename on line 12345"<br />
<br />
</div><br />
<br />
'''Solution'''<br />
<br />
1. Delete all uploaded files.<br />
<br />
2. Re-upload the files.<br />
<br />
(3. If necessary: Re-install by browsing to /limesurveyfolder/admin/install)<br />
<br />
==Not able to add or edit subquestions/answers after upgrade==<br />
<br />
If you're not capable of editing or adding a question, ask youre host provider to change the mod_security setting of the domain name. See the forum thread [http://www.limesurvey.org/en/support/forums/1-installation-a-update-issues/46435-not-able-to-add-or-edit-questions-on-new-190-?limit=10 Not Able to Add or Edit Questions on new 1.90] for more info.<br />
<br />
==Fancy URLs by removing index.php from the URL path==<br />
<br />
If you want to use fancy URLs and so not have /index.php in every URL please edit /application/config/config.php and change<br />
<br />
<syntaxhighlight lang="php" enclose="div">'showScriptName' => true,</syntaxhighlight><br />
<br />
to<br />
<br />
<syntaxhighlight lang="php" enclose="div">'showScriptName' => false,</syntaxhighlight><br />
<br />
For this to work properly you must use an Apache webserver with a properly installed mod_rewrite module.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Installation_-_LimeSurvey_CE&diff=1582Installation - LimeSurvey CE2012-09-20T11:09:43Z<p>Admin: </p>
<hr />
<div><br />
<div style="float:right;"><div class="simplebox">Additional pages:{toc}</div></div> {maketoc title="On this page:"}<br />
<br />
<div class="simplebox"> Note: These installation instructions are for version 2.0 or later. Older instructions for 1.92 can be found here [[Installation Version 1.92 or older|here]] </div><br />
<br />
=1. Make sure you can use LimeSurvey on your website=<br />
<br />
Make sure your server meets the following additional requirements. Most of these requirements will also be checked during the installation.<br />
<br />
Required:<br />
* Minimum 80 MB disk space<br />
* MySQL 4.1.0 or later '''OR''' Microsoft SQL Server 2005 or later '''OR''' Postgres 8.1 or later<br />
* PHP 5.1.2 or later with the following modules/libraries enabled:<br />
** mbstring (Multibyte String Functions) extension library (see also [http://docs.limesurvey.org/tiki-index.php?page=Installation+FAQ#What_is_this_mbstring_Multibyte_String_Functions_library_ Installation FAQ])<br />
** PDO database driver for MySQL (pdo_mysql or pdo_mysqli) or Postgres (pdo_pgsql) or MSSQL (pdo_sqlsrv)<br />
<br />
<div class="simplebox"> Please note that LimeSurvey 2.x uses different database drivers than 1.x . If you get a message not No DBO driver was found during the installation you will have to contact your webspace provider and ask them to activate one of the aforementioned database driver libraries. </div><br />
<br />
Optional PHP Extensions:<br />
* '''GD-Library''' '''with FreeType support''' installed is needed for captchas or nice charts in statistics - see [http://de3.php.net/manual/en/image.setup.php PHP GD-Library Extension documentation]<br />
* '''IMAP''' (pretty standard) is needed for the [[Email bounce tracking system]] - see [http://www.php.net/manual/en/imap.setup.php PHP IMAP Extension documentation]<br />
* '''LDAP''' installed is needed to import tokens using LDAP - see [http://de.php.net/manual/en/ldap.installation.php PHP LDAP Documentation]<br />
* '''Zip''' (pretty standard) for template upload and import resources Zip archives - see [http://www.php.net/manual/en/zip.setup.php PHP Zip Extension documentation]<br />
* '''Zlib''' (pretty standard) is needed for the [[ComfortUpdate]] - see [http://www.php.net/manual/en/zlib.setup.php PHP Zlib Extension documentation]<br />
<br />
In most cases your webspace provider or system administrator will be able to help you out on these optional components.<br />
<br />
If you want to try LimeSurvey on your local machine we recommend [http://www.apachefriends.org/en/xampp.html XAMPP] which is an easy to install software package containing a complete web server with Apache, MySQL, PHP and Perl. LimeSurvey will run on XAMPP with no configuration needed.<br />
<br />
If you want to run Microsoft's IIS server take a look at "[[Installation of LimeSurvey on a Windows XP machine]]" and "[[Installation on XP with IIS]]".<br />
<br />
==1.1 Hosting for LimeSurvey==<br />
<br />
LimeSurvey should work with most hosting companies which provide PHP and MYSQL. If you want a ready-installed version of LimeSurvey consider using LimeService, else check out our [[LimeSurvey-compatible hosting companies|list of LimeSurvey-compatible hosting companies]].<br />
<br />
=2. Download the LimeSurvey package=<br />
<br />
[http://www.limesurvey.org/en/download Download] the latest stable LimeSurvey zip package (there are also gzip, bz2 and 7zip packages available for your convenience) and save it to your local disk.<br />
<br />
=3. Unpack the LimeSurvey package=<br />
<br />
Uncompress the zip file into a dedicated directory/folder using your preferred compression software. When you uncompress the file make sure that you uncompress the directory structure with the files (this is default behavior for most compression programs). The path name for the installation directory should not include '''(''' or ''')''' characters, but may include the '''space''' character<br />
<br />
=4. Collect information about your server=<br />
<br />
You will need to know the following things to install LimeSurvey on your web server correctly:<br />
*Your intended website URL where your scripts will reside (e.g: ''http://my.domain.com/limesurvey'')<br />
*The physical disk location on your server where your scripts will reside (ie: ''/home/usr/htdocs/limesurvey'')<br />
*The IP/net location of your database server (ie: ''localhost'')<br />
*If your database server uses a non-standard port find out which port it is.<br />
*Your username and password for your database server<br />
*With most providers you can't let the script create the database but have to do it yourself. If you are using such a provider please create a database (for example ''limesurvey'') yourself.<br />
<br />
=5. Upload the files to your web server=<br />
<br />
Using your FTP program, connect to your web server and create a directory to store your scripts. Then upload the files using the directory structure they are in. Make sure you '''upload the files in binary mode''' (check the settings of your FTP program). Please note that uploading in ASCII mode can lead to uncommon errors (e.g. 'class not found' error during installation), also images may not be uploaded correctly.<br />
<br />
=7. Set Directory permissions=<br />
<br />
For the script to work properly it needs certain access to some directories - this applies especially to Linux/*nix systems.<br />
*The '''"/limesurvey/tmp"''' directory and all its subdiretories are used for imports & uploads and should be set to ''Read & Write'' for your webserver.<br />
*The '''"/limesurvey/upload/"''' directory and all its subdirectories must also have ''Read & Write'' for your webserver in order to enable picture and media files upload.<br />
*The other directories can be set to ''Read Only'' or in Linux/Unix. You may wish to set the permissions on each file within the /limesurvey/admin directory to ''Read Only''.<br />
<br />
<div class="simplebox">[[File:help.png]] '''Hint:''' If you are using Linux then depending on your webserver configuration you will have to chmod the rights on the writable folders to 755 or 777. Try 755 first - if it does not work 'upgrade' to 777.</div><br />
<br />
=8. Run the installation script=<br />
<br />
'''Go to "http://your.domain.com/limesurvey/admin"'''. If you configured everything correctly the LimeSurvey installer should be starting - just follow the instructions. You will be asked if to create the database and/or create the tables inside the database. Limesurvey then creates the needed tables in the database.<br />
<br />
=9. Connect to the administration script for the first time=<br />
<br />
After the installer has finished you are done! Open your browser and enter the URL of your admin.php script. Assuming you used LimeSurvey as the directory name to store the files in, this will be something like "http://your.domain.com/limesurvey/admin/admin.php".<br />
<br />
You should get a login screen. The default login credentials (if not changed during in the installation) are<br />
<br />
<div class="simplebox"> User: admin<br />
<br />
Password: password<br />
<br />
</div><br />
<br />
You will be prompted to change the default password after you logged in. Have fun!<br />
<br />
=10. What if I have problems...=<br />
<br />
Like all computer programs, most of the time things will work just like the instructions say, but sometimes they just won't. There are too many possible reasons for things not going according to plan to describe here. If you have trouble, first check out the [[Installation FAQ]]. If you don't find your answer there please post your problem and any error messages in the [http://www.limesurvey.org/en/forum LimeSurvey forums] on limesurvey.org or join the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel]:<br />
<br />
<div class="simplebox"><center>'''[http://www.limesurvey.org/en/community-services/live-chat Direct link to the official LimeSurvey IRC Channel]'''</center></div></div>Adminhttps://www.limesurvey.org/manual/index.php?title=Upgrading_from_a_previous_version&diff=3566Upgrading from a previous version2012-09-20T10:57:14Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Before you start...=<br />
<br />
<span style='color:#FF0000'>... read this because it is very important: '''Always backup the files and the database of your current installation!!'''</span><br />
<br />
You can do this using a database adminstration tool like [http://www.phpmyadmin.net phpMyAdmin] etc. and a file manager! If you don't know how to do this you should better not proceed but ask someone who knows or use the [[ComfortUpdate]] instead.<br />
<br />
=The quick way (for minor version changes)=<br />
<br />
You can use this instruction if you are doing a minor upgrade (for example from 2.00 to 2.01)<br />
*Backup your files and database (did we already mention that?)<br />
*Delete all the old files/directory except for<br />
**/application/config/config.php<br />
**/upload directory<br />
*Copy the new files from the new LimeSurvey package to the existing location.<br />
*'''After the upgrade: Clear your browser cache and cookies!'''<br />
<br />
=The thorough way (for big version jumps)=<br />
<br />
Unfortunately there are a couple of things to consider, so please scan the following instruction closely.<br />
<br />
==Upgrading from version 1.50 or later to any later 2.xx version==<br />
#[http://www.limesurvey.org/download Download] the latest version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. For example in Linux tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory.<br />
### Using phpMyAdmin or similar to export all tables; or use the according '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file, modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## Open http://<yourdomain>/<yourlimesurveydir>/admin in your browser and follow the instructions (you can use the old config.php as reference). The existing database will be atuomatically detected and , if necessary, upgraded after confirmation.<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
# Check if any special manual checks apply as listed below<br />
# '''Now clear your browser cache and cookies!'''<br />
# You are done (:biggrin:).<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 2.xx''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from version 1.50 or later to any later 1.xx version==<br />
#[http://www.limesurvey.org/download Download] the desired version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. e.g. tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory<br />
### Using phpMyAdmin or similar to export all tables; or using the '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file ,modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## Edit or replace the '''config.php''' file:<br />
### If your previous version was < 1.70: Edit the new '''config.php''' to reflect changed settings in the backup '''config.php''' file. '''Do not just overwrite the new '''config.php''' with your old one!'''<br />
### If your previous version was >= 1.70: Simply replace the new '''config.php''' with your backup '''config.php''' (as the file format has not changed).<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
# Finishing the installation<br />
## Once you open the URL to your LimeSurvey administration the database tables will be updated after confirmation<br />
## Remove or rename the '''/admin/install''' directory as/if instructed by the installation script<br />
## Check if any special, manual checks apply as listed below<br />
# You are done (:biggrin:). If you notice any problems after the upgrade: Clear your browser cache and cookies!<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 1.92''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from a version earlier than v1.50 (v1.0 through v1.44)==<br />
<br />
Since the data structure and a lot of other things were changed, '''upgrading from any version previous to v1.50 is NOT possible'''. If you have old survey structure files with a *.sql extension the only way to get these into a newer version is to install [http://www.limesurvey.org/en/archived-releases/finish/24-archived-releases/289-limesurvey150zip version 1.50], import the .sql file(s) there, then upgrade that version to the most recent LimeSurvey version. See the also then page [[Transferring an installation]] for more details.<br />
<br />
=Upgrade FAQ=<br />
<br />
==What is the most actual LimeSurvey version that still supports PHP4?==<br />
<br />
The last release offering PHP4 support was version 1.82+.<br />
<br />
==Can I upgrade even if I have active surveys?==<br />
<br />
Yes, you can. Exceptions may be mentioned in the thorough instructions above. We strongly advise to test your surveys after upgrade to check if your design templates still work alright.<br />
<br />
==What is best way to port LimeSurvey *.sql survey structure files to the latest version?==<br />
<br />
Install version 1.50, import the file and export the survey structure to the newer .csv format. The latest version still can read the .csv survey structure format.</div>Adminhttps://www.limesurvey.org/manual/index.php?title=Upgrading_from_a_previous_version&diff=3567Upgrading from a previous version2012-09-20T10:57:04Z<p>Admin: </p>
<hr />
<div><br />
__TOC__<br />
<br />
=Before you start...=<br />
<br />
<span style='color:#FF0000'>... read this because it is very important: '''Always backup the files and the database of your current installation!!'''</span><br />
<br />
You can do this using a database adminstration tool like [http://www.phpmyadmin.net phpMyAdmin] etc. and a file manager! If you don't know how to do this you should better not proceed but ask someone who knows or use the [[ComfortUpdate]] instead.<br />
<br />
=The quick way (for minor version changes)=<br />
<br />
You can use this instruction if you are doing a minor upgrade (for example from 2.00 to 2.01)<br />
*Backup your files and database (did we already mention that?)<br />
*Delete all the old files/directory except for<br />
**/application/config/config.php<br />
**/upload directory<br />
*Copy the new files from the new LimeSurvey package to the existing location.<br />
*'''After the upgrade: Clear your browser cache and cookies!'''<br />
<br />
=The thorough way (for big version jumps)=<br />
<br />
Unfortunately there are a couple of things to consider, so please scan the following instruction closely.<br />
<br />
==Upgrading from version 1.50 or later to any later 2.xx version==<br />
#[http://www.limesurvey.org/download Download] the latest version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. For example in Linux tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory.<br />
### Using phpMyAdmin or similar to export all tables; or use the according '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file, modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## Open http://<yourdomain>/<yourlimesurveydir>/admin in your browser and follow the instructions (you can use the old config.php as reference). The existing database will be atuomatically detected and , if necessary, upgraded after confirmation.<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
# Check if any special manual checks apply as listed below<br />
# '''Now clear your browser cache and cookies!'''<br />
# You are done (:biggrin:).<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 2.xx''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from version 1.50 or later to any later 1.xx version==<br />
#[http://www.limesurvey.org/download Download] the desired version of LimeSurvey.<br />
# Prepare and backup the old installation<br />
## Backup your installation directory files and SQL-based database just in case.<br />
### At the command-line level, make a '''.zip''' or similar archive of the whole installation directory tree of files. e.g. tar cvzf foo.tgz cps100 will tar and zip the whole of the cps100 directory<br />
### Using phpMyAdmin or similar to export all tables; or using the '''Limesurvey Administration''' button [[File:button-export-sql.png]] to backup the entire database<br />
## Copy your '''config.php''' file ,modified '''template''' directories and the /upload directory separately for quick access later.<br />
# Replace all the installation directory files<br />
## Delete all old files in the existing installation directory<br />
## Upload and unpack the new code version into the same installation directory<br />
## Edit or replace the '''config.php''' file:<br />
### If your previous version was < 1.70: Edit the new '''config.php''' to reflect changed settings in the backup '''config.php''' file. '''Do not just overwrite the new '''config.php''' with your old one!'''<br />
### If your previous version was >= 1.70: Simply replace the new '''config.php''' with your backup '''config.php''' (as the file format has not changed).<br />
## If your previous version was older than 1.90: Copy any customized templates to /upload/templates - you will also need to rename each template directory whose name matches an existing template in /templates.<br />
## Copy your /upload directory back to the old location<br />
## Double check the '''permissions''' set on the directories (write access to '''/tmp''', '''/upload''' and and their subdirectories is required) as described in [http://docs.limesurvey.org/tiki-index.php?page=Installation&structure;=English+Instructions+for+LimeSurvey#Set_Directory_permissions Installation]<br />
# Finishing the installation<br />
## Once you open the URL to your LimeSurvey administration the database tables will be updated after confirmation<br />
## Remove or rename the '''/admin/install''' directory as/if instructed by the installation script<br />
## Check if any special, manual checks apply as listed below<br />
# You are done (:biggrin:). If you notice any problems after the upgrade: Clear your browser cache and cookies!<br />
<br />
<div class="simplebox">'''Special checks after an upgrade''':<br />
*'''from any earlier version to 1.92''': The '''templates''' have been changed in a lot of places. Please check your customized templates if they are still looking right. If not you will have to edit your templates accordingly (check out the original templates to see what was changed)<br/><br />
*'''from a version earlier than v1.53''': When upgrading from a version before v1.53 to the latest version, please check the '''global user rights''' of each user. There was a new '''superadmin''' right introduced in v1.53 that can give a user the same privilege as the master administration account created during the install. The upgrade script is guessing who to give this right to in the older versions. As this is not perfect, it should be carefully checked.</div><br />
<br />
==Upgrading from a version earlier than v1.50 (v1.0 through v1.44)==<br />
<br />
Since the data structure and a lot of other things were changed, '''upgrading from any version previous to v1.50 is NOT possible'''. If you have old survey structure files with a *.sql extension the only way to get these into a newer version is to install [http://www.limesurvey.org/en/archived-releases/finish/24-archived-releases/289-limesurvey150zip version 1.50], import the .sql file(s) there, then upgrade that version to the most recent LimeSurvey version. See the also then page [[Transferring an installation]] for more details.<br />
<br />
=Upgrade FAQ=<br />
<br />
==What is the most actual LimeSurvey version that still supports PHP4?==<br />
<br />
The last release offering PHP4 support was version 1.82+.<br />
<br />
==Can I upgrade even if I have active surveys?==<br />
<br />
Yes, you can. Exceptions may be mentioned in the thorough instructions above. We strongly advise to test your surveys after upgrade to check if your design templates still work alright.<br />
<br />
==What is best way to port LimeSurvey *.sql survey structure files to the latest version?==<br />
<br />
Install version 1.50, import the file and export the survey structure to the newer .csv format. The latest version still can read the .csv survey structure format.</div>Admin