LimeSurvey Manual - User contributions [en]

Question themes

2021-01-25T21:48:06Z

Cdorin:

= Introduction =

{{Alert|Update 25.01.2021: At the moment, the LS3 themes are not automatically converted and imported to LS4. Make sure the themes are compatible with LS4 beforehand.}}

Question Themes can be used to customize existing question types and change their visual appearance. Question Themes can only be built on core '''Question Types'''.

[[File:QuestionThemes1OverviewExample.png]]

[[File:QuestionThemes2OverviewExample.png]]

= Access =

To access the Question Themes, go to Configuration > Themes > Question Themes.

[[File:QuestionThemes1Overview.png]]

[[File:QuestionThemes2Overview.png]]

Here you can visualize both question types, core question themes, and user question themes.

= Visibility =

Question Themes are by default visible, but can be switched off. Once turned off, '''they will no longer be displayed inside the question type selector'''.

When the Option "[[Question Themes#Engine|show as question type]]" is enabled, all Question Themes will also be displayed inside the Question Type Selector.

[[File:QuestionThemes3Visibility.png]]

[[File:QuestionThemes4Visibility.png]]

= Uninstall and Available Question Themes =

All themes that are available for installation will be displayed in this section.

If you want to uninstall a question you can do so by selecting the Question Theme and choosing "uninstall" inside the dropdown menu under the table. They will now appear inside the available Question Themes table.

If a theme is uninstalled, it won't be available anymore inside the question type selector.

'''{{Note|Used Question Themes cannot be uninstalled while they are still used inside a Survey.}}'''

[[File:QuestionThemes5AvailableQuestions.png]]

= Broken Question Themes =

