LimeSurvey Manual - User contributions [en]

Central participants database (User panel) Development

2013-10-13T15:22:50Z

Nery: /* lime_participants */

__TOC__

=Database Schema=

==Central Storage==

===lime_participants===

The first table is the actual central table where all the participants’ entries are stored. The table is as follows

{|
!participant_id!!first_name!!last_name!!e_mail!!blacklisted_global
|-
|4b3403665fea6||Carsten||Schmitz||carsten.schmitz@example.com||N
|-
|4b1357665fea6||Jason||Cleeland||js@example.org||N
|-
|4dc14fa0db7f4||Thilabult||Lemer||thilabault.lemer@example.net||N
|}

{|
!language!!owner_uid!!date_created!!date_modified!!max_surveys
|-
|en|| 1||2007-11-04 01:00:01||2007-11-04 01:00:01||0
|-
|en|| 2||2007-11-04 01:00:01||2007-11-04 01:00:01||2
|-
|en|| 1||2007-11-04 01:00:01||2007-11-04 01:00:01||1
|}

The fields in the table are explained below:
*participant_id : It is the primary key for the table and will be auto-generated.
*first_name : It contains the first name of the participant.
*last_name : It contains the last name of the participant.
*e_mail : It contains the email id of the participant.
*language : It contains the language preference of the participant.
*blacklisted_global : It is a field that will be updated if a participant hits 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; the other, from a particular survey. When the user blacklists 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 will not be allowed to add that user to any of the surveys. If a new survey is set, then the administrator will also 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 participant will not be allowed to answer any survey. The participant will have another set of URL's in case he/she wishes to unblock himself/herself.
*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.
*date_created and date_modified are self-explanatory fields.
*max_surveys:The max_surveys field will contain a number that indicates the maximum number of surveys to which a participant can be locked. For example: if it contains 0, the participant can be added to any other survey: However, if it contains the value 2, the participant can only be locked to two surveys: so after adding him to two surveys, he can not be added to any third survey.

The combination of email and owner_uid will be the composite key for this table.

----

==Locking Feature==

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.

===lime_participant_links===

The schema of the table is

{|
|participant_id||survey_id||token_id||date_created
|-
|4b3403665fea6||63273||1||2011-03-08 12:32
|-
|4b1357665fea6||76581||1||2011-03-08 12:32
|}

This table will be used for two purposes as far as I can see for now,

1) It will give the clear cut info as to which survey a particular participant is added to.

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.

----

==Token Table==

===lime_tokens_xxxxxx===

{|
|participant_id||token||token_id||e_mail_status ||sent||reminder_sent
|-
|4b3403665fea6||afir2ski6wrcyny||1||OK||2011-03-08 12:32||N
|}

{|
|reminder_count||completed||uses_left||valid_from||valid_until||blacklisted ||att_id
|-
|0|| 2011-03-08 12:32||0||23.03.2011 00:00 ||26.03.2011 00:00|| N||2
|}

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.

The Fields in table are explained below:
*participant_id : This is the key for linking participants in this system.
*token,token_id,e_mail_status,sent,reminder_sent,reminder_count,completed,uses_left,valid_from,valid_until: Same as in the previous system.
*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.
*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

----

==Attribute Control==

This feature will be using three tables namely :

1) lime_participant_attributes - Store the actual attribute information

2) lime_participant_attribute_info - Store the UI information related to the attribute

3) lime_participant_attribute_values - Store the possible values of the attribute

===lime_participant_attributes===

This is the table that will hold the actual values

{|
| participant_id|| attribute_id|| value|| id
|-
|4b3403665fea6|| 1|| Male|| 1
|-
|4b1357665fea6|| 1|| Male|| 2
|}

The fields of the table are explained below
* participant_id : Again this is the unique id for the participants.
* 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.
* value : This field contain the actual value of the attribute, in case of textbox, It will contain the value contained in the text box.

===lime_participant_attribute_info===

This is the table that will hold the UI related information for attribute control

{|
| attrbute_id|| attribute_name|| attribute_type|| visible
|-
|1|| sex|| DD|| 1
|}
*attribute_id : The unique id give to each additional attribute.
*attribute_name : This is the label that will be shown in the UI created for additional attribute.
*attribute_type : This field contains the type of UI that needs to be created for this particular attribute
*visible : This field will tell whether that attribute is to be used for the current set of participants or not

===lime_participant_attribute_values===

This is the table that will hold all the possible values for the particular attribute. The scehma of this table is

{|
| attribute_id|| value_id|| p_value
|-
| 1|| 1|| male
|-
| 1|| 2|| male
|-
|2|| 1||
|}

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.

----

==Relationship==

The relationship between the tables explained above is shown below.

[[File:Relationsv4.png]]}

----

=User Interface=

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.

[[File:Screen_shot_1.png]]

When clicked on the Add Participants the following screen will come up

----

==Add Participant==

[[File:Screen_shot_2.jpg]]

Explanation of the above screenshot is given below:
*ID : This is the autogenerated ID for each participant.
*First Name, Last Name, Email, Language : These fields are self-explanatory.
*Blacklisted: This is the local blacklisted field I explained earlier.
*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.
*Owner: This will be a fixed field by default that will contain the owner’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
*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.
*Sex: This is the additional attribute we set under attribute_control.

----

==Import from CSV/LDAP==

[[File:Screen_shot_3.jpg]]

The CSV file upload feature is similar to what we used to do under tokens, however with some differences, the differences are mentioned below:
*The language is no longer an optional field, but under the mandatory fields.
*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.
*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.
*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.
*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.
*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.

----

==Display Participants==

[[File:Screen_shot_4.png]]

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.

----

==Blacklist Control==

[[File:Screen_shot_5.png]]

All the settings under this page will be stored under the settings_global table. Each of setting is

explained below
*The first option if set, will mark participant blacklist for all the survey's that are present in the system currently.
*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.
*The third option will not allow the participant to be even added to the survey if the global blacklist field is set.
*The fourth option will not show the blacklisted participant in the display participant.
*In the fifth option, if the participant blacklist himself/herself globally , he will be deleted from the database .
*The sixth option will decide that whether the URL to blacklist the user will be sent in the invitation.

----

==User Control==

[[File:Screen_shot_6.png]]

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.
*The first field if enabled or disable this feature completely.
*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.
*The third option will set if the owner field is editable or not.

----

==Attribute Control==

[[File:Screen_shot_7.png]]

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
*Drop Down
*Check Box
*Radio
*jQuery DatePicker
*Text Box

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.

----

==Add to survey==

[[File:Screen_shot_8.png]]

The UI is explained below:
*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.
*Lock this group to the survey will lock this particular group to the survey, and will not allow any other
*This field will give all the global attributes that are present with the participants and only relevant attributes are added to the survey
*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.

----

==Sign Up Control==

[[File:Screen_shot_10.png]]

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.

The mock - up of the sign up control is as shown :

[[File:Screen_shot_9.png]]

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.

----

=CodeIgniter Specific Details=

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.

==Controller==

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
*addParticipant //Add Participant
*import //Import CSV/LDAP
*displayparticipant //Display the jqgrid
*blcontrol //Blacklist Control
*usercontrol //User Control
*signupcontrol //signupcontrol

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.

For Storing data we have functions such as
*storeParticipant
*storeBL
*storeUser
*storeSignup

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.

==Models==

For the models we have
*participants_model
*attribute_model
*token_model(older token table)
*survey_links_model

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.

==View==

For the view, I have decided to use the following views. These are
*headercpdb
*addparticipant_view
*displayparticipant_view
*importparticipant_view
*blcontrol_view
*usercontrol_view
*signupcontrol_view

----

=Scenario Testing=

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

1) What do you want to do?

2) Where will the system fail?

3) Feature Suggestion?

----

=Action Plan :)=

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

Plan for June

{|
| Date||What to do ?
|-
|<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>
|-
|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 .
|-
|16-22th June ||Addition and attribute control
|-
|23-28th June ||CSV and LDAP upload with attribute support
|-
|29-10th July ||Add to token table and vice versa with editing logic and max surveys feature
|-
|11-15th July ||Sending email with blacklist control and the required logic
|-
|(12 July - 16 July) || (Midterm Break)
|-
|16-31th July ||sign up addition for participants along with the multiligual attribute support for token system
|-
|1-15th August ||features from if we have time list
|-
|16-22th August ||cleaning up code, video tutorials, testing and bug fixing
|-
|23-31th August ||worst case scenario or else party time ;)
|}

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.

----

=Weekly Meetings=

This will contain the logs of the weekly meetings we have:

12th May 2011 -> http://docs.limesurvey.org/CPDB+Meeting+Log+12-05-2011

Logs of meeting from the 19th of May will be available at the link below

http://docs.limesurvey.org/CPDB+Meeting+Logs

----

=Scenarios=

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

==Privacy Scenarios==

'''Single Company Installation'''

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.

'''Multi User Installation'''

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.

==Survey Invitation Scenarios==

'''Pre-existing List, Add it to Participants Database'''

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.

'''Pre-existing List, Don't add it to the participants database'''

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.

'''Generate attributes for the participants database from answers to a survey'''

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.

'''Generate tokens from participants list based on earlier survey'''

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.

'''Generate tokens from participants list based on their survey history'''

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:

1) Select search criteria from values such as "survey name", "survey completed date"

2) Fill out matching values (ie: text string for survey name, dates for completion dates)

3) Make the system search through all participants for matches to the search criteria

4) See a list of all the matching participants (and the relevant information)

5) Be able to do something with the resulting list (most likely copy them to a token table)

'''Generate tokens from participants list based on other attribute'''

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:

1) Select the attribute or attributes to use in his search

2) Enter a search value/criteria for the search

3) Make the system search through all the participants he has rights to view, for matches to his search criteria

4) See a list of all the matching participants (and probably the relevant attribute data)

5) Do stuff with the list (most likely, copy those participants to a token table for a survey)

'''Taking care of the panel health'''

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.

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.

==Other scenario types?==

Theme editor/pt

2013-10-12T11:10:16Z

Nery: Created page with "=Introdução="

<languages />
=Introdução=

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.

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.

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:

<syntaxhighlight lang="html4strict" enclose="div"><center><font face='verdana' color='red'>{SURVEYNAME}</font><br />
<font face='verdana' color='blue'><u>{SURVEYDESCRIPTION}</u></center>
</syntaxhighlight>

One gets a result that looks like:

<div class="simplebox"><center>'''<span style='color:red'>My New Survey</span>'''</center>
<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>

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

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/en/download-limesurvey-design-templates/com_josetta_menu_control_panel/viewcategory/9-survey-design-templates Template Repository]

=Creating a new Template=

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.

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

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.

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

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.

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.

=The LimeSurvey Template Editor=

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.

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.

[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The Template Menu==

*'''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.
*'''Import Template:''' Allows you to import a template.
*'''Export Template:''' Allows you to export the current template to a .zip-File.
*'''Copy Template:''' Allows you to make a new template by copying the current one.
*'''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.

The "Screen" drop-down list on the right allows you to choose which particular survey page you are currently looking at.

==Import/Export/Copy a Template==

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.

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.

==Page Structure / Template Use==
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl
*'''The Submit Page:''' startpage.pstpl, survey.pstpl, submit.pstpl, (privacy.pstpl), navigator.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files==

The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag, even though many browsers do not require strict adherence to the W3 HTML 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.
*'''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)
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. 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.
*'''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.
*'''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
*'''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.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl endgroup.pstpl but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl but for the print version of the survey.

== CSS and Javascript==

Two files are allways used for template : template.css for css and template.js for javascript.
*'''{TEMPLATECSS}:''' Add lines for default css, template.css and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js and all js files needed for LimeSurvey.

=== Replacing default css or javascript===

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.

==Other Template Files==

The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''' and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages==

There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the survey's settings. The table below indicates which template files are used in constructing each of these pages.

{| class="wikitable"
! '''Survey Pages:'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}

<span style='color:red'>'''*'''</span>NOTE: In 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>

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

==The File Control Section==

In the "file control" window on the left, you can click on one of the template files that is used to compile the page. 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.

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:

<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/mypicture.jpg'</syntaxhighlight>
You can use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>

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.

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

==Location of template files==

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.

To create a new template, use the according icon in the template editor.

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.

You can use any image files that you upload into the template management area with syntax like this:

<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS=

Styling of questions in CSS has become much easier. Each question type now has a unique class. Mandatory question's also have an additional mandatory class. For example, for a non-mandatory question:

<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>

and if the question is mandatory

<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>

and if the question is mandatory but the user didn't answer it or if there is validation on a question

<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>

and if the question has validation applied but the user hasn't answered correctly

<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part==

These classes are used for each question type. Some question types use only one or two class, but others can use much more.

{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answer are question too, then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question type have multi list class: like checkbox with comment : class="checkbox-list text-list"
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .numeric-item
| The answer part of a numeric input
| Multi numeric question type, array of number
| <li class="numeric-item">, <td class="numeric-item">
|
|-
! scope="row" | .select-list
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .select-item
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .hide
| Used for accessibility: hidden with css but read by screenreader
| Short text question
| <label class="hide">
| Can be used for other purpose
|-
! scope="row" | .dontread
| Used for accessibility: not be read by screenreader
| Array question type
| <th class="dontread">
|
|-
! scope="row" | .checkbox
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .radio
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2
| Array question type
| Alternation for line
| <tr class="array1">
|
|}

=== Some example of question part with classes===

'''text-short question type:'''<source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source>
'''Multiple short text'''<source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source>
'''Array question type'''<source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source>
==The full list of question classes==

{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes==

<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>

These apply to the help and/or validation tip messages so that each type can be individually styled.

The .hide-tip option and .input-error options, 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.

All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed, and are color-coded to indicate whether the answers pass the validation criteria.

Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been med; then re-display the page using a harsher color if the person submits the page with lingering validation errors.

{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template==

The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>

If you're styling your own custom template, you should be able to copy everything after the above 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.

==Internet Explorer conditional style sheets==

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.

<source lang="html4strict" enclose="div">



</source>

You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either /templates/default/ or /templates/limespired for Tables base layout and CSS based layout respectively.

<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer===

You can put conditional class for body in startpage.pstpl, and use this class in your template.css. This method is used in citronade template. Adding a js / no-js class to to have javascript / no javascript system.

<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>

And in template.css use

<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify==

The text editor within LimeSurvey is able to format RTL Text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords==

Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}

The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)

{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded 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}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself, to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{SUBMITBUTTON}||submit.pstpl||Displays the final submit button
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACY}||submit.pstpl||Displays privacy information when survey is anonymous
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{CLOSEWINDOW}||All Files (Preferably in navigator.pstpl)||URL to close current window
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons==

Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file, and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes (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)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally you should use this to make sure that their font size and colour is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background colour for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the colour and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the colour and style of the warning message displayed if the participant's browser has javascript disabled)

There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)

An example of using these classes with style sheets can be found in the "bubblegum" template that comes with the LimeSurvey application.

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.

==Styling the progress bar==

'''Before version 1.87:'''

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.

'''Version 1.87 and newer:'''

The progress bar appearance can be modified with CSS.

To change the background colour of the bar, add something like the following to the end of your template.css file.

<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>

To change the border colour of the bar, add something like the following to the end of your template.css file.

<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers==

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.

===Basic CMS Integration support===

<div class="simplebox">Deprecated: This function is not available anymore in version 2.0 or later</div>

To be able to integrate LimeSurvey into another CMS, use the following options in '''config.php''':

// Set $embedded to true and specify the header and footer functions if the survey is to be displayed embedded in a CMS

<nowiki>
$embedded = false;
$embedded_inc = ""; // path to the header to include if any
$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog
$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog
</nowiki>

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.

===Support for your own Javascript functions===

Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling each. This way a template author can create their own '''template_onload()''' function in the HEAD that replaces the default one.

'''Version 1.87 and newer:'''
*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.
*There are more details in the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|workaround section]].

=Videos on Templates=

This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, customizing survey description page, and completed page.

[http://youtu.be/Uk3FQyDTIY0 LimeSurvey training video - template customization]

=Tips & Tricks=

==Some language specific element==

If you want to have some language specific sentence in a survey, for example a help at end of each page, you can add in a .pstl file a sentence and hidding it for other language. And hidding it in the template.css, we can use the pseudo selector :lang, but for best compatibility, we use some class.

Example for a help sentence at bottom of the page, in french and english, put this on endpage.pstpl:

<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>

and in template.css

<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>

You can use it to for other sentence in your question before 1.92 ( in 1.92, there are better solutions).

==Change the layout of the survey page==

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.

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

==Import/Export of templates: Mac users==

Mac users, please note: Mac OSX default archive utility may have problems with zip folders "generated on the fly".

a work around is to unix'es unzip from the command line:

$ unzip template.zip -d template

Archive: template.zip

inflating: template/startpage

inflating: ...

or scripts in their mac-compiled counterparts:

http://homepage.mac.com/roger_jolly/software/

==Changing your templates traffic light from red to green==

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

GO to file directory ie file manager, find templates directory.

1 change permission on eg"vallendar" (or any template of your choice) directory to read 777

2 voila! the red traffic light on "vallendar" is now green.

3 NOTE: to restrict access for safety, when finished editing template files, change all templates files back to what they were eg 644

==Replacing the help icon==

When a question help text is shown then an help.gif image is used from the default template folder.

You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It then will be automatically used instead of the default help icon.

==Replacing an existing logo==

'''Note''': Before uploading a new logo always delete the old, existing one!

1. To edit the logo go to the &bdquo;<u>template.css</u>” file which you can find it here:

[[File:t1.PNG|200px]]

2. Click the search button to find occurrences of logo related styles.

[[File:2.png|200px]]

3. Search for <u>#logo</u>

[[File:3.PNG|200px]]

4. Edit the main style file

You will see something similar to:

[[File:t4.PNG|500px]]

If you want to change the image just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).

If you want change the image size adjust width and height (in pixels) like this:

<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo==

1. Find and open the &bdquo;<u>startpage.pstpl</u>” template file.

[[File:5.PNG|200px]]

2. After the <source lang="html4strict" ><body ... ></source> tag add this line to &bdquo;<u>startpage.pstpl</u>”:
<source lang="html4strict"><img id="page_logo" src="{TEMPLATEURL}logo.png"><br></source>

3. To add logo go to &bdquo;<u>template.css</u>”, you can find it here (see in screen):

[[File:6.PNG|500px]]

3.1 Then go to the end of the main &bdquo;<u>template.css</u>” style file.

3.2 To align the logo add...

'''If you want the logo to be placed at left side:'''

<syntaxhighlight lang="php" enclose="div">#page_logo{
float:left;
}</syntaxhighlight>

'''If you want the logo to be placed at right side:'''

<syntaxhighlight lang="php" enclose="div">#page_logo{
float:right;
}</syntaxhighlight>

'''If you want to center the logo'''

<syntaxhighlight lang="php" enclose="div">#page_logo{
display: block;
margin-left: auto;
margin-right: auto;
}</syntaxhighlight>

==Use the same template with different logos==

If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:

<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip)==

There are 3 solutions to remove the default help:
# like a [[Advanced question settings#hide_tip|hide_tip attribute]] but for all question and survey.
# you can remove the {QUESTIONHELP} and is container from the file question.pstl, but it can be a bad idea for screenreader.
# for the default template and some other, add this at the end of tempate.css

<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon==

A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators
#Name your new favicon "favicon.ico" and place it in your template directory
#Add the following code to your '''startpage.pstpl''' before the </head> tag

<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages==

(''Version 1.91 and newer'')

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.

example from default template of LimeSurvey 1.91+

<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>

To '''not''' differentiate even and odd pages at the (default) template find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array==

To create a vertical separator border for a dual scale array you can add the following lines to your '''template.css'''-file.

<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>

header_separator is used to adress the separator for the header "td" and "dual_scale_separator" is used to adress the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list==

To hide the "Please contact ..." message on the start page (with the survey list) you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:

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

$('#surveycontact').hide(); //Hides the survey contact message

</syntaxhighlight>

==Remove the survey contact message shown on error messages==

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:

<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>

and add the following function to your *template.js* file

<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>

It will probably not work for an englisch survey and have to be extended when using for multilingual surveys. But it's an idea/tip how to solve this.

==How to deal with multilingual question attributes (before version 2.0 at which those were added)==

If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other"

<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>

At the template.css of your template (at /limesurvey/upload/templates/<yourtemplatename>/template.css) add:

<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

Translations:Theme editor/1/pt

2013-10-12T11:10:14Z

Nery: Created page with "=Introdução="

=Introdução=

Theme editor/pt

2013-10-12T11:10:06Z

Nery: Created page with "O editor de modelos"

<languages />
=Introduction=

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.

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.

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:

<syntaxhighlight lang="html4strict" enclose="div"><center><font face='verdana' color='red'>{SURVEYNAME}</font><br />
<font face='verdana' color='blue'><u>{SURVEYDESCRIPTION}</u></center>
</syntaxhighlight>

One gets a result that looks like:

<div class="simplebox"><center>'''<span style='color:red'>My New Survey</span>'''</center>
<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>

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

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/en/download-limesurvey-design-templates/com_josetta_menu_control_panel/viewcategory/9-survey-design-templates Template Repository]

=Creating a new Template=

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.

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

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.

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

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.

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.

=The LimeSurvey Template Editor=

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.

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.

[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The Template Menu==

*'''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.
*'''Import Template:''' Allows you to import a template.
*'''Export Template:''' Allows you to export the current template to a .zip-File.
*'''Copy Template:''' Allows you to make a new template by copying the current one.
*'''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.

The "Screen" drop-down list on the right allows you to choose which particular survey page you are currently looking at.

==Import/Export/Copy a Template==

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.

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.

==Page Structure / Template Use==
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl
*'''The Submit Page:''' startpage.pstpl, survey.pstpl, submit.pstpl, (privacy.pstpl), navigator.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files==

The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag, even though many browsers do not require strict adherence to the W3 HTML 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.
*'''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)
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. 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.
*'''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.
*'''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
*'''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.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl endgroup.pstpl but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl but for the print version of the survey.

== CSS and Javascript==

Two files are allways used for template : template.css for css and template.js for javascript.
*'''{TEMPLATECSS}:''' Add lines for default css, template.css and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js and all js files needed for LimeSurvey.

=== Replacing default css or javascript===

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.

==Other Template Files==

The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''' and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages==

There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the survey's settings. The table below indicates which template files are used in constructing each of these pages.

{| class="wikitable"
! '''Survey Pages:'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}

<span style='color:red'>'''*'''</span>NOTE: In 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>

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

==The File Control Section==

In the "file control" window on the left, you can click on one of the template files that is used to compile the page. 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.

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:

<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/mypicture.jpg'</syntaxhighlight>
You can use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>

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.

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

==Location of template files==

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.

To create a new template, use the according icon in the template editor.

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.

You can use any image files that you upload into the template management area with syntax like this:

<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS=

Styling of questions in CSS has become much easier. Each question type now has a unique class. Mandatory question's also have an additional mandatory class. For example, for a non-mandatory question:

<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>

and if the question is mandatory

<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>

and if the question is mandatory but the user didn't answer it or if there is validation on a question

<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>

and if the question has validation applied but the user hasn't answered correctly

<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part==

These classes are used for each question type. Some question types use only one or two class, but others can use much more.

{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answer are question too, then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question type have multi list class: like checkbox with comment : class="checkbox-list text-list"
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .numeric-item
| The answer part of a numeric input
| Multi numeric question type, array of number
| <li class="numeric-item">, <td class="numeric-item">
|
|-
! scope="row" | .select-list
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .select-item
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .hide
| Used for accessibility: hidden with css but read by screenreader
| Short text question
| <label class="hide">
| Can be used for other purpose
|-
! scope="row" | .dontread
| Used for accessibility: not be read by screenreader
| Array question type
| <th class="dontread">
|
|-
! scope="row" | .checkbox
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .radio
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2
| Array question type
| Alternation for line
| <tr class="array1">
|
|}

=== Some example of question part with classes===

'''text-short question type:'''<source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source>
'''Multiple short text'''<source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source>
'''Array question type'''<source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source>
==The full list of question classes==

{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes==

<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>

These apply to the help and/or validation tip messages so that each type can be individually styled.

The .hide-tip option and .input-error options, 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.

All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed, and are color-coded to indicate whether the answers pass the validation criteria.

Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been med; then re-display the page using a harsher color if the person submits the page with lingering validation errors.

{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template==

The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>

If you're styling your own custom template, you should be able to copy everything after the above 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.

==Internet Explorer conditional style sheets==

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.

<source lang="html4strict" enclose="div">



</source>

You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either /templates/default/ or /templates/limespired for Tables base layout and CSS based layout respectively.

<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer===

You can put conditional class for body in startpage.pstpl, and use this class in your template.css. This method is used in citronade template. Adding a js / no-js class to to have javascript / no javascript system.

<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>

And in template.css use

<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify==

The text editor within LimeSurvey is able to format RTL Text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords==

Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}

The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)

{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded 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}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself, to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{SUBMITBUTTON}||submit.pstpl||Displays the final submit button
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACY}||submit.pstpl||Displays privacy information when survey is anonymous
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{CLOSEWINDOW}||All Files (Preferably in navigator.pstpl)||URL to close current window
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons==

Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file, and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes (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)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally you should use this to make sure that their font size and colour is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background colour for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the colour and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the colour and style of the warning message displayed if the participant's browser has javascript disabled)

There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)

An example of using these classes with style sheets can be found in the "bubblegum" template that comes with the LimeSurvey application.

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.

==Styling the progress bar==

'''Before version 1.87:'''

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.

'''Version 1.87 and newer:'''

The progress bar appearance can be modified with CSS.

To change the background colour of the bar, add something like the following to the end of your template.css file.

<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>

To change the border colour of the bar, add something like the following to the end of your template.css file.

<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers==

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.

===Basic CMS Integration support===

<div class="simplebox">Deprecated: This function is not available anymore in version 2.0 or later</div>

To be able to integrate LimeSurvey into another CMS, use the following options in '''config.php''':

// Set $embedded to true and specify the header and footer functions if the survey is to be displayed embedded in a CMS

<nowiki>
$embedded = false;
$embedded_inc = ""; // path to the header to include if any
$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog
$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog
</nowiki>

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.

===Support for your own Javascript functions===

Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling each. This way a template author can create their own '''template_onload()''' function in the HEAD that replaces the default one.

'''Version 1.87 and newer:'''
*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.
*There are more details in the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|workaround section]].

=Videos on Templates=

This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, customizing survey description page, and completed page.

[http://youtu.be/Uk3FQyDTIY0 LimeSurvey training video - template customization]

=Tips & Tricks=

==Some language specific element==

If you want to have some language specific sentence in a survey, for example a help at end of each page, you can add in a .pstl file a sentence and hidding it for other language. And hidding it in the template.css, we can use the pseudo selector :lang, but for best compatibility, we use some class.

Example for a help sentence at bottom of the page, in french and english, put this on endpage.pstpl:

<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>

and in template.css

<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>

You can use it to for other sentence in your question before 1.92 ( in 1.92, there are better solutions).

==Change the layout of the survey page==

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.

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

==Import/Export of templates: Mac users==

Mac users, please note: Mac OSX default archive utility may have problems with zip folders "generated on the fly".

a work around is to unix'es unzip from the command line:

$ unzip template.zip -d template

Archive: template.zip

inflating: template/startpage

inflating: ...

or scripts in their mac-compiled counterparts:

http://homepage.mac.com/roger_jolly/software/

==Changing your templates traffic light from red to green==

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

GO to file directory ie file manager, find templates directory.

1 change permission on eg"vallendar" (or any template of your choice) directory to read 777

2 voila! the red traffic light on "vallendar" is now green.

3 NOTE: to restrict access for safety, when finished editing template files, change all templates files back to what they were eg 644

==Replacing the help icon==

When a question help text is shown then an help.gif image is used from the default template folder.

You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It then will be automatically used instead of the default help icon.

==Replacing an existing logo==

'''Note''': Before uploading a new logo always delete the old, existing one!

1. To edit the logo go to the &bdquo;<u>template.css</u>” file which you can find it here:

[[File:t1.PNG|200px]]

2. Click the search button to find occurrences of logo related styles.

[[File:2.png|200px]]

3. Search for <u>#logo</u>

[[File:3.PNG|200px]]

4. Edit the main style file

You will see something similar to:

[[File:t4.PNG|500px]]

If you want to change the image just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).

If you want change the image size adjust width and height (in pixels) like this:

<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo==

1. Find and open the &bdquo;<u>startpage.pstpl</u>” template file.

[[File:5.PNG|200px]]

2. After the <source lang="html4strict" ><body ... ></source> tag add this line to &bdquo;<u>startpage.pstpl</u>”:
<source lang="html4strict"><img id="page_logo" src="{TEMPLATEURL}logo.png"><br></source>

3. To add logo go to &bdquo;<u>template.css</u>”, you can find it here (see in screen):

[[File:6.PNG|500px]]

3.1 Then go to the end of the main &bdquo;<u>template.css</u>” style file.

3.2 To align the logo add...

'''If you want the logo to be placed at left side:'''

<syntaxhighlight lang="php" enclose="div">#page_logo{
float:left;
}</syntaxhighlight>

'''If you want the logo to be placed at right side:'''

<syntaxhighlight lang="php" enclose="div">#page_logo{
float:right;
}</syntaxhighlight>

'''If you want to center the logo'''

<syntaxhighlight lang="php" enclose="div">#page_logo{
display: block;
margin-left: auto;
margin-right: auto;
}</syntaxhighlight>

==Use the same template with different logos==

If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:

<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip)==

There are 3 solutions to remove the default help:
# like a [[Advanced question settings#hide_tip|hide_tip attribute]] but for all question and survey.
# you can remove the {QUESTIONHELP} and is container from the file question.pstl, but it can be a bad idea for screenreader.
# for the default template and some other, add this at the end of tempate.css

<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon==

A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators
#Name your new favicon "favicon.ico" and place it in your template directory
#Add the following code to your '''startpage.pstpl''' before the </head> tag

<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages==

(''Version 1.91 and newer'')

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.

example from default template of LimeSurvey 1.91+

<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>

To '''not''' differentiate even and odd pages at the (default) template find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array==

To create a vertical separator border for a dual scale array you can add the following lines to your '''template.css'''-file.

<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>

header_separator is used to adress the separator for the header "td" and "dual_scale_separator" is used to adress the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list==

To hide the "Please contact ..." message on the start page (with the survey list) you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:

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

$('#surveycontact').hide(); //Hides the survey contact message

</syntaxhighlight>

==Remove the survey contact message shown on error messages==

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:

<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>

and add the following function to your *template.js* file

<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>

It will probably not work for an englisch survey and have to be extended when using for multilingual surveys. But it's an idea/tip how to solve this.

==How to deal with multilingual question attributes (before version 2.0 at which those were added)==

If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other"

<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>

At the template.css of your template (at /limesurvey/upload/templates/<yourtemplatename>/template.css) add:

<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

Translations:Theme editor/Page display title/pt

2013-10-12T11:10:04Z

Nery: Created page with "O editor de modelos"

O editor de modelos

Theme editor

2013-10-12T02:07:37Z

Nery:

<languages /> <translate>

=Introduction= 


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.


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.


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:


<syntaxhighlight lang="html4strict" enclose="div"><center><font face='verdana' color='red'>{SURVEYNAME}</font><br />
<font face='verdana' color='blue'><u>{SURVEYDESCRIPTION}</u></center>
</syntaxhighlight>


One gets a result that looks like:


<div class="simplebox"><center>'''<span style='color:red'>My New Survey</span>'''</center>
<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>


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


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/en/download-limesurvey-design-templates/com_josetta_menu_control_panel/viewcategory/9-survey-design-templates Template Repository]

=Creating a new Template= 


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.


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


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.


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


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.


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.

=The LimeSurvey Template Editor= 


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.


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.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The Template Menu== 


*'''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.
*'''Import Template:''' Allows you to import a template.
*'''Export Template:''' Allows you to export the current template to a .zip-File.
*'''Copy Template:''' Allows you to make a new template by copying the current one.
*'''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.


The "Screen" drop-down list on the right allows you to choose which particular survey page you are currently looking at.

==Import/Export/Copy a Template== 


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.


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.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl
*'''The Submit Page:''' startpage.pstpl, survey.pstpl, submit.pstpl, (privacy.pstpl), navigator.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag, even though many browsers do not require strict adherence to the W3 HTML 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.
*'''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)
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. 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.
*'''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.
*'''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
*'''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.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl endgroup.pstpl but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl but for the print version of the survey.

== CSS and Javascript== 


Two files are allways used for template : template.css for css and template.js for javascript.
*'''{TEMPLATECSS}:''' Add lines for default css, template.css and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js and all js files needed for LimeSurvey.

=== Replacing default css or javascript=== 


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.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''' and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the survey's settings. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages:'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In 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>


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

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. 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.


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:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/mypicture.jpg'</syntaxhighlight>
You can use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


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.


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

==Location of template files== 


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.


To create a new template, use the according icon in the template editor.


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.


You can use any image files that you upload into the template management area with syntax like this:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type now has a unique class. Mandatory question's also have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory but the user didn't answer it or if there is validation on a question


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied but the user hasn't answered correctly


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two class, but others can use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answer are question too, then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question type have multi list class: like checkbox with comment : class="checkbox-list text-list"
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .numeric-item
| The answer part of a numeric input
| Multi numeric question type, array of number
| <li class="numeric-item">, <td class="numeric-item">
|
|-
! scope="row" | .select-list
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .select-item
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .hide
| Used for accessibility: hidden with css but read by screenreader
| Short text question
| <label class="hide">
| Can be used for other purpose
|-
! scope="row" | .dontread
| Used for accessibility: not be read by screenreader
| Array question type
| <th class="dontread">
|
|-
! scope="row" | .checkbox
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .radio
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2
| Array question type
| Alternation for line
| <tr class="array1">
|
|}

=== Some example of question part with classes=== 


'''text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options, 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.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed, and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been med; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above 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.

==Internet Explorer conditional style sheets== 


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.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either /templates/default/ or /templates/limespired for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put conditional class for body in startpage.pstpl, and use this class in your template.css. This method is used in citronade template. Adding a js / no-js class to to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL Text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded 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}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself, to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{SUBMITBUTTON}||submit.pstpl||Displays the final submit button
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACY}||submit.pstpl||Displays privacy information when survey is anonymous
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{CLOSEWINDOW}||All Files (Preferably in navigator.pstpl)||URL to close current window
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file, and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes (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)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally you should use this to make sure that their font size and colour is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background colour for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the colour and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the colour and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


An example of using these classes with style sheets can be found in the "bubblegum" template that comes with the LimeSurvey application.


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.

==Styling the progress bar== 


'''Before version 1.87:'''


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.


'''Version 1.87 and newer:'''


The progress bar appearance can be modified with CSS.


To change the background colour of the bar, add something like the following to the end of your template.css file.


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border colour of the bar, add something like the following to the end of your template.css file.


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


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.

===Basic CMS Integration support=== 


<div class="simplebox">Deprecated: This function is not available anymore in version 2.0 or later</div>


To be able to integrate LimeSurvey into another CMS, use the following options in '''config.php''':


// Set $embedded to true and specify the header and footer functions if the survey is to be displayed embedded in a CMS


<nowiki>
$embedded = false;
$embedded_inc = ""; // path to the header to include if any
$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog
$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog
</nowiki>


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.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling each. This way a template author can create their own '''template_onload()''' function in the HEAD that replaces the default one.


'''Version 1.87 and newer:'''
*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.
*There are more details in the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|workaround section]].

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, customizing survey description page, and completed page.


[http://youtu.be/Uk3FQyDTIY0 LimeSurvey training video - template customization]

=Tips & Tricks= 

==Some language specific element== 


If you want to have some language specific sentence in a survey, for example a help at end of each page, you can add in a .pstl file a sentence and hidding it for other language. And hidding it in the template.css, we can use the pseudo selector :lang, but for best compatibility, we use some class.


Example for a help sentence at bottom of the page, in french and english, put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>


You can use it to for other sentence in your question before 1.92 ( in 1.92, there are better solutions).

==Change the layout of the survey page== 


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.


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

==Import/Export of templates: Mac users== 


Mac users, please note: Mac OSX default archive utility may have problems with zip folders "generated on the fly".


a work around is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


or scripts in their mac-compiled counterparts:


http://homepage.mac.com/roger_jolly/software/

==Changing your templates traffic light from red to green== 


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


GO to file directory ie file manager, find templates directory.


1 change permission on eg"vallendar" (or any template of your choice) directory to read 777


2 voila! the red traffic light on "vallendar" is now green.


3 NOTE: to restrict access for safety, when finished editing template files, change all templates files back to what they were eg 644

==Replacing the help icon== 


When a question help text is shown then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It then will be automatically used instead of the default help icon.

==Replacing an existing logo== 


'''Note''': Before uploading a new logo always delete the old, existing one!


1. To edit the logo go to the &bdquo;<u>template.css</u>” file which you can find it here:


[[File:t1.PNG|200px]]


2. Click the search button to find occurrences of logo related styles.


[[File:2.png|200px]]


3. Search for <u>#logo</u>


[[File:3.PNG|200px]]


4. Edit the main style file


You will see something similar to:


[[File:t4.PNG|500px]]


If you want to change the image just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want change the image size adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo== 


1. Find and open the &bdquo;<u>startpage.pstpl</u>” template file.


[[File:5.PNG|200px]]


2. After the <source lang="html4strict" ><body ... ></source> tag add this line to &bdquo;<u>startpage.pstpl</u>”:
<source lang="html4strict"><img id="page_logo" src="{TEMPLATEURL}logo.png"><br></source>


3. To add logo go to &bdquo;<u>template.css</u>”, you can find it here (see in screen):


[[File:6.PNG|500px]]


3.1 Then go to the end of the main &bdquo;<u>template.css</u>” style file.


3.2 To align the logo add...


'''If you want the logo to be placed at left side:'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
float:left;
}</syntaxhighlight>


'''If you want the logo to be placed at right side:'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
float:right;
}</syntaxhighlight>


'''If you want to center the logo'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
display: block;
margin-left: auto;
margin-right: auto;
}</syntaxhighlight>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip)== 


There are 3 solutions to remove the default help:
# like a [[Advanced question settings#hide_tip|hide_tip attribute]] but for all question and survey.
# you can remove the {QUESTIONHELP} and is container from the file question.pstl, but it can be a bad idea for screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators
#Name your new favicon "favicon.ico" and place it in your template directory
#Add the following code to your '''startpage.pstpl''' before the </head> tag


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


(''Version 1.91 and newer'')


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.


example from default template of LimeSurvey 1.91+


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


To '''not''' differentiate even and odd pages at the (default) template find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


header_separator is used to adress the separator for the header "td" and "dual_scale_separator" is used to adress the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list== 


To hide the "Please contact ..." message on the start page (with the survey list) you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


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


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages== 


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:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for an englisch survey and have to be extended when using for multilingual surveys. But it's an idea/tip how to solve this.

==How to deal with multilingual question attributes (before version 2.0 at which those were added)== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other"


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


At the template.css of your template (at /limesurvey/upload/templates/<yourtemplatename>/template.css) add:


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

</translate>

Theme editor

2013-10-12T02:00:52Z

Nery:

<languages /> <translate>

=Introduction= 


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.


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.


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:


<syntaxhighlight lang="html4strict" enclose="div"><center><font face='verdana' color='red'>{SURVEYNAME}</font><br />
<font face='verdana' color='blue'><u>{SURVEYDESCRIPTION}</u></center>
</syntaxhighlight>


One gets a result that looks like:


<div class="simplebox"><center>'''<span style='color:red'>My New Survey</span>'''</center>
<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>


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


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/en/download-limesurvey-design-templates/com_josetta_menu_control_panel/viewcategory/9-survey-design-templates Template Repository]

=Creating a new Template= 


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.


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


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.


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


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.


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.

=The LimeSurvey Template Editor= 


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.


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.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The Template Menu== 


*'''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.
*'''Import Template:''' Allows you to import a template.
*'''Export Template:''' Allows you to export the current template to a .zip-File.
*'''Copy Template:''' Allows you to make a new template by copying the current one.
*'''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.


The "Screen" drop-down list on the right allows you to choose which particular survey page you are currently looking at.

==Import/Export/Copy a Template== 


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.


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.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl
*'''The Submit Page:''' startpage.pstpl, survey.pstpl, submit.pstpl, (privacy.pstpl), navigator.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag, even though many browsers do not require strict adherence to the W3 HTML 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.
*'''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)
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. 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.
*'''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.
*'''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
*'''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.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl endgroup.pstpl but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl but for the print version of the survey.

== CSS and Javascript== 


Two files are allways used for template : template.css for css and template.js for javascript.
*'''{TEMPLATECSS}:''' Add lines for default css, template.css and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js and all js files needed for LimeSurvey.

=== Replacing default css or javascript=== 


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.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''' and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the survey's settings. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages:'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In 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>


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

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. 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.


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:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/mypicture.jpg'</syntaxhighlight>
You can use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


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.


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