If there are errors while loading the [[Question Themes#Uninstall and Available Question Themes|available question themes]], they will be displayed in this category with an error message.

= Importing Question Theme =

It is possible to import Question Themes using the import button. During the import, the theme will be automatically installed and available for use.

When a theme is imported from LS3 or above, it will be automatically converted into the current standard.

The imported Theme must be in the '''ZIP''' format.

Before compressing the folder to zip, it must have the following structure:

[[File:QuestionThemes6ImportStructure.png]]

NAME/survey/questions/answer/QUESTIONTYPENAME/config.xml

= List of question types/IDs and default CSS 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
|-
|
|}

= Configuration =

The configuration of a question theme can be found inside config.xml.

An example can be found in the [https://github.com/LimeSurvey/LimeSurvey/tree/develop/docs/themes docs folder].

== Metadata ==

The Metadata describes the question theme. These settings will also be saved in the database.

[[File:QuestionThemes7MetaData.png]]

{| class="wikitable"
!Tag
!Type
!Mandatory
!Description
|-
| name || string || x || The name of the extension
|-
| type || string || x || Type of the extension; can be "plugin", "theme", etc; see below
|-
| title || string || x || The title that is displayed in the frontend
|-
| creationDate || date (YYYY-MM-DD) || || Date the extension was created
|-
| lastUpdate || date (YYYY-MM-DD) || || Date of the latest update
|-
| author || string || x || Plugin author
|-
| authorUrl || url || x || URL to author web page, necessary so that customers can contact author for support
|-
| copyright || string || x || Copyright Information
|-
| license || string || x || Extension licence
|-
| version || string as [https://semver.org/ semantic version] || x || Extension version number
|-
| apiVersion || string || x || Api version number
|-
| description || string || x || Information that will be shown as help text
|-
| questionType || string || x || The Question Type the Theme is associated with
|-
| group || string || x || The Group inside the selector it should be assigned to
|-
| subquestions || string || x || If or how many Subquestionscales should be displayed
|-
| answerscales || string || x || If or how many Answerscales should be displayed
|-
| hasdefaultvalues || string || x || If the Theme has default values
|-
| assessable || string || x || If the Theme can be used for Assessments (Quiz)
|-
| class || string || x || The HTML class name for the Theme
|}

== Files ==

List of the of files loaded via asset manager.

[[File:QuestionThemes8Files.png]]

== General Attributes ==

General attributes are attributes that are displayed on the right side of the question editor.

These attributes are predefined and are the same for all Question Themes. Currently, no new ones can be added. If you want to show or hide certain options for a Question Theme, you can remove or add the attribute.

[[File:QuestionThemes9GeneralAttributes.png]]

== Attributes ==

Attributes are options you want to give to a Question Theme and can be customized. They are visible at the bottom of the question editor.

[[File:QuestionThemes10Attributes.png]]

{| class="wikitable"
!Tag
|-
| name || The internal name
|-
| category ||The category tab in which the attribute should be displayed. This can also be a new one.
|-
| sortorder || At which position inside the tab it should be display from top left (smallest) to bottom right (highest)
|-
| inputtype || What type the input should be rendered as
|-
| default || The default value for the input field
|-
| help || The help text
|-
| caption || The frontend Title for the Theme
|-
| i18n ||
|-
| readonly ||
|-
| readonly_when_active ||
|-
| expression ||
|}

== Engine ==

Configuration for special load options

[[File:QuestionThemes11Engine.png]]

{| class="wikitable"
!Tag
!Type
!Mandatory
!Description
|-
| load_core_css || boolean |||| If core css should be loaded
|-
| load_core_js || boolean |||| If core js should be loaded
|-
| show_as_template || boolean |||| If the Theme should be loaded
|-
| show_as_question_type || boolean |||| If the Theme should be listed inside the question type selector
|}

= Compatibility =

== Converting LS3 to LS4 ==

When updating to LS4, the custom Question Themes will be updated to the LS4 standard. If the theme has missing attributes that cannot be automatically inserted, they will not be installed and instead be available for installation. If errors occur, they can be found under [[Question Themes#Broken Question Themes|the broken question themes table]].

If you want to import a Question Theme from LS3 into LS4 after upgrade, you can simply use the [[Question Themes#Importing Question Theme|import function]] which automatically converts the LS3 theme to the LS4 standard.

The question themes created for LS4 are not backwards compatible (cannot be used in LS3!).

== LS4 changes ==

The "custom_attributes" tag is no long needed. Attributes will always be defined inside the attributes tag instead. There is no need for different naming since they will be merged together when reading the Question Type.

Also, there have been additions to the metadata section of the xml. Additions are marked in red.

[[File:QuestionThemes12Compatibility.png]]

Question themes

2021-01-25T21:36:51Z

Cdorin:

= Introduction =

{{Alert|Update 25.01.2021: At the moment, the LS3 themes are not automatically converted and imported to LS4. Make sure the themes are compatible with LS4 beforehand.}}

= Overview =

Question Themes can be used to customize existing question types and change their visual appearance. Question Themes can only be built on core '''Question Types'''.

[[File:QuestionThemes1OverviewExample.png]]

[[File:QuestionThemes2OverviewExample.png]]

= Access =

To access the Question Themes, go to Configuration > Themes > Question Themes.

[[File:QuestionThemes1Overview.png]]

[[File:QuestionThemes2Overview.png]]

Here you can visualize both question types, core question themes, and question themes.

= Visibility =

Question Themes are by default visible, but can be switched off. They will no longer be displayed inside the Question Type and Question Theme Selector.

When the Option "[[#Engine|show as question type]]" is enabled all Question Themes will also be displayed inside the Question Type Selector.

[[File:QuestionThemes3Visibility.png]]

[[File:QuestionThemes4Visibility.png]]

= Uninstall and Available Question Themes =

All themes that are available for installation will be displayed in this section.

If you want to uninstall a question you can do so by selecting the Question Theme and choosing "uninstall" inside the dropdown menu under the table. They will now appear inside the available Question Themes.

Uninstalling a Question Theme will prevent the use inside selectors.
Used Question Themes cannot be uninstalled while they are still used inside a Survey.

[[File:QuestionThemes5AvailableQuestions.png]]

= Broken Question Themes =

If there are errors while loading [[#Uninstall and Available Question Themes|Available Question Themes]] they will be displayed in this category with an error message to the related theme.

= Importing Question Theme =

It is possible to import Question Themes using the import button. During the import, the theme will be automatically installed and available for use.

When a theme is imported from LS3 or above, it will be automatically converted into the current standard.

The imported Theme must be in the '''ZIP''' format.

Before compressing the folder to zip, it must have the following structure:

[[File:QuestionThemes6ImportStructure.png]]

NAME/survey/questions/answer/QUESTIONTYPENAME/config.xml

= List of question types/IDs and default CSS 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
|-
|
|}

= Configuration =

The configuration for a Question Theme can be found inside config.xml.
An example can be found in the [https://github.com/LimeSurvey/LimeSurvey/tree/develop/docs/themes docs folder].

== Metadata ==

The Metadata describes the Question Theme. These settings will also be saved in the database.
[[File:QuestionThemes7MetaData.png]]

{| class="wikitable"
!Tag
!Type
!Mandatory
!Description
|-
| name || string || x || The name of the extension
|-
| type || string || x || Type of the extension; can be "plugin", "theme", etc; see below
|-
| title || string || x || The title that is displayed in the frontend
|-
| creationDate || date (YYYY-MM-DD) || || Date the extension was created
|-
| lastUpdate || date (YYYY-MM-DD) || || Date of the latest update
|-
| author || string || x || Plugin author
|-
| authorUrl || url || x || URL to author web page, necessary so that customers can contact author for support
|-
| copyright || string || x || Copyright Information
|-
| license || string || x || Extension licence
|-
| version || string as [https://semver.org/ semantic version] || x || Extension version number
|-
| apiVersion || string || x || Api version number
|-
| description || string || x || Information that will be shown as help text
|-
| questionType || string || x || The Question Type the Theme is associated with
|-
| group || string || x || The Group inside the selector it should be assigned to
|-
| subquestions || string || x || If or how many Subquestionscales should be displayed
|-
| answerscales || string || x || If or how many Answerscales should be displayed
|-
| hasdefaultvalues || string || x || If the Theme has default values
|-
| assessable || string || x || If the Theme can be used for Assessments (Quiz)
|-
| class || string || x || The HTML class name for the Theme
|}

== Files ==

List of the of files loaded via asset manager.

[[File:QuestionThemes8Files.png]]

== General Attributes ==

Attributes that are displayed on the right side of the question editor.
These attributes are predefined and are the same for all Question Themes. Currently no new ones can be added. If you want to show or hide certain options for a Question Theme, you can remove or add the attribute.
[[File:QuestionThemes9GeneralAttributes.png]]

== Attributes ==

Attributes are options you want to give to a Question Theme and can be customized. They are visible at the bottom of the question editor.
[[File:QuestionThemes10Attributes.png]]
{| class="wikitable"
!Tag
|-
| name || The internal name
|-
| category ||The category tab in which the attribute should be displayed. This can also be a new one.
|-
| sortorder || At which position inside the tab it should be display from top left (smallest) to bottom right (highest)
|-
| inputtype || What type the input should be rendered as
|-
| default || The default value for the input field
|-
| help || The help text
|-
| caption || The frontend Title for the Theme
|-
| i18n ||
|-
| readonly ||
|-
| readonly_when_active ||
|-
| expression ||
|}

== Engine ==

Configuration for special load options

[[File:QuestionThemes11Engine.png]]

{| class="wikitable"
!Tag
!Type
!Mandatory
!Description
|-
| load_core_css || boolean |||| If core css should be loaded
|-
| load_core_js || boolean |||| If core js should be loaded
|-
| show_as_template || boolean |||| If the Theme should be loaded
|-
| show_as_question_type || boolean |||| If the Theme should be listed inside the question type selector
|}

= Compatibility =

== Converting LS3 to LS4 ==

When updating to LS4, the current custom Question Themes will be updated to the LS4 standard. If the theme has missing attributes that can not be automatically inserted, they will not be installed and instead be available for installation. If errors occur, they can be found under [[#Broken Question Themes]].
If you want to import a Question Theme from LS3 into LS4 after you have updated your installation, you can simply use the [[#Importing Question Theme]] which has an integrated functionality to automatically convert it.

Importing a Question Theme from LS4 into LS3 is not automatically possible.

== LS4 changes ==

The "custom_attributes" tag is no long needed. Attributes will always be defined inside the attributes tag instead. There is no need for different naming since they will be merged together when reading the Question Type.

Also, there have been additions to the metadata section of the xml. Additions are marked in red.

[[File:QuestionThemes12Compatibility.png]]

Question themes

2021-01-25T21:34:55Z

Cdorin:

= Introduction =

{{Alert|Update 25.01.2021: At the moment, the LS3 themes are not automatically converted and imported to LS4. Make sure the themes are compatible with LS4 beforehand.}}

== Overview ==

Question Themes can be used to customize existing question types and change their visual appearance. Question Themes can only be built on core '''Question Types'''.

[[File:QuestionThemes1OverviewExample.png]]

[[File:QuestionThemes2OverviewExample.png]]

== Access ==

To access the Question Themes, go to Configuration > Themes > Question Themes.

[[File:QuestionThemes1Overview.png]]

[[File:QuestionThemes2Overview.png]]

Here you can visualize both question types, core question themes, and question themes.

== Visibility ==
Question Themes are by default visible, but can be switched off. They will no longer be displayed inside the Question Type and Question Theme Selector.

When the Option "[[#Engine|show as question type]]" is enabled all Question Themes will also be displayed inside the Question Type Selector.

[[File:QuestionThemes3Visibility.png]]
[[File:QuestionThemes4Visibility.png]]

== Uninstall and Available Question Themes ==
All themes that are available for installation will be displayed in this section.

If you want to uninstall a question you can do so by selecting the Question Theme and choosing "uninstall" inside the dropdown menu under the table. They will now appear inside the available Question Themes.

Uninstalling a Question Theme will prevent the use inside selectors.
Used Question Themes cannot be uninstalled while they are still used inside a Survey.
[[File:QuestionThemes5AvailableQuestions.png]]

== Broken Question Themes ==
If there are errors while loading [[#Uninstall and Available Question Themes|Available Question Themes]] they will be displayed in this category with an error message to the related theme.

== Importing Question Theme ==
It is possible to import Question Themes using the import button. During the import, the theme will be automatically installed and available for use.

When a theme is imported from LS3 or above, it will be automatically converted into the current standard.

The imported Theme must be in the '''ZIP''' format.

Before compressing the folder to zip, it must have the following structure:

[[File:QuestionThemes6ImportStructure.png]]
NAME/survey/questions/answer/QUESTIONTYPENAME/config.xml

==List of question types/IDs and default CSS 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
|-
|
|}

== Configuration ==
The configuration for a Question Theme can be found inside config.xml.
An example can be found in the [https://github.com/LimeSurvey/LimeSurvey/tree/develop/docs/themes docs folder].

=== Metadata ===
The Metadata describes the Question Theme. These settings will also be saved in the database.
[[File:QuestionThemes7MetaData.png]]

{| class="wikitable"
!Tag
!Type
!Mandatory
!Description
|-
| name || string || x || The name of the extension
|-
| type || string || x || Type of the extension; can be "plugin", "theme", etc; see below
|-
| title || string || x || The title that is displayed in the frontend
|-
| creationDate || date (YYYY-MM-DD) || || Date the extension was created
|-
| lastUpdate || date (YYYY-MM-DD) || || Date of the latest update
|-
| author || string || x || Plugin author
|-
| authorUrl || url || x || URL to author web page, necessary so that customers can contact author for support
|-
| copyright || string || x || Copyright Information
|-
| license || string || x || Extension licence
|-
| version || string as [https://semver.org/ semantic version] || x || Extension version number
|-
| apiVersion || string || x || Api version number
|-
| description || string || x || Information that will be shown as help text
|-
| questionType || string || x || The Question Type the Theme is associated with
|-
| group || string || x || The Group inside the selector it should be assigned to
|-
| subquestions || string || x || If or how many Subquestionscales should be displayed
|-
| answerscales || string || x || If or how many Answerscales should be displayed
|-
| hasdefaultvalues || string || x || If the Theme has default values
|-
| assessable || string || x || If the Theme can be used for Assessments (Quiz)
|-
| class || string || x || The HTML class name for the Theme
|}

=== Files ===
List of the of files loaded via asset manager.

[[File:QuestionThemes8Files.png]]

=== General Attributes ===
Attributes that are displayed on the right side of the question editor.
These attributes are predefined and are the same for all Question Themes. Currently no new ones can be added. If you want to show or hide certain options for a Question Theme, you can remove or add the attribute.
[[File:QuestionThemes9GeneralAttributes.png]]

=== Attributes ===
Attributes are options you want to give to a Question Theme and can be customized. They are visible at the bottom of the question editor.
[[File:QuestionThemes10Attributes.png]]
{| class="wikitable"
!Tag
|-
| name || The internal name
|-
| category ||The category tab in which the attribute should be displayed. This can also be a new one.
|-
| sortorder || At which position inside the tab it should be display from top left (smallest) to bottom right (highest)
|-
| inputtype || What type the input should be rendered as
|-
| default || The default value for the input field
|-
| help || The help text
|-
| caption || The frontend Title for the Theme
|-
| i18n ||
|-
| readonly ||
|-
| readonly_when_active ||
|-
| expression ||
|}

=== Engine ===
Configuration for special load options

[[File:QuestionThemes11Engine.png]]

{| class="wikitable"
!Tag
!Type
!Mandatory
!Description
|-
| load_core_css || boolean |||| If core css should be loaded
|-
| load_core_js || boolean |||| If core js should be loaded
|-
| show_as_template || boolean |||| If the Theme should be loaded
|-
| show_as_question_type || boolean |||| If the Theme should be listed inside the question type selector
|}

== Compatibility ==
=== Converting LS3 to LS4 ===
When updating to LS4, the current custom Question Themes will be updated to the LS4 standard. If the theme has missing attributes that can not be automatically inserted, they will not be installed and instead be available for installation. If errors occur, they can be found under [[#Broken Question Themes]].
If you want to import a Question Theme from LS3 into LS4 after you have updated your installation, you can simply use the [[#Importing Question Theme]] which has an integrated functionality to automatically convert it.

Importing a Question Theme from LS4 into LS3 is not automatically possible.

=== LS4 changes ===
The "custom_attributes" tag is no long needed. Attributes will always be defined inside the attributes tag instead. There is no need for different naming since they will be merged together when reading the Question Type.

Also, there have been additions to the metadata section of the xml. Additions are marked in red.
[[File:QuestionThemes12Compatibility.png]]

Question themes

2021-01-25T17:30:43Z

Cdorin:

{{Alert|Update 25.01.2021: At the moment, the LS3 themes are not automatically converted and imported to LS4. Make sure the themes are compatible with LS4 beforehand.}}

== Overview ==

Question Themes can be used to customize existing question types and change their visual appearance. Question Themes can only be built on core '''Question Types'''.

[[File:QuestionThemes1OverviewExample.png]]

[[File:QuestionThemes2OverviewExample.png]]

== Access ==

To access the Question Themes, go to Configuration > Themes > Question Themes.

[[File:QuestionThemes1Overview.png]]

[[File:QuestionThemes2Overview.png]]

Here you can visualize both question types, core question themes, and question themes.

== Visibility ==
Question Themes are by default visible, but can be switched off. They will no longer be displayed inside the Question Type and Question Theme Selector.

When the Option "[[#Engine|show as question type]]" is enabled all Question Themes will also be displayed inside the Question Type Selector.

[[File:QuestionThemes3Visibility.png]]
[[File:QuestionThemes4Visibility.png]]

== Uninstall and Available Question Themes ==
All themes that are available for installation will be displayed in this section.

If you want to uninstall a question you can do so by selecting the Question Theme and choosing "uninstall" inside the dropdown menu under the table. They will now appear inside the available Question Themes.

Uninstalling a Question Theme will prevent the use inside selectors.
Used Question Themes cannot be uninstalled while they are still used inside a Survey.
[[File:QuestionThemes5AvailableQuestions.png]]

== Broken Question Themes ==
If there are errors while loading [[#Uninstall and Available Question Themes|Available Question Themes]] they will be displayed in this category with an error message to the related theme.

== Importing Question Theme ==
It is possible to import Question Themes using the import button. During the import, the theme will be automatically installed and available for use.

When a theme is imported from LS3 or above, it will be automatically converted into the current standard.

The imported Theme must be in the '''ZIP''' format.

Before compressing the folder to zip, it must have the following structure:

[[File:QuestionThemes6ImportStructure.png]]
NAME/survey/questions/answer/QUESTIONTYPENAME/config.xml

==List of question types/IDs and default CSS 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
|-
|
|}

== Configuration ==
The configuration for a Question Theme can be found inside config.xml.
An example can be found in the [https://github.com/LimeSurvey/LimeSurvey/tree/develop/docs/themes docs folder].

=== Metadata ===
The Metadata describes the Question Theme. These settings will also be saved in the database.
[[File:QuestionThemes7MetaData.png]]

{| class="wikitable"
!Tag
!Type
!Mandatory
!Description
|-
| name || string || x || The name of the extension
|-
| type || string || x || Type of the extension; can be "plugin", "theme", etc; see below
|-
| title || string || x || The title that is displayed in the frontend
|-
| creationDate || date (YYYY-MM-DD) || || Date the extension was created
|-
| lastUpdate || date (YYYY-MM-DD) || || Date of the latest update
|-
| author || string || x || Plugin author
|-
| authorUrl || url || x || URL to author web page, necessary so that customers can contact author for support
|-
| copyright || string || x || Copyright Information
|-
| license || string || x || Extension licence
|-
| version || string as [https://semver.org/ semantic version] || x || Extension version number
|-
| apiVersion || string || x || Api version number
|-
| description || string || x || Information that will be shown as help text
|-
| questionType || string || x || The Question Type the Theme is associated with
|-
| group || string || x || The Group inside the selector it should be assigned to
|-
| subquestions || string || x || If or how many Subquestionscales should be displayed
|-
| answerscales || string || x || If or how many Answerscales should be displayed
|-
| hasdefaultvalues || string || x || If the Theme has default values
|-
| assessable || string || x || If the Theme can be used for Assessments (Quiz)
|-
| class || string || x || The HTML class name for the Theme
|}

=== Files ===
List of the of files loaded via asset manager.

[[File:QuestionThemes8Files.png]]

=== General Attributes ===
Attributes that are displayed on the right side of the question editor.
These attributes are predefined and are the same for all Question Themes. Currently no new ones can be added. If you want to show or hide certain options for a Question Theme, you can remove or add the attribute.
[[File:QuestionThemes9GeneralAttributes.png]]

=== Attributes ===
Attributes are options you want to give to a Question Theme and can be customized. They are visible at the bottom of the question editor.
[[File:QuestionThemes10Attributes.png]]
{| class="wikitable"
!Tag
|-
| name || The internal name
|-
| category ||The category tab in which the attribute should be displayed. This can also be a new one.
|-
| sortorder || At which position inside the tab it should be display from top left (smallest) to bottom right (highest)
|-
| inputtype || What type the input should be rendered as
|-
| default || The default value for the input field
|-
| help || The help text
|-
| caption || The frontend Title for the Theme
|-
| i18n ||
|-
| readonly ||
|-
| readonly_when_active ||
|-
| expression ||
|}

=== Engine ===
Configuration for special load options

[[File:QuestionThemes11Engine.png]]

{| class="wikitable"
!Tag
!Type
!Mandatory
!Description
|-
| load_core_css || boolean |||| If core css should be loaded
|-
| load_core_js || boolean |||| If core js should be loaded
|-
| show_as_template || boolean |||| If the Theme should be loaded
|-
| show_as_question_type || boolean |||| If the Theme should be listed inside the question type selector
|}

== Compatibility ==
=== Converting LS3 to LS4 ===
When updating to LS4, the current custom Question Themes will be updated to the LS4 standard. If the theme has missing attributes that can not be automatically inserted, they will not be installed and instead be available for installation. If errors occur, they can be found under [[#Broken Question Themes]].
If you want to import a Question Theme from LS3 into LS4 after you have updated your installation, you can simply use the [[#Importing Question Theme]] which has an integrated functionality to automatically convert it.

Importing a Question Theme from LS4 into LS3 is not automatically possible.

=== LS4 changes ===
The "custom_attributes" tag is no long needed. Attributes will always be defined inside the attributes tag instead. There is no need for different naming since they will be merged together when reading the Question Type.

Also, there have been additions to the metadata section of the xml. Additions are marked in red.
[[File:QuestionThemes12Compatibility.png]]

Make your plugin compatible with LS4

2021-01-20T09:26:52Z

Cdorin: Created page with "Text"

Text

LimeSurvey Manual

2021-01-20T09:26:34Z

Cdorin:

<languages />
<translate>

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


<div style="clear:right;float:right;"><div class="simplebox">
Main Chapters:
*[[Installation - LimeSurvey CE]]
*[[Getting Started]]
*[[Administering LimeSurvey]]
*[[Surveys - introduction|Surveys - Introduction]]
*[[Surveys - management|Surveys - Management]]
*[[Not Categorized and Advanced Features]]
*[[General FAQ]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
*[[Workarounds]]
*[[License]]
*[[Version change log| Version Change Log]]
*[[Plugins - advanced|Plugins - Advanced]]
</div></div>


[https://www.limesurvey.org/ LimeSurvey] allows users (think of users as "administrators" NOT participants!) to quickly create intuitive, powerful online question and answer surveys that can work for only a few participants or thousands of participants without much effort. The survey software is self-guiding for the respondents who are participating. This manual is thus focused on how to install the application, administer the installation, as well as support survey creators, administrators, and users who need to generate reports.


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


The main chapters of the manual are located in the box to the right. You can also scroll down further on this page to see the complete table of contents and go directly to the topic you are interested in.


Are you still having trouble finding what you want? Don't forget the general '''search box''' (upper right corner of the wiki), our [[General FAQ]], and [[Workarounds]] list. If you are looking for community help, join our [https://www.limesurvey.org/en/forum/ discussion forums] and check the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel].


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

= Manual - Table of Contents = 


*[[LimeSurvey PRO vs LimeSurvey CE]]
**[[LimeSurvey PRO vs LimeSurvey CE#What do I need?|What do I need?]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
**[[Quick start guide - LimeSurvey 3.0+|Quick Start Guide - LimeSurvey 3.0+]]


*[[Installation - LimeSurvey CE]]
**[[Optional settings|Optional Settings]]
**[[Upgrading from a previous version|Upgrading From a Previous Version]]
***[[ComfortUpdate]]
**[[Installation using a command line interface (CLI)|Installation Using a Command Line Interface (CLI)]]
**[[Transferring an installation|Transferring an Installation]]
**[[Installation FAQ]]
***[[Installation security hints|Installation Security Hints]]
***[[Localization]]
*[[Getting Started]]
**[[First login - your user preferences|First Login - Your User Preferences]]
*[[Administering LimeSurvey]]
**[[Administering LimeSurvey#Settings Tab|Settings Tab]]
***[[Home page settings|Home Page Settings]]
***[[Global settings|Global Settings]]
***[[Plugin manager|Plugin Manager]]
***[[Menu configuration|Menu Configuration]]{{NewIn|3.0}}
***[[Menu entries configuration|Menu Entries Configuration]]{{NewIn|3.0}}
**[[Administering LimeSurvey#Users Tab|Users Tab]]
***[[Manage users|Manage Users]]
***[[Manage user groups|Manage User Groups]]
***[[Central Participant Database]] (CPDB)
**[[Administering LimeSurvey#Advanced Tab|Advanced Tab]]
***[[Theme editor|Theme Editor]] (LimeSurvey 2.x)
****[[New Template System in LS3.x|New Template System In LS3.x]]
****[[Themes]]
****[[Question themes|Question Themes]]
***[[Label sets|Label Sets]]
***[[Check data integrity|Check Data Integrity]]
***[[Backup entire database|Backup Entire Database]]
***[[ComfortUpdate]]


*[[Surveys - introduction|Surveys - Introduction]]
**[[Surveys - introduction#Create_a_new_survey|Create a Survey]]
***[[Surveys - introduction#Import a survey|Import a Survey]]
***[[Surveys - introduction#Copy a survey|Copy a Survey]]
**[[Survey settings|Survey Settings]]
***[[Overview]]
***[[General settings|General Settings]]
***[[Text elements|Text Elements]]
***[[Data policy settings|Data Policy Settings]]
***[[Theme options|Theme Options]]
***[[Presentation]]
***[[Participant settings|Participant Settings]] (was ''Participant Tokens'')
***[[Notifications_%26_data|Notifications & Data]]
***[[Publication & access|Publication & Access]]
**[[Survey menu|Survey Menu]]
***[[List questions|List Questions]]
***[[List question groups|List Question Groups]]
***[[Reorder questions and question groups|Reorder Questions and Question Groups]]
***[[Survey participants|Survey Participants]] (was ''Tokens'')
****[[Email bounce tracking system|Email Bounce Tracking System]]
***[[Survey quotas|Quotas]]
***[[Assessments]]
***[[Survey permissions|Survey Permissions]]
***[[Email templates|Email Templates]]
****[[Email placeholders|Email Placeholders]]
***[[Panel integration|Panel Integration]]
***[[Resources]]
***[[Plugin menu|Plugin Menu]]
**[[Survey structure|Survey Structure]]
**[[Question groups - introduction|Question Groups - Introduction]]
***[[Question_groups_-_introduction#Question_group_actions|Question Group Toolbar Options]]
***[[Question groups - introduction#Preview question group|Preview Question Group]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change Group Order]]
**[[Questions - introduction|Questions - Introduction]]
***[[Question types|Question Types]]
****[[Question type - Array|Question Type - Array]]
****[[Question type - Array by column|Question Type - Array by column]]
****[[Question type - Array dual scale|Question Type - Array dual scale]]
****[[Question type - Array (5 point choice)|Question Type - Array (5 point choice)]]
****[[Question type - Array (10 point choice)|Question Type - Array (10 point choice)]]
****[[Question type - Array (Increase-Same-Decrease)|Question Type - Array (Increase-Same-Decrease)]]
****[[Question type - Array (Numbers)|Question Type - Array (Numbers)]]
****[[Question type - Array (Texts)|Question Type - Array (Texts)]]
****[[Question type - Array (Yes-No-Uncertain)|Question Type - Array (Yes-No-Uncertain)]]
****[[Question type - Date|Question Type - Date]]
****[[Question type - Equation|Question Type - Equation]]
****[[Question type - File upload|Question Type - File upload]]
****[[Question type - Gender|Question Type - Gender]]
****[[Question type - Language switch|Question Type - Language switch]]
****[[Question type - Numerical input|Question Type - Numerical input]]
****[[Question type - Multiple numerical input|Question Type - Multiple numerical input]]
****[[Question type - Ranking|Question Type - Ranking]]
****[[Question type - Text display|Question Type - Text display]]
****[[Question type - Yes-No|Question Type - Yes-No]]
****[[Question type - Multiple choice|Question Type - Multiple choice]]
****[[Question type - Multiple choice with comments|Question Type - Multiple choice with comments]]
****[[Question type - 5 point choice|Question Type - 5 point choice]]
****[[Question type - List (Dropdown)|Question Type - List (Dropdown)]]
****[[Question type - List (Radio)|Question Type - List (Radio)]]
****[[Question type - List with comment|Question Type - List with comment]]
****[[Question type - Short free text|Question Type - Short free text]]
*****[[Question type_-_Short_free_text#Location|Set up maps and store location]]
****[[Question type - Long free text|Question Type - Long free text]]
****[[Question type - Huge free text|Question Type - Huge free text]]
****[[Question type - Multiple short text|Question Type - Multiple short text]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change question order]]
***[[Question toolbar options]]
****[[Preview function]]
****[[Edit question]]
****[[Check question logic]]
****[[Delete question]]
****[[Export question]]
****[[Copy question]]
****[[Setting conditions]]
****[[Adding answers or subquestions]]
****[[Default answers]]
**[[ExpressionScript Engine - Quick start guide]]
***[[ExpressionScript - Presentation]]
***[[ExpressionScript How-tos]]
***[[ExpressionScript examples]]
***[[ExpressionScript Engine roadmap]]
***[[ExpressionScript for developers]]
***[[ExpressionScript sample surveys]]
****[[Expression Manager]] - old page with full documentation
**[[Show logic file]]
*[[Survey toolbar options]]
**[[Testing a survey]]
**[[Activating a survey]]
**[[Running a survey safely]]
***[[Changing an active survey]]
**[[Closing a survey]]
**[[Iterate survey]]
**[[Tools]]
***[[Delete survey]]
***[[Quick-translation]]
***[[Reset conditions]]
***[[Survey logic file]]
***[[Regenerate question codes]]
**[[Display/Export survey]]
***[[QueXML PDF Export]]
***[[Tab Separated Value survey structure]]
**[[Survey participants]]
**[[Responses (survey results)]]
***[[Responses & statistics]]
****[[Responses & statistics#Responses summary|Response summary]]
****[[Responses]]
****[[Data entry]]
****[[Statistics]]
*****[[Statistics - expert mode]]
*****[[Statistics - simple mode]]
****[[Timing statistics]]
****[[Export responses]]
****[[Import responses]]
*****[[Problems & solutions]]
****[[View saved but not submitted responses]]
****[[Iterate survey#General|Iterate survey]]
****[[Batch deletion]]
***[[Data entry]]
***[[Partial (saved) responses]]
*[[Multilingual survey]]
*[[Not categorized and advanced features]]
**[[SGQA identifier]]
**[[Using regular expressions]]
**[[URL fields]]
**[[RemoteControl 2 API]]
**[[Data encryption]]
*[[General FAQ]]
*[[Troubleshooting]]
*[[Workarounds]]
**[[Workarounds: Question design, layout and templating]]
**[[Workarounds: Manipulating a survey at runtime using Javascript]]
**[[Workarounds: Survey behaviour]]
**[[Workarounds: Further solutions provided by LimeSurvey users]]
*[[License]]
*[[Version change log]]
*[[Plugins - advanced]]
**[[Make your plugin compatible with LS4]]
**[[Available third party plugins]]

=LimeSurvey Development= 
*[[Version guide]] - A short guide on version numbering
*[[Development overview]] - General pages about LimeSurvey development
*[[LimeSurvey 2.x development documentation]]
*[[New Template System in LS3.x]] - Quick overview of the novelties of the LimeSurvey 3 template system

=Translating LimeSurvey= 


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

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

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

</translate>

Survey group permissions

2020-12-22T09:40:11Z

Cdorin: Created page with "In construction"

In construction

LimeSurvey PRO vs LimeSurvey CE

2020-10-13T16:52:50Z

Cdorin:

<languages />
<translate>


__TOC__

=Introduction= 


Before starting the discussion about '''LimeSurvey PRO''' (LimeSurvey Cloud) and '''LimeSurvey CE''' (LimeSurvey Community Edition), it is important to understand the difference between ''LimeSurvey'' and ''LimeSurvey GmbH''. ''LimeSurvey'' refers to the web server-based software that is freely distributed under the [https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html GNU General Public License v2] (GPL v2) and above. ''LimeSurvey GmbH'' refers to the company that was built around the LimeSurvey software in order to better coordinate its development and provide various LimeSurvey paid services (e.g., hosting, personalized templates, add-on packages, technical support, etc.).


<div class="simplebox">[[File:help.png]] Find more information about LimeSurvey's license at https://community.limesurvey.org/licence-trademark/.</div>


Because LimeSurvey has a General Public License and is an <u>[https://en.wikipedia.org/wiki/Open_source_software open-source software]</u>, it can be used, modified, and distributed for commercial, private, and educational purposes by anyone, '''With the exception of the name and logo, which are trademarked'''. For example, LimeSurvey can easily be used to create and distribute questionnaires for the evaluation of a university class or professor, or it can be installed on a personal server in order to conduct online/offline marketing research for your company.


<div class="simplebox">[[File:help.png]] LimeSurvey is an open-source software. This means that its code is fully disclosed. To access it, check the following GitHub link: https://github.com/LimeSurvey/LimeSurvey</div>


In order to install LimeSurvey on your personal computer (for development purposes) or on your server, a minimal set of requirements need to be met. For an exhaustive step-by-step explanation on how to install LimeSurvey, read our [[Installation - LimeSurvey CE|installation guideline]].


However, for users who might find the installation process too time consuming and for those who have no server administration knowledge, [https://www.limesurvey.org/ LimeSurvey GmbH] offers [https://www.limesurvey.org/en/pricing PRO hosting services]. With [https://www.limesurvey.org/en/pricing PRO hosting services], the installation is created for you!


<center>[[File:provsce.png]]</center>


<div class="simplebox">[[File:help.png]] Quite often, you will see words related to ''hosting services'', ''self-hosted software'', and ''personal server'' mentioned within this wiki section. We suggest the [https://www.limesurvey.org/en/blog/20-blog/120-hosting-solutions-two-sides-of-the-same-coin following post from our blog] to better grasp the hosting-related concepts.</div>

=LimeSurvey PRO vs LimeSurvey CE= 


Check the following table in order to better grasp the main differences that exist between the two services:


{| class="wikitable" style="text-align: center; color: black"
|+LimeSurvey PRO vs LimeSurvey CE - Summary
!LimeSurvey PRO
!LimeSurvey CE
|-
|Hosting is provided by LimeSurvey. The creation of an up-and-running installation should not take more than 5 minutes.
|Self-hosted.
|-
|You can choose one of the four types of subscriptions: [https://www.limesurvey.org/en/pricing FREE, BASIC, EXPERT and ENTERPRISE].
|You may either use the free version or pick one of the [https://www.limesurvey.org/en/pricing three premium packages]. The premium package contains the ComfortUpdate feature, access to older versions and a multitude of design templates.
|-
|Always uses the latest stable version of LimeSurvey.
|You get access not only to the latest releases, but also to the older ones. You choose which to use.
|-
|Technical support included for the paid packages.
|Technical ComfortUpdate support included for the premium packages.
|-
|Contains all the features that make LimeSurvey great.
|Contains all the features that make LimeSurvey great.
|-
|LimeSurvey PRO comes with response and storage usage buttons due to the limitations imposed by the subscription packages.
|LimeSurvey CE does not contain response and storage usage buttons. Limitation are due to the amount of space allocated from the personal server to the LimeSurvey-related tasks.
|-
|No server access. This means that no third-party plugins/extensions can be added to your LimeSurvey installation.
|If you own your server, you can access your LimeSurvey installation. You can start [[Optional settings|tweaking it]] and further enhance it by adding additional extensions/add-ons.
|-
|The ComfortUpdate tool is utilized to upgrade the LimeSurvey installation.
|The ComfortUpdate tool is utilized to upgrade the LimeSurvey installation. The update can also be done manually.
|-
|You save valuable time by using our available hosting and avoiding any server or installation configuration.
|Ideal for hands-on people with technical knowledge. [[LimeSurvey_Manual|The LimeSurvey manual]] Is a great place to start learning about this software.
|-
|Reliable response inflow due to a self-renewing subscription system.
|The only limitation is related to your server and its configuration.
|-
|More flexibility - You have 3 days until the date of renewal to cancel your subscription!
|The software is hosted on your servers. No linkages between the activity performed by you with the help of the ''LimeSurvey software'' and ''LimeSurvey GmbH''.
|}


{{Box|Please note that the above table is just a summary of the main features provided by the two versions of LimeSurvey. For an exhaustive description, access the following limesurvey.org links: [https://community.limesurvey.org/comfort-update-extension/ LimeSurvey CE] to get a complete description of what each of them can do.}}

==LimeSurvey CE== 


Convinced that '''LimeSurvey CE''' is right for you? You can install it on your server now. To download LimeSurvey CE, access the '''Resources''' tab from the [https://community.limesurvey.org/downloads/ LimeSurvey] main toolbar and click on the Download option.


<center>[[File:LimeSurvey.org - Project - Downloads.png]]</center>


The following page will load:


<center>[[File:Project - Downloads - Display.png]]</center>


Four boxes will be displayed:
*'''LimeSurvey PRO''': If you click on the '''create installation''' button, you will be first asked to create a [https://www.limesurvey.org/en/pricing LimeSurvey.org] account in order to be able to access your online LimeSurvey installation. If you wish to use our hosting services, continue reading the following quick start guide: [[Quick start guide - LimeSurvey 3.0+|LimeSurvey PRO Quick Start Guide]].
*'''LimeSurvey CE''': This option allows you to download the LimeSurvey software, archived in different formats and also in an executable file (usually the latest link). Use this option if you would like to install LimeSurvey on your own server or on your own computer for personal testing. It is ideal for hands-on people with technical knowledge. You will see that LimeSurvey CE is divided into stable releases and development releases. For a rock-solid software, go for the stable release. However, if you would like to test new LimeSurvey features and you want help us solve bugs, go for the development release.


<div class="simplebox">[[File:help.png]] To get access to the latest software developments, [https://github.com/LimeSurvey/LimeSurvey follow us on GitHub].</div>


*'''Templates:''' You may find example surveys here, label sets, and question templates in various languages. All the templates are community-made. You can also contribute by uploading your work and making it publicly available to other users.
*'''Extensions:''' LimeSurvey supports plugins and extensions. By clicking on the "SEE EXTENSIONS" button, you get access to a directory that contains all the LimeSurvey third-party extensions (your own contribution can also be listed there).


{{Alert|Title=Attention|text=Only LimeSurvey CE supports third-party plugins! If you would like to use an extension in LimeSurvey Pro, please write [mailto:support@limesurvey.org Support].}}

==LimeSurvey PRO== 


Access the following [[Quick start guide - LimeSurvey 3.0+|step-by-step guide]] to learn how to create a [https://www.limesurvey.org/en/pricing LimeSurvey PRO] account and launch your first survey.


<div class='simplebox'> [[File:help.png]] You can also check the following [https://www.youtube.com/watch?v=oyoq14XpkwA video tutorial] on how to set up a professional account on LimeSurvey.</div>

=What do I need?= 


There is a lot of information to grasp. We are completely aware of this and you might feel a bit overwhelmed.
We suggest you do a '''cost-benefit analysis'''. Some aspects that are worth taking into consideration:
*'''Capital:''' Think of the costs of running a server for example. Even though a lot of low-cost hosting providers can be found online, take into account that you have to take care not only of your LimeSurvey installation, but also of the server configuration. If you want to create more complex surveys and/or install/create additional plugins, employees with knowledge in PHP, HTML, CSS will be needed - which means higher costs for you and your business.
*'''Human resources''': If complex surveys are created, employees with IT-related skills might be needed. That is why it is better (sometimes) to outsource such services. You may use our LimeSurvey PRO services or the help provided by our official partners.
*'''Time:''' Time is a limited resource. Different time-related constraints (e.g., deadlines, lots of qualitative research requests from your clients, etc.) transform time into an important independent variable that should definitely influence your final decision.


Think of all your possible needs and available resources before choosing between LimeSurvey PRO and LimeSurvey CE.


Generally, if you want to use LimeSurvey without any download or configuration, use should LimeSurvey PRO. You can test it freely as long as you want and then purchase one of the subscription packages. However, if you have a running server infrastructure and want to integrate LimeSurvey into that, take a look at LimeSurvey CE. We also offer great LimeSurvey CE packages to enhance your installation with one-click updates and more custom themes.


{{Note|Additional help can be found at one of our partners listed here: https://www.limesurvey.com/.}}

=What if I still have questions?= 


We have a lovable community. You are more than welcome to post your questions and/or thoughts on our [https://forum.limesurvey.org LimeSurvey forums] or [https://discord.gg/DEjguXn|LimeSurvey Discord channel]:


<div class="simplebox"><center>'''[https://discord.gg/DEjguXn Direct link to the official LimeSurvey Discord group]'''</center></div>

</translate>

LimeSurvey PRO vs LimeSurvey CE

2020-10-13T16:52:19Z

Cdorin:

File:Free LimeSurvey Pro.png

2020-10-13T16:45:57Z

Cdorin: Cdorin uploaded a new version of File:Free LimeSurvey Pro.png

File:Editions and Pricing - LimeSurvey Pro.png

2020-10-13T16:45:35Z

Cdorin: Cdorin uploaded a new version of File:Editions and Pricing - LimeSurvey Pro.png

Quick start guide - LimeSurvey 3.0+

2020-10-09T15:25:18Z

Cdorin:

<languages />
<translate>


__TOC__


<div class="simplebox">[[File:help.png]] '''Note''': Please note that this is just a basic quick start guide. Its aim is to get new users acquainted with the main functions and features provided by [https://www.limesurvey.org LimeSurvey]. If you would like to know more about LimeSurvey and its capabilities, continue reading [https://manual.limesurvey.org our manual]. If further questions arise, please post them on [https://www.limesurvey.org/forum our forum] or join the [https://discord.gg/DEjguXn LimeSurvey Discord channel]. We are looking forward to hearing from you! </div>

=Introduction - What is LimeSurvey?= 


LimeSurvey is a free and open source online survey application written in [https://secure.php.net/manual/en/intro-whatis.php PHP] and distributed under the [https://www.gnu.org/licenses/gpl-2.0.html GNU General Public License 2]. The software enables users to develop and publish online surveys, collect responses, create statistics, and export the resulting data to other applications. You can either install LimeSurvey on your own server ([https://www.limesurvey.org/editions-and-prices/limesurvey-ce/editions-and-prices-community LimeSurvey CE]), or use one of our hosting services ([https://www.limesurvey.org/editions-and-prices/limesurvey-pro/editions-and-prices-professional LimeSurvey Pro]).


The following start guide was written using [https://www.limesurvey.org/editions-and-prices/limesurvey-pro/editions-and-prices-professional LimeSurvey Pro]. To install LimeSurvey on your own server, refer to the [https://manual.limesurvey.org/Installation installation section] in [https://manual.limesurvey.org/LimeSurvey_Manual the LimeSurvey manual].

=Create a Free LimeSurvey Account= 
[https://www.limesurvey.org LimeSurvey] allows users to create a free account to test its features and core functions. To try it out, you can either select '''Sign Up For Free''' or '''Pricing''' from the [https://www.limesurvey.org LimeSurvey website] and complete the registration.


<center>[[File:Editions and Pricing - LimeSurvey Pro.png]]</center>


{{Note|Check the [https://www.limesurvey.org/editions-and-prices following link] for a short comparison between [https://www.limesurvey.org/editions-and-prices/limesurvey-pro/editions-and-prices-professional LimeSurvey Pro] and [https://www.limesurvey.org/editions-and-prices/limesurvey-ce/editions-and-prices-community LimeSurvey CE].}}


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


Selecting '''Sign up For Free''' will take you directly to the registration page.


Four options will be displayed when '''Pricing''' is selected: '''Free''', '''Basic''', '''Expert''', and '''Enterprise'''. Click on the '''Register Now''' button in the '''FREE''' option box (the registration page will be displayed).


<center>[[File:Free LimeSurvey Pro.png]]</center>


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


The next step is filling in the following fields:
*'''Username:''' the username of your account which will also be used to access your LimeSurvey installation
*'''Email:''' the email the activation link will be sent to
*'''Password:''' the password of your account which will also be used to access your LimeSurvey installation


<center>[[File:Join LimeSurvey pro.png]]</center>


Click in each text box for more details about each field. You can also subscribe to the LimeSurvey newsletter in order to receive help, tips, updates, service discounts, and the latest news.


<div class="simplebox">[[File:help.png]] '''Note''': You can unsubscribe at any time: (1) Sign into your account. (2) Click on your username at the top of the page and select ''Your LimeSurvey Profile.'' (3) Select ''Community Profile'' from the Profile Menu on the left side of the page. (4) Click on ''Mailing Lists'' in the middle of the page. (4) Uncheck the LimeSurvey Newsletter box. </div>

For faster registration, LimeSurvey allows each user to sign up via their Twitter, Gmail, or GitHub account. LimeSurvey will gather the basic information required from your selected source.


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


After creating your LimeSurvey account by clicking on the '''SIGN UP''' button, you will receive an email from us. This email contains the account activation link that you should click on to access your newly created account. Clicking the link takes you to the [https://www.limesurvey.org/ LimeSurvey website] and automatically logs you into your LimeSurvey account.

=Create a Free LimeSurvey Installation= 


To access your survey link, you have first to create an installation. Click on your username from the main toolbar and select '''Your LimeSurvey profile'''.


<center>[[File:TestLimeSurveyNow profile.png]]</center>


Choose '''Survey Application''' from the Profile Menu located on the left side of the screen to create an installation.


<center>[[File:Installations - Create an installation.png]]</center>


You will be asked to:
*Type in the Domain name (the URL link of the questionnaire).
*Choose one of the four server locations that best suits your needs.


<center>[[File:Profile Menu - Installations.png]]</center>


When the domain-related fields are completed and saved, the installation process will start. This can take up to 10 seconds. Please refer to the example installation setting page below.


<center>[[File:LimeSurvey Pro - your installation settings.png]]</center>


You can now access your server by clicking on the ''administration URL''. To sign in to your LimeSurvey installation, use your [https://www.limesurvey.org LimeSurvey.org] credentials.


<center>[[File:Sign in to your LimeSurvey installation.png]]</center>


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

=Start Using LimeSurvey= 
Logging in takes you to the LimeSurvey home page, which contains a toolbar located in the top right corner and a set of boxes located in the middle of the page corresponding to six LimeSurvey functionality shortcuts.


The toolbar contains the following options:


<center>[[File:QSG LS3 Homepage toolbar LimeSurvey.png]]</center>


*'''Tutorials''': Here, (in any LimeSurvey 3+ installation), you will find a ''"Beginner Tour"'' tutorial to help you get a basic understanding of LimeSurvey and its most essential features.
*'''Configuration''': Select this option to access all of the ''Advanced'', ''User'', and ''Settings'' functions to administer your LimeSurvey installation.
**'''Settings''': Here you will find options that can help you customize your LimeSurvey installation.
***''Home page settings:'' You can use this option to tweak the settings of the home page.
***''Global settings:'' The changes done here affect the entire LimeSurvey installation, influencing also the setting of non-superadministrator users for all users.
***''Plugin manager:'' Here is where you find the options to activate a series of plugins that are supported by the LimeSurvey team. New plugins can also be added to your installation.
**'''Users''': Here you can find options related to the management of the users and survey participants.
***''Manage survey administrators:'' New survey administrators can be added from here.
***''Create/edit user groups:'' This function allows you to separate administration users into groups.
***''Central participant database:'' You, as an administrator, can use this function to store the participants' information in a central table/database that is independent of any table with survey participants.
**'''Advanced settings''': Non user- or survey settings-related options are found here. These are options that can be used to enhance your LimeSurvey installation.
***''Theme editor:'' Click on the ''Theme editor'' option if you would like to add/edit/delete survey themes, admin themes, or question themes. The themes allow you to control the look and feel of pages of your survey or of your LimeSurvey GUI.
***''Manage label sets:'' Label sets are basically list templates where each list has a set of codes with labels and it can be used in most question types either as answers or as subquestions.
***''Check data integrity:'' This checks the consistency and the redundancy of the data.
***''Backup entire database:'' Used to backup the LimeSurvey data when important LimeSurvey upgrades are pushed or when you move your LimeSurvey installation to another server.
***''ComfortUpdate:'' a tool that can be used to easily update your LimeSurvey installation from your web browser with just a few mouse clicks (instead of performing a manual LimeSurvey reinstallation).
*'''Surveys:''' A survey includes, via different interconnected databases: languages, question groups, questions, question attributes, answers, subquestions, default answers, assessments, quotas, quota members, and quota language settings. Clicking on the green arrow will display a window with the following options:
**'''Create a new survey:''' Allows you to create a new survey.
**'''Import a new survey:''' Allows you to import a survey.
**'''Copy a survey:''' Allows you to quickly copy a survey. The copied survey will appear in the surveys list where it can be edited.
**'''List surveys:''' Lists all of your existing surveys.
*'''Response Balance:''' Shows the number of responses left from your subscription. Because you only have access to a free account at the moment, 25 responses per month are available to you. If you run out of responses, purchase more using [https://www.limesurvey.org/editions-and-prices/limesurvey-pro/editions-and-prices-professional the following link].
*'''Storage:''' This is the amount of MBs that are at your disposal to store your surveys and answers. Because you created a free account, you have 10 MB storage space. If you would like to receive more storage space, choose [https://www.limesurvey.org/editions-and-prices/limesurvey-pro/editions-and-prices-professional one of the following paid options from here].
*'''Username:''' Here you can either access your user preferences or sign out of your account.
*'''Notifications:''' Click the green bell to display notifications related to your LimeSurvey installation.


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


There are six default boxes on the home page of your LimeSurvey installation.


<center>[[File:QSG LS3 LimeSurvey homepage.png]]</center>


* '''Create survey'''
* '''List surveys'''
* '''Global settings'''
* '''ComfortUpdate'''
* '''Label Sets'''
* '''Themes'''


<div class="simplebox">[[File:help.png]] The boxes are shortcuts (click on them) for the different LimeSurvey functionalities. The boxes and their number can be changed from '''Configuration -> Home page settings'''.</div>


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

==Create a Survey== 


To create a survey, click on the '''Create a new survey''' box.


<center>[[File:Create a new survey - Example.png]]</center>


The '''Create survey''' page will be displayed.


<center>[[File:QSG LS3 Create a survey model.png]]</center>


The following options will be displayed:
*'''Survey Title:''' The title of the survey has to be typed in here. You cannot proceed further if no name is given to your survey. No worrires if you do not feel inspired at the moment, the title of the survey can be changed later.
*'''Base Language:''' This is the main language of the survey. Additional languages can be added later from the settings of the survey.
*'''Sample Question:''' This feature is disabled by default. If you enable it, a question group and question examples will be added to your survey.
*'''End URL:''' You have the possibility to redirect users to another page when they finish filling in the questionnaire. If you wish to redirect them, type in the URL and activate the "automatically load URL" option that is located under the [[Surveys_-_introduction#Presentation_.26_navigation|Presentation & navigation tab]].
*'''URL Description:''' A short "End URL" description can be added in cases where the user is redirected to a non-related survey webpage. It may helpful if the survey administrator adds notes (explaining the purpose of the redirection to the respective URL).
*'''Date Format:''' This option is important when you want to record [[Notifications_%26_data|timestamps]] together with the survey participants' answers. If you click on it, a drop-down list will display with a list of date formats. Choose the one that your survey respondents will be familiar with (do not forget that different date formats are used across the world).
*'''Decimal Format:''' Two options are available: dot (.) and comma (,). Choose the one that is used in the region where your survey will be conducted (e.g., US vs Germany).
*'''Description:''' A short description of the survey can be added here.
*'''Welcome Message:''' The survey participants will be greeted by this welcome message if something is typed in.
*'''End Message:''' Type in a message that will be displayed to the survey participants when they submit the answers to the questionnaire (when the survey is complete).


{{Box|There are six options on the tool bar at the top. The one you just read about is [[Text elements]]. The other five are: [[General settings]], [[Presentation|Presentation & navigation]], [[Publication_%26_access|Publication & access control]], [[Notifications_%26_data|Notification & data management]], and [[Participant_settings|Participant settings]] (known as Tokens). By clicking on each of them, more advanced menus will be displayed. They are used to enhance your survey. Choosing enhancements here is not required because they can be edited later from the settings of the survey once it is created.}}


Once you are done completing the fields, click on the '''Save and close''' button located in the upper-right part of the window. You will be redirected to the home page of your recently added survey.


<center>[[File:QSG LS3 General view.png]]</center>

==Create a Question Group== 


A question group is used to group different elements of a survey like descriptions, questions, and answers.


To create a question group, first select the survey that you want to add the question group to. To do that, click on the '''Surveys''' button located on the top toolbar from the LimeSurvey home page.


<center>[[File:Quick start guide - Surveys list.png]]</center>


Click on the survey you wish to add the question group to - the survey page will be displayed. The menu on the left contains two tabs: [[Survey settings|settings]] and [[Survey structure|structure]]. To add questions and question groups, you have to work from the '''Structure''' tab.


<center>[[File:QSG LS3 Visualise settings tab.png]]</center>


Once the '''Structure''' tab is selected, the menu on the left will be displayed as follows.


<center>[[File:QSG LS3 Add question group.png]]</center>


Now, click on the '''Add question group''' button. The following page will be displayed.


<center>[[File:QSG LS3 Question group options.png]]</center>


*'''Title:''' This is the name of the survey group.
*'''Description:''' A short description of the question group can be typed in. It can be displayed to the survey participants if the corresponding option is enabled from the settings of the survey.
*'''Randomization Group:''' This function is used when you would like to randomize certain question groups (the same has to be allocated to the respective question groups).
*'''Relevance Equation:''' This feature is used to restrict survey participants to certain question groups, based on their previous answers.


Once done, click on the '''Save''' button located in the upper-right part of the window.


{{Box|The last two fields from the screenshot are left empty because knowledge about the expression manager of LimeSurvey is required. If you would like to read more about them, start with [https://manual.limesurvey.org/Question_groups_-_introduction our wiki on question groups].}}
{{Alert|title=Warning|text= You must create a question group first in order to start adding questions to your survey.}}

==Create a Question== 


To create a new question, always remember that you need first to create a question group. Please check the steps [[Quick_start_guide_-_LimeSurvey_3.0%2B#Create_a_question_group|presented above to see how you can add a question group to a survey]].


Once done creating the survey and adding a question group, select the '''Structure''' tab again and click on the add question button or select the question group from the menu on the left and click on the “add new question to group” button located under the '''Group quick actions'''.


<center>[[File:QSG LS3 Add question.png]]</center>


Once clicked, the '''Create question''' page will be displayed. It contains the following options:


<center>[[File:QSG LS3 Create question menu.png]]</center>


*'''Code:''' This represents the individual question name/code with which the survey is saved in the database and can be used further in more complex and advanced types of questions.
*'''Question:''' This is the name of the question that will actually appear in the survey for the survey participants.
*'''Help:''' This is a short text that can be provided in order to help the survey participants better understand the question.
*'''General Options:''' The functionalities located under this option allow you to modify the most important question-related settings. It includes four options:
**''Question Type:'' Many question types can be used in LimeSurvey. To better understand them, hover the mouse over each option or read [https://manual.limesurvey.org/Questions_-_introduction our wiki on questions].
**''Question Group:'' Here you can choose which question group you would like to add the question to.
**''Validation:'' This feature is available on all free text type or numeric questions. It is used for response validation. If the response is not validated, the user will be prompted to try again before they can progress.
**''Mandatory:'' This option is available for all question types. This setting allows you to require users to answer the question before they can move on to the next question.
**''Relevance Equation:'' This is a setting for advanced users. We recommend that the default value of "1" is used (it means that the item will be always shown).


Please note that, according to the selected question type, different tabs will be displayed below the '''General settings''' tab. To find out more about this, we suggest that you to first read [[Question types|the following wiki section]].


For example, if the '''Long free text''' question type is selected (the default option), then the following tabs will be displayed: '''General options''', '''Display''', '''Input''', '''Logic''', '''Other''', '''Statistics''', '''Timer'''.
Click on the '''Save''' button. You will be redirected to a page that contains the summary of the recently added question.


<center>[[File:QSG LS Summary question added.png]]</center>


To add more questions, follow the same procedure described above.

==Add Subquestions and Answers== 


Different types of questions require subquestions, predefined sets of answers, both or neither. For example, a question that requires the age of a survey participant does not require any subquestion or predefined set of answers. On the other hand, a simple array question requires both subquestions and answers.


<div class="simplebox">[[File:help.png]] The lack of subquestions and/or sets of answers is emphasized in the question summary if they are absent.</div>


The next screenshot contains an array-type question.


<center>[[File:QSG LS3 Subq q example.png]]</center>

===Add subquestions=== 


To add subquestions, go to the top toolbar and click on '''Edit subquestions'''. Type in the subquestions you wish the survey participants to answer.


<center>[[File:QSG LS3 Edit subq.png]]</center>


<div class="simplebox">[[File:help.png]] Click on the ''green plus sign'' located under the '''Actions''' column to add more fields.</div>

===Add Answers=== 


To add a set of predefined answers, go to the top toolbar and click on '''Edit answer options'''. Type in the answers.


<center>[[File:QSG_LS3_Edit_answers.png]]</center>


<div class="simplebox">[[File:help.png]] Click on the ''green plus sign'' located under the '''Actions''' column to add more fields.</div>


Save the set of answers and preview the question (look for the '''Preview question''' button located on the top toolbar).


<center>[[File:Quick start guide - Toolbar Preview question.png]]</center>


Our question looks like this:


<center>[[File:QSG_LS3_Preview_queston.png]]</center>


Congratulations! You have successfully created your first array-type question.

==Organize Questions== 


If your survey already contains dozens of questions, it is a time-consuming process to access each question and/or question group and edit the order one-by-one. Therefore, to quickly reorganize your questions and question groups, you can change the order of the questions and question groups from the '''Survey Structure''' menu. Once accessed, click on the three-lines symbol that is located in front of the question (group) name and start dragging it to the desired position.


<center>[[File:Reorder-question.png]]</center>

==Activate/Stop Survey== 


Now that you have at least one question and question group added to your survey, you can activate it. Select the '''Settings''' tab from the menu on the left and click on the '''Overview''' option. The following page will be displayed.


<center>[[File:QSG LS3 Activate survey.png]]</center>


Check the toolbar and click on the '''Activate this survey''' button.


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


Before activation, a window will be displayed asking you about some general survey settings.


<center>[[File:QSG LS3 Save and activate survey.png]]</center>


{{Alert|title=Attention|text=If you decide to activate a survey, no edits can be done to the groups, questions, subquestions, and their corresponding codes.}}


*'''Anonymyzed Responses:''' This option allows you to determine whether responses to your survey are matched with information from your survey's token table or kept "anonymous". If you decide to enable it, your survey is set to anonymize responses - there will be no way to connect answers and participants.
*'''Save IP Address:''' If enabled, the IP address of the survey respondent will be stored together with his/her answers.
*'''Save Timings:''' If enabled, the time spent on each page of the survey by each survey participant is recorded.
*'''Date Stamp:''' Turn this option on if you would like to see the date the answers were submitted.
*'''Save Referrer URL:''' If enabled, the referrer URL will be stored together with the answers.


Once you are done enabling the desired functionalities, click on the '''Save & activate survey''' button. The following message should be displayed.


<center>[[FIle:QSG_LS3_after_activating_a_survey.png]]</center>


Select the option <u>'''No, thanks'''</u> to disable the closed-access mode! This will allow everyone access to your survey.


Congratulations! You have activated your first survey! If you want to start sharing the survey URL, go to the home page of your survey, and look for the survey URL in the '''Survey summary'''.


<center>[[File:QSG_LS3_Survey_url.png]]</center>


Copy the link and start sharing it.


If you want to deactivate (stop) the survey, click on the '''Overview''' tab from the left-side menu and look for the '''Stop this survey''' button located on the top toolbar.


<center>[[File:Quick start guide - Stop this survey.png]]</center>

==Statistics== 


To quickly see your survey statistics, click on the '''Survey''' button located on the top toolbar of your LimeSurvey home page. A list with all the available surveys will be displayed. Now, go to the last column and click on the '''Statistics''' button ([[File:Quick start guide - see Statistics survey.png]]) that corresponds to the row of the survey you wish to analyse.


<center>[[File:QSG LS3 Survey statistics.png]]</center>


A new window with a set of graphs will be displayed. If you want to use them in a report, scroll down and click on the '''Export images''' button located on the bottom-left part of the page. All the charts will be separately saved as .png files and archived in a .zip file.


On the upper-right part of the window, you can see the '''Expert mode''' button. Click on it in order to access more statistics-related filters.


Once you select the filters for your analysis, click on the '''View Statistics''' button located on the upper-right part of the window.


<center>[[File:QSG LS3 View statistics expert.png]]</center>


The results are displayed in HTML, Excel or PDF based on the chosen format.

==Exporting the Questions and Responses== 


If you want to export the results in a different format in order to produce statistics and graphs using other apps such as SPSS, R, STATA, etc., access the survey you want to analyse. Click on the ''Responses'' button located on the top toolbar, and then on ''Responses & Statistics''.


<center>[[File:QSG LS3 Responses and statistics.png]]</center>


Now you are on the '''Browse responses''' page. Look at the top toolbar for the '''Export''' button and select the desired format you wish to export to. If you select the first option, all the availalbe formats in which you can export the data will be displayed.


<center>[[File:QSG LS3 Export responses.png]]</center>


<center>[[File:Quick start guide - Export different formats.png]]</center>


Once the filters are set, click on the '''Export''' button located in the upper-right side of the window.

=Other LimeSurvey Features - Advanced Users= 


Check the features of [https://www.limesurvey.org/editions-and-prices/limesurvey-pro/editions-and-prices-professional LimeSurvey Pro] package by clicking on the following link: https://www.limesurvey.org/editions-and-prices/limesurvey-pro/professional-features.


If further questions arise, please post them on [https://www.limesurvey.org/forum our forum] or join the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel].

</translate>

LimeSurvey Manual

2020-10-06T15:54:19Z

Cdorin:

<languages />
<translate>

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


<div style="clear:right;float:right;"><div class="simplebox">
Main Chapters:
*[[Installation - LimeSurvey CE]]
*[[Getting Started]]
*[[Administering LimeSurvey]]
*[[Surveys - introduction|Surveys - Introduction]]
*[[Surveys - management|Surveys - Management]]
*[[Not Categorized and Advanced Features]]
*[[General FAQ]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
*[[Workarounds]]
*[[License]]
*[[Version change log| Version Change Log]]
*[[Plugins - advanced|Plugins - Advanced]]
</div></div>


[https://www.limesurvey.org/ LimeSurvey] allows users (think of users as "administrators" NOT participants!) to quickly create intuitive, powerful online question and answer surveys that can work for only a few participants or thousands of participants without much effort. The survey software is self-guiding for the respondents who are participating. This manual is thus focused on how to install the application, administer the installation, as well as support survey creators, administrators, and users who need to generate reports.


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


The main chapters of the manual are located in the box to the right. You can also scroll down further on this page to see the complete table of contents and go directly to the topic you are interested in.


Are you still having trouble finding what you want? Don't forget the general '''search box''' (upper right corner of the wiki), our [[General FAQ]], and [[Workarounds]] list. If you are looking for community help, join our [https://www.limesurvey.org/en/forum/ discussion forums] and check the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel].


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

= Manual - Table of Contents = 


*[[LimeSurvey PRO vs LimeSurvey CE]]
**[[LimeSurvey PRO vs LimeSurvey CE#What do I need?|What do I need?]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
**[[Quick start guide - LimeSurvey 3.0+|Quick Start Guide - LimeSurvey 3.0+]]


*[[Installation - LimeSurvey CE]]
**[[Optional settings|Optional Settings]]
**[[Upgrading from a previous version|Upgrading From a Previous Version]]
***[[ComfortUpdate]]
**[[Installation using a command line interface (CLI)|Installation Using a Command Line Interface (CLI)]]
**[[Transferring an installation|Transferring an Installation]]
**[[Installation FAQ]]
***[[Installation security hints|Installation Security Hints]]
***[[Localization]]
*[[Getting Started]]
**[[First login - your user preferences|First Login - Your User Preferences]]
*[[Administering LimeSurvey]]
**[[Administering LimeSurvey#Settings Tab|Settings Tab]]
***[[Home page settings|Home Page Settings]]
***[[Global settings|Global Settings]]
***[[Plugin manager|Plugin Manager]]
***[[Menu configuration|Menu Configuration]]{{NewIn|3.0}}
***[[Menu entries configuration|Menu Entries Configuration]]{{NewIn|3.0}}
**[[Administering LimeSurvey#Users Tab|Users Tab]]
***[[Manage users|Manage Users]]
***[[Manage user groups|Manage User Groups]]
***[[Central Participant Database]] (CPDB)
**[[Administering LimeSurvey#Advanced Tab|Advanced Tab]]
***[[Theme editor|Theme Editor]] (LimeSurvey 2.x)
****[[New Template System in LS3.x|New Template System In LS3.x]]
****[[Themes]]
****[[Question themes|Question Themes]]
***[[Label sets|Label Sets]]
***[[Check data integrity|Check Data Integrity]]
***[[Backup entire database|Backup Entire Database]]
***[[ComfortUpdate]]


*[[Surveys - introduction|Surveys - Introduction]]
**[[Surveys - introduction#Create_a_new_survey|Create a Survey]]
***[[Surveys - introduction#Import a survey|Import a Survey]]
***[[Surveys - introduction#Copy a survey|Copy a Survey]]
**[[Survey settings|Survey Settings]]
***[[Overview]]
***[[General settings|General Settings]]
***[[Text elements|Text Elements]]
***[[Data policy settings|Data Policy Settings]]
***[[Theme options|Theme Options]]
***[[Presentation]]
***[[Participant settings|Participant Settings]] (was ''Participant Tokens'')
***[[Notifications_%26_data|Notifications & Data]]
***[[Publication & access|Publication & Access]]
**[[Survey menu|Survey Menu]]
***[[List questions|List Questions]]
***[[List question groups|List Question Groups]]
***[[Reorder questions and question groups|Reorder Questions and Question Groups]]
***[[Survey participants|Survey Participants]] (was ''Tokens'')
****[[Email bounce tracking system|Email Bounce Tracking System]]
***[[Survey quotas|Quotas]]
***[[Assessments]]
***[[Survey permissions|Survey Permissions]]
***[[Email templates|Email Templates]]
****[[Email placeholders|Email Placeholders]]
***[[Panel integration|Panel Integration]]
***[[Resources]]
***[[Plugin menu|Plugin Menu]]
**[[Survey structure|Survey Structure]]
**[[Question groups - introduction|Question Groups - Introduction]]
***[[Question_groups_-_introduction#Question_group_actions|Question Group Toolbar Options]]
***[[Question groups - introduction#Preview question group|Preview Question Group]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change Group Order]]
**[[Questions - introduction|Questions - Introduction]]
***[[Question types|Question Types]]
****[[Question type - Array|Question Type - Array]]
****[[Question type - Array by column|Question Type - Array by column]]
****[[Question type - Array dual scale|Question Type - Array dual scale]]
****[[Question type - Array (5 point choice)|Question Type - Array (5 point choice)]]
****[[Question type - Array (10 point choice)|Question Type - Array (10 point choice)]]
****[[Question type - Array (Increase-Same-Decrease)|Question Type - Array (Increase-Same-Decrease)]]
****[[Question type - Array (Numbers)|Question Type - Array (Numbers)]]
****[[Question type - Array (Texts)|Question Type - Array (Texts)]]
****[[Question type - Array (Yes-No-Uncertain)|Question Type - Array (Yes-No-Uncertain)]]
****[[Question type - Date|Question Type - Date]]
****[[Question type - Equation|Question Type - Equation]]
****[[Question type - File upload|Question Type - File upload]]
****[[Question type - Gender|Question Type - Gender]]
****[[Question type - Language switch|Question Type - Language switch]]
****[[Question type - Numerical input|Question Type - Numerical input]]
****[[Question type - Multiple numerical input|Question Type - Multiple numerical input]]
****[[Question type - Ranking|Question Type - Ranking]]
****[[Question type - Text display|Question Type - Text display]]
****[[Question type - Yes-No|Question Type - Yes-No]]
****[[Question type - Multiple choice|Question Type - Multiple choice]]
****[[Question type - Multiple choice with comments|Question Type - Multiple choice with comments]]
****[[Question type - 5 point choice|Question Type - 5 point choice]]
****[[Question type - List (Dropdown)|Question Type - List (Dropdown)]]
****[[Question type - List (Radio)|Question Type - List (Radio)]]
****[[Question type - List with comment|Question Type - List with comment]]
****[[Question type - Short free text|Question Type - Short free text]]
*****[[Question type_-_Short_free_text#Location|Set up maps and store location]]
****[[Question type - Long free text|Question Type - Long free text]]
****[[Question type - Huge free text|Question Type - Huge free text]]
****[[Question type - Multiple short text|Question Type - Multiple short text]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change question order]]
***[[Question toolbar options]]
****[[Preview function]]
****[[Edit question]]
****[[Check question logic]]
****[[Delete question]]
****[[Export question]]
****[[Copy question]]
****[[Setting conditions]]
****[[Adding answers or subquestions]]
****[[Default answers]]
**[[ExpressionScript Engine - Quick start guide]]
***[[ExpressionScript - Presentation]]
***[[ExpressionScript How-tos]]
***[[ExpressionScript examples]]
***[[ExpressionScript Engine roadmap]]
***[[ExpressionScript for developers]]
***[[ExpressionScript sample surveys]]
****[[Expression Manager]] - old page with full documentation
**[[Show logic file]]
*[[Survey toolbar options]]
**[[Testing a survey]]
**[[Activating a survey]]
**[[Running a survey safely]]
***[[Changing an active survey]]
**[[Closing a survey]]
**[[Iterate survey]]
**[[Tools]]
***[[Delete survey]]
***[[Quick-translation]]
***[[Reset conditions]]
***[[Survey logic file]]
***[[Regenerate question codes]]
**[[Display/Export survey]]
***[[QueXML PDF Export]]
***[[Tab Separated Value survey structure]]
**[[Survey participants]]
**[[Responses (survey results)]]
***[[Responses & statistics]]
****[[Responses & statistics#Responses summary|Response summary]]
****[[Responses]]
****[[Data entry]]
****[[Statistics]]
*****[[Statistics - expert mode]]
*****[[Statistics - simple mode]]
****[[Timing statistics]]
****[[Export responses]]
****[[Import responses]]
*****[[Problems & solutions]]
****[[View saved but not submitted responses]]
****[[Iterate survey#General|Iterate survey]]
****[[Batch deletion]]
***[[Data entry]]
***[[Partial (saved) responses]]
*[[Multilingual survey]]
*[[Not categorized and advanced features]]
**[[SGQA identifier]]
**[[Using regular expressions]]
**[[URL fields]]
**[[RemoteControl 2 API]]
**[[Data encryption]]
*[[General FAQ]]
*[[Troubleshooting]]
*[[Workarounds]]
**[[Workarounds: Question design, layout and templating]]
**[[Workarounds: Manipulating a survey at runtime using Javascript]]
**[[Workarounds: Survey behaviour]]
**[[Workarounds: Further solutions provided by LimeSurvey users]]
*[[License]]
*[[Version change log]]
*[[Plugins - advanced]]
**[[Available third party plugins]]

=LimeSurvey Development= 
*[[Version guide]] - A short guide on version numbering
*[[Development overview]] - General pages about LimeSurvey development
*[[LimeSurvey 2.x development documentation]]
*[[New Template System in LS3.x]] - Quick overview of the novelties of the LimeSurvey 3 template system

=Translating LimeSurvey= 


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

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

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

</translate>

General settings

2020-09-18T13:36:32Z

Cdorin:

<languages />
<translate>


__TOC__

=Introduction= 


The general settings panel of a survey allows you to edit basic information about the survey such as the survey owner, administrator's email, and the template deployed in his or her survey.


It access it, click on the '''Settings''' tab and look for the ''General settings'' tab:


<center>[[File:Survey_settings_General_settings.png]]</center>

=General settings panel= 


The following functionalities can be edited from the general settings panel:


<center>[[File:Create a new survey - General settings.png]]</center>

==Base language== 
It represents the main language of the survey. The base language corresponds with the [[Global settings#Language|default site language]]. The latter can be changed from the global settings of your LimeSurvey installation by a super-administrator.

==Additional languages== 
More languages can be added to your survey. This option is important when you want to create multilingual surveys. For example, if you wish to use English, German, and Romanian for your survey, add Romanian and German as additional languages (if English is already the default/base language). The list of available languages could be smaller if the LimeSurvey administrator diminished the number of available languages from the [[Global settings#Language|LimeSurvey global settings]].

==Survey owner== 
Select the survey owner. The user has all the permissions associated to the respective survey: [[Manage_users#Set_permissions_for_a_single_survey|survey permissions]] (wiki link).

==Administrator== 
Type in the name of the administrator.

==Admin email== 
Type in the email of the survey administrator.


{{Note|'''Administrator''' and '''admin email''' are utilized in the LimeSurvey [[Email templates|email templates]] system.}}
<div class="simplebox">[[File:help.png]] Many hosting providers' SMTP servers will only accept emails whose "From:" address is on a local domain. Any emails that do not conform to this rule are discarded silently, without any visible error message. If this happens to you, ensure that you are using a provider-based email address in the "Admin email" field. You could also set up email forwarding on the provider's side, so that any messages sent there are relayed to your preferred address.</div>

==Bounce email== 
This is the email address where the delivery error notification emails (bounced emails) will be sent to.
<div class="simplebox">[[File:help.png]] A bounce email is an electronic email which is returned to the sender for various reasons (e.g. invalid address, temporary unavailable mail server, full recipient's mailbox, etc).</div>


{{Note|The bounce email settings can be set up [[Email_bounce_tracking_system|locally]] and/or [[General_settings#Bounce_email|globally]].}}

==Fax to== 
This field is used to give a fax number on the "printable survey" - i.e.: when you want to send someone a hard copy because he or she cannot use the online survey.

==Group== 
Select the [[Surveys - introduction#Survey groups|survey group]]{{NewIn|3.0}} the newly created survey should be added to.

==Format== 
It allows you to choose the way in which the questions will be displayed to the survey respondents. Three options are available:
*''Question by Question'' : The questions will be displayed one by one (one question per page). If this option is selected, a separate "welcome" page and "end" page will be displayed when taking the survey.
*''Group by Group'' : Each survey page will display a question group. Also, a separate "welcome" page and "end" page will still be displayed when taking the survey, as in the "Question by Question" surveys.
*''All in one'' : If chosen, all the pages will be displayed on a single page. If you select this option, no separate pages exist for the "welcome" and "end" pages - they will all appear on the same page, together with the questions.

==Template== 
You can select the desired template from the drop-down list. The default one is rather simple but functional. More information on creating your own templates is available [[Theme editor|here]].

</translate>

Talk:Theme editor

2020-09-15T16:23:58Z

Cdorin:

The screenshots in this page show a recent limesurvey interface but the text is about pstpl files, while LS starting from version 3 should rely on twig files only, afaik.
What's the deal?
Maybe the page could be reverted to the original version (pictures from version 2) as a reference. Otherwise, it may be marked as incomplete/wip IMHO.
--[[User:Ritapas|Ritapas]] ([[User talk:Ritapas|talk]]) 10:40, 15 September 2020 (CEST)

Fair point. I am afraid to remove it since there are still plenty of users relying on LimeSurvey 2.x . We will remove it when LimeSurvey 4 will be available in Comfort Update. Till then, see: [[New_Template_System_in_LS3.x]]
--[[User:cdorin|Dorin]] ([[User talk:cdorin|talk]]) 15 September 2020

Talk:Theme editor

2020-09-15T16:23:05Z

Cdorin:

LimeSurvey Manual

2020-07-01T13:19:41Z

Cdorin:

<languages />
<translate>

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


<div style="clear:right;float:right;"><div class="simplebox">
Main Chapters:
*[[Installation - LimeSurvey CE]]
*[[Getting Started]]
*[[Administering LimeSurvey]]
*[[Surveys - introduction|Surveys - Introduction]]
*[[Surveys - management|Surveys - Management]]
*[[Not Categorized and Advanced Features]]
*[[General FAQ]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
*[[Workarounds]]
*[[License]]
*[[Version change log| Version Change Log]]
*[[Plugins - advanced|Plugins - Advanced]]
</div></div>


[https://www.limesurvey.org/ LimeSurvey] allows users to quickly create intuitive, powerful online question and answer surveys that can work for only a few participants or thousands of participants without much effort. The survey software is self-guiding for the respondents who are participating. This manual is thus focused on how to install the application, administer the installation, as well as support survey creators, administrators and users who need to generate reports.


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


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


Are you still having trouble finding what you want? Don't forget the general '''search box''' (upper right corner of the wiki), our [[General FAQ]], and [[Workarounds]] list. If you are looking for community help, join our [https://www.limesurvey.org/en/forum/ discussion forums] and check the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel].


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

= Manual - table of contents= 


*[[LimeSurvey PRO vs LimeSurvey CE]]
**[[LimeSurvey PRO vs LimeSurvey CE#What do I need?|What do I need?]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
**[[Quick start guide - LimeSurvey 2.50+|Quick Start Guide - LimeSurvey 2.50+]]
**[[Quick start guide - LimeSurvey 3.0+|Quick Start Guide - LimeSurvey 3.0+]]


*[[Installation - LimeSurvey CE]]
**[[Optional settings|Optional Settings]]
**[[Upgrading from a previous version|Upgrading From a Previous Version]]
***[[ComfortUpdate]]
**[[Installation using a command line interface (CLI)|Installation Using a Command Line Interface (CLI)]]
**[[Transferring an installation|Transferring an Installation]]
**[[Installation FAQ]]
***[[Installation security hints|Installation Security Hints]]
***[[Localization]]
*[[Getting Started]]
**[[First login - your user preferences|First Login - Your User Preferences]]
*[[Administering LimeSurvey]]
**[[Administering LimeSurvey#Settings Tab|Settings Tab]]
***[[Home page settings|Home Page Settings]]
***[[Global settings|Global Settings]]
***[[Plugin manager|Plugin Manager]]
***[[Menu configuration|Menu Configuration]]{{NewIn|3.0}}
***[[Menu entries configuration|Menu Entries Configuration]]{{NewIn|3.0}}
**[[Administering LimeSurvey#Users Tab|Users Tab]]
***[[Manage users|Manage Users]]
***[[Manage user groups|Manage User Groups]]
***[[Central Participant Database]] (CPDB)
**[[Administering LimeSurvey#Advanced Tab|Advanced Tab]]
***[[Theme editor|Theme Editor]] (LimeSurvey 2.x)
****[[New Template System in LS3.x|New Template System In LS3.x]]
****[[Themes]]
****[[Question themes|Question Themes]]
***[[Label sets|Label Sets]]
***[[Check data integrity|Check Data Integrity]]
***[[Backup entire database|Backup Entire Database]]
***[[ComfortUpdate]]


*[[Surveys - introduction|Surveys - Introduction]]
**[[Surveys - introduction#Create_a_new_survey|Create a Survey]]
***[[Surveys - introduction#Import a survey|Import a Survey]]
***[[Surveys - introduction#Copy a survey|Copy a Survey]]
**[[Survey settings|Survey Settings]]
***[[Overview]]
***[[General settings|General Settings]]
***[[Text elements|Text Elements]]
***[[Data policy settings|Data Policy Settings]]
***[[Theme options|Theme Options]]
***[[Presentation]]
***[[Participant settings|Participant Settings]] (was ''Participant Tokens'')
***[[Notifications_%26_data|Notifications & Data]]
***[[Publication & access|Publication & Access]]
**[[Survey menu|Survey Menu]]
***[[List questions|List Questions]]
***[[List question groups|List Question Groups]]
***[[Reorder questions and question groups|Reorder Questions and Question Groups]]
***[[Survey participants|Survey Participants]] (was ''Tokens'')
****[[Email bounce tracking system|Email Bounce Tracking System]]
***[[Survey quotas|Quotas]]
***[[Assessments]]
***[[Survey permissions|Survey Permissions]]
***[[Email templates|Email Templates]]
****[[Email placeholders|Email Placeholders]]
***[[Panel integration|Panel Integration]]
***[[Resources]]
***[[Plugin menu|Plugin Menu]]
**[[Survey structure|Survey Structure]]
**[[Question groups - introduction|Question Groups - Introduction]]
***[[Question_groups_-_introduction#Question_group_actions|Question Group Toolbar Options]]
***[[Question groups - introduction#Preview question group|Preview Question Group]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change Group Order]]
**[[Questions - introduction|Questions - Introduction]]
***[[Question types|Question Types]]
****[[Question type - Array|Question Type - Array]]
****[[Question type - Array by column|Question Type - Array by column]]
****[[Question type - Array dual scale|Question Type - Array dual scale]]
****[[Question type - Array (5 point choice)|Question Type - Array (5 point choice)]]
****[[Question type - Array (10 point choice)|Question Type - Array (10 point choice)]]
****[[Question type - Array (Increase-Same-Decrease)|Question Type - Array (Increase-Same-Decrease)]]
****[[Question type - Array (Numbers)|Question Type - Array (Numbers)]]
****[[Question type - Array (Texts)|Question Type - Array (Texts)]]
****[[Question type - Array (Yes-No-Uncertain)|Question Type - Array (Yes-No-Uncertain)]]
****[[Question type - Date|Question Type - Date]]
****[[Question type - Equation|Question Type - Equation]]
****[[Question type - File upload|Question Type - File upload]]
****[[Question type - Gender|Question Type - Gender]]
****[[Question type - Language switch|Question Type - Language switch]]
****[[Question type - Numerical input|Question Type - Numerical input]]
****[[Question type - Multiple numerical input|Question Type - Multiple numerical input]]
****[[Question type - Ranking|Question Type - Ranking]]
****[[Question type - Text display|Question Type - Text display]]
****[[Question type - Yes-No|Question Type - Yes-No]]
****[[Question type - Multiple choice|Question Type - Multiple choice]]
****[[Question type - Multiple choice with comments|Question Type - Multiple choice with comments]]
****[[Question type - 5 point choice|Question Type - 5 point choice]]
****[[Question type - List (Dropdown)|Question Type - List (Dropdown)]]
****[[Question type - List (Radio)|Question Type - List (Radio)]]
****[[Question type - List with comment|Question Type - List with comment]]
****[[Question type - Short free text|Question Type - Short free text]]
*****[[Question type_-_Short_free_text#Location|Set up maps and store location]]
****[[Question type - Long free text|Question Type - Long free text]]
****[[Question type - Huge free text|Question Type - Huge free text]]
****[[Question type - Multiple short text|Question Type - Multiple short text]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change question order]]
***[[Question toolbar options]]
****[[Preview function]]
****[[Edit question]]
****[[Check question logic]]
****[[Delete question]]
****[[Export question]]
****[[Copy question]]
****[[Setting conditions]]
****[[Adding answers or subquestions]]
****[[Default answers]]
**[[ExpressionScript Engine - Quick start guide]]
***[[ExpressionScript - Presentation]]
***[[ExpressionScript How-tos]]
***[[ExpressionScript examples]]
***[[ExpressionScript Engine roadmap]]
***[[ExpressionScript for developers]]
***[[ExpressionScript sample surveys]]
****[[Expression Manager]] - old page with full documentation
**[[Show logic file]]
*[[Survey toolbar options]]
**[[Testing a survey]]
**[[Activating a survey]]
**[[Running a survey safely]]
***[[Changing an active survey]]
**[[Closing a survey]]
**[[Iterate survey]]
**[[Tools]]
***[[Delete survey]]
***[[Quick-translation]]
***[[Reset conditions]]
***[[Survey logic file]]
***[[Regenerate question codes]]
**[[Display/Export survey]]
***[[QueXML PDF Export]]
***[[Tab Separated Value survey structure]]
**[[Survey participants]]
**[[Responses (survey results)]]
***[[Responses & statistics]]
****[[Responses & statistics#Responses summary|Response summary]]
****[[Responses]]
****[[Data entry]]
****[[Statistics]]
*****[[Statistics - expert mode]]
*****[[Statistics - simple mode]]
****[[Timing statistics]]
****[[Export responses]]
****[[Import responses]]
*****[[Problems & solutions]]
****[[View saved but not submitted responses]]
****[[Iterate survey#General|Iterate survey]]
****[[Batch deletion]]
***[[Data entry]]
***[[Partial (saved) responses]]
*[[Multilingual survey]]
*[[Not categorized and advanced features]]
**[[SGQA identifier]]
**[[Using regular expressions]]
**[[URL fields]]
**[[RemoteControl 2 API]]
**[[Data encryption]]
*[[General FAQ]]
*[[Troubleshooting]]
*[[Workarounds]]
**[[Workarounds: Question design, layout and templating]]
**[[Workarounds: Manipulating a survey at runtime using Javascript]]
**[[Workarounds: Survey behaviour]]
**[[Workarounds: Further solutions provided by LimeSurvey users]]
*[[License]]
*[[Version change log]]
*[[Plugins - advanced]]
**[[Available third party plugins]]

=LimeSurvey development= 
*[[Version guide]] - A short guide on version numbering
*[[Development overview]] - General pages about LimeSurvey development
*[[LimeSurvey 2.x development documentation]]
*[[New Template System in LS3.x]] - Quick overview of the novelties of the LimeSurvey 3 template system

=Translating LimeSurvey= 


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

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

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

</translate>

LimeSurvey Manual

2020-07-01T13:15:43Z

Cdorin:

<languages />
<translate>

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


<div style="clear:right;float:right;"><div class="simplebox">
Main Chapters:
*[[Installation - LimeSurvey CE]]
*[[Getting Started]]
*[[Administering LimeSurvey]]
*[[Surveys - introduction|Surveys - Introduction]]
*[[Surveys - management|Surveys - Management]]
*[[Not Categorized and Advanced Features]]
*[[General FAQ]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
*[[Workarounds]]
*[[License]]
*[[Version change log| Version Change Log]]
*[[Plugins - advanced|Plugins - Advanced]]
</div></div>


[https://www.limesurvey.org/ LimeSurvey] allows users to quickly create intuitive, powerful online question and answer surveys that can work for only a few participants or thousands of participants without much effort. The survey software is self-guiding for the respondents who are participating. This manual is thus focused on how to install the application, administer the installation, as well as support survey creators, administrators and users who need to generate reports.


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


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


Are you still having trouble finding what you want? Don't forget the general '''search box''' (upper right corner of the wiki), our [[General FAQ]], and [[Workarounds]] list. If you are looking for community help, join our [https://www.limesurvey.org/en/forum/ discussion forums] and check the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel].


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

= Manual - table of contents= 


*[[LimeSurvey PRO vs LimeSurvey CE]]
**[[LimeSurvey PRO vs LimeSurvey CE#What do I need?|What do I need?]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
**[[Quick start guide - LimeSurvey 2.50+|Quick Start Guide - LimeSurvey 2.50+]]
**[[Quick start guide - LimeSurvey 3.0+|Quick Start Guide - LimeSurvey 3.0+]]


*[[Installation - LimeSurvey CE]]
**[[Optional settings|Optional Settings]]
**[[Upgrading from a previous version|Upgrading From a Previous Version]]
***[[ComfortUpdate]]
**[[Installation using a command line interface (CLI)|Installation Using a Command Line Interface (CLI)]]
**[[Transferring an installation|Transferring an Installation]]
**[[Installation FAQ]]
***[[Installation security hints|Installation Security Hints]]
***[[Localization]]
*[[Getting Started]]
**[[First login - your user preferences|First Login - Your User Preferences]]
*[[Administering LimeSurvey]]
**[[Administering LimeSurvey#Settings Tab|Settings Tab]]
***[[Home page settings|Home Page Settings]]
***[[Global settings|Global Settings]]
***[[Plugin manager|Plugin Manager]]
***[[Menu configuration|Menu Configuration]]{{NewIn|3.0}}
***[[Menu entries configuration|Menu Entries Configuration]]{{NewIn|3.0}}
**[[Administering LimeSurvey#Users Tab|Users Tab]]
***[[Manage users|Manage Users]]
***[[Manage user groups|Manage User Groups]]
***[[Central Participant Database]] (CPDB)
**[[Administering LimeSurvey#Advanced Tab|Advanced Tab]]
***[[Theme editor|Theme Editor]] (LimeSurvey 2.x)
****[[New Template System in LS3.x|New Template System In LS3.x]]
****[[Themes]]
****[[Question themes|Question Themes]]
***[[Label sets|Label Sets]]
***[[Check data integrity|Check Data Integrity]]
***[[Backup entire database|Backup Entire Database]]
***[[ComfortUpdate]]


*[[Surveys - introduction|Surveys - Introduction]]
**[[Surveys - introduction#Create_a_new_survey|Create a Survey]]
***[[Surveys - introduction#Import a survey|Import a Survey]]
***[[Surveys - introduction#Copy a survey|Copy a Survey]]
**[[Survey settings|Survey Settings]]
***[[Overview]]
***[[General settings|General Settings]]
***[[Text elements|Text Elements]]
***[[Data policy settings|Data Policy Settings]]
***[[Theme options|Theme Options]]
***[[Presentation]]
***[[Participant settings|Participant Settings]] (was ''Participant Tokens'')
***[[Notifications_%26_data|Notifications & Data]]
***[[Publication & access|Publication & Access]]
**[[Survey menu|Survey Menu]]
***[[List questions|List Questions]]
***[[List question groups|List Question Groups]]
***[[Reorder questions and question groups|Reorder Questions and Question Groups]]
***[[Survey participants|Survey Participants]] (was ''Tokens'')
****[[Email bounce tracking system|Email Bounce Tracking System]]
***[[Survey quotas|Quotas]]
***[[Assessments]]
***[[Survey permissions|Survey Permissions]]
***[[Email templates|Email Templates]]
****[[Email placeholders|Email Placeholders]]
***[[Panel integration|Panel Integration]]
***[[Resources]]
***[[Plugin menu|Plugin Menu]]
**[[Survey structure|Survey Structure]]
**[[Question groups - introduction|Question Groups - Introduction]]
***[[Question_groups_-_introduction#Question_group_actions|Question Group Toolbar Options]]
***[[Question groups - introduction#Preview question group|Preview Question Group]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change Group Order]]
**[[Questions - introduction|Questions - Introduction]]
***[[Question types|Question Types]]
****[[Question type - Array|Question Type - Array]]
****[[Question type - Array by column|Question Type - Array by column]]
****[[Question type - Array dual scale]]
****[[Question type - Array (5 point choice)]]
****[[Question type - Array (10 point choice)]]
****[[Question type - Array (Increase-Same-Decrease)]]
****[[Question type - Array (Numbers)]]
****[[Question type - Array (Texts)]]
****[[Question type - Array (Yes-No-Uncertain)]]
****[[Question type - Date]]
****[[Question type - Equation]]
****[[Question type - File upload]]
****[[Question type - Gender]]
****[[Question type - Language switch]]
****[[Question type - Numerical input]]
****[[Question type - Multiple numerical input]]
****[[Question type - Ranking]]
****[[Question type - Text display]]
****[[Question type - Yes-No]]
****[[Question type - Multiple choice]]
****[[Question type - Multiple choice with comments]]
****[[Question type - 5 point choice]]
****[[Question type - List (Dropdown)]]
****[[Question type - List (Radio)]]
****[[Question type - List with comment]]
****[[Question type - Short free text]]
*****[[Question type_-_Short_free_text#Location|Set up maps and store location]]
****[[Question type - Long free text]]
****[[Question type - Huge free text]]
****[[Question type - Multiple short text]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change question order]]
***[[Question toolbar options]]
****[[Preview function]]
****[[Edit question]]
****[[Check question logic]]
****[[Delete question]]
****[[Export question]]
****[[Copy question]]
****[[Setting conditions]]
****[[Adding answers or subquestions]]
****[[Default answers]]
**[[ExpressionScript Engine - Quick start guide]]
***[[ExpressionScript - Presentation]]
***[[ExpressionScript How-tos]]
***[[ExpressionScript examples]]
***[[ExpressionScript Engine roadmap]]
***[[ExpressionScript for developers]]
***[[ExpressionScript sample surveys]]
****[[Expression Manager]] - old page with full documentation
**[[Show logic file]]
*[[Survey toolbar options]]
**[[Testing a survey]]
**[[Activating a survey]]
**[[Running a survey safely]]
***[[Changing an active survey]]
**[[Closing a survey]]
**[[Iterate survey]]
**[[Tools]]
***[[Delete survey]]
***[[Quick-translation]]
***[[Reset conditions]]
***[[Survey logic file]]
***[[Regenerate question codes]]
**[[Display/Export survey]]
***[[QueXML PDF Export]]
***[[Tab Separated Value survey structure]]
**[[Survey participants]]
**[[Responses (survey results)]]
***[[Responses & statistics]]
****[[Responses & statistics#Responses summary|Response summary]]
****[[Responses]]
****[[Data entry]]
****[[Statistics]]
*****[[Statistics - expert mode]]
*****[[Statistics - simple mode]]
****[[Timing statistics]]
****[[Export responses]]
****[[Import responses]]
*****[[Problems & solutions]]
****[[View saved but not submitted responses]]
****[[Iterate survey#General|Iterate survey]]
****[[Batch deletion]]
***[[Data entry]]
***[[Partial (saved) responses]]
*[[Multilingual survey]]
*[[Not categorized and advanced features]]
**[[SGQA identifier]]
**[[Using regular expressions]]
**[[URL fields]]
**[[RemoteControl 2 API]]
**[[Data encryption]]
*[[General FAQ]]
*[[Troubleshooting]]
*[[Workarounds]]
**[[Workarounds: Question design, layout and templating]]
**[[Workarounds: Manipulating a survey at runtime using Javascript]]
**[[Workarounds: Survey behaviour]]
**[[Workarounds: Further solutions provided by LimeSurvey users]]
*[[License]]
*[[Version change log]]
*[[Plugins - advanced]]
**[[Available third party plugins]]

=LimeSurvey development= 
*[[Version guide]] - A short guide on version numbering
*[[Development overview]] - General pages about LimeSurvey development
*[[LimeSurvey 2.x development documentation]]
*[[New Template System in LS3.x]] - Quick overview of the novelties of the LimeSurvey 3 template system

=Translating LimeSurvey= 


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

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

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

</translate>

LimeSurvey Manual

2020-07-01T13:13:40Z

Cdorin:

<languages />
<translate>

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


<div style="clear:right;float:right;"><div class="simplebox">
Main Chapters:
*[[Installation - LimeSurvey CE]]
*[[Getting Started]]
*[[Administering LimeSurvey]]
*[[Surveys - introduction|Surveys - Introduction]]
*[[Surveys - management|Surveys - Management]]
*[[Not Categorized and Advanced Features]]
*[[General FAQ]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
*[[Workarounds]]
*[[License]]
*[[Version change log| Version Change Log]]
*[[Plugins - advanced|Plugins - Advanced]]
</div></div>


[https://www.limesurvey.org/ LimeSurvey] allows users to quickly create intuitive, powerful online question and answer surveys that can work for only a few participants or thousands of participants without much effort. The survey software is self-guiding for the respondents who are participating. This manual is thus focused on how to install the application, administer the installation, as well as support survey creators, administrators and users who need to generate reports.


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


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


Are you still having trouble finding what you want? Don't forget the general '''search box''' (upper right corner of the wiki), our [[General FAQ]], and [[Workarounds]] list. If you are looking for community help, join our [https://www.limesurvey.org/en/forum/ discussion forums] and check the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel].


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

= Manual - table of contents= 


*[[LimeSurvey PRO vs LimeSurvey CE]]
**[[LimeSurvey PRO vs LimeSurvey CE#What do I need?|What do I need?]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
**[[Quick start guide - LimeSurvey 2.50+|Quick Start Guide - LimeSurvey 2.50+]]
**[[Quick start guide - LimeSurvey 3.0+|Quick Start Guide - LimeSurvey 3.0+]]


*[[Installation - LimeSurvey CE]]
**[[Optional settings|Optional Settings]]
**[[Upgrading from a previous version|Upgrading From a Previous Version]]
***[[ComfortUpdate]]
**[[Installation using a command line interface (CLI)|Installation Using a Command Line Interface (CLI)]]
**[[Transferring an installation|Transferring an Installation]]
**[[Installation FAQ]]
***[[Installation security hints|Installation Security Hints]]
***[[Localization]]
*[[Getting Started]]
**[[First login - your user preferences|First Login - Your User Preferences]]
*[[Administering LimeSurvey]]
**[[Administering LimeSurvey#Settings Tab|Settings Tab]]
***[[Home page settings|Home Page Settings]]
***[[Global settings|Global Settings]]
***[[Plugin manager|Plugin Manager]]
***[[Menu configuration|Menu Configuration]]{{NewIn|3.0}}
***[[Menu entries configuration|Menu Entries Configuration]]{{NewIn|3.0}}
**[[Administering LimeSurvey#Users Tab|Users Tab]]
***[[Manage users|Manage Users]]
***[[Manage user groups|Manage User Groups]]
***[[Central Participant Database]] (CPDB)
**[[Administering LimeSurvey#Advanced Tab|Advanced Tab]]
***[[Theme editor|Theme Editor]] (LimeSurvey 2.x)
****[[New template system in LS3.x|New Template System In LS3.x]]
****[[Themes]]
****[[Question themes|Question Themes]]
***[[Label sets|Label Sets]]
***[[Check data integrity|Check Data Integrity]]
***[[Backup entire database|Backup Entire Database]]
***[[ComfortUpdate]]


*[[Surveys - introduction|Surveys - Introduction]]
**[[Surveys - introduction#Create_a_new_survey|Create a Survey]]
***[[Surveys - introduction#Import a survey|Import a Survey]]
***[[Surveys - introduction#Copy a survey|Copy a Survey]]
**[[Survey settings|Survey Settings]]
***[[Overview]]
***[[General settings|General Settings]]
***[[Text elements|Text Elements]]
***[[Data policy settings|Data Policy Settings]]
***[[Theme options|Theme Options]]
***[[Presentation]]
***[[Participant settings|Participant Settings]] (was ''Participant Tokens'')
***[[Notifications_%26_data|Notifications & Data]]
***[[Publication & access|Publication & Access]]
**[[Survey menu|Survey Menu]]
***[[List questions|List Questions]]
***[[List question groups|List Question Groups]]
***[[Reorder questions and question groups|Reorder Questions and Question Groups]]
***[[Survey participants|Survey Participants]] (was ''Tokens'')
****[[Email bounce tracking system|Email Bounce Tracking System]]
***[[Survey quotas|Quotas]]
***[[Assessments]]
***[[Survey permissions|Survey Permissions]]
***[[Email templates|Email Templates]]
****[[Email placeholders|Email Placeholders]]
***[[Panel integration|Panel Integration]]
***[[Resources]]
***[[Plugin menu|Plugin Menu]]
**[[Survey structure|Survey Structure]]
**[[Question groups - introduction|Question Groups - Introduction]]
***[[Question_groups_-_introduction#Question_group_actions|Question Group Toolbar Options]]
***[[Question groups - introduction#Preview question group|Preview Question Group]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change Group Order]]
**[[Questions - introduction|Questions - Introduction]]
***[[Question types|Question Types]]
****[[Question type - Array|Question Type - Array]]
****[[Question type - Array by column|Question Type - Array by column]]
****[[Question Type - Array dual scale]]
****[[Question Type - Array (5 point choice)]]
****[[Question Type - Array (10 point choice)]]
****[[Question Type - Array (Increase-Same-Decrease)]]
****[[Question Type - Array (Numbers)]]
****[[Question Type - Array (Texts)]]
****[[Question Type - Array (Yes-No-Uncertain)]]
****[[Question Type - Date]]
****[[Question Type - Equation]]
****[[Question Type - File upload]]
****[[Question Type - Gender]]
****[[Question Type - Language switch]]
****[[Question Type - Numerical input]]
****[[Question Type - Multiple numerical input]]
****[[Question Type - Ranking]]
****[[Question Type - Text display]]
****[[Question Type - Yes-No]]
****[[Question Type - Multiple choice]]
****[[Question Type - Multiple choice with comments]]
****[[Question Type - 5 point choice]]
****[[Question Type - List (Dropdown)]]
****[[Question Type - List (Radio)]]
****[[Question Type - List with comment]]
****[[Question Type - Short free text]]
*****[[Question_Type_-_Short_free_text#Location|Set up maps and store location]]
****[[Question Type - Long free text]]
****[[Question Type - Huge free text]]
****[[Question Type - Multiple short text]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change question order]]
***[[Question toolbar options]]
****[[Preview function]]
****[[Edit question]]
****[[Check question logic]]
****[[Delete question]]
****[[Export question]]
****[[Copy question]]
****[[Setting conditions]]
****[[Adding answers or subquestions]]
****[[Default answers]]
**[[ExpressionScript Engine - Quick start guide]]
***[[ExpressionScript - Presentation]]
***[[ExpressionScript How-tos]]
***[[ExpressionScript examples]]
***[[ExpressionScript Engine roadmap]]
***[[ExpressionScript for developers]]
***[[ExpressionScript sample surveys]]
****[[Expression Manager]] - old page with full documentation
**[[Show logic file]]
*[[Survey toolbar options]]
**[[Testing a survey]]
**[[Activating a survey]]
**[[Running a survey safely]]
***[[Changing an active survey]]
**[[Closing a survey]]
**[[Iterate survey]]
**[[Tools]]
***[[Delete survey]]
***[[Quick-translation]]
***[[Reset conditions]]
***[[Survey logic file]]
***[[Regenerate question codes]]
**[[Display/Export survey]]
***[[QueXML PDF Export]]
***[[Tab Separated Value survey structure]]
**[[Survey participants]]
**[[Responses (survey results)]]
***[[Responses & statistics]]
****[[Responses & statistics#Responses summary|Response summary]]
****[[Responses]]
****[[Data entry]]
****[[Statistics]]
*****[[Statistics - expert mode]]
*****[[Statistics - simple mode]]
****[[Timing statistics]]
****[[Export responses]]
****[[Import responses]]
*****[[Problems & solutions]]
****[[View saved but not submitted responses]]
****[[Iterate survey#General|Iterate survey]]
****[[Batch deletion]]
***[[Data entry]]
***[[Partial (saved) responses]]
*[[Multilingual survey]]
*[[Not categorized and advanced features]]
**[[SGQA identifier]]
**[[Using regular expressions]]
**[[URL fields]]
**[[RemoteControl 2 API]]
**[[Data encryption]]
*[[General FAQ]]
*[[Troubleshooting]]
*[[Workarounds]]
**[[Workarounds: Question design, layout and templating]]
**[[Workarounds: Manipulating a survey at runtime using Javascript]]
**[[Workarounds: Survey behaviour]]
**[[Workarounds: Further solutions provided by LimeSurvey users]]
*[[License]]
*[[Version change log]]
*[[Plugins - advanced]]
**[[Available third party plugins]]

=LimeSurvey development= 
*[[Version guide]] - A short guide on version numbering
*[[Development overview]] - General pages about LimeSurvey development
*[[LimeSurvey 2.x development documentation]]
*[[New Template System in LS3.x]] - Quick overview of the novelties of the LimeSurvey 3 template system

=Translating LimeSurvey= 


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

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

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

</translate>

LimeSurvey Manual

2020-07-01T13:11:55Z

Cdorin:

<languages />
<translate>

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


<div style="clear:right;float:right;"><div class="simplebox">
Main Chapters:
*[[Installation - LimeSurvey CE]]
*[[Getting Started]]
*[[Administering LimeSurvey]]
*[[Surveys - introduction|Surveys - Introduction]]
*[[Surveys - management|Surveys - Management]]
*[[Not Categorized and Advanced Features]]
*[[General FAQ]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
*[[Workarounds]]
*[[License]]
*[[Version change log| Version Change Log]]
*[[Plugins - advanced|Plugins - Advanced]]
</div></div>


[https://www.limesurvey.org/ LimeSurvey] allows users to quickly create intuitive, powerful online question and answer surveys that can work for only a few participants or thousands of participants without much effort. The survey software is self-guiding for the respondents who are participating. This manual is thus focused on how to install the application, administer the installation, as well as support survey creators, administrators and users who need to generate reports.


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


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


Are you still having trouble finding what you want? Don't forget the general '''search box''' (upper right corner of the wiki), our [[General FAQ]], and [[Workarounds]] list. If you are looking for community help, join our [https://www.limesurvey.org/en/forum/ discussion forums] and check the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel].


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

= Manual - table of contents= 


*[[LimeSurvey PRO vs LimeSurvey CE]]
**[[LimeSurvey PRO vs LimeSurvey CE#What do I need?|What do I need?]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
**[[Quick start guide - LimeSurvey 2.50+|Quick Start Guide - LimeSurvey 2.50+]]
**[[Quick start guide - LimeSurvey 3.0+|Quick Start Guide - LimeSurvey 3.0+]]


*[[Installation - LimeSurvey CE]]
**[[Optional settings|Optional Settings]]
**[[Upgrading from a previous version|Upgrading From a Previous Version]]
***[[ComfortUpdate]]
**[[Installation using a command line interface (CLI)|Installation Using a Command Line Interface (CLI)]]
**[[Transferring an installation|Transferring an Installation]]
**[[Installation FAQ]]
***[[Installation security hints|Installation Security Hints]]
***[[Localization]]
*[[Getting Started]]
**[[First login - your user preferences|First Login - Your User Preferences]]
*[[Administering LimeSurvey]]
**[[Administering LimeSurvey#Settings Tab|Settings Tab]]
***[[Home page settings|Home Page Settings]]
***[[Global settings|Global Settings]]
***[[Plugin manager|Plugin Manager]]
***[[Menu configuration|Menu Configuration]]{{NewIn|3.0}}
***[[Menu entries configuration|Menu Entries Configuration]]{{NewIn|3.0}}
**[[Administering LimeSurvey#Users Tab|Users Tab]]
***[[Manage users|Manage Users]]
***[[Manage user groups|Manage User Groups]]
***[[Central Participant Database]] (CPDB)
**[[Administering LimeSurvey#Advanced Tab|Advanced Tab]]
***[[Theme editor|Theme Editor]] (LimeSurvey 2.x)
****[[New template system in LS3.x|New Template System In LS3.x]]
****[[Themes]]
****[[Question themes|Question Themes]]
***[[Label sets|Label Sets]]
***[[Check data integrity|Check Data Integrity]]
***[[Backup entire database|Backup Entire Database]]
***[[ComfortUpdate]]


*[[Surveys - introduction|Surveys - Introduction]]
**[[Surveys - introduction#Create_a_new_survey|Create a Survey]]
***[[Surveys - introduction#Import a survey|Import a Survey]]
***[[Surveys - introduction#Copy a survey|Copy a Survey]]
**[[Survey settings|Survey Settings]]
***[[Overview]]
***[[General settings|General Settings]]
***[[Text elements|Text Elements]]
***[[Data policy settings|Data Policy Settings]]
***[[Theme options|Theme Options]]
***[[Presentation]]
***[[Participant settings|Participant Settings]] (was ''Participant Tokens'')
***[[Notifications_%26_data|Notifications & Data]]
***[[Publication & access|Publication & Access]]
**[[Survey menu|Survey Menu]]
***[[List questions|List Questions]]
***[[List question groups|List Question Groups]]
***[[Reorder questions and question groups|Reorder Questions and Question Groups]]
***[[Survey participants|Survey Participants]] (was ''Tokens'')
****[[Email bounce tracking system|Email Bounce Tracking System]]
***[[Survey Quotas|Quotas]]
***[[Assessments]]
***[[Survey permissions|Survey Permissions]]
***[[Email templates|Email Templates]]
****[[Email placeholders|Email Placeholders]]
***[[Panel integration|Panel Integration]]
***[[Resources]]
***[[Plugin menu|Plugin Menu]]
**[[Survey structure|Survey Structure]]
**[[Question groups - introduction|Question Groups - Introduction]]
***[[Question_Groups_-_introduction#Question_group_actions|Question Group Toolbar Options]]
***[[Question Groups - introduction#Preview question group|Preview Question Group]]
***[[Survey_Structure#Reordering_questions_and_question_groups|Change Group Order]]
**[[Questions - introduction|Questions - Introduction]]
***[[Question types|Question Types]]
****[[Question Type - Array]]
****[[Question Type - Array by column]]
****[[Question Type - Array dual scale]]
****[[Question Type - Array (5 point choice)]]
****[[Question Type - Array (10 point choice)]]
****[[Question Type - Array (Increase-Same-Decrease)]]
****[[Question Type - Array (Numbers)]]
****[[Question Type - Array (Texts)]]
****[[Question Type - Array (Yes-No-Uncertain)]]
****[[Question Type - Date]]
****[[Question Type - Equation]]
****[[Question Type - File upload]]
****[[Question Type - Gender]]
****[[Question Type - Language switch]]
****[[Question Type - Numerical input]]
****[[Question Type - Multiple numerical input]]
****[[Question Type - Ranking]]
****[[Question Type - Text display]]
****[[Question Type - Yes-No]]
****[[Question Type - Multiple choice]]
****[[Question Type - Multiple choice with comments]]
****[[Question Type - 5 point choice]]
****[[Question Type - List (Dropdown)]]
****[[Question Type - List (Radio)]]
****[[Question Type - List with comment]]
****[[Question Type - Short free text]]
*****[[Question_Type_-_Short_free_text#Location|Set up maps and store location]]
****[[Question Type - Long free text]]
****[[Question Type - Huge free text]]
****[[Question Type - Multiple short text]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change question order]]
***[[Question toolbar options]]
****[[Preview function]]
****[[Edit question]]
****[[Check question logic]]
****[[Delete question]]
****[[Export question]]
****[[Copy question]]
****[[Setting conditions]]
****[[Adding answers or subquestions]]
****[[Default answers]]
**[[ExpressionScript Engine - Quick start guide]]
***[[ExpressionScript - Presentation]]
***[[ExpressionScript How-tos]]
***[[ExpressionScript examples]]
***[[ExpressionScript Engine roadmap]]
***[[ExpressionScript for developers]]
***[[ExpressionScript sample surveys]]
****[[Expression Manager]] - old page with full documentation
**[[Show logic file]]
*[[Survey toolbar options]]
**[[Testing a survey]]
**[[Activating a survey]]
**[[Running a survey safely]]
***[[Changing an active survey]]
**[[Closing a survey]]
**[[Iterate survey]]
**[[Tools]]
***[[Delete survey]]
***[[Quick-translation]]
***[[Reset conditions]]
***[[Survey logic file]]
***[[Regenerate question codes]]
**[[Display/Export survey]]
***[[QueXML PDF Export]]
***[[Tab Separated Value survey structure]]
**[[Survey participants]]
**[[Responses (survey results)]]
***[[Responses & statistics]]
****[[Responses & statistics#Responses summary|Response summary]]
****[[Responses]]
****[[Data entry]]
****[[Statistics]]
*****[[Statistics - expert mode]]
*****[[Statistics - simple mode]]
****[[Timing statistics]]
****[[Export responses]]
****[[Import responses]]
*****[[Problems & solutions]]
****[[View saved but not submitted responses]]
****[[Iterate survey#General|Iterate survey]]
****[[Batch deletion]]
***[[Data entry]]
***[[Partial (saved) responses]]
*[[Multilingual survey]]
*[[Not categorized and advanced features]]
**[[SGQA identifier]]
**[[Using regular expressions]]
**[[URL fields]]
**[[RemoteControl 2 API]]
**[[Data encryption]]
*[[General FAQ]]
*[[Troubleshooting]]
*[[Workarounds]]
**[[Workarounds: Question design, layout and templating]]
**[[Workarounds: Manipulating a survey at runtime using Javascript]]
**[[Workarounds: Survey behaviour]]
**[[Workarounds: Further solutions provided by LimeSurvey users]]
*[[License]]
*[[Version change log]]
*[[Plugins - advanced]]
**[[Available third party plugins]]

=LimeSurvey development= 
*[[Version guide]] - A short guide on version numbering
*[[Development overview]] - General pages about LimeSurvey development
*[[LimeSurvey 2.x development documentation]]
*[[New Template System in LS3.x]] - Quick overview of the novelties of the LimeSurvey 3 template system

=Translating LimeSurvey= 


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

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

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

</translate>

LimeSurvey Manual

2020-07-01T13:05:23Z

Cdorin:

<languages />
<translate>

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


<div style="clear:right;float:right;"><div class="simplebox">
Main Chapters:
*[[Installation - LimeSurvey CE]]
*[[Getting Started]]
*[[Administering LimeSurvey]]
*[[Surveys - introduction|Surveys - Introduction]]
*[[Surveys - management|Surveys - Management]]
*[[Not Categorized and Advanced Features]]
*[[General FAQ]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
*[[Workarounds]]
*[[License]]
*[[Version changelog| Version Change Log]]
*[[Plugins - advanced|Plugins - Advanced]]
</div></div>


[https://www.limesurvey.org/ LimeSurvey] allows users to quickly create intuitive, powerful online question and answer surveys that can work for only a few participants or thousands of participants without much effort. The survey software is self-guiding for the respondents who are participating. This manual is thus focused on how to install the application, administer the installation, as well as support survey creators, administrators and users who need to generate reports.


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


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


Are you still having trouble finding what you want? Don't forget the general '''search box''' (upper right corner of the wiki), our [[General FAQ]], and [[Workarounds]] list. If you are looking for community help, join our [https://www.limesurvey.org/en/forum/ discussion forums] and check the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel].


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

= Manual - table of contents= 


*[[LimeSurvey PRO vs LimeSurvey CE]]
**[[LimeSurvey PRO vs LimeSurvey CE#What do I need?|What do I need?]]
*[[How to design a good survey (guide)|How to Design a Good Survey (Guide)]]
**[[Quick start guide - LimeSurvey 2.50+|Quick Start Guide - LimeSurvey 2.50+]]
**[[Quick start guide - LimeSurvey 3.0+|Quick Start Guide - LimeSurvey 3.0+]]


*[[Installation - LimeSurvey CE]]
**[[Optional settings|Optional Settings]]
**[[Upgrading from a previous version|Upgrading From a Previous Version]]
***[[ComfortUpdate]]
**[[Installation using a command line interface (CLI)|Installation Using a Command Line Interface (CLI)]]
**[[Transferring an installation|Transferring an Installation]]
**[[Installation FAQ]]
***[[Installation security hints|Installation Security Hints]]
***[[Localization]]
*[[Getting Started]]
**[[First login - your user preferences|First Login - Your User Preferences]]
*[[Administering LimeSurvey]]
**[[Administering LimeSurvey#Settings Tab|Settings Tab]]
***[[Home page settings|Home Page Settings]]
***[[Global settings|Global Settings]]
***[[Plugin manager|Plugin Manager]]
***[[Menu configuration|Menu Configuration]]{{NewIn|3.0}}
***[[Menu entries configuration|Menu Entries Configuration]]{{NewIn|3.0}}
**[[Administering LimeSurvey#Users Tab|Users Tab]]
***[[Manage users|Manage Users]]
***[[Manage user groups|Manage User Groups]]
***[[Central Participant Database]] (CPDB)
**[[Administering LimeSurvey#Advanced Tab|Advanced Tab]]
***[[Theme Editor]] (LimeSurvey 2.x)
****[[New Template System In LS3.x]]
****[[Themes]]
****[[Question Themes]]
***[[Label Sets]]
***[[Check Data Integrity]]
***[[Backup Entire Database]]
***[[ComfortUpdate]]


*[[Surveys - Introduction]]
**[[Surveys - Introduction#Create_a_new_survey|Create a Survey]]
***[[Surveys - introduction#Import a survey|Import a Survey]]
***[[Surveys - introduction#Copy a survey|Copy a Survey]]
**[[Survey Settings]]
***[[Overview]]
***[[General Settings]]
***[[Text Elements]]
***[[Data Policy Settings]]
***[[Theme Options]]
***[[Presentation]]
***[[Participant Settings]] (was ''Participant Tokens'')
***[[Notifications_%26_data|Notifications & Data]]
***[[Publication & Access]]
**[[Survey Menu]]
***[[List Questions]]
***[[List Question Groups]]
***[[Reorder Questions and Question Groups]]
***[[Survey Participants]] (was ''Tokens'')
****[[Email Bounce Tracking System]]
***[[Survey Quotas|Quotas]]
***[[Assessments]]
***[[Survey Permissions]]
***[[Email Templates]]
****[[Email Placeholders]]
***[[Panel Integration]]
***[[Resources]]
***[[Plugin Menu]]
**[[Survey Structure]]
**[[Question Groups - Introduction]]
***[[Question_Groups_-_Introduction#Question_group_actions|Question Group Toolbar Options]]
***[[Question Groups - Introduction#Preview question group|Preview Question Group]]
***[[Survey_Structure#Reordering_questions_and_question_groups|Change Group Order]]
**[[Questions - Introduction]]
***[[Question Types]]
****[[Question Type - Array]]
****[[Question Type - Array by column]]
****[[Question Type - Array dual scale]]
****[[Question Type - Array (5 point choice)]]
****[[Question Type - Array (10 point choice)]]
****[[Question Type - Array (Increase-Same-Decrease)]]
****[[Question Type - Array (Numbers)]]
****[[Question Type - Array (Texts)]]
****[[Question Type - Array (Yes-No-Uncertain)]]
****[[Question Type - Date]]
****[[Question Type - Equation]]
****[[Question Type - File upload]]
****[[Question Type - Gender]]
****[[Question Type - Language switch]]
****[[Question Type - Numerical input]]
****[[Question Type - Multiple numerical input]]
****[[Question Type - Ranking]]
****[[Question Type - Text display]]
****[[Question Type - Yes-No]]
****[[Question Type - Multiple choice]]
****[[Question Type - Multiple choice with comments]]
****[[Question Type - 5 point choice]]
****[[Question Type - List (Dropdown)]]
****[[Question Type - List (Radio)]]
****[[Question Type - List with comment]]
****[[Question Type - Short free text]]
*****[[Question_Type_-_Short_free_text#Location|Set up maps and store location]]
****[[Question Type - Long free text]]
****[[Question Type - Huge free text]]
****[[Question Type - Multiple short text]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change question order]]
***[[Question toolbar options]]
****[[Preview function]]
****[[Edit question]]
****[[Check question logic]]
****[[Delete question]]
****[[Export question]]
****[[Copy question]]
****[[Setting conditions]]
****[[Adding answers or subquestions]]
****[[Default answers]]
**[[ExpressionScript Engine - Quick start guide]]
***[[ExpressionScript - Presentation]]
***[[ExpressionScript How-tos]]
***[[ExpressionScript examples]]
***[[ExpressionScript Engine roadmap]]
***[[ExpressionScript for developers]]
***[[ExpressionScript sample surveys]]
****[[Expression Manager]] - old page with full documentation
**[[Show logic file]]
*[[Survey toolbar options]]
**[[Testing a survey]]
**[[Activating a survey]]
**[[Running a survey safely]]
***[[Changing an active survey]]
**[[Closing a survey]]
**[[Iterate survey]]
**[[Tools]]
***[[Delete survey]]
***[[Quick-translation]]
***[[Reset conditions]]
***[[Survey logic file]]
***[[Regenerate question codes]]
**[[Display/Export survey]]
***[[QueXML PDF Export]]
***[[Tab Separated Value survey structure]]
**[[Survey participants]]
**[[Responses (survey results)]]
***[[Responses & statistics]]
****[[Responses & statistics#Responses summary|Response summary]]
****[[Responses]]
****[[Data entry]]
****[[Statistics]]
*****[[Statistics - expert mode]]
*****[[Statistics - simple mode]]
****[[Timing statistics]]
****[[Export responses]]
****[[Import responses]]
*****[[Problems & solutions]]
****[[View saved but not submitted responses]]
****[[Iterate survey#General|Iterate survey]]
****[[Batch deletion]]
***[[Data entry]]
***[[Partial (saved) responses]]
*[[Multilingual survey]]
*[[Not categorized and advanced features]]
**[[SGQA identifier]]
**[[Using regular expressions]]
**[[URL fields]]
**[[RemoteControl 2 API]]
**[[Data encryption]]
*[[General FAQ]]
*[[Troubleshooting]]
*[[Workarounds]]
**[[Workarounds: Question design, layout and templating]]
**[[Workarounds: Manipulating a survey at runtime using Javascript]]
**[[Workarounds: Survey behaviour]]
**[[Workarounds: Further solutions provided by LimeSurvey users]]
*[[License]]
*[[Version change log]]
*[[Plugins - advanced]]
**[[Available third party plugins]]

=LimeSurvey development= 
*[[Version guide]] - A short guide on version numbering
*[[Development overview]] - General pages about LimeSurvey development
*[[LimeSurvey 2.x development documentation]]
*[[New Template System in LS3.x]] - Quick overview of the novelties of the LimeSurvey 3 template system

=Translating LimeSurvey= 


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

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

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

</translate>

Manage roles

2020-06-12T14:50:48Z

Cdorin: Created page with " __TOC__ =Manage roles= Since version 4 LimeSurvey has an inbuilt role system for global permissions. A role is a template for a user permission, that is applied to the use..."

__TOC__

=Manage roles=

Since version 4 LimeSurvey has an inbuilt role system for global permissions.

A role is a template for a user permission, that is applied to the user instead of his own set permissions.

==Basic overview==
To see the role management check the configuration and click on ''Create/edit roles''

[[File:OpenRoleManagement.jpg]]

You will see an overview of the currently available roles and a possibility to create or import a role.

[[File:RolesOverview.jpg]]

There are five buttons in the actions column assigned to all roles.

[[File:RolesDetailButtons.jpg]]

* The view button, identifiable by the magnifying glass icon, will give you an overview over all the users that are currently members of this role.
* Edit permissions, identidfied by the lock icon, opens the permission table. All permissions selected here will be applied to any member of the role
* Edit role, identified by the edit icon, opens the edit mask again, where name and description can be amended to need.
* Export role, identified by the download icon, lets you export a permission as an XML-File, to be imported into another instance as needed.
* Delete role, identified with the red trashbin icon, deletes the role, but shows a confimration modal first.

==Add a new role==
To add a new role click on ''Add role'' in the top bar.

* Put in a name for the role.
** It should be as short as possible, as this is the identifier used when applying to users
* Put in a Description
** The description will be shown only on the overview page. Add a short description on what the role should be obliged to do.
ATTENTION! Both input fields are required and need to be filled!
* Last click on ''Save''

Question themes

2020-06-12T14:47:37Z

Cdorin: Created page with "== Overview == Question Themes can be used to customize existing question types and change there visual appearance. Question Themes can only be built for allready existing Que..."

== Overview ==
Question Themes can be used to customize existing question types and change there visual appearance. Question Themes can only be built for allready existing Question Types.

[[File:QuestionThemes1OverviewExample.png]]
[[File:QuestionThemes2OverviewExample.png]]

== Access ==
To access the Question Themes go to Configuration > Themes > Question Themes.

[[File:QuestionThemes1Overview.png]]
[[File:QuestionThemes2Overview.png]]

== Visibility ==
Question Themes are by default visible but can be switched to off. They will not be displayed anymore inside the Question Type and Question Theme Selector.

When the Option "[[#Engine|show as question type]]" is enabled all Question Themes will now also be displayed inside the Question Type Selector.

[[File:QuestionThemes3Visibility.png]]
[[File:QuestionThemes4Visibility.png]]

== Uninstall and Available Question Themes ==
All Themes that are available for installation will be displayed in this section.

If u want to uninstall a Question you can do so by selecting the Question Theme and choosing "uninstall" inside the dropdown menu under the table. They will now appear inside the available Question Themes.

Uninstalling a Question Theme will prevent the use inside selectors.
Used Question Themes cannot be uninstalled while they are still used inside a Survey.
[[File:QuestionThemes5AvailableQuestions.png]]

== Broken Question Themes ==
If there should be errors while loading [[#Uninstall and Available Question Themes|Available Question Themes]] they will be displayed in this Category with an Error Message to the related Theme.

== Importing Question Theme ==
It is possible to import Question Themes using the import Button. During the import the Theme will be automatically installed and available for use.

When importing a Theme from LS3 or above they will be automatically converted into the current standard

The imported Theme must be in the '''ZIP''' format.

Before compressing the folder to zip it must have the following structure:

[[File:QuestionThemes6ImportStructure.png]]
NAME/survey/questions/answer/QUESTIONTYPENAME/config.xml

==List of question types/IDs and default CSS 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
|-
|
|}

== Configuration ==
The configuration for a Question Theme can be found inside config.xml.
An example can be found in the [https://github.com/LimeSurvey/LimeSurvey/tree/develop/docs/themes docs folder].

=== Metadata ===
The Metadata describes the Question Theme, these settings will also be saved in the Database.
[[File:QuestionThemes7MetaData.png]]

{| class="wikitable"
!Tag
!Type
!Mandatory
!Description
|-
| name || string || x || The name of the extension
|-
| type || string || x || Type of the extension; can be "plugin", "theme", etc; see below
|-
| title || string || x || The title that is displayed in the frontend
|-
| creationDate || date (YYYY-MM-DD) || || Date the extension was created
|-
| lastUpdate || date (YYYY-MM-DD) || || Date of the latest update
|-
| author || string || x || Plugin author
|-
| authorUrl || url || x || URL to author web page, necessary so that customers can contact author for support
|-
| copyright || string || x || Copyright Information
|-
| license || string || x || Extension licence
|-
| version || string as [https://semver.org/ semantic version] || x || Extension version number
|-
| apiVersion || string || x || Api version number
|-
| description || string || x || Information that will be shown as help text
|-
| questionType || string || x || The Question Type the Theme is associated with
|-
| group || string || x || The Group inside the selector it should be assigned to
|-
| subquestions || string || x || If or how many Subquestionscales should be displayed
|-
| answerscales || string || x || If or how many Answerscales should be displayed
|-
| hasdefaultvalues || string || x || If the Theme has default values
|-
| assessable || string || x || If the Theme can be used for Assessments (Quiz)
|-
| class || string || x || The HTML class name for the Theme
|}

=== Files ===
List of the of files loaded via asset manager.

[[File:QuestionThemes8Files.png]]

=== Generalattributes ===
Attributes that are displayed on the right side of the Questioneditor.
These Attributes are predifined and are the same for all Question Themes, currently no new ones can be added. If you want to show or hide certain options for a Question Theme you can remove or add the attribute.
[[File:QuestionThemes9GeneralAttributes.png]]

=== Attributes ===
Attributes are Options you want to give to this Question Theme and can be customized. They are visible at the bottom of the questioneditor.
[[File:QuestionThemes10Attributes.png]]
{| class="wikitable"
!Tag
|-
| name || The internal name
|-
| category ||The category tab in which the attribute should be displayed. This can also be a new one.
|-
| sortorder || At which position inside the tab it should be display from top left (smallest) to bottom right (highest)
|-
| inputtype || What type the input should be rendered as
|-
| default || The default value for the input field
|-
| help || The help text
|-
| caption || The frontend Title for the Theme
|-
| i18n ||
|-
| readonly ||
|-
| readonly_when_active ||
|-
| expression ||
|}

=== Engine ===
Configuration for special load options

[[File:QuestionThemes11Engine.png]]

{| class="wikitable"
!Tag
!Type
!Mandatory
!Description
|-
| load_core_css || boolean |||| If core css should be loaded
|-
| load_core_js || boolean |||| If core js should be loaded
|-
| show_as_template || boolean |||| If the Theme should be loaded
|-
| show_as_question_type || boolean |||| If the Theme should be listed inside the question type selector
|}

== Compatibility ==
=== Converting LS3 to LS4 ===
When updating to LS4 the current custom Question Themes will be updated into the LS4 standard. If the Theme has missing attributes that can not be automatically inserted, they will not be installed and instead be available for installation. If an error occurs they can be found under [[#Broken Question Themes]].
If you want to import a Question Theme from LS3 into LS4 after you have updated your Installation you can simply use the [[#Importing Question Theme]] which has an integrated functionality to automatically convert it.

Importing a Question Theme from LS4 into LS3 is not automatically possible.

=== LS4 changes ===
The "custom_attributes" tag is not needed anymore. Attributes will allways be defined inside the attributes tag instead. There is no need for different naming since they will be merged together when reading the Question Type.

Further there has been addistions to the metadata section of the xml, additions are marked in red.
[[File:QuestionThemes12Compatibility.png]]

LimeSurvey Manual

2020-06-12T14:47:09Z

Cdorin:

<languages />
<translate>

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


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


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


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


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


Still having trouble finding what you want? Don't forget the general '''search box''' (upper right corner of the wiki), our [[General FAQ]] and [[Workarounds]] list. If you are looking for community help, join our [https://www.limesurvey.org/en/forum/ discussion forums] and check the [irc://irc.freenode.net/limesurvey|LimeSurvey IRC channel].


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

= Manual - table of contents= 


*[[LimeSurvey PRO vs LimeSurvey CE]]
**[[LimeSurvey PRO vs LimeSurvey CE#What do I need?|What do I need?]]
*[[How to design a good survey (guide)]]
**[[Quick start guide - LimeSurvey 2.50+]]
**[[Quick start guide - LimeSurvey 3.0+]]


*[[Installation - LimeSurvey CE]]
**[[Optional settings]]
**[[Upgrading from a previous version]]
***[[ComfortUpdate]]
**[[Installation using a command line interface (CLI)]]
**[[Transferring an installation]]
**[[Installation FAQ]]
***[[Installation security hints]]
***[[Localization]]
*[[Getting started]]
**[[First login - your user preferences]]
*[[Administering LimeSurvey]]
**[[Administering LimeSurvey#Settings tab|Settings tab]]
***[[Home page settings]]
***[[Global settings]]
***[[Plugin manager]]
***[[Menu configuration]]{{NewIn|3.0}}
***[[Menu entries configuration]]{{NewIn|3.0}}
**[[Administering LimeSurvey#Users tab|Users tab]]
***[[Manage users]]
***[[Manage user groups]]
***[[Central Participant Database]] (CPDB)
**[[Administering LimeSurvey#Advanced tab|Advanced tab]]
***[[Theme editor]] (LimeSurvey 2.x)
****[[New Template System in LS3.x]]
****[[Themes]]
****[[Question themes]]
***[[Label sets]]
***[[Check data integrity]]
***[[Backup entire database]]
***[[ComfortUpdate]]


*[[Surveys - introduction]]
**[[Surveys - introduction#Create_a_new_survey|Create a survey]]
***[[Surveys - introduction#Import a survey|Import a survey]]
***[[Surveys - introduction#Copy a survey|Copy a survey]]
**[[Survey settings]]
***[[Overview]]
***[[General settings]]
***[[Text elements]]
***[[Data policy settings]]
***[[Theme options]]
***[[Presentation]]
***[[Participant settings]] (was ''Participant tokens'')
***[[Notifications_%26_data|Notifications & data]]
***[[Publication & access]]
**[[Survey menu]]
***[[List questions]]
***[[List question groups]]
***[[Reorder questions and question groups]]
***[[Survey participants]] (was ''Tokens'')
****[[Email bounce tracking system]]
***[[Survey quotas|Quotas]]
***[[Assessments]]
***[[Survey permissions]]
***[[Email templates]]
****[[Email placeholders]]
***[[Panel integration]]
***[[Resources]]
***[[Plugin menu]]
**[[Survey structure]]
**[[Question groups - introduction]]
***[[Question_groups_-_introduction#Question_group_actions|Question group toolbar options]]
***[[Question groups - introduction#Preview question group|Preview question group]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change group order]]
**[[Questions - introduction]]
***[[Question types]]
****[[Question type - Array]]
****[[Question type - Array by column]]
****[[Question type - Array dual scale]]
****[[Question type - Array (5 point choice)]]
****[[Question type - Array (10 point choice)]]
****[[Question type - Array (Increase-Same-Decrease)]]
****[[Question type - Array (Numbers)]]
****[[Question type - Array (Texts)]]
****[[Question type - Array (Yes-No-Uncertain)]]
****[[Question type - Date]]
****[[Question type - Equation]]
****[[Question type - File upload]]
****[[Question type - Gender]]
****[[Question type - Language switch]]
****[[Question type - Numerical input]]
****[[Question type - Multiple numerical input]]
****[[Question type - Ranking]]
****[[Question type - Text display]]
****[[Question type - Yes-No]]
****[[Question type - Multiple choice]]
****[[Question type - Multiple choice with comments]]
****[[Question type - 5 point choice]]
****[[Question type - List (Dropdown)]]
****[[Question type - List (Radio)]]
****[[Question type - List with comment]]
****[[Question type - Short free text]]
*****[[Question_type_-_Short_free_text#Location|Set up maps and store location]]
****[[Question type - Long free text]]
****[[Question type - Huge free text]]
****[[Question type - Multiple short text]]
***[[Survey_structure#Reordering_questions_and_question_groups|Change question order]]
***[[Question toolbar options]]
****[[Preview function]]
****[[Edit question]]
****[[Check question logic]]
****[[Delete question]]
****[[Export question]]
****[[Copy question]]
****[[Setting conditions]]
****[[Adding answers or subquestions]]
****[[Default answers]]
**[[ExpressionScript Engine - Quick start guide]]
***[[ExpressionScript - Presentation]]
***[[ExpressionScript How-tos]]
***[[ExpressionScript examples]]
***[[ExpressionScript Engine roadmap]]
***[[ExpressionScript for developers]]
***[[ExpressionScript sample surveys]]
****[[Expression Manager]] - old page with full documentation
**[[Show logic file]]
*[[Survey toolbar options]]
**[[Testing a survey]]
**[[Activating a survey]]
**[[Running a survey safely]]
***[[Changing an active survey]]
**[[Closing a survey]]
**[[Iterate survey]]
**[[Tools]]
***[[Delete survey]]
***[[Quick-translation]]
***[[Reset conditions]]
***[[Survey logic file]]
***[[Regenerate question codes]]
**[[Display/Export survey]]
***[[QueXML PDF Export]]
***[[Tab Separated Value survey structure]]
**[[Survey participants]]
**[[Responses (survey results)]]
***[[Responses & statistics]]
****[[Responses & statistics#Responses summary|Response summary]]
****[[Responses]]
****[[Data entry]]
****[[Statistics]]
*****[[Statistics - expert mode]]
*****[[Statistics - simple mode]]
****[[Timing statistics]]
****[[Export responses]]
****[[Import responses]]
*****[[Problems & solutions]]
****[[View saved but not submitted responses]]
****[[Iterate survey#General|Iterate survey]]
****[[Batch deletion]]
***[[Data entry]]
***[[Partial (saved) responses]]
*[[Multilingual survey]]
*[[Not categorized and advanced features]]
**[[SGQA identifier]]
**[[Using regular expressions]]
**[[URL fields]]
**[[RemoteControl 2 API]]
**[[Data encryption]]
*[[General FAQ]]
*[[Troubleshooting]]
*[[Workarounds]]
**[[Workarounds: Question design, layout and templating]]
**[[Workarounds: Manipulating a survey at runtime using Javascript]]
**[[Workarounds: Survey behaviour]]
**[[Workarounds: Further solutions provided by LimeSurvey users]]
*[[License]]
*[[Version change log]]
*[[Plugins - advanced]]
**[[Available third party plugins]]

=LimeSurvey development= 
*[[Version guide]] - A short guide on version numbering
*[[Development overview]] - General pages about LimeSurvey development
*[[LimeSurvey 2.x development documentation]]
*[[New Template System in LS3.x]] - Quick overview of the novelties of the LimeSurvey 3 template system

=Translating LimeSurvey= 


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

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

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

</translate>

Statistics - Mantis (measurement)

2020-04-21T12:49:27Z

Cdorin: Created page with "To be continued"

To be continued

QS:Em validation sq

2020-04-15T09:43:54Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Sub-question validation equation (em_validation_sq)=== 


'''Description'''


This is an equation that is used to validate each subquestion (text field) individually. Any text field that does not pass these validation conditions will have its background color turned pink (using the .em_sq_fn_validation CSS style) to highlight the error. Note that this is available in addition to the regular expression-based validation option.


'''Valid values'''


Any equation that makes use of the [[ExpressionScript - Presentation|ExpressionScript]] syntax, without surrounding curly braces.


'''Examples'''


For example, if you want to allow only numbers that are a multiple of 3 as answers, the equation would be:


<syntaxhighlight lang="php" enclose="div">(this / 3) == floor(this/3)</syntaxhighlight>


The reserved variable [[ExpressionScript - Presentation#The_reserved_.27this.27.2C_.27self.27.2C_and_.27that.27_variables|''this'']] is automatically replaced by a reference to the active text entry cell.


</onlyinclude>


[[Category:Question Settings]][[Category:Question Logic Options]]

</translate>

QS:Em validation sq

2020-04-15T09:43:32Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Sub-question validation equation (em_validation_sq)=== 


'''Description'''


This is an equation that is used to validate each subquestion (text field) individually. Any text field that does not pass these validation conditions will have its background color turned pink (using the .em_sq_fn_validation CSS style) to highlight the error. Note that this is available in addition to the regular expression-based validation option.


'''Valid values'''


Any equation that makes use of the [[ExpressionScript]] syntax, without surrounding curly braces.


'''Examples'''


For example, if you want to allow only numbers that are a multiple of 3 as answers, the equation would be:


<syntaxhighlight lang="php" enclose="div">(this / 3) == floor(this/3)</syntaxhighlight>


The reserved variable [[ExpressionScript - Presentation#The_reserved_.27this.27.2C_.27self.27.2C_and_.27that.27_variables|''this'']] is automatically replaced by a reference to the active text entry cell.


</onlyinclude>


[[Category:Question Settings]][[Category:Question Logic Options]]

</translate>

QS:Max num value n

2020-04-15T09:41:35Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Maximum value of the numerical input (max_num_value_n)=== 


'''Description'''


Maximum value of the numeric input that can be introduced in the input box by the respondent.


'''Valid values'''
*Any integer value above 0
*Any number
*Any SGQA code
*Any question code (variable name)
*Any equation, using [[ExpressionScript - Presentation|ExpressionScript]] syntax, without surrounding curly braces.
</onlyinclude>


[[Category:Question Settings]][[Category:Question Input Options]]

</translate>

QS:Min num value

2020-04-15T09:40:44Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Minimum sum value (min_num_value)=== 


'''Description'''


This setting is available in the multiple numeric and numeric array input questions. When this attribute is set, the input value(s) (depending on the type of question) must meet this criteria - the (sum of) number(s) has to be higher than the value you type in this box. Otherwise, the respondents will not be able to submit her answer(s).


'''Valid values'''
*Any integer value above 0
*Any number (using . (dot) for decimal separator)
*Any SGQA code
*Any question code (variable name)
*Any equation, using [[ExpressionScript - Presentation|ExpressionScript]] syntax, without surrounding curly braces.


'''Example'''
*Setting a value of 10 would mean that the total value of all numbers entered in all input boxes fr this question may not be smaller than 10. Totals of 9 would not be allowed. A total of 12 would be acceptable.


</onlyinclude>


[[Category:Question Settings]][[Category:Question Input Options]]

</translate>

QS:Max num value

2020-04-15T09:38:36Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Maximum sum value (max_num_value)=== 


'''Description'''


This setting is available in the multiple numeric and numeric array input questions. When this attribute is set, the input value(s) (depending on the type of question) must meet this criteria - the (sum of) number(s) has to be smaller than the value you type in this box. Otherwise, the respondent will not be able to submit her answer.


'''Valid values'''
*Any integer value above 0
*Any number
*Any SGQA code
*Any question code (variable name)
*Any equation, using [[ExpressionScript - Presentation|ExpressionScript]] syntax, without surrounding curly braces.


'''Example'''
*Setting a value of 20 would mean that the total value of all numbers entered in all input boxes for this question may not exceed 20. Totals of 21 would not be allowed. A total of 15 would be acceptable.


</onlyinclude>


[[Category:Question Settings]][[Category:Question Input Options]]

</translate>

QS:Equals num value

2020-04-15T09:37:50Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Equals sum value (equals_num_value)=== 


'''Description'''


Sets the sum total of all predefined answers that will be accepted. For example: Setting a value of 20 for this attribute would mean that the only acceptable total for all items would be 20. A value of 15 or 60 would be unacceptable.


'''Valid values'''


*Any number value


*Any SGQA code
*Any question code (variable name)
*Any equation, using [[ExpressionScript - Presentation|ExpressionScript]] syntax, without surrounding curly braces.


</onlyinclude>


[[Category:Question Settings]][[Category:Advanced Question Settings]]

</translate>

QS:Equals num value

2020-04-15T09:37:22Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Equals sum value (equals_num_value)=== 


'''Description'''


Sets the sum total of all predefined answers that will be accepted. For example: Setting a value of 20 for this attribute would mean that the only acceptable total for all items would be 20. A value of 15 or 60 would be unacceptable.


'''Valid values'''


*Any number value


{{FeatureChange|v=1.92}}


*Any SGQA code
*Any question code (variable name)
*Any equation, using [[ExpressionScript - Presentation|ExpressionScript]] syntax, without surrounding curly braces.


</onlyinclude>


[[Category:Question Settings]][[Category:Advanced Question Settings]]

</translate>

QS:Min num value n

2020-04-15T09:36:44Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Minimum value of the numeric input (min_num_value_n)=== 


'''Description'''


Minimum value of the numeric input that can be introduced in the input box by the respondent.


'''Valid values'''
*Any integer value above 0
*Any number
*Any SGQA code
*Any question code (variable name)
*Any equation, using [[ExpressionScrip - Presentation|Expression Manager]] syntax, without surrounding curly braces.
</onlyinclude>


[[Category:Question Settings]][[Category:Question Input Options]]

</translate>

QS:CSS Class

2020-04-15T09:35:51Z

Cdorin:

<translate>

<languages />

<onlyinclude>
===CSS class (css_class)=== 
'''Description'''


If you want to add special CSS classes to certain questions, you can enter the CSS class name(s) in this box. Make sure you leave an empty space between different class names.


'''Valid values'''


* Any text string with a space between different CSS class names.


{{Hint|Text=You can also insert an [[ExpressionScript - Presentation|expression]] in this box{{NewIn|3.0.0}}. Remember that the output of the expression will not be updated dynamically.}}


{{Alert|[http://www.w3.org/TR/CSS2/syndata.html#characters According to the W3C], CSS class names can contain only the characters [a-zA-Z, and 0-9] and ISO 10646 characters U+00A1 and higher, plus the hyphen (-) and the underscore (_). They cannot start with a digit, or a hyphen followed by a digit. LimeSurvey encodes CSS classes, but it does not fix it totally.}}
</onlyinclude>


[[Category:Question Settings]][[Category:Question Display Options]]

</translate>

QS:Em validation q tip

2020-04-15T09:32:35Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Tip for whole question validation equation (em_validation_q_tip)=== 


'''Description'''


If you are using [[QS:em_validation_q|the question validation equation]], you can use this box in order to display an optional message as question '''tip''' on how the question has to be filled out.


'''Valid values'''


*Any string or equation that makes use of the [[ExpressionScript - Presentation|ExpressionScript]] syntax.


'''Example'''


See the example from the [[QS:em_validation_q| question validation equation]] wiki section- it shows how the tip can be tailored to show which parts of a multiple short text question fail the validation criteria.


</onlyinclude>


[[Category:Question Settings]][[Category:Question Logic Options]]

</translate>

QS:Em validation q

2020-04-15T09:31:22Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Question validation equation (em_validation_q) === 


'''Description'''


This is an equation that is used to validate the entire question (e.g, all of its parts collectively for a multi-answer question). If the question fails the validation criteria, then em_validation_q_tip message will be displayed (it uses the CSS style .error). This tip uses the .em_q_fn_validation CSS style, which is hidden by default within template.css.


The main difference between this feature and the subquestion validation equations ([[QS:Em_validation_sq|em_validation_sq option]]) is that for this feature, if the question (or question parts) fail validation, then an error message could be shown. For the subquestion validation, each text entry cell (e.g., in an array question type, but it can also be applied to single entry question types) will be styled so that the background color is (light) red.


'''Valid values'''


*Any equation that makes use of the [[ExpressionScript - Presentation|ExpressionScript]] syntax, without surrounding curly braces.


'''Example'''


*You want to collect demographic information from users via a multiple short text question, and you want to validate that the user has entered a valid email address and phone number.


This example shows how the question looks with invalid answers:


<center>[[File:validation-invalid-both.jpg]]</center>


And here is what it looks like with one invalid answer:


<center>[[File:validation-invalid-phone.jpg]]</center>


Here is how you edit a question to enter that information:


<center>[[File:validation-gui.jpg]]</center>


And here is part of the [[Show_logic_file|Show Logic File]] output that lets you check the accuracy of your expression and ensure that there are no syntax errors:


<center>[[File:validation-logic.jpg]]</center>


As you can see, the validation equation tests that both the email and phone number are either empty or match a regular expression filter.


The validation tip only shows the warning message if the phone or email appears invalid.


{{Hint|Text=In order to create complex validation messages, read about the usage of the [[ExpressionScript - Presentation|ExpressionScript]].}}


If you wish to import the example from above into your LimeSurvey installation, download the following .lsq file: [[Media:Em validation q example.zip|Em_validation_q_example.zip]].


{{Hint|Text=Remember, LimeSuvey uses the Perl syntax for regular expressions, so they should start and end with / (slash character)!}}
</onlyinclude>


[[Category:Question Settings]][[Category:Question Logic Options]]


Another slightly different example can be downloaded below. It states that none of the three subquestion fields can be empty at the same time and that at least one of them has to be filled in (according to its corresponding regular expression). Download the question from [[Media:Limesurvey_question_id_question_validation.zip|here]].

</translate>

QS:Random group

2020-04-15T09:30:06Z

Cdorin:

<languages />
<translate>

<onlyinclude>

===Randomization group name (random_group)=== 


'''Description'''


It places the questions into a specified randomization group, all questions included in the specified group being displayed in a random order to the survey respondents.


You can find a sample survey using randomization group name in [[ExpressionScript_sample_surveys#Randomly_Ask_A_Specific_Number_Of_Questions_In_A_Group_.28a_subset_of_the_questions.29|ExpressionScript sample survey]].


'''Valid values'''


Just enter any string you like (for example: 'group1'). All question which have set the same string within the '''randomization group name''' box will have their place in the survey randomized (=randomly exchanged among each other).


'''Preview'''
To preview the questions use the ''preview survey'' instead of the ''preview question group'' function, as the second has been reported to not show the questions in a randomized order.
</onlyinclude>


[[Category:Question Settings]][[Category:Question Logic Options]]

</translate>

QS:Max answers

2020-04-15T09:27:57Z

Cdorin:

<translate>

<languages />
<onlyinclude>

===Maximum answers (max_answers)=== 


'''Description'''


It can be used to limit the total number of answers a user can select in a multiple choice question.


'''Valid values'''


*Any number value
*Any [[SGQA_identifier|SGQA]] code
*Any question code (variable name)
*Any equation, using [[ExpressionScript - Presentation|ExpressionScript]] syntax, without surrounding curly braces.


'''Example'''


If set to 2, the user will only be able to check at most two checkboxes or one checkbox + fill the "Other" field (if any). For the [[Question_type_-_Ranking|Ranking question type]], the participant would be able to select maximum two items.
</onlyinclude>


[[Category:Question Settings]][[Category:Question Logic Options]]

</translate>

QS:Min answers

2020-04-15T09:24:39Z

Cdorin:

<translate>

<languages />

<onlyinclude>
===Minimum answers (min_answers)=== 


'''Description'''


This function can be used to ensure that a user selects at least a certain number of answers in a multiple choice question.


'''Valid values'''


*Any integer value above 0
*Any number
*Any [[SGQA_identifier|SGQA]] code
*Any question code (variable name)
*Any equation, using [[ExpressionScript - Presentation|ExpressionScript]] syntax, without surrounding curly braces.


'''Example'''


If set to X (a random number), the users can submit the survey form if they select at least X checkboxes. If this option is utilised for ranking questions, this ensures that at least three items are ranked before allowing the respondent to submit the answers/survey.


<div class="simplebox">[[File:help.png]] Please note that if you use this attribute with Ranking questions, you have to set the question to '''non-mandatory'''. Otherwise, all the items need to be ranked which is counter-intuitive if you decide to use the '''min_answers''' function too.</div>
</onlyinclude>


[[Category:Question Settings]][[Category:Question Logic Options]]

</translate>

QS:Hidden

2020-04-15T09:20:52Z

Cdorin:

<translate>

<languages />

<onlyinclude>
===Always hide this question (hidden)=== 


'''Description'''


If enabled, the question will always be hidden - it will not be displayed to the survey participants. This function can be used in the following scenarios:


* If you wish to prefill a question with a URL and you want not to have it displayed on the screen. This overrides any conditions used within the survey because the respective question will not even be embedded on the page.
* If you wish to store or calculate a value on the fly via the [[ExpressionScript - Presentation]].


<div class="simplebox">[[File:help.png]] '''Note:''' A common question type that is used with this function is the [[Question_type_-_Equation|Equation]] one.</div>


'''Available options'''
*On
*Off (default)
</onlyinclude>


[[Category:Question Settings]][[Category:Question Display Options]]

</translate>

QS:Relevance

2020-04-15T09:18:05Z

Cdorin:

<translate>

<languages />

<onlyinclude>
===Relevance equation=== 


'''Description'''


If the value of the relevance equation is "1" or "true", the question is "relevant" in the survey context, i.e. it is shown to the survey participant. If not, the question is hidden. Any survey question allows you to specify a relevance equation. This function is the successor of [[Setting_conditions|conditions]] and supports much more complex conditional logic.


'''Syntax Highlighting'''


Whenever you save the relevance equation, it is evaluated and syntax-highlighted. Any errors will be color coded so that you can quickly detect and fix them.


{{Hint|Text=To check if all the relevance equations are used correctly within your survey, read about our [[Show_logic_file|show logic file]] feature.}}


'''Valid values'''


*Any equation that makes use of the [[ExpressionScript - Presentation|ExpressionScript]] syntax, without surrounding curly braces.


'''Examples'''


Here are good examples of [[ExpressionScript How-tos#Syntax_Highlighting|syntax highlighting]].


</onlyinclude>


[[Category:Question Settings]][[Category:General Question Options]]
</translate>

Export responses

2020-04-15T09:16:01Z

Cdorin:

<languages /> <translate>

__TOC__


Once your survey is active, you can start browsing responses and export them for further analyses. To access the export function, click on '''Responses''' (displayed on any survey-related panel) and then click on '''Responses & statistics''' from the dropdown menu.


<center>[[File:browse_results.png]]</center>


The default page that is loaded is [[Response summary]]. Now, look for the '''Export''' option located on the top toolbar:


<center>[[File:export2.png]]</center>


Several options are available:


*[[Export responses#Export responses|Export results]]
*[[Export responses#Export responses to SPSS|Export responses to SPSS]]
*[[Export responses#Exporting a VV survey file|Export a VV survey file]]

=Export responses= 


The following panel is displayed when the first export-related option is selected from the drop-down menu:


<center>[[File:Export responses page.png]]</center>


Several filter options are separated into:


*'''Format:''' it allows you to select the format in which you wish to export your results. The following formats are available:
** ''CSV File (all charsets):'' see also the "CSV field separator" option at the bottom of the '''Format''' tab. The default one is "comma". The other options are "semicolon" and "tab"
** ''HTML''
** ''R (data file):'' if this option is chosen, please also export your survey into R (syntax file). To find out more details about how you can analyse your data in R, check [[Export_responses#Export_R|this wiki subsection]]
** ''Microsoft Word (latin charset)''
** ''Microsoft Excel (all charsets)''
** ''STATA (.xml):'' for more details on how to analyse your data in STATA, read the following [[Export_responses#Export_STATA-xml|wiki subsection]]
** ''PDF''
** ''R (syntax file):'' if this option is chosen, please also export your survey into R (syntax file). To find out more details on how you can analyse your data in R, check [[Export_responses#Export_R|this wiki subsection]]


*'''General'''
** ''Completion state:'' set to export all records OR completed records only OR incomplete records only. For more information on their meaning, check [[Responses_%26_statistics#Responses_summary|this wiki subsection]]
** ''Export language:'' the default option is the base language of your survey


*'''Range''': refers to the id of the stored responses from the [[Responses#The_response_table_page|response table]]. In case the values you introduced are wrong (ie., no response id was found between the values you entered), a pop-up will be displayed when you will try to export the responses asking you to enter values that can be found in the table.


{{Note|'''Range''' is not displayed if you wish to export [[Export_responses#Export_a_single_response|only one response]] or [[Export_responses#Export_a_group_of_responses|a group of responses]].}}


*'''Responses'''
** ''Export responses as:'' you can either export full answers or convert answer codes. If the later is selected, the answers submitted by your respondents will be replaced by the answer code of the respective answer. "Yes" and "No" answers will be converted to "Y" and "N" answers to any string of characters. If "Convert Y/N to" is enabled, then the answer codes that use Y and N as answers will be converted into the strings of characters from their corresponded boxes. By default, the values are 1 for Y and 2 for N.


{{Note|To better understand the difference between full answer and answer codes, check the following [[Adding_answers_or_subquestions|wiki section]].}}


*'''Headings'''
**''Export question as:'' sets how the heading should look like in the exported file. The following options are available:
***Question code
***Abbreviated question text: the length of the question is decreased if this option is selected (useful if you work with long questions)
***Full question text (default)
***Question code & question text
**''Strip HTML code:'' enabled by default in order not to export the HTML used in question text boxes
**''Convert spaces in question text to underscores:'' disabled by default. If enabled, the spaces from the question text are converted to underscores.
**''Text abbreviated:'' disabled by default. If enabled, the question text will be abbreviated. The length of the question text is given by the number put into the "Number of characters". Please note that this option is useful in the case in which you wish to abbreviate the question texts resulted from selecting either "Full question text" or "Question code & question text" as heading text.
** ''Use ExpressionScript code:'' disabled by default. If enabled, the questions and subquestions will be exported as they are used within the ExpressionScript. Therefore, the heading would resemble the [[ExpressionScript - Presentation#Qcode_variable_naming|qcode variable naming]]. Please note that one of the following question heading options has to be chosen: "Question code" or "Question code & question text".
** ''Number of characters:'' set up a maximum number of characters to be displayed in the headings. This option works if you wish to export your question as abbreviated question text. The default number is 15.
** ''Code/text separator:'' select the option you wish to use to separate the question code from the text of the question. By default, it is a "dot" followed by an empty string (<SPACE>).


*'''Column Control''': sets the questions (and their corresponding answers) to be exported. The questions in this list are represented by their corresponding question code and question text. By default, all columns will be exported. To select multiple columns, use CTRL and/or SHIFT keys.


*'''Token control''' - sets which '''''survey participant''''' data should be exported. This option is only available if your survey is [[Participant_settings#Anonymized_responses|not anonymous]]! Click here for more information on what a [[Survey participants|survey participant table]] is and how you can use it in LimeSurvey.


<center>[[File:export_tokens.png]]</center>

==Export R== 


The free software environment [http://www.r-project.org/ R] is an alternative for SPSS used for statistical computing and graphics.


'''Follow these steps to import your dataset in R:'''


#Download '''both''' the syntax file and data file
#Store both files in your R working directory (use ''getwd()'' and ''setwd()'' in a R command window to get and set your working directory)
#Enter <code>source("File_name_syntax.R")</code> in the R command window. It will import the data in the correct format to a data frame called "data".


{{Note|You may also use [https://www.rstudio.com/products/rstudio/download/ RStudio] (free open source solution) to work with your data in R in a nice and easy-to-understand GUI. By following the above guideline, your data should look like this:


<center>[[File:Rstudio-screen1.png]]</center>


<center>[[File:RStudio-screen2.png]]</center>}}


Responses with limited options will be factored with the levels matching the code of the question and the labels matching the options.


Questions with "other" as an option will have the question field with _Other appended as a new column for the other data.


<div class="simplebox"> '''R-export''' is a plugin in LimeSurvey. If you cannot find the R-export options (R (syntax file), R (data file)) under '''Format''', make sure the R-export plugin is enabled in the [[Plugin menu|plugin menu]].


<center>[[File:Export results to R plugin.png]]</center></div>

==Export STATA-xml== 


STATA is a commercial data analysis and statistical software package.


This export routine was created to facilitate rapid analysis of data collected with LimeSurvey. It creates an XML-file in STATAs proprietary format. This format offers several advantages over importing plain CSV files:
*Data sets are fully labelled including variable labels (question, subquestion) and value labels (answers, if applicable).
*Dates are already transformed to STATAs internal date format and thus can directly be used to calculate differences between days etc.
*Variable names are, if necessary, converted to a STATA compatible format.
*Data formats of variables (string, integer, float, etc.) are already set according to the underlying data (no more numbers encoded as strings!).


'''How to load the file in STATA:'''
# In STATA's menu, click on File, Import, xml-data
# Choose browse to navigate to your exported file and click 'OK'.


{{Note|If you prefer STATA's binary .dta files, you can just save your data again in this format.}}


{{Alert|title=Attention|text=
*Due to a limitation in STATA's data format, the length of string (text) variables have a maximum of 244 characters (Stata versions 8-12) and 2045 characters (Stata version 13 and above). Please indicate your Stata version in the settings of the [[Plugin menu|export plugin]]:


<center>[[File:STATA export plugin.png]]</center>


<center>[[File:Export_for_stata.png]]</center>


*STATA only supports attaching value labels to numerical values. So, to achieve short answers (usually one or two digits) and have these properly labelled, one should use numerical answer-codes in LimeSurvey (1=Totally agree). If non-numerical answer codes are used (A=Totally agree), then the complete answer text will be used as answer (eg., 'Totally agree').}}

=Export responses to SPSS= 


SPSS Statistics is a software package used for logical batched and non-batched statistical analysis. You can use the official SPSS package or [https://www.gnu.org/software/pspp/ GNU PSPP] replacement for the proprietary program SPSS.


To export your response data to SPSS, go to '''Responses & statistics''' section and select the SPSS-corresponding option located under the '''Export''' menu:


<center>[[File:Export2Spss.png]]</center>


The following page is displayed:


<center>[[File:Export response data to SPSS.png]]</center>


The following options are displayed in the panel:


*'''Data selection:''' you can select which data should be selected for export: all responses OR only complete responses OR only incomplete responses
*'''SPSS version:''' check your SPSS installation version. Two different export options can be chosen: prior to version 16 and 16 or up
*'''Language:''' acts like a filter that allows you to filter the exported responses based on the language used to fill out the survey
*'''Limit:''' type in any numerical value to get exported only the first "n" entries from your response table
*'''Offset:''' type in any numerical value to get exported your response table without the first "n" entries from your response table
*'''No answer:''' if left empty, an empty string is stored as answer for the questions that have not been answered by respondents. Type in this box any string of characters to replace the empty string. The set of characters will be displayed in the exported .dat file


SPSS export includes two files:
# a syntax file (''survey_xxxx_SPSS_syntax_file.sps'')
# and a data file (''survey_xxxx_SPSS_data_file.dat'').


After having downloaded these files you can open them using a raw text editor like notepad to take a look how the exported data looks like. The syntax file holds the commands that should be run to import the data. It is like a programming language inside SPSS. The .dat file contains a comma separated file with all data. '''We recommend you not to import your data as csv''' because there is the risk of loosing information about questions, label sets, and so on.

==Import LimeSurvey responses to SPSS== 


To import your data to SPSS, pursue these steps:
#Download the data and the syntax file.
#Open the syntax file in SPSS in Unicode mode.
#Edit the 'FILE=' line and complete the filename with a full path to the downloaded data file.
#Choose 'Run/All' from the menu to run the import.
#Done

=VVExport= 


Once you've begun collecting responses, there may be occasions where you need to be able to directly edit and modify large quantities of data from your responses table (where a spreadsheet tool may be more useful).


VVExport (the "VV" stands for vertical verification) allows you to export your responses table into a .csv file. So long as the general structure of the file remains intact, you can then edit values within it, and then import the file again into your responses table using the "VVImport" feature.


<div class="simplebox">'''When do I need to use VVExport and VVImport?
It is often used in three scenarios:
# In the first one, it is used to combine large amounts of data in one LimeSurvey installation. Imagine that you run two similar surveys on two different machines. In order to combine the two response tables, you will have to use VVExport, VVImport, and a third-party app (e.g., spreadsheet apps) to combine your data and put it on one LimeSurvey installation.
# It may also be used to edit the response table of a survey. For small edits, you can access the [[Responses#The_response_table_page|response table]] and edit the desired answers. Still, for "macro-editing", VVExport and VVImport are recommended because a spreadsheet program can help you quickly edit dozens of responses at the same time.
# A "vv survey file" allows you to import the responses to a survey when the question/answer combinations have changed. Effectively, this allows you to add or remove questions in an active survey.


'''Attention!''' To add, remove or '''edit''' questions, you have to deactivate your survey, do the changes, and then activate it again. The old response table that was created as a result of the [[Closing_a_survey#Deactivation|response table deactivation]] can be imported into the newly activated survey by selecting '''Import''' -> '''Import responses from a deactivated survey table'''. For more details, check this [[Import responses#Import responses from a deactivated survey table|wiki subsection]].</div>


To export your data via VVExport, go to [[Responses & statistics]] section and select the VV-corresponding option located under the '''Export''' menu:


<center>[[File:Export VV button.png]]</center>


The following page will be loaded:


<center>[[File:VV2-export-en.png]]</center>


* '''Survey ID:''': The ID of the survey to be exported
* '''Export:''' The completion state of the responses to be exported:
**''Completed responses only:'' if a respondent reaches the last page of a survey and clicks the '''Submit''' button, then his or her response is marked as being complete
**''Incomplete responses only:'' if a respondent does not click on that ''Submit'' button located before the end page, then the response is marked as being incomplete
**''All responses:'' export both completed and incomplete responses
* '''File extension:''' The file extension. The file is a TSV ([[wikipedia:Tab-separated_values|tab-separated values]]) file. For easy opening in MS-Excel set the extension to .txt. If you use LibreOffice, OpenOffice or any other spreadsheet program, you can leave it to .csv (default format)


{{Note|The first two rows of the spreadsheet are the column labels. The first row is a "human readable" column heading that details the name of the question. The second row is the real column name (Internal DB- or Qcode-name) for that response.}}


* '''VV export version:''' The 1.0 version (''Old VV version'') uses database column headers, version 2.0 (Last VV version) uses [[Expression_Manager#Qcode_Variable_Naming|Qcode Variable Naming]]. Version 2.0 is selected by default if all of your question code are unique.


{{Note|''Last VV version'' allows different column names than the ones from the database. If your question codes are unique, then the new version is selected. In the new version each column name uses the [[Expression_Manager#Qcode_Variable_Naming|Qcode Variable Naming]]. The update of surveys is [[Export responses#Editing a VV survey file|easier]] in this way.}}


{{Alert|title=Attention|'''Things you should be aware of:'''
* If you want to import responses using "VVImport" make sure to check whether the responses should be added to the existing responses or all responses should be overwritten.
* If you are trying to import responses from a different yet identical (e.g., identical questions/answers from another survey), make sure you are using the correct vv file and that the first two lines of the .csv file are correct.
* If you import a survey to your LimeSurvey installation the SID will not change (if possible). The group id and question id however might change. So you might have to adjust the first two heading lines to match the new group id/question id.}}

==Exporting a VV survey file== 


When you choose to export responses using VVExport, you will be given the option to choose whether you want to export all responses or complete responses only or incomplete responses only. The file extension allows you to choose which extension the exported file will have. For easy use, .csv should be chosen.


The first two rows of the spreadsheet/tab-delimited file are the column labels. The first row is a "human readable" column heading that details the name of the question/answer field. The second row is the internal PHP/database column name for that response.


You should not modify the first two rows of this spreadsheet if you want to be able to "import" the data back into LimeSurvey at a later point.

==VV files structure - example== 

===VV version 1 TSV file=== 


<syntaxhighlight lang="text" enclose="div">
Response ID Date submitted Last page Start language Token please vote from 1 to 6 (1 - super, 6 - worst)
id submitdate lastpage startlanguage token 46492X40X1991
183 09.11.11 11:44 3 de jsfhusdgqfygqsy 4
184 09.11.11 11:53 3 de sdfhsifgsyergze 2
190 09.11.11 11:44 3 de qsdqshkfhkdsjhj 1
</syntaxhighlight>

===VV version 2 TSV file=== 


<syntaxhighlight lang="text" enclose="div">
Response ID Date submitted Last page Start language Token please vote from 1 to 6 (1 - super, 6 - worst)
id submitdate lastpage startlanguage token QCODE
183 09.11.11 11:44 3 de jsfhusdgqfygqsy 4
184 09.11.11 11:53 3 de sdfhsifgsyergze 2
190 09.11.11 11:44 3 de qsdqshkfhkdsjhj 1
</syntaxhighlight>


In this example, the SQGA identifiers are not used - instead, the Qcode variable naming <code>QCODE</code> is used in the second line.


<div class="simplebox">To understand the difference between SGQA and Qcode, please check the following two wiki sections:
* [[SGQA_identifier|SGQA wiki section]]
* [[Expression_Manager_-_presentation#Qcode_variable_naming|Question code wiki section]]


We generally recommend our users to use question codes since they are much easier to be used (it represents an addition to the SGQA system used in the earlier versions of LimeSurvey.
</div>

==Reserved names== 


A .vv file uses left and right brackets for reserved names. When importing, this string is replaced by:
* <code>{question_not_shown}</code> : NULL value in database. LimeSurvey uses [empty string] for not answered question, and NULL value for questions not shown.
* <code>{quote}</code> : " (a double quote)
* <code>{cr}</code> : Carriage return
* <code>{newline}</code> : A new line
* <code>{lbrace}</code> : Left bracket (for example, if you want to have {cr} in response : use <code>{lbrace}{cr}</code> )

==Editing a VV survey file== 


When a .vv file has been successfully exported you can use a spreadsheet tool to open and edit the file. If you have to choose a column separator when opening the file please use the "Tab" character. If you are using non-ASCII characters make sure you set "UTF-8" as character set.


{{Alert|If you are using Microsoft Excel to edit the exported vv file, you should know that Excel destroys the original data structure of the file. This causes an error when you try to reimport the edited .vv file. The workaround is to save as a .txt file once you edited the data from the .csv file. If you save as .csv, Excel uses comma-delimits which will not import into LimeSurvey. By saving as a .txt file, Excel saves as a tab-delimited file which can be imported into LimeSurvey. For other Excel-related issues, check this [[Problems_%26_solutions#Excel|wiki subsection]].}}


If you simply wish to simply edit your data, then be careful at the first two columns so that you can later easily VVImport your data back into your LimeSurvey installation!


If you combine data from two different surveys, please note that the old VV version uses [[SGQA_identifier|SGQA]] which will most probably give you different "question ids". Therefore, be careful how you merge the data!


The alternative would be to use the last VV version because question codes can be constant throughout different LimeSurvey installations (if you use the same survey structure across multiple LimeSurvey instances).


When importing the VV file, if two response IDs match and the '''Exclude record IDs''' is disabled, you can make LimeSurvey:
*Report and skip the new record
*Renumber the new record
*Replace the existing record
*Replace answers in file in the existing record


{{Note|For more information on how to import a VV file, check the following wiki subsection: [[Import_responses#Import_a_VV_survey_file|Import a VV survey file]].}}

=Other export options= 


In case you do not need to export the whole survey, you can also choose to export only:
* [[Export responses#Export a single response|a single responses]] or
* [[Export responses#Export a group of responses|a group of (filtered) responses]]

==Export a single response== 


If you want to export an individual response, you can do it in two ways:


1. Login to LimeSurvey, choose your survey, click on [[Notifications & data]] tab and make sure you receive basic email notifications:


<center>[[File:Receive emails detailed.png]]</center>


Every time someone has completed a survey, you will receive an email with a link: "Click the following link to see the individual response". This will take you to a page with a button above the response data saying "Export this response":


<center>[[File:Export one response 2.png]]</center>


Choose how the single response will be exported:


<center>[[File:Export one response 3.png]]</center>


{{Note|You can observe that no '''Range''' export option is displayed since you export only one answer}}


2. Login to your LimeSurvey installation/instance, choose your survey. Select tab [[Responses]] located under the '''settings''' tab:


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


{{Note|[[Responses]] and [[Statistics|statistics]] options are displayed under the '''settings tab''' only if the survey is '''not''' [[Closing_a_survey#Deactivation|deactivated]].}}


See the "action" column. Hover the mouse over each option and see which one allows you to see the response details (the first button):


<center>[[File:Export one response 1.png]]</center>


The response entry will be loaded. Click on the "Export this response" button. You will be redirected to a panel from where you can select how the exported file should look like:


<center>[[File:Export one response 3.png]]</center>


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


As you can observe, you can also export the response as a pdf file:


<center>[[File:Export a response as pdf.png]]</center>


This option is usually needed when you wish to share to one of your respondents his/her results. In the case in which you wish to share only certain parts of his/her answer, check the pdf export option located in the [[Statistics#Statistics_-_expert_mode|Statistics panel]]. In this way, you can hide your ''hidden questions'' and/or ''different assessments'' you run "in the background".

==Export a group of responses== 


This option is useful in the case in which you wish to export a certain group of filtered responses.


To do it, access your [[Responses#The_response_table_page|Responses table]] table:


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


{{Note|[[Responses]] and [[statistics|statistics]] options are displayed under the '''settings tab''' only if the survey is '''not''' [[Closing_a_survey#Deactivation|deactivated]].}}


You can either order the responses according to the value from each column by clicking on the column label or you can type in the empty boxes located below the column labels a string of characters according to which you wish your data to be filtered to.


<center>[[File:Filter group of responses.png]]</center>


<div class="simplebox">[[File:Help.png]] Not any string of characters may work. It is dependent of the question type. For example, a popup will be displayed for "startdate". For number-based questions, you may use signs such as ">=, <=, <, >" to better filter your data. For the "completed" column, a dropdown box is displayed if you click on "All" (default option), allowing you to filter your response table data according to the completion state of the responses and so on.</div>


Once done, your table should look like the one below. Now, tick all the filtered responses, click on the '''Selected response(s)...''' button located in the bottom left side of the response table, and select the '''Export''' button:


<center>[[File:Export group of responses 1.png]]</center>


The next page will be loaded:


<center>[[File:Export group of responses 2.png]]</center>


The '''Range''' column is not displayed since you have already selected the entries you wish to export. To check those IDs, check '''Selection''' (see the above screenshot). You can click on '''Reset''' if you wish to export all your data instead.
</translate>

URL fields

2020-04-15T09:13:57Z

Cdorin:

<languages />
<translate>


__TOC__

=Introduction= 


URL fields parameters can be used in the:
* [[URL_fields#End_URL_field|End URL]] field of the survey (see [[Text elements|survey text elements]])
* URL field of the quota rule (read more about survey quotas [[Survey quotas|here]])
* [[URL_fields#Start_URL|Start URL]] field of the survey (see [[Text elements|survey text elements]]).

=End URL field= 


'''At the end of a survey or when a quota causes a survey to terminate''', there is the option to set an ending URL. This URL is presented to the participant who has finished the survey on the end page or you can optionally set the participant to be automatically redirected to the respective URL. This can be done by filling in the End URL option from the [[Text elements|Survey text elements]] panel and by enabling the automatic load of the end URL from the [[Presentation]] panel once a survey is completed .


But, LimeSurvey offers the possibility to use URL fields in many other ways which in turn allows you to enhance the functionality of your survey.

==Basic fields== 


You can use '''{SAVEDID}''', '''{TOKEN}''', '''{SID}''', and '''{LANG}''' in the end URL:
*'''SAVEDID''' is the id assigned to this particular submission;
*'''TOKEN''' is the token used to participate in the survey;
*'''SID''' is the survey ID;
*'''LANG''' is the language code.


For example:


<code>
<nowiki>https://www.limesurvey.org/test.php?var1={SAVEDID}&var2={TOKEN}&var3={SID}&lang={LANG}</nowiki>
</code>

==Answer fields== 


You can also use '''{INSERTANS:SGQA}''' or [[ExpressionScript - Presentation#Qcode_Variable_Naming|ExpressionScript variables]]. This URL field allows you to add the response to a specific question in the survey into the end URL. This can be useful for sending a response to an external script (i.e. an email address collected during the survey).


For example:


<code><nowiki>
https://www.limesurvey.org/test.php?email={EMAILADDRESS}
</nowiki></code>


It is important to add "newtest/y" to the URL to force a new session whenever your survey participants wants to fill in your survey.


<code><nowiki>
https://exampletest.limequery.com/index.php/survey/index/sid/48315/newtest/Y?48315X2X222007=Y&48315X2X222008=Y
</nowiki></code>


In the above scenario, the URL pertains to a survey with ID = 48315, group =2, question=22 and answercodes = 2007 and 2008.


{{Note|For more details on the necessity of "newtest/y", check the following [https://www.limesurvey.org/forum/installation-a-update-issues/108334-use-case-for-not-using-newtest-y forum thread].}}

==Expressions== 


You can also use any [[ExpressionScript - Presentation|expression]] here.


For example:


<code><nowiki>
http://www.limesurvey.org/test.php?gender={if(sex=='Male','M','F')}&name;={name}
</nowiki></code>

==Passthrough fields== 


To use passthrough fields, you '''must''' define the variable names via panel integration. If you don't assign a target question, the variables will not be saved into responses (read more about the LimeSurvey [[Panel integration|panel integration]] feature). To use such a parameter in the end URL, just insert the tag '''{PASSTHRU:<paramname>}''' where ''<paramname>'' is the name of your input parameter.


Let's suppose that you defined [[Panel integration|a parameter]] named "foobar". The survey is started with a link like this one:


<code>
<nowiki>https://example.org/limesurvey/index.php/survey/index/sid/12345/lang/eb?foobar=XYZ123</nowiki>
</code>


The XYZ123 is the value you want "to pass".


The end URL of a survey with the following URL <code><nowiki>https://www.limesurvey.org/test.php?foobarout={PASSTHRU:foobar}</nowiki></code> would then be converted to <code><nowiki>https://www.limesurvey.org/test.php?foobarout=XYZ123</nowiki></code>

=Start URL= 

==Prefilling a survey using GET parameters== 


You can prefill all answers except the [[Question_type_-_File_upload|upload]] and [[Question type - Equation|equation question type]]. You can use [[ExpressionScript - Presentation#Access to Variables|qcode naming]] for parameters and set the value for single question types. For the multiple question type, you must use a [[SGQA identifier]].


Then, answers are set to the prefilled value. For single choice option, you must use the code of the answer, for multi choice question, you must use Y if you want to prefill the answer.


Here are some start URL examples:


* <code><nowiki>http://ls.example.org/1234?QTEXT=prefilled</nowiki></code> : Fill in the question with code QTEXT with <nowiki>'prefilled'</nowiki>
* <code><nowiki>https://ls.example.org/1234?MULTI_SQ001=prefilled</nowiki></code> {{NewIn|v=3.14.1}} : Fill in the subquestion SQ001 of question with title MULTI with <nowiki>'prefilled'</nowiki> (for a multiple text question for example).
* <code><nowiki>https://ls.example.org/1234?single=-oth-&single_other=Other%20text</nowiki></code> {{NewIn|v=3.14.1}} : Select the "other" answer option of a single choice question and fill in the other value with the text "Other text".
* <code><nowiki>https://ls.example.org/1234?1234X1X1SQ001=prefilled</nowiki></code> : Fill in the subquestion SQ001 of question with ID: 1 from group with ID: 1 with <nowiki>'prefilled'</nowiki>
* <code><nowiki>https://ls.example.org/1234?1234X1X1SQ001=A1</nowiki></code> : Preselect the answer option <nowiki>'A1'</nowiki> of the subquestion SQ001 of question with ID: 1 from group that has ID: 1.
* <code><nowiki>https://ls.example.org/1234?1234X1X1SQ001=Y</nowiki></code> : Preselect the subquestion SQ001 of the question that has the ID 1, from the group that has ID: 1.


{{Hint|Text=GET parameters use "?" for the first parameter and "&" for the subsequent ones. If you already have "?" in your URL, you must use "&" to add more GET parameters.}}


{{Hint|Text=The extra GET parameters are only filled in when the survey starts anew. Therefore, for testing, always add newtest=Y to start a fresh survey. For example: <code><nowiki>http://ls.example.org/1234?QTEXT=prefilled&newtest=Y</nowiki></code>}}

==Prefilling a survey using GET parameters using URL parameters tab== 


You can prefill (sometimes easier) answers using URL parameters which can be configured in [[Panel integration|panel integration]].

==Prefilling and hiding the answer== 


You can use the [[QS:Hidden|hidden attribute]] of a question to hide it from your respondents. If so, the question still remains prefilled.

</translate>

ExpressionScript sample surveys

2020-04-15T08:55:27Z

Cdorin:

<languages />
<translate>


__TOC__

=Introduction= 


The best way to learn how to use the ExpressionScript is to play with working examples and modify them to your needs.


You may find below a set of sample surveys to demonstrate (and test) how the EM can be used to enhance your survey. These surveys can be found in the distribution's /docs/demosurveys folder.

=Relevance, Tailoring and Equations= 

==Overview== 


The following example computes the BMI (Body Mass Index) of each respondent. See below the features that are demonstrated within this example.

==EM Features Demonstrated== 


#'''Relevance''' - support for powerful conditional logic;
#'''Piping / Tailoring''' - offers the ability to pipe or tailor answers and question metadata;
#'''Dynamic Tailoring''' - note that reports are changed on the page as you answer questions.
#'''Micro-Tailoring''' - conditional tailoring withing sentences and reports using if() statements
#'''Equations''' - a new [[Question type - Equation|question type]] that lets you do calculations and store the results in the database, even if the calculation is hidden
#'''Conditional Validation''' - validation criteria, such as the minimum allowable value, can be conditional - e.g., based upon equations.

==Screenshots== 


This example computes the Body Mass Index, a calculation of your weight and height to determine whether you are overweight. Note that initially, all you see are the four mandatory questions:


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


Once you enter your information (and you get to choose whether to use metric or non-metric units), you see a tailored report that summarizes what you entered, telling you your weight status:


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


Here is a different example, using non-metric units to show how the result changes dynamically:


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


There are hidden [[Question type - Equation|Equation-type questions]] at the internal level that converts the data to metric (if needed), storing the metric height, weight, BMI, and weight status in the database without needing custom JavaScript.


You can see in the next set of examples how you can use mathematical and other functions within tailored reports. This is how the page looks like before you enter any data. There is conditional logic to show blank cells if no (or non-numeric) data is entered, rather than showing "NaN" or "Divide by Zero".


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


As numbers are entered, the on-page report changes to show the computation being performed, and its result.


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


There are many other examples in this sample survey. For example, the below screenshot shows one of the dozens of ways you can fill out the Dynamic Relevance page. As the help text notes, try different ages, and especially illogical combinations of responses to see the amusing messages generated at the bottom. Also note that if you say that you have more than one child, the message will say "I hope you enjoy playing with your X children", rather than saying "I hope you enjoy playing with your child". This shows how you can easily micro-tailor sentences to make them match the gender and/or number of your subjects. You can even easily conjugate verbs and decline nouns based upon gender and number.


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

==Download== 


To access the survey sample, please click on the following link: [[Media:LS3_em_tailoring.zip|LS3_em_tailoring.zip]].

=Sample Census= 

==Overview== 


This is a census example that asks how many people are in your household.


It demonstrates how group-level relevance can make it easier to implement a "loop" of questions. After creating the group for Person 1, I exported the group. Since I used qcode variable names like p1_name instead of the SGQA code, I could use a text editor to quickly edit and re-import the group several times (e.g., it took about 10 seconds to edit and re-import each repeating group, ensuring that all variables had unique variables names and that the group-level logic was correct).


You can also the [[Copy question|copy question]] feature, but it won't be as fast as the option suggested above.


This also shows how you can prevent the Finished message from appearing until the survey is truly finished (e.g., when all needed groups are completed).

==EM Features Demonstrated== 


#'''Group-level relevance''' - The follow-up groups (Person 1-5) only show for up to the number of cohabitants specified;
#'''Tailoring''' - The final report summarizes the demographic data for each cohabitant;
#'''Progressive question display''' - Whether in group or all-in-one mode, subsequent questions only show as soon as the preceding ones are answered.

==Screenshots== 


The survey generates a tailored report showing the demographics of the specified number of cohabitants:


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


If you switch to question-at-a-time mode, you see that the index tailors the questions. Since the user said that the person is a woman, it asks "What is her name". And since we answered "Mary", the next question says "How old is Mary"?


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

==Download== 


To download the survey sample, click here: [[Media:LS3_group_relevance.zip|LS3_group_relevance.zip]].

=Cascading Array Filters= 

==Overview== 


This survey is based on the design of a survey courtesy of Joy Lane Research, LLC.

==Screenshots== 


In the following, note that:
*Q02 only shows the set of products checked in Q01 (by using array_filter)
*Q02 also shows "Another product", the text entered into the "Other electronic" field in Q01
*Q04 only shows products from Q02 that were checked (so the array filter cascades)
*Q05 only shows products from Q02 that were not checked in Q02 (using a cascaded array_filter_exclude)


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


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

==Download== 


Click on the following link to download the above example: [[Media:ls2_cascading_array_filter.lss|LS2_cascading_array_filter survey example]].

=Piping/Tailoring Using All Question Types and Attributes= 

==Overview== 


If you are confused about how to name your variables (SGQA vs Qcodes), you are not alone. Although the main documentation describes [[ExpressionScript - Presentation#Access to Variables|how to compose Qcode variable names]], nothing beats seeing it in a working demo. This survey shows how you can access question attributes and responses using the ExpressionScript.


{{Note|For this example, we recommend turning off the built-in HTML editor (or converting it to the pop-up mode) when editing this survey. It can take a minute or more for the HTML editor to render the large HTML reports in edit mode.}}

==Content== 


*Examples of every question type
*All questions types that can use "other" are included so that you can see how that affects variable naming
*Default values for all the question types that accepts defaults
*Tailoring - On- and off-page reports showing all 16 available EM dot notation suffixes.
*These reports show all of the currently entered data (so show you how you could generate your own printable reports for users in lieu of the print-answers screen)
*Proper Qcode and SGQA naming of all variables

==Screenshots== 


This is a huge survey, so we chose not to include screen shots. Instead, please download and play with it.

==Download== 


Click on the following link to download the survey: [[Media:ls2_EM_question_attributes.lss|LS3_EM_question_attributes.lss]]

=Traditional validation, re-envisioned= 

==Overview== 


This demonstrates all the validation types that make use of expressions and how they affect each of the question types that support validation. In many cases, the validation tips start hidden and only appear if a question fails validation criteria (thus also disappearing once the question passes the validation criteria).

==Validation Types Demonstrated== 


#[[QS:Min_num_value_n|min_num_value_n]] - minimum value for an answer
#[[QS:Max_num_value_n|max_num_value_n]] - max value for an answer
#[[QS:Min_answers|min_answers]] - minimum number of answers required
#[[QS:Max_answers|max_answers]] maximum number of answers allowed
#[[QS:Multiflexible_min|multiflexible_min]] - minimum value allowed for an answer (for multiflexi numbers question type)
#[[QS:Multiflexible_max|multiflexible_max]] - maximum value allowed for an answer (for multiflexi numbers question type)
#[[QS:Min_num_value|min_num_value]] - minimum allowed sum across all answers for the question
#[[QS:Max_num_value|max_num_value]] - maximum allowed sum across all answers for the question
#[[QS:Equals_num_value|equals_num_value]] - the sum across all answers for the question must equal this value
#[[QS:Preg_validation|validation]] - this is the regular expression validation for the question - it can apply to individual cells

==Screenshots== 


Using new CSS styles, each validation type shows up a separate tip. If they are shown, they can be hidden via the hide_tip option. The default option is to show them with red font if the question fails the validation criteria, and green if it passes them:


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


A user cannot submit a page with validation errors. He will be immediately warned if he entered wrong information:


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


Validation can be applied to individual cells within an array, such as in this example where regular expression validations ensure that each entry is a properly formatted US phone number including area code.


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

==Download== 


To download the above example, click on the following link: [[Media:LS3_Validation_tests.zip|LS3_Validation_tests.zip]].

=Validation Equations= 

==Overview== 


Sometimes you need custom validation that cannot be achieved using the traditional min/max criteria. For this, you will need to use the em_validation_q and em_validation_sq options which let you construct complex validation equations at the question and subquestion level, respectively.


{{Note|At the subquestion level, we also introduce the "this" variable to make it easy to validate each cell in an array without needing to know its variable name. For more details about it, click here.}}

==EM Features Demonstrated== 


#[[QS:Em_validation_q|em_validation_q]] - this is an equation that determines whether the whole question is valid
#[[QS:Em_validation_q_tip|em_validation_q_tip]] - this is the message to show if the question fails em_validation_q criteria
#[[QS:Em_validation_sq|em_validation_sq]] - this is the equation that determines whether each subquestion (array cell) is valid
#[[QS:Em_validation_sq_tip|em_validation_sq_tip]] - this is the message to show if any of the subquestions is invalid.


In general, when em_validation_sq is used, if any cell is invalid, the background color for that cell turns red to indicate that there is an error.

==Screenshots== 


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


This question ensures that you enter the ages of your children in descending order by applying this validation equation:


<syntaxhighlight lang="php" enclose="div">q1_sq1 >= q1_sq2 && q1_sq2 >= q1_sq3 && q1_sq3 >= q1_sq4</syntaxhighlight>


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


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


In the below example, the validation ensures that no more than 3 questions are answered on any given row by applying this validation equation:


<syntaxhighlight lang="php" enclose="div">(sum(Test_A_1, Test_A_2, Test_A_3, Test_A_4, Test_A_5) <= 3) && (sum(Test_B_1, Test_B_2, Test_B_3, Test_B_4, Test_B_5) <= 3) && (sum(Test_C_1, Test_C_2, Test_C_3, Test_C_4, Test_C_5) <= 3)</syntaxhighlight>


You can also write this as follows, LimeSurvey automatically converting it at run-time to the above-listed expression.


<syntaxhighlight lang="php" enclose="div">(sum(self.sq_A) <= 3) && (sum(self.sq_B) <= 3) && (sum(self.sq_C) <= 3)</syntaxhighlight>


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

==Download== 


To download the survey sample used in the above examples, click on the following link: [[Media:ls2_test_em_sq_validation.lss|ls2_test_em_sq_validation.lss]].

=Subquestion relevance= 

==Overview== 


This shows how array_filter and validation criteria can interact. For validations that apply to sums, only relevant (visible) values are considered.

==EM Features Demonstrated== 


#[[QS:Array_filter|array_filter]]
#[[QS:Array filter exclude|array_filter_exclude]]
#[[QS:Min_num_value|min_num_value]]
#[[QS:Max num value|max_num_value]]
#[[QS:equals_num_value|equals_num_value]]


It also shows dynamic reporting of the numbers of questions answered in the core questions.

==Screenshots== 


Changing the number of visible rows dynamically changes the sum. Marking a subquestion as being irrelevant doesn't clear its value. Rather, if it is irrelevant, its values don't contribute to any equation.


<center>[[File:sqrel1.jpg]][[File:Sqrelver12.png]]</center>


Note what happens when we check the "Fifth subquestion" for the first question '''"Which rows should appear below"'''. Note that the sum for the second "Enter some numbers" question is now 5. Even though subquestion 5 for that question still has the value 14 (e.g., if you un-check the fifth subquestion, you will see the value of 14 again), that value does not contribute to the sum since it is currently irrelevant. All irrelevant data is cleared (NULLed in the database) on submit, but it stays available on the page in case users want or need to change their minds about answers.


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

==Download== 


To download our example, click here: [[Media:ls2_subquestion_relevance.lss|ls2_subquestion_relevance.lss]].

=Using Comma as Radix Separator (Decimal Point)= 

==Overview== 


The ExpressionScript ensures that only valid numbers can be entered into numeric fields. If you enter an invalid number, you will be warned that something is wrong (e.g., in the case of the fruity theme, the whole question is "red-ed").


Note that the numeric values are always converted to using a period as the radix separator within the database. In this way, the statistical analyses will work appropriately.


To change the radix separator, access the [[Text elements]] options located under the [[Survey_settings|Settings]] tab, and look for the [[Text_elements#Survey_text_elements_panel|decimal mark]] functionality.


{{Note|For more information on what a radix separator is, click [https://en.wikipedia.org/wiki/Radix_point|here].}}

==Question Types Using Radix Separator== 


#[[Question type - Numerical input|Numerical input]] <nowiki>[</nowiki>N]
#[[Question type - Multiple numerical input|Multiple numerical input]] <nowiki>[</nowiki>K]
#[[Question type - Array (Numbers)|Array (Numbers)]] <nowiki>[</nowiki>:]
#[[Question type - Array (Texts)|Array (Texts)]] <nowiki>[</nowiki>;], when using the [[QS:Numbers_only|numbers_only]] attribute
#[[Question type - List (Radio)|List (radio)]] <nowiki>[</nowiki>L], when using the [[QS:Other_numbers_only|other_numbers_only]] attribute
#[[Question type - Short free text|Short free text]] <nowiki>[</nowiki>S], when using the [[QS:Numbers_only|numbers_only]] attribute
#[[Question type - Multiple short text|Multiple short text]] <nowiki>[</nowiki>Q], when using the [[QS:Numbers_only|numbers_only]] attribute
#[[Question type - Multiple choice|Multiple choice]] <nowiki>[</nowiki>M], when using the [[QS:Other_numbers_only|other_numbers_only]] attribute
#[[Question type - Multiple choice with comments|Multiple choice with comments]] <nowiki>[</nowiki>P], when using the [[QS:Other_numbers_only|other_numbers_only]] attribute

==Screenshots== 


You may note in the below screenshots that comma can be used as a radix separator.


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

==Download== 


To download the above example, click on the following link: [[Media:ls2_comma_as_radix_separator.lss|ls2_comma_as_radix_separator.lss]].

=Randomization Groups= 

==Overview== 


This survey demonstrates how to make use of the '''random_group''' attribute.


If this attribute is used, each time you start the survey, the question order is randomized. However, once the survey is started, the randomization order remains fixed, even if you change languages.

==Screenshots== 


Let's check together the below example. The first random question on the page will either be Q1 , Q4, or Q7. The second randomized question on the page will either be Q2, Q5, or Q8.


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


Here is the randomization generated the first time I tested this survey.


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


A different randomization was generated the second time I tested the survey.


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


But, when I switched to French (without re-starting the survey), the randomization order remained intact.


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

==Download== 


To download the above example, click on the following link: [[Media:Randomization_Group_Test.lss|Randomization_Group_Test.lss]]

=Randomly Ask One Question Per Group= 

==Overview== 


This survey shows how you can configure a survey to randomly display one question per group. In it, there are 5 groups of 6 questions each. At the outset, in Group 0, five hidden Equation questions, called ask1-ask5, are populated. Each one has the value of {floor(rand(1,6.9999))} in the question text field, which means that the variables ask1-ask5 will each have a value between 1 and 6. Then, each question in the group has a relevance equation like "ask1==N" where N is the Nth question in the group (so the third question in group 1 has the relevance equation "ask1==3").


This survey works equally well in survey-at-a-time, group-by-group, and question-by-question modes. Since the randomization is set in the first group, and that group is effectively hidden (since all of the ask1-ask5 questions are hidden), the randomization stays the same for the subject; but each different subject will have a distinct randomization.

==Features Demonstrated== 


#[[Question type - Equation|Equation question type]]
#Randomization functions
#Conditional (if) function

==Screenshots== 


This is Group0, which uses the [[Question type - Equation|Equation question type]] to select random values from 1 to 6 for each group (except the last group, which has only 4 questions). Note that the "if()" function first checks whether ask1 has already been set, and if so, uses that value. If the value hasn't been set, then it uses a random value to set the value of ask1.


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


This Group shows how the variable (ask4) from Group0 is used to control which question is visible within the fourth group.


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

==Download== 


To download the above survey example, click here: [[Media:limesurvey_survey_55164.lss|Random questions within a group survey example]].

=Randomly Ask A Specific Number Of Questions In A Group (a subset of the questions)= 


{{Alert|This applies only to all random questions from one group and only if the [[General_settings#General_settings_panel|Group by group or All in one]] format is used.}}

==Overview== 


This survey shows how to ask a random subset of questions in a group. For example, show 5 random questions out of 10 questions located within a group.


The survey has one group containing 10 questions. All questions are assigned the same [[QS:Random_group|randomization group name]]. As a result, they will be displayed in a random order on page load. Each question is given a relevance equation that the sum of the "[[ExpressionScript - Presentation#Access to Variables|relevanceStatus]]" of all other questions in the group is less than the number of questions you want to show. Since [[ExpressionScript - Presentation#Access to Variables|relevanceStatus]] is assigned as questions are rendered, this effectively totals the number of preceding questions.


So, in our 5 out of 10 example, the equation for Q1 would be:


<syntaxhighlight lang="php" enclose="div">sum(Q2.relevanceStatus, Q3.relevanceStatus, Q4.relevanceStatus, Q5.relevanceStatus, Q6.relevanceStatus, Q7.relevanceStatus, Q8.relevanceStatus, Q9.relevanceStatus, Q10.relevanceStatus) LT 5</syntaxhighlight>


For Q2, it would be:


<syntaxhighlight lang="php" enclose="div">sum(Q1.relevanceStatus, Q3.relevanceStatus, Q4.relevanceStatus, Q5.relevanceStatus, Q6.relevanceStatus, Q7.relevanceStatus, Q8.relevanceStatus, Q9.relevanceStatus, Q10.relevanceStatus) LT 5</syntaxhighlight>


And so on...

==Features Demonstrated== 


#[[ExpressionScript#Access_to_Variables|relevanceStatus variable]]
#[[QS:Random group|Randomizing]]

==Download== 


To download the above example, click on the following link: [[Media:Random_5_out_of_10.lss|Random 5 out of 10 survey example]].

=Rating User-Entered List of Products= 

==Overview== 


The below example shows how you can ask users to list a set of products that interest them, and then have them rate those products.

==ES Features Demonstrated== 


#'''Tailoring answers''' - when rating products, the labels come from the comment field of the preceding multiple choice question
#'''Tailoring scales''' - many advanced questions options, like scale headings, can also be tailored.

==Screenshots== 


This image shows that even though only products 1,3, and 5 were selected, only those 3 are displayed (using the [[QS:Array_filter|array_filter]] attribute). Moreover, the row labels in the second question are either the product numbers (if nothing is entered into the comment field) or the contents of the comment fields.


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


This image shows how the tailored answers are specified:


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


Here is the Show Logic File for that question, which lets us verify that the conditional logic works as desired (e.g., to see whether there are any syntax errors):


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


The next image shows a group in which you specify a 5 point rating scale (Options 1-5), the title of the scale, and the products you want to rate. The final question shows that each of the parts of the array question can be tailored:


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


The next image shows the logic file view of the last question. As you can observe, the subquestions, answers, and scale headers can be tailored.


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

==Download== 


To download the survey example from above, click on the following link: [[Media:Rating_User-Entered_List_of_Products_Survey.zip|Rating user-entered list of products survey example]].

</translate>

ExpressionScript for developers

2020-04-15T08:51:56Z

Cdorin:

__TOC__

{{Alert|text=Starting 2020, we renamed the Expression Manager to ExpressionScript.}}

This wiki page is meant for the LimeSurvey development team and others wishing to contribute to LimeSurvey. It provides details about how to work with, test, and extend ExpressionScript (ES).

{{Alert|text=Please note that his document is currently incomplete.}}

==Getting Started==

The best way to get started with EM is to:
*Install [https://www.limesurvey.org/about-limesurvey/download the latest version of LimeSurvey]
*Load and play with the ExpressionScript demos (located in /docs/demosurveys of the distribution)
*Navigate through all of the test cases
**To see the ExpressionScript displayed in the configuration toolbar, you must activate first the debug mode from application/config/config.php.
*Read the documentation
**Main user documentation for [[ExpressionScript - quick start guide|ExpressionScript]]
**ExpressionScript [[ExpressionScript HowTos|How Tos]]

==EM Source Code Organization and Purpose==

=== ExpressionScript Engine (EM) ===

Implements a [https://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] in PHP and JavaScript which let you create variables and securely expose a specified set of pre-defined functions.

==== Location ====

* Version 1.92: /classes/expressions/ExpressionScript Engine.php
* Versions 2.0 and 3.0: /application/helpers/expressions/em_core_helper.php

==== Recursive Descent Parser (all variables and functions starting with ''RDP_'') ====

* This is the core of the EM, a compiler which builds and evaluates the parse tree for the expression
* Unless you are an expert in compiler theory, you should not touch the RDP_ code.

==== API Functions to the RDP ====

* RegisterFunctions - an interface to add external functions to EM
* sProcessStringContainingExpressions() - splits string on expressions, evaluates each, then joins together the parts
* ProcessBooleanExpression() - evaluates whether an equation (not surrounded by curly braces) is true
* Get*() - returns information about the most recently processed expressions

=== LimeExpressionScript Engine (LEM) ===

This centralizes the integration of LimeSurvey with EM.

==== Location ====

* Version 1.92: /classes/expressions/LimeExpressionScript Engine.php
* Versions 2.0 and 3.0: /application/helpers/expressions/em_manager_helper.php

==== Navigation Functions ====

These process the current responses, update the database, find the next relevant set of questions, and create the metadata needed to render those questions:
* NavigateForwards()
* NavigateBackwards()
* JumpTo()
* GetLastMoveResult()

==== Initialization Functions ====

* StartSurvey() - initializes the survey, setting all variable mappings
* setVariableAndTokenMappingsForExpressionScript Engine() - post-processes CreateFieldMap() to create metadata needed for all variables and token values
* _CreateSubQLevelRelevanceAndValidationEquations() - processes advanced question attributes such as array_filter, min_answers, and min_value
* ProcessAllNeededRelevance() - computes the relevance results (and JavaScript) for all applicable questions
* _ProcessGroupRelevance() - computes the relevance of a group based upon its own relevance criteria and the status of the questions it contains.

==== Functions to Generate Tailored Content ====

* StartProcessingPage() - called at beginning of each page
* StartProcessingGroup() - called for each group on a page
* FinishProcessingGroup() - collects all tailoring for this group so can render appropriate JavaScript
* FinishProcessingPage() - completes the EM-related processing, and serializes LEM into $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* GetRelevanceAndTailoringJavaScript() - collects all relevance, validation, and tailoring logic and generates ExprMgr_process_relevance_and_tailoring() JavaScript function

==== Response Management ====

*ProcessCurrentResponses() - validates and processes the $_POSTed responses
*_UpdateValuesInDatabase() - saves values to database, including NULLing irrelevant values

==== Caching ====

LEM tries to avoid calling the Initialization functions each page, storing state in $_SESSION<nowiki>[</nowiki>'LEMsingleton']
* SetDirtyFlag() - when called, tells LEM to force a rebuild of the Initialization functions (e.g. of admin has added/removed/updated any questions, groups, conditions, or defaults)
* SetSurveyId()- calls SetDirtyFlag if the user wants to work with a different survey from the one that is cached
* SetEMLanguage() - calls SetDirtyFlag() if the user starts to use a language different from the cached one

==== Validation Functions ====

* _ValidateSurvey() - validates the entire survey by calling _ValidateGroup()
* _ValidatGroup() - validates a group and returns its status by calling _ValidateQuestion() on all of its questions
* _ValidateQuestion() - validates a question, determining whether it is relevant, hidden, or fails any validation and/or mandatory criteria

===EM-related JavaScript===

*Location
**Version 1.92: /classes/expressions/em_javascript.js
**Versions 2.0 and 3.0: /scripts/admin/expressions/em_javascript.js
*Purpose - contains all of the custom javascript needed for EM

====JavaScript equivalents of PHP functions====

About 20 functions from phpjs.org

====Core Functions====

*LEManyNA() - checks whether any of the variables are irrelevant
*LEMval() - retrieves the value for any variable, or its metadata (via the dot notation syntax)
*LEMsetTabIndexes() - ensures that the tab sequence will act as expected even if input elements change visibility.

===EM-related Test Cases===

*Location
**Version 1.92: /classes/expressions/test/*.php
**Versions 2.0 and 3.0: /application/views/admin/expressions/*
*Purpose
**'''Available Functions''' - runs EM::ShowAllowableFunctions to display functions and syntax from EM->RDP_ValidFunctions
**'''String Splitter''' - runs EM::UnitTestStringSplitter() to show how it parses strings with curly braces
**'''Tokenizer''' - runs EM::UnitTestTokenizer() to show how EM detects and categorizes tokens (e.g. variables, string, functions, operators)
**'''Unit Tests of Isolated Expressions''' - runs EM::UnitTestEvaluator() for unit tests of each of ExpressionScript's features (e.g. all operators and functions). Color coding shows whether any tests fail. Syntax highlighting shows cases where ExpressionScript properly detects bad syntax.
**'''Unit Tests of Expressions Within Strings''' - runs LEM::UnitTestProcessStringContainingExpressions() to show how ExpressionScript can process strings containing one or more variable, token, or expression replacements surrounded by curly braces.
**'''Unit Test Dynamic Relevance Processing''' - runs LEM::UnitTestRelevance() to show how questions and substitutions should dynamically change based upon values entered.
**'''Preview Conversion of Conditions to Relevance''' - runs LEM::UnitTestConvertConditionsToRelevance() to show relevance equations for all conditions in the database, grouped by question id
**'''Bulk Convert Conditions to Relevance''' - actually performs the conversion, saving the generated relevance equations (while retaining the original conditions)
**'''Test Navigation''' - unit tests LEM::NavigateForwards() for the selected survey, generating the following information based upon the selected debugging options:
***Detailed Timing - shows low-level timing information for each part of EM (e.g. to examine duration of database calls)
***Validation Summary - shows one line per group and question, showing its relevance equation, and indicating whether it was irrelevant, hidden, mandatory and/or failed validation criteria. Also shows the generated SQL per navigation step to update the database
***Validation Detail - shows extra details per question, including
****Validation Tip, Equation, JavaScript equivalent of the Equation
****Lists of subquestions; which are relevant; and which are unanswered
****List of array filters applied, by subquestion
***Pretty Print Syntax - syntax highlights all of the equations so that you can see errors, and also click on variable names to jump to those questions and edit them.
**'''Show Survey Logic File''' - generates the logic file which is available via the "QA" buttons in the admin console.

==How EM Works==

===What is an Expression?===

Anything surrounded by curly braces is an Expression, with two exceptions:
*if there is whitespace after the opening brace or before the closing brace, it is ignored.
**The EM can ignore in this way the embedded JavaScript.
**So, if you have JavaScript that might be parsed by EM, make sure to add a space or newline after the opening brace.
*Escaped curly braces are ignored (e.g. <span style='color:#F00'>'''\{'''</span> and <span style='color:#F00'>'''\}'''</span>)

Note that EM does support Expressions within strings. Moreover, Expressions can contain nested strings, but not nested expressions. So, the following red sections are valid Expressions and will cause substitions to occur within the containing strings.
*<img src="images/mine_<span style='color:#F00'>'''{Q1}'''</span>.png">
*<img src="images/mine_<span style='color:#F00'>'''{if(Q1=="Y",'yes','no')}'''</span>.png">
*<img src="images/mine_<span style='color:#F00'>'''{if(Q1=="Y",'single quote with {nested braces}',"double quote with {nested braces}")}'''</span>.png">

===What does EM do with text containing expressions?===

#A regular expression divides the source line into STRING and EXPRESSION tokens
#Each EXPRESSION is parsed by ExpressionScript Engine, a [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser].
##If there are syntax errors, EM returns an HTML string that syntax-highlights the equation and puts red-lined boxes around syntax errors
##If there are no syntax errors, EM returns the result of evaluating the expression
#EM re-joins the STRING and EM-evaluated EXPRESSION parts.
#EM optionally appends the translation activity to structures used by GetRelevanceAndTailoringJavaScript().

===How can we be sure that EM accurately parses the equations?===

EM was originally written in 1999-2000 by Dr. Tom White (TMSWhite) for a different project (Dialogix) in Java, using [http://en.wikipedia.org/wiki/JavaCC JavaCC], an open source compiler compiler (parser generator). That Java-based project has been in production for over a decade, and has been fully vetted for unit and integration tests.

Since there is no production-grade parser generator for PHP and JavaScript (although [http://www.antlr.org/ Antlr] is coming close), TMSWhite created a custom [http://en.wikipedia.org/wiki/Recursive_descent_parser recursive descent parser] for LimeSurvey. To ensure its accuracy, EM's logic is based upon the JavaCC source code for Dialogix. The JavaCC syntax mirrors the functionality needed for a recursive descent parser. JavaCC happens to build a state-based compiler, which is a little more efficient than a recusive descent parser. However, state-based compilers are impossible to read, understand, or expand without JavaCC-like source code, so it did not make sense to try to port the JavaCC output directly to PHP.

Futhermore, there are comprehensive unit and integration test suites for EM. These make it easy to validate the accuracy of the EM system. Each test suite includes dozens to hundreds of test cases, and it is trivial to add addition test cases.

===How does the Recursive Descent Parser work?===

EM must do the following:
#Tokenize the expression - separating strings, words (variable names vs. functions), and punctuation; and categorizing the types of each.
#Analyze the tokens to build a parse tree, checking for syntax errors along the way.
#Return the result of evaluating the expression (using PHP) (or return syntax-highlighted HTML if there are syntax errors).
#Create a safe JavaScript equivalent of the expression so that expressions can be dynamically re-computed client-side.
#Determine which variables are used in each expression (so can make sure they are available client-side).

===How does EM integrate into LimeSurvey?===

The LimeExpressionScript Engine (LEM) class manages the integration of EM into LimeSurvey. LEM must:
#Initialize all of the variables needed by LimeSurvey (e.g., for TOKENS, INSERTANS, and templatereplace())
#Know which Group and Question are being processed
#Record the results and metadata about all of the text that LimeSurvey asks it to process
#Output static HTML that reflects the results of that processing
#Output JavaScript that lets those results be dynamically re-computed if values on the page change.

==Extending EM==

=== Adding Functions ===

When you add a function that does not exist in PHP, add it also to the body of '''em_core_helper.php'''

''FIXME'': Eventually we should separate out such add-on functions into their own php file.

Functions are stored in LimeExpressionScript Engine::amValidFunctions[]. Some existing examples are:
<syntaxhighlight lang=PHP>
'abs' => array('abs', 'Math.abs', 'Absolute value', 'number abs(number)', 'http://www.php.net/manual/en/function.checkdate.php', 1),
'if' => array('exprmgr_if', 'LEMif', 'Excel-style if(test,result_if_true,result_if_false)', 'if(test,result_if_true,result_if_false)', '', 3),
'max' => array('max', 'Math.max', 'Find highest value', 'number max(arg1, arg2, ... argN)', 'http://www.php.net/manual/en/function.max.php', -2),
'substr' => array('substr', 'substr', 'Return part of a string', 'string substr(string, start <nowiki>[</nowiki>, length])', 'http://www.php.net/manual/en/function.substr.php', 2,3)
</syntaxhighlight>

The syntax for each function is:
<syntaxhighlight lang=PHP>
function => array( detail_1, detail_2, detail_3, detail_4, detail_5, detail_6 )
</syntaxhighlight>

The ''details'' which must be included in the array are:

# PHP function name - this is the PHP function that will be called for that func.
# JavaScript function name - this is the JavaScript function that will be called for that function
# Meaning - this is a short description of what the function does
# Syntax - this shows the valid syntax for the function
# Reference - this is an optional URL showing more details about the syntax (e.g. a link to the PHP documentation)
# Number of required arguments
#* Multiple values are allowed at the end of the array. For example, substr() above can take 2 or 3 arguments
#* Negative values mean that the function accepts a variable number of arguments
#* Negative values less than -1 mean that the function requires at least abs(N)-1 arguments (so -2 means it requires at least 1 argument)

If you add a function that does not exist in JavaScript, then add it to the body of '''em_javascript.js'''

===Adding Test Cases===

Please do! The testing frameworks are solid. You just need to add more tests following the examples in the code.

Make sure to add Unit tests for new functions to UnitTestEvaluator

* Syntax is ExpectedResult~Expression, such as:
* 212~5 + max(1,(2+3),(4 + (5 + 6)),[[]],[[7 + 8) + 9),( (10 + 11), 12),(13 + (14 * 15) - 16) )

When your test case should return an error, use NULL as the expected value, like this:

* NULL~four * / seven
* NULL~(5 + 7) = 8

[[Category:Development]]

ExpressionScript examples

2020-04-15T08:47:46Z

Cdorin:

<languages />
<translate>

__TOC__


{{Note| '''Please help extending this article''' by adding your own examples. This will help others getting started using the Expression Script.}}

=Structure= 


The first part of the article will describe what Expressions can be used for and where to find/add an Expression. The second part provides examples on how to use Expression.

=Categories of Expressions= 


LimeSurvey uses Expressions for the following purposes:
* [[ExpressionScript_examples#Relevance|Relevance]]
* [[ExpressionScript_examples#Validation|Validation]]
* [[ExpressionScript_examples#Text output|Text output]]
* [[ExpressionScript_examples#Answers storing|Answers storing]]

==Relevance== 


'''Purpose: Hiding question groups/questions'''


Relevance controls whether a question group or question is shown or hidden. If the result of the Expression is "true" (i.e. 1), the element will be shown. Otherwise (if the result of the Expression is "false" (i.e. 0)), the element will be hidden.


{|class="wikitable"
!Type!!Shows/hides!!Where to find!!Screenshot
|-
|Question group Relevance||question group||Create/Edit question group -> "Relevance equation:"||[[File:Group relevance equation screenshot.png|30px]]
|-
|Question Relevance||question||Create/Edit question -> "Relevance equation:"||[[File:Question relevance equation screenshot.png|30px]]
|-
|Subquestion Relevance||subquestion||Edit subquestions -> "Relevance equation:"||[[File:Subquestion relevance equation screenshot.png|30px]]
|-
|}

==Validation== 


'''Purpose: Validate input/actions on questions/subquestions/answers'''


Validation controls whether the respondent's input into a question or action is valid or not. If the result of the expression is "true" (i.e. 1), the "good" class will be applied to the element and validation message. Otherwise, if the result of the expression is "false" (i.e. 0)), the "error" class will be apllied to the element and validation message. You can declare a style for these classes in the '''template.css'''.


{|class="wikitable"
!Type!!Validates!!Where to find!!Screenshot
|-
|Question Validation||question||Create/Edit question -> "Logic tab" -> "Question validation equation"||[[File:Question validation equation.png|30px]]
|-
|Subquestion Validation||subquestions||Create/Edit question -> "Logic tab" -> "Subquestion validation equation"||[[File:Subquestion validation screenshot.png|30px]] ‎
|}

==Text output== 


'''Purposes: (Do something) and write out some text'''


An expression can be used to write out some text. For example, you can test or calculate something and specify the output depending on the result of the test or calculation. It can also be used to insert the question text, answers, question types, ... of a question used before the Expression is used. Text output can be used everywhere where a text is shown and can return every kind of results.


{|class="wikitable"
!Use Case!!Description
|-
|Micro tailoring||Adjust a text, e.g., write "Mr" or "Mrs" depending on a gender question asked before
|-
|Calculation||Calculate a value and write it out, e.g., "Your family income is xxx"
|-
|Reference||Insert a text from an element, e.g., "Your name is xxx. How old are you?"
|}

==Answers storing== 


'''Purposes: (Do something,) (write out some text) and store something in the database'''


[[Question type - Equation|The Equation Question Type]] can be used to store something in the database. You can do something with an Expression, show the Equation question (which is similar to a [[Question type - Text display|text display]]) and store the result of the Expression in the database. It stores the answer into the responses table. Then, the result can be used within the statistics feature or it can also be imported into one of the formats provided by the LimeSurvey export functionality.

=Examples for Expressions= 

==Insert an answer from a previous question== 


{| class="wikitable"
|Purpose||Insert an answer from a previous question
|-
|Type||Reference
|-
|Example||Question one (question code "Q00"): What city do you live in? <br /> Question two (question code "Q01") How long have you lived in CITY? <br /> To do: The answer from question one should be used instead of "CITY" from the second question.
|-
|Expression||{QOO}
|-
|Description|| The answer provided in Q00 replaces the Q00 field from the second question
|-
|Steps||Create/Edit question two <br /> Insert "How long have you lived in {QOO} (years)?" into the question text field
|-
|colspan="2" align="center"|[[File:Simple expression city name.png]]
|}

==Using hidden equation question to autofill an answer== 


'''Problem:'''
Imagine you have two questions Q1 and Q2. Q1 asks respondents for their age. Q2 divides respondents into three groups: age is below 20 years, age is 20, age is greater than 20.
So, Q2 should make use of the values "1", "2", "3", which correspond to the above conditions. Also, we should not forget to make Q2 invisible (the question will not be displayed in the survey, but the values will be via the "background process" within the responses table).


'''To fill in the database using the Equation question type:'''
* First, create a question with code Q1 as a numerical input question.
* Then create another question with code Q2 as an equation question.
* In the "Display settings" tab chapter of Q2:
** set "Always hide this question" field as "On"
** type in "Equation" field the expression:
<pre>Q2=if(Q1.NAOK < 20, "1", if(Q1.NAOK > 20, "3", "2"))}</pre>

==Create a summary page using placeholders== 


This tutorial demonstrates how you can create an overview at the end of the survey, listing all questions and answers via [http://manual.limesurvey.org/ExpressionScript#Access_to_Variables ExpressionScript placeholders].
It also shows how to limit such an overview to answered questions only.


Our example can be downloaded from here: [[Media:Limesurvey_Expression_Manager_Placeholder_Demo_Survey.lss|Survey placeholders survey example]].


'''''Question types being used here:'''''


'''1. Single choice questions / single text/numeric questions'''
*List (dropdown)
*List (radio) [L]
*Yes/No [Y]
*Long free text [T]
*Short free text [S]
*Numerical input [N]
*Equation [*]


'''2. Question with subquestions'''
*Multiple short text [Q]
*Multiple choice [M]
*Array [F]
*Array (Yes/No/Uncertain) [C]
*Array (10 point choice) [B]


'''3. Questions with 2 scales'''
*Array dual scale [1]


'''4. Questions with X and Y scales'''
*Array (Numbers) [:]


'''5. Mask questions'''
*Text display [X]


In this simple example, our overview will be a simple list with:


- ''Question text:'' User's answer

===Single choice questions / single text/numeric questions=== 


For all these question types, Limesurvey will store a single response:


*List (dropdown)
*List (radio)
*List with comment
*5 point choice
*Yes/No
*Short free text
*Long free text
*Huge free text
*Numerical input
*Equation
*Date
*Gender


Assuming the question code of the question is q1, we can reference the question text and answer using:


- {q1.question}: {q1.shown}


Example:


- How old are you?: 25


If you want to check whether that question was answered you can put an IF statement around your output:


<pre>{if(!is_empty(q1),join("- ",q1.question,": ",q1.shown),"")}</pre>


This "translates" to: IF question with code q1 is not empty, output "- " AND the question text AND ": " AND the answer text (the join() function joins elements as a new string; ELSE: output nothing ("" means empty string).

===Question with subquestions=== 


For all these question types LimeSurvey uses subquestions:


*Multiple short text
*Multiple choice
*Multiple choice with comments
*Array
*Array (5 point choice)
*Array (10 point choice)
*Array (Yes/No/Uncertain)
*Array (Increase/Same/Decrease)
*Array by column


Assuming the question code of the question is q2 and the subquestions are numbered SQ001, SQ002, (auto-numbering done by LimeSurvey), we can reference the question text and answer using:


- {q2_SQ001.question}: {q2_SQ001.shown}


- {q2_SQ002.question}: {q2_SQ002.shown}


For multiple choice questions it makes sense to now show the text of the ticked subquestion but to show a Y for each selected option:


- {q2_SQ001.question}: {q2_SQ001}


- {q2_SQ002.question}: {q2_SQ002}


...


Note that currently it is not possible to output the question text of questions with subquestions, see [http://bugs.limesurvey.org/view.php?id=8858 this feature request].

====Example 1 (assuming question type is multiple choice)==== 


- Do you know these car brands?


-- Mercedes: Y


-- Audi: N


-- Volvo: Y


If you want to output checked items only you can put an IF statement around your output and check for the checkbox value:


<pre>{ if( q2_SQ001=="Y", join( "- ", q2_SQ001.question, ": ", q2_SQ001.shown ), "" ) }</pre>


Use the <i>listifop</i> function if you want to output a list of only the selected items, eg: Mercedes, Volvo


<pre>{ listifop( 'value', '==', 'Y', 'question', ', ', that.q2.sgqa ) }</pre>


Where  <small>that.q2</small>  expands to all of q2's subquestions. See [[ExpressionScript - Presentation#The_reserved_.22this.22.2C_.22self.22.2C_and_.22that.22_variables|self, this and that]] for more detail.


</br>

====Example 2 (assuming question type is Array (10 point choice))==== 


- Please rate the quality of the car brands below on a scale from 1=very bad to 10=very good?


-- Mercedes: 7


-- Audi: 9


-- Volvo: 9


If you want to output rated items only you can put an IF statement around your output and check if the current sub question was answered by using:


<pre>{ if( ! is_empty( q3_SQ001 ), join( "- ", q3_SQ001.question, ": ", q3_SQ001.shown ), "" ) }</pre>


Use the <i>listifop</i> function if for example you want to only output a list of the selected items greater than eight, eg: Audi / Volvo


<pre>{ listifop( 'value', '>', 8, 'question', ' / ', that.q3.sgqa ) }</pre>


</br>

===Question with two scales=== 


{{Note|This applies to the dual scale question type only.}}


Let's assume that the following codes are being used:
*Question code: q4
*Subquestion codes: SQ001, SQ002, ...
*Answer codes scale 1: A1, A2, ...
*Answer codes scale 2: B1, B2, ...


{{Note|To refer to the result of a certain subquestion on a certain scale, you need to use QuestionCode . '_' . SubQuestionCode . '_' . ScaleID. '''Note that "ScaleID" is 0 for the first scale and 1 for the other!'''</br> Example for referring to the answer of the third subquestion and second scale: q4_SQ003_1 - Question 4, subquestion 3, second scale.}}


Let's output the results for both scales and the first two subquestions:


- {q4_SQ001_0.question}: {q4_SQ001_0.shown} / {q4_SQ001_1.shown}


- {q4_SQ002_0.question}: {q4_SQ002_0.shown} / {q4_SQ002_1.shown}


To output the subquestion text, you need to add the scale ID to the placeholder (though the texts are the same for both scales). So instead of {q4_SQ001.question} we have to use {q4_SQ001_0.question} or {q4_SQ001_1.question}.


If you want to export/display the results of subquestions with at least one answer only, use this syntax for each subquestion:


<pre>{if(count(q4_SQ001_0,q4_SQ001_1)>0,join("- ",q4_SQ001_0.question,": ",q4_SQ001_0.shown," / ",q4_SQ001_1.shown),"")}</pre>

===Question with X and Y scales=== 


This applies to all matrix questions which allow an answer for every cell (not just every row as shown previously):
*Array Texts
*Array Numbers


Assumed codes used:
*Question code: q5
*Subquestion codes: SQ001, SQ002, ...
*Answer codes: A1, A2, ...


To refer to the result of a certain subquestion from a certain column, you need to use QuestionCode . '_' . SubQuestionCode . '_' . AnswerCode. Example for referring to the answer of the third subquestion and second column: q5_SQ003_A2.


Let's output the results for columns 1-3 of the first two subquestions:


- {q5_SQ001_A1.question}: {q5_SQ001_A1.shown} | {q5_SQ001_A2.shown} | {q5_SQ001_A3.shown}


- {q5_SQ002_A1.question}: {q5_SQ002_A1.shown} | {q5_SQ002_A2.shown} | {q5_SQ002_A3.shown}


Since for these question types each cell (combination of X axes and Y axes) equals one answer option, a test for existing data needs to be done for each cell. Example:


<pre>{if(!is_empty(q5_SQ001_A1),join("- ",q5_SQ001_A1.question,": ",q5_SQ001_A1.shown),"")}</pre>


{{Note|To output the subquestion text you need to add the answer code to the placeholder (though the texts are the same for all answer options). So instead of {q5_SQ001.question} we have to use {q5_SQ001_A1.question} or {q5_SQ001_A2.question}.}}

==Hide question if answer from previous question is empty== 


{|class="wikitable"
|Purpose||Hide question if answer from previous question is empty
|-
|Type||Question Relevance
|-
|Example||Question one: question code "name", question text "What's your name?" <br /> Question two: question text "{name}, how old are you?" <br /> To do: Hide question two if the textfield of question one is empty
|-
|Expression||!is_empty(name)
|-
|Description||is_empty() determines whether a variable is considered to be empty. The "!" negates the result. So if the variable is not empty the Expression will be true and the question is shown
|-
|Steps||Create/edit question two <br /> Insert "!is_empty(name)" into "Relevance equation:"
|-
|Sample File||[[Media:Hide_question_if_empty_question_group.zip|Hide_question_if_empty_question_group.zip]]
|-
|colspan="2" align="center"|[[File:Hide question if empty 1.png]][[File:Hide question if empty 2.png]]
|}

==Hide question group if answer from previous question is Yes or No== 


{|class="wikitable"
|Purpose||Hide question group if answer from previous question is Yes or No
|-
|Type||Question group Relevance
|-
|Example||Page one, Question Group one, Question one: question code "PET", question text "Do you have a pet?" -Yes -No <br /> Page two, Question Group two: Title "About your pet(s)" <br /> To do: Show/Hide question group two if answer from question one is Yes/No
|-
|Expression||PET == "Y"
|-
|Description||PET is the question code for the question you want to check the answer. If you don't use a suffix EM will use "Qcode.code". So you compare the answer code from the PET question to the value "Y". If the participant answers "Yes" the Expression is true and the question group "About your pet(s)" will be shown.
|-
|Steps||Create/edit question group two <br /> Insert "PET == "Y"" into "Relevance equation:"
|-
|Sample File||[[Media:Hide question group if answer from previous question is Yes or No.zip|Hide_question group_if_answer_from_previous_question_is_Yes_or_No.zip]]
|-
|colspan="2" align="center"|[[File:Hide question group if answer from previous question is Yes or No 1.png]][[File:Hide question group if answer from previous question is Yes or No 2.png]]
|}

==Display value of a multiple answer input question field== 


{|class="wikitable"
|Purpose||Display value of a multiple answer input question field
|-
|Type||Reference
|-
|Example||Question one: question code "AskChildAge", question text "How old are your children?". Subquestions codes -Child1 -Child2 -Child3 - ChildXXX <br /> Question two: question code "ReportChildAge" question text "About your first child: - CHILD1 is AGE1."
|-
|Expression||{AskChildAge_Child1.question}, {AskChildAge_Child1.value}
|-
|Description||You want to use the value of a subquestion in a following question. You can access the subquestion value with this kind of expression: QcodeQuestion_QcodeSubquestion.value
|-
|Steps||Create/edit the second question <br /> Insert this text in the description: "About your first child: - {AskChildAge_Child1.question} is {AskChildAge_Child1.value}."
|-
|Sample File||[[Media:Display_value_of_a_multiple_answer_input_question_field.zip|Display_value_of_a_multiple_answer_input_question_field.zip]]
|-
|colspan="2" align="center"|[[File:Display value of a multiple answer input question field 1.png]]
|}

==Validate number of boxes ticked per row for an "Array (Numbers) Checkbox" question== 


{|class="wikitable"
|Purpose||Validate number of boxes ticked per row
|-
|Type||Validation
|-
|Example||Question of type "Array Numbers (Checkbox Layout)"
|-
|Expression||sum(...)
|-
|Description||(sum(Test_A_1, Test_A_2, Test_A_3, Test_A_4, Test_A_5) <= X) determines whether at least X checkboxes in row A are checked. <br />If you want to check all three rows (A, B, C), you can connect the expression using "&&": <br />(sum(Test_A_1, Test_A_2, Test_A_3, Test_A_4, Test_A_5) <= X) <br />&& (sum(Test_B_1, Test_B_2, Test_B_3, Test_B_4, Test_B_5) <= X) <br />&& (sum(Test_C_1, Test_C_2, Test_C_3, Test_C_4, Test_C_5) <= X)
|-
|Steps||Create/edit question of type "Array Numbers (Checkbox Layout)".<br /> Insert the above expression into "Question validation equation" at the advanced question settings (you might have to adjust variable namings!).
|-
|Sample File||[[Media:limesurvey_survey_53654.lss|Validate number of boxes ticker per row for an Array (Numbers) Checkbox.lss]]
|-
|colspan="2" align="center"|[[File:Validate number of boxes ticker per row for an Array (Numbers) Checkbox 05.png]][[File:Validate number of boxes ticker per row for an Array (Numbers) Checkbox 1.png]]
|}

==Calculate difference between two dates== 


{| class="wikitable"
|Purpose||Calculate difference between two dates
|-
|Type||Relevance / Equation question type / Validation
|-
|Example||Question one (date/time, code: DOB): What is your date of birth? <br /> Question two (date/time, code: datetoday): What is the date today? <br /> Question three (boilerplate): You are XXXX days old. <br /> To do: Calculate and display the number of days between the date given in question 1 and the question 2.
|-
|Expression||{(strtotime(datetoday)-strtotime(DOB))/60/60/24}<br>
|-
|Description|| strtotime calculates the number of seconds between the 1st of January 1970 and the given date. The above expression calculates the number of seconds between the two given dates. The term "/60/60/24" just calculates the number of days from the number of seconds. <br /> Instead of asking for the "datetoday", you can also use strtotime('now') or simply time(), which directly returns the number of seconds from January 1970 until now (i.e. the time the survey was taken). Thus you could quickly figure out the age of a person in years with the equation {(time() - strtotime(DOB)) / 60 / 60 / 24 / 365.25} In any of these cases, it is critical that the date is entered in a proper format, otherwise the strtotime() function will not work right.
|-
|Steps||Create two date questions (for the date of birth and for today's date) and a boilerplate question. <br /> In the question text of the boilerplate question insert: "On {datetoday} you were {(strtotime(today)-strtotime(dob))/60/60/24} days days old." <br /><br /> Please note: The function strtotime can work with MANY but not all date formats. If you run into problems set your survey's date format to mm/dd/yyyy or yyyy-mm-dd or dd.mm.yyyy"
|-
|Sample File||[[Media:TestSurvey_Working_with_Dates.zip|Date_difference.zip]]
|-
|colspan="2" align="center"|[[File:Date_difference_example.png]]
|}

==Using ExpressionScript for Assessments== 


Here comes another example on how to use the ExpressionScript with [[Question type - Array|Array type questions]] and assessments:</ br>


Let's say you have 2 array questions and you want to save the results of the calculation data to your database. It is actually simple, you will need to create and test your arrays and submit a dummy response to see if it works and gives you the results in the completed page.


'''Implementation details:'''
*add a question of type equation
*add the following line assuming that Q1 is your array question code while Q2 is the second one:
** <pre>{sum(Q1_SQ001.value,Q2_SQ001.value)}</pre>


Note that SQ001 is the default code for any subquestion. If you change the subquestion code, adjust the equation above accordingly.

==Using em_validation_q in array== 


You can use the [[QS:Em_validation_q|question validation equation]] to control an array with any condition.


'''Implementation details:'''
* for the first array : array of single choice
** Question code is ARRAY
** Sub question code are SQ01,SQ02,SQ03 and SQ04
** update the Whole question validation equation and put <pre>!is_empty(ARRAY_SQ01) and !is_empty(ARRAY_SQ03) </pre>
* for the second array : array of text
** Question code is ARRAYTEXT
** Sub question at Y axis code are SY01,SY02,SY03, and SY04
** Update the Whole question validation equation and put <pre>count(self.sq_SY01 >= 1) and count(self.sq_SY03 >= 3)</pre>
</translate>

ExpressionScript How-tos

2020-04-15T08:29:08Z

Cdorin:

<languages />
<translate>

__TOC__

=Overview of what has been previously explained= 


If you have followed so far the structure of the LimeSurvey manual, it means that you already the [[ExpressionScript - Presentation#Key_Definitions|LimeSurvey terminology]]. Next, we covered expressions and variables in order to learn how to enhance our surveys. In the next part, we moved to the types and meanings of [[ExpressionScript - Presentation#Syntax Highlighting|syntax highlighting]] to learn how to correct syntax errors.


With these basic notions covered, we could move towards examples and explaining how expressions work within LimeSurvey.

=Syntax Highlighting= 


The following screenshots give examples, but do not show the values of the tooltips. A tooltip is an informative box which is displayed whenever you hover the mouse over any bold colored words.


Because of this syntax highlighting, it is very easy to compose correct expressions, even the ones that are complicated. Although the LimeSurvey team plans to try to build an Expression Builder GUI, you can use the existing syntax-highlighting to quickly identify and fix typos. You can also use the tooltips to validate the accuracy of your expressions (e.g., confirm you have selected the desired variable(s)).


In each of the examples, there are three columns:
#Source - this is the raw text that you would enter into the LimeSurvey question field
#Pretty Print - this is the syntax-highlighted equivalent of what you entered
#*Note that Expressions are shown with a tan background, but not surrounded by curly braces in this highlighting.
#*Since EM supports recursive substitution, showing curly braces in the highlighting would cause syntax errors
#Result - this is the output generated when EM processes the source
#*Everything that can be properly substituted is
#*Expressions with errors are shown in-line, with syntax highlighting. Errors are surrounded by a red-lined box.

==Proper Syntax== 


You may find below examples of proper syntax:
#Values: shows that known variables are color coded according to whether are set on the current page. Old-style INSERTANS:xxxx gets its own color-coding style
#Question Attributes: shows that dot notation can access some properties of questions
#Math: shows that basic and complex calculations are supported
#TextProcessing: shows some of the available text-processing functions
#Dates: shows two of the available date-related functions
#Conditional: shows the usage of the if() function. The choices can be nested.
#Tailored paragraph: you can completely customize a report based upon prior values
#EM processes within strings: shows that it can do substitutions within strings. This example generates a tailored image name.
#EM doesn't process curly braces like these: shows that if the curly braces are escaped, or there is a white space between the expression and the curly braces, ES ignores the expression.


<center>[[File:em-syntax-highlighting-1-v2.jpg]]</center>

==EM Syntax Containing Errors== 


Here are examples of common errors when typing ES expressions. Note that the tooltips provide additional information.
#Inline Javascript that forgot to add spaces after curly brace
#*Since "document.write" appears right after a curly brace, EM thinks it is an expression, and red-boxes "document" and "write" since they are undefined variable and functions, respectively
#Unknown/Misspelled variables, functions and operators
#*Here we forgot that we are using the variable name "gender" instead of "sex", but EM catches that error. It also red-boxes '++', since that is not a supported operator.
#Warns if use = instead of eq, or perform value assignments
#*Note that the '=' and '+=' are in red text instead of black. If you hover the mouse over them, you will see warnings that you are assigning a value.
#Wrong number of arguments for functions
#*if() takes 3 arguments, but it has been given 4, so hovering over the red-boxed "if" will explain the error and show the supported syntax
#*sum() takes an unlimited number of arguments, but we had a trailing comma before the closing parentheses, so that is red-boxed
#Mismatched parentheses
#*This is one of the most common errors when writing expressions.
#*This shows two examples of missing closing parentheses, and one example of having one too many closing parentheses.
#Unsuported syntax
#*If you use an operator or punctuation that ES does not support, it will red-box it.
#Invalid assignments
#*Some variables are readWrite and can have their values changed. Others are read-only.
#*If you try to change the value of a read-only variable, you can't. EM will red-box the attempt.
#*If you try to assign a value to an equation or a string, you will also get an error


<center>[[File:em-syntax-highlighting-errors-v2.jpg]]</center>

=="Live" examples of Syntax Highlighting with active tooltips== 


<table border="1">
<tr><th>Source</th><th>Pretty Print</th><th>Result</th></tr><tr><td><b>Here is an example of OK syntax with tooltips</b><br>Hello {if(gender=='M','Mr.','Mrs.')} {surname}, it is now {date('g:i a',time())}. Do you know where your {sum(numPets,numKids)} children and pets are?


</td><td><b>Here is an example of OK syntax with tooltips</b><br>Hello <span style="background-color: #eee8aa;"><span title="Excel-style if(test,result_if_true,result_if_false); if(test,result_if_true,result_if_false)" style="color: blue; font-weight: bold">if</span>(<span title="[java61764X1X5][G:2][Q:110]: What is your gender (male/female)?; value=M" style="color: green; font-weight: bold">gender</span> == <span title="" style="color: gray">'M'</span>,<span title="" style="color: gray">'Mr.'</span>,<span title="" style="color: gray">'Mrs.'</span>)</span> <span style="background-color: #eee8aa;"><span title="[java61764X1X1][G:1][Q:20]: What is your last/surname?; value=Smith" style="color: green; font-weight: bold">surname</span></span>, it is now <span style="background-color: #eee8aa;"><span title="Format a local date/time; string date(format [, timestamp=time()])" style="color: blue; font-weight: bold">date</span>(<span title="" style="color: gray">'g:i a'</span>,<span title="Return current UNIX timestamp; number time()" style="color: blue; font-weight: bold">time</span>())</span>. Do you know where your <span style="background-color: #eee8aa;"><span title="Calculate the sum of values in an array; number sum(arg1, arg2, ... argN)" style="color: blue; font-weight: bold">sum</span>(<span title="[java61764X1X4][G:2][Q:50]: How many pets do you have?; value=1" style="color: maroon; font-weight: bold">numPets</span>,<span title="[java61764X1X3][G:2][Q:40]: How many kids do you have?; value=2" style="color: green; font-weight: bold">numKids</span>)</span> children and pets are?


</td><td><b>Here is an example of OK syntax with tooltips</b><br>Hello <span id="LEMtailor_Q_40_1">Mr.</span> <span id="LEMtailor_Q_40_2">Smith</span>, it is now 6:07 am. Do you know where your <span id="LEMtailor_Q_40_4">3</span> children and pets are?
</td></tr>
<tr><td><b>Here are common errors so you can see the tooltips</b><br>Variables used before they are declared: {notSetYet}<br>Unknown Function: {iff(numPets>numKids,1,2)}<br>Unknown Variable: {sum(age,num_pets,numKids)}<br>Wrong # parameters: {sprintf()},{if(1,2)},{date()}<br>Assign read-only-vars:{TOKEN:ATTRIBUTE_1+=10},{name='Sally'}<br>Unbalanced parentheses: {pow(3,4},{(pow(3,4)},{pow(3,4))}


</td><td><b>Here are common errors so you can see the tooltips</b><br>Variables used before they are declared: <span style="background-color: #eee8aa;"><span title="This variable is not declared until a later page; Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="This variable is not declared until a later page; Not a valid expression; [java61764X3X6][G:3][Q:200]: Who will win the next election?; value=?" style="color: #FF00FF ; font-weight: bold">notSetYet</span></span></span><br>Unknown Function: <span style="background-color: #eee8aa;"><span title="Undefined function" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Undefined function" style="color: blue; font-weight: bold">iff</span></span>(<span title="[java61764X1X4][G:2][Q:50]: How many pets do you have?; value=1" style="color: maroon; font-weight: bold">numPets</span> > <span title="[java61764X1X3][G:2][Q:40]: How many kids do you have?; value=2" style="color: green; font-weight: bold">numKids</span>,1,2)</span><br>Unknown Variable: <span style="background-color: #eee8aa;"><span title="Calculate the sum of values in an array; number sum(arg1, arg2, ... argN)" style="color: blue; font-weight: bold">sum</span>(<span title="[java61764X1X2][G:2][Q:30]: How old are you?; value=45" style="color: green; font-weight: bold">age</span>,<span title="Undefined variable" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Undefined variable" style="color: red; font-weight: bold">num_pets</span></span>,<span title="[java61764X1X3][G:2][Q:40]: How many kids do you have?; value=2" style="color: green; font-weight: bold">numKids</span>)</span><br>Wrong # parameters: <span style="background-color: #eee8aa;"><span title="Function must have at least 1 argument(s); Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Function must have at least 1 argument(s); Not a valid expression; Return a formatted string; string sprintf(format, arg1, arg2, ... argN)" style="color: blue; font-weight: bold">sprintf</span></span>()</span>,<span style="background-color: #eee8aa;"><span title="Function does not support that number of arguments: 2. Function supports this many arguments, where -1=unlimited: 3; Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Function does not support that number of arguments: 2. Function supports this many arguments, where -1=unlimited: 3; Not a valid expression; Excel-style if(test,result_if_true,result_if_false); if(test,result_if_true,result_if_false)" style="color: blue; font-weight: bold">if</span></span>(1,2)</span>,<span style="background-color: #eee8aa;"><span title="Function does not support that number of arguments: 0. Function supports this many arguments, where -1=unlimited: 1,2; Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Function does not support that number of arguments: 0. Function supports this many arguments, where -1=unlimited: 1,2; Not a valid expression; Format a local date/time; string date(format [, timestamp=time()])" style="color: blue; font-weight: bold">date</span></span>()</span><br>Assign read-only-vars:<span style="background-color: #eee8aa;"><span title="The value of this variable can not be changed; Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="The value of this variable can not be changed; Not a valid expression; ; value=worker" style="color: #996600; font-weight: bold">TOKEN:ATTRIBUTE_1</span></span><span title="Assigning a new value to a variable" style="color: red; font-weight: bold">+=</span>10</span>,<span style="background-color: #eee8aa;"><span title="The value of this variable can not be changed; Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="The value of this variable can not be changed; Not a valid expression; [java61764X1X1][G:1][Q:10]: What is your first/given name?; value=Peter" style="color: green; font-weight: bold">name</span></span><span title="Assigning a new value to a variable" style="color: red; font-weight: bold">=</span><span title="" style="color: gray">'Sally'</span></span><br>Unbalanced parentheses: <span style="background-color: #eee8aa;"><span title="Parentheses not balanced" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Parentheses not balanced; Exponential expression; number pow(base, exp)" style="color: blue; font-weight: bold">pow</span></span>(3,4</span>,<span style="background-color: #eee8aa;"><span title="Parentheses not balanced" style="border-style: solid; border-width: 2px; border-color: red;">(</span><span title="Exponential expression; number pow(base, exp)" style="color: blue; font-weight: bold">pow</span>(3,4)</span>,<span style="background-color: #eee8aa;"><span title="Exponential expression; number pow(base, exp)" style="color: blue; font-weight: bold">pow</span>(3,4)<span title="Extra right parentheses detected" style="border-style: solid; border-width: 2px; border-color: red;">)</span></span>


</td><td><b>Here are common errors so you can see the tooltips</b><br>Variables used before they are declared: <span id="LEMtailor_Q_40_5"><span style="background-color: #eee8aa;"><span title="This variable is not declared until a later page; Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="This variable is not declared until a later page; Not a valid expression; [java61764X3X6][G:3][Q:200]: Who will win the next election?; value=?" style="color: #FF00FF ; font-weight: bold">notSetYet</span></span></span></span><br>Unknown Function: <span style="background-color: #eee8aa;"><span title="Undefined function" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Undefined function" style="color: blue; font-weight: bold">iff</span></span>(<span title="[java61764X1X4][G:2][Q:50]: How many pets do you have?; value=1" style="color: maroon; font-weight: bold">numPets</span> > <span title="[java61764X1X3][G:2][Q:40]: How many kids do you have?; value=2" style="color: green; font-weight: bold">numKids</span>,1,2)</span><br>Unknown Variable: <span style="background-color: #eee8aa;"><span title="Calculate the sum of values in an array; number sum(arg1, arg2, ... argN)" style="color: blue; font-weight: bold">sum</span>(<span title="[java61764X1X2][G:2][Q:30]: How old are you?; value=45" style="color: green; font-weight: bold">age</span>,<span title="Undefined variable" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Undefined variable" style="color: red; font-weight: bold">num_pets</span></span>,<span title="[java61764X1X3][G:2][Q:40]: How many kids do you have?; value=2" style="color: green; font-weight: bold">numKids</span>)</span><br>Wrong # parameters: <span style="background-color: #eee8aa;"><span title="Function must have at least 1 argument(s); Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Function must have at least 1 argument(s); Not a valid expression; Return a formatted string; string sprintf(format, arg1, arg2, ... argN)" style="color: blue; font-weight: bold">sprintf</span></span>()</span>,<span style="background-color: #eee8aa;"><span title="Function does not support that number of arguments: 2. Function supports this many arguments, where -1=unlimited: 3; Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Function does not support that number of arguments: 2. Function supports this many arguments, where -1=unlimited: 3; Not a valid expression; Excel-style if(test,result_if_true,result_if_false); if(test,result_if_true,result_if_false)" style="color: blue; font-weight: bold">if</span></span>(1,2)</span>,<span style="background-color: #eee8aa;"><span title="Function does not support that number of arguments: 0. Function supports this many arguments, where -1=unlimited: 1,2; Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Function does not support that number of arguments: 0. Function supports this many arguments, where -1=unlimited: 1,2; Not a valid expression; Format a local date/time; string date(format [, timestamp=time()])" style="color: blue; font-weight: bold">date</span></span>()</span><br>Assign read-only-vars:<span style="background-color: #eee8aa;"><span title="The value of this variable can not be changed; Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="The value of this variable can not be changed; Not a valid expression; ; value=worker" style="color: #996600; font-weight: bold">TOKEN:ATTRIBUTE_1</span></span><span title="Assigning a new value to a variable" style="color: red; font-weight: bold">+=</span>10</span>,<span id="LEMtailor_Q_40_12"><span style="background-color: #eee8aa;"><span title="The value of this variable can not be changed; Not a valid expression" style="border-style: solid; border-width: 2px; border-color: red;"><span title="The value of this variable can not be changed; Not a valid expression; [java61764X1X1][G:1][Q:10]: What is your first/given name?; value=Peter" style="color: green; font-weight: bold">name</span></span><span title="Assigning a new value to a variable" style="color: red; font-weight: bold">=</span><span title="" style="color: gray">'Sally'</span></span></span><br>Unbalanced parentheses: <span style="background-color: #eee8aa;"><span title="Parentheses not balanced" style="border-style: solid; border-width: 2px; border-color: red;"><span title="Parentheses not balanced; Exponential expression; number pow(base, exp)" style="color: blue; font-weight: bold">pow</span></span>(3,4</span>,<span style="background-color: #eee8aa;"><span title="Parentheses not balanced" style="border-style: solid; border-width: 2px; border-color: red;">(</span><span title="Exponential expression; number pow(base, exp)" style="color: blue; font-weight: bold">pow</span>(3,4)</span>,<span style="background-color: #eee8aa;"><span title="Exponential expression; number pow(base, exp)" style="color: blue; font-weight: bold">pow</span>(3,4)<span title="Extra right parentheses detected" style="border-style: solid; border-width: 2px; border-color: red;">)</span></span>


</td></tr>
<tr><td><b>Here is some of the unsupported syntax</b><br>No support for '++', '--', '%',';': {min(++age, --age,age % 2);}<br>Nor '|', '&', '^': {(sum(2 | 3,3 & 4,5 ^ 6)}}<br>Nor arrays: {name[2], name['mine']}
</td><td><b>Here is some of the unsupported syntax</b><br>No support for '++', '--', '%',';': <span style="background-color: #eee8aa;"><span title="Find lowest value; number min(arg1, arg2, ... argN)" style="color: blue; font-weight: bold">min</span>(<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> ++ </span><span title="[java61764X1X2][G:2][Q:30]: How old are you?; value=45" style="color: green; font-weight: bold">age</span>,<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> -- </span><span title="[java61764X1X2][G:2][Q:30]: How old are you?; value=45" style="color: green; font-weight: bold">age</span>,<span title="[java61764X1X2][G:2][Q:30]: How old are you?; value=45" style="color: green; font-weight: bold">age</span><span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> % </span>2)<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> ; </span></span><br>Nor '|', '&', '^': <span style="background-color: #eee8aa;">(<span title="Calculate the sum of values in an array; number sum(arg1, arg2, ... argN)" style="color: blue; font-weight: bold">sum</span>(2<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> | </span>3,3<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> & </span>4,5<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> ^ </span>6)</span>}<br>Nor arrays: <span style="background-color: #eee8aa;"><span title="[java61764X1X1][G:1][Q:10]: What is your first/given name?; value=Peter" style="color: green; font-weight: bold">name</span><span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> [ </span>2<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> ] </span>,<span title="[java61764X1X1][G:1][Q:10]: What is your first/given name?; value=Peter" style="color: green; font-weight: bold">name</span><span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> [ </span><span title="" style="color: gray">'mine'</span><span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> ] </span></span>


</td><td><b>Here is some of the unsupported syntax</b><br>No support for '++', '--', '%',';': <span style="background-color: #eee8aa;"><span title="Find lowest value; number min(arg1, arg2, ... argN)" style="color: blue; font-weight: bold">min</span>(<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> ++ </span><span title="[java61764X1X2][G:2][Q:30]: How old are you?; value=45" style="color: green; font-weight: bold">age</span>,<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> -- </span><span title="[java61764X1X2][G:2][Q:30]: How old are you?; value=45" style="color: green; font-weight: bold">age</span>,<span title="[java61764X1X2][G:2][Q:30]: How old are you?; value=45" style="color: green; font-weight: bold">age</span><span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> % </span>2)<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> ; </span></span><br>Nor '|', '&', '^': <span style="background-color: #eee8aa;">(<span title="Calculate the sum of values in an array; number sum(arg1, arg2, ... argN)" style="color: blue; font-weight: bold">sum</span>(2<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> | </span>3,3<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> & </span>4,5<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> ^ </span>6)</span>}<br>Nor arrays: <span style="background-color: #eee8aa;"><span title="[java61764X1X1][G:1][Q:10]: What is your first/given name?; value=Peter" style="color: green; font-weight: bold">name</span><span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> [ </span>2<span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> ] </span>,<span title="[java61764X1X1][G:1][Q:10]: What is your first/given name?; value=Peter" style="color: green; font-weight: bold">name</span><span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> [ </span><span title="" style="color: gray">'mine'</span><span title="Unsupported syntax" style="border-style: solid; border-width: 2px; border-color: red;"> ] </span></span>


</td></tr>
</table>

=Tailoring Examples (e.g. extending {INSERTANS:xxx})= 

=="Dear {Mr}/{Mrs} Smith..."== 


Use the if() function to conditionally choose whether to display 'Mr.' or 'Mrs.'.


The syntax is if(test,do_if_true,do_if_false).


{|
|#||Code||Question||Type
|-
|1||gender||What is your gender?||Gender
|-
|2||example1||Dear {if(gender=='M','Mr.','Mrs.')} Smith, ...||Long free text
|}


<center>[[File:em-tailoring-q-ex1.jpg]]</center>


As it can be observed below, "Mr" and "Mrs" are tailored to what the respondent selects as answer to question "gender".


<center>[[File:em-tailoring-q-ex1-usage.jpg]]
[[File:em-tailoring-q-ex2-usage.jpg]]</center>

=="Dear {Mr}/{Mrs} Smith..." in invitation email== 


You can use the example above in the invitation email using attributes from the token table. Use the if() function to choose whether 'Mr.' or 'Mrs.' should be used in the email.


The syntax is "if(test,do_if_true,do_if_false)".


{|
|#||attribute||value
|-
|1||Last name||Smith
|-
|2||Email address||test@test.com
|-
|3||ATTRIBUTE_2||M
|}


Text in invitation email:


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


Dear {if(ATTRIBUTE_2=='M','Mr','Mrs')} {LASTNAME},


you have been invited to participate in a survey:


https:/...


</syntaxhighlight>


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


email View:


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

=Calculation / Assessment Examples= 

==Calculate assessment values at runtime and store the results in the survey data== 


This example uses all of EM's features, including Relevance, Tailoring, and the Equation question type.


It also shows that all of them are JavaScript-enabled, so if you have these features on a page, it will dynamically change as people set and change their answers.


{|
|#||Code||Question||Type||Relevance
|-
|1||numKids||How many children do you have?||Numerical input||1
|-
|2||kid1||How old is your first child?||Numerical input||numKids >= 1
|-
|3||kid2||How old is your second child?||Numerical input||numKids >= 2
|-
|4||kid3||How old is your third child?||Numerical input||numKids >= 3
|-
|5||kid4||How old is your fourth child?||Numerical input||numKids >= 4
|-
|6||sumKidAges||{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK)}||Equation||1
|-
|7||kidSummary||You said that you have {numKids}. {if(numKids==1,'child','children')}. {if(numKids>1,implode(' ','The sum of ages of your first ',min(numKids,4),' kids is ',sumKidAges,'.'),' ')}||Text display||1
|}


To download this example, please click on the following link: [[Media:Assessments_survey_example.zip|Assessments_survey_example]].


You may find below screenshots of representative questions. As you can see, EM syntax-highlights all fields that might contain tailoring. Here, you see examples of syntax-highlighting Relevance, the Equation question type, and substitutions within a question. You can also use substitutions within Help, Group header display, Welcome message, and End message.


In the next example, since the relevance is {numKids >= 2), the question will only be visible if the respondent reports that she has at least two children.


<center>[[File:em-tailoring2-q-kid2.jpg]]</center>


Below, you may observe that each variable has the .NAOK suffix attached to it. This is because of how EM supports cascading relevance. If you did not have .NAOK, then the sum would only be computed if the person said she has 4 children (e.g., if all of the variables are relevant). The usage of .NAOK means that we want to compute the sum even if all or some of the variables are irrelevant (e.g., "Not Applicable" (NA) is alright (OK)).


However, the .NAOK attribute only affects whether variables are passed into EM. If the respondent initially says she has 3 children, and enters ages for each, then changes her mind and says she has 2, we don't want to see the sum of the 3 entered values - since the third child is "not applicable" in our case anymore:


<center>[[File:em-tailoring2-q-sumKidAges.jpg]]</center>


Each separate Expression is color coded with a tan background. As you can see, there are three separate Expressions here. The last one contains a message that is conditionally shown only if the person has more than one child.


<center>[[File:em-tailoring2-q-kidSummary.jpg]]</center>


Now, here are screenshots of the survey in action.


When you first visit the page, you see this. Note that is says "You have 0 '''children'''" instead of "You have 0 '''child'''".


<center>[[File:em-tailoring2-s-0kids.jpg]]</center>


If I change the value for number of children to 1, the display instantly changes to this, even though it is on the same page:


<center>[[File:em-tailoring2-s-1kid.jpg]]</center>


Now notice that the grammar is correct: "You have 1 '''child'''".


Now I change the value for number of children to 3, and the display instantly changes to this.


Notice that you now see the conditional message at the bottom: "The sum of ages of your first 3 kids is 0.".


</center>[[File:em-tailoring2-s-3kids.jpg]]</center>


Now I'll enter ages for my imaginary children, and I get this display, summing up their ages:


<center>[[File:em-tailoring2-s-3kids-sum.jpg]]</center>


Again, the score and display updates instantly as I enter the values, so you can use this to show a running total of an Assessment Score.


Now, I change the value for the number of children to 2. The display has changed to this:


<center>[[File:em-tailoring2-s-2kids-sum.jpg]]</center>


Notice that although I had entered a value of 5.5 for the third child, the report now only sums the values of my first 2 children.


The reason for this is that the 3rd value is now irrelevant, and irrelevant values are actively ignored by EM.


If I were to change the number of kids back to 3, I would see the value of 5.5 I entered again. So, I don't lose any information I enter on the page.


However, if I navigate to the Next or Previous page, all irrelevant values will be NULLed out in the session and in the database. So, if I were to keep the value at 2, go to the next page, and then come back and state that I actually have 3 kids, I would no longer see the age of 5.5.

==Enter data and see a dynamically changing report of what was entered on the same page== 


This example presents the Tailoring process within LimeSurvey.


To download this example, click on the following link: [[Media:Dynamic_change_of_the_report_when_data_is_entered_on_the_same_page_survey.zip|Dynamic changes survey example]].


Here is what the page looks like initially. You only see the question asking what city you live in:


<center>[[File:em-on_page_report-usage-1.jpg]]</center>


Once you start to enter an answer, the tailoring process is also starting:


<center>[[File:em-on_page_report-usage-2.jpg]]</center>


As you enter answers, the table at the bottom of the page is updated to show the answer codes and values of your responses.


<center>[[File:em-on_page_report-usage-3.jpg]]</center>

=Common Debugging Examples= 

==Nested if() Statements (Conditional Logic)== 


EM supports the function "if(test,do_if_true,do_if_false)" so that you can perform conditional logic or tailoring. This function can be nested to do the equivalent of "if { } else if { } else { }". EM will let you know if the parentheses are not balanced (e.g., you are missing a closing right parenthesis), or if you have any extra right parentheses. You should try to count the parentheses as you compose long nested if statements, save it, check for syntax errors, and fix them if any are found. Let's check together the below example.


The group of questions used below can be accessed from here: [[Media:Example_tailoring_group11.zip|Tailoring survey example.lsg]]


First, with nothing entered, you just see "Hello."


<center>[[File:em-nested-if-blank.jpg]]</center>


If you enter a name, it says, "Hello {name}."


<center>[[File:em-nested-if-name.jpg]]</center>


If you enter an age, you get a tailored message, depending upon whether you are a pre-school-age child or not:


<center>[[File:em-nested-if-toddler.jpg]]</center>


School aged, teenager, or adult. Here is a teenager who wants to be anonymous:


<center>[[File:em-nested-if-teenager.jpg]]</center>


Here is the logic file of the group. As you can see in the "if-based" question, there are nested if statements based upon the person's age.


<center>[[File:em-nested-if-logic-file.jpg]]</center>


When you are originally editing this question, it is likely that at some point, you will have the wrong number of parentheses. Here's what happens if you have too few:


<center>[[File:em-nested-if-missing-closing-paren.jpg]]</center>


If you hover over the word "if", which is surrounded by a red box, it says "Parentheses not balanced". In this case, there should be four closing parentheses after "already an adult!", but there are only three.


If, on the other hand, you have an extra right parenthesis, it will be surrounded by a red box, like this:


<center>[[File:em-nestedd-if-extra-right-paren.jpg]]</center>


When you are actually editing the question, the question looks like this:


<center>[[File:em-nested-if-edit-screen.jpg]]</center>
</translate>

Setting conditions

2020-04-15T08:27:39Z

Cdorin:

<languages /> <translate>

__TOC__

=Overview of Conditions in LimeSurvey= 


LimeSurvey has a very powerful logical branching feature. It can be accessed by clicking on the '''Set conditions''' button - [[File:conditions_icon.png]] - located on each [[Question toolbar options|question bar]].


In this chapter we will describe:
* what conditions you can find in LimeSurvey
* what you can and can't do with conditions
* what steps you need to learn to set up simple or more complex conditions


For step-by-step video instructions check out [http://www.youtube.com/watch?v=oexr0z-eo9U this tutorial] or download the condition sample survey: [[Media:LimeSurvey_Survey_Setting_Conditions.zip|LimeSurvey_Survey_Setting_Conditions.zip]].


{{Hint|Text=The conditions functionalities work like a GUI for [[ExpressionScript - Presentation|the expressions and equations that can be applied to questions]], allowing the users to easily increase the complexity of their surveys without getting into expressions and relevance equations. However, [[ExpressionScript - Presentation|the ExpressionScript]] must be studied/known to increase the range of options that is available within LimeSurvey.}}

==Hide/Show Branching Versus Jump Branching== 


You can design logical branching with LimeSurvey, which means that you can decide that some questions will be displayed only if some conditions are met like "Show question X if the answer to question Y was Z".


Our approach is to implement a '''Hide/Show Branching Logic''':
* you can define a condition or a set of conditions on each question of your survey - if the condition is met, the question will be then displayed:


<center>[[File:simple-condition-on-yes-question.png]]</center>


<div class='simplebox'> [[File:help.png]] Simply put:
* a question without a condition defined on it will always be displayed;
* a question with a condition defined on it will not be displayed unless the condition is met.</div>


This approach is different from the '''Jump Branching Logic''' that is sometimes implemented by other software. In the '''Jump Branching Logic''', the resulting action of a met condition would be to jump to another question (that is to say hide all questions in between). '''LimeSurvey doesn't implement this Jump Branching Logic''' method. Instead, if you wish to jump a series of questions, you should simply set the same condition on all the questions you do not wish to be displayed. For example, if the jump condition you want to set on Question2 is "Jump to Question5 if the answer to Question1 is 'Yes'", you can simply:
*set a condition on questions 2, 3 and 4 to only display "if the answer to Question1 was '''NOT''' 'Yes'"


LimeSurvey makes setting the same condition on multiple questions (and thus implementing '''Jump Branching Logic''') easy by allowing you to "copy" a condition from one question to a series of others. In the above example, you would begin by setting the condition on Question2, then from the same screen, you would copy that condition to Question3 and Question4.


<div class='simplebox'> [[File:help.png]] To find out more details on how you can copy conditions within LimeSurvey, please continue reading the following [[Setting conditions#How to copy conditions|wiki section]].</div>

==Supported Types of Conditions== 


Basically, a condition can compare values, returning either true or false.


The values that can be compared are '''answers to previous questions'''. For instance, if you answer 'Yes' to Question1, Question2 will then be showed to the survey respondent:


<center>[[File:Questions_example_set_conditions_y.png]]</center>


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


At this point, it is important to understand what is considered an eligible question-entry for the condition editor.


A '''question-entry''' is either:
* a simple question (for all question types apart from Array questions)
** for instance: text questions, radio or dropdown lists, and even multiple choices questions
* or a row in Array questions (except for Array dual scale and Array multiple flexible questions)
** for instance: array with 5 radio buttons or array with label questions
* or either the left part or the right part of an Array dual scale question
* or each cell of an Array flexible question


{{Note|Check the following [[Question types|link]] to find out more about the available question types in LimeSurvey.}}


* '''constant values'''
** for instance: "If you answered more than 18 years to the question below"


<center>[[File:simple-condition-on-numerical-question.png]]</center>


* '''Participants' profile data:''' To use data from the survey participants table, "Anonymized responses" must be set to '''NO'''. This option can be found in survey [[Participant settings|participant settings]] panel.


<center>[[File:simple-condition-on-token.png]]</center>


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


Several comparison operators are supported - from the simple "equals" to the advanced "regular expression":
* The basic ones refer to the "equal" and "not equal to" operations
* The ''greater/less than'' operator family is also available, and is usually used when using numeric question-entries
** Please note that comparisons on numeric fields make use of the numeric order. For instance, 2 < 10
** If you're using a question entry whose type is text, the condition could be evaluated as "2" > "10" (string order)!
** Numeric questions, as well as text questions (when they have the 'numbers_only' attribute set), will use the numeric order for comparisons
* An advanced comparison operator using regular expressions is also available (don't panic! If you don't know what this means, then you don't need it)
** the pattern is '''not''' to be enclosed in '/' characters
** for instance: '''[a-zA-Z]$'''

==How can I combine conditions?== 


You can '''build complex conditions''' by '''combining simple conditions''' with the '''AND '''and '''OR '''logical operators.


<center>[[File:simple-conditions-combination.png]]</center>


However, it is important to understand that '''LimeSurvey automatically determines which logical operator to apply'''. This means that the use of the '''OR '''or '''AND '''operators is determined '''according to the context''' of the condition. In the above example, there is only one scenario. This means that LimeSurvey makes use of [https://en.wikipedia.org/wiki/Boolean_algebra Boolean algebra], which means that operator '''or''' is "computed" first.


We'll talk more about complex conditions [[Setting_conditions#The usage of scenarios - Using ORed conditions between different questions|later]]. Let's first focus together on the elementary ones.

=The conditions designer= 


First, you need to access the [[Question toolbar options#The question toolbar|conditions designer]]. To do that, click on the question you wish to apply the condition to:


<center>[[File:Question designer search question.png]]</center>


Now, look for the '''Set conditions''' button located on the top question bar:


<center>[[File:Question designer set conditions.png]]</center>


Once accessed, the following page will be displayed:


<center>[[File:Question designer top.png]]</center>


The conditions designer panel can be divided into three sections:
* [[Setting conditions#The conditions designer toolbar|The conditions designer toolbar]]
* [[Setting conditions#Overview of the existent conditions|The current existent question conditions]]
* [[Setting conditions#Add/Edit conditions|Add/edit condition menu]]

==The conditions designer toolbar== 


You may find on the toolbar the following options:


<center>[[File:Show conditions designer toolbar.png]]</center>


*'''Show conditions for this question''': Click on this button to get a quick overview of the current existent conditions that are applied to your question.


*'''Add and edit conditions''': It represents the default page that opens automatically once you click the '''Set conditions''' button. It is divided in two parts: (1) a table displaying all the existent conditions and scenarios, and (2) the [[Setting conditions#Add/Edit conditions|add/edit conditions menu]].


*'''Copy conditions''': Sometimes, you wish to apply the same condition to X questions in order to get questionY displayed at the end. For this, click on '''Copy conditions'''. A new window will open displaying the current existent conditions added to your question (let's call it question3). To add them to question5, check the desired conditions you wish to be copied, select question5, and click on the '''Copy conditions''' button located on the bottom left part of the panel. For further information, please continue reading the following [[Setting conditions#How to copy conditions|wiki section]].


*'''Save and close''': Once you are done with the changes, click '''Save and close''' to get your conditions saved.


*'''Move to question''': In order not to leave the conditions designer panel while moving to another question, use the following option to select from the dropdown list the next question you wish to apply conditions to. Please note that the dropdown list displays the questions that are displayed in the survey before and after the current question.


*'''Close''': If you wish to exit the panel without performing any changes, you can either go straight to the settings/structure tab and select the desired option or click '''Close''', which is located in the upper right of the screen.

==Overview of the existent conditions== 


This section displays a table that contains all the existent scenarios and conditions of a question. Certain actions can be performed from here:


<center>[[FIle:Show conditions for this questions pic.png]]</center>


*In the top right part, three actions are available:
**Quick-add conditions - it fastens the process of adding conditions (read [[Setting conditions#Add/Edit conditions|below]] to learn about all the options)
**Renumber scenarios - if clicked, the scenarios will be renumbered with incremental numbers beginning from one. Please note that this option is displayed only if two or more scenarios are applied to your question.
**Delete all conditions - you can delete via this action all the current existent conditions and scenarios applied to your question.


<center>[[FIle:Conditions designer quickadd and delete.png]]</center>


*Besides the id number of each scenario there are three buttons that allow you to perform the following actions:
**Delete scenario
**Change scenario number
**Add condition to this scenario - click on this button to add another condition to the desired scenario


<center>[[FIle:Conditions Designer table scenarios.png]]</center>


*Two actions can be performed on each condition:
**Delete condition
**Edit condition - if clicked, you will be able to edit the condition from the [[Setting conditions#Add/Edit conditions|conditions menu]]


<center>[[FIle:Conditions Designer table conditions.png]]</center>

==Add/Edit conditions== 


The bottom part of the screen is allocated to the Add/edit conditions menu:


<center>[[File:Add_edit_condition_q.png]]</center>


<div class='simplebox'> You can also edit the condition from the same location if you pressed before on the green pencil that corresponds to the question you wish to be edited (see the [[Setting conditions#Overview of the existent conditions|conditions and scenarios table]]).</div>


To understand how the conditions feature works in LimeSurvey, we will first present the elementary conditions.


<div class='simplebox'>[[File:help.png]] '''Note''': For the moment '''don't modify the default scenario''' ([[File:default_scenario.png]]) that is automatically selected in the condition addition form. It will be covered later within this [[Setting conditions#The usage of scenarios - Using ORed conditions between different questions|wiki section]].</div>

===Definition of elementary conditions=== 


An elementary condition is simply a single condition '''without any OR or AND''' logical operators.


It is composed by:
* a left operand: the ''tested value''. You can choose the ''tested value'' type by selecting the appropriate tab in the condition editor. It can either be a previous question or a [[Survey participants|survey participant]] attribute.


<center>[[File:edit-conditions-testedvalueTab.png]]</center>


If you select a question-entry (from the '''Previous questions''' tab) and if this question uses predefined answers, then the corresponding predefined answers are displayed under the '''Predefined''' tab of the comparison value selection.


<div class='simplebox'> [[File:help.png]] Note that in order to use the Token your survey must:
*not use [[Participant settings|anonymous answers]]
*use a [[Survey participants|survey participants table]] and [[Participant settings|closed access]].</div>


* a ''comparison operator''. Choose the ''comparison operator'' you want to apply from the dropdown list (''less than'', ''less than or equal to'', ''equals'', ''not equal to'', ''greater than or equal to'', ''greater than'', ''[[ExpressionScript - Presentation|regular expression]]'').


* a right operand: the ''comparison value''. You can choose the ''comparison value'' type by selecting the appropriate tab in the condition editor. When you create a condition, you can select as the comparison value a predefined value (answer), a constant, a question, a survey participant attribute, or a regular expression:


<center>[[File:edit-conditions-comparisonvalueTab.png]]</center>

===Example of elementary conditions and how to create them=== 


* Show Question 'AAMN' '''if''' "the answer to Question 'Gender' is the predefined answer 'Male'"
** ''tested value'' = answer to Question 'Gender'
** ''comparison operator'' = equals
** ''comparison value'' = predefined answer code (the 'Male' answer in this case)


<center>[[File:edit-simple-condition-predefanswer.png]]</center>


* Show Question 'Alcohol' '''if''' "the answer to Question 'Age' is greater or equal than the numerical value '18'"
** ''tested value'' = answer to Question 'Age'
** ''comparison operator'' = greater than or equal to
** ''comparison value'' = the constant value '18'


<center>[[File:edit-simple-condition-constant.png]]</center>


{{Alert|title=Attention|text=When using a constant 'comparison value' for a date question, regardless of the date format set in your survey, you must use the YYYY-MM-DD date format.}}


* Show Question 'Alcohol' '''if''' "the answer to Question 'BirthDate' is greater than 2000-01-01'''"
** ''tested value'' = answer to Question 'BirthDate'
** ''comparison operator'' = Greater than or equal to
** ''comparison value'' = '2000-01-01' (the format in the constant field: 2000-01-01)


<center>[[File:Date time example condition.png]]</center>


* Show Question 'Alcohol' '''if''' "the the 'DrinkingHistory' [[Survey participants|participant's attribute]]" matches the 'Yes' string.
** ''tested value''= the 'DrinkingHistory' value taken from the [[Survey participants#Manage attributes|survey participants table]]
** ''comparison operator'' = equals
** ''comparison value'' = the constant value 'Yes'


<center>[[File:edit-simple-condition-leftToken.png]]</center>

=Conditions and scenarios in LimeSurvey= 

==Default condition combinations== 


As said earlier, LimeSurvey automatically decides which logical operator (AND or OR) should be applied between conditions depending on the 'context'.


Note also that '''the order in which you define your elementary conditions is not relevant''' as LimeSurvey will automatically reorder them according to its own logic.


Let's study this in detail. Two rules should be always remembered:
* [[Setting conditions#First rule: conditions having the same tested value are ORed together|First rule]]: conditions having the same ''tested value'' are ORed together
* [[Setting conditions#Second rule: conditions having different tested value are ANDed together|Second rule]]: conditions having different tested value are ANDed together

===First rule: conditions having the same ''tested value'' are ORed together=== 


When you have several conditions, they are '''ORed''' together if they share the same '''tested value'''. This is the case if the condition applies to several answers belonging to one single question. For example, a condition was applied below to three answers belonging to the same question - if answer to Question 'FavColour' equals 'green' '''OR''' answer to Question 'FavColour' equals 'red' '''OR''' answer to Question 'FavColour' equals 'blue', then Question 'BirthDate' will be displayed to the survey respondent:


<center>[[File:edit-conditions-naturalOr-edit.png]]


[[File:edit-conditions-naturalOr-result.png]]</center>


<div class='simplebox'>[[File:help.png]] Note: To select multiple predefined answers, don't forget to hold the Shift or Ctrl key while selecting the '''tested values'''.</div>

===Second rule: conditions having different ''tested value'' are ANDed together=== 


When you have several conditions, they are '''ANDed''' together if they don't share the same '''tested values'''. For example, you may see below the case for several conditions based on different previous questions - "If answer to Question 'Alcohol' equals 'Y' answer '''AND''' answer to Question 'Gender' equals 'F'", then Question 'Alcoholconsumption' will be displayed to the survey respondent:


<center>[[File:edit-conditions-naturalAND-editA.png]]


[[File:edit-conditions-naturalAND-editB.png]] </center>


<center>[[File:edit-conditions-naturalAND-result.png]]</center>

===The multiple options questions=== 


<div class='simplebox'>[[File:help.png]] '''Note:''' This paragraph applies to ''Multiple options'' and ''Multiple options with comments'' questions, and not to ''Array Multiple Flexible (number) with checkbox layout'' questions (in case of the latter, each checkbox is a separate question-entry and is not really handled as other multiple options question-types).</div>


The ''Multiple choice'' and ''Multiple choice with comments'' question types will be displayed in two flavors:
* a ''Group of checkboxes'' flavor which let you set conditions on all possible answers of the respective question;
* a set of ''Single checkbox'' entries which lets you set conditions on each checkbox individually.


<center>[[File:edit-conditions-MultipleOptions1.png]]</center>

====The group of checkboxes flavour==== 


Now, let's focus on an example to better understand the difference between the two flavours. Let's imagine that we wish to display the 'Pointchoice' Question only if the respondent checks at least one of the ''tested answers'' listed under the 'MultipleOrganizations' Question.


As mentioned above, the group of checkboxes flavor allows you to set conditions on all possible answers of the respective question. Therefore, only the options that refer to responsibilities are selected as '''comparison values''' below:


<center>[[File:edit-conditions-MultipleOptionsOR.png]]</center>


As we can observe, the conditions get ORed due to the ''Group of checkboxes'' flavour selected in the beginning.:


<center>[[File:edit-conditions-MultipleOptionsOR-result.png]]</center>

====ANDing conditions in multiple choice questions==== 


Now, let's focus on a similar example. However, we are looking this time only for the most active members to ask them further questions. To do this, we make use of the '''Single checkbox''' flavour which allows you to set conditions based on each checkbox individually.


In this example, question X will be displayed if ''A'' and ''B'' are checked:


<center>[[File:edit-conditions-MultipleOptionsAND2.png]]</center>


<center>[[File:edit-conditions-MultipleOptionsAND3.png]]</center>


Once done, you can observe that the two conditions are ANDed now.


<center>[[File:edit-conditions-MultipleOptionsAND-result.png]]</center>


This means that your question will not be displayed unless both tested values (the selected subquestions) are met.

==The usage of scenarios - Using ORed conditions between different questions== 


Now, you may argue that sometimes you need to have '''ORed''' conditions even when they are set on different questions (that is to say on different '''tested values'''). This is why we got scenarios!

===Definition of a scenario=== 


A scenario is simply '''a manual grouping of conditions''' in which some conditions are evaluated independently of other conditions from other scenarios. The complex condition resulting in this association of several scenarios will be met only if one scenario is met. In other words, scenarios are '''logical grouping of conditions''', respecting the above [[Setting conditions#Default condition combinations|rules]], and '''which are ORed together''' to build complex conditions.


Everything described above applies to the conditions located in every scenario. By default, all the new conditions are created inside the ''Default Scenario'', which uses number '1' as its identifier. When you create new conditions, you can choose whether they are added to the default scenario or not. To change the scenario, just use another identifier.

===Adding a question to another scenario=== 


When you create (or edit) a condition, you can modify the scenario in which the condition is stored by simply clicking on the add scenario button:


<center>[[File:edit-conditions-EditorView-Scenario.png]]</center>


As you can observe, the default scenario uses as identifier '1'. To add conditions to different scenarios, change the identifier by typing a different number in the box.


The number id of a scenario has no importance and different scenarios can have non-continuous ids.


<center>[[File:Conditions test ids.png]]</center>


You can change the number assigned to a scenario by clicking this Icon [[File:scenario_edit.png]] and assigning the new id to the scenario.


<center>[[File:edit_scenario_conditions.png]]</center>


<div class='simplebox'> [[File:help.png]] '''Note:''' As said above, scenario numbers have no impact in the way conditions are evaluated. However, modifying the scenario numbers are needed in order to:
* decide in which order the scenarios are displayed when using the printable version of a survey
* merge conditions from two scenarios (in order to merge scenario 10 with scenario 1, just renumber scenario 10, so that it is scenario 1).</div>

===Example: creating three scenarios=== 


To create three scenarios, you need at least three conditions and to add to each of them a different scenario id. Once done, the scenarios are going to be connected among themselves via the 'OR' operator. For example, it could look like this:


<center>[[File:edit-conditions-EditorView-Scenario2.png]]</center>

== AND vs OR in the same scenario== 


You may end up in certain cases with AND and OR logical operators in the same scenario:


<center>[[File:And vs OR example.png]]</center>


LimeSurvey will always apply first OR. For further details on this, you may check the following Wikipedia article on [https://en.wikipedia.org/wiki/Boolean_algebra Boolean algebra].


However. the order of operations can also be observed in the Relevance equation field. For the above example, the relevance equation is highlighted below:


<center>[[File:AND vs OR relevance eq.png]]</center>


As it can be observed, a set of extra parentheses is added for the OR logical operations in order to let the software know that it must be "computed" first.


<div class='simplebox'> [[File:help.png]] '''Help:''' For more information on relevance equations, check the [[ExpressionScript - Presentation]] and [[QS:Relevance|relevance equation]] wiki sections. </div>

=How to copy conditions= 


The copy conditions functionality can be used when you wish to apply the same set of conditions you applied to Question5 to Question10. In this way, you will not have to manually recreate the conditions you applied to the previous question(s).


To start copying conditions, you first have to select the question the condition(s) is/are applied to (Question 'LowQ' in our case). Then, select the conditions you wish to be copied and select the question you wish to have the conditions added to (Question 'Alcohol' in our case).


<center>[[File:Copy conditions panel.png]]</center>


<div class='simplebox'>[[FIle:help.png]] '''Note:''' Conditions can only be set based on questions that appear before the question on which the condition is set.</div>


Please pay attention to how the copy conditions functions work when you wish to copy and apply a set of conditions located under different scenarios to another question which uses the same or different scenario id numbers. To summarise the possible cases you might have, check the following example:


* you wish to copy Scenario 1 - Condition A, Scenario 1- Condition B, Scenario 7 - Condition C, and Scenario 7 - Condition D from QuestionX into QuestionY
*QuestionY already contains Scenario 1 - Condition A, Scenario - Condition C, Scenario 6 - Condition E, Scenario 8- Condition F.
*Once copied, the following conditions will be applied to QuestionY:
**Scenario 1: Condition A, Condition B, Condition C -> '''Condition A is not copied anymore as it already exists in QuestionY, only condition B being copied.'''
**Scenario 6: Condition E -> not affected
**Scenario 7: Condition C, Condition D -> '''a new scenario is created where the two conditions are added to it'''
**Scenario 8: Condition F -> not affected

=Reset conditions= 


To quickly reset all the survey conditions, click on one survey-related setting, look for '''Tools''' on the top toolbar, and click '''Reset conditions:'''


<center>[[File:Reset_conditions_location.png]]</center>


Next, confirm on the next page that you want to proceed and all the conditions will be deleted.

=Things to watch out for= 

==General considerations== 


There are a few basic rules you should keep in mind before setting conditions on a question:
*Once a single condition has been set for a question, that question '''will not be displayed''' unless that condition is met.
*Conditions can only be set based on questions that appear '''before''' the question on which the condition is set.
*If you change the order of questions in your survey after you create conditions, LimeSurvey does not warn you if the changed order will break any of your conditions. You should always put aside the creation of conditions until you are satisfied with the order of questions and groups in your survey.
*You can modify conditions even after a survey has been activated. This should be done with caution, as there is no "consistency checking" applied here.

==Conditions using the 'no answer' predefined answer== 


<center>[[File:noanswer_conditions.png]]</center>


Setting the following condition "Show question 'FavColour' if the answer to the question 'Gender' is 'no answer'" really means "show question 'FavColour' if question 'Gender' was displayed to the survey participant who did not submit answer".


{{Hint|Text=To have the no answer option displayed as a predefined answer, the question cannot be [[QS:Mandatory|mandatory]].}}

==Chained conditions== 


If you set conditions on a question that, itself, has conditions, you could end up with your survey behaving in ways you might not have predicted. For example, a typical side-effect is that if you hide all questions in a group with chained conditions, the group header will still be shown unless you correct these conditions as explained below.


<center>[[File:chained_conditions1.png]]</center>


<center>[[File:chained_conditions2_bad.png]]</center>


In the above example, the 'Alcohol' question is displayed if the respondent has previously answered to the 'AAMN' question 'No (N)'. However, the 'AAMN' question might not be displayed at the end if the respondent did not select to the previous question ('Gender') answer 'Male (M)'. In this scenario, no 'Alcohol' question will be displayed if 'Male (M)' was chosen previously.


To have the 'Alcohol' question displayed, you have to copy the conditions from the earlier question(s) to the one you're editing. To have the 'Alcohol' question displayed, you need to set up the following set of conditions:
* Show 'AAMN' if the answer to 'Gender' is 'Male (M)'
* Show 'Alcohol' if answer to 'Gender' is 'Male (M)' '''and''' if answer to 'AAMN' is No (N)'.


After correction, the correct set of conditions for 'Alcohol' should look like this:


<center>[[File:chained_conditions2_good.png]]</center>


So if you are designing a complicated survey with a large number of conditions, make sure you test the survey for as many different combinations of results as you can think of.


<div class='simplebox'>[[File:help.png]] To find out more on how you can copy conditions in LimeSurvey, please scroll up or click here to continue reading the dedicates [[Setting_conditions#How_to_copy_conditions|wiki section]].</div>

==Limitations and workarounds== 

===Progress-bar=== 


If you create a survey where many questions get skipped because of conditions, the progress bar either jumps over a set of questions or the survey ends at 50%.


To avoid such behavior, the questions that could be skipped should be arranged between the shown questions. In this way, only one or two questions get skipped per answer.


For example, based on Question1 (yes or no question), 14 questions (2A to 15A) will be displayed if the answer to Question1 is 'Yes', or 2B to 15B if the answer to Question1 was 'No'.


If you arrange the questions in one group and arrange them like 2A, 2B, 3A, 3B, and so on, you will get a nearly correct progress bar, while arranging the questions like 2A, 3A, 4A, [...], 2B, 3B, 4B, ... you will get a progress bar from 0 to 50% or from 50% to 100%, depending on the answer to the first question.

=== Setting a constant comparison value for a "Date" Question Type=== 


You have to use the internal representation of Date values (which is '''YYYY-MM-DD''') to define your constant comparison value.

=== Setting conditions for "Other" Options in the Multiple Options Question Type=== 


In the multiple options question type, you can use the "Other" provided in the question type as a valid choice but you cannot set conditions on it. For example, Question No 1 says "Which color do you prefer to use?" Answer checkbox choices are Blue, Black and Other. If the participant chooses Blue, you can set a condition. If the participant chooses Black, you can set a different condition. '''However, if the participant chooses "Other" and types in something in the text box, there is NO way a condition can be set.''' LimeSurvey does not recognize if the participant chose the "Other" condition. This is NOT a bug but a limitation.


There is no real field recorded for the 'other' checkbox for this question type. Thus, the only way to know if the user has answered the 'other' part of the question or not would be to check if the value of the text written in the other input field is empty or not.


However, due to the specific way Multiple choice questions are handled, testing the 'other' text input field has never been implemented.


As a workaround, add an explicit answer option called 'Other' and do not use the built-in 'other' option of these question types. Then add an additional short text question which will be displayed if this 'Other' checkbox was clicked.

===How to use parenthesis for the boolean expressions?=== 


'''''You can't!'''''


If you want to design something like:


''(condition1 OR condition2)'' AND ''(condition3 OR condition4)'',


you'll have to set up:


''(condition1 AND condition3)'' OR


''(condition1 AND condition4)'' OR


''(condition2 AND condition3)'' OR


''(condition2 AND condition4)''
</translate>

Testing a survey

2020-04-15T08:04:39Z

Cdorin:

<languages />
<translate>


You can test a survey at any point while you are creating it by clicking the '''Preview survey''' button located on the survey toolbar:


<center>[[File:Testing_a_survey_preview.png]]</center>


This allows you to check the survey looks and feels before initializing it. When testing/previewing your survey, the responses will '''not''' be stored in the response table.


<div class="simplebox"><center>'''Hint:''' Use this functionality to test surveys that employs [[Setting conditions|conditions]] and/or [[ExpressionScript - Presentation|expressions]] to check if everything works as expected! If something is wrong, you should use the [[Show logic file|logic file]] option to quickly find out where the error is.</center>


<center>'''Testing a survey thoroughly prevents a lot of problems at a later time! '''</center></div>


{{Alert|title=Attention|text=If the survey is active and you open too many tabs by clicking on "Execute survey", you may not be able to continue the survey (an error will pop up suggesting you to use the index to navigate the survey). When that happens, please close all the tabs and make sure to open only 2 or 3 tabs to test the live version of your survey.}}

</translate>

Survey toolbar options

2020-04-15T08:04:05Z

Cdorin:

<languages />
<translate>


__TOC__

=Quick introduction= 


The survey toolbar options will be displayed once you accessed one of the survey-related settings:


<center>[[File:Survey_toolbar_options_-_access.png]]</center>


In a nutshell, the toolbar contains the following options:


<center>[[FIle:Overview toolbar.png]]</center>


*'''Survey status:''' There are four types of buttons that you might see on the left part of the toolbar, depending on the status of your survey:
**[[File:Button - activate this survey.png]] : It is displayed if the survey is inactive. Click on this button for activating the survey. To see the URL of the survey, check the ''Survey URL'' box located in the [[Overview#Survey summary|Survey summary section]];
**[[File:Button - stop this survey.png]] : It shows up if the survey is active. Click on this button if you wish to stop the survey (it cannot be accessed anymore by the respondents);
**[[File:Button - execute survey.png]]: If the survey is active, you can click on the '''Execute survey''' button to check and fill out the survey. The difference between this option and '''Preview survey''' is that the latter does not store your answers while the former does;
**[[File:Button - expired survey.png]] : It is displayed if the survey has expired. To reactivate it, click on the button to access the [[Publication & access|publication and access control settings]] to change the start or expiry date/time of the survey.
*'''Preview survey:''' It allows you to preview the survey. The green arrow appears when your survey is multilingual. Click on each language to separately check the multilingual versions of your survey.
*'''Tools:''' The following functionalities can be accessed from the '''tools''' menu:
**''Delete survey:'' Use this button if you want to delete the survey;
**''Quick-translation:'' Offers quick access to the translation menu. Please note that it is accessible only if your survey is multilingual - additional languages have been added besides the base language;
**''Reset conditions:'' All the survey conditions will be removed;
**''Survey logic file:'' It checks the logic of your survey. It is utilized when more advanced features are used in the survey. For more details, read [[Show_logic_file|our wiki section on survey logic]];
**''Regenerate question codes:'' The users that have the permission to edit questions can allocate a unique ID to any survey question. However, if these IDs differ too much (the numbering is too messy), the '''Regenerate question codes''' function can be used to automatically rename the survey questions. The numbering can be:
***''Straight:'' If this option is used, each question will be allocated a code that corresponds to their order from the [[Survey structure|survey structure]] (e.g. Q00001, Q0002, etc.);
***''By question group:'' If this option is chosen, each question will be allocated a code that corresponds to the group each of them belongs to and their order within that question group: (G1Q00001, G1Q00002, G2Q00001, etc.).
*'''Display/Export:''' For a comprehensive description of this functionality, check our wiki page on [[Exporting_a_survey_structure|LimeSurvey export functionality]];
*'''Survey participants:''' It is used when you would like to invite a group of people to be part of your survey and ensure that each person can only participate once. For further details, check the [[Survey_participants|survey participants wiki page]];
*'''Responses:''' It offers the survey administrator access to menus that allows him/her to see the stored responses, enter new data, export or import answers, and view the partially saved but not submitted answers. By clicking on the arrow, three options will show up:
**''Responses & Statistics:'' It displays a summary of all the stored survey responses and respondents;
**''Data entry screen:'' It allows the survey administrator to enter new data into his/her response tables. It is a useful function when you first record the answers from the survey participants offline and then you want to analyse their answers via the functionalities provided by LimeSurvey;
**''Partial (saved) responses:'' It displays the partially (but not submitted) saved responses.

=Survey toolbar options - structure= 


For a more comprehensive view on the survey toolbar and its capabilities, check the following wiki section links:


*[[Testing a survey]] - to test a survey, use the preview survey function and survey logic file (if you use expressions)


*[[Activating a survey]] - activate it only when you finished testing it and once Once you are happy with its structure


*[[Running a survey safely]] - certain options cannot be edited anymore once the survey is active in order to preserve the survey logic
**[[Changing an active survey]] - it is not possible to change from the LimeSurvey user interface the main settings of your survey. However, this can still be done via certain tricks, even though we recommend a lot of caution if you decide to rely on them


*[[Closing a survey]] - to close a survey, you can either choose to [[Closing_a_survey#Expiry|expire it]] or [[Closing_a_survey#Deactivation|deactivate it]]


*[[Iterate survey]] - read the following wiki subsection to use the same survey structure for the same set of participants and compare previous responses of one participant to those given later by him or her


*[[Tools]] - certain survey-related tools are available from this menu:
**[[Delete survey]] - deletes the current survey
**[[Quick-translation]] - to quickly translate the groups, questions, subquestions and/or answers used within your survey, use the following function instead of accessing separately every survey component
**[[Reset conditions]] - in the case in which you wish to reconstruct your survey or you wish to increase the complexity of your survey, use the following button to delete the current [[Setting conditions|conditions]]. Please also read the following [[ExpressionScript_-_Presentation#Can_I_mix_Conditions_and_Relevance_equations.3F|wiki subsection]] to see how you can use conditions and expressions within one survey
**[[Show logic file|Survey logic file]] - this functionality is important when you use complex relevance, tailoring, and validation equations
**[[Regenerate question codes]] - sometimes you can get lost in the question codes used across a long survey. To have the code names quickly reorganized, use this function to get all the question codes regenerated in a structured way


*[[Display/Export survey]] - to display or export your current survey, use this function
**[[QueXML PDF Export]] - the queXML PDF Export function allows for the export of the current survey in to a structured PDF file that is suitable for being processed using Optical Mark Recognition (OMR) software such as [https://quexf.sourceforge.net queXF]
**[[Tab Separated Value survey structure]] - this option is important for those who wish to edit a survey via spreadsheet software such as Excel, LibreOffice or Google Docs


*[[Survey participants]] - it is one of the most important functionalities provided by LimeSurvey. It allows you to invite a group of people to participate in your survey, keep track of who has completed the survey, and ensure that each person can only participate once


*[[Responses (survey results)]] - all the response- and statistics-related functions are listed here:
**[[Responses & statistics]] - focuses on the stored responses and statistics creation:
***[[Responses & statistics#Responses summary|Response summary]] - provides a quick overview of the current submitted summary
***[[Responses]] - it displays the response table;
***[[Data entry]] - to manually introduce responses into the survey response table, use this function. This is mainly used when survey responses were collected offline
***[[Statistics]] - provides simple and complex statistics, as well as the possibility to export your data outside LimeSurvey
****[[Statistics - simple mode]] - it makes use of the in-built statistics function to generate simple graphs and charts
****[[Statistics - expert mode]] - it allows you do select certain data to be displayed in the statistics. In the case in which the in-build expert mode is not sufficient for your needs, you can export the data in other formats to further analyse it by using other statistics-specialised software
***[[Timing statistics]] -
***[[Export responses]] - used to export survey responses
***[[Import responses]] - used to import responses gathered in other surveys
***[[View saved but not submitted responses]]
***[[Iterate survey]] - used to launch the same survey to the same set of survey participants to analyse trends
***[[Batch deletion]] - use this function to delete answers in batch
**[[Data entry]] - to manually introduce responses into the survey response table, use this function. This is mainly used when survey responses were collected offline
**[[Partial (saved) responses]] - under certain conditions users can resume later the survey to finish filling it in. The respective answers can be seen by you with the help of this function

</translate>