==Location of template files== 


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.


To create a new template, use the according icon in the template editor.


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.


You can use any image files that you upload into the template management area with syntax like this:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type now has a unique class. Mandatory question's also have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory but the user didn't answer it or if there is validation on a question


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied but the user hasn't answered correctly


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two class, but others can use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answer are question too, then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question type have multi list class: like checkbox with comment : class="checkbox-list text-list"
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .numeric-item
| The answer part of a numeric input
| Multi numeric question type, array of number
| <li class="numeric-item">, <td class="numeric-item">
|
|-
! scope="row" | .select-list
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .select-item
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .hide
| Used for accessibility: hidden with css but read by screenreader
| Short text question
| <label class="hide">
| Can be used for other purpose
|-
! scope="row" | .dontread
| Used for accessibility: not be read by screenreader
| Array question type
| <th class="dontread">
|
|-
! scope="row" | .checkbox
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .radio
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2
| Array question type
| Alternation for line
| <tr class="array1">
|
|}

=== Some example of question part with classes=== 


'''text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options, 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.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed, and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been med; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above 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.

==Internet Explorer conditional style sheets== 


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.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either /templates/default/ or /templates/limespired for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put conditional class for body in startpage.pstpl, and use this class in your template.css. This method is used in citronade template. Adding a js / no-js class to to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL Text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded 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}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself, to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{SUBMITBUTTON}||submit.pstpl||Displays the final submit button
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACY}||submit.pstpl||Displays privacy information when survey is anonymous
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{CLOSEWINDOW}||All Files (Preferably in navigator.pstpl)||URL to close current window
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file, and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes (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)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally you should use this to make sure that their font size and colour is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background colour for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the colour and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the colour and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


An example of using these classes with style sheets can be found in the "bubblegum" template that comes with the LimeSurvey application.


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.

==Styling the progress bar== 


'''Before version 1.87:'''


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.


'''Version 1.87 and newer:'''


The progress bar appearance can be modified with CSS.


To change the background colour of the bar, add something like the following to the end of your template.css file.


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border colour of the bar, add something like the following to the end of your template.css file.


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


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.

===Basic CMS Integration support=== 


<div class="simplebox">Deprecated: This function is not available anymore in version 2.0 or later</div>


To be able to integrate LimeSurvey into another CMS, use the following options in '''config.php''':


// Set $embedded to true and specify the header and footer functions if the survey is to be displayed embedded in a CMS


<nowiki>
$embedded = false;
$embedded_inc = ""; // path to the header to include if any
$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog
$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog
</nowiki>


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.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling each. This way a template author can create their own '''template_onload()''' function in the HEAD that replaces the default one.


'''Version 1.87 and newer:'''
*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.
*There are more details in the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|workaround section]].

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, customizing survey description page, and completed page.


[http://youtu.be/Uk3FQyDTIY0 LimeSurvey training video - template customization]

=Tips & Tricks= 

==Some language specific element== 


If you want to have some language 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 language. And hidding it in the template.css, we can use pseudo selector :lang, but for best compatibility, we use some class.


Example for a help sentence at bottom of the page, in french and english, put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>


You can use it to for other sentence in your question before 1.92 ( in 1.92, there are better solutions).

==Change the layout of the survey page== 


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.


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

==Import/Export of templates: Mac users== 


Mac users, please note: Mac OSX default archive utility may have problems with zip folders "generated on the fly".


a work around is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


or scripts in their mac-compiled counterparts:


http://homepage.mac.com/roger_jolly/software/

==Changing your templates traffic light from red to green== 


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


GO to file directory ie file manager, find templates directory.


1 change permission on eg"vallendar" (or any template of your choice) directory to read 777


2 voila! the red traffic light on "vallendar" is now green.


3 NOTE: to restrict access for safety, when finished editing template files, change all templates files back to what they were eg 644

==Replacing the help icon== 


When a question help text is shown then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It then will be automatically used instead of the default help icon.

==Replacing an existing logo== 


'''Note''': Before uploading a new logo always delete the old, existing one!


1. To edit the logo go to the &bdquo;<u>template.css</u>” file which you can find it here:


[[File:t1.PNG|200px]]


2. Click the search button to find occurrences of logo related styles.


[[File:2.png|200px]]


3. Search for <u>#logo</u>


[[File:3.PNG|200px]]


4. Edit the main style file


You will see something similar to:


[[File:t4.PNG|500px]]


If you want to change the image just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want change the image size adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo== 


1. Find and open the &bdquo;<u>startpage.pstpl</u>” template file.


[[File:5.PNG|200px]]


2. After the <source lang="html4strict" ><body ... ></source> tag add this line to &bdquo;<u>startpage.pstpl</u>”:
<source lang="html4strict"><img id="page_logo" src="{TEMPLATEURL}logo.png"><br></source>


3. To add logo go to &bdquo;<u>template.css</u>”, you can find it here (see in screen):


[[File:6.PNG|500px]]


3.1 Then go to the end of the main &bdquo;<u>template.css</u>” style file.


3.2 To align the logo add...


'''If you want the logo to be placed at left side:'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
float:left;
}</syntaxhighlight>


'''If you want the logo to be placed at right side:'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
float:right;
}</syntaxhighlight>


'''If you want to center the logo'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
display: block;
margin-left: auto;
margin-right: auto;
}</syntaxhighlight>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip)== 


There are 3 solutions to remove the default help:
# like a [[Advanced question settings#hide_tip|hide_tip attribute]] but for all question and survey.
# you can remove the {QUESTIONHELP} and is container from the file question.pstl, but it can be a bad idea for screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators
#Name your new favicon "favicon.ico" and place it in your template directory
#Add the following code to your '''startpage.pstpl''' before the </head> tag


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


(''Version 1.91 and newer'')


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.


example from default template of LimeSurvey 1.91+


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


To '''not''' differentiate even and odd pages at the (default) template find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


header_separator is used to adress the separator for the header "td" and "dual_scale_separator" is used to adress the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list== 


To hide the "Please contact ..." message on the start page (with the survey list) you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


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


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages== 


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:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for an englisch survey and have to be extended when using for multilingual surveys. But it's an idea/tip how to solve this.

==How to deal with multilingual question attributes (before version 2.0 at which those were added)== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other"


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


At the template.css of your template (at /limesurvey/upload/templates/<yourtemplatename>/template.css) add:


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

</translate>

Theme editor

2013-10-12T01:55:37Z

Nery:

<languages /> <translate>

=Introduction= 


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.


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.


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:


<syntaxhighlight lang="html4strict" enclose="div"><center><font face='verdana' color='red'>{SURVEYNAME}</font><br />
<font face='verdana' color='blue'><u>{SURVEYDESCRIPTION}</u></center>
</syntaxhighlight>


One gets a result that looks like:


<div class="simplebox"><center>'''<span style='color:red'>My New Survey</span>'''</center>
<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>


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


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/en/download-limesurvey-design-templates/com_josetta_menu_control_panel/viewcategory/9-survey-design-templates Template Repository]

=Creating a new Template= 


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.


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


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.


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


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.


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.

=The LimeSurvey Template Editor= 


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.


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.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The Template Menu== 


*'''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.
*'''Import Template:''' Allows you to import a template.
*'''Export Template:''' Allows you to export the current template to a .zip-File.
*'''Copy Template:''' Allows you to make a new template by copying the current one.
*'''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.


The "Screen" drop-down list on the right allows you to choose which particular survey page you are currently looking at.

==Import/Export/Copy a Template== 


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.


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.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl
*'''The Submit Page:''' startpage.pstpl, survey.pstpl, submit.pstpl, (privacy.pstpl), navigator.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag, even though many browsers do not require strict adherence to the W3 HTML 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.
*'''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)
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. 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.
*'''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.
*'''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
*'''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.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl endgroup.pstpl but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl but for the print version of the survey.

== CSS and Javascript== 


Two files are allways used for template : template.css for css and template.js for javascript.
*'''{TEMPLATECSS}:''' Add lines for default css, template.css and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js and all js files needed for LimeSurvey.

=== Replacing default css or javascript=== 


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.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''' and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the survey's settings. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages:'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In 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>


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

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. 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.


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:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/mypicture.jpg'</syntaxhighlight>
You can use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


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.


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

==Location of template files== 


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.


To create a new template, use the according icon in the template editor.


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.


You can use any image files that you upload into the template management area with syntax like this:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type now has a unique class. Mandatory question's also have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory but the user didn't answer it or if there is validation on a question


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied but the user hasn't answered correctly


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two class, but others can use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answer are question too, then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question type have multi list class: like checkbox with comment : class="checkbox-list text-list"
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .numeric-item
| The answer part of a numeric input
| Multi numeric question type, array of number
| <li class="numeric-item">, <td class="numeric-item">
|
|-
! scope="row" | .select-list
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .select-item
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .hide
| Used for accessibility: hidden with css but read by screenreader
| Short text question
| <label class="hide">
| Can be used for other purpose
|-
! scope="row" | .dontread
| Used for accessibility: not be read by screenreader
| Array question type
| <th class="dontread">
|
|-
! scope="row" | .checkbox
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .radio
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2
| Array question type
| Alternation for line
| <tr class="array1">
|
|}

=== Some example of question part with classes=== 


'''text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options, 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.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed, and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been med; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above 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.

==Internet Explorer conditional style sheets== 


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.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either /templates/default/ or /templates/limespired for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put conditional class for body in startpage.pstpl, and use this class in your template.css. This method is used in citronade template. Adding a js / no-js class to to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL Text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded 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}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself, to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{SUBMITBUTTON}||submit.pstpl||Displays the final submit button
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACY}||submit.pstpl||Displays privacy information when survey is anonymous
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{CLOSEWINDOW}||All Files (Preferably in navigator.pstpl)||URL to close current window
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file, and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes (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)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally you should use this to make sure that their font size and colour is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background colour for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the colour and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the colour and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


An example of using these classes with style sheets can be found in the "bubblegum" template that comes with the LimeSurvey application.


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.

==Styling the progress bar== 


'''Before version 1.87:'''


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.


'''Version 1.87 and newer:'''


The progress bar appearance can be modified with CSS.


To change the background colour of the bar, add something like the following to the end of your template.css file.


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border colour of the bar, add something like the following to the end of your template.css file.


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


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.

===Basic CMS Integration support=== 


<div class="simplebox">Deprecated: This function is not available anymore in version 2.0 or later</div>


To be able to integrate LimeSurvey into another CMS, use the following options in '''config.php''':


// Set $embedded to true and specify the header and footer functions if the survey is to be displayed embedded in a CMS


<nowiki>
$embedded = false;
$embedded_inc = ""; // path to the header to include if any
$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog
$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog
</nowiki>


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.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling each. This way a template author can create their own '''template_onload()''' function in the HEAD that replaces the default one.


'''Version 1.87 and newer:'''
*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.
*There are more details in the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|workaround section]].

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, customizing survey description page, and completed page.


[http://youtu.be/Uk3FQyDTIY0 LimeSurvey training video - template customization]

=Tips & Tricks= 

==Some language specific element== 


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.


Example for a help sentence at bottom of the page, in french an english, put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>


You can use it to for other sentence in your question before 1.92 ( in 1.92, there are better solutions).

==Change the layout of the survey page== 


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.


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

==Import/Export of templates: Mac users== 


Mac users, please note: Mac OSX default archive utility may have problems with zip folders "generated on the fly".


a work around is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


or scripts in their mac-compiled counterparts:


http://homepage.mac.com/roger_jolly/software/

==Changing your templates traffic light from red to green== 


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


GO to file directory ie file manager, find templates directory.


1 change permission on eg"vallendar" (or any template of your choice) directory to read 777


2 voila! the red traffic light on "vallendar" is now green.


3 NOTE: to restrict access for safety, when finished editing template files, change all templates files back to what they were eg 644

==Replacing the help icon== 


When a question help text is shown then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It then will be automatically used instead of the default help icon.

==Replacing an existing logo== 


'''Note''': Before uploading a new logo always delete the old, existing one!


1. To edit the logo go to the &bdquo;<u>template.css</u>” file which you can find it here:


[[File:t1.PNG|200px]]


2. Click the search button to find occurrences of logo related styles.


[[File:2.png|200px]]


3. Search for <u>#logo</u>


[[File:3.PNG|200px]]


4. Edit the main style file


You will see something similar to:


[[File:t4.PNG|500px]]


If you want to change the image just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want change the image size adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo== 


1. Find and open the &bdquo;<u>startpage.pstpl</u>” template file.


[[File:5.PNG|200px]]


2. After the <source lang="html4strict" ><body ... ></source> tag add this line to &bdquo;<u>startpage.pstpl</u>”:
<source lang="html4strict"><img id="page_logo" src="{TEMPLATEURL}logo.png"><br></source>


3. To add logo go to &bdquo;<u>template.css</u>”, you can find it here (see in screen):


[[File:6.PNG|500px]]


3.1 Then go to the end of the main &bdquo;<u>template.css</u>” style file.


3.2 To align the logo add...


'''If you want the logo to be placed at left side:'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
float:left;
}</syntaxhighlight>


'''If you want the logo to be placed at right side:'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
float:right;
}</syntaxhighlight>


'''If you want to center the logo'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
display: block;
margin-left: auto;
margin-right: auto;
}</syntaxhighlight>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip)== 


There are 3 solutions to remove the default help:
# like a [[Advanced question settings#hide_tip|hide_tip attribute]] but for all question and survey.
# you can remove the {QUESTIONHELP} and is container from the file question.pstl, but it can be a bad idea for screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators
#Name your new favicon "favicon.ico" and place it in your template directory
#Add the following code to your '''startpage.pstpl''' before the </head> tag


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


(''Version 1.91 and newer'')


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.


example from default template of LimeSurvey 1.91+


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


To '''not''' differentiate even and odd pages at the (default) template find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


header_separator is used to adress the separator for the header "td" and "dual_scale_separator" is used to adress the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list== 


To hide the "Please contact ..." message on the start page (with the survey list) you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


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


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages== 


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:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for an englisch survey and have to be extended when using for multilingual surveys. But it's an idea/tip how to solve this.

==How to deal with multilingual question attributes (before version 2.0 at which those were added)== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other"


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


At the template.css of your template (at /limesurvey/upload/templates/<yourtemplatename>/template.css) add:


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

</translate>

Theme editor

2013-10-12T01:47:17Z

Nery:

<languages /> <translate>

=Introduction= 


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.


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.


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:


<syntaxhighlight lang="html4strict" enclose="div"><center><font face='verdana' color='red'>{SURVEYNAME}</font><br />
<font face='verdana' color='blue'><u>{SURVEYDESCRIPTION}</u></center>
</syntaxhighlight>


One gets a result that looks like:


<div class="simplebox"><center>'''<span style='color:red'>My New Survey</span>'''</center>
<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>


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


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/en/download-limesurvey-design-templates/com_josetta_menu_control_panel/viewcategory/9-survey-design-templates Template Repository]

=Creating a new Template= 


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.


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


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.


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


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.


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.

=The LimeSurvey Template Editor= 


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.


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.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The Template Menu== 


*'''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.
*'''Import Template:''' Allows you to import a template.
*'''Export Template:''' Allows you to export the current template to a .zip-File.
*'''Copy Template:''' Allows you to make a new template by copying the current one.
*'''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.


The "Screen" drop-down list on the right allows you to choose which particular survey page you are currently looking at.

==Import/Export/Copy a Template== 


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.


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.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl
*'''The Submit Page:''' startpage.pstpl, survey.pstpl, submit.pstpl, (privacy.pstpl), navigator.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag, even though many browsers do not require strict adherence to the W3 HTML 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.
*'''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)
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. 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.
*'''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.
*'''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
*'''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.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl endgroup.pstpl but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl but for the print version of the survey.

== CSS and Javascript== 


Two files are allways used for template : template.css for css and template.js for javascript.
*'''{TEMPLATECSS}:''' Add lines for default css, template.css and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js and all js files needed for LimeSurvey.

=== Replacing default css or javascript=== 


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.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''' and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the survey's settings. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages:'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In 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>


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

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. 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.


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:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/mypicture.jpg'</syntaxhighlight>
You can use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


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.


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

==Location of template files== 


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.


To create a new template, use the according icon in the template editor.


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.


You can use any image files that you upload into the template management area with syntax like this:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type now has a unique class. Mandatory question's also have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory but the user didn't answer it or if there is validation on a question


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied but the user hasn't answered correctly


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two class, but others can use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answer are question too, then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question type have multi list class: like checkbox with comment : class="checkbox-list text-list"
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .numeric-item
| The answer part of a numeric input
| Multi numeric question type, array of number
| <li class="numeric-item">, <td class="numeric-item">
|
|-
! scope="row" | .select-list
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .select-item
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .hide
| Used for accessibility: hidden with css but read by screenreader
| Short text question
| <label class="hide">
| Can be used for other purpose
|-
! scope="row" | .dontread
| Used for accessibility: not be read by screenreader
| Array question type
| <th class="dontread">
|
|-
! scope="row" | .checkbox
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .radio
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2
| Array question type
| Alternation for line
| <tr class="array1">
|
|}

=== Some example of question part with classes=== 


'''text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options, 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.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed, and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been med; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, You should be able to copy everything after the above 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.

==Internet Explorer conditional style sheets== 


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.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either /templates/default/ or /templates/limespired for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put conditional class for body in startpage.pstpl, and use this class in your template.css. This method is used in citronade template. Adding a js / no-js class to to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL Text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded 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}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself, to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{SUBMITBUTTON}||submit.pstpl||Displays the final submit button
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACY}||submit.pstpl||Displays privacy information when survey is anonymous
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{CLOSEWINDOW}||All Files (Preferably in navigator.pstpl)||URL to close current window
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file, and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes (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)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally you should use this to make sure that their font size and colour is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background colour for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the colour and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the colour and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


An example of using these classes with style sheets can be found in the "bubblegum" template that comes with the LimeSurvey application.


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.

==Styling the progress bar== 


'''Before version 1.87:'''


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.


'''Version 1.87 and newer:'''


The progress bar appearance can be modified with CSS.


To change the background colour of the bar, add something like the following to the end of your template.css file.


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border colour of the bar, add something like the following to the end of your template.css file.


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


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.

===Basic CMS Integration support=== 


<div class="simplebox">Deprecated: This function is not available anymore in version 2.0 or later</div>


To be able to integrate LimeSurvey into another CMS, use the following options in '''config.php''':


// Set $embedded to true and specify the header and footer functions if the survey is to be displayed embedded in a CMS


<nowiki>
$embedded = false;
$embedded_inc = ""; // path to the header to include if any
$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog
$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog
</nowiki>


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.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling each. This way a template author can create their own '''template_onload()''' function in the HEAD that replaces the default one.


'''Version 1.87 and newer:'''
*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.
*There are more details in the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|workaround section]].

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, customizing survey description page, and completed page.


[http://youtu.be/Uk3FQyDTIY0 LimeSurvey training video - template customization]

=Tips & Tricks= 

==Some language specific element== 


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.


Example for a help sentence at bottom of the page, in french an english, put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>


You can use it to for other sentence in your question before 1.92 ( in 1.92, there are better solutions).

==Change the layout of the survey page== 


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.


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

==Import/Export of templates: Mac users== 


Mac users, please note: Mac OSX default archive utility may have problems with zip folders "generated on the fly".


a work around is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


or scripts in their mac-compiled counterparts:


http://homepage.mac.com/roger_jolly/software/

==Changing your templates traffic light from red to green== 


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


GO to file directory ie file manager, find templates directory.


1 change permission on eg"vallendar" (or any template of your choice) directory to read 777


2 voila! the red traffic light on "vallendar" is now green.


3 NOTE: to restrict access for safety, when finished editing template files, change all templates files back to what they were eg 644

==Replacing the help icon== 


When a question help text is shown then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It then will be automatically used instead of the default help icon.

==Replacing an existing logo== 


'''Note''': Before uploading a new logo always delete the old, existing one!


1. To edit the logo go to the &bdquo;<u>template.css</u>” file which you can find it here:


[[File:t1.PNG|200px]]


2. Click the search button to find occurrences of logo related styles.


[[File:2.png|200px]]


3. Search for <u>#logo</u>


[[File:3.PNG|200px]]


4. Edit the main style file


You will see something similar to:


[[File:t4.PNG|500px]]


If you want to change the image just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want change the image size adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo== 


1. Find and open the &bdquo;<u>startpage.pstpl</u>” template file.


[[File:5.PNG|200px]]


2. After the <source lang="html4strict" ><body ... ></source> tag add this line to &bdquo;<u>startpage.pstpl</u>”:
<source lang="html4strict"><img id="page_logo" src="{TEMPLATEURL}logo.png"><br></source>


3. To add logo go to &bdquo;<u>template.css</u>”, you can find it here (see in screen):


[[File:6.PNG|500px]]


3.1 Then go to the end of the main &bdquo;<u>template.css</u>” style file.


3.2 To align the logo add...


'''If you want the logo to be placed at left side:'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
float:left;
}</syntaxhighlight>


'''If you want the logo to be placed at right side:'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
float:right;
}</syntaxhighlight>


'''If you want to center the logo'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
display: block;
margin-left: auto;
margin-right: auto;
}</syntaxhighlight>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip)== 


There are 3 solutions to remove the default help:
# like a [[Advanced question settings#hide_tip|hide_tip attribute]] but for all question and survey.
# you can remove the {QUESTIONHELP} and is container from the file question.pstl, but it can be a bad idea for screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators
#Name your new favicon "favicon.ico" and place it in your template directory
#Add the following code to your '''startpage.pstpl''' before the </head> tag


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


(''Version 1.91 and newer'')


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.


example from default template of LimeSurvey 1.91+


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


To '''not''' differentiate even and odd pages at the (default) template find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


header_separator is used to adress the separator for the header "td" and "dual_scale_separator" is used to adress the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list== 


To hide the "Please contact ..." message on the start page (with the survey list) you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


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


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages== 


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:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for an englisch survey and have to be extended when using for multilingual surveys. But it's an idea/tip how to solve this.

==How to deal with multilingual question attributes (before version 2.0 at which those were added)== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other"


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


At the template.css of your template (at /limesurvey/upload/templates/<yourtemplatename>/template.css) add:


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

</translate>

Theme editor

2013-10-12T01:36:28Z

Nery:

<languages /> <translate>

=Introduction= 


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.


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.


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:


<syntaxhighlight lang="html4strict" enclose="div"><center><font face='verdana' color='red'>{SURVEYNAME}</font><br />
<font face='verdana' color='blue'><u>{SURVEYDESCRIPTION}</u></center>
</syntaxhighlight>


One gets a result that looks like:


<div class="simplebox"><center>'''<span style='color:red'>My New Survey</span>'''</center>
<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>


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


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/en/download-limesurvey-design-templates/com_josetta_menu_control_panel/viewcategory/9-survey-design-templates Template Repository]

=Creating a new Template= 


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.


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


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.


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


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.


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.

=The LimeSurvey Template Editor= 


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.


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.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The Template Menu== 


*'''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.
*'''Import Template:''' Allows you to import a template.
*'''Export Template:''' Allows you to export the current template to a .zip-File.
*'''Copy Template:''' Allows you to make a new template by copying the current one.
*'''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.


The "Screen" drop-down list on the right allows you to choose which particular survey page you are currently looking at.

==Import/Export/Copy a Template== 


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.


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.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl
*'''The Submit Page:''' startpage.pstpl, survey.pstpl, submit.pstpl, (privacy.pstpl), navigator.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag, even though many browsers do not require strict adherence to the W3 HTML 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.
*'''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)
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. 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.
*'''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.
*'''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
*'''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.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl endgroup.pstpl but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl but for the print version of the survey.

== CSS and Javascript== 


Two files are allways used for template : template.css for css and template.js for javascript.
*'''{TEMPLATECSS}:''' Add lines for default css, template.css and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js and all js files needed for LimeSurvey.

=== Replacing default css or javascript=== 


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.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''' and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the survey's settings. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages:'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In 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>


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

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. 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.


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:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/mypicture.jpg'</syntaxhighlight>
You can use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


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.


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

==Location of template files== 


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.


To create a new template, use the according icon in the template editor.


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.


You can use any image files that you upload into the template management area with syntax like this:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type now has a unique class. Mandatory question's also have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory but the user didn't answer it or if there is validation on a question


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied but the user hasn't answered correctly


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


This class are used for each question type. Some question type use only one or two class, but other can use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answer are question too, then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question type have multi list class: like checkbox with comment : class="checkbox-list text-list"
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .numeric-item
| The answer part of a numeric input
| Multi numeric question type, array of number
| <li class="numeric-item">, <td class="numeric-item">
|
|-
! scope="row" | .select-list
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .select-item
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .hide
| Used for accessibility: hidden with css but read by screenreader
| Short text question
| <label class="hide">
| Can be used for other purpose
|-
! scope="row" | .dontread
| Used for accessibility: not be read by screenreader
| Array question type
| <th class="dontread">
|
|-
! scope="row" | .checkbox
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .radio
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .odd .even
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2
| Array question type
| Alternation for line
| <tr class="array1">
|
|}

=== Some example of question part with classes=== 


'''text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options, 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.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed, and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been med; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, You should be able to copy everything after the above 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.

==Internet Explorer conditional style sheets== 


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.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either /templates/default/ or /templates/limespired for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put conditional class for body in startpage.pstpl, and use this class in your template.css. This method is used in citronade template. Adding a js / no-js class to to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL Text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded 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}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself, to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{SUBMITBUTTON}||submit.pstpl||Displays the final submit button
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACY}||submit.pstpl||Displays privacy information when survey is anonymous
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{CLOSEWINDOW}||All Files (Preferably in navigator.pstpl)||URL to close current window
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file, and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes (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)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally you should use this to make sure that their font size and colour is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background colour for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the colour and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the colour and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


An example of using these classes with style sheets can be found in the "bubblegum" template that comes with the LimeSurvey application.


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.

==Styling the progress bar== 


'''Before version 1.87:'''


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.


'''Version 1.87 and newer:'''


The progress bar appearance can be modified with CSS.


To change the background colour of the bar, add something like the following to the end of your template.css file.


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border colour of the bar, add something like the following to the end of your template.css file.


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


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.

===Basic CMS Integration support=== 


<div class="simplebox">Deprecated: This function is not available anymore in version 2.0 or later</div>


To be able to integrate LimeSurvey into another CMS, use the following options in '''config.php''':


// Set $embedded to true and specify the header and footer functions if the survey is to be displayed embedded in a CMS


<nowiki>
$embedded = false;
$embedded_inc = ""; // path to the header to include if any
$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog
$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog
</nowiki>


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.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling each. This way a template author can create their own '''template_onload()''' function in the HEAD that replaces the default one.


'''Version 1.87 and newer:'''
*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.
*There are more details in the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|workaround section]].

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, customizing survey description page, and completed page.


[http://youtu.be/Uk3FQyDTIY0 LimeSurvey training video - template customization]

=Tips & Tricks= 

==Some language specific element== 


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.


Example for a help sentence at bottom of the page, in french an english, put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>


You can use it to for other sentence in your question before 1.92 ( in 1.92, there are better solutions).

==Change the layout of the survey page== 


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.


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

==Import/Export of templates: Mac users== 


Mac users, please note: Mac OSX default archive utility may have problems with zip folders "generated on the fly".


a work around is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


or scripts in their mac-compiled counterparts:


http://homepage.mac.com/roger_jolly/software/

==Changing your templates traffic light from red to green== 


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


GO to file directory ie file manager, find templates directory.


1 change permission on eg"vallendar" (or any template of your choice) directory to read 777


2 voila! the red traffic light on "vallendar" is now green.


3 NOTE: to restrict access for safety, when finished editing template files, change all templates files back to what they were eg 644

==Replacing the help icon== 


When a question help text is shown then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It then will be automatically used instead of the default help icon.

==Replacing an existing logo== 


'''Note''': Before uploading a new logo always delete the old, existing one!


1. To edit the logo go to the &bdquo;<u>template.css</u>” file which you can find it here:


[[File:t1.PNG|200px]]


2. Click the search button to find occurrences of logo related styles.


[[File:2.png|200px]]


3. Search for <u>#logo</u>


[[File:3.PNG|200px]]


4. Edit the main style file


You will see something similar to:


[[File:t4.PNG|500px]]


If you want to change the image just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want change the image size adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo== 


1. Find and open the &bdquo;<u>startpage.pstpl</u>” template file.


[[File:5.PNG|200px]]


2. After the <source lang="html4strict" ><body ... ></source> tag add this line to &bdquo;<u>startpage.pstpl</u>”:
<source lang="html4strict"><img id="page_logo" src="{TEMPLATEURL}logo.png"><br></source>


3. To add logo go to &bdquo;<u>template.css</u>”, you can find it here (see in screen):


[[File:6.PNG|500px]]


3.1 Then go to the end of the main &bdquo;<u>template.css</u>” style file.


3.2 To align the logo add...


'''If you want the logo to be placed at left side:'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
float:left;
}</syntaxhighlight>


'''If you want the logo to be placed at right side:'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
float:right;
}</syntaxhighlight>


'''If you want to center the logo'''


<syntaxhighlight lang="php" enclose="div">#page_logo{
display: block;
margin-left: auto;
margin-right: auto;
}</syntaxhighlight>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip)== 


There are 3 solutions to remove the default help:
# like a [[Advanced question settings#hide_tip|hide_tip attribute]] but for all question and survey.
# you can remove the {QUESTIONHELP} and is container from the file question.pstl, but it can be a bad idea for screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators
#Name your new favicon "favicon.ico" and place it in your template directory
#Add the following code to your '''startpage.pstpl''' before the </head> tag


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


(''Version 1.91 and newer'')


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.


example from default template of LimeSurvey 1.91+


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


To '''not''' differentiate even and odd pages at the (default) template find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


header_separator is used to adress the separator for the header "td" and "dual_scale_separator" is used to adress the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list== 


To hide the "Please contact ..." message on the start page (with the survey list) you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


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


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages== 


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:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for an englisch survey and have to be extended when using for multilingual surveys. But it's an idea/tip how to solve this.

==How to deal with multilingual question attributes (before version 2.0 at which those were added)== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other"


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


At the template.css of your template (at /limesurvey/upload/templates/<yourtemplatename>/template.css) add:


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

</translate>

Alternatives to the LimeSurvey import function

2013-10-10T21:59:21Z

Nery:

<languages />
<translate>

__TOC__

=Import using the administration interface= 


If you have previously exported a survey structure, you can import it from the "Create, import, or copy survey" screen. Click on the import button. Click on the browse button to choose the file, and then click on the button. The import process reads the following formats:
*.LSA files, .TXT files
*v1.50 or later .CSV files created by LimeSurvey
*v1.90 or later .LSS files created by LimeSurvey


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.

=Import using the commandline utility= 


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.


This functionality is useful when you have timeout problems with the web version that could happen when you have very long surveys to import.


To use it, in the shell go to the limesurvey/admin folder and execute:


php cmdline_importsurvey <File to import> <nowiki>[</nowiki><user> <password>]


*<File to import> has to be one of the described above
*<user> has to be a user with the right to create surveys
*<password> the password for the user <br />*<user> and <password> are only required if the control access is active


If you need to see the parameters you can execute:


php cmdline_importsurvey -h

=Importing surveys from other applications= 


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 proprietary software or providers can be a bad idea in the first place.
</translate>

Expression Manager

2013-10-10T14:46:46Z

Nery:

<languages /> <translate>


__TOC__


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

=Quick Start Tutorial= 

==Overview== 


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


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


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

==Relevance (Controlling Navigation/Branching)== 


Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses 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).


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


[[File:tutorial1.jpg]]


Relevance is shown and editable in the following places:

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


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


[[File:tutorial2.jpg]]


This is the edit screen for the BMI question.


[[File:tutorial3.jpg]]


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

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


This is a sample census survey. The first page asks how many people live with you and stores that in the "cohabs" variable. This page is only shown if you have more than one cohabitant (so it is shown for the second person cohabitating with you), and also only shows if you specified how Person One is related to you (p1_rel).


[[File:tutorial4.jpg]]


As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}). EM combines the Group and Question-level relevance for you. Questions in a group are only asked if the group as a whole is relevant. Then, only the subset of questions within the group that are relevant are asked.


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


[[File:tutorial5.jpg]]


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

==Tailoring/Piping== 


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

===Conditional Equations=== 


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


[[File:tailoring7.jpg]]


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


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


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


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


[[File:tailoring8.jpg]]


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


[[File:tailoring9.jpg]]

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


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


This example shows the BMI report.


[[File:tailoring10.jpg]]


Here is the edit window for the same question.


[[File:tailoring11.jpg]]


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


[[File:tailoring12.jpg]]


You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.


Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation== 


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


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


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

=Introduction= 


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


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

==Key Definitions== 
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?== 


The short answer is No (but also yes).


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


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


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

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


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


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

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


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


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


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

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


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

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


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

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


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


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

=Getting Started= 


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

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

==Conditions => Relevance== 


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

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


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

==Replacements => Micro-Tailoring== 


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

==Validation== 


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

==Equations== 


Equations were not supported without fancy JavaScript.

==Equation Question Type== 


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

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


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

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


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

===Relevance and Cascading Relevance=== 


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


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


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


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


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


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

===Group-Level Relevance=== 


Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first 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.

===Tailoring / Piping=== 


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


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

===Equations=== 


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


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

==Syntax== 


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


Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:


<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>


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


EM syntax follows normal operator precedence:


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


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

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


Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you 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.


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 "==")


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

==Access to Variables== 


Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5)
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question


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


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


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

=== Security issue=== 


For security issues, text entered by user are filtered. Some caracter are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming== 


Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:


QuestionCode . '_' . SubQuestionID . '_' . ScaleId


For comment and other, question code are QuestionCode_comment and QuestionCode_other


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

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


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


The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).


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


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


''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected.


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


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


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


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


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


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


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


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

==Access to Functions== 


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

===Implemented Functions=== 


The following functions are currently available:


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

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


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


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

==Expression Manager Knows Which Variables are Local== 


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

==Cascading Conditions== 


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


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

===Overriding Cascading Conditions=== 


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


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


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


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

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


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


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


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


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

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


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

=Syntax Highlighting= 


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

==Types and Meanings of Syntax Highlighting== 


{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||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.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||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.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||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 page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Relationship to LimeSurvey Ideas / Feature Requests= 


Expression Manager provides complete or partial solutions to each of the following:
*[http://ideas.limesurvey.org/ideatorrent/idea/1 Conditions]
*[http://ideas.limesurvey.org/ideatorrent/idea/3/ Answercounts]
*[http://ideas.limesurvey.org/ideatorrent/idea/5 Advanced reporting for assessments]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/6 Assessment reports]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/7 Store assessment results for further evaluation]
**Equations let one store the Assessment value in the database, completely solving this problem
*[http://ideas.limesurvey.org/ideatorrent/idea/22/ More advanced condition rules]
*[http://ideas.limesurvey.org/ideatorrent/idea/28 Open Answertable up so that we can alter formatting]
**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
*[http://ideas.limesurvey.org/ideatorrent/idea/37 Export survey results with full questions to include images]
**since Tailoring has access to the full question text, it can include images in the export
**if subjects choose Print Your Answers after finishing the survey, those printouts will be fully tailored
*[http://ideas.limesurvey.org/ideatorrent/idea/63 List of question codes and SGQA identifiers]
**The Show Survey Logic view shows that mapping (plus much more information)
**In addition, you no longer have to use SGQA codes to refer to variables - you can use the Question code/title.
*[http://ideas.limesurvey.org/ideatorrent/idea/69 Branch/jump to another question (earlier or later) based on current question]
**You can use the Navigation Index for this in most cases
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/86 set quota for total responses]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/101 Review all conditions]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/105 Review all questions + Review all groups]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/107 How to visualize questions, logic & conditions]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/113 Offline Surveys]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/120 Remove INSERTANS from question text at survey results]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/137 Informed Consent and Authorization Functionality]
**You can 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).
*[http://ideas.limesurvey.org/ideatorrent/idea/199 Show codes instead of of answers using INSERTANS]
**{Qcode} returns the code instead of the response text (which you can get via {INSERTANS:SGQA}, or {Qcode.shown})
*[http://ideas.limesurvey.org/ideatorrent/idea/204 Need group mean or calculations for assessments]
**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)}
**Computing the mean across a set of respondants would require extension of the Quota functionality.
*[http://ideas.limesurvey.org/ideatorrent/idea/222 To insert a language dependent text]
**Tailoring lets you conjugate verbs and decline nouns in each language
*[http://ideas.limesurvey.org/ideatorrent/idea/225 Surveyors should approve their answers]
**Custom Questions with tailoring, or the showAllResponsesExcept() function will let respondants 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.
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Suppliment to #answernnXnnXnnn method of targetting form elements]
**You can now refer to questions and answers by their Question Code, so there is no longer a need to modify SGQA values.
*[http://ideas.limesurvey.org/ideatorrent/idea/262 More flexibility with hidden questions]
*[http://ideas.limesurvey.org/ideatorrent/idea/265 Remove specific conditions from multiple questions]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/268 Cross Survey Reporting]
**By using question codes that are unique across your surveys and versions, you can consolidate data from multiple surveys and/or compare them
*[http://ideas.limesurvey.org/ideatorrent/idea/275 Simplifying integration with other tools]
**Expression Manager uses Question Codes instead of SGQA, making it easier to integrate with other tools.
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Expose assessment score to 3rd party app processing]
**This can be done with Equation question type
*[http://ideas.limesurvey.org/ideatorrent/idea/309 Multiple thank you pages]
**This can be supported via conditional relevance branching and tailoring

=Additional Reading= 

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]== 

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

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

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

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

</translate>

Expression Manager

2013-10-10T13:38:37Z

Nery:

<languages /> <translate>


__TOC__


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

=Quick Start Tutorial= 

==Overview== 


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


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


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

==Relevance (Controlling Navigation/Branching)== 


Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses 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).


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


[[File:tutorial1.jpg]]


Relevance is shown and editable in the following places:

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


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


[[File:tutorial2.jpg]]


This is the edit screen for the BMI question.


[[File:tutorial3.jpg]]


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

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


This is a sample census survey. The first page asks how many people live with you and stores that in the "cohabs" variable. This page is only shown if you have more than one cohabitant (so it is shown for the second person cohabitating with you), and also only shows if you specified how Person One is related to you (p1_rel).


[[File:tutorial4.jpg]]


As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}). EM combines the Group and Question-level relevance for you. Questions in a group are only asked if the group as a whole is relevant. Then, only the subset of questions within the group that are relevant are asked.


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


[[File:tutorial5.jpg]]


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

==Tailoring/Piping== 


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

===Conditional Equations=== 


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


[[File:tailoring7.jpg]]


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


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


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


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


[[File:tailoring8.jpg]]


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


[[File:tailoring9.jpg]]

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


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


This example shows the BMI report.


[[File:tailoring10.jpg]]


Here is the edit window for the same question.


[[File:tailoring11.jpg]]


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


[[File:tailoring12.jpg]]


You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.


Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation== 


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


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


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

=Introduction= 


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


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

==Key Definitions== 
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?== 


The short answer is No (but also yes).


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


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


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

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


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


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

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


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


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


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

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


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

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


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

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


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


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

=Getting Started= 


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

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

==Conditions => Relevance== 


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

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


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

==Replacements => Micro-Tailoring== 


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

==Validation== 


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

==Equations== 


Equations were not supported without fancy JavaScript.

==Equation Question Type== 


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

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


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

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


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

===Relevance and Cascading Relevance=== 


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


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


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


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


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


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

===Group-Level Relevance=== 


Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first 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.

===Tailoring / Piping=== 


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


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

===Equations=== 


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


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

==Syntax== 


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


Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:


<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>


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


EM syntax follows normal operator precedence:


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


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

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


Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you 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.


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 "==")


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

==Access to Variables== 


Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5)
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question


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


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


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

=== Security issue=== 


For security issues, text entered by user are filtered. Some caracter are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming== 


Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:


QuestionCode . '_' . SubQuestionID . '_' . ScaleId


For comment and other, question code are QuestionCode_comment and QuestionCode_other


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

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


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


The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).


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


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


''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected.


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


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


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


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


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


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


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


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

==Access to Functions== 


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

===Implemented Functions=== 


The following functions are currently available:


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

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


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


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

==Expression Manager Knows Which Variables are Local== 


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

==Cascading Conditions== 


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


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

===Overriding Cascading Conditions=== 


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


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


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


The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then 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.

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


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


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


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


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

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


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

=Syntax Highlighting= 


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

==Types and Meanings of Syntax Highlighting== 


{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||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.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||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.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||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 page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Relationship to LimeSurvey Ideas / Feature Requests= 


Expression Manager provides complete or partial solutions to each of the following:
*[http://ideas.limesurvey.org/ideatorrent/idea/1 Conditions]
*[http://ideas.limesurvey.org/ideatorrent/idea/3/ Answercounts]
*[http://ideas.limesurvey.org/ideatorrent/idea/5 Advanced reporting for assessments]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/6 Assessment reports]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/7 Store assessment results for further evaluation]
**Equations let one store the Assessment value in the database, completely solving this problem
*[http://ideas.limesurvey.org/ideatorrent/idea/22/ More advanced condition rules]
*[http://ideas.limesurvey.org/ideatorrent/idea/28 Open Answertable up so that we can alter formatting]
**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
*[http://ideas.limesurvey.org/ideatorrent/idea/37 Export survey results with full questions to include images]
**since Tailoring has access to the full question text, it can include images in the export
**if subjects choose Print Your Answers after finishing the survey, those printouts will be fully tailored
*[http://ideas.limesurvey.org/ideatorrent/idea/63 List of question codes and SGQA identifiers]
**The Show Survey Logic view shows that mapping (plus much more information)
**In addition, you no longer have to use SGQA codes to refer to variables - you can use the Question code/title.
*[http://ideas.limesurvey.org/ideatorrent/idea/69 Branch/jump to another question (earlier or later) based on current question]
**You can use the Navigation Index for this in most cases
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/86 set quota for total responses]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/101 Review all conditions]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/105 Review all questions + Review all groups]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/107 How to visualize questions, logic & conditions]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/113 Offline Surveys]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/120 Remove INSERTANS from question text at survey results]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/137 Informed Consent and Authorization Functionality]
**You can 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).
*[http://ideas.limesurvey.org/ideatorrent/idea/199 Show codes instead of of answers using INSERTANS]
**{Qcode} returns the code instead of the response text (which you can get via {INSERTANS:SGQA}, or {Qcode.shown})
*[http://ideas.limesurvey.org/ideatorrent/idea/204 Need group mean or calculations for assessments]
**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)}
**Computing the mean across a set of respondants would require extension of the Quota functionality.
*[http://ideas.limesurvey.org/ideatorrent/idea/222 To insert a language dependent text]
**Tailoring lets you conjugate verbs and decline nouns in each language
*[http://ideas.limesurvey.org/ideatorrent/idea/225 Surveyors should approve their answers]
**Custom Questions with tailoring, or the showAllResponsesExcept() function will let respondants 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.
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Suppliment to #answernnXnnXnnn method of targetting form elements]
**You can now refer to questions and answers by their Question Code, so there is no longer a need to modify SGQA values.
*[http://ideas.limesurvey.org/ideatorrent/idea/262 More flexibility with hidden questions]
*[http://ideas.limesurvey.org/ideatorrent/idea/265 Remove specific conditions from multiple questions]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/268 Cross Survey Reporting]
**By using question codes that are unique across your surveys and versions, you can consolidate data from multiple surveys and/or compare them
*[http://ideas.limesurvey.org/ideatorrent/idea/275 Simplifying integration with other tools]
**Expression Manager uses Question Codes instead of SGQA, making it easier to integrate with other tools.
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Expose assessment score to 3rd party app processing]
**This can be done with Equation question type
*[http://ideas.limesurvey.org/ideatorrent/idea/309 Multiple thank you pages]
**This can be supported via conditional relevance branching and tailoring

=Additional Reading= 

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]== 

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

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

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

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

</translate>

Expression Manager

2013-10-10T13:31:12Z

Nery:

<languages /> <translate>


__TOC__


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

=Quick Start Tutorial= 

==Overview== 


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


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


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

==Relevance (Controlling Navigation/Branching)== 


Some surveys use "Goto Logic", such that if you answer Question 1 with option C, then jump to Question 5. This approach is very limiting, since is hard to validate, and easily breaks if you have to re-order questions. EM uses 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).


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


[[File:tutorial1.jpg]]


Relevance is shown and editable in the following places:

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


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


[[File:tutorial2.jpg]]


This is the edit screen for the BMI question.


[[File:tutorial3.jpg]]


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

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


This is a sample census survey. The first page asks how many people live with you and stores that in the "cohabs" variable. This page is only shown if you have more than one cohabitant (so it is shown for the second person cohabitating with you), and also only shows if you specified how Person One is related to you (p1_rel).


[[File:tutorial4.jpg]]


As you can see, the group also has question-level relevance criteria, such that each question only appears once you have answered the question before it (e.g. {!is_empty(p1_sex)}). EM combines the Group and Question-level relevance for you. Questions in a group are only asked if the group as a whole is relevant. Then, only the subset of questions within the group that are relevant are asked.


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


[[File:tutorial5.jpg]]


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

==Tailoring/Piping== 


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

===Conditional Equations=== 


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


[[File:tailoring7.jpg]]


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


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


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


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


[[File:tailoring8.jpg]]


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


[[File:tailoring9.jpg]]

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


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


This example shows the BMI report.


[[File:tailoring10.jpg]]


Here is the edit window for the same question.


[[File:tailoring11.jpg]]


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


[[File:tailoring12.jpg]]


You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.


Please remember that all tailoring must surround expressions with Curly Braces, so that LimeSurvey knows which parts of the question are free text and which should be parsed through Expression Manager.

==Validation== 


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


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


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

=Introduction= 


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


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

==Key Definitions== 
#'''Expression''': Anything surrounded by curly braces
#*As long as there is no white space immediately after the opening brace or before the closing curly brace
#*The contents of Expressions are evaluted by EM, so they can contain mathematical formulas, functions, and complex string and date processing.
#'''Tailoring''': Sometimes called "piping", this is the process of conditionally modifying text
#*You have access to all 'replacement fields', TOKENs, and INSERTANS values
#*You also have easier access to questions, answers, and their properties.
#'''Relevance''' Equation: A new question attribute controlling question visiblity
#*If there is a relevance equation, then the question is only shown if the relevance evaluates to true.
#*Internally, all array_filter and array_filter_exclude commands become sub-question-level relevance
#'''Equation''' Question Type: A new question type that saves calculations or reports to the database
#*It is like a Boilerplate question, but its contents are saved to the database even if you set "Always Hide this Question"
#'''SGQA''': This is how variables are named in LimeSurvey <= 1.91+
#*Stands for Survey-Group-Question-Answer
#*SGQA variable names look like 123X5X382X971, and may have sub-question suffixes.
#*These variable names are specific to the underlying S/Q/G/A database codes, so often need to be changed
#'''Question Code''': This is the preferred variable name for EM
#*This can be a descriptive name indicating the purpose of the question, making it easier to read complex logic
#*Although not required to be unique in <= 1.91+, it must be unique if you want to use EM
#*Valid question codes should NOT start with a number, so when using the question code to number your questions, simply use "q1", or "q1a" or "g1q2".
#*This is what currently becomes the variable name if you export data to SPSS or R, so if you do statistical analysis, you probably already made this unique.

==Do I have to use EM?== 


The short answer is No (but also yes).


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


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


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

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


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


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

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


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


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


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

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


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

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


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

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


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


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

=Getting Started= 


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

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

==Conditions => Relevance== 


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

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


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

==Replacements => Micro-Tailoring== 


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

==Validation== 


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

==Equations== 


Equations were not supported without fancy JavaScript.

==Equation Question Type== 


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

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


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

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


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

===Relevance and Cascading Relevance=== 


Every question type now has a Relevance option which controls whether the question is displayed. EM processes each of the Relevance Equations in the order they should appear in the survey. If the expression is true (or missing - to support legacy surveys), the question will be 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.


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


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


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


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


As long as you are on the same page, any data you entered will still be there, just hidden. So, if you enter some information, then choose 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.

===Group-Level Relevance=== 


Expression Manager also supports group-level relevance. This makes it easier to implement looping. Say you want to collect information about up to 10 entities (such a products or people in a household), where you first 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.

===Tailoring / Piping=== 


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


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

===Equations=== 


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


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

==Syntax== 


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


Note, it is OK for expressions to span multiple lines, as long as there is no whitespace after the opening curly brace or before the closing curly brace. This is especially helpful for nested if() statements like this:


<syntaxhighlight lang="java" enclose="div">{if(is_empty(PFTotals),
'',
if(PFTotals >= -5 && PFTotals <= -4,
'Very Soft',
if(PFTotals >= -3 && PFTotals <= -2,
'Soft',
if(PFTotals == -1,
'Somewhat Soft',
if(PFTotals == 0,
'Moderate',
if(PFTotals == 1,
'Somewhat Hard',
if(PFTotals >= 2 && PFTotals <= 3,
'Hard',
if(PFTotals >= 4 && PFTotals <= 5,
'Very Hard',
''
)
)
)
)
)
)
)
)}
</syntaxhighlight>


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


EM syntax follows normal operator precedence:


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


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

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


Note, you should avoid using the assignment operators unless absolutely necessary, since they may cause unexpected side-effects. For example, if you change the value of a previous response, the cascading relevance and validation logic between that question and the current question is not re-computed, so you could end up with internally inconsistent data (e.g. questions that stay answered but should have been NULLed, or questions that are skipped but should have been answered). In general, if you want to assign a value to a variable, you 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.


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 "==")


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

==Access to Variables== 


Expression Manager provides read-only access to whichever variables we might need. For backwards compatibility, it provides access to the following:
*TOKEN:xxx - the value of a TOKEN (e.g. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5)
*INSERTANS:SGQA - the display value of an answer (e.g. "Yes")
*All {XXX} values used by templates
*In question text, you can use {QID} replaced by the question id and {SGQ} replaced by the SGQA of the question


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


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


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

=== Security issue=== 


For security issues, text entered by user are filtered. Some caracter are replaced by HTML entities.
* & by &amp;
* < by &lt;
* > by &gt;

==Qcode Variable Naming== 


Here are the details of how to construct a Qcode (and access some properties) by question type. In general, Qcodes are constructed as:


QuestionCode . '_' . SubQuestionID . '_' . ScaleId


For comment and other, question code are QuestionCode_comment and QuestionCode_other


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

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


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


The 'this' variable is used exclusively within the "Whole question validation equation" and "Sub-question validation equation" advanced question options. It expands to the variable names of each of the cells within those questions. So, if you want to make sure that each entry is greater than three, you would set the "Sub-question validation equation" to (this > 3).


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


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


''sub-selector'' is one of:
*comments - only subquestions that are comments (e.g. from multiple choice with comment and list with comment)
*nocomments - only subquestions that are not comments
*sq_X - where X is a row or column identifier. Only sub-questions matching pattern X are selected.


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


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


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


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


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


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


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


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

==Access to Functions== 


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

===Implemented Functions=== 


The following functions are currently available:


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

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


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


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

==Expression Manager Knows Which Variables are Local== 


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

==Cascading Conditions== 


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


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

===Overriding Cascading Conditions=== 


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


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


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


The use of the .NAOK suffix also lets authors design surveys that have several possible paths but then 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.

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


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


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


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


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

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


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

=Syntax Highlighting= 


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

==Types and Meanings of Syntax Highlighting== 


{| class="wikitable"
!Color!!Sample!!Meaning!!Tooltip!!Comments
|-
|tan background||style='background-color: #eee8aa'|Sample||the whole equation||none||Anything within curly braces that is recognized as an equation (e.g. there is no leading or trailing whitepace) will be color-coded with a tan background to help distinguish it from surrounding text
|-
|blue bold text||style='color:blue; background-color:#eee8aa'|'''Sample'''||function name||meaning and allowable syntax||function names, or things that should be functions since they are followed by an opening parenthesis, are presented in bold blue text. Tooltips show the meaning and allowable syntax for the function.
|-
|grey text||style='color:grey; background-color:#eee8aa'|Sample||string||none||single and double-quoted strings are shown in grey text
|-
|bold maroon text||style='color:maroon; background-color:#eee8aa'|'''Sample'''||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.
|-
|bold cyan text||style='color:#4C88BE; background-color:#eee8aa'|'''Sample'''||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.
|-
|bold green text||style='color:green; background-color:#eee8aa'|'''Sample'''||variable set on a prior page||<nowiki>[</nowiki>name or SGQA code]: question; value; answerList showing codes for each value||Any variable that is set on a prior page is shown in bold green text. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold pink text||style='color:#FF00FF; background-color:#eee8aa'|'''Sample'''||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 page is shown in bold pink text. These are erorrs since the variable is being used before it is declareed. The tooltip shows its name (if you used INSERTANS:xxx) or SGQA code (if you used the new naming system), the actual question, and its current value (or blank if not set). If the question type expects responses from an enumerated value set, the mapping of the codes to display values is show.
|-
|bold tan text||style='color:#996600; background-color:#eee8aa'|'''Sample'''||a lime replacement value||the value||Lime Replacement Strings (like {TOKEN:xxx}, {PRIVACY_MESSAGE}) are shown in bold tan text.
|-
|red text||style='color:red; background-color:#eee8aa'|Sample||assignment operator||warning message||If you use one of the assignment operator (=) that operator will be displayed in red text. This is meant to help prevent accidental re-assignment of values when you really meant to check whether a == b instead of setting the value of a = b.
|-
|normal black text||style='color:black; background-color:#eee8aa'|Sample||punctuation||none||All other punctuation within the expression is shown as normal black text.
|-
|red-boxed text||a bold red line surrounds the error||syntax error||description of the error||Any detected syntax errors are shown by surrounding the error with a red box. The tooltip shows the error. Examples include unmatched parentheses, use of undefined functions, passing the wrong number of arguments to functions, poorly structured expressions (e.g. missing operators between variables), trying to assign a new value to a read-only variable, trying to assign values to non-variables, or using unsupported syntax. Note that the syntax error dectection system may only report one error in an expression even if there are multiple errors; however, if any errors are detected, at least one error will be shown.
|}

=Relationship to LimeSurvey Ideas / Feature Requests= 


Expression Manager provides complete or partial solutions to each of the following:
*[http://ideas.limesurvey.org/ideatorrent/idea/1 Conditions]
*[http://ideas.limesurvey.org/ideatorrent/idea/3/ Answercounts]
*[http://ideas.limesurvey.org/ideatorrent/idea/5 Advanced reporting for assessments]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/6 Assessment reports]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/7 Store assessment results for further evaluation]
**Equations let one store the Assessment value in the database, completely solving this problem
*[http://ideas.limesurvey.org/ideatorrent/idea/22/ More advanced condition rules]
*[http://ideas.limesurvey.org/ideatorrent/idea/28 Open Answertable up so that we can alter formatting]
**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
*[http://ideas.limesurvey.org/ideatorrent/idea/37 Export survey results with full questions to include images]
**since Tailoring has access to the full question text, it can include images in the export
**if subjects choose Print Your Answers after finishing the survey, those printouts will be fully tailored
*[http://ideas.limesurvey.org/ideatorrent/idea/63 List of question codes and SGQA identifiers]
**The Show Survey Logic view shows that mapping (plus much more information)
**In addition, you no longer have to use SGQA codes to refer to variables - you can use the Question code/title.
*[http://ideas.limesurvey.org/ideatorrent/idea/69 Branch/jump to another question (earlier or later) based on current question]
**You can use the Navigation Index for this in most cases
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/86 set quota for total responses]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/101 Review all conditions]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/105 Review all questions + Review all groups]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/107 How to visualize questions, logic & conditions]
**The [[Show Logic File|Show Logic File]] view shows this (and much more)
*[http://ideas.limesurvey.org/ideatorrent/idea/113 Offline Surveys]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/120 Remove INSERTANS from question text at survey results]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/137 Informed Consent and Authorization Functionality]
**You can 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).
*[http://ideas.limesurvey.org/ideatorrent/idea/199 Show codes instead of of answers using INSERTANS]
**{Qcode} returns the code instead of the response text (which you can get via {INSERTANS:SGQA}, or {Qcode.shown})
*[http://ideas.limesurvey.org/ideatorrent/idea/204 Need group mean or calculations for assessments]
**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)}
**Computing the mean across a set of respondants would require extension of the Quota functionality.
*[http://ideas.limesurvey.org/ideatorrent/idea/222 To insert a language dependent text]
**Tailoring lets you conjugate verbs and decline nouns in each language
*[http://ideas.limesurvey.org/ideatorrent/idea/225 Surveyors should approve their answers]
**Custom Questions with tailoring, or the showAllResponsesExcept() function will let respondants 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.
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Suppliment to #answernnXnnXnnn method of targetting form elements]
**You can now refer to questions and answers by their Question Code, so there is no longer a need to modify SGQA values.
*[http://ideas.limesurvey.org/ideatorrent/idea/262 More flexibility with hidden questions]
*[http://ideas.limesurvey.org/ideatorrent/idea/265 Remove specific conditions from multiple questions]
**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.
*[http://ideas.limesurvey.org/ideatorrent/idea/268 Cross Survey Reporting]
**By using question codes that are unique across your surveys and versions, you can consolidate data from multiple surveys and/or compare them
*[http://ideas.limesurvey.org/ideatorrent/idea/275 Simplifying integration with other tools]
**Expression Manager uses Question Codes instead of SGQA, making it easier to integrate with other tools.
*[http://ideas.limesurvey.org/ideatorrent/idea/1.92 Expose assessment score to 3rd party app processing]
**This can be done with Equation question type
*[http://ideas.limesurvey.org/ideatorrent/idea/309 Multiple thank you pages]
**This can be supported via conditional relevance branching and tailoring

=Additional Reading= 

==[[Expression Manager Sample Surveys|Expression Manager Sample Surveys]]== 

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

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

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

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

</translate>

QS:Array filter exclude

2013-10-10T07:26:03Z

Nery:

<translate>

<languages />
<onlyinclude>

===Array exclusion filter (array_filter_exclude)=== 


'''Description'''


The Array filter exclusion advanced setting allows you to use a multiple choice question to select or set which responses '''won't''' display in a subsequent list, array or multiple choice question.


<div class="simplebox">Starting in 1.92, subsequent questions can be filtered on any array question types, including:
*Multiple choice
*Multiple choice with comments
*Multiple short text
*Multiple numeric
*Array (5 point, 10 point, Yes/No/Unknown, Increase/Same/Decrease, Column)
*Array (Dual Scale, Text, Numbers)
*Ranking


Furthermore, each of these types of questions can filtered.


The only exception is Array (Column), which can filter other questions, but can not itself be filtered.</div>


'''To set a filter'''


Enter the question code of a multiple options question to use as the source information. For example, if your source multiple option question code is "Q1" enter "Q1" into 'Array filter exclusion' input in the '''advanced settings''' of the question you want to filter.


<div class="simplebox">Starting in 1.92, you can enter multiple array_filter_exclude options for a single question, separated by semicolons</div>


The source question has to contain exactly the same list of answers/subquestion as the question you wish to filter. Your question will then only display those answers/subquestion that were not selected in the multiple options question.


If the questions do not have exactly the same set of answers/subquestions and codes, then the filters will break.


<div class="simplebox">Starting in 1.92, if Q2 has sub-questions that are not present in Q1, they will always be displayed rather than breaking the filters.</div>


'''Cascading'''


The Array filter exclusions settings will cascade – that is you can select a question which filters another question, which filters another question, and so on.


'''Example'''


Ticking items 'One' and 'Three' in the first question results in those questions not being displayed in the subsequent question which uses array filter exclusion


Multi Option Question


Code:Q1


Question: Which animals do you like?


1 Cat


2 Dog


3 Zebra


Array 5 Point Choice Question


</onlyinclude>


[[Category:Question Settings]][[Category:Advanced Question Settings]]

</translate>

How to join the LimeSurvey project team

2013-10-10T00:23:45Z

Nery:

<languages /> <translate>


__TOC__

=We need you!= 


So.. you think LimeSurvey is a great product and you would like to contribute?


Hey, you do not have to necessarily write code! You also could be a tester, translator, supporter or all of it. You are welcome! Or maybe you hacked a little in the source and created a nifty new feature and/or you would like to do future development in this project? We love you!

=How to become a LimeSurvey developer/translator/team member?= 

==Common requirements== 
*Be a team player, nice & polite.
*Communicate much and often with the other team members. Show up to the development meetings. Show up in our IRC channel ([irc://irc.freenode.net/limesurvey]) to get a glimpse what is going on.
*Share your thoughts. Don't be single minded. Discuss your ideas with the other team members.
*Real life comes first - but give us a small notice if and for how long you will be gone.
*Developers come and go in an open source project - that is absolutely normal. However if you leave the project please give us a notice and tell us how far you are, what you did and if there are things still to do so that someone else can pick up your work.
*Attend to the developers meeting which take place every Monday on 22:00 Berlin time on the channel #limesurvey-team on irc.freenode.org (ask Carsten Schmitz for the password - see below)

==First steps== 


If you agree to the above points please follow these steps:
#Create a personal account on the limesurvey.org website here (if you don't have one): [http://www.limesurvey.org/en/component/comprofiler/registers]
#Create a personal account on gitHub here (if you don't have one): [https://github.com/signup/free]
#Make sure you subscribe to the limesurvey-developer mailing list at [http://sourceforge.net/p/limesurvey/mailman/?source=navbar]. If you want to get notified of any changes in the development source code then subscribe to the limesurvey-git list too.
#If you use a Windows System get the Git client SmartGit (there are others but we recommend this one) to access the source code gitHub. You can download it from [http://www.syntevo.com/smartgithg/]
#Introduce yourself on the limesurvey-developer mailing list and provide the following information:
## A short resume (so we can see what your background is)
## Tell us why you would like to work in the LimeSurvey project ('I am bored to death!', 'I like your style...') (:wink:)
## Tell us in what area you would like to help (coding, patching, support etc.)
# Carsten Schmitz will get back to you as soon as possible. He is a very nice guy and will give you an introduction and will provide more information on the next steps.
# Visit the [http://www.limesurvey.org/en/community-services/live-chat official LimeSurvey IRC Channel] and SAY HELLO TO US!<br />([irc://irc.freenode.net/limesurvey])

==Additional information for new developers== 


LimeSurvey contains a lot of old and mess code - but by now we strictly pay attention to coding guidelines which are very important.


Coding Guidelines and Generic Code Implementation will help you and any developers working on your code at a later time by easier understanding your code and making it more modular.


To ensure this quality we are mentoring new developers using the following steps:
# At first we only assign small tasks to the new developer. What task is assigned will be decided together with the new developer.
# The developer sends the code to the mentor for review.
# If the mentor is satisfied with the code quality the developer may commit the code to the repository.
# Rinse and repeat Step 1 to 3 until the mentor states that the new developer is ready to submit patches freely to the repository.

==Additional information for new supporters== 


Giving support is a specialty since you are interacting with lots of different persons, friendly and not so friendly, strict or sloppy, eager or calm.


Therefore we have a special request to persons who give support in the channel or forums:
*'''Don't be caught by support burnout'''. It's nearly impossible to answer every technical question that is asked in the forum. In many cases, the problem doesn't lie in the technical aspects of the question; cultural barriers may get in the way of communication, or it may be difficult to explain to a newbie just where to begin. When you try to answer every question, regardless of difficulty, you set yourself up for support burnout. <br />Support burnout is nearly always accompanied by the feeling that you're losing control of your time, that the people you've set out to help are making unreasonable demands. The problem is that you're taking on too much responsibility; but it begins to appear instead that the problem is the end user who's asking for help.<br />Different people react to support burnout in different ways. Some offer malicious advice, some insist that every question a newbie asks should be answered with a URL or by lists of manual references. <br />Such arbitrary rule sets tend to grow longer over time, because they don't solve the real problem. You can't answer every question, and you shouldn't try. Be gentle, be courteous, be flexible and be as patient and helpful as you can - but let someone else try to answer questions that you find too frustrating. Don't try to be a superhuman support machine. Also leave room for user-to-user help. If you support every user and answer every question you do not necessarily boost the community thinking because too much activity takes away any other user motivation to help.

</translate>

How to join the LimeSurvey project team

2013-10-10T00:22:31Z

Nery:

<languages /> <translate>


__TOC__

=We need you!= 


So.. you think LimeSurvey is a great product and you would like to contribute?


Hey, you do not have to necessarily write code! You also could be a tester, translator, supporter or all of it. You are welcome! Or maybe you hacked a little in the source and created a nifty new feature and/or you would like to do future development in this project? We love you!

=How to become a LimeSurvey developer/translator/team member?= 

==Common requirements== 
*Be a team player, nice & polite.
*Communicate much and often with the other team members. Show up to the development meetings. Show up in our IRC channel ([irc://irc.freenode.net/limesurvey]) to get a glimpse what is going on.
*Share your thoughts. Don't be single minded. Discuss your ideas with the other team members.
*Real life comes first - but give us a small notice if and for how long you will be gone.
*Developers come and go in an open source project - that is absolutely normal. However if you leave the project please give us a notice and tell us how far you are, what you did and if there are things still to do so that someone else can pick up your work.
*Attend to the developers meeting which take place every Monday on 22:00 Berlin time on the channel #limesurvey-team on irc.freenode.org (ask Carsten Schmitz for the password - see below)

==First steps== 


If you agree to the above points please follow these steps:
#Create a personal account on the limesurvey.org website here (if you don't have one): [http://www.limesurvey.org/en/component/comprofiler/registers]
#Create a personal account on gitHub here (if you don't have one): [https://github.com/signup/free]
#Make sure you subscribe to the limesurvey-developer mailing list at [http://sourceforge.net/p/limesurvey/mailman/?source=navbar]. If you want to get notified of any changes in the development source code then subscribe to the limesurvey-git list too.
#If you use a Windows System get the Git client SmartGit (there are others but we recommend this one) to access the source code gitHub. You can download it from [http://www.syntevo.com/smartgithg/]
#Introduce yourself on the limesurvey-developer mailing list and provide the following information:
## A short resume (so we can see what your background is)
## Tell us why you would like to work in the LimeSurvey project ('I am bored to death!', 'I like your style...') (:wink:)
## Tell us in what area you would like to help (coding, patching, support etc.)
# Carsten Schmitz will get back to you as soon as possible. He is a very nice guy and will give you an introduction and will provide more information on the next steps.
# Visit the [http://www.limesurvey.org/en/community-services/live-chat official LimeSurvey IRC Channel] and SAY HELLO TO US!<br />([irc://irc.freenode.net/limesurvey])

==Additional information for new developers== 


LimeSurvey contains alot of old and mess code - but by now we strictly pay attention to coding guidelines which are very important.


Coding Guidelines and Generic Code Implementation will help you and any developers working on your code at a later time by easier understanding your code and making it more modular.


To ensure this quality we are mentoring new developers using the following steps:
# At first we only assign small tasks to the new developer. What task is assigned will be decided together with the new developer.
# The developer sends the code to the mentor for review.
# If the mentor is satisfied with the code quality the developer may commit the code to the repository.
# Rinse and repeat Step 1 to 3 until the mentor states that the new developer is ready to submit patches freely to the repository.

==Additional information for new supporters== 


Giving support is a specialty since you are interacting with lots of different persons, friendly and not so friendly, strict or sloppy, eager or calm.


Therefore we have a special request to persons who give support in the channel or forums:
*'''Don't be caught by support burnout'''. It's nearly impossible to answer every technical question that is asked in the forum. In many cases, the problem doesn't lie in the technical aspects of the question; cultural barriers may get in the way of communication, or it may be difficult to explain to a newbie just where to begin. When you try to answer every question, regardless of difficulty, you set yourself up for support burnout. <br />Support burnout is nearly always accompanied by the feeling that you're losing control of your time, that the people you've set out to help are making unreasonable demands. The problem is that you're taking on too much responsibility; but it begins to appear instead that the problem is the end user who's asking for help.<br />Different people react to support burnout in different ways. Some offer malicious advice, some insist that every question a newbie asks should be answered with a URL or by lists of manual references. <br />Such arbitrary rule sets tend to grow longer over time, because they don't solve the real problem. You can't answer every question, and you shouldn't try. Be gentle, be courteous, be flexible and be as patient and helpful as you can - but let someone else try to answer questions that you find too frustrating. Don't try to be a superhuman support machine. Also leave room for user-to-user help. If you support every user and answer every question you do not necessarily boost the community thinking because too much activity takes away any other user motivation to help.

</translate>

QS:Array filter exclude

2013-10-08T20:43:57Z

Nery:

<translate>

<languages />
<onlyinclude>

===Array exclusion filter (array_filter_exclude)=== 


'''Description'''


The Array filter exclusion advanced setting allows you to use a multiple choice question to select or set which responses '''won't''' display in a subsequent list, array or multiple choice question.


<div class="simplebox">Starting in 1.92, subsequent questions can be filtered on any array question types, including:
*Multiple choice
*Multiple choice with comments
*Multiple short text
*Multiple numeric
*Array (5 point, 10 point, Yes/No/Unknown, Increase/Same/Decrease, Column)
*Array (Dual Scale, Text, Numbers)
*Ranking


Furthermore, each of these types of questions can filtered.


The only exception is Array (Column), which can filter other questions, but can not itself be filtered.</div>


'''To set a filter'''


Enter the question code of a multiple options question to use as the source information. For example, if your source multiple option question code is "Q1" enter "Q1" into 'Array filter exclusion' input in the '''advanced settings''' of the question you want to filter.


<div class="simplebox">Starting in 1.92, you can enter multiple array_filter_exclude options for a single question, separated by semicolons</div>


The source question has to contain exactly the same list of answers/subquestion as the question you wish to filter. Your question will then only display those answers/subquestion that were not selected in the multiple options question.


If the questions do not have exactly the same set of answers/subquestions and codes, then the filters will break.


<div class="simplebox">Starting in 1.92, if Q2 has sub-questions that are not present in Q1, they will always be displayed rather than breaking the filters.</div>


'''Cascading'''


The Array filter exclusions settings will cascade – that is you can select a question which filters another question, which filters another question, and so on.


'''Example'''


Ticking items 'One' and 'Three' in the first question results in those questions not being displayed in the subsequent question which users array filter exclusion


Multi Option Question


Code:Q1


Question: Which animals do you like?


1 Cat


2 Dog


3 Zebra


Array 5 Point Choice Question


</onlyinclude>


[[Category:Question Settings]][[Category:Advanced Question Settings]]

</translate>

How to design a good survey (guide)

2013-10-06T15:10:37Z

Nery: /* Matrix questions. */

__TOC__

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

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

In this page, you'll find a simple guide to putting together a survey which will not only be painless for your audience to answer, but will give you meaningful answers too.

=Before making a survey.=

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

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

Based on that:
*'''Will a survey help me for this problem? '''
*'''How the survey can help me to answer the problem?'''
*'''Who are the right people to ask?'''
*'''How can you reach them?'''
*'''What is needed to make them understand your questions?'''
*'''Which - if any - are the statistical methods you want/need to use on the data?'''

These are just a few of the issues you need to be clear about to even decide weather LimeSurvey is the right tool for you. LimeSurvey is great for fully structured (you know all the questions you might need to ask before you start the interview), standardized (everyone gets more or less the same questionnaire), mostly quantitative (it is mainly about numbers or questions with predefined answers) questionnaires which are collected online.

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

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

==Structuring a questionnaire.==

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

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

Putting these ice breaking questions at the beginning might help to avoid participants to interrupt your survey as people might be less likely to terminate once they have already put some work into answering the questionnaire.

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

(single choice)

You can use Conditions, to make next question appear about cherries, if participant choosed answer ''cherries''.

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

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

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

(single choice)

Do you know any recipes releated to cherries?

[textfield]

</syntaxhighlight>

Above is an example of easy attractive questions followed by main question.

The point was to gather recipes releated to cherries, apples and bananas.

On the other hand.

If you need to ask problematic questions, you might think about using different pages (one page per group or one page per question) and putting theses questions at the very end. By this, if participants decide to interrupt, at least their former answers are saved.

Another aspect for structure is to avoid biases introduced by the questionnaire itself.

For example, in market research there are concepts which require unaided and aided questions. An example for an unaided question would be:

<syntaxhighlight lang="php" enclose="div">"Which brands of chocolate do you know?"

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

The corresponding example for an aided question would be:

<syntaxhighlight lang="php" enclose="div"> "Which of the following brands of chocolate do you know?"

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

If you would like to include both into the same questionnaire, you should again make sure to put them on different pages and put the unaided version before the aided on - otherwise you will basically teach or at least actively remind participants about existing brands which will invalidate your results for a following unaided question.

==Individual questions==

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

Example:

People may say '''"yes"''' to donate money if you ask the questions this way
* ''Do you love nature?''
* ''Will you donate money to help the river?''

But probably will say '''"no"''' if you ask the questions this way:
* ''Is lack of money a problem for you?''
* ''Will you donate money to help the river?''

To avoid this kind of thing, try to have your questions go:
*from the least sensitive to the most sensitive
*from the more general to the more specific
*from questions about facts to questions about opinions

Also, a survey question can be:
*'''Open-ended''' (the person can answer in any way they want), or
*'''Closed-ended''' (the person chooses from one of several options)

Closed ended questions are much easier to total up later on, but may stop people giving an answer they really want.

Example: "''What is your favorite color?''"

'''Open-ended''': Someone may answer "dark fuchsia", in which case you will need to have a category "dark fuchsia" in your results.

'''Closed-ended''': With a choice of only 12 colors your work will be easier, but they may not be able to pick their exact favorite color.

Look at each of your questions and decide if they should be open-ended or closed ended (take the opportunity to rewrite any questions, too)

Example: "''What do you think is the best way to clean up the river''?"

Make it '''Open-ended''': the answers won't be easy to put in a table or graph, but you may get some good ideas, and there may be some good quotes for your report.

Example: "''How often do you visit the river?''"

Make it '''Closed-ended''' with the following options:
*Nearly every day
*At least 5 times a year
*1 to 4 times a year
*Almost never

You will be able to present this data in a neat bar graph.

When working with multiple choices or single choice questions make sure to choose the right one and formulate both question and answers appropriately.

'''For example:'''

<syntaxhighlight lang="php" enclose="div">Which of the following fruit do you like?
#Apples ()
#Bananas ()
#Cherries ()</syntaxhighlight>

is a typical multiple choice question, as you can like several of those - in contrary "Which of the following fruit do you prefer?" is a single choice question.

Both fruit examples have been formulated to make clear that is is only about the fruit listed as answers. If your question would be "Which is you favorite fruit?" you should either have a really exhaustive list of fruit or - more likely, use LimeSurvey's setting to add an "other" field. More generally, answer options in most cased need to be complete, mutually exclusive and definite.

If you have multiple or single choice questions with a lot of options for answers, you need to be aware that this might introduce another bias, as participants are likely to pay more attention to the very first options than to those in the middle. LimeSurvey offers a nice option to randomize the order of questions and to some extend diminish this problem.

==What makes a good survey?==

There are 3 features of a survey which might make it useful:
# The questions are clear and precise, collectively allowing for detailed,unambiguous and meaningful answers.
# All predefined answers provided and their formats are appropriate to the question.
# There is room for people to add additional information if they need.

Adding to that, always keep the user experience in mind. Reading, scrolling and clicking are tyring activites, so:
# Avoid any unnecessary question
# Use conditions to avoid asking questions not relevant for a specific participant
# Keep questions and answers short easily readable - use appropriate markup
# Think about the trade-off between scrolling and clicking. Display everything on one page for short questionnaires (5-15 questions, depending on question complexity). Use groups wisely for longer questionnaires, i.e. group questions comprehensible; use group descriptions to give a clear statement about the topic of the following questions.
# Avoid confusing participants with different scales, i.e. limit the amount of different scales types, scale scopes and different scales descriptions as much as possible. Try not to change the direction of scales. (There are some methodological exceptions).
#For rating scales it might be useful use an even number of rating options so the user has to decide for a certain direction (see below).

<syntaxhighlight lang="php" enclose="div">Example for good answer scales:

1. Very good

2. Good

3. Quite good

4. Not that good

5. Bad

6. Very bad

Example for bad answer scales:

1. Good

2. Fair

3. Bad</syntaxhighlight>

The best way to start designing a survey is to take a second to imagine your ideal feedback. It goes without saying that meaningful responses are the most useful ones, so try to create questions which invite these answers.

How can you go about that? The best method is to split up all the areas and decide on what information you need.

For example, imagine you held an event, open to the public, and needed to get some general feedback about the event.

A "bad" survey might be similar to the following:

<syntaxhighlight lang="php" enclose="div">Did you enjoy the Event?

( ) Yes

( ) No

How good was the wifi?

1 2 3 4 5 6 7 8 9 10

( ) ( ) ( ) ( ) ( ) ( ) ( ) ( ) ( ) ( )

Did you arrive OK?

( ) Yes

( ) No

Was the provided map OK?

( ) Yes

( ) No

Were how did you feel about the mixture of speakers?

( ) Very sad ( ) Sad( ) Neutral ( ) Happy ( ) Very Happy</syntaxhighlight>

==Survey Bias==

In obtaining market research, one of the most critical things to avoid is the issue of survey bias - that is, asking the respondent questions which may influence the results he or she provides and thus invalidates or skews your data. It is very easy and common for a company or individual without the proper market research education and experience to err in this way. This extends to many things, such as the way a question is phrased, to the types of responses which are available, to the way that an interviewer presents the questions if data is being collected by phone or in-person.

For example, a biased survey question may be written as such:

<syntaxhighlight lang="php" enclose="div">How much did you enjoy the event?

( )Very much

( )A little bit

( )Not very much

( )Not at all</syntaxhighlight>

At first glance, it appears that there is no problem with the structure of this question. After all, the respondent is able to provide his or her answer from "very much" to "not at all". However, the problem appears in the question phrasing itself. By asking the respondent "How much" he or she enjoyed the event, the interview has already established a bias by assuming that the respondent enjoyed the event in some way or another, which may not be the case.

The following example would be a far better what to ask the question which does not lead or bias the respondent in any way:

<syntaxhighlight lang="php" enclose="div">How would you rate your overall enjoyment of the event on a 1 to 5 scale, where 1 is "Not at all enjoyed" and 5 is "Completely enjoyed"

1 2 3 4 5

( ) ( ) ( ) ( ) ( )</syntaxhighlight>

Using this modified question, the respondent is not led to the assumption that any enjoyment was had, and is able to supply an answer in a numerical way that makes it easy for him or her to specify the enjoyment level, and makes it easy for the survey solicitor to tabulate and compare the results with other respondents.

This is just one minor example of a good survey design principle. This understanding extends to all things.

==Matrix questions.==

That may be a bit of a generalisation, but its a good rule to live by.
Anything that involves a scale of any sort should be avoided
unless you want an answer that can be measured on a scale, like age, time (maybe) or quantities.
Similarly, a matrix of compulsory questions can be a bit of a deterrent for your audience as not only are they badly structured,
but they don't allow for any extra information.

Chances are if someone is completing your survey they want to give feedback, and if they don't think they can share anything useful they'll just close the window and move on.

So what's wrong with the survey above?

Let's look at each question step by step.

Question 1 doesn't really achieve anything. Imagine receiving 100 "no" responses. Firstly you'd be sad, but secondly you would have absolutely nothing to do with the information. We'll look at a possible improvement to this in a moment.

Question 2 is so bad it's painful. If we go back to our 3 steps, we see that the questions need to be clear and precise. I'm not an expert in Wifi but I'm fairly certain you don't measure it in "goods". What's more, it doesn't allow for a meaningful answer – What will you do with the knowledge that while 33% of people rated your wifi as being 6 good, only 23% rated it as 7 good? Point number 2 tells us that the predefined answers need to be appropriate to the question.

It's fairly obvious that a scale of 1 to 10 won't help you improve on the quality of your wifi. The real killer in this one is the need to have space for people to add additional information. How could someone report a specific problem?

In this case? It's impossible. Surveys are all about finding out something you can work with or learn from.

The next two questions have the same result – they provide a platform for people to say yes or no. And neither of those questions allow for detail. In a better survey, which we'll consider in a moment, you could learn particular problems from specific people.

The final question is another painful one. Asking for the level of satisfaction about something is pretty much useless, as every person has different interests, and so everyone will likely have different opinions on each speaker. It's another example of where a range question is being used and shouldn't be.

Have a look at the improved survey there.

<syntaxhighlight lang="php" enclose="div">Did you make use of the in-house wifi?

( ) Yes

( ) No

Did you experience any problems?

( ) No problems at all

( ) A couple of small issues, nothing major

( ) One or two severe issues

( ) The wifi was nearly totally unusable.

If you experienced problems, could you briefly describe them? (Text field)

Did you arrive ok?

( ) Yes

( ) No

How did you come to our event?

( ) Train

( ) Car

( ) Bus

( ) Light Rail (IE Tube, Tram)

( ) Walk

Did you use the map from our website?

( ) Yes

( ) No

If you looked at the map, was it detailed enough?

( ) Yes

( ) It gave me a rough idea, I used another map for more detail though

( ) Not detailed at all.

If you didn't use the map, why not?

( ) Not enough detail

( ) I used a satnav/google maps instead

( ) I didn't even know it existed!

Generally speaking, were the speakers interesting? Did you enjoy the presentations?

( ) Nearly all were interesting and thoroughly enjoyable

( ) Mainly enjoyable, but a handful of less interesting talks.

( ) A 50 – 50 split

( ) More dull than interesting

( ) Didn't find any interesting.

Please elaborate on your answer to the question above. Feel free to reference any

particular people/talks. (Text field)

If we could improve the range of talks, or you have any other interesting ideas regarding

the talks, list them below (Text field)

If you have any other recommendations or ideas, please list them below. (Text field)</syntaxhighlight>

This survey may be a little longer, but it's a lot easier to both answer and interpret the answers from. Asking two or three questions about each of the topics means that when it comes to processing the results you can do a little more analysis. For example. Imagine, in response to the first survey you received 30 people saying they didn't arrive OK.

This would have been as much information as you could possibly extract from the results, but with our new set of answers it would be possible to deduce which forms of transport presented people with trouble. What's more, you could go on to see whether they were using a provided map or another form, and use this to target improvements for the future.

''' Keep in mind, that after 50 questions, the user is most likely to not read the question anymore.'''

Other important additions are the text field questions – these allow your audience to give specific feedback which you can draw from. It's a good idea to not make these compulsory though, as they may put people off answering.

To conclude, when writing a survey you should aim to create one which asks specific questions targeted to the issues you need to answer. Also remember that it doesn't do any harm to gather a little extra background information as you can use it all to get better information from the result.

It's also important to phrase your questions well, as if people need to answer the questions and they don't understand them, they'll close the window and move on. Try to hand your survey to someone else to proof read before making it publicly available to ensure its definitely crystal clear what the question is asking.

Workarounds: Survey behaviour

2013-10-06T13:27:51Z

Nery: /* Loop question(s) */

LimeSurvey users have been very creative in finding out how to change the behavior of a survey. All their workarounds are listed here. You can find some '''similar approaches''' at:
* [[Workarounds: Manipulating a survey at runtime using Javascript]]
* [[Workarounds: Question design, layout and templating]]

<div class="simplebox"><center><br />'''Please keep in mind that these workarounds are not official LimeSurvey extensions - they are solutions that users have created for themselves.<br /><span style='color:#EE0000,#FFFFFF'>Therefore LimeSurvey can't offer guarantees or support for these solutions.</span><br />If you have questions, please contact the users that, thankfully, shared their solutions with the community.'''<br /><br /></center></div>

__TOC__

=Respond multiple times using the same computer=

''Tested with: ''

With this workaround it will be possible to respond multiple times to the same survey. Normally there will be a message saying that the computer already received the answers. To prevent this you have to add the following code to the URL that leads to the survey ''"&newtest;=Y"''.

Example of the "new" url:

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

http://www.yourdomain.org/limesurvey/index.php?sid=12345&newtest;=Y

</syntaxhighlight>

=Allow Multiple Survey Invitations to the same Email Address to be completed in the Same Browser Session=

''Tested with: ''

'''Problem:''' When Multiple Surveys Invitations are activated during the same browser session, the second and subsequent survey activation results in a system message stating that the survey has already been completed. A user would have to close the browser and reopen in order to complete the next survey inviation.

'''Workaround:''' Edit the Survey Invitation Email (also the reminder) Template. Append "&newtest;=Y" to the {SURVEYURL} line so it looks like this {SURVEYURL}&newtest;=Y

Save the edited templates.

Note: The save of this template edit does not seem to work when using HTML invitations, only text based invitations.

=Add a data field to manually add data=

''Tested with: ''

If you want to add some additional data after a user has finished a survey you can use the dataentry screen of the admin panel. You have to set up the survey as follows:
# Create a question that can store the needed data at the end of the survey.
# Use [[Setting conditions|conditions]] on the previous question so that whatever is answered at the previous question the following question '''doesn't appear'''.
# To enter several questions repeat steps 1-2. Don't forget to adapt the conditions.
# Go to the admin panel, chose the survey from the list and go to ''Dataentry screen for survey''.
# Enter the additional data

=Randomization=

Often you want to randomize certain elements of a survey, here are some approaches:

==Totally random survey order==

''Tested with:''

If you want to use random order globally for all questions in your survey, you can do it like this, depending on what type of question routine you use.
# If you use Group by Group add "shuffle($_SESSION<nowiki>[</nowiki>'grouplist']);" at the end of UpdateSessionGroupList($language) function in index.php
# If you use Question by Question or All-in-one put "shuffle($_SESSION<nowiki>[</nowiki>'fieldarray'])" at the end of buildsurveysession() function in index.php

'''Important:''' This modifications affect all surveys in application, you may want to use an if statement with surveyid to make this work with specific surveys e.g.

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

if ($surveyid==12345)

{

do_some_shuffling()

}

</syntaxhighlight>
*Saving survey is not possible because this workaround doesn't save random order for specyfic tokens.
*Solution doesn't care about language changes so if you have on in your survey this will not work.
*Using conditions is not possible because conditions rely on a fixed and pre-determined order of questions.

==Randomize the order of ''sequences of groups'' in a survey==

''Tested with: 1.86''

You can randomize the order of subsequences of groups in a survey. E.g., you may have a survey comprising the below group structure
*demographics
*itemgroup1
*itemgroup2
*itemgroup3
*interlude
*itemgroup4
*itemgroup5
*itemgroup6
*closingcomments

and want to separately randomize the presentation order of itemgroup1...3 and itemgroup4...6 while maintaining the position of the other three groups. A working code modification is described in the PDF file [http://bugs.limesurvey.org/file_download.php?file_id=1228&type;=bug randomize_groups] which is downloadable from the Bugtracker at [http://bugs.limesurvey.org/view.php?id=557].
* '''Note:''' The code will randomize the order of subsequent groups in isolation, not across different sequences. Hence in the above example, you might get ''itemgroup1, 3, 2'' but never ''itemgroup1, 4, 2''
* '''Note:''' The survey presentation format must be ''Group by Group'' not ''Question by Question''
* '''Note:''' If you wish to select only a limited number of groups from a larger set, replace

<syntaxhighlight lang="php" enclose="div">$scratcharr = array_merge($scratcharr, $randarr);</syntaxhighlight>with

<syntaxhighlight lang="php" enclose="div">$scratcharr = array_merge($scratcharr, array_slice($randarr,0,x));</syntaxhighlight>

where x is the number of elements/groups that you wish to include. In the example above '''$scratcharr = array_merge($scratcharr, array_slice($randarr,0,2));''' would select two out of the possible three groups in each group set.
* '''Warning:''' The code is compatible with conditions operating on items within a group but most possibly produces erroneous behavior with conditions between groups
* '''Warning:''' In a multi-language survey, the groups get randomized each time the language is changed. A simple workaround is to remove the language changer from the question pages of the survey leaving it on the welcome page only. (Though not totally foolproof this does lower the risk of unnecessary language changes.)

==Selective Question Randomization==

''Tested with: 1.82''

With this workaround you are able to select which groups within a survey should have their questions randomized and not kept in order. This workaround also adds a tab in the question ordering page. The extra tab allows you to enable / disable question randomization for the selected group.

A working code and database modification is described in the PDF file [http://bugs.limesurvey.org/file_download.php?file_id=1939&type;=bug selective_random_questions] which is downloadable from the Bugtracker at [http://bugs.limesurvey.org/view.php?id=3107].

'''Note:''' This might not work when adding conditions or assessments to the survey.

==Randomize the order of questions within individual groups - JavaScript solution==

''Tested with: 1.85+ (7557), IE 6/7, Firefox 3.0, Safari 3.2''

This workaround allows you to randomize the order of questions in individual groups. It uses JavaScript/jQuery to apply this randomization to only those groups that you wish and requires no modification of the core files when updating the installation.

The script uses a cookie to "remember" the shuffled order of the questions for the duration of the session so if a respondent navigates away from the group and returns, they will see the same question order. However if the survey is submitted or the session expires the questions will be re-shuffled.

A couple of cautions about the script are:
#If the survey is saved, the questions will be re-shuffled when it is accessed again (as with the PHP solution).
#The question shuffling may play havoc with conditions within a group (as with the PHP solution).
#The script has been tested with all templates shipped with 1.85+ but if you have a custom template with "question" in the ID of division(s) (ie <div id="<span style='color:red'>question</span>Holder">) it may fail - the script looks for all divs with IDs starting with "question" and adds them to an array to be shuffled.

There is a small demonstration [http://www.partnersinc.biz/surveys//index.php?sid=84767&newtest=Y&lang=en here].

Put simply, the script:
#Checks cookies to see if the questions have already been shuffled for this group and session.
#If so - displays the questions in that order.
#If not - creates an array of all of the questions in the group, shuffles the array, sets a cookie with the shuffled array contents, displays the questions in the shuffled order.

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript (see [[Optional settings#Security|documentation here]])..
#Create your group and questions.
#In the source of the group description add the following onload function (see [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|How to use script]]).

Onload code:

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

<script type="text/javascript" charset="utf-8">

$(document).ready(function() {

function shuffleQuestions() {

// Create an array to hold question IDs

var qArray = new Array();

// Find the group ID of the page

var fieldNames = $( 'input#fieldnames' ).attr('value');

var tmp = fieldNames.split('X');

var sID = tmp[0];

var gID = tmp[1];

// A function to get the value of a cookie by name

function getCookie ( cookieName ) {

var results = document.cookie.match ( '(<div class="simplebox">|;) ?' + cookieName + '=([</div>;]*)(;|$)' );

if ( results ) {

return ( unescape ( results[2] ) );

}

else {

return null;

}

}

// Get the session name

var sessionName = getCookie ( 'PHPSESSID' );

// Check to see if the question order has already been shuffled in this session

var cookieArray = getCookie ( 'sArray' + gID + '_' + sessionName );

// If already shuffled, use that question order

if ( cookieArray ) {

//qArray = $.trim(cookieArray);

qArray = cookieArray.split(',');

}

// If not, go ahead and shuffle

else {

// Load the IDs of all questions on the page into the array

$( 'div[id<div class="simplebox">="question"]' ).each(function(i) {

qArray.push($( this ).attr('id'));

});

// Shuffle the questions array

function shuffle(o){

for(var j, x, i = o.length; i; j = parseInt(Math.random() * i), x = o[--i], o[i] = o[j], o[j] = x);

return o;

}

shuffle(qArray);

// Set a cookie with the value of the shuffled array

var today = new Date();

today.setTime( today.getTime() );

var expires = 2 * 1000 * 60 * 60 * 24; // Expire the cookie in 2 days

var expiresDate = new Date( today.getTime() + (expires) );

document.cookie = 'sArray' + gID + '_' + sessionName + '=' + qArray + ';expires=' + expiresDate.toGMTString();

}

// Wrap the questions in a div

$( 'div[id</div>="question"]' ).wrapAll( document.createElement('div') );

$( 'div[id<div class="simplebox">="question"]:eq(0)' ).parent().attr('id', 'qWrapper');

$( 'div#qWrapper' ).css({

'padding':0,

'margin':0

});

// Insert the questions into the wrapper in the shuffled order

$.each(qArray, function(i, val){

$( 'div#' + val + '' ).appendTo( $( '#qWrapper' ) );

});

}

shuffleQuestions();

});

</script>

</syntaxhighlight>

==Randomise the order of questions ''within'' groups==

''Tested with: ''

You can randomize the order questions of within groups (i.e. without interleaving questions from different groups) like this:

1 Call a custom function from the last line of buildsurveysession() before the return statement in index.php:

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

$_SESSION['fieldarray'] = withinGroupsShuffle();

</syntaxhighlight>

2. Add these custom functions at the end of the same file:

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

$currentGid;

function withinGroupsShuffle() {

global $currentGid;

$groupArray = array();

$shuffledArray = array();

foreach ($_SESSION['grouplist'] as $group) {

$currentGid = $group[0];

$groupArray = array_filter($_SESSION['fieldarray'], "questionInGroup");

shuffle($groupArray);

$tmp = $shuffledArray;

$shuffledArray = array_merge($tmp, $groupArray);

$groupArray = array();

}

return $shuffledArray;

}

function questionInGroup($question) {

global $currentGid;

return ($question[5] == $currentGid) ? 1 : 0;

}

</syntaxhighlight>

(''I'm new to PHP, so please make changes if you can make the code shorter or more elegant'')

This could be combined with the method mentioned above for shuffling the order of groups:

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

shuffle($_SESSION['grouplist']);

</syntaxhighlight>

I don't know how this code affects or is affected by conditions or tokens! This code has the same limitations as the global randomisation above: it applies to all groups in all surveys. It would be nice to add a group-level parameter like randomise_questions = [0|1], but I can't find a mechanism for doing that.

==Randomize all questions in "All In One" mode - even if they are place in groups.==

''Tested with: 1.91, IE 7/8, Firefox 3.6, Safari 3.2''

This workaround will randomize all questions when using "All In One" mode, even if they are place in groups. This may be useful if you want to use group assessments and display all questions on a single page in a random order.

Notes:
*The workaround is tested in the default template and may need slight tweaks for others.
*It is NOT tested with conditions.

Implementation is as follows:
#[[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|Set up your survey to use JavaScript]].
#Add the following script to the source of one of the questions.

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

<script type="text/javascript" charset="utf-8">

$(document).ready(function() {

shuffleQuestions();

function shuffleQuestions() {

// Hide the group wrappers

$('div[id</div>="group-"]').hide();

// Create and insert a new question wrapper

var qWrapper = '<div id="qWrapper">\

<table class="group"> \

<tbody> \

<tr> \

<td> \

</td> \

</tr> \

</tbody> \

</table>\

</div>';

$('div[id<div class="simplebox">="group-"]:last').after(qWrapper);

$( 'div#qWrapper td' ).css({'padding-top':'10px'});

// Create an array to hold question IDs

var qArray = new Array();

// Load the IDs of all questions on the page into the array

$('div[id</div>="question"]').each(function(i) {

qArray.push($(this).attr('id'));

});

// Shuffle the questions array

function shuffle(o){

for(var j, x, i = o.length; i; j = parseInt(Math.random() * i), x = o[--i], o[i] = o[j], o[j] = x);

return o;

}

shuffle(qArray);

// Insert the questions into the new question wrapper in the shuffled order

$.each(qArray, function(i, val){

$('div#' + val + '').appendTo($('#qWrapper td:first'));

});

}

});

</script></syntaxhighlight>

==Random question sets==

''Tested with: 1.85+ (7557), IE 6/7, Firefox 3.0, Safari 3.2''

This workaround, in conjunction with the [[Workarounds: Survey behaviour#Randomize the order of questions within individual groups - JavaScript solution|randomizing questions script]], allows you to display a random set of questions in a group.

There is a small demonstration [http://www.partnersinc.biz/surveys//index.php?sid=84767&newtest=Y&lang=en here] (page 2).

JavaScript is used to first shuffle the question order and then hide the number of questions that you stipulate, effectively giving respondents a random question set. So if, as in the demo, you have 5 questions in your group and choose to hide 2, the respondents will be presented with a random 3 questions.

A brief explanation of the script is:
*The questions are shuffled (see [[Workarounds: Survey behaviour#Randomize the order of questions within individual groups - JavaScript solution|randomizing questions]]) and their IDs placed in an array.
*The number of questions to be shown is calculated and their IDs are moved to a new array.
*All questions in the first array are hidden - this effectively hides the first '''''n''''' questions on the page so you'll get a random set of questions displayed.
*An asterisk is prepended to the remaining questions (remove this if your questions are not mandatory).
*When the next/submit button is clicked, all remaining questions are checked for an answer. If any are unanswered, their text is turned red, an alert is popped up and the next/submit is aborted (remove this if your questions are not mandatory).

A cookie is used to "remember" the shuffled order of the questions for the duration of the session so if a respondent navigates away from the group and returns, they will see the same question set. However if the survey is submitted or the session expires, the questions will be re-shuffled and a new set will be displayed. Therefor this workaround should not be used with surveys that can be saved.

A couple of cautions about the script are:
#If the survey is saved, the questions will be re-shuffled when it is accessed again and a new question set will be displayed.
#The question shuffling may play havoc with conditions within a group.
#The script has been tested with all templates shipped with 1.85+ but if you have a custom template with "question" in the ID of division(s) (ie <div id="<span style='color:red'>question</span>Holder">) it may fail - the script looks for all divs with IDs starting with "question" and adds them to an array to be shuffled.
#The script may need to be modified to display the "Mandatory" asterisk in templates other than the default - see below.

Implementation is as follows:
#Turn off ''$filterxsshtml'' to allow insertion of JavaScript (see [[Optional settings#Security|documentation here]]).
#Create your group with all questions non-mandatory (we'll make them mandatory later with JavaScript).
#In the source of the group description add the following onload function (see [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey?|How to use script here]]).
#Modify the function call at the end of the script for the number of questions to be hidden and the mandatory error text.

Onload code:

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

<script type="text/javascript" charset="utf-8">

$(document).ready(function() {

function shuffleQuestions() {

// Create an array to hold question IDs

var qArray = new Array();

// Find the group ID of the page

var fieldNames = $( 'input#fieldnames' ).attr('value');

var tmp = fieldNames.split('X');

var sID = tmp[0];

var gID = tmp[1];

// A function to get the value of a cookie by name

function getCookie ( cookieName ) {

var results = document.cookie.match ( '(<div class="simplebox">|;) ?' + cookieName + '=([</div>;]*)(;|$)' );

if ( results ) {

return ( unescape ( results[2] ) );

}

else {

return null;

}

}

// Get the session name

var sessionName = getCookie ( 'PHPSESSID' );

// Check to see if the question order has already been shuffled in this session

var cookieArray = getCookie ( 'sArray' + gID + '_' + sessionName );

// If already shuffled, use that question order

if ( cookieArray ) {

//qArray = $.trim(cookieArray);

qArray = cookieArray.split(',');

}

// If not, go ahead and shuffle

else {

// Load the IDs of all questions on the page into the array

$( 'div[id<div class="simplebox">="question"]' ).each(function(i) {

qArray.push($( this ).attr('id'));

});

// Shuffle the questions array

function shuffle(o){

for(var j, x, i = o.length; i; j = parseInt(Math.random() * i), x = o[--i], o[i] = o[j], o[j] = x);

return o;

}

shuffle(qArray);

// Set a cookie with the value of the shuffled array

var today = new Date();

today.setTime( today.getTime() );

var expires = 2 * 1000 * 60 * 60 * 24; // Expire the cookie in 2 days

var expiresDate = new Date( today.getTime() + (expires) );

document.cookie = 'sArray' + gID + '_' + sessionName + '=' + qArray + ';expires=' + expiresDate.toGMTString();

}

// Wrap the questions in a div

$( 'div[id</div>="question"]' ).wrapAll( document.createElement('div') );

$( 'div[id<div class="simplebox">="question"]:eq(0)' ).parent().attr('id', 'qWrapper');

$( 'div#qWrapper' ).css({

'padding':0,

'margin':0

});

// Insert the questions into the wrapper in the shuffled order

$.each(qArray, function(i, val){

$( 'div#' + val + '' ).appendTo( $( '#qWrapper' ) );

});

}

shuffleQuestions();

function hideQuestions(numberToHide, mandatoryMsg) {

// Create an array of the IDs of all questions on the page

var questions = new Array();

$( 'div[id</div>="question"]' ).each(function(i) {

questions.push($( this ).attr('id'));

});

// Remove the "shown" questions and place them in a new array

var questionsLength = questions.length;

var shownQuestions = questions.splice(numberToHide,questionsLength-numberToHide);

// Hide the remaining questions

$.each(questions, function(i, val){

$( 'div#' + val + '' ).hide();

});

// Add an asterisk to the "shown" questions

// NOTE: Comment this section out if questions are not mandatory

$( 'td.questiontext' ).prepend( '<span class="asterisk">*</span>');

// Interrupt the submit function and validate mandatory questions

// NOTE: Comment this section out if questions are not mandatory

$('form#limesurvey').submit(function(){

// Override the built-in "disable navigation buttons" feature

$('#moveprevbtn, #movenextbtn, #movesubmitbtn').attr('disabled', '');

// Loop through all "shown" questions and check for answer

var answered = 0;

$.each(shownQuestions, function(i, val){

if ( $( 'div#' + val + ' input.radio:checked' ).length == 0 ) {

$( 'div#' + val + '' ).css('color', 'red');

answered = 1;

}

else {

$( 'div#' + val + '' ).css('color', '');

}

});

if ( answered == 1 ) {

alert ( mandatoryMsg );

return false;

}

else {

return true;

}

});

}

// Call the hide function

// Edit here for number of question to hide and mandatory message

hideQuestions(2, 'Please complete all questions');

});

</script>

</syntaxhighlight>

To add the asterisk to non default templates, replace ''$( 'td.questiontext' ).prepend( '<span class="asterisk">*</span>');'''' with:

- basic - ''$( 'td.be' ).prepend( '<span class="asterisk">*</span>');''

- bluengrey - Not possible to insert asterisk in correct location

- business_grey - ''$( 'div.questiontext' ).prepend( '<span class="asterisk">*</span>');''

- clear_logo - ''$( 'td.be' ).prepend( '<span class="asterisk">*</span>');''

- default - ''$( 'td.questiontext' ).prepend( '<span class="asterisk">*</span>');''

- eirenicon - Not possible to insert asterisk in correct location

- limespired - ''$( 'div.survey-question-text' ).prepend( '<span class="asterisk">*</span>');''

- mint_idea - ''$( 'div.survey-question-text' ).prepend( '<span class="asterisk">*</span>');''

- sherpa - ''$( 'div.survey-question-text' ).prepend( '<span class="asterisk">*</span>');''

- vallendar - Not possible to insert asterisk in correct location

==Randomization - ''Assign People Randomly'' To Surveys==

''Tested with: ''

This is a very easy way to assign people randomly to surveys, I think experts do it in other ways, but it works for me.

''LINK.PHP:''
<syntaxhighlight lang="php" enclose="div"><?php
$db = @file("link.txt"); // path to .txt file
$anz = @count($db);
srand((double)microtime()*1000000); // random numbers
$random = rand(1,$anz);
print $db[$random-1];
?>
</syntaxhighlight>

''LINK.TXT:''
<syntaxhighlight lang="php" enclose="div">
<meta http-equiv="refresh" content="1;url=http://www.survey1.com">
<meta http-equiv="refresh" content="1;url=http://www.survey2.com">
</syntaxhighlight>
''Only one link per line!''

''INDEX.PHP:''
<syntaxhighlight lang="php" enclose="div">
<html>
<head><title>title</title>

<?php
include("link.php");
?>

</head>
<body>

<table width=100% height=100%>
<tr>
<td valign=middle>
<center><font size=5>loading ... </font></center>
</td>
</tr>
</table>

</body>
</html>
</syntaxhighlight>

==Random Redirect responders to surveys==
''Tested with: ''

As the workaround above, this one assign randomly (uniform distribution) people to multiple surveys in easier way, but with the same outcome: every survey has the same probability to be accessed by a responder.

1. Copy and paste the code below in a text editor.
2. Replace the URLs with those of your surveys, and save it as index.php
3. Create a new directory in your server.
4. Upload the file in that directory and give the link (http://www.yourdomain.com/newdirectory) to the responders.

<syntaxhighlight lang="php" enclose="div">
<?php
$urls = array("www.site1.com",
"www.site2.com",
"www.site3.com");
$url = $urls[array_rand($urls)];
header("Location: http://$url");
?>
</syntaxhighlight>

==Prefilling survey elements==

There are some ways to pre-fill elements in a survey. The data to prefill an answer can be passed by URL if it matches a certain format.

==Prefilling survey answers using the survey URL==
''Tested with: 1.80 and later''

You can prefill answers to questions in your survey by passing the [[SGQA identifier]], and the answer, as a parameter of your survey URL. This feature will only work where the survey is commenced immediately upon entering the URL (so it won't work if you use CAPTCHA's to restrict access, or the registration page).

You'll need to ensure that the answer you pass is the correct format for the question you are attempting to prefill - for example - multiple option questions should contain a "Y" to check a box. List type questions need the correct answer code. To be certain which codes to pass, complete a survey manually with the prefilled answer(s) you want, and then export the results as question codes and answer codes(not full text). This will give you both the correct SGQA identifier (the name of the column), and the correct format for the answer.

<div class="simplebox">Starting with version 1.92+, you can use [[Expression Manager#Access to Variables|qcode naming]] for the variables in addition to, or instead of, using SGQA naming.</div>

<div class="simplebox">In '''version 2.x''' the link for a prefill have to look like that: http://www.example/index.php/survey/index/sid/712544/newtest/Y?712544X99X2151=gelb&712544X99X2152=12345 <br>
It's important to add "newtest/Y" to the link.</div>

'''Example:'''

<div class="simplebox">http://www.example.../index.php?sid=1234&1234X43X123=Y</div>

With 2.0, if your url is like this /survey/sid/1234, you have to use:
<div class="simplebox">http://www.example.../survey/sid/1234/1234X43X123/Y</div>

When the user gets to that question, the "Y" will be prefilled as the answer to question 123 in group 43 in survey 1234.

'''Example Single-Choice:'''

<div class="simplebox">http://www.example.../index.php?sid=1234&1234X43X123=A2</div>

With 2.0, if your url is like this /survey/sid/1234, you have to use:
<div class="simplebox">http://www.example.../survey/sid/1234/1234X43X123/A2</div>

If you like to prefill a single choice question (answer-code A1 - X ), you have to write this. If you export the results of this question, you will see, that this kind of question save the answer code as result in table. Use in any case the capital "X" in the link!

===Prefilling survey answers using the survey URL and hiding the Answer===

Starting with version 1.87 every question has a property 'Always hide this question' which can be used for this purpose.

==Prefilling a date question with the current date==

''Tested with: 1.80RC3''

Workaround created by user "Mazi"

Using the [[Workarounds: Survey behaviour#Prefilling survey answers using the survey URL|workaround mentioned above]] you can prefill the current date for a date question. Instead of using the common link to a survey which looks like this

<div class="simplebox">http://www.yourdomain.org/limesurvey/index.php?sid=53298&newtest;=Y&lang;=de</div>

you create an additional script, let's call it date.php. This script contains the following code:

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

<?php

$date = date("Y-m-d");

header("Location: http://www.yourdomain.org/limesurvey/index.php?sid=53298&newtest;=Y&lang;=de&53298X15X102=$date");

?>

</syntaxhighlight>

The script determines the current date and calls the survey with a certain URL. The current date is attached as the answer for a certain date question using [http://docs.limesurvey.org/tiki-index.php?page=SGQA+identifier SGQA identifier]. Don't forget to '''adjust the SID and SGQA identifier''' according to your survey/group/question ID!

Upload the new ''date.php'' file into your limesurvey directory. You can then call the survey using this link:

<div class="simplebox">http://www.yourdomain.org/limesurvey/date.php</div>

Things to watch out for:
* Date questions always use the internal date data format of the database which has to be YYYY-MM-DD!
* You have to adjust the SID at the URl.
* Also adjust the SGQA identifier (SIDXGIDXQID) according to your survey.
* This solution doesn't work if you use tokens at your survey.

=Offer option to change answers later=

''Tested with: ''

When having a closed access survey using a token table it is possible to offer the opportunity to change answers later. Normally after having submitted the answers a token is marked as "used". To prevent this do as follows:
* set your survey to question-by-question mode (or group-by-group mode)
* set the survey to Non anonymous + Allow persistence for token answers
* activate survey and create your token table
* add at least one question of type boilerplate (which contains just some text). This is necessaray to give some instructions to the user like "''Your answers have been recorded to the DB, if you're sure you won't modify them, you can submit your response. If unsure, please quit your browser now and get back later with the private URL you've received''.

By not submitting the survey the user is still able to change the answers later.

=Use general password for accessing a survey=

If you don't want to use tokens but a general password to access a survey you can set your survey to "allow public access". Don't create a token table but use the following workaround:
# Create a short text question first
# Create the other questions
# Use conditions on all the other questions. You can use regular expressions to validate the string entered at the short text question. Just validate a certain password. If the password is correct the following questions are shown.
# Create a boilerplate question which just says "invalid password" which is shown if the user entered a wrong password.

=Create token on the fly and Edit completed survey=

Warning: The link for the code link is wrong (June 2013)

When having a close token survey you can create a token on the fly by giving as parameters sid and token.

In addition if someone has already completed a survey he can review his answers and correct them.

[http://bugs.limesurvey.org/view.php?id=2982 Just put this script attached at the bugtracker ticket into limesurveys root directory]

'''Prerequisites''':
# Anonymous answers? No (This survey is NOT anonymous.)
# Enable Token-based answers persistence? Yes
# Switch to closed-acces mode

'''Example''':

<div class="simplebox">http://www.yoururl.com/limesurvey180/newtoken.php?sid=98761&token;=12345</div>

where Survey id = 98761 your survey's id and token=12345 a token (any token actually)
# The first time the token will be created and you you will redirect to anwser the surrvey
# If you wont complete the survey and call the script with the same parameters you will be redirect to the same case in order to finish the survey
# If you finish the survey and call the script with the same parameters you will see restart the survey with your previews answers prefiled so you can change them
# Back to 3

this is valid for all survey in the installation but you can make a filter so it wont be valid for every survey.

'''Relative posts'''
*LimeSurvey Bug & Feature Tracker

[http://bugs.limesurvey.org/view.php?id=2982]
*the code

http://bugs.limesurvey.org/file_download.php?file_id=1826&type=bug

by user "janokary"

=multiple 'completed' with only one token=

''Tested with: 1.71''

Whit a closed survey, each token work only one time. Sometime we need the possibility to complete a particular survey several time with the same token. This works only if you survey is set to non-anonymous answers and to use datestamps.

Here is an example for the survey id '71314'. Don't forget to adapt your own sid.

Edit ''index.php '' to in the function submittokens() replace lines ~ 1312 :

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

if (bIsTokenCompletedDatestamped($thissurvey))

{

$utquery .= "SET completed='$today'\n";

}

}

else

{

$utquery .= "SET completed='Y'\n";

</syntaxhighlight>with lines :

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

if (bIsTokenCompletedDatestamped($thissurvey))

{

//multiple token only for survey 71314

if ($surveyid == '71314') {

$utquery .= "SET completed='N'\n";

}else {

$utquery .= "SET completed='$today'\n";

}

}

else

{

//$utquery .= "SET completed='Y'\n";

</syntaxhighlight>

We never update the database with the completed date and time for this survey.

'''Warning''' : a limitation of this code is that you never recieve a confirmation mail for the completed.

=Loop question(s)=

''Tested with: 1.85''

There is no real loop option within LimeSurvey 1.x. To loop a question an initial question to determine the number of loops is needed. Looping is then done using a condition workaround:

1. Create a single choice question asking "How many X do you want to rate", possible answers 1, 2, 3, 4, 5.

2. Create up to 5 following questions asking "Please rate item 1/2/3/...".

3. Check manual -> conditions and read it carefully.

4. Set conditions like

a) "Only show Q3 (Rate item 2) IF Q1 (How many...) was answered 2

OR Q1 (How many...) was answered 3

OR Q1 (How many...) was answered 4

OR Q1 (How many...) was answered 5"

b) "Only show Q4 (Rate item 3) IF Q1 (How many...) was answered 3

OR Q1 (How many...) was answered 4

OR Q1 (How many...) was answered 5"

c) Q5... see above

d) Q6...

Of course Q2 is always shown, the following question will be added by conditions depending on what the user answered at Q1.

Manage users

2013-10-06T10:28:02Z

Nery:

<languages />
<translate>

__TOC__

= User management= 

==Create users== 


To create a new user open the user management ('''main menu''' -> '''Create/Edit users ''' [[File:LimeSurveyBenuzerVerwaltung.jpg]]).


[[File:LimeSurveyAddUser.jpg]]
* Enter the desired username into the textfield '''Username'''.
* Enter the email address into the textfield '''Email'''. Please note
** If you don't want the user to receive 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.
** 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.
* Enter the users full name into the textfield '''Full name''' . Please note
** The full name entered here will be used as standard contact person name for surveys created by this user.
* Click '''Add user'''


So you created a new user. You will find out more about setting user permissions if you continue reading further.

==Edit users== 


You can use the pen symbol [[File:LimeSurveyBleistiftSymbol.jpg]] to edit a user.


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

==Delete users== 


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

=Global permissions= 


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.

==Setting global permissions for a user== 


To set global permissions for a user just click the key symbol [[File:LimeSurveySchluesselSymbol.jpg]].


[[File:LimeSurveySetGlobalPermissions.jpg]]


You can now add or remove the following rights.
* '''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.
* '''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.
* '''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.
* '''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.
* '''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.
* '''Manage labels''': This right grants all rights regarding label sets (create, edit and delete).


The most important use cases for granting user rights are collected at the '''use cases''' part of this article.

==Setting template permissions for a user== 


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.


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


To set/edit the template permissions for a user simply click the key symbol for design templates [[File:LimeSurveySchluesselSymbolTemplates.jpg]].


[[File:LimeSurveySetDesignTemplatesLS.jpg]]


You can now select the design templates this user can select. After you finished your selection/deselection just hit '''Save settings''' .


The most important use cases for granting user rights are collected at the '''use cases''' part of this article.

=Setting permissions for a single survey= 


These permissions only apply for a single survey. If you want to set permissions for the whole system you can use the global permissions.


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

==Setting user permissions for a single survey== 


To change the survey permissions you have to select '''Survey permissions''' from the '''Survey properties''' menu.


[[File:LimeSurveySurveyPermissions.jpg]]


In the next step you select the user you want to change the survey rights and click '''Add user'''.


[[File:LimeSurveyAddSurveyPermission.jpg]]


After you click '''Set survey permissions''' the survey permissions matrix for the survey and user will be shown.


[[File:LimeSurveyUserPermissionMatrix.jpg]]


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.


In the other columns you can choose whether a user can do a single actions from this feature/part.


After you finished editing the survey permissions click '''Save now'''.


The most important use cases for granting user rights are collected at the '''use cases''' part of this article.

=Use cases= 


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.

==A new person in charge for administrating LimeSurvey will be added== 
* login as '''admin'''
* Create a new user account
* Set global permissions for user to '''SuperAdministrator'''
* not necessary: Setting the template permissions ('''SuperAdministrator''' has all permissions for all templates)
* not necessary: Setting the survey permissions ('''SuperAdministrator''' has all permissions for all surveys)

==A new user wants to create own surveys== 
* login as '''admin''' or user with '''SuperAdministrator''' permission.
* Create a new user account
* Set global permissions for user to '''Create survey'''
* Set template permissions for user to the template/s that should be used by the user/user-group
* not necessary: Setting the survey permissions (The creator of a survey has all permissions for his/her surveys)

==The creator of a survey needs another person to edit his/her survey== 
* login as '''admin''' or user with '''SuperAdministrator''' permission.
* Create a new user account
* Set '''no global permissions''' for user
* Set '''no template permissions''' for user
* 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).

==A person responsible for the survey wants to see the results of the survey and export them== 
* login as '''admin''' or user with '''SuperAdministrator''' permission.
* Create a new user account
* Set '''no global permissions''' for user
* Set '''no template permissions''' for user
* Set survey permissions to: '''Responses''': '''View/read''' and '''export''' , '''Statistics''': '''View/read'''


[[File:LimeSurveyCusomerOwnStatistics.jpg]]


----


To be moved somewhere else once better defined:


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.


{|
|Class||Description
|-
|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.
|-
|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.
|-
|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.
|-
|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.
|-
|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.
|}

=Use one-time passwords= 


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.


To enable this login method [[Optional settings#Use_one_time_passwords |a setting has to be turned on]] ($use_one_time_passwords = true;) in config.php.


The URL has to contain the following variables:
* '''user:''' The username normally used to login into LimeSurvey. This username has to exist in the 'users' table of the database.
* '''onepass:''' The plain text password which is then compared to the password in the 'users' table


A valid URL to login using a one-time password will look like this...


... for 1.81 to 1.92:


<div class="simplebox">http://www.yourdomain.org/limesurvey/admin/admin.php?user=myusername&onepass;=secretpassword</div>


...for 2.0 or later:


<div class="simplebox">http://www.yourdomain.org/limesurvey/index.php/admin/authentication/login?user=myusername&onepass;=secretpassword</div>


'''Things to watch out for:'''
* One time passwords have to be enabled by setting "$use_one_time_passwords = true;" (for 1.92), respective "use_one_time_passwords => true" (for 2.0 in config section) in config.php.
* The passed username has to exist in LimeSurvey's ''users'' table
* The one time password, which can be set by an external application, has to be stored as [http://www.php.net/md5 MD5 hash] in column ''one_time_pw'' of table ''users''
* 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.
* 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 a second time.
</translate>