https://www.limesurvey.org/api.php?action=feedcontributions&feedformat=atom&user=SammousaLimeSurvey Manual - User contributions [en]2026-08-12T21:00:21ZUser contributionsMediaWiki 1.43.9https://www.limesurvey.org/manual/index.php?title=Plugins_-_advanced&diff=67878Plugins - advanced2016-05-10T11:51:12Z<p>Sammousa: /* API */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
Starting from LimeSurvey 2.05, LimeSurvey will officially support plugins. Some plugins will be supported by the LimeSurvey team and will go into core. Some will be supported by others outside the LimeSurvey team. To help find them, check out the [[Available third party plugins]] and add your own plugin to it!<br />
<br />
Plugins allow users to customize the functionality of their installation while still being able to benefit from regular software updates.<br />
<br />
This documentation is meant for developers that are extending LimeSurvey for their own use or for their clients; end users will not be helped by this documentation.<br />
<br />
Plugins must implement the [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/iPlugin.php iPlugin] interface. We recommend extending your plugin class from the [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/PluginBase.php PluginBase] class. <br />
<br />
Plugins are developed around an [http://manual.limesurvey.org/Plugin_events event] mechanism.<br />
<br />
== Plugin settings ==<br />
<br />
By extending you benefit from common functionality required by plugins that we already have implemented for you. One of these function is the implementation of the getPluginSettings function. This function must return an array describing the configuration options for the user.<br />
<br />
The example plugin exposes just 1 configurable setting, the message it'll show.<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
protected $settings = array(<br />
'logo' => array(<br />
'type' => 'logo',<br />
'path' => 'assets/logo.png'<br />
),<br />
<br />
'message' => array(<br />
'type' => 'string',<br />
'label' => 'Message'<br />
)<br />
);<br />
</syntaxhighlight><br />
<br />
The array contains a name for each setting as a key. The values are arrays containing the required meta data.<br />
<br />
Supported types are:<br />
<br />
* logo<br />
* string<br />
* html<br />
* choice<br />
* relevance<br />
* info<br />
<br />
Besides type a number of other keys are available:<br />
<br />
* label, defines a label (use English, the label specified here will be passed through the translation functions)<br />
* default, defines a value to show if no value is specified.<br />
* current, defines the current value.<br />
* readOnly, specifies the setting is read only.<br />
<br />
You can find a plugin example using all actual settings at https://framagit.org/Shnoulle/exampleSettings<br />
<br />
== Events ==<br />
<br />
Plugins subscribe to events and can interact with LimeSurvey when the event is fired. For a list of currently available events check [[Plugin events]].<br />
<br />
== API ==<br />
<br />
Plugins should only extend LimeSurvey via its "public" API. This means that directly using classes found in the source code is a bad practice. Though we can't force you not to, you risk having a broken plugin with every minor update we do.<br />
<br />
As much as possible interact with LimeSurvey only via methods described [http://api.limesurvey.org/classes/ls.pluginmanager.LimesurveyApi.html here]. Same as for events.<br />
<br />
New functions can be added to the API object upon request.<br />
<br />
The API object is available via `$this->api` when extending from PluginBase, otherwise you can get it from the PluginManager instance that is passed to your plugins' constructor.<br />
<br />
== Special plugins ==<br />
<br />
[[Authentication plugin development]]<br />
<br />
== Available plugins ==<br />
* [[Authentication plugins]]<br />
* [[Available third party plugins]]<br />
<br />
[[Category:Development]]<br />
[[Category:Plugins]]</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Plugins_-_advanced&diff=67876Plugins - advanced2016-05-10T09:13:59Z<p>Sammousa: </p>
<hr />
<div><br />
== Overview ==<br />
<br />
Starting from LimeSurvey 2.05, LimeSurvey will officially support plugins. Some plugins will be supported by the LimeSurvey team and will go into core. Some will be supported by others outside the LimeSurvey team. To help find them, check out the [[Available third party plugins]] and add your own plugin to it!<br />
<br />
Plugins allow users to customize the functionality of their installation while still being able to benefit from regular software updates.<br />
<br />
This documentation is meant for developers that are extending LimeSurvey for their own use or for their clients; end users will not be helped by this documentation.<br />
<br />
Plugins must implement the [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/iPlugin.php iPlugin] interface. We recommend extending your plugin class from the [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/PluginBase.php PluginBase] class. <br />
<br />
Plugins are developed around an [http://manual.limesurvey.org/Plugin_events event] mechanism.<br />
<br />
Plugins should only extend LS via its "public" API. This means that directly using classes found in the source code is a bad practice. Though we can't force you not to, you risk having a broken plugin with every minor update we do.<br />
As much as possible interact with LS only via http://api.limesurvey.org/classes/ls.pluginmanager.LimesurveyApi.html, same as for events.<br />
<br />
New functions can be added to the API object upon request.<br />
<br />
== Plugin settings ==<br />
<br />
By extending you benefit from common functionality required by plugins that we already have implemented for you. One of these function is the implementation of the getPluginSettings function. This function must return an array describing the configuration options for the user.<br />
<br />
The example plugin exposes just 1 configurable setting, the message it'll show.<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
protected $settings = array(<br />
'logo' => array(<br />
'type' => 'logo',<br />
'path' => 'assets/logo.png'<br />
),<br />
<br />
'message' => array(<br />
'type' => 'string',<br />
'label' => 'Message'<br />
)<br />
);<br />
</syntaxhighlight><br />
<br />
The array contains a name for each setting as a key. The values are arrays containing the required meta data.<br />
<br />
Supported types are:<br />
<br />
* logo<br />
* string<br />
* html<br />
* choice<br />
* relevance<br />
* info<br />
<br />
Besides type a number of other keys are available:<br />
<br />
* label, defines a label (use English, the label specified here will be passed through the translation functions)<br />
* default, defines a value to show if no value is specified.<br />
* current, defines the current value.<br />
* readOnly, specifies the setting is read only.<br />
<br />
You can find a plugin example using all actual settings at https://framagit.org/Shnoulle/exampleSettings<br />
<br />
== Events ==<br />
<br />
Plugins subscribe to events and can interact with LimeSurvey when the event is fired. For a list of currently available events check [[Plugin events]].<br />
<br />
== Special plugins ==<br />
[[Authentication plugin development]]<br />
<br />
== Available plugins ==<br />
* [[Authentication plugins]]<br />
* [[Available third party plugins]]<br />
<br />
[[Category:Development]]<br />
[[Category:Plugins]]</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Plugins_-_advanced&diff=67875Plugins - advanced2016-05-10T09:06:38Z<p>Sammousa: </p>
<hr />
<div><br />
== Overview ==<br />
<br />
Starting from LimeSurvey 2.05, LimeSurvey will officially support plugins. Some plugins will be supported by the LimeSurvey team and will go into core. Some will be supported by others outside the LimeSurvey team. To help find them, check out the [[Available third party plugins]] and add your own plugin to it!<br />
<br />
Plugins allow users to customize the functionality of their installation while still being able to benefit from regular software updates.<br />
<br />
This documentation is meant for developers that are extending LimeSurvey for their own use or for their clients; end users will not be helped by this documentation.<br />
<br />
Plugins must implement the [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/iPlugin.php iPlugin] interface. We recommend extending your plugin class from the [https://github.com/LimeSurvey/LimeSurvey/blob/master/application/libraries/PluginManager/PluginBase.php PluginBase] class. <br />
<br />
Plugins are developed around an [http://manual.limesurvey.org/Plugin_events event] mechanism.<br />
<br />
Plugins should only extend LS via its "public" API. This means that directly using classes found in the source code is a bad practice. Though we can't force you not to, you risk having a broken plugin with every minor update we do.<br />
As much as possible interact with LS only via http://api.limesurvey.org/classes/ls.pluginmanager.LimesurveyApi.html, same as for events, this API object can be extended upon request.<br />
<br />
== Plugin settings ==<br />
<br />
By extending you benefit from common functionality required by plugins that we already have implemented for you. One of these function is the implementation of the getPluginSettings function. This function must return an array describing the configuration options for the user.<br />
<br />
The example plugin exposes just 1 configurable setting, the message it'll show.<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
protected $settings = array(<br />
'logo' => array(<br />
'type' => 'logo',<br />
'path' => 'assets/logo.png'<br />
),<br />
<br />
'message' => array(<br />
'type' => 'string',<br />
'label' => 'Message'<br />
)<br />
);<br />
</syntaxhighlight><br />
<br />
The array contains a name for each setting as a key. The values are arrays containing the required meta data.<br />
<br />
Supported types are:<br />
<br />
* logo<br />
* string<br />
* html<br />
* choice<br />
* relevance<br />
* info<br />
<br />
Besides type a number of other keys are available:<br />
<br />
* label, defines a label (use English, the label specified here will be passed through the translation functions)<br />
* default, defines a value to show if no value is specified.<br />
* current, defines the current value.<br />
* readOnly, specifies the setting is read only.<br />
<br />
You can find a plugin example using all actual settings at https://framagit.org/Shnoulle/exampleSettings<br />
<br />
== Events ==<br />
<br />
Plugins subscribe to events and can interact with LimeSurvey when the event is fired. For a list of currently available events check [[Plugin events]].<br />
<br />
== Special plugins ==<br />
[[Authentication plugin development]]<br />
<br />
== Available plugins ==<br />
* [[Authentication plugins]]<br />
* [[Available third party plugins]]<br />
<br />
[[Category:Development]]<br />
[[Category:Plugins]]</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Talk:Plugins_-_advanced&diff=67615Talk:Plugins - advanced2016-04-27T21:06:37Z<p>Sammousa: </p>
<hr />
<div>Add a picture to show how each setting type look like.<br />
<br />
[[User:Olle|Olle]] ([[User talk:Olle|talk]]) 23:36, 22 April 2016 (CEST)<br />
<br />
TODO: Add information of each setting type:<br />
<br />
* logo<br />
* string<br />
* html<br />
* choice<br />
* relevance<br />
* info<br />
<br />
should rather be:<br />
<br />
{|<br />
! <b>Setting type</b> !! <b>Description</b> !! <b>Example usage</b><br />
|-<br />
| <code>logo</code> || Logo to what? Put a logo in HTML flow || near same than 'info' type <br />
|-<br />
| <code>string</code> || Enter string, htmlOptions needed for HTML5 validation || https://github.com/SondagesPro/LS-exportCompleteAnswers/blob/master/exportCompleteAnswers.php#L64<br />
|-<br />
| <code>float/integer</code> || Enter a number<br />
|-<br />
| <code>html</code> || a textearea with html editor for admin user (or public user ?)<br />
|-<br />
| <code>choice</code> || choice : select box, need htmlOptions (multiple) || https://github.com/SondagesPro/LS-moreAccessibility/blob/master/moreAccessibility.php#L32 , can be multiple.<br />
|-<br />
| <code>relevance</code> || Enter a relevance equation (this is basically a text editor++ think syntax highlighting / checking).<br />
|-<br />
| <code>password</code> || A password : to fix : don't show it in HTML flow. || for another tool (smtp/API ... etc)<br />
|-<br />
| <code>info</code> || Show information in the settings ||<br />
<syntaxhighlight lang="php"><br />
protected $settings = array(<br />
'PluginName_settingName' => array(<br />
'type' => 'info',<br />
'content' => 'This is some info'<br />
)<br />
);<br />
</syntaxhighlight> <br />
|}<br />
<br />
[[User:Olle|Olle]] ([[User talk:Olle|talk]]) 23:44, 22 April 2016 (CEST)<br />
<br />
We need a way to center info, or style it better by default. Also, it should use Bootstrap form-horizontal, the labels are not centered vertically as should.<br />
<br />
[[User:Olle|Olle]] ([[User talk:Olle|talk]]) 00:17, 23 April 2016 (CEST)<br />
<br />
TODO: Add support for tabs in the settings widget.<br />
<br />
[[User:Olle|Olle]] ([[User talk:Olle|talk]]) 15:37, 23 April 2016 (CEST)<br />
<br />
@todo : add 'lang" system : show directly html/textarea/input with all language of survey or global settings. Sam start something when save with extra data.<br />
[[User:DenisChenu|DenisChenu]] ([[User talk:DenisChenu|talk]]) 08:51, 27 April 2016 (CEST)<br />
<br />
<br />
Any information about plugins and translations?<br />
<br />
[[User:Olle|Olle]] ([[User talk:Olle|talk]]) 22:46, 25 April 2016 (CEST)<br />
<br />
@todo : bug reported on Feature request. It's a must have. Thii Yii::t directly is better for this [[User:DenisChenu|DenisChenu]] ([[User talk:DenisChenu|talk]]) 08:51, 27 April 2016 (CEST)<br />
<br />
Another feature request: A member variable that checks for LS version number.<br />
<br />
[[User:Olle|Olle]] ([[User talk:Olle|talk]]) 23:07, 25 April 2016 (CEST)<br />
<br />
Already can be done App()->getConfig("version"); I use it in one of my plugin, but don't remind where. [[User:DenisChenu|DenisChenu]] ([[User talk:DenisChenu|talk]]) 08:51, 27 April 2016 (CEST)</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_object_types&diff=67376Question object types2016-04-25T14:41:49Z<p>Sammousa: /* Storing custom question attributes */</p>
<hr />
<div>Question object types is about making questions in LS more object-oriented and modular, and letting users create and upload their own object types.<br />
<br />
<br />
Basically, every place in the code which is doing a switch on question type should be replaced by a polymorphic call to an object, e.g. <code>$object->renderFrontend();</code><br />
<br />
<br />
Old wiki page: https://manual.limesurvey.org/Question_Objects<br />
<br />
=== Use-cases ===<br />
<br />
* Colour picker - user click on a picture with colours, and the position in the picture defines the colour.<br />
* "... the surgeon would indicate the location of a fracture by drawing on a diagram of the knee."<br />
* Having more than one question in one "library" file, where some of the questions can be activated via a bought activation code.<br />
* Gender question as being a subtype of yes-no. Yes/No : subtype of "fixed list" ?<br />
<br />
=== Features ===<br />
<br />
TODO<br />
<br />
=== Open issues ===<br />
<br />
* Is array it's own object type, or is it a <i>property</i> of a question? Could we have an array of any question typ, e.g. yes/no questions?<br />
* Cross-cutting concerns: <br />
** What if the user wants to add a comment field to all questions in the survey? Use a plugin? Or time limit, which can be added to all questions, but shouldn't take up space if it's not used. Shnoulle/Sam recommends EAV table; Olle thinks it's too schema-less and that question types could modify the database instead. Actually all this part was in QuestionAttribute.<br />
*** Sam:<br />
**** I think we can identify some properties that apply to (almost) all question types, these should be in the question table (think EM expression, or mandatory or always hidden).<br />
**** Then there are properties that are specific for a question type, for example the maximum / minimum number for a text question, or the step size for a slider. Storing these in the main table as separate column will make create lots of columns with very sparse data. Alternatives are EAV or serialization. Note: LS core will never do anything with this data except retrieve / store it, so serialization is a valid option.<br />
**** Then there are generic question settings that someone might want to add support for, for example time_limit. There should be some way for plugins to add these settings to all questions and then handle their values when the time comes. -- This is something new and needs to be further explored.<br />
** Example of some part that can not be Question Type object, but must extend Question type <br />
*** Updating EM/core system : example for [[Question_type_-_Short_free_text#Always_hide_this_question_.28hidden.29|hidden]] or [[Question_type_-_Short_free_text#Randomization_group_name_.28random_group.29|random_group]], validation (em_validation, numeric, min , max ...)<br />
*** Updating HTML produced only [[Question_type_-_Short_free_text#Maximum_characters_.28maximum_chars.29|maximum_chars]], validation can update HTML part too : min+max+step on numeric for example (usage of type="number")<br />
*** Add some JS/css or some HTML element (addContent, registerScript ....) [[Question_type_-_Short_free_text#Time_limit_.28time_limit.29|time_limit]]<br />
* Composability: Should it be possible to combine two questions into one, or pick-and-choose among "question elements"?<br />
* Should we also change the way we save answer data? If yes, in which step - first or last? Which database design should we use instead?<br />
* Can we inherit views?<br />
* Interaction with plugins, e.g. Stata XML export? No other way around it than using switch in plugin, or each question type should itself supply a method the plugin can use?<br />
<br />
=== Implementation ===<br />
<br />
Object hierarchy.<br />
<br />
<br />
==== Methods ====<br />
<br />
This is a list of functions that question types could implement. They could be included in a "base interface" or abstract base class.<br />
<br />
<br />
{| <br />
! <b>Function name</b> !! <b>Meaning</b> !! <b> Mandatory </b><br />
|-<br />
| renderFrontend || Former qanda code; render question for survey taker || Y<br />
|-<br />
| renderDataEntryForm || Render form for manual insertion of data. NB: Same as renderFrontend? || Y<br />
|-<br />
| getSettings || Return settings (array) that can be used by a settings widget for edit form in backend || Y<br />
|-<br />
| renderCustomSettings || Possibly custom HTML settings?<br />
|-<br />
| getExportData || Way of exporting : data + "syntax of data" : SPSS/Stata/triple-S/etc ... Some "settings" can update this too (interger value for numeric for example)<br />
|-<br />
| getStatisticsData || Return statistics data that will be fed to a renderer (like HTML, PDF, etc) || Y<br />
|}<br />
<br />
<br />
Implemented as Yii module, with views, models and controllers (http://www.yiiframework.com/doc/guide/1.1/en/basics.module#creating-module).<br />
<br />
<br />
Replace switch-cases in:<br />
<br />
* Frontend render (render answers, qanda)<br />
* Backend render (edit question, file <code>questions.php</code>)<br />
* Statistics<br />
* SQL and database queries, included extra field the question might define<br />
* Expression manager<br />
<br />
Ideally, each switch case in the code should have a unit test or functional test to test it with.<br />
<br />
==== Current question types ====<br />
<br />
<br />
From statistics.php:<br />
<br />
* 1 - Array Dual Scale <br />
* 5 - 5 Point Choice<br />
* A - Array (5 Point Choice)<br />
* B - Array (10 Point Choice)<br />
* C - Array (Yes/No/Uncertain)<br />
* D - Date<br />
* E - Array (Increase, Same, Decrease)<br />
* F - Array (Flexible Labels)<br />
* G - Gender<br />
* H - Array (Flexible Labels) by Column<br />
* I - Language Switch<br />
* K - Multiple Numerical Input<br />
* L - List (Radio)<br />
* M - Multiple choice<br />
* N - Numerical Input<br />
* O - List With Comment<br />
* P - Multiple choice with comments<br />
* Q - Multiple Short Text<br />
* R - Ranking<br />
* S - Short Free Text<br />
* T - Long Free Text<br />
* U - Huge Free Text<br />
* X - Boilerplate Question<br />
* Y - Yes/No<br />
* ! - List (Dropdown)<br />
* : - Array (Flexible Labels) multiple drop down<br />
* ; - Array (Flexible Labels) multiple texts<br />
* | - File Upload<br />
<br />
<br />
Categories:<br />
<br />
* Single-choice questions<br />
* Arrays<br />
* Mask questions<br />
* Text questions<br />
* Multiple-choice questions<br />
<br />
=== Prototype/proof-of-concept ===<br />
<br />
As a first cycle of development (iteration), one could implement a completely new question type (say, drawing board) with the new system on top of the old one. The purpose would be to get a better feeling of the problem domain, what changes are needed, if the current approach is possible, and so on.<br />
<br />
<br />
After the prototype is done, the existent questions can be exported to the new system one by one. This represents a "horizontal" development style, where the complete problem is solved for _one_ case in the first cycle, in contrast to exporting the entire qanda to the new system, then the entire statistics module, etc. A horizontal style would give faster results and introduce lesser mechanical work, focusing on design and creativity which is needed in the beginning.<br />
<br />
<br />
Example from qanda:<br />
<br />
<br />
<syntaxhighlight lang="php">if (is_object($ia))<br />
{<br />
$ia->renderFrontend();<br />
}<br />
else<br />
{<br />
switch ($ia[4]) // $ia[4] is question type<br />
{<br />
case 'X': //BOILERPLATE QUESTION<br />
$values = do_boilerplate($ia);<br />
break;<br />
// and so on for all question types<br />
}<br />
}</syntaxhighlight><br />
<br />
<br />
When all questions have been exported to the new system, this snippet will just be:<br />
<br />
<br />
<syntaxhighlight lang="php"><br />
$ia->renderFrontend();<br />
</syntaxhighlight><br />
<br />
=== Current LS3 implementation ===<br />
<br />
Note, this is the current state and some of these are mostly because it is a refactoring from LS2.<br />
<br />
1. Uses an interface.<br />
<br />
2. Defines what columns it needs via a fieldname => column type map.<br />
<br />
3. Defines what EM expressions apply to it.<br />
<br />
4. Defines a render functionality that renders the content.<br />
<br />
5. Defines a list of classes that should be in the wrapping div.<br />
<br />
==== Storing custom question attributes ====<br />
<nowiki>Assumptions:<br />
1. All questions are always (partly) stored in the `Questions` table.<br />
2. There exist question attributes that are unknown (we don't know their names, their types and how many there are).<br />
3. Known question attributes (like: mandatory) are always stored normalized as a column in the `Questions` table, the list below applies only to custom attributes.<br />
<br />
<br />
Options for storing custom question attributes:<br />
<br />
1. Single Table Inheritance (Add columns to `questions` table).<br />
- Risk of collisions<br />
- Harder to import backups into environments that slightly differ.<br />
- Creates a very sparse table.<br />
+ Fast for retrieving<br />
+ Easy to support full model validation in Yii<br />
+ Easy to interpret database / SQL exports.<br />
o Full support for advanced queries / indexes (LS does not do advanced queries on this table)<br />
<br />
<br />
2. Use EAV.<br />
- Schemaless<br />
- No data types (everything is a string)<br />
+ Current approach.<br />
+ Easy to interpret database / SQL exports.<br />
o Little support for advanced queries (LS does not do advanced queries on this table)<br />
+ Easy to support full model validation in Yii<br />
- Requires transactions if we want to have atomic writes.<br />
<br />
3. Use EBLOB - store question attributes in a serialized form like JSON / XML.<br />
- Schemaless<br />
o More datatypes than EAV: string, int, float, bool, NULL. Fewer datatypes than STI or CTI.<br />
+ Fast for retrieving<br />
+ Easy to support full model validation in Yii<br />
o Little / slow support for advanced queries (LS does not do advanced queries on this table)<br />
o Write amplification (Yii writes the whole record regardless of what columns changed)<br />
- Unfriendly for direct database editing.<br />
<br />
<br />
4.Class table inheritance (Separate table per question type containing a PK that is a FK into `Questions`)<br />
+ Strict schema<br />
+ Easy to interpret database / SQL exports.<br />
- Requires transactions if we want to have atomic writes.<br />
- Complicated to implement in Yii.<br />
- Reading requires at least one query per question type, depending on implemention up to 1 query per question.<br />
</nowiki></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_object_types&diff=67375Question object types2016-04-25T14:34:35Z<p>Sammousa: /* Storing custom question attributes */</p>
<hr />
<div>Question object types is about making questions in LS more object-oriented and modular, and letting users create and upload their own object types.<br />
<br />
<br />
Basically, every place in the code which is doing a switch on question type should be replaced by a polymorphic call to an object, e.g. <code>$object->renderFrontend();</code><br />
<br />
<br />
Old wiki page: https://manual.limesurvey.org/Question_Objects<br />
<br />
=== Use-cases ===<br />
<br />
* Colour picker - user click on a picture with colours, and the position in the picture defines the colour.<br />
* "... the surgeon would indicate the location of a fracture by drawing on a diagram of the knee."<br />
* Having more than one question in one "library" file, where some of the questions can be activated via a bought activation code.<br />
* Gender question as being a subtype of yes-no. Yes/No : subtype of "fixed list" ?<br />
<br />
=== Features ===<br />
<br />
TODO<br />
<br />
=== Open issues ===<br />
<br />
* Is array it's own object type, or is it a <i>property</i> of a question? Could we have an array of any question typ, e.g. yes/no questions?<br />
* Cross-cutting concerns: <br />
** What if the user wants to add a comment field to all questions in the survey? Use a plugin? Or time limit, which can be added to all questions, but shouldn't take up space if it's not used. Shnoulle/Sam recommends EAV table; Olle thinks it's too schema-less and that question types could modify the database instead. Actually all this part was in QuestionAttribute.<br />
*** Sam:<br />
**** I think we can identify some properties that apply to (almost) all question types, these should be in the question table (think EM expression, or mandatory or always hidden).<br />
**** Then there are properties that are specific for a question type, for example the maximum / minimum number for a text question, or the step size for a slider. Storing these in the main table as separate column will make create lots of columns with very sparse data. Alternatives are EAV or serialization. Note: LS core will never do anything with this data except retrieve / store it, so serialization is a valid option.<br />
**** Then there are generic question settings that someone might want to add support for, for example time_limit. There should be some way for plugins to add these settings to all questions and then handle their values when the time comes. -- This is something new and needs to be further explored.<br />
** Example of some part that can not be Question Type object, but must extend Question type <br />
*** Updating EM/core system : example for [[Question_type_-_Short_free_text#Always_hide_this_question_.28hidden.29|hidden]] or [[Question_type_-_Short_free_text#Randomization_group_name_.28random_group.29|random_group]], validation (em_validation, numeric, min , max ...)<br />
*** Updating HTML produced only [[Question_type_-_Short_free_text#Maximum_characters_.28maximum_chars.29|maximum_chars]], validation can update HTML part too : min+max+step on numeric for example (usage of type="number")<br />
*** Add some JS/css or some HTML element (addContent, registerScript ....) [[Question_type_-_Short_free_text#Time_limit_.28time_limit.29|time_limit]]<br />
* Composability: Should it be possible to combine two questions into one, or pick-and-choose among "question elements"?<br />
* Should we also change the way we save answer data? If yes, in which step - first or last? Which database design should we use instead?<br />
* Can we inherit views?<br />
* Interaction with plugins, e.g. Stata XML export? No other way around it than using switch in plugin, or each question type should itself supply a method the plugin can use?<br />
<br />
=== Implementation ===<br />
<br />
Object hierarchy.<br />
<br />
<br />
==== Methods ====<br />
<br />
This is a list of functions that question types could implement. They could be included in a "base interface" or abstract base class.<br />
<br />
<br />
{| <br />
! <b>Function name</b> !! <b>Meaning</b> !! <b> Mandatory </b><br />
|-<br />
| renderFrontend || Former qanda code; render question for survey taker || Y<br />
|-<br />
| renderDataEntryForm || Render form for manual insertion of data. NB: Same as renderFrontend? || Y<br />
|-<br />
| getSettings || Return settings (array) that can be used by a settings widget for edit form in backend || Y<br />
|-<br />
| renderCustomSettings || Possibly custom HTML settings?<br />
|-<br />
| getExportData || Way of exporting : data + "syntax of data" : SPSS/Stata/triple-S/etc ... Some "settings" can update this too (interger value for numeric for example)<br />
|-<br />
| getStatisticsData || Return statistics data that will be fed to a renderer (like HTML, PDF, etc) || Y<br />
|}<br />
<br />
<br />
Implemented as Yii module, with views, models and controllers (http://www.yiiframework.com/doc/guide/1.1/en/basics.module#creating-module).<br />
<br />
<br />
Replace switch-cases in:<br />
<br />
* Frontend render (render answers, qanda)<br />
* Backend render (edit question, file <code>questions.php</code>)<br />
* Statistics<br />
* SQL and database queries, included extra field the question might define<br />
* Expression manager<br />
<br />
Ideally, each switch case in the code should have a unit test or functional test to test it with.<br />
<br />
==== Current question types ====<br />
<br />
<br />
From statistics.php:<br />
<br />
* 1 - Array Dual Scale <br />
* 5 - 5 Point Choice<br />
* A - Array (5 Point Choice)<br />
* B - Array (10 Point Choice)<br />
* C - Array (Yes/No/Uncertain)<br />
* D - Date<br />
* E - Array (Increase, Same, Decrease)<br />
* F - Array (Flexible Labels)<br />
* G - Gender<br />
* H - Array (Flexible Labels) by Column<br />
* I - Language Switch<br />
* K - Multiple Numerical Input<br />
* L - List (Radio)<br />
* M - Multiple choice<br />
* N - Numerical Input<br />
* O - List With Comment<br />
* P - Multiple choice with comments<br />
* Q - Multiple Short Text<br />
* R - Ranking<br />
* S - Short Free Text<br />
* T - Long Free Text<br />
* U - Huge Free Text<br />
* X - Boilerplate Question<br />
* Y - Yes/No<br />
* ! - List (Dropdown)<br />
* : - Array (Flexible Labels) multiple drop down<br />
* ; - Array (Flexible Labels) multiple texts<br />
* | - File Upload<br />
<br />
<br />
Categories:<br />
<br />
* Single-choice questions<br />
* Arrays<br />
* Mask questions<br />
* Text questions<br />
* Multiple-choice questions<br />
<br />
=== Prototype/proof-of-concept ===<br />
<br />
As a first cycle of development (iteration), one could implement a completely new question type (say, drawing board) with the new system on top of the old one. The purpose would be to get a better feeling of the problem domain, what changes are needed, if the current approach is possible, and so on.<br />
<br />
<br />
After the prototype is done, the existent questions can be exported to the new system one by one. This represents a "horizontal" development style, where the complete problem is solved for _one_ case in the first cycle, in contrast to exporting the entire qanda to the new system, then the entire statistics module, etc. A horizontal style would give faster results and introduce lesser mechanical work, focusing on design and creativity which is needed in the beginning.<br />
<br />
<br />
Example from qanda:<br />
<br />
<br />
<syntaxhighlight lang="php">if (is_object($ia))<br />
{<br />
$ia->renderFrontend();<br />
}<br />
else<br />
{<br />
switch ($ia[4]) // $ia[4] is question type<br />
{<br />
case 'X': //BOILERPLATE QUESTION<br />
$values = do_boilerplate($ia);<br />
break;<br />
// and so on for all question types<br />
}<br />
}</syntaxhighlight><br />
<br />
<br />
When all questions have been exported to the new system, this snippet will just be:<br />
<br />
<br />
<syntaxhighlight lang="php"><br />
$ia->renderFrontend();<br />
</syntaxhighlight><br />
<br />
=== Current LS3 implementation ===<br />
<br />
Note, this is the current state and some of these are mostly because it is a refactoring from LS2.<br />
<br />
1. Uses an interface.<br />
<br />
2. Defines what columns it needs via a fieldname => column type map.<br />
<br />
3. Defines what EM expressions apply to it.<br />
<br />
4. Defines a render functionality that renders the content.<br />
<br />
5. Defines a list of classes that should be in the wrapping div.<br />
<br />
==== Storing custom question attributes ====<br />
<nowiki>Assumptions:<br />
1. All questions are always (partly) stored in the `Questions` table.<br />
2. There exist question attributes that are unknown (we don't know their names, their types and how many there are).<br />
3. Known question attributes (like: mandatory) are always stored normalized as a column in the `Questions` table, the list below applies only to custom attributes.<br />
<br />
<br />
Options for storing custom question attributes:<br />
<br />
1. Single Table Inheritance (Add columns to `questions` table).<br />
- Risk of collisions<br />
- Harder to import backups into environments that slightly differ.<br />
- Creates a very sparse table.<br />
+ Fast for retrieving<br />
+ Easy to support full model validation in Yii<br />
+ Easy to interpret database / SQL exports.<br />
o Full support for advanced queries / indexes (LS does not do advanced queries on this table)<br />
<br />
<br />
2. Use EAV.<br />
- Schemaless<br />
- No data types (everything is a string)<br />
+ Current approach.<br />
+ Easy to interpret database / SQL exports.<br />
o Little support for advanced queries (LS does not do advanced queries on this table)<br />
+ Easy to support full model validation in Yii<br />
- Requires transactions if we want to have atomic writes.<br />
<br />
3. Use EBLOB - store question attributes in a serialized form like JSON / XML.<br />
- Schemaless<br />
o More datatypes than EAV: string, int, float, bool, NULL. Fewer datatypes than STI or CTI.<br />
+ Fast for retrieving<br />
+ Easy to support full model validation in Yii<br />
o Little / slow support for advanced queries (LS does not do advanced queries on this table)<br />
o Write amplification (Yii writes the whole record regardless of what columns changed)<br />
- Unfriendly for direct database editing.<br />
<br />
<br />
4.Class table inheritance (Separate table per question type containing a PK that is a FK into `Questions`)<br />
+ Strict schema<br />
+ Easy to interpret database / SQL exports.<br />
- Requires transactions if we want to have atomic writes.<br />
</nowiki></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_object_types&diff=67374Question object types2016-04-25T14:30:57Z<p>Sammousa: /* Storing custom question attributes */</p>
<hr />
<div>Question object types is about making questions in LS more object-oriented and modular, and letting users create and upload their own object types.<br />
<br />
<br />
Basically, every place in the code which is doing a switch on question type should be replaced by a polymorphic call to an object, e.g. <code>$object->renderFrontend();</code><br />
<br />
<br />
Old wiki page: https://manual.limesurvey.org/Question_Objects<br />
<br />
=== Use-cases ===<br />
<br />
* Colour picker - user click on a picture with colours, and the position in the picture defines the colour.<br />
* "... the surgeon would indicate the location of a fracture by drawing on a diagram of the knee."<br />
* Having more than one question in one "library" file, where some of the questions can be activated via a bought activation code.<br />
* Gender question as being a subtype of yes-no. Yes/No : subtype of "fixed list" ?<br />
<br />
=== Features ===<br />
<br />
TODO<br />
<br />
=== Open issues ===<br />
<br />
* Is array it's own object type, or is it a <i>property</i> of a question? Could we have an array of any question typ, e.g. yes/no questions?<br />
* Cross-cutting concerns: <br />
** What if the user wants to add a comment field to all questions in the survey? Use a plugin? Or time limit, which can be added to all questions, but shouldn't take up space if it's not used. Shnoulle/Sam recommends EAV table; Olle thinks it's too schema-less and that question types could modify the database instead. Actually all this part was in QuestionAttribute.<br />
*** Sam:<br />
**** I think we can identify some properties that apply to (almost) all question types, these should be in the question table (think EM expression, or mandatory or always hidden).<br />
**** Then there are properties that are specific for a question type, for example the maximum / minimum number for a text question, or the step size for a slider. Storing these in the main table as separate column will make create lots of columns with very sparse data. Alternatives are EAV or serialization. Note: LS core will never do anything with this data except retrieve / store it, so serialization is a valid option.<br />
**** Then there are generic question settings that someone might want to add support for, for example time_limit. There should be some way for plugins to add these settings to all questions and then handle their values when the time comes. -- This is something new and needs to be further explored.<br />
** Example of some part that can not be Question Type object, but must extend Question type <br />
*** Updating EM/core system : example for [[Question_type_-_Short_free_text#Always_hide_this_question_.28hidden.29|hidden]] or [[Question_type_-_Short_free_text#Randomization_group_name_.28random_group.29|random_group]], validation (em_validation, numeric, min , max ...)<br />
*** Updating HTML produced only [[Question_type_-_Short_free_text#Maximum_characters_.28maximum_chars.29|maximum_chars]], validation can update HTML part too : min+max+step on numeric for example (usage of type="number")<br />
*** Add some JS/css or some HTML element (addContent, registerScript ....) [[Question_type_-_Short_free_text#Time_limit_.28time_limit.29|time_limit]]<br />
* Composability: Should it be possible to combine two questions into one, or pick-and-choose among "question elements"?<br />
* Should we also change the way we save answer data? If yes, in which step - first or last? Which database design should we use instead?<br />
* Can we inherit views?<br />
* Interaction with plugins, e.g. Stata XML export? No other way around it than using switch in plugin, or each question type should itself supply a method the plugin can use?<br />
<br />
=== Implementation ===<br />
<br />
Object hierarchy.<br />
<br />
<br />
==== Methods ====<br />
<br />
This is a list of functions that question types could implement. They could be included in a "base interface" or abstract base class.<br />
<br />
<br />
{| <br />
! <b>Function name</b> !! <b>Meaning</b> !! <b> Mandatory </b><br />
|-<br />
| renderFrontend || Former qanda code; render question for survey taker || Y<br />
|-<br />
| renderDataEntryForm || Render form for manual insertion of data. NB: Same as renderFrontend? || Y<br />
|-<br />
| getSettings || Return settings (array) that can be used by a settings widget for edit form in backend || Y<br />
|-<br />
| renderCustomSettings || Possibly custom HTML settings?<br />
|-<br />
| getExportData || Way of exporting : data + "syntax of data" : SPSS/Stata/triple-S/etc ... Some "settings" can update this too (interger value for numeric for example)<br />
|-<br />
| getStatisticsData || Return statistics data that will be fed to a renderer (like HTML, PDF, etc) || Y<br />
|}<br />
<br />
<br />
Implemented as Yii module, with views, models and controllers (http://www.yiiframework.com/doc/guide/1.1/en/basics.module#creating-module).<br />
<br />
<br />
Replace switch-cases in:<br />
<br />
* Frontend render (render answers, qanda)<br />
* Backend render (edit question, file <code>questions.php</code>)<br />
* Statistics<br />
* SQL and database queries, included extra field the question might define<br />
* Expression manager<br />
<br />
Ideally, each switch case in the code should have a unit test or functional test to test it with.<br />
<br />
==== Current question types ====<br />
<br />
<br />
From statistics.php:<br />
<br />
* 1 - Array Dual Scale <br />
* 5 - 5 Point Choice<br />
* A - Array (5 Point Choice)<br />
* B - Array (10 Point Choice)<br />
* C - Array (Yes/No/Uncertain)<br />
* D - Date<br />
* E - Array (Increase, Same, Decrease)<br />
* F - Array (Flexible Labels)<br />
* G - Gender<br />
* H - Array (Flexible Labels) by Column<br />
* I - Language Switch<br />
* K - Multiple Numerical Input<br />
* L - List (Radio)<br />
* M - Multiple choice<br />
* N - Numerical Input<br />
* O - List With Comment<br />
* P - Multiple choice with comments<br />
* Q - Multiple Short Text<br />
* R - Ranking<br />
* S - Short Free Text<br />
* T - Long Free Text<br />
* U - Huge Free Text<br />
* X - Boilerplate Question<br />
* Y - Yes/No<br />
* ! - List (Dropdown)<br />
* : - Array (Flexible Labels) multiple drop down<br />
* ; - Array (Flexible Labels) multiple texts<br />
* | - File Upload<br />
<br />
<br />
Categories:<br />
<br />
* Single-choice questions<br />
* Arrays<br />
* Mask questions<br />
* Text questions<br />
* Multiple-choice questions<br />
<br />
=== Prototype/proof-of-concept ===<br />
<br />
As a first cycle of development (iteration), one could implement a completely new question type (say, drawing board) with the new system on top of the old one. The purpose would be to get a better feeling of the problem domain, what changes are needed, if the current approach is possible, and so on.<br />
<br />
<br />
After the prototype is done, the existent questions can be exported to the new system one by one. This represents a "horizontal" development style, where the complete problem is solved for _one_ case in the first cycle, in contrast to exporting the entire qanda to the new system, then the entire statistics module, etc. A horizontal style would give faster results and introduce lesser mechanical work, focusing on design and creativity which is needed in the beginning.<br />
<br />
<br />
Example from qanda:<br />
<br />
<br />
<syntaxhighlight lang="php">if (is_object($ia))<br />
{<br />
$ia->renderFrontend();<br />
}<br />
else<br />
{<br />
switch ($ia[4]) // $ia[4] is question type<br />
{<br />
case 'X': //BOILERPLATE QUESTION<br />
$values = do_boilerplate($ia);<br />
break;<br />
// and so on for all question types<br />
}<br />
}</syntaxhighlight><br />
<br />
<br />
When all questions have been exported to the new system, this snippet will just be:<br />
<br />
<br />
<syntaxhighlight lang="php"><br />
$ia->renderFrontend();<br />
</syntaxhighlight><br />
<br />
=== Current LS3 implementation ===<br />
<br />
Note, this is the current state and some of these are mostly because it is a refactoring from LS2.<br />
<br />
1. Uses an interface.<br />
<br />
2. Defines what columns it needs via a fieldname => column type map.<br />
<br />
3. Defines what EM expressions apply to it.<br />
<br />
4. Defines a render functionality that renders the content.<br />
<br />
5. Defines a list of classes that should be in the wrapping div.<br />
<br />
==== Storing custom question attributes ====<br />
<nowiki>Assumptions:<br />
1. All questions are always (partly) stored in the `Questions` table.<br />
2. There exist question attributes that are unknown (we don't know their names, their types and how many there are).<br />
3. Known question attributes (like: mandatory) are always stored normalized as a column in the `Questions` table, the list below applies only to custom attributes.<br />
<br />
<br />
Options for storing custom question attributes:<br />
<br />
1. Single Table Inheritance (Add columns to `questions` table).<br />
- Risk of collisions<br />
- Harder to import backups into environments that slightly differ.<br />
- Creates a very sparse table.<br />
+ Fast for retrieving<br />
+ Easy to support full model validation in Yii<br />
o Full support for advanced queries / indexes (LS does not do advanced queries on this table)<br />
<br />
<br />
2. Use EAV.<br />
- Schemaless<br />
- No data types (everything is a string)<br />
+ Current approach.<br />
+ Easier to interpret database / SQL exports.<br />
o Little support for advanced queries (LS does not do advanced queries on this table)<br />
+ Easy to support full model validation in Yii<br />
- Requires transactions if we want to have atomic writes.<br />
<br />
3. Use EBLOB - store question attributes in a serialized form like JSON / XML.<br />
- Schemaless<br />
o More datatypes than EAV: string, int, float, bool, NULL. Fewer datatypes than STI or CTI.<br />
+ Fast for retrieving<br />
+ Easy to support full model validation in Yii<br />
o Little / slow support for advanced queries (LS does not do advanced queries on this table)<br />
o Write amplification (Yii writes the whole record regardless of what columns changed)<br />
- Unfriendly for direct database editing.<br />
<br />
<br />
4.Class table inheritance (Separate table per question type containing a PK that is a FK into `Questions`)<br />
+ Strict schema<br />
- Requires transactions if we want to have atomic writes.<br />
</nowiki></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_object_types&diff=67373Question object types2016-04-25T14:28:56Z<p>Sammousa: /* Storing custom question attributes */</p>
<hr />
<div>Question object types is about making questions in LS more object-oriented and modular, and letting users create and upload their own object types.<br />
<br />
<br />
Basically, every place in the code which is doing a switch on question type should be replaced by a polymorphic call to an object, e.g. <code>$object->renderFrontend();</code><br />
<br />
<br />
Old wiki page: https://manual.limesurvey.org/Question_Objects<br />
<br />
=== Use-cases ===<br />
<br />
* Colour picker - user click on a picture with colours, and the position in the picture defines the colour.<br />
* "... the surgeon would indicate the location of a fracture by drawing on a diagram of the knee."<br />
* Having more than one question in one "library" file, where some of the questions can be activated via a bought activation code.<br />
* Gender question as being a subtype of yes-no. Yes/No : subtype of "fixed list" ?<br />
<br />
=== Features ===<br />
<br />
TODO<br />
<br />
=== Open issues ===<br />
<br />
* Is array it's own object type, or is it a <i>property</i> of a question? Could we have an array of any question typ, e.g. yes/no questions?<br />
* Cross-cutting concerns: <br />
** What if the user wants to add a comment field to all questions in the survey? Use a plugin? Or time limit, which can be added to all questions, but shouldn't take up space if it's not used. Shnoulle/Sam recommends EAV table; Olle thinks it's too schema-less and that question types could modify the database instead. Actually all this part was in QuestionAttribute.<br />
*** Sam:<br />
**** I think we can identify some properties that apply to (almost) all question types, these should be in the question table (think EM expression, or mandatory or always hidden).<br />
**** Then there are properties that are specific for a question type, for example the maximum / minimum number for a text question, or the step size for a slider. Storing these in the main table as separate column will make create lots of columns with very sparse data. Alternatives are EAV or serialization. Note: LS core will never do anything with this data except retrieve / store it, so serialization is a valid option.<br />
**** Then there are generic question settings that someone might want to add support for, for example time_limit. There should be some way for plugins to add these settings to all questions and then handle their values when the time comes. -- This is something new and needs to be further explored.<br />
** Example of some part that can not be Question Type object, but must extend Question type <br />
*** Updating EM/core system : example for [[Question_type_-_Short_free_text#Always_hide_this_question_.28hidden.29|hidden]] or [[Question_type_-_Short_free_text#Randomization_group_name_.28random_group.29|random_group]], validation (em_validation, numeric, min , max ...)<br />
*** Updating HTML produced only [[Question_type_-_Short_free_text#Maximum_characters_.28maximum_chars.29|maximum_chars]], validation can update HTML part too : min+max+step on numeric for example (usage of type="number")<br />
*** Add some JS/css or some HTML element (addContent, registerScript ....) [[Question_type_-_Short_free_text#Time_limit_.28time_limit.29|time_limit]]<br />
* Composability: Should it be possible to combine two questions into one, or pick-and-choose among "question elements"?<br />
* Should we also change the way we save answer data? If yes, in which step - first or last? Which database design should we use instead?<br />
* Can we inherit views?<br />
* Interaction with plugins, e.g. Stata XML export? No other way around it than using switch in plugin, or each question type should itself supply a method the plugin can use?<br />
<br />
=== Implementation ===<br />
<br />
Object hierarchy.<br />
<br />
<br />
==== Methods ====<br />
<br />
This is a list of functions that question types could implement. They could be included in a "base interface" or abstract base class.<br />
<br />
<br />
{| <br />
! <b>Function name</b> !! <b>Meaning</b> !! <b> Mandatory </b><br />
|-<br />
| renderFrontend || Former qanda code; render question for survey taker || Y<br />
|-<br />
| renderDataEntryForm || Render form for manual insertion of data. NB: Same as renderFrontend? || Y<br />
|-<br />
| getSettings || Return settings (array) that can be used by a settings widget for edit form in backend || Y<br />
|-<br />
| renderCustomSettings || Possibly custom HTML settings?<br />
|-<br />
| getExportData || Way of exporting : data + "syntax of data" : SPSS/Stata/triple-S/etc ... Some "settings" can update this too (interger value for numeric for example)<br />
|-<br />
| getStatisticsData || Return statistics data that will be fed to a renderer (like HTML, PDF, etc) || Y<br />
|}<br />
<br />
<br />
Implemented as Yii module, with views, models and controllers (http://www.yiiframework.com/doc/guide/1.1/en/basics.module#creating-module).<br />
<br />
<br />
Replace switch-cases in:<br />
<br />
* Frontend render (render answers, qanda)<br />
* Backend render (edit question, file <code>questions.php</code>)<br />
* Statistics<br />
* SQL and database queries, included extra field the question might define<br />
* Expression manager<br />
<br />
Ideally, each switch case in the code should have a unit test or functional test to test it with.<br />
<br />
==== Current question types ====<br />
<br />
<br />
From statistics.php:<br />
<br />
* 1 - Array Dual Scale <br />
* 5 - 5 Point Choice<br />
* A - Array (5 Point Choice)<br />
* B - Array (10 Point Choice)<br />
* C - Array (Yes/No/Uncertain)<br />
* D - Date<br />
* E - Array (Increase, Same, Decrease)<br />
* F - Array (Flexible Labels)<br />
* G - Gender<br />
* H - Array (Flexible Labels) by Column<br />
* I - Language Switch<br />
* K - Multiple Numerical Input<br />
* L - List (Radio)<br />
* M - Multiple choice<br />
* N - Numerical Input<br />
* O - List With Comment<br />
* P - Multiple choice with comments<br />
* Q - Multiple Short Text<br />
* R - Ranking<br />
* S - Short Free Text<br />
* T - Long Free Text<br />
* U - Huge Free Text<br />
* X - Boilerplate Question<br />
* Y - Yes/No<br />
* ! - List (Dropdown)<br />
* : - Array (Flexible Labels) multiple drop down<br />
* ; - Array (Flexible Labels) multiple texts<br />
* | - File Upload<br />
<br />
<br />
Categories:<br />
<br />
* Single-choice questions<br />
* Arrays<br />
* Mask questions<br />
* Text questions<br />
* Multiple-choice questions<br />
<br />
=== Prototype/proof-of-concept ===<br />
<br />
As a first cycle of development (iteration), one could implement a completely new question type (say, drawing board) with the new system on top of the old one. The purpose would be to get a better feeling of the problem domain, what changes are needed, if the current approach is possible, and so on.<br />
<br />
<br />
After the prototype is done, the existent questions can be exported to the new system one by one. This represents a "horizontal" development style, where the complete problem is solved for _one_ case in the first cycle, in contrast to exporting the entire qanda to the new system, then the entire statistics module, etc. A horizontal style would give faster results and introduce lesser mechanical work, focusing on design and creativity which is needed in the beginning.<br />
<br />
<br />
Example from qanda:<br />
<br />
<br />
<syntaxhighlight lang="php">if (is_object($ia))<br />
{<br />
$ia->renderFrontend();<br />
}<br />
else<br />
{<br />
switch ($ia[4]) // $ia[4] is question type<br />
{<br />
case 'X': //BOILERPLATE QUESTION<br />
$values = do_boilerplate($ia);<br />
break;<br />
// and so on for all question types<br />
}<br />
}</syntaxhighlight><br />
<br />
<br />
When all questions have been exported to the new system, this snippet will just be:<br />
<br />
<br />
<syntaxhighlight lang="php"><br />
$ia->renderFrontend();<br />
</syntaxhighlight><br />
<br />
=== Current LS3 implementation ===<br />
<br />
Note, this is the current state and some of these are mostly because it is a refactoring from LS2.<br />
<br />
1. Uses an interface.<br />
<br />
2. Defines what columns it needs via a fieldname => column type map.<br />
<br />
3. Defines what EM expressions apply to it.<br />
<br />
4. Defines a render functionality that renders the content.<br />
<br />
5. Defines a list of classes that should be in the wrapping div.<br />
<br />
==== Storing custom question attributes ====<br />
<nowiki>Assumptions:<br />
1. All questions are always (partly) stored in the `Questions` table.<br />
2. There exist question attributes that are unknown (we don't know their names, their types and how many there are).<br />
3. Known question attributes (like: mandatory) are always stored normalized as a column in the `Questions` table, the list below applies only to custom attributes.<br />
<br />
<br />
Options for storing custom question attributes:<br />
<br />
1. Single Table Inheritance (Add columns to `questions` table).<br />
- Risk of collisions<br />
- Harder to import backups into environments that slightly differ.<br />
- Creates a very sparse table.<br />
+ Fast for retrieving<br />
+ Easy to support full model validation in Yii<br />
o Full support for advanced queries / indexes (LS does not do advanced queries on this table)<br />
<br />
<br />
2. Use EAV.<br />
- Schemaless<br />
- No data types (everything is a string)<br />
+ Current approach.<br />
o Little support for advanced queries (LS does not do advanced queries on this table)<br />
+ Easy to support full model validation in Yii<br />
- Requires transactions if we want to have atomic writes.<br />
<br />
3. Use EBLOB - store question attributes in a serialized form like JSON / XML.<br />
- Schemaless<br />
o More datatypes than EAV: string, int, float, bool, NULL. Fewer datatypes than STI or CTI.<br />
+ Fast for retrieving<br />
+ Easy to support full model validation in Yii<br />
o Little / slow support for advanced queries (LS does not do advanced queries on this table)<br />
o Write amplification (Yii writes the whole record regardless of what columns changed)<br />
- Unfriendly for direct database editing.<br />
<br />
<br />
4.Class table inheritance (Separate table per question type containing a PK that is a FK into `Questions`)<br />
+ Strict schema<br />
- Requires transactions if we want to have atomic writes.<br />
</nowiki></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_object_types&diff=67372Question object types2016-04-25T14:09:10Z<p>Sammousa: </p>
<hr />
<div>Question object types is about making questions in LS more object-oriented and modular, and letting users create and upload their own object types.<br />
<br />
<br />
Basically, every place in the code which is doing a switch on question type should be replaced by a polymorphic call to an object, e.g. <code>$object->renderFrontend();</code><br />
<br />
<br />
Old wiki page: https://manual.limesurvey.org/Question_Objects<br />
<br />
=== Use-cases ===<br />
<br />
* Colour picker - user click on a picture with colours, and the position in the picture defines the colour.<br />
* "... the surgeon would indicate the location of a fracture by drawing on a diagram of the knee."<br />
* Having more than one question in one "library" file, where some of the questions can be activated via a bought activation code.<br />
* Gender question as being a subtype of yes-no. Yes/No : subtype of "fixed list" ?<br />
<br />
=== Features ===<br />
<br />
TODO<br />
<br />
=== Open issues ===<br />
<br />
* Is array it's own object type, or is it a <i>property</i> of a question? Could we have an array of any question typ, e.g. yes/no questions?<br />
* Cross-cutting concerns: <br />
** What if the user wants to add a comment field to all questions in the survey? Use a plugin? Or time limit, which can be added to all questions, but shouldn't take up space if it's not used. Shnoulle/Sam recommends EAV table; Olle thinks it's too schema-less and that question types could modify the database instead. Actually all this part was in QuestionAttribute.<br />
*** Sam:<br />
**** I think we can identify some properties that apply to (almost) all question types, these should be in the question table (think EM expression, or mandatory or always hidden).<br />
**** Then there are properties that are specific for a question type, for example the maximum / minimum number for a text question, or the step size for a slider. Storing these in the main table as separate column will make create lots of columns with very sparse data. Alternatives are EAV or serialization. Note: LS core will never do anything with this data except retrieve / store it, so serialization is a valid option.<br />
**** Then there are generic question settings that someone might want to add support for, for example time_limit. There should be some way for plugins to add these settings to all questions and then handle their values when the time comes. -- This is something new and needs to be further explored.<br />
** Example of some part that can not be Question Type object, but must extend Question type <br />
*** Updating EM/core system : example for [[Question_type_-_Short_free_text#Always_hide_this_question_.28hidden.29|hidden]] or [[Question_type_-_Short_free_text#Randomization_group_name_.28random_group.29|random_group]], validation (em_validation, numeric, min , max ...)<br />
*** Updating HTML produced only [[Question_type_-_Short_free_text#Maximum_characters_.28maximum_chars.29|maximum_chars]], validation can update HTML part too : min+max+step on numeric for example (usage of type="number")<br />
*** Add some JS/css or some HTML element (addContent, registerScript ....) [[Question_type_-_Short_free_text#Time_limit_.28time_limit.29|time_limit]]<br />
* Composability: Should it be possible to combine two questions into one, or pick-and-choose among "question elements"?<br />
* Should we also change the way we save answer data? If yes, in which step - first or last? Which database design should we use instead?<br />
* Can we inherit views?<br />
* Interaction with plugins, e.g. Stata XML export? No other way around it than using switch in plugin, or each question type should itself supply a method the plugin can use?<br />
<br />
=== Implementation ===<br />
<br />
Object hierarchy.<br />
<br />
<br />
==== Methods ====<br />
<br />
This is a list of functions that question types could implement. They could be included in a "base interface" or abstract base class.<br />
<br />
<br />
{| <br />
! <b>Function name</b> !! <b>Meaning</b> !! <b> Mandatory </b><br />
|-<br />
| renderFrontend || Former qanda code; render question for survey taker || Y<br />
|-<br />
| renderDataEntryForm || Render form for manual insertion of data. NB: Same as renderFrontend? || Y<br />
|-<br />
| getSettings || Return settings (array) that can be used by a settings widget for edit form in backend || Y<br />
|-<br />
| renderCustomSettings || Possibly custom HTML settings?<br />
|-<br />
| getExportData || Way of exporting : data + "syntax of data" : SPSS/Stata/triple-S/etc ... Some "settings" can update this too (interger value for numeric for example)<br />
|-<br />
| getStatisticsData || Return statistics data that will be fed to a renderer (like HTML, PDF, etc) || Y<br />
|}<br />
<br />
<br />
Implemented as Yii module, with views, models and controllers (http://www.yiiframework.com/doc/guide/1.1/en/basics.module#creating-module).<br />
<br />
<br />
Replace switch-cases in:<br />
<br />
* Frontend render (render answers, qanda)<br />
* Backend render (edit question, file <code>questions.php</code>)<br />
* Statistics<br />
* SQL and database queries, included extra field the question might define<br />
* Expression manager<br />
<br />
Ideally, each switch case in the code should have a unit test or functional test to test it with.<br />
<br />
==== Current question types ====<br />
<br />
<br />
From statistics.php:<br />
<br />
* 1 - Array Dual Scale <br />
* 5 - 5 Point Choice<br />
* A - Array (5 Point Choice)<br />
* B - Array (10 Point Choice)<br />
* C - Array (Yes/No/Uncertain)<br />
* D - Date<br />
* E - Array (Increase, Same, Decrease)<br />
* F - Array (Flexible Labels)<br />
* G - Gender<br />
* H - Array (Flexible Labels) by Column<br />
* I - Language Switch<br />
* K - Multiple Numerical Input<br />
* L - List (Radio)<br />
* M - Multiple choice<br />
* N - Numerical Input<br />
* O - List With Comment<br />
* P - Multiple choice with comments<br />
* Q - Multiple Short Text<br />
* R - Ranking<br />
* S - Short Free Text<br />
* T - Long Free Text<br />
* U - Huge Free Text<br />
* X - Boilerplate Question<br />
* Y - Yes/No<br />
* ! - List (Dropdown)<br />
* : - Array (Flexible Labels) multiple drop down<br />
* ; - Array (Flexible Labels) multiple texts<br />
* | - File Upload<br />
<br />
<br />
Categories:<br />
<br />
* Single-choice questions<br />
* Arrays<br />
* Mask questions<br />
* Text questions<br />
* Multiple-choice questions<br />
<br />
=== Prototype/proof-of-concept ===<br />
<br />
As a first cycle of development (iteration), one could implement a completely new question type (say, drawing board) with the new system on top of the old one. The purpose would be to get a better feeling of the problem domain, what changes are needed, if the current approach is possible, and so on.<br />
<br />
<br />
After the prototype is done, the existent questions can be exported to the new system one by one. This represents a "horizontal" development style, where the complete problem is solved for _one_ case in the first cycle, in contrast to exporting the entire qanda to the new system, then the entire statistics module, etc. A horizontal style would give faster results and introduce lesser mechanical work, focusing on design and creativity which is needed in the beginning.<br />
<br />
<br />
Example from qanda:<br />
<br />
<br />
<syntaxhighlight lang="php">if (is_object($ia))<br />
{<br />
$ia->renderFrontend();<br />
}<br />
else<br />
{<br />
switch ($ia[4]) // $ia[4] is question type<br />
{<br />
case 'X': //BOILERPLATE QUESTION<br />
$values = do_boilerplate($ia);<br />
break;<br />
// and so on for all question types<br />
}<br />
}</syntaxhighlight><br />
<br />
<br />
When all questions have been exported to the new system, this snippet will just be:<br />
<br />
<br />
<syntaxhighlight lang="php"><br />
$ia->renderFrontend();<br />
</syntaxhighlight><br />
<br />
=== Current LS3 implementation ===<br />
<br />
Note, this is the current state and some of these are mostly because it is a refactoring from LS2.<br />
<br />
1. Uses an interface.<br />
<br />
2. Defines what columns it needs via a fieldname => column type map.<br />
<br />
3. Defines what EM expressions apply to it.<br />
<br />
4. Defines a render functionality that renders the content.<br />
<br />
5. Defines a list of classes that should be in the wrapping div.<br />
<br />
==== Storing custom question attributes ====<br />
<nowiki>Assumptions:<br />
1. All questions are always (partly) stored in the `Questions` table.<br />
2. There exist question attributes that are unknown (we don't know their names, their types and how many there are).<br />
3. Known question attributes (like: mandatory) are always stored normalized as a column in the `Questions` table, the list below applies only to custom attributes.<br />
<br />
<br />
Options for storing custom question attributes:<br />
<br />
1. Single Table Inheritance (Add columns to `questions` table).<br />
- Risk of collisions<br />
- Harder to import backups into environments that slightly differ.<br />
- Creates a very sparse table.<br />
+ Fast for retrieving<br />
+ Easy to support full model validation in Yii<br />
o Full support for advanced queries / indexes (LS does not do advanced queries on this table)<br />
<br />
<br />
2. Use EAV.<br />
- Schemaless<br />
+ Current approach.<br />
o Little support for advanced queries (LS does not do advanced queries on this table)<br />
+ Easy to support full model validation in Yii<br />
- Requires transactions if we want to have atomic writes.<br />
<br />
3. Use EBLOB - store question attributes in a serialized form like JSON / XML.<br />
- Schemaless<br />
+ Fast for retrieving<br />
+ Easy to support full model validation in Yii<br />
o Little / slow support for advanced queries (LS does not do advanced queries on this table)<br />
o Write amplification (Yii writes the whole record regardless of what columns changed)<br />
- Unfriendly for direct database editing.<br />
<br />
<br />
4.Class table inheritance (Separate table per question type containing a PK that is a FK into `Questions`)<br />
+ Strict schema<br />
- Requires transactions if we want to have atomic writes.<br />
</nowiki></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_object_types&diff=67332Question object types2016-04-25T11:13:50Z<p>Sammousa: </p>
<hr />
<div>Question object types is about making questions in LS more object-oriented and modular, and letting users create and upload their own object types.<br />
<br />
<br />
Basically, every place in the code which is doing a switch on question type should be replaced by a polymorphic call to an object, e.g. <code>$object->renderFrontend();</code><br />
<br />
<br />
Old wiki page: https://manual.limesurvey.org/Question_Objects<br />
<br />
=== Use-cases ===<br />
<br />
* Colour picker - user click on a picture with colours, and the position in the picture defines the colour.<br />
* "... the surgeon would indicate the location of a fracture by drawing on a diagram of the knee."<br />
* Having more than one question in one "library" file, where some of the questions can be activated via a bought activation code.<br />
<br />
=== Features ===<br />
<br />
TODO<br />
<br />
=== Open issues ===<br />
<br />
* Is array it's own object type, or is it a <i>property</i> of a question? Could we have an array of any question typ, e.g. yes/no questions?<br />
* Cross-cutting concerns: <br />
** What if the user wants to add a comment field to all questions in the survey? Use a plugin? Or time limit, which can be added to all questions, but shouldn't take up space if it's not used. Shnoulle/Sam recommends EAV table; Olle thinks it's too schema-less and that question types could modify the database instead. Actually all this part was in QuestionAttribute.<br />
<br />
*** Sam:<br />
**** I think we can identify some properties that apply to (almost) all question types, these should be in the question table (think EM expression, or mandatory or always hidden).<br />
**** Then there are properties that are specific for a question type, for example the maximum / minimum number for a text question, or the step size for a slider. Storing these in the main table as separate column will make create lots of columns with very sparse data. Alternatives are EAV or serialization. Note: LS core will never do anything with this data except retrieve / store it, so serialization is a valid option.<br />
**** Then there are generic question settings that someone might want to add support for, for example time_limit. There should be some way for plugins to add these settings to all questions and then handle their values when the time comes. -- This is something new and needs to be further explored.<br />
<br />
<br />
** Example of some part that can not be Question Type object, but must extend Question type <br />
*** Updating EM/core system : example for [[Question_type_-_Short_free_text#Always_hide_this_question_.28hidden.29|hidden]] or [[Question_type_-_Short_free_text#Randomization_group_name_.28random_group.29|random_group]], validation (em_validation, numeric, min , max ...)<br />
*** Updating HTML produced only [[Question_type_-_Short_free_text#Maximum_characters_.28maximum_chars.29|maximum_chars]], validation can update HTML part too : min+max+step on numeric for example (usage of type="number")<br />
*** Add some JS/css or some HTML element (addContent, registerScript ....) [[Question_type_-_Short_free_text#Time_limit_.28time_limit.29|time_limit]]<br />
* Composability: Should it be possible to combine two questions into one, or pick-and-choose among "question elements"?<br />
* Should we also change the way we save answer data? If yes, in which step - first or last? Which database design should we use instead?<br />
* Can we inherit views?<br />
* Interaction with plugins, e.g. Stata XML export? No other way around it than using switch in plugin, or each question type should itself supply a method the plugin can use?<br />
<br />
=== Implementation ===<br />
<br />
Object hierarchy.<br />
<br />
<br />
==== Methods ====<br />
<br />
This is a list of functions that question types could implement. They could be included in a "base interface" or abstract base class.<br />
<br />
<br />
{| <br />
! <b>Function name</b> !! <b>Meaning</b> !! <b> Mandatory </b><br />
|-<br />
| renderFrontend || Former qanda code; render question for survey taker || Y<br />
|-<br />
| renderDataEntryForm || Render form for manual insertion of data. NB: Same as renderFrontend? || Y<br />
|-<br />
| getSettings || Return settings (array) that can be used by a settings widget for edit form in backend || Y<br />
|-<br />
| renderCustomSettings || Possibly custom HTML settings?<br />
|-<br />
| getStatisticsData || Return statistics data that will be fed to a renderer (like HTML, PDF, etc) || Y<br />
|}<br />
<br />
<br />
Implemented as Yii module, with views, models and controllers (http://www.yiiframework.com/doc/guide/1.1/en/basics.module#creating-module).<br />
<br />
<br />
Replace switch-cases in:<br />
<br />
* Frontend render (render answers, qanda)<br />
* Backend render (edit question, file <code>questions.php</code>)<br />
* Statistics<br />
* SQL and database queries, included extra field the question might define<br />
* Expression manager<br />
<br />
Ideally, each switch case in the code should have a unit test or functional test to test it with.<br />
<br />
==== Current question types ====<br />
<br />
<br />
From statistics.php:<br />
<br />
* 1 - Array Dual Scale <br />
* 5 - 5 Point Choice<br />
* A - Array (5 Point Choice)<br />
* B - Array (10 Point Choice)<br />
* C - Array (Yes/No/Uncertain)<br />
* D - Date<br />
* E - Array (Increase, Same, Decrease)<br />
* F - Array (Flexible Labels)<br />
* G - Gender<br />
* H - Array (Flexible Labels) by Column<br />
* I - Language Switch<br />
* K - Multiple Numerical Input<br />
* L - List (Radio)<br />
* M - Multiple choice<br />
* N - Numerical Input<br />
* O - List With Comment<br />
* P - Multiple choice with comments<br />
* Q - Multiple Short Text<br />
* R - Ranking<br />
* S - Short Free Text<br />
* T - Long Free Text<br />
* U - Huge Free Text<br />
* X - Boilerplate Question<br />
* Y - Yes/No<br />
* ! - List (Dropdown)<br />
* : - Array (Flexible Labels) multiple drop down<br />
* ; - Array (Flexible Labels) multiple texts<br />
* | - File Upload<br />
<br />
<br />
Categories:<br />
<br />
* Single-choice questions<br />
* Arrays<br />
* Mask questions<br />
* Text questions<br />
* Multiple-choice questions<br />
<br />
=== Prototype/proof-of-concept ===<br />
<br />
As a first cycle of development (iteration), one could implement a completely new question type (say, drawing board) with the new system on top of the old one. The purpose would be to get a better feeling of the problem domain, what changes are needed, if the current approach is possible, and so on.<br />
<br />
<br />
After the prototype is done, the existent questions can be exported to the new system one by one. This represents a "horizontal" development style, where the complete problem is solved for _one_ case in the first cycle, in contrast to exporting the entire qanda to the new system, then the entire statistics module, etc. A horizontal style would give faster results and introduce lesser mechanical work, focusing on design and creativity which is needed in the beginning.<br />
<br />
<br />
Example from qanda:<br />
<br />
<br />
<syntaxhighlight lang="php">if (is_object($ia))<br />
{<br />
$ia->renderFrontend();<br />
}<br />
else<br />
{<br />
switch ($ia[4]) // $ia[4] is question type<br />
{<br />
case 'X': //BOILERPLATE QUESTION<br />
$values = do_boilerplate($ia);<br />
break;<br />
// and so on for all question types<br />
}<br />
}</syntaxhighlight><br />
<br />
<br />
When all questions have been exported to the new system, this snippet will just be:<br />
<br />
<br />
<syntaxhighlight lang="php"><br />
$ia->renderFrontend();<br />
</syntaxhighlight><br />
<br />
=== Current LS3 implementation ===<br />
<br />
Note, this is the current state and some of these are mostly because it is a refactoring from LS2.<br />
<br />
1. Uses an interface.<br />
<br />
2. Defines what columns it needs via a fieldname => column type map.<br />
<br />
3. Defines what EM expressions apply to it.<br />
<br />
4. Defines a render functionality that renders the content.<br />
<br />
5. Defines a list of classes that should be in the wrapping div.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Talk:Question_object_types&diff=66990Talk:Question object types2016-04-21T09:50:09Z<p>Sammousa: </p>
<hr />
<div>== Question object specification text ==<br />
<br />
# I think specification is not the same as (our) implementation.<br />
#: Olle: True. But the current implementation in LS3 lacks specification. There needs to be something written down that exactly specifies what's needed and why.<br />
#:: Sam: Agree, the current implementation is just a refactoring of LS2 code (moving global functions to OO), it can and should be adapted to whatever requirements come up with.<br />
# Specifications should consist of interfaces (and optionally abstract classes) only.<br />
#: Olle: Question types will need to include CSS, Javascript, HTML, pictures etc. So only interfaces is not enough.<br />
#:: Sam: It doesn't matter what they include, we just need to specify how it should interact. For example, for example how it tells us what javascript / css to publish to a publicly accessible directory. Note that I agree that we should give a "logically structured" example plugin, that should not be part of the contract in my opinion.<br />
<br />
== Current LS3 implementation ==<br />
Note, this is the current state and some of these are mostly because it is a refactoring from LS2.<br />
<br />
1. Uses an interface.<br />
<br />
2. Defines what columns it needs via a fieldname => column type map.<br />
<br />
3. Defines what EM expressions apply to it.<br />
<br />
4. Defines a render functionality that renders the content.<br />
<br />
5. Defines a list of classes that should be in the wrapping div.<br />
<br />
#: Sam: Regarding the current minimum requirements with 6 render functions:<br />
(11:44:52 AM) sammousa: @ollehar, I don't like the 5 render functions on the question interface<br />
<br />
(11:45:34 AM) sammousa: 3 of them are for statistics, but instead there should be 1 "canonical" form for statistical information that LS can then properly render into different formats<br />
<br />
(11:45:50 AM) sammousa: (I don't want to implement a new question type just to have it use a different kind of display for statistics)<br />
<br />
(11:46:24 AM) sammousa: Also I don't think we should have renderEditForm, but instead we should provide some format where a question can define its settings.<br />
<br />
(11:46:49 AM) sammousa: Having each question render HTML will make templating practically impossible; also when I develop a new type of question<br />
<br />
(11:47:10 AM) sammousa: I don't want to think about HTML code for the settings, I just want to say: setting A is a boolean setting</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Talk:Question_object_types&diff=66989Talk:Question object types2016-04-21T09:49:47Z<p>Sammousa: </p>
<hr />
<div>== Question object specification text ==<br />
<br />
# I think specification is not the same as (our) implementation.<br />
#: Olle: True. But the current implementation in LS3 lacks specification. There needs to be something written down that exactly specifies what's needed and why.<br />
#:: Sam: Agree, the current implementation is just a refactoring of LS2 code (moving global functions to OO), it can and should be adapted to whatever requirements come up with.<br />
# Specifications should consist of interfaces (and optionally abstract classes) only.<br />
#: Olle: Question types will need to include CSS, Javascript, HTML, pictures etc. So only interfaces is not enough.<br />
#:: Sam: It doesn't matter what they include, we just need to specify how it should interact. For example, for example how it tells us what javascript / css to publish to a publicly accessible directory. Note that I agree that we should give a "logically structured" example plugin, that should not be part of the contract in my opinion.<br />
<br />
== Current LS3 implementation ==<br />
Note, this is the current state and some of these are mostly because it is a refactoring from LS2.<br />
<br />
1. Uses an interface.<br />
<br />
2. Defines what columns it needs via a fieldname => column type map.<br />
<br />
3. Defines what EM expressions apply to it.<br />
<br />
4. Defines a render functionality that renders the content.<br />
<br />
5. Defines a list of classes that should be in the wrapping div.<br />
<br />
#: Sam: Regarding the current minimum requirements with 6 render functions:<br />
(11:44:52 AM) sammousa: @ollehar, I don't like the 5 render functions on the question interface<br />
(11:45:34 AM) sammousa: 3 of them are for statistics, but instead there should be 1 "canonical" form for statistical information that LS can then properly render into different formats<br />
(11:45:50 AM) sammousa: (I don't want to implement a new question type just to have it use a different kind of display for statistics)<br />
(11:46:24 AM) sammousa: Also I don't think we should have renderEditForm, but instead we should provide some format where a question can define its settings.<br />
(11:46:49 AM) sammousa: Having each question render HTML will make templating practically impossible; also when I develop a new type of question<br />
(11:47:10 AM) sammousa: I don't want to think about HTML code for the settings, I just want to say: setting A is a boolean setting</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Talk:Question_object_types&diff=66684Talk:Question object types2016-04-12T16:32:33Z<p>Sammousa: /* Question object specification text */</p>
<hr />
<div>== Question object specification text ==<br />
<br />
# I think specification is not the same as (our) implementation.<br />
## Olle: True. But the current implementation in LS3 lacks specification. There needs to be something written down that exactly specifies what's needed and why.<br />
## Sam: Agree, the current implementation is just a refactoring of LS2 code (moving global functions to OO), it can and should be adapted to whatever requirements come up with.<br />
# Specifications should consist of interfaces (and optionally abstract classes) only.<br />
## Olle: Question types will need to include CSS, Javascript, HTML, pictures etc. So only interfaces is not enough.<br />
## Sam: It doesn't matter what they include, we just need to specify how it should interact. For example, for example how it tells us what javascript / css to publish to a publicly accessible directory. Note that I agree that we should give a "logically structured" example plugin, that should not be part of the contract in my opinion.<br />
<br />
== Current LS3 implementation ==<br />
Note, this is the current state and some of these are mostly because it is a refactoring from LS2.<br />
<br />
1. Uses an interface.<br />
<br />
2. Defines what columns it needs via a fieldname => column type map.<br />
<br />
3. Defines what EM expressions apply to it.<br />
<br />
4. Defines a render functionality that renders the content.<br />
<br />
5. Defines a list of classes that should be in the wrapping div.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Talk:Question_object_types&diff=66676Talk:Question object types2016-04-12T13:02:02Z<p>Sammousa: </p>
<hr />
<div>== Question object specification text ==<br />
1. I think specification is not the same as (our) implementation.<br />
<br />
2. Specifications should consist of interfaces (and optionally abstract classes) only.<br />
<br />
== Current LS3 implementation ==<br />
Note, this is the current state and some of these are mostly because it is a refactoring from LS2.<br />
<br />
1. Uses an interface.<br />
<br />
2. Defines what columns it needs via a fieldname => column type map.<br />
<br />
3. Defines what EM expressions apply to it.<br />
<br />
4. Defines a render functionality that renders the content.<br />
<br />
5. Defines a list of classes that should be in the wrapping div.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Talk:Question_object_types&diff=66675Talk:Question object types2016-04-12T12:55:17Z<p>Sammousa: Created page with "Question object specification 1. I think specification is not the same as (our) implementation. 2. Specifications should consist of interfaces (and optionally abstract classes..."</p>
<hr />
<div>Question object specification<br />
1. I think specification is not the same as (our) implementation.<br />
2. Specifications should consist of interfaces (and optionally abstract classes) only.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Plugin_events&diff=66033Plugin events2015-07-02T08:50:05Z<p>Sammousa: </p>
<hr />
<div>At version 2.05+ build 140320 the following events are available for plugins to subscribe to:<br />
*[[Authentication plugin development#afterLoginFormSubmit|afterLoginFormSubmit]]<br />
*[[Authentication plugin development#afterLogout|afterLogout]]<br />
*[[afterPluginLoad]]<br />
*[[afterSurveyComplete]]<br />
*[[afterSurveyQuota]]{{NewIn|v=2.05|b=141006}}<br />
*[[beforeActivate]]<br />
*[[beforeDeactivate]]<br />
*[[beforeHasPermission]]{{NewIn|v=2.06}}<br />
*[[beforeLoadResponse]]<br />
*[[beforeLogin]]<br />
*[[beforeLogout]]<br />
*[[beforeQuestionRender]]{{NewIn|v=2.05|b=140922}}<br />
*[[beforeRegister]]{{NewIn|v=2.06}}<br />
*[[beforeRegisterForm]]{{NewIn|v=2.06}}<br />
*[[beforePermissionSetSave]]<br />
*[[beforeSurveyPage]]{{NewIn|v=2.05|b=140109}}<br />
*[[beforeSurveySettings]]<br />
*[[beforeTokenEmail]]{{NewIn|v=2.05|b=140404}}<br />
*[[cron]]{{NewIn|v=2.05|b=140404}}<br />
*[[listExportOptions]]<br />
*[[listExportPlugins]]<br />
*[[listQuestionPlugins]]<br />
*[[newDirectRequest]]<br />
*[[newExport]]<br />
*[[newLoginForm]]<br />
*[[newSurveySettings]]<br />
*[[newUserSession]]<br />
<br />
[[Category:Development]]<br />
[[Category:Plugins]]</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Feature:alloweditaftercompletion&diff=64711Feature:alloweditaftercompletion2015-04-03T09:43:52Z<p>Sammousa: </p>
<hr />
<div>When enabled this will allow users to edit their response after completion.<br />
A user can get access to edit his or her response in several ways:<br />
*When using tokens, by clicking the token link. <br />
*When not using tokens, by using the "bookmark my survey" button.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Feature:alloweditaftercompletion&diff=64710Feature:alloweditaftercompletion2015-04-03T09:43:34Z<p>Sammousa: </p>
<hr />
<div>{{DISPLAYTITLE:Allow editing after completion}} <br />
When enabled this will allow users to edit their response after completion.<br />
A user can get access to edit his or her response in several ways:<br />
*When using tokens, by clicking the token link. <br />
*When not using tokens, by using the "bookmark my survey" button.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Feature:alloweditaftercompletion&diff=64708Feature:alloweditaftercompletion2015-04-03T09:39:58Z<p>Sammousa: Created page with "When enabled this will allow users to edit their response after completion. A user can get access to edit his or her response in several ways: *When using tokens, by clicking..."</p>
<hr />
<div>When enabled this will allow users to edit their response after completion.<br />
A user can get access to edit his or her response in several ways:<br />
*When using tokens, by clicking the token link. <br />
*When not using tokens, by using the "bookmark my survey" button.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Project_ideas_for_GSoC_2015&diff=64427Project ideas for GSoC 20152015-02-24T15:10:47Z<p>Sammousa: /* Make use of the SettingsWidget for core functions */</p>
<hr />
<div>=Welcome, Google Summer of Code student aspirants!=<br />
<br />
This page lists project ideas developed by the LimeSurvey Community - '''please note that we have applied as organization for GSoC 2015 but we are currently waiting if we will get accepted into this great program, again'''. <br />
<br />
The ideas listed here are the ones that will get the most support since they have been developed by people who know the project and what it needs the most. However, if you have your own project idea for LimeSurvey please discuss your awesome idea with us in our [https://www.limesurvey.org/en/forum/development forums], [https://lists.sourceforge.net/lists/listinfo/limesurvey-developers mailing list] or in our [https://www.limesurvey.org/en/community-services/live-chat IRC channel at #limesurvey on irc.freenode.net]. <br />
<br />
You can also find alot of ideas for new features in our [http://bugs.limesurvey.org/set_project.php?ref=view_all_set.php&project_id=12 feature tracker] <br />
<br />
Also have a look at our following documents:<br />
<br />
*[[GSoC FAQ]] <br />
*[[GSoC getting started]]<br />
*[[GSoC selection criteria]]<br />
*[[GSoC Student Application Template]]<br />
<br />
We are looking forward to your proposal. Good luck!<br />
<br />
=Project ideas=<br />
<br />
==Visualize different paths through a survey based on conditions set at a survey==<br />
<br />
Limesurvey's Expression Manager (EM) allows [https://manual.limesurvey.org/Expression_Manager#Relevance_.28Controlling_Navigation.2FBranching.29 adding complex conditions] to survey questions so that certain questions are only shown if those conditions validate to "true". At lengthy surveys with lots of conditions this will create several different potentials paths through a survey depending on the answers given by a user.<br />
To help our growing user base to deal with this complex problem we plan to create a fully new tool for visualizing the different paths through a survey based on the existing conditions.<br />
<br />
<br />
'''Steps'''<br />
# Have a look at the [https://manual.limesurvey.org/Expression_Manager Expression Manager documentation] to get familiar with this powerful tool for creating complex conditions<br />
# Check how conditions are stored at the database<br />
# Analyse how EM internally handles conditions to determine whether a question should be displayed <br />
# Test conditions of different complexity at different survey levels (single question vs survey groups)<br />
# Do some research on tools which can be used for visualizing paths e.g. [http://diagramo.com/Diagramo]. Make sure the licence is compatible with the [https://www.limesurvey.org/en/about-limesurvey/license Limesurvey licence]<br />
# Describe the architecture of your program and how you plan to integrate it into Limesurvey. Discuss your approach with your mentor<br />
# Start coding a first test version based on simple conditions and short surveys. Test how this scales when it comes to larger surveys and more complex conditions.<br />
# Share your first version with other developers and Limesurvey users so they can test their own complex surveys.<br />
<br />
'''Skills'''<br />
<br />
You should know about PHP MVC architcture and PHP frameworks (we are using [http://www.yiiframework.com/ Yii] framework) because most development will be PHP code.<br />
You should also know SQL because your scirpts will need to query the DB for existing conditions. Some HTML + CSS will help for creating a nice visualization of the different paths.<br />
<br />
'''Difficulty'''<br />
<br />
Medium<br />
<br />
'''Mentor(s)'''<br />
<br />
Carsten Schmitz, Marcel Minke ([[User:Mazi|Mazi]])<br />
<br />
==Update Limesurvey Template Engine to use Twig==<br />
<br />
Currently Limesurvey uses its own custom coded template engine. Since the framework used for Limesurvey ("[http://www.yiiframework.com/ Yii]") supports the [http://www.yiiframework.com/ Twig] template engine we plan to replace the custom coded template engine with Twig's template engine for better code maintenance and embedding with the Yii framework. Extra credits would get you if you introduce customized template functions - so a user can easily change logo, logo placement and colors for a specific template using the template editor.<br />
<br />
'''Steps'''<br />
# Check how the current Limesurvey templates are structured<br />
# Dig into the related code to find out how the underlying Limesurvey template engine works<br />
# Get familiar with the structure of Twig templates <br />
# Test-edit one of the shipped templates and make it twig-compatible<br />
# Embed the Twig template engine into Limesurvey<br />
# Test your test template and the Twig template engine carefully<br />
# Adjust further shipped Limesurvey templates<br />
<br />
'''Skills'''<br />
<br />
You should know how a template engine and framework works. In addition to that HTML and CSS skills are required for adjusting the shipped Limesurvey templates.<br />
You should also know about PHP because switching the template engine will require adjustments of the Limesurvey source code as well.<br />
<br />
'''Difficulty'''<br />
<br />
Easy to medium<br />
<br />
'''Mentor(s)'''<br />
<br />
Marcel Minke ([[User:Mazi|Mazi]])<br />
<br />
==Remove jQuery UI and replace it with Bootstrap, harmonize GUI of different admin screens==<br />
<br />
The Limesurvey admin GUI currently uses a mixture of jQuery UI and Bootstrap code. That does not only make the related code difficult to maintain, it also creates a lot of overhead.<br />
In addition to that, the different admin screens are not overall standardized and lack harmonization.<br />
<br />
This task aims at standardizing the ~20-25 different Limesurvey admin screens and cleaning up the underlying code for easier maintenance and faster loading times.<br />
<br />
<br />
'''Steps'''<br />
# Click through the different screen at the Limesurvey admin interface. Note which screens already look nice and which ones are not following the overall design standards.<br />
# Take a look at the related source code and MVC views to see how the code for the views is structured and which libraries are used.<br />
# Note where at the code jQuery UI is used.<br />
# Test how to best remove the jQuery UI elements and what is needed to replace that code with Bootstrap features.<br />
# Adjust the admin GUI code to make it fully Bootstrap compatible.<br />
# Check all Limesurvey admin screens, standardize the layout/design and polish them where needed.<br />
<br />
<br />
'''Skills'''<br />
<br />
You should be familiar with jQuery UI and Bootstrap and known about HTML + CSS. A basic understanding of the MVC coding approach as well as some PHP coding skills are also helpful.<br />
<br />
<br />
'''Difficulty'''<br />
<br />
Easy to medium<br />
<br />
'''Mentor(s)'''<br />
<br />
* Marcel Minke ([[User:Mazi|Mazi]])<br />
* Carsten Schmitz<br />
* [[User:DenisChenu|Denis Chenu]]<br />
<br />
==Re-organize the Limesurvey Admin Interface for better Navigation Usability==<br />
<br />
When creating a survey at the Limesurvey admin interface the current page structure is:<br />
survey list -> survey question groups -> questions (within the current group)<br />
<br />
That structure forces users to often navigate using the drop down and back/next buttons when dealing with larger surveys. Having a new menu on the left presenting a structured overview of all question groups with all their questions would help a lot to easily jump from question X to question Y.<br />
That new overview should contain icons for:<br />
* Deleting a question/question group<br />
* Directly jumping to the survey question/question group edit mode<br />
* Copying a survey question<br />
* Adding a new question/question group at the appropriate survey section<br />
<br />
'''Steps'''<br />
# Check how the current Limesurvey survey designer is structured<br />
# Have a look at the different features available on the different levels (survey/question group/question)<br />
# Think which features could additionally be added to the icon list above<br />
# Check the related code for creating a full overview of question groups + questions<br />
# Adjust the admin GUI to embed the additional overview on the left<br />
# Create the code for the new overview and the functions presented by the different icons (most of that code is already there)<br />
# Testing, testing, testing...<br />
<br />
'''Skills'''<br />
<br />
You should be familiar with the "[http://www.yiiframework.com/ Yii]" framework we are using for Limesurvey or at least other PHP frameworks. A good understanding of object-oriented PHP programmierung is required as well.<br />
For adjusting the GUI moderate HTML + CSS skills are needed.<br />
<br />
'''Difficulty'''<br />
<br />
Easy<br />
<br />
'''Mentor(s)'''<br />
<br />
Carsten Schmitz<br />
<br />
==Make use of the SettingsWidget for core functions==<br />
<br />
Use and update (if needed) extension SettingsWidget for core Survey forms.<br />
<br />
Some forms to be updated:<br />
<br />
* Survey settings<br />
* Personal settings<br />
* Users settings (IN LS3 users' settings are managed by the authentication plugin and already use SettingsWidget)<br />
* Export settings<br />
<br />
'''Skills'''<br />
<br />
PHP, html, js and css<br />
<br />
'''Difficulty'''<br />
<br />
Easy to moderate : some settings can be more diffcult<br />
<br />
'''Link on mantis'''<br />
<br />
* [http://bugs.limesurvey.org/view.php?id=9523 SettingsWidget :renderHTML]<br />
* [http://bugs.limesurvey.org/view.php?id=9501 SettingsWidget :renderDate / DateTime and Time]<br />
<br />
'''Mentor(s)'''<br />
<br />
[[User:DenisChenu|Denis Chenu]]<br />
<br />
==Expression Manager JavaScript optimizations==<br />
<br />
Actually the Expression Manager in LimeSurvey uses inline JavaScript for relevance, updating classes and updating HTML. In its current state an administrator or extension developer can not use their own functions. The task is to update Expression manager inline JavaScript to use an JavaScript-only event on update expression manager javascript to call an actual function on this events.<br />
<br />
The second part of this task is to move inline Javascript to jQuery. In the old current system each input (when taking a survey) uses the onchange/onkeyup function to fire events. The idea is to remove these inline code and use only JavaScript/jQuery general code where possible.<br />
<br />
'''Skills'''<br />
<br />
Some PHP to update Expression Manager class, deep jQuery/JavaScript knowledge. A jQuery plugin might be a great idea.<br />
<br />
'''Difficulty'''<br />
<br />
Moderate<br />
<br />
'''Mantis'''<br />
* [http://bugs.limesurvey.org/view.php?id=8725 Replace Expression manager Hard coded javascript by event]<br />
<br />
<br />
'''Mentor(s)'''<br />
<br />
[[User:DenisChenu|Denis Chenu]]<br />
<br />
== Revamp database grids in LimeSurvey==<br />
<br />
We have various data table/lists in LimeSurvey - for example when listing surveys, tokens or responses.<br />
With most of these lists we use jqGrid, some don't use any Javascript widget at all.<br />
<br />
All instances of data lists in LimeSurvey should be replaced with a proper Javascript grid (which has to be chosen yet) and a related widget in Yii. As smarter as you will choose the data grid and as better the related Yii widget is coded as easier you will be able to replace the existing jqGrid with your better version.<br />
<br />
All lists need to be customized in some way - for example with token editing we will need mass editing functions - for example you should be able to set all tokens to be unused, reset invitation/reminder date/time or similar. <br />
<br />
'''Skills'''<br />
<br />
*Good PHP and JavaScript skills<br />
*Experience with jQuery and Bootstrap, AJAX<br />
<br />
'''Difficulty'''<br />
<br />
Medium difficulty - getting accustomed to the Yii 1.1 widget system and replacing the existing jqGrid functionality will be the difficult part.<br />
<br />
'''Mentor(s)'''<br />
<br />
*[[User:C_schmitz|Carsten Schmitz]]<br />
*Sam Mousa<br />
<br />
==Replace current CKEditor usage with TinyMCE==<br />
<br />
LimeSurvey currently uses extensively CKEditor to let people edit their survey texts (question, answer options, general survey texts) and invitation emails.<br />
However the CKEditor version we are using is outdated and some components are difficult to update due to CKeditor limitations. Also we use a customized CKeditor widget and a file browser widget that needs to be replaced with newer & better versions. <br />
<br />
We have concluded that TinyMCE will be the best replacement as the codebase is very stable and it offers a plugin interface.<br />
<br />
Your task would be to replace CKEditor instances with TinyMCE - also a widget for Yii should be written to ease any future implementation.<br />
As mentioned before the functionality of the existing CKEditor extensions need to be ported as TinyMCE plugins.<br />
<br />
This task is linked with [[#Make_use_of_the_SettingsWidget_for_core_functions]]<br />
'''Skills'''<br />
<br />
*Good PHP and JavaScript skills<br />
*Experience with jQuery and Bootstrap, AJAX<br />
<br />
<br />
'''Difficulty'''<br />
<br />
Medium difficulty - getting accustomed to the Yii 1.1 widget system and replacing the existing CKEditor functionality will be the difficult part.<br />
<br />
<br />
'''Mentor(s)'''<br />
<br />
*[[User:C_schmitz|Carsten Schmitz]]<br />
*Sam Mousa<br />
*[[User:DenisChenu|Denis Chenu]]<br />
<br />
==Idea template==<br />
<br />
Describe the idea here in general terms<br />
<br />
'''Skills'''<br />
<br />
Explain what sort of coding skills would be needed for a student to implement this project<br />
<br />
'''Difficulty'''<br />
<br />
Explain the level of difficulty involved<br />
<br />
'''Mentor(s)'''<br />
<br />
Put your name (and tag) here if you are willing to mentor a student for this idea<br />
<br />
=Additional links=<br />
==Official GSoC links==<br />
*[https://www.google-melange.com/gsoc/homepage/google/gsoc2015 GSoC 2015 website]<br />
*[https://www.google-melange.com/gsoc/events/google/gsoc2015 GSoC 2015 Timeline/Deadlines]<br />
*[https://www.google-melange.com/gsoc/document/show/gsoc_program/google/gsoc2015/help_page GSoC 2015 FAQ page]<br />
<br />
==Limesurvey coding details==<br />
*[https://manual.limesurvey.org/Coding_guidelines Limesurvey coding guidelines]<br />
*[https://manual.limesurvey.org/Accessing_the_source_code Accessing the Limesurvey source code]<br />
*[https://manual.limesurvey.org/Standard_for_Git_commit_messages Standard GIT commit messages]<br />
*[https://manual.limesurvey.org/Directory_structure Limesurvey code base and directory structure]<br />
*[https://manual.limesurvey.org/Yii Basic Yii framework information]<br />
<br />
==General information==<br />
*[https://manual.limesurvey.org/GSoC_getting_started GSoC - Getting started]<br />
*[https://manual.limesurvey.org/Writing_GSoC_application How to write your application]<br />
*[https://manual.limesurvey.org/GSoC_Student_Application_Template Application template]<br />
*[https://manual.limesurvey.org/GSoC_selection_criteria Our selection criteria]<br />
*[https://manual.limesurvey.org/GSoC_FAQ GSoC FAQ]<br />
<br />
[[Category:GSOC_2015]]</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=RemoteControl_2_API&diff=62281RemoteControl 2 API2014-09-02T10:58:16Z<p>Sammousa: /* How to use LSRC2 */</p>
<hr />
<div><br />
__TOC__<br />
<br />
=Introduction=<br />
<br />
LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or later. The old [RemoteControl] will not be available any longer in version 2.<br />
<br />
LSRC2 makes it possible for developers to control specific functionality of LimeSurvey from any other application, without being restricted to PHP as a programming language.<br />
<br />
The following features are planned:<br />
* start a predefined survey (change titles and things)<br />
* add predefined groups or questions<br />
* activate the survey, restrict it to start and endtime<br />
* make it closed,<br />
* add participant data/tokens when you need them<br />
* return the unused tokens to the main application<br />
* get a fieldmap for a survey,<br />
* invite or remind the participants of your survey<br />
<br />
...and much more<br />
<br />
==Requirements==<br />
* libXML installed<br />
<br />
=Setup=<br />
<br />
== How to configure LSRC2==<br />
<br />
In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to [[Global settings]], choose the tab 'Services' and select one of the two RPC services (XML-RPC or JSON-RPC) service.<br />
<br />
== Security==<br />
<br />
LSRC2 uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also LSRC2 is protected against brute-force password cracking - like the normal administration login.<br />
<br />
=How to use LSRC2=<br />
<br />
The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol<br />
<br />
LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC version 1 specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.<br />
<br />
LSRC2 offers a lot of functions. Please check the automatically generated [http://api.limesurvey.org/classes/remotecontrol_handle.html API Documentation].<br />
LSRC2 offers the following functions:<br />
<br />
==get_session_key==<br />
<br />
Using this function you can create a new XML/JSON-RPC session key. This is mandatory for all following LSRC2 function calls.<br />
<br />
Parameters: username (string), password (string)<br />
<br />
Returns:<br />
*On success: A session key (string)<br />
*On failure: for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.<br />
<br />
==release_session_key==<br />
<br />
Using this function you can close a previously opened XML-RPC/JSON-RPC session.<br />
<br />
Parameters: session key (string)<br />
<br />
Returns:<br />
*Always: 'OK' (string)<br />
<br />
==get_site_settings==<br />
<br />
Function to provide with site settings only to administrators<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) The session key<br />
<br />
sSetttingName (string) - Name of the setting to get<br />
<br />
Returns:<br />
*On success: (string) Setting<br />
*On failure: (string) Error message<br />
<br />
==add_survey==<br />
<br />
RPC Routine to add an empty survey with minimum details<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (int), The wish id of the Survey to add<br />
<br />
sSurveyTitle (string), Title of the new Survey<br />
<br />
sSurveyLanguage (string), Default language of the Survey<br />
<br />
sformat (string), Question appearance format (S|G|A)<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Faulty parameters<br />
**Creation Failed<br />
<br />
==delete_survey==<br />
<br />
RPC Routine to Delete a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string), Auth credentials<br />
<br />
iSurveyID (int), The Survey to delete<br />
<br />
Returns:<br />
*On success: Status =>OK (array)<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
<br />
==import_survey==<br />
<br />
RPC Routine to import a survey from lss,csv,xls or survey zip archive.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sImportData (string) String containing the BASE 64 encoded data of a lss,csv,xls or survey zip archive<br />
<br />
sImportDataType (string), The format of the import file (lss,csv,xls or zip)<br />
<br />
sNewSurveyName (string), The optional new name of the survey (base language)<br />
<br />
DestSurveyID (int), This is the new ID of the survey - if already used a random one will be taken instead<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Import error<br />
<br />
==get_survey_properties==<br />
<br />
RPC Routine to get properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An array with the properties to return<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
{|<br />
| || || || || ||<br />
|-<br />
| sid|| savetimings|| allowprev|| tokenanswerspersistence|| showgroupinfo|| showwelcome<br />
|-<br />
| owner_id|| template|| printanswers|| assessments|| shownoanswer || showprogress<br />
|-<br />
| admin|| language|| ipaddr|| usecaptcha|| showqnumcode|| allowjumps<br />
|-<br />
| active|| additional_languages || refurl|| usetokens|| bouncetime|| navigationdelay<br />
|-<br />
| expires|| datestamp|| datecreated|| bounce_email|| bounceprocessing|| nokeyboard<br />
|-<br />
| startdate|| usecookie|| publicstatistics|| attributedescriptions|| bounceaccounttype|| alloweditaftercompletion<br />
|-<br />
| adminemail|| allowregister|| publicgraphs|| emailresponseto|| bounceaccounthost|| googleanalyticsstyle<br />
|-<br />
| anonymized|| allowsave|| listpublic|| emailnotificationto|| bounceaccountpass|| googleanalyticsapikey<br />
|-<br />
| faxto|| autonumber_start|| htmlemail|| tokenlength|| bounceaccountencryption||<br />
|-<br />
|format|| autoredirect|| sendconfirmation|| showxquestions|| bounceaccountuser|| <br />
|}<br />
<br />
==set_survey_properties==<br />
<br />
RPC Routine to set properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An assosiative array with the name-value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) The result of the change for each property<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
Properties available for changing are all those defined in get_survey_properties with the following exceptions<br />
<br />
{|<br />
|properties not allowed to be modified|| Properties not allowed to be modified when survey active<br />
|-<br />
|sid||anonymized<br />
|-<br />
|language||datestamp<br />
|-<br />
|additional_languages||savetimings<br />
|-<br />
|active||ipaddr<br />
|-<br />
|||refurl<br />
|-<br />
|<br />
|}<br />
<br />
==list_surveys==<br />
<br />
RPC Routine to list the ids and info of surveys belonging to a user.<br />
<br />
* If user is admin he can get surveys of every user (parameter sUser) or all surveys (sUser=null)<br />
<br />
* Else only the syrveys belonging to the user requesting will be shown.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sUser (string) - The users surveys to list<br />
<br />
Returns:<br />
*On success: (array) Survey's properties<br />
*On failure: (array) Failure status<br />
**Invalid user<br />
**Invalid session key<br />
**No permission<br />
**No surveys found<br />
<br />
Survey's properties:<br />
<br />
{|<br />
|property||type<br />
|-<br />
|sid||integer<br />
|-<br />
|surveyls_title||string<br />
|-<br />
|startdate||date<br />
|-<br />
|expires||date<br />
|-<br />
|active||y/n<br />
|-<br />
|<br />
|}<br />
<br />
==activate_survey==<br />
<br />
RPC Routine that launches a newly created survey (sets active -available for users)<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
Returns<br />
*On success: (array) The result of the activation<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Activation Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==export_statistics==<br />
<br />
RPC routine to export statistics of a survey to a user.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
docType (string) - Type of document to generate<br />
<br />
sLanguage (string) Optional language of the survey to use (if not set, default language is selected)<br />
<br />
graph (string) - Optional parameter to enable graphs (0|1)<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid session key<br />
**No permission<br />
<br />
==get_summary==<br />
<br />
RPC routine to get survey summary, regarding token usage and survey participation.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
sStatname (string) - The statistic to return or 'all' to get an array of all statistics<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**No available data<br />
**No such property<br />
**Invalid session key<br />
**No permission<br />
<br />
Available statistics:<br />
<br />
{|<br />
|Survey stats||Token stats<br />
|-<br />
|completed_responses||token_count<br />
|-<br />
|incomplete_responses||token_invalid<br />
|-<br />
|full_responses||token_sent<br />
|-<br />
|||token_opted_out<br />
|-<br />
|||token_completed<br />
|-<br />
|<br />
|}<br />
<br />
==add_language==<br />
<br />
RPC Routine to add a language to an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) - The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the new language to be added. Note: If the language is already in that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==delete_survey_language==<br />
<br />
RPC Routine to delete a language of an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the language to be removed. Note: If the language is not part of that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Cannot remove base language<br />
**Error<br />
**No permission<br />
**Invalid session key<br />
<br />
==get_language_properties==<br />
<br />
RPC Routine to get survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleSettings (array) - An array with the properties to return<br />
<br />
slang (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available parameters:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
| surveyls_survey_id || surveyls_url || surveyls_email_register_subj || email_admin_notification_subj<br />
|-<br />
| surveyls_language || surveyls_urldescription || surveyls_email_register || email_admin_notification<br />
|-<br />
| surveyls_title || surveyls_email_invite_subj || surveyls_email_confirm_subj || email_admin_responses_subj<br />
|-<br />
| surveyls_description || surveyls_email_invite || surveyls_email_confirm || email_admin_responses<br />
|-<br />
| surveyls_welcometext || surveyls_email_remind_subj || surveyls_dateformat || surveyls_numberformat<br />
|-<br />
|surveyls_endtext || surveyls_email_remind || surveyls_attributecaptions || <br />
|}<br />
<br />
==set_language_properties==<br />
<br />
RPC Routine to set survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleData (array) - An assosiative array with the key-value pairs of properties to set. Invalid fieldnames or fields that may not be modified are ignored.<br />
<br />
sLanguage (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) Result for each parameter set<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Allowed Parameters:<br />
<br />
All those defined in get-language_properties except:<br />
*surveyls_language<br />
*surveyls_survey_id<br />
<br />
==add_group==<br />
<br />
RPC Routine to add an empty group with minimum details.<br />
<br />
* Used as a placeholder for importing questions.<br />
<br />
* Returns the groupid of the created group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the surveythat the group will be added<br />
<br />
sGroupTitle (string) - Name of the new group<br />
<br />
sGroupDescription (string) - Optional description of the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Creation Failed<br />
<br />
==delete_group==<br />
<br />
RPC Routine to delete a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey that the group belongs<br />
<br />
sGroupID (int) - Id of the group to delete<br />
<br />
Returns:<br />
*On success: (int) The ID of the deleted group<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid Group ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Group deletion failed<br />
<br />
==import_group==<br />
<br />
RPC Routine to import a group - imports lsg,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey that the group will belong<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sGroupDescription (string) -The format of the importfile in the stream (lsg|csv)<br />
<br />
sNewGroupName (string) - Optional new name for the group<br />
<br />
sNewGroupDescription (string) - Optional new description for the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid extension<br />
**Error: Invalid LimeSurvey group structure XML<br />
**Invalid session key<br />
**No permission<br />
**Import Error<br />
<br />
==get_group_properties==<br />
<br />
RPC Routine to return properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to get properties of<br />
<br />
aGroupSettings (array) - Array containing the properties to request.<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|gid||description<br />
|-<br />
|sid||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==set_group_properties==<br />
<br />
RPC Routine to set properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to set properties to<br />
<br />
aGroupData (array) - Assosiative Array containing key-value pairs of the properties to set.<br />
<br />
Returns:<br />
*On success: (array) The result of each set action<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Group with dependencies - Order cannot be changed<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|||description<br />
|-<br />
|||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_groups==<br />
<br />
RPC Routine to return the ids and info of groups belonging to survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey to get groups of<br />
<br />
Returns:<br />
*On success: (array) The list of the groups<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**No groups found<br />
**Invalid session key<br />
**No permission<br />
<br />
==list_users==<br />
<br />
RPC Routine to return the ids and info of users<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
Returns:<br />
*On success: (array) The list of users<br />
*On failure: (array) Failure status<br />
**No users found<br />
**Invalid session key<br />
**No permission (super admin is required)<br />
<br />
==delete_question==<br />
<br />
RPC Routine to delete a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to delete<br />
<br />
Returns:<br />
*On success: (int)id of the deleted Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
** Invalid question ID<br />
**Survey is active and not editable<br />
**Cannot delete Question. Others rely on this question<br />
**Error<br />
<br />
==import_question==<br />
<br />
RPC Routine to import a question - imports lsq,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey that the new questions belongs<br />
<br />
iGroupID (int) - Id of the group that the new questions belongs<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sImportDataType (string) - Format of the input stream (lsq,csv)<br />
<br />
sMandatory (string) - Optional Mandatory question option (default to No)<br />
<br />
sNewQuestionTitle (string) - Optional new title for the question<br />
<br />
sNewqQuestion (string) - An optional new question<br />
<br />
sNewQuestionHelp (string) - An optional new question help text<br />
<br />
Returns:<br />
*On success: (int) Id of the new Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Invalid group ID<br />
**Survey is active and not editable<br />
**Invalid extension<br />
**Invalid LimeSurvey question structure XML<br />
<br />
==get_question_properties==<br />
<br />
RPC Routine to return properties of a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to get properties of<br />
<br />
aQuestionSettings (array) The properties to get<br />
<br />
sLanguage (string) Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
|gid||type||help||language<br />
|-<br />
|parent_qid||title||other||scale_id<br />
|-<br />
|sid||question||mandatory||same_default<br />
|-<br />
|gid||preg||question_order||relevance<br />
|-<br />
|subquestions||attributes||attributes_lang||answeroptions<br />
|-<br />
|<br />
|}<br />
<br />
==set_question_properties==<br />
<br />
RPC Routine to set question properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iQuestionID (int) - Id of the question to get properties of<br />
<br />
aQuestionData (array) - An array with the particular fieldnames as keys and their values to set on that particular question<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The resilt of the set of each property<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Questions with dependencies - Order cannot be changed<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|help|| ||<br />
|-<br />
|title||other||scale_id<br />
|-<br />
|question||mandatory||same_default<br />
|-<br />
|preg||question_order||relevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_questions==<br />
<br />
RPC Routine to return the ids and info of questions of a survey/group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
iGroupID (int) - Id of the group to get questions of<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The list of the questions<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Invalid survey ID<br />
**Missmatch in surveyid and groupid<br />
**No questions found<br />
<br />
==activate_tokens==<br />
<br />
Activate tokens<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
surveyid (string) The survey ID<br />
<br />
additional_attributes (array of integers) Any additional attribute fields to create. Just give the attribute IDs<br />
<br />
Returns:<br />
*On success: (array) status OK<br />
*On failure: (array) Any other status<br />
<br />
==add_participants==<br />
<br />
Using this function you can add new entries to your token table. You can also set if for these new entries a token key is automatically created. Please note that this function does not check for duplicate content in any of the fields, except for token keys created by the function itself.<br />
<br />
Parameters:<br />
*sessionkey (string) - The session key<br />
*surveyID (string) - The survey id<br />
*participantData (array) - 2-dimensional array/structure containing your participants data<br />
*createTokenKey (boolean) - Set this to true if you want a token key create automatically for each entry - if your participant data included a [token] field it will be overwritten<br />
<br />
Returns:<br />
*On success: participant data (struct) - structure containing your participants data plus the token ID and (if applicable) the new token<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
<br />
JSON-RPC example:<br />
<br />
<syntaxhighlight lang="php" enclose="div">Request:<br />
<br />
{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}<br />
<br />
Response:<br />
<br />
{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight><br />
<br />
==delete_participants==<br />
<br />
RPC Routine to delete multiple participants of a Survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
aTokenIDs (array) - IId of the tokens/participants to delete<br />
<br />
Returns:<br />
*On success: (array) Array of deletion status for each participant<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
<br />
==get_participant_properties==<br />
<br />
RPC Routine to return settings of a token/participant of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to get token properties<br />
<br />
iTokenID (int) - Id of the participant to check<br />
<br />
aTokenProperties (array) - The properties to get<br />
<br />
Returns:<br />
*On success: (array) Array of requested values<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|tid|| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==set_participant_properties==<br />
<br />
RPC Routine to set properties of a survey participant/token<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to set token properties<br />
<br />
iTokenID (int) - Id of the participant to alter<br />
<br />
aTokenData (array) - Key - value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) Array of results of changing properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
||| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==list_participants==<br />
<br />
RPC routine to return the IDs and info of token/participants of a survey.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
iSurveyID (int) - Id of the survey to list participants<br />
iStart (int) - Start id of the token list<br />
iLimit (int) - Number of participants to return<br />
bUnused (bool) - If you want unused tokensm, set true<br />
aAttributes(bool|array) An array of extended attributes that can be requested, besides the default ones (default value to false)<br />
<br />
Returns:<br />
*On success: (array) Array of Participants info<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No Tokens found<br />
<br />
Note:<br />
<br />
If you provide the iLimit parameter it is required to provide the iStart parameter.<br />
<br />
==activate_tokens==<br />
<br />
RPC routine to to initialise the survey's collection of tokens where new participant tokens may be later added<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to list participants<br />
<br />
aAttributeFields (array) - An array of integer describing any additional attribute fields<br />
<br />
Returns:<br />
*On success: (array) Status OK<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Token table could not be created<br />
<br />
==invite_participants==<br />
<br />
RPC Routine to invite participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==remind_participants==<br />
<br />
RPC Routine to send reminder for participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
iMinDaysBetween (int) - Optional parameter days from last reminder<br />
<br />
iMaxReminders (int) - Optional parameter Maximum reminders count<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==add_response==<br />
<br />
<source lang=php><br />
public function add_response($sSessionKey, $iSurveyID, $aResponseData)<br />
</source><br />
<br />
RPC Routine to add a response to the survey responses collection.<br />
<br />
'''Return''': int|array On success: Returns the id of the inserted survey response. On failure array with error information<br />
<br />
{| class="wikitable"<br />
! Parameter !! Type !! Description<br />
|-<br />
| $sSessionKey || string || Auth credentials<br />
|-<br />
| $iSurveyID || int || Id of the Survey<br />
|-<br />
| $aResponseData || array || The actual response<br />
|-<br />
|}<br />
<br />
==export_responses==<br />
<source lang=php><br />
public function export_responses($sSessionKey, $iSurveyID, $sDocumentType, $sLanguageCode=null,<br />
$sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $iFromResponseID=null, $iToResponseID=null, $aFields=null)<br />
</source><br />
<br />
RPC Routine to export responses. Returns the requested file as base64 encoded string. <br />
<br />
'''Return''': array|string On success: Requested file as base 64-encoded string. On failure array with error information<br />
<br />
'''Note''': If you have huge response sets try only to request a certain number of records at a time otherwise the server may run out of memory.<br />
<br />
'''Note''': Starting with version 2.0.5 the $iFromResponseID and $iToResponseID parameters refer to the minimum and maximum id's; prior to this version the parameters refer to the record's offset in the table<br />
<br />
{| class="wikitable"<br />
! Parameter !! Type !! Description<br />
|-<br />
| $sSessionKey || string || Auth credentials<br />
|-<br />
| $iSurveyID || int || Id of the Survey<br />
|-<br />
| $sDocumentType || string || pdf,csv,xls,doc,json<br />
|-<br />
| $sLanguageCode || string || The language to be used<br />
|-<br />
| $sCompletionStatus || string || Optional 'complete','incomplete' or 'all' - defaults to 'all'<br />
|-<br />
| $sHeadingType || string || 'code','full' or 'abbreviated' Optional defaults to 'code'<br />
|-<br />
| $sResponseType || string || 'short' or 'long' Optional defaults to 'short'<br />
|-<br />
| $iFromResponseID || integer || Optional<br />
|-<br />
| $iToResponseID || integer || Optional<br />
|-<br />
| $aFields|| array || Optional Selected fields<br />
|-<br />
|}<br />
<br />
==export_responses_by_token==<br />
<br />
<source lang=php><br />
public function export_responses_by_token($sSessionKey, $iSurveyID, $sDocumentType, $sToken, \<br />
$sLanguageCode=null, $sCompletionStatus='all', $sHeadingType='code', $sResponseType='short', $aFields=null)<br />
</source><br />
<br />
Export responses data of specific token. Returns the requested file as base64 encoded string.<br />
<br />
'''Return''': array|string On success: Requested file as base 64-encoded string. On failure array with error information<br />
<br />
{| class="wikitable"<br />
! Parameter !! Type !! Description<br />
|-<br />
| $sSessionKey || string || Auth credentials<br />
|-<br />
| $iSurveyID || int || Id of the Survey<br />
|-<br />
| $sDocumentType || string || pdf,csv,xls,doc,json<br />
|-<br />
| $sToken || string || The token for which responses needed<br />
|-<br />
| $sLanguageCode || string || The language to be used<br />
|-<br />
| $sCompletionStatus || string || Optional 'complete','incomplete' or 'all' - defaults to 'all'<br />
|-<br />
| $sHeadingType || string || 'code','full' or 'abbreviated' Optional defaults to 'code'<br />
|-<br />
| $sResponseType || string || 'short' or 'long' Optional defaults to 'short'<br />
|-<br />
| $aFields|| array || Optional Selected fields<br />
|-<br />
|}<br />
<br />
=Testing=<br />
<br />
To test you will have to activate JSON-RPC in global settings. To run a simple self-test go to<br />
<br />
http://path_to_your_limesurvey_installation/index.php/admin/remotecontrol/test . This will import the example survey, do various things with it and delete it afterwards.<br />
<br />
The test assumes that you still are using the standard user 'admin' with password 'password'.<br />
<br />
The client function for this test can be found in /application/controller/admin/remotecontrol.php and the particular function is called test().<br />
<br />
=Ruby Example=<br />
<br />
There are some cool things that you can use with the RemoteControl2 API and this is an example of a production use of this. Basically, I, (kobaltz in the forums) have a third party site that I built that controls the users and level of access of each company and their users. From within this site, I have a daemon that will generate participants of the appropriate survey twice an hour. This will use LimeSurvey's Mail Function to send the end user a link to the survey. Administrators of the third party site will get statistical data of the end user filling out the survey as well as a link to review the surveys completed using the same template that the user used to fill it out. Reducing duplicate entry of data made possible with the RemoteControl2 API.<br />
<br />
==Load Requirements and Declare Values==<br />
You will first need to require the dependencies needed to establish communication with the API. Also, note that there is a username and password field that requires to be stored in plain text. I have a separate API User within my LimeSurvey to handle these calls.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
#!/usr/bin/env ruby<br />
<br />
require 'net/https'<br />
require 'uri'<br />
require 'json'<br />
<br />
username = "api_user"<br />
password = "api_user"<br />
</syntaxhighlight><br />
<br />
==Module==<br />
<br />
The below code is used to define the module LimeSurvey. Within this module is an API class. We will use this to create an instance of this module and then call on the API call wherever needed.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
module LimeSurvey<br />
class API<br />
def initialize(service_url)<br />
@uri = URI.parse(service_url)<br />
end<br />
<br />
def method_missing(name, *args)<br />
post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json<br />
resp = JSON.parse( http_post_request(post_body) )<br />
raise JSONRPCError, resp['error'] if resp['error']<br />
resp['result']<br />
end<br />
<br />
def http_post_request(post_body)<br />
http = Net::HTTP.new(@uri.host, @uri.port)<br />
request = Net::HTTP::Post.new(@uri.request_uri)<br />
request.content_type = 'application/json'<br />
request.body = post_body<br />
http.request(request).body<br />
end<br />
end<br />
<br />
class JSONRPCError < RuntimeError; end<br />
end<br />
</syntaxhighlight><br />
<br />
==API Call==<br />
This code is used to create the instance of the LimeSurvey::API module and class. You will want to change the URL to that of your RemoteControl2 URL.<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')<br />
</syntaxhighlight><br />
<br />
==Examples==<br />
This example takes the above code and puts it into play. I create a new session with the RemoteControl2 API and store the session in the variable session_key. You will want to change the ID numbers to the appropriate Survey ID in the examples.<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
system("cls")<br />
session_key = survey.get_session_key(username,password)<br />
puts "Session Key: #{session_key}"<br />
puts "\n"<br />
<br />
<br />
response = survey.get_survey_properties(session_key, "863224", ["owner_id"])<br />
puts "Properties: #{response}"<br />
puts "\n"<br />
<br />
response = survey.list_surveys(sSessionKey: session_key, sUser: "dkimura")<br />
puts "Survey List: #{response}"<br />
puts "\n"<br />
<br />
response = survey.add_participants(<br />
session_key, <br />
"863224",<br />
[email:"james.bond@example.com",lastname:"Bond",firstname:"James"]<br />
)<br />
puts "Add Participant: #{response}"<br />
puts "\n"<br />
<br />
response = survey.invite_participants(<br />
session_key, <br />
"863224"<br />
)<br />
puts "Invite Participant: #{response}"<br />
<br />
response = survey.release_session_key(session_key)<br />
puts "Release Session: #{response}"<br />
<br />
# Grabs a Survey's list of participants and parses through them<br />
# The response is in an array format.<br />
# Each response within the array is in JSON format (How the survey is configured with RemoteControl2)<br />
# Convert the participant response to JSON and then display the token.<br />
response = survey.list_participants(session_key, "593987")<br />
puts "\n"<br />
response_participants = []<br />
response.each do |part|<br />
resps = JSON.parse(part.to_json)<br />
puts "Participant: #{resps['token']}"<br />
puts "\n"<br />
end<br />
</syntaxhighlight><br />
==Example Return==<br />
<br />
From the above example, here is the return that I receive. Some of the items are returned as a hash and some items returned as an array of hashes.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
Session Key: piadscbc94vyanxwkdy8f3xii4av2b2w<br />
<br />
Properties: {"owner_id"=>"1"}<br />
<br />
Survey List: [{"sid"=>"863224", "surveyls_title"=>"Statement of Work v0.12", "startdate"=>nil, "expires"=>nil, "active"=>"Y"}]<br />
<br />
Add Participant: [{"email"=>"james.bond@example.com", "lastname"=>"Bond", "firstname"=>"James", "tid"=>"7", "token"=>"pt5ztzxndibkz4j"}]<br />
<br />
Invite Participant: {"7"=>{"name"=>"James Bond", "email"=>"james.bond@example.com", "status"=>"OK"}, "status"=>"0 left to send"}<br />
<br />
Participant: p7m5zmh38wi9mbk<br />
Participant: nssu6ne6ii9wva9<br />
Participant: r9kr2sahn7tfsv9<br />
Participant: a28ci2z9m7ynfgg<br />
Participant: 4ytt5axg9ebdazh<br />
Participant: wswjv2t5v7vh4p7<br />
Participant: fqvxeckgh6vgy3e<br />
Participant: n5p2vfnh7dwx699<br />
Participant: ycsmigup9pagm6z<br />
Participant: 33ztf4g74k2kvx4<br />
<br />
Release Session: OK<br />
</syntaxhighlight><br />
<br />
=PHP Example=<br />
<br />
To include JSON-RPC in your application, you can write an application using the light-weight jsonRPCClient from the [https://github.com/weberhofer/jsonrpcphp jsonrpcphp Github repository].<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<?php<br />
<br />
require_once 'jsonRPCClient.php';<br />
define( 'LS_BASEURL', 'http://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL<br />
define( 'LS_USER', 'rpcuser' );<br />
define( 'LS_PASSWORD', 'mypassword' );<br />
<br />
// the survey to process<br />
$survey_id=374699;<br />
<br />
// instanciate a new client<br />
$myJSONRPCClient = new jsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );<br />
<br />
// receive session key<br />
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );<br />
<br />
// receive all ids and info of groups belonging to a given survey<br />
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );<br />
print_r($groups, null );<br />
<br />
// release the session key<br />
$myJSONRPCClient->release_session_key( $sessionKey );<br />
<br />
?><br />
<br />
</syntaxhighlight><br />
<br />
=JAVA example=<br />
To decode and code your json calls you can use the library gson as you can see in the following example:<br />
<br />
<syntaxhighlight lang="java" enclose="div"><br />
import java.io.IOException;<br />
import java.io.UnsupportedEncodingException;<br />
<br />
import org.apache.http.HttpEntity;<br />
import org.apache.http.HttpResponse;<br />
import org.apache.http.client.methods.HttpPost;<br />
import org.apache.http.entity.StringEntity;<br />
import org.apache.http.impl.client.DefaultHttpClient;<br />
import org.apache.http.util.EntityUtils;<br />
<br />
import com.google.gson.JsonElement;<br />
import com.google.gson.JsonObject;<br />
import com.google.gson.JsonParser;<br />
<br />
public class TestHttpClient {<br />
<br />
public static String parse(String jsonLine) {<br />
JsonElement jelement = new JsonParser().parse(jsonLine);<br />
JsonObject jobject = jelement.getAsJsonObject();<br />
String result = jobject.get("result").toString();<br />
return result;<br />
}<br />
<br />
<br />
public static void main(String[] args) throws UnsupportedEncodingException {<br />
DefaultHttpClient client = new DefaultHttpClient(); <br />
<br />
HttpPost post = new HttpPost("http://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");<br />
post.setHeader("Content-type", "application/json");<br />
post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": {\"username\": \"YOUR_USERNAME\", \"password\": \"YOUR_PASSWORD\" }, \"id\": 1}"));<br />
try {<br />
HttpResponse response = client.execute(post);<br />
if(response.getStatusLine().getStatusCode() == 200){<br />
HttpEntity entity = response.getEntity();<br />
String sessionKey = parse(EntityUtils.toString(entity));<br />
post.setEntity( new StringEntity("{\"method\": \"list_groups\", \"params\": {\"sSessionKey \": "+sessionKey+", \"iSurveyID \": \"ID_SURVEY\" }, \"id\": 1}"));<br />
response = client.execute(post);<br />
if(response.getStatusLine().getStatusCode() == 200){<br />
entity = response.getEntity();<br />
System.out.println(EntityUtils.toString(entity));<br />
}<br />
}<br />
<br />
<br />
} catch (IOException e) {<br />
e.printStackTrace();<br />
}<br />
}}<br />
<br />
<br />
</syntaxhighlight><br />
<br />
=Python example=<br />
<syntaxhighlight lang="python" enclose="div"><br />
import urllib<br />
import urllib2<br />
import json<br />
import sys<br />
# There is an generic json-rpc implemantation in Python but it dose not work for me in this case so I worte Some functions <br />
<br />
<br />
<br />
def get_session_key():<br />
req = urllib2.Request(url='http://myurl/index.php/admin/remotecontrol',\<br />
data='{\"method\":\"get_session_key\",\"params\":{\"username\":\"admin\",\"password\":\"mypassword\"},\"id\":1}')<br />
req.add_header('content-type', 'application/json')<br />
req.add_header('connection', 'Keep-Alive')<br />
try:<br />
f = urllib2.urlopen(req)<br />
myretun = f.read()<br />
#print myretun<br />
j=json.loads(myretun)<br />
return j['result']<br />
except :<br />
e = sys.exc_info()[0]<br />
print ( "<p>Error: %s</p>" % e )<br />
<br />
def get_question_properties(skey,QuestionID):<br />
req = urllib2.Request(url='http://myurl/index.php/admin/remotecontrol',\<br />
data='{\"method\":\"get_question_properties\",\"params\":{\"sSessionKey\":\"'+skey+'\",\"iQuestionID\":'+QuestionID+',\<br />
\"aQuestionSettings\":[\"gid\",\"type\",\"help\",\"language\",\"sid\",\"question_order\",\"question\",\"subquestions\"]},\"id\": 1}')<br />
<br />
req.add_header('content-type', 'application/json')<br />
req.add_header('connection', 'Keep-Alive')<br />
try:<br />
f = urllib2.urlopen(req)<br />
myretun = f.read()<br />
#print myretun<br />
j=json.loads(myretun)<br />
return j['result']<br />
except :<br />
e = sys.exc_info()[0]<br />
print ( "<p>Error: %s</p>" % e )<br />
<br />
<br />
def release_session_key(relkey):<br />
req = urllib2.Request(url='http://myurl/index.php/admin/remotecontrol',\<br />
data='{\"method\":\"release_session_key\",\"params\":{\"sSessionKey\":\"'+relkey+'\"},\"id\":1}')<br />
req.add_header('content-type', 'application/json')<br />
req.add_header('connection', 'Keep-Alive')<br />
try:<br />
f = urllib2.urlopen(req)<br />
myretun = f.read()<br />
#print myretun<br />
j=json.loads(myretun)<br />
return j['result']<br />
except :<br />
e = sys.exc_info()[0]<br />
print ( "<p>Error: %s</p>" % e )<br />
<br />
<br />
def export_responses2(skey,sid):<br />
req = urllib2.Request(url='http://myurl/index.php/admin/remotecontrol',\<br />
data='{\"method\":\"export_responses\",\"params\":{\"sSessionKey\":\"'+skey+'\",\"iSurveyID\":\"'+sid+'\",\<br />
\"DocumentType\":\"csv\",\"sLanguageCode\":\"de\",\"sHeadingType\":\"full\"},\<br />
"id\": 1}')<br />
req.add_header('content-type', 'application/json')<br />
req.add_header('connection', 'Keep-Alive')<br />
try:<br />
f = urllib2.urlopen(req)<br />
myretun = f.read()<br />
#print myretun<br />
j=json.loads(myretun)<br />
return j['result']<br />
except :<br />
e = sys.exc_info()[0]<br />
print ( "<p>Error: %s</p>" % e ) <br />
<br />
<br />
mykey=get_session_key()<br />
print export_responses2(mykey,'566237').decode('base64')<br />
get_question_properties(mykey,'574')<br />
print release_session_key(mykey)<br />
</syntaxhighlight><br />
<br />
=JSON-RPC notes=<br />
<br />
The content-type of the HTTP request must be application/json. Most formatting errors or a failure to set the content-type header will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.<br />
<br />
<syntaxhighlight lang="php" enclose="div">Request:<br />
<br />
HTTP headers:<br />
<br />
content-type=application/json<br />
<br />
connection=Keep-Alive<br />
<br />
host=mylimesurveyhost.com<br />
<br />
content-length=65<br />
<br />
user-agent=Apache-HttpClient/4.2.2 (java 1.5)<br />
<br />
Post body:<br />
<br />
{"method":"get_session_key","params":{"username":"admin","password":"mypassword"},"id":1}<br />
<br />
Response body:<br />
<br />
{"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}</syntaxhighlight></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Cron_(command)&diff=61290Cron (command)2014-04-05T15:38:18Z<p>Sammousa: </p>
<hr />
<div>{{FeatureStarting|2.06}} <br />
<br />
'''When'''<br />
<br />
This event happen when server admin set a crontab instruction.<br />
<br />
'''How to use'''<br />
<br />
This event need to be call with php cli instruction.<br />
<code>php yourlimesurveydir/application/commands/console.php plugin cron --interval=X<code><br />
<br />
'''Input'''<br />
<br />
The event receives the following information:<br />
''interval'' the interval parameter, set this to the interval (in minutes) you run this cron job. Plugins can use this information to self-limit their execution time, or get an idea of when the event will fire next.<br />
<br />
<br />
[[Category:Plugins events]]</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Testing&diff=59320Testing2013-11-05T13:13:41Z<p>Sammousa: Unit testing</p>
<hr />
<div>Limesurvey 2.05 contains unit tests using PHPUnit.<br />
<br />
To run the tests go to the directory application/tests and run phpunit --bootstrap bootstrap.php unit/</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=RemoteControl_2_API&diff=56804RemoteControl 2 API2013-09-13T07:03:56Z<p>Sammousa: /* How to use LSRC2 */</p>
<hr />
<div><br />
__TOC__<br />
<br />
=Introduction=<br />
<br />
LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or later. The old [RemoteControl] will not be available any longer in version 2.<br />
<br />
LSRC2 makes it possible for developers to control specific functionality of LimeSurvey from any other application, without being restricted to PHP as a programming language.<br />
<br />
The following features are planned:<br />
* start a predefined survey (change titles and things)<br />
* add predefined groups or questions<br />
* activate the survey, restrict it to start and endtime<br />
* make it closed,<br />
* add participant data/tokens when you need them<br />
* return the unused tokens to the main application<br />
* get a fieldmap for a survey,<br />
* invite or remind the participants of your survey<br />
<br />
...and much more<br />
<br />
==Requirements==<br />
* libXML installed<br />
<br />
=Setup=<br />
<br />
== How to configure LSRC2==<br />
<br />
In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to [[Global settings]], choose the tab 'Services' and select one of the two RPC services (XML-RPC or JSON-RPC) service.<br />
<br />
== Security==<br />
<br />
LSRC2 uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also LSRC2 is protected against brute-force password cracking - like the normal administration login.<br />
<br />
=How to use LSRC2=<br />
<br />
The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol<br />
<br />
LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC version 1 specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.<br />
<br />
LSRC2 offers the following functions:<br />
<br />
==get_session_key==<br />
<br />
Using this function you can create a new XML-RPC session key. This is mandatory for all following LSRC2 function calls.<br />
<br />
Parameters: username (string), password (string)<br />
<br />
Returns:<br />
*On success: A session key (string)<br />
*On failure: for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.<br />
<br />
==release_session_key==<br />
<br />
Using this function you can close a previously opened XML-RPC/JSON-RPC session.<br />
<br />
Parameters: session key (string)<br />
<br />
Returns:<br />
*Always: 'OK' (string)<br />
<br />
==get_site_settings==<br />
<br />
Function to provide with site settings only to administrators<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) The session key<br />
<br />
sSetttingName (string) - Name of the setting to get<br />
<br />
Returns:<br />
*On success: (string) Setting<br />
*On failure: (string) Error message<br />
<br />
==add_survey==<br />
<br />
RPC Routine to add an empty survey with minimum details<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (int), The wish id of the Survey to add<br />
<br />
sSurveyTitle (string), Title of the new Survey<br />
<br />
sSurveyLanguage (string), Default language of the Survey<br />
<br />
sformat (string), Question appearance format (S|G|A)<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Faulty parameters<br />
**Creation Failed<br />
<br />
==delete_survey==<br />
<br />
RPC Routine to Delete a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string), Auth credentials<br />
<br />
iSurveyID (int), The Survey to delete<br />
<br />
Returns:<br />
*On success: Status =>OK (array)<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
<br />
==import_survey==<br />
<br />
RPC Routine to import a survey from lss,csv,xls or survey zip archive.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sImportData (string) String containing the BASE 64 encoded data of a lss,csv,xls or survey zip archive<br />
<br />
sImportDataType (string), The format of the import file (lss,csv,xls or zip)<br />
<br />
sNewSurveyName (string), The optional new name of the survey (base language)<br />
<br />
DestSurveyID (int), This is the new ID of the survey - if already used a random one will be taken instead<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Import error<br />
<br />
==get_survey_properties==<br />
<br />
RPC Routine to get properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An array with the properties to return<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
{|<br />
| || || || || ||<br />
|-<br />
| sid|| savetimings|| allowprev|| tokenanswerspersistence|| showgroupinfo|| showwelcome<br />
|-<br />
| owner_id|| template|| printanswers|| assessments|| shownoanswer || showprogress<br />
|-<br />
| admin|| language|| ipaddr|| usecaptcha|| showqnumcode|| allowjumps<br />
|-<br />
| active|| additional_languages || refurl|| usetokens|| bouncetime|| navigationdelay<br />
|-<br />
| expires|| datestamp|| datecreated|| bounce_email|| bounceprocessing|| nokeyboard<br />
|-<br />
| startdate|| usecookie|| publicstatistics|| attributedescriptions|| bounceaccounttype|| alloweditaftercompletion<br />
|-<br />
| adminemail|| allowregister|| publicgraphs|| emailresponseto|| bounceaccounthost|| googleanalyticsstyle<br />
|-<br />
| anonymized|| allowsave|| listpublic|| emailnotificationto|| bounceaccountpass|| googleanalyticsapikey<br />
|-<br />
| faxto|| autonumber_start|| htmlemail|| tokenlength|| bounceaccountencryption||<br />
|-<br />
|format|| autoredirect|| sendconfirmation|| showxquestions|| bounceaccountuser|| <br />
|}<br />
<br />
==set_survey_properties==<br />
<br />
RPC Routine to set properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An assosiative array with the name-value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) The result of the change for each property<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
Properties available for changing are all those defined in get_survey_properties with the following exceptions<br />
<br />
{|<br />
|properties not allowed to be modified|| Properties not allowed to be modified when survey active<br />
|-<br />
|sid||anonymized<br />
|-<br />
|language||datestamp<br />
|-<br />
|additional_languages||savetimings<br />
|-<br />
|active||ipaddr<br />
|-<br />
|||refurl<br />
|-<br />
|<br />
|}<br />
<br />
==list_surveys==<br />
<br />
RPC Routine to list the ids and info of surveys belonging to a user.<br />
<br />
* If user is admin he can get surveys of every user (parameter sUser) or all surveys (sUser=null)<br />
<br />
* Else only the syrveys belonging to the user requesting will be shown.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sUser (string) - The users surveys to list<br />
<br />
Returns:<br />
*On success: (array) Survey's properties<br />
*On failure: (array) Failure status<br />
**Invalid user<br />
**Invalid session key<br />
**No permission<br />
**No surveys found<br />
<br />
Survey's properties:<br />
<br />
{|<br />
|property||type<br />
|-<br />
|sid||integer<br />
|-<br />
|surveyls_title||string<br />
|-<br />
|startdate||date<br />
|-<br />
|expires||date<br />
|-<br />
|active||y/n<br />
|-<br />
|<br />
|}<br />
<br />
==activate_survey==<br />
<br />
RPC Routine that launches a newly created survey (sets active -available for users)<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
Returns<br />
*On success: (array) The result of the activation<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Activation Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==export_statistics==<br />
<br />
RPC routine to export statistics of a survey to a user.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
docType (string) - Type of document to generate<br />
<br />
sLanguage (string) Optional language of the survey to use (if not set, default language is selected)<br />
<br />
graph (string) - Optional parameter to enable graphs (0|1)<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid session key<br />
**No permission<br />
<br />
==get_summary==<br />
<br />
RPC routine to get survey summary, regarding token usage and survey participation.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
sStatname (string) - The statistic to return<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**No available data<br />
**No such property<br />
**Invalid session key<br />
**No permission<br />
<br />
Available statistics:<br />
<br />
{|<br />
|Survey stats||Token stats<br />
|-<br />
|completed_responses||token_count<br />
|-<br />
|incomplete_responses||token_invalid<br />
|-<br />
|full_responses||tokens_sent<br />
|-<br />
|||token_opted_out<br />
|-<br />
|||token_completed<br />
|-<br />
|<br />
|}<br />
<br />
==add_language==<br />
<br />
RPC Routine to add a language to an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) - The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the new language to be added. Note: If the language is already in that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==delete_survey_language==<br />
<br />
RPC Routine to delete a language of an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the language to be removed. Note: If the language is not part of that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Cannot remove base language<br />
**Error<br />
**No permission<br />
**Invalid session key<br />
<br />
==get_language_properties==<br />
<br />
RPC Routine to get survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleSettings (array) - An array with the properties to return<br />
<br />
slang (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available parameters:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
| surveyls_survey_id || surveyls_url || surveyls_email_register_subj || email_admin_notification_subj<br />
|-<br />
| surveyls_language || surveyls_urldescription || surveyls_email_register || email_admin_notification<br />
|-<br />
| surveyls_title || surveyls_email_invite_subj || surveyls_email_confirm_subj || email_admin_responses_subj<br />
|-<br />
| surveyls_description || surveyls_email_invite || surveyls_email_confirm || email_admin_responses<br />
|-<br />
| surveyls_welcometext || surveyls_email_remind_subj || surveyls_dateformat || surveyls_numberformat<br />
|-<br />
|surveyls_endtext || surveyls_email_remind || surveyls_attributecaptions || <br />
|}<br />
<br />
==set_language_properties==<br />
<br />
RPC Routine to set survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleData (array) - An assosiative array with the key-value pairs of properties to set. Invalid fieldnames or fields that may not be modified are ignored.<br />
<br />
sLanguage (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) Result for each parameter set<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Allowed Parameters:<br />
<br />
All those defined in get-language_properties except:<br />
*surveyls_language<br />
*surveyls_survey_id<br />
<br />
==add_group==<br />
<br />
RPC Routine to add an empty group with minimum details.<br />
<br />
* Used as a placeholder for importing questions.<br />
<br />
* Returns the groupid of the created group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the surveythat the group will be added<br />
<br />
sGroupTitle (string) - Name of the new group<br />
<br />
sGroupDescription (string) - Optional description of the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Creation Failed<br />
<br />
==delete_group==<br />
<br />
RPC Routine to delete a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey that the group belongs<br />
<br />
sGroupID (int) - Id of the group to delete<br />
<br />
Returns:<br />
*On success: (int) The ID of the deleted group<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid Group ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Group deletion failed<br />
<br />
==import_group==<br />
<br />
RPC Routine to import a group - imports lsg,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey that the group will belong<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sGroupDescription (string) -The format of the importfile in the stream (lsg|csv)<br />
<br />
sNewGroupName (string) - Optional new name for the group<br />
<br />
sNewGroupDescription (string) - Optional new description for the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid extension<br />
**Error: Invalid LimeSurvey group structure XML<br />
**Invalid session key<br />
**No permission<br />
**Import Error<br />
<br />
==get_group_properties==<br />
<br />
RPC Routine to return properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to get properties of<br />
<br />
aGroupSettings (array) - Array containing the properties to request.<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|gid||description<br />
|-<br />
|sid||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==set_group_properties==<br />
<br />
RPC Routine to set properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to set properties to<br />
<br />
aGroupData (array) - Assosiative Array containing key-value pairs of the properties to set.<br />
<br />
Returns:<br />
*On success: (array) The result of each set action<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Group with dependencies - Order cannot be changed<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|||description<br />
|-<br />
|||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_groups==<br />
<br />
RPC Routine to return the ids and info of groups belonging to survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey to get groups of<br />
<br />
Returns:<br />
*On success: (array) The list of the groups<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**No groups found<br />
**Invalid session key<br />
**No permission<br />
<br />
==list_users==<br />
<br />
RPC Routine to return the ids and info of users<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
Returns:<br />
*On success: (array) The list of users<br />
*On failure: (array) Failure status<br />
**No users found<br />
**Invalid session key<br />
**No permission (super admin is required)<br />
<br />
==delete_question==<br />
<br />
RPC Routine to delete a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to delete<br />
<br />
Returns:<br />
*On success: (int)id of the deleted Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
** Invalid question ID<br />
**Survey is active and not editable<br />
**Cannot delete Question. Others rely on this question<br />
**Error<br />
<br />
==import_question==<br />
<br />
RPC Routine to import a question - imports lsq,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey that the new questions belongs<br />
<br />
iGroupID (int) - Id of the group that the new questions belongs<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sImportDataType (string) - Format of the input stream (lsq,csv)<br />
<br />
sMandatory (string) - Optional Mandatory question option (default to No)<br />
<br />
sNewQuestionTitle (string) - Optional new title for the question<br />
<br />
sNewqQuestion (string) - An optional new question<br />
<br />
sNewQuestionHelp (string) - An optional new question help text<br />
<br />
Returns:<br />
*On success: (int) Id of the new Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Invalid group ID<br />
**Survey is active and not editable<br />
**Invalid extension<br />
**Invalid LimeSurvey question structure XML<br />
<br />
==get_question_properties==<br />
<br />
RPC Routine to return properties of a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to get properties of<br />
<br />
aQuestionSettings (array) The properties to get<br />
<br />
sLanguage (string) Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
|gid||type||help||language<br />
|-<br />
|parent_qid||title||other||scale_id<br />
|-<br />
|sid||question||mandatory||same_default<br />
|-<br />
|gid||preg||question_order||relevance<br />
|-<br />
|subquestions||attributes||attributes_lang||answeroptions<br />
|-<br />
|<br />
|}<br />
<br />
==set_question_properties==<br />
<br />
RPC Routine to set question properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iQuestionID (int) - Id of the question to get properties of<br />
<br />
aQuestionData (array) - An array with the particular fieldnames as keys and their values to set on that particular question<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The resilt of the set of each property<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Questions with dependencies - Order cannot be changed<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|help|| ||<br />
|-<br />
|title||other||scale_id<br />
|-<br />
|question||mandatory||same_default<br />
|-<br />
|preg||question_order||relevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_questions==<br />
<br />
RPC Routine to return the ids and info of questions of a survey/group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
iGroupID (int) - Id of the group to get questions of<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The list of the questions<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Invalid survey ID<br />
**Missmatch in surveyid and groupid<br />
**No questions found<br />
<br />
==activate_tokens==<br />
<br />
Activate tokens<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
surveyid (string) The survey ID<br />
<br />
additional_attributes (array of integers) Any additional attribute fields to create. Just give the attribute IDs<br />
<br />
Returns:<br />
*On success: (array) status OK<br />
*On failure: (array) Any other status<br />
<br />
==add_participants==<br />
<br />
Using this function you can add new entries to your token table. You can also set if for these new entries a token key is automatically created. Please note that this function does not check for duplicate content in any of the fields, except for token keys created by the function itself.<br />
<br />
Parameters:<br />
*sessionkey (string) - The session key<br />
*surveyID (string) - The survey id<br />
*participantData (array) - 2-dimensional array/structure containing your participants data<br />
*createTokenKey (boolean) - Set this to true if you want a token key create automatically for each entry - if your participant data included a [token] field it will be overwritten<br />
<br />
Returns:<br />
*On success: participant data (struct) - structure containing your participants data plus the token ID and (if applicable) the new token<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
<br />
JSON-RPC example:<br />
<br />
<syntaxhighlight lang="php" enclose="div">Request:<br />
<br />
{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}<br />
<br />
Response:<br />
<br />
{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight><br />
<br />
==delete_participants==<br />
<br />
RPC Routine to delete multiple participants of a Survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
aTokenIDs (array) - IId of the tokens/participants to delete<br />
<br />
Returns:<br />
*On success: (array) Array of deletion status for each participant<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
<br />
==get_participant_properties==<br />
<br />
RPC Routine to return settings of a token/participant of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to get token properties<br />
<br />
iTokenID (int) - Id of the participant to check<br />
<br />
aTokenProperties (array) - The properties to get<br />
<br />
Returns:<br />
*On success: (array) Array of requested values<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|tid|| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==set_participant_properties==<br />
<br />
RPC Routine to set properties of a survey participant/token<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to set token properties<br />
<br />
iTokenID (int) - Id of the participant to alter<br />
<br />
aTokenData (array) - Key - value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) Array of results of changing properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
||| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==list_participants==<br />
<br />
RPC routine to return the IDs and info of token/participants of a survey.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
iSurveyID (int) - Id of the survey to list participants<br />
iStart (int) - Start id of the token list<br />
iLimit (int) - Number of participants to return<br />
bUnused (bool) - If you want unused tokensm, set true<br />
aAttributes(bool|array) An array of extended attributes that can be requested, besides the default ones (default value to false)<br />
<br />
Returns:<br />
*On success: (array) Array of Participants info<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No Tokens found<br />
<br />
==activate_tokens==<br />
<br />
RPC routine to to initialise the survey's collection of tokens where new participant tokens may be later added<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to list participants<br />
<br />
aAttributeFields (array) - An array of integer describing any additional attribute fields<br />
<br />
Returns:<br />
*On success: (array) Status OK<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Token table could not be created<br />
<br />
==invite_participants==<br />
<br />
RPC Routine to invite participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==remind_participants==<br />
<br />
RPC Routine to send reminder for participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
iMinDaysBetween (int) - Optional parameter days from last reminder<br />
<br />
iMaxReminders (int) - Optional parameter Maximum reminders count<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==add_response==<br />
<br />
Using this function you can add new responses to your survey response table.<br />
<br />
Parameters:<br />
*sSessionKey (string) - The session key<br />
*iSurveyID (integer) - The survey id<br />
*aResponseData (array) - array/structure containing your response data<br />
<br />
Returns:<br />
*On success: response_id (integer) - Returns the id of the inserted survey response<br />
*On failure: (array) with error description<br />
<br />
==export_responses==<br />
<br />
Export response data to pdf,csv,xls,doc<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
SurveyID (int) - Id of the Survey<br />
<br />
DocumentType (string) - pdf,csv,xls,doc, html<br />
<br />
sLanguageCode (string) - Optional The language to be used - if not given then the base language will be used<br />
<br />
CompletionStatus (string) - Optional 'complete','incomplete' or 'all' selection of responses - defaults to complete<br />
<br />
HeadingType (string) - 'code','full' or 'abbreviated'. type of question heading. Optional defaults to 'code'<br />
<br />
ResponseType (string) - 'short' or 'long' response type.Optional defaults to 'short'<br />
<br />
FromResponse (int) - Optional start number of response<br />
<br />
ToResponse (int) - Optional end number of responses<br />
<br />
Return:<br />
<br />
On success: Requested file as base 64-encoded string.<br />
<br />
On failure: Array with error information<br />
<br />
Note: If you have huge response sets try only to request a certain number of records at a time otherwise the server may run out of memory.<br />
<br />
==export_responses_by_token==<br />
<br />
Export responses data of specific token to pdf,csv,xls,doc<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
SurveyID (int) - Id of the Survey<br />
<br />
DocumentType (string) - pdf,csv,xls,doc,html<br />
<br />
sToken (string) - Token string of a candidate<br />
<br />
sLanguageCode (string) - Optional The language to be used - if not given then the base language will be used<br />
<br />
CompletionStatus (string) - Optional 'complete','incomplete' or 'all' selection of responses - defaults to complete<br />
<br />
HeadingType (string) - 'code','full' or 'abbreviated'. type of question heading. Optional defaults to 'code'<br />
<br />
ResponseType (string) - 'short' or 'long' response type.Optional defaults to 'short'<br />
<br />
aFields (array) - Optional Selected fields<br />
<br />
Return:<br />
<br />
On success: Requested file as base 64-encoded string.<br />
<br />
On failure: Array with error information<br />
<br />
=Testing=<br />
<br />
To test you will have to activate JSON-RPC in global settings. To run a simple self-test go to<br />
<br />
http://path_to_your_limesurvey_installation/index.php/admin/remotecontrol/test . This will import the example survey, do various things with it and delete it afterwards.<br />
<br />
The test assumes that you still are using the standard user 'admin' with password 'password'.<br />
<br />
The client function for this test can be found in /application/controller/admin/remotecontrol.php and the particular function is called test().<br />
<br />
=Ruby Example=<br />
<br />
There are some cool things that you can use with the RemoteControl2 API and this is an example of a production use of this. Basically, I, (kobaltz in the forums) have a third party site that I built that controls the users and level of access of each company and their users. From within this site, I have a daemon that will generate participants of the appropriate survey twice an hour. This will use LimeSurvey's Mail Function to send the end user a link to the survey. Administrators of the third party site will get statistical data of the end user filling out the survey as well as a link to review the surveys completed using the same template that the user used to fill it out. Reducing duplicate entry of data made possible with the RemoteControl2 API.<br />
<br />
==Load Requirements and Declare Values==<br />
You will first need to require the dependencies needed to establish communication with the API. Also, note that there is a username and password field that requires to be stored in plain text. I have a separate API User within my LimeSurvey to handle these calls.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
#!/usr/bin/env ruby<br />
<br />
require 'net/https'<br />
require 'uri'<br />
require 'json'<br />
<br />
username = "api_user"<br />
password = "api_user"<br />
</syntaxhighlight><br />
<br />
==Module==<br />
<br />
The below code is used to define the module LimeSurvey. Within this module is an API class. We will use this to create an instance of this module and then call on the API call wherever needed.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
module LimeSurvey<br />
class API<br />
def initialize(service_url)<br />
@uri = URI.parse(service_url)<br />
end<br />
<br />
def method_missing(name, *args)<br />
post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json<br />
resp = JSON.parse( http_post_request(post_body) )<br />
raise JSONRPCError, resp['error'] if resp['error']<br />
resp['result']<br />
end<br />
<br />
def http_post_request(post_body)<br />
http = Net::HTTP.new(@uri.host, @uri.port)<br />
request = Net::HTTP::Post.new(@uri.request_uri)<br />
request.content_type = 'application/json'<br />
request.body = post_body<br />
http.request(request).body<br />
end<br />
end<br />
<br />
class JSONRPCError < RuntimeError; end<br />
end<br />
</syntaxhighlight><br />
<br />
==API Call==<br />
This code is used to create the instance of the LimeSurvey::API module and class. You will want to change the URL to that of your RemoteControl2 URL.<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')<br />
</syntaxhighlight><br />
<br />
==Examples==<br />
This example takes the above code and puts it into play. I create a new session with the RemoteControl2 API and store the session in the variable session_key. You will want to change the ID numbers to the appropriate Survey ID in the examples.<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
system("cls")<br />
session_key = survey.get_session_key(username,password)<br />
puts "Session Key: #{session_key}"<br />
puts "\n"<br />
<br />
<br />
response = survey.get_survey_properties(session_key, "863224", ["owner_id"])<br />
puts "Properties: #{response}"<br />
puts "\n"<br />
<br />
response = survey.list_surveys(sSessionKey: session_key, sUser: "dkimura")<br />
puts "Survey List: #{response}"<br />
puts "\n"<br />
<br />
response = survey.add_participants(<br />
session_key, <br />
"863224",<br />
[email:"james.bond@example.com",lastname:"Bond",firstname:"James"]<br />
)<br />
puts "Add Participant: #{response}"<br />
puts "\n"<br />
<br />
response = survey.invite_participants(<br />
session_key, <br />
"863224"<br />
)<br />
puts "Invite Participant: #{response}"<br />
<br />
response = survey.release_session_key(session_key)<br />
puts "Release Session: #{response}"<br />
<br />
# Grabs a Survey's list of participants and parses through them<br />
# The response is in an array format.<br />
# Each response within the array is in JSON format (How the survey is configured with RemoteControl2)<br />
# Convert the participant response to JSON and then display the token.<br />
response = survey.list_participants(session_key, "593987")<br />
puts "\n"<br />
response_participants = []<br />
response.each do |part|<br />
resps = JSON.parse(part.to_json)<br />
puts "Participant: #{resps['token']}"<br />
puts "\n"<br />
end<br />
</syntaxhighlight><br />
==Example Return==<br />
<br />
From the above example, here is the return that I receive. Some of the items are returned as a hash and some items returned as an array of hashes.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
Session Key: piadscbc94vyanxwkdy8f3xii4av2b2w<br />
<br />
Properties: {"owner_id"=>"1"}<br />
<br />
Survey List: [{"sid"=>"863224", "surveyls_title"=>"Statement of Work v0.12", "startdate"=>nil, "expires"=>nil, "active"=>"Y"}]<br />
<br />
Add Participant: [{"email"=>"james.bond@example.com", "lastname"=>"Bond", "firstname"=>"James", "tid"=>"7", "token"=>"pt5ztzxndibkz4j"}]<br />
<br />
Invite Participant: {"7"=>{"name"=>"James Bond", "email"=>"james.bond@example.com", "status"=>"OK"}, "status"=>"0 left to send"}<br />
<br />
Participant: p7m5zmh38wi9mbk<br />
Participant: nssu6ne6ii9wva9<br />
Participant: r9kr2sahn7tfsv9<br />
Participant: a28ci2z9m7ynfgg<br />
Participant: 4ytt5axg9ebdazh<br />
Participant: wswjv2t5v7vh4p7<br />
Participant: fqvxeckgh6vgy3e<br />
Participant: n5p2vfnh7dwx699<br />
Participant: ycsmigup9pagm6z<br />
Participant: 33ztf4g74k2kvx4<br />
<br />
Release Session: OK<br />
</syntaxhighlight><br />
<br />
=PHP Example=<br />
<br />
To include JSON-RPC in your application, you can write an application based on the tiny jsonRPCClient from [http://jsonrpcphp.org/ | jsonrpcphp.org]<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<?php<br />
<br />
require_once 'jsonRPCClient.php';<br />
<br />
define( 'LS_BASEURL', 'http://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL<br />
<br />
define( 'LS_USER', 'rpcuser' );<br />
<br />
define( 'LS_PASSWORD', 'mypassword' );<br />
<br />
// the survey to process<br />
<br />
$survey_id=374699;<br />
<br />
// instanciate a new client<br />
<br />
$myJSONRPCClient = new jsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );<br />
<br />
// receive session key<br />
<br />
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );<br />
<br />
// receive all ids and info of groups belonging to a given survey<br />
<br />
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );<br />
<br />
print_r($groups, null );<br />
<br />
// release the session key<br />
<br />
$myJSONRPCClient->release_session_key( $sessionKey );<br />
<br />
?><br />
<br />
</syntaxhighlight><br />
<br />
=JAVA example=<br />
To decode and code your json calls you can use the library gson as you can see in the following example:<br />
<br />
<syntaxhighlight lang="java" enclose="div"><br />
import java.io.IOException;<br />
import java.io.UnsupportedEncodingException;<br />
<br />
import org.apache.http.HttpEntity;<br />
import org.apache.http.HttpResponse;<br />
import org.apache.http.client.methods.HttpPost;<br />
import org.apache.http.entity.StringEntity;<br />
import org.apache.http.impl.client.DefaultHttpClient;<br />
import org.apache.http.util.EntityUtils;<br />
<br />
import com.google.gson.JsonElement;<br />
import com.google.gson.JsonObject;<br />
import com.google.gson.JsonParser;<br />
<br />
public class TestHttpClient {<br />
<br />
public static String parse(String jsonLine) {<br />
JsonElement jelement = new JsonParser().parse(jsonLine);<br />
JsonObject jobject = jelement.getAsJsonObject();<br />
String result = jobject.get("result").toString();<br />
return result;<br />
}<br />
<br />
<br />
public static void main(String[] args) throws UnsupportedEncodingException {<br />
DefaultHttpClient client = new DefaultHttpClient(); <br />
<br />
HttpPost post = new HttpPost("http://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");<br />
post.setHeader("Content-type", "application/json");<br />
post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": {\"username\": \"YOUR_USERNAME\", \"password\": \"YOUR_PASSWORD\" }, \"id\": 1}"));<br />
try {<br />
HttpResponse response = client.execute(post);<br />
if(response.getStatusLine().getStatusCode() == 200){<br />
HttpEntity entity = response.getEntity();<br />
String sessionKey = parse(EntityUtils.toString(entity));<br />
post.setEntity( new StringEntity("{\"method\": \"list_groups\", \"params\": {\"sSessionKey \": "+sessionKey+", \"iSurveyID \": \"ID_SURVEY\" }, \"id\": 1}"));<br />
response = client.execute(post);<br />
if(response.getStatusLine().getStatusCode() == 200){<br />
entity = response.getEntity();<br />
System.out.println(EntityUtils.toString(entity));<br />
}<br />
}<br />
<br />
<br />
} catch (IOException e) {<br />
e.printStackTrace();<br />
}<br />
}}<br />
<br />
<br />
</syntaxhighlight><br />
<br />
=JSON-RPC notes=<br />
<br />
The content-type of the HTTP request must be application/json. Most formatting errors or a failure to set the content-type header will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.<br />
<br />
<syntaxhighlight lang="php" enclose="div">Request:<br />
<br />
HTTP headers:<br />
<br />
content-type=application/json<br />
<br />
connection=Keep-Alive<br />
<br />
host=mylimesurveyhost.com<br />
<br />
content-length=65<br />
<br />
user-agent=Apache-HttpClient/4.2.2 (java 1.5)<br />
<br />
Post body:<br />
<br />
{"method":"get_session_key","params":{"username":"admin","password":"mypassword"},"id":1}<br />
<br />
Response body:<br />
<br />
{"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}</syntaxhighlight><br />
<br />
=Changes=<br />
<br />
2.0a Only three functions are supported right now: getSessionKey, releaseSessionKey, deleteSurvey<br />
<br />
2.0b Added function add_participants<br />
<br />
2.0RC5 Added import_survey, activate_survey, activate_tokens<br />
<br />
2.0 (build 121030) Added subquestions, attributes, attributes_lang and answeroptions properties for get_question_properties<br />
<br />
...<br />
<br />
for further changes check the Limesurvey release notes, thanks!<br />
<br />
[[Category:Development]]</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=RemoteControl_2_API&diff=44313RemoteControl 2 API2013-07-06T15:32:16Z<p>Sammousa: /* export_responses_by_token */</p>
<hr />
<div><br />
__TOC__<br />
<br />
=Introduction=<br />
<br />
LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or later. The old [RemoteControl] will not be available any longer in version 2.<br />
<br />
LSRC2 makes it possible for developers to control specific functionality of LimeSurvey from any other application, without being restricted to PHP as a programming language.<br />
<br />
The following features are planned:<br />
* start a predefined survey (change titles and things)<br />
* add predefined groups or questions<br />
* activate the survey, restrict it to start and endtime<br />
* make it closed,<br />
* add participant data/tokens when you need them<br />
* return the unused tokens to the main application<br />
* get a fieldmap for a survey,<br />
* invite or remind the participants of your survey<br />
<br />
...and much more<br />
<br />
==Requirements==<br />
* libXML installed<br />
<br />
=Setup=<br />
<br />
== How to configure LSRC2==<br />
<br />
In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to [[Global settings]], choose the tab 'Services' and select one of the two RPC services (XML-RPC or JSON-RPC) service.<br />
<br />
== Security==<br />
<br />
LSRC2 uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also LSRC2 is protected against brute-force password cracking - like the normal administration login.<br />
<br />
=How to use LSRC2=<br />
<br />
The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol<br />
<br />
LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC version 1 specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.<br />
<br />
LSRC2 offers the following functions:<br />
<br />
==get_session_key==<br />
<br />
Using this function you can create a new XML-RPC session key. This is mandatory for all following LSRC2 function calls.<br />
<br />
Parameters: username (string), password (string)<br />
<br />
Returns:<br />
*On success: A session key (string)<br />
*On failure: for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.<br />
<br />
==release_session_key==<br />
<br />
Using this function you can close a previously opened XML-RPC/JSON-RPC session.<br />
<br />
Parameters: session key (string)<br />
<br />
Returns:<br />
*Always: 'OK' (string)<br />
<br />
==get_site_settings==<br />
<br />
Function to provide with site settings only to administrators<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) The session key<br />
<br />
sSetttingName (string) - Name of the setting to get<br />
<br />
Returns:<br />
*On success: (string) Setting<br />
*On failure: (string) Error message<br />
<br />
==add_survey==<br />
<br />
RPC Routine to add an empty survey with minimum details<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (int), The wish id of the Survey to add<br />
<br />
sSurveyTitle (string), Title of the new Survey<br />
<br />
sSurveyLanguage (string), Default language of the Survey<br />
<br />
sformat (string), Question appearance format (S|G|A)<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Faulty parameters<br />
**Creation Failed<br />
<br />
==delete_survey==<br />
<br />
RPC Routine to Delete a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string), Auth credentials<br />
<br />
iSurveyID (int), The Survey to delete<br />
<br />
Returns:<br />
*On success: Status =>OK (array)<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
<br />
==import_survey==<br />
<br />
RPC Routine to import a survey from lss,csv,xls or survey zip archive.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sImportData (string) String containing the BASE 64 encoded data of a lss,csv,xls or survey zip archive<br />
<br />
sImportDataType (string), The format of the import file (lss,csv,xls or zip)<br />
<br />
sNewSurveyName (string), The optional new name of the survey (base language)<br />
<br />
DestSurveyID (int), This is the new ID of the survey - if already used a random one will be taken instead<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Import error<br />
<br />
==get_survey_properties==<br />
<br />
RPC Routine to get properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An array with the properties to return<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
{|<br />
| || || || || ||<br />
|-<br />
| sid|| savetimings|| allowprev|| tokenanswerspersistence|| showgroupinfo|| showwelcome<br />
|-<br />
| owner_id|| template|| printanswers|| assessments|| shownoanswer || showprogress<br />
|-<br />
| admin|| language|| ipaddr|| usecaptcha|| showqnumcode|| allowjumps<br />
|-<br />
| active|| additional_languages || refurl|| usetokens|| bouncetime|| navigationdelay<br />
|-<br />
| expires|| datestamp|| datecreated|| bounce_email|| bounceprocessing|| nokeyboard<br />
|-<br />
| startdate|| usecookie|| publicstatistics|| attributedescriptions|| bounceaccounttype|| alloweditaftercompletion<br />
|-<br />
| adminemail|| allowregister|| publicgraphs|| emailresponseto|| bounceaccounthost|| googleanalyticsstyle<br />
|-<br />
| anonymized|| allowsave|| listpublic|| emailnotificationto|| bounceaccountpass|| googleanalyticsapikey<br />
|-<br />
| faxto|| autonumber_start|| htmlemail|| tokenlength|| bounceaccountencryption||<br />
|-<br />
|format|| autoredirect|| sendconfirmation|| showxquestions|| bounceaccountuser|| <br />
|}<br />
<br />
==set_survey_properties==<br />
<br />
RPC Routine to set properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An assosiative array with the name-value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) The result of the change for each property<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
Properties available for changing are all those defined in get_survey_properties with the following exceptions<br />
<br />
{|<br />
|properties not allowed to be modified|| Properties not allowed to be modified when survey active<br />
|-<br />
|sid||anonymized<br />
|-<br />
|language||datestamp<br />
|-<br />
|additional_languages||savetimings<br />
|-<br />
|active||ipaddr<br />
|-<br />
|||refurl<br />
|-<br />
|<br />
|}<br />
<br />
==list_surveys==<br />
<br />
RPC Routine to list the ids and info of surveys belonging to a user.<br />
<br />
* If user is admin he can get surveys of every user (parameter sUser) or all surveys (sUser=null)<br />
<br />
* Else only the syrveys belonging to the user requesting will be shown.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sUser (string) - The users surveys to list<br />
<br />
Returns:<br />
*On success: (array) Survey's properties<br />
*On failure: (array) Failure status<br />
**Invalid user<br />
**Invalid session key<br />
**No permission<br />
**No surveys found<br />
<br />
Survey's properties:<br />
<br />
{|<br />
|property||type<br />
|-<br />
|sid||integer<br />
|-<br />
|surveyls_title||string<br />
|-<br />
|startdate||date<br />
|-<br />
|expires||date<br />
|-<br />
|active||y/n<br />
|-<br />
|<br />
|}<br />
<br />
==activate_survey==<br />
<br />
RPC Routine that launches a newly created survey (sets active -available for users)<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
Returns<br />
*On success: (array) The result of the activation<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Activation Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==export_statistics==<br />
<br />
RPC routine to export statistics of a survey to a user.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
docType (string) - Type of document to generate<br />
<br />
sLanguage (string) Optional language of the survey to use (if not set, default language is selected)<br />
<br />
graph (string) - Optional parameter to enable graphs (0|1)<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid session key<br />
**No permission<br />
<br />
==get_summary==<br />
<br />
RPC routine to get survey summary, regarding token usage and survey participation.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
sStatname (string) - The statistic to return<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**No available data<br />
**No such property<br />
**Invalid session key<br />
**No permission<br />
<br />
Available statistics:<br />
<br />
{|<br />
|Survey stats||Token stats<br />
|-<br />
|completed_responses||token_count<br />
|-<br />
|incomplete_responses||token_invalid<br />
|-<br />
|full_responses||tokens_sent<br />
|-<br />
|||token_opted_out<br />
|-<br />
|||token_completed<br />
|-<br />
|<br />
|}<br />
<br />
==add_language==<br />
<br />
RPC Routine to add a language to an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) - The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the new language to be added. Note: If the language is already in that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==delete_survey_language==<br />
<br />
RPC Routine to delete a language of an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the language to be removed. Note: If the language is not part of that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Cannot remove base language<br />
**Error<br />
**No permission<br />
**Invalid session key<br />
<br />
==get_language_properties==<br />
<br />
RPC Routine to get survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleSettings (array) - An array with the properties to return<br />
<br />
slang (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available parameters:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
| surveyls_survey_id || surveyls_url || surveyls_email_register_subj || email_admin_notification_subj<br />
|-<br />
| surveyls_language || surveyls_urldescription || surveyls_email_register || email_admin_notification<br />
|-<br />
| surveyls_title || surveyls_email_invite_subj || surveyls_email_confirm_subj || email_admin_responses_subj<br />
|-<br />
| surveyls_description || surveyls_email_invite || surveyls_email_confirm || email_admin_responses<br />
|-<br />
| surveyls_welcometext || surveyls_email_remind_subj || surveyls_dateformat || surveyls_numberformat<br />
|-<br />
|surveyls_endtext || surveyls_email_remind || surveyls_attributecaptions || <br />
|}<br />
<br />
==set_language_properties==<br />
<br />
RPC Routine to set survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleData (array) - An assosiative array with the key-value pairs of properties to set. Invalid fieldnames or fields that may not be modified are ignored.<br />
<br />
sLanguage (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) Result for each parameter set<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Allowed Parameters:<br />
<br />
All those defined in get-language_properties except:<br />
*surveyls_language<br />
*surveyls_survey_id<br />
<br />
==add_group==<br />
<br />
RPC Routine to add an empty group with minimum details.<br />
<br />
* Used as a placeholder for importing questions.<br />
<br />
* Returns the groupid of the created group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the surveythat the group will be added<br />
<br />
sGroupTitle (string) - Name of the new group<br />
<br />
sGroupDescription (string) - Optional description of the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Creation Failed<br />
<br />
==delete_group==<br />
<br />
RPC Routine to delete a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey that the group belongs<br />
<br />
sGroupID (int) - Id of the group to delete<br />
<br />
Returns:<br />
*On success: (int) The ID of the deleted group<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid Group ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Group deletion failed<br />
<br />
==import_group==<br />
<br />
RPC Routine to import a group - imports lsg,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey that the group will belong<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sGroupDescription (string) -The format of the importfile in the stream (lsg|csv)<br />
<br />
sNewGroupName (string) - Optional new name for the group<br />
<br />
sNewGroupDescription (string) - Optional new description for the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid extension<br />
**Error: Invalid LimeSurvey group structure XML<br />
**Invalid session key<br />
**No permission<br />
**Import Error<br />
<br />
==get_group_properties==<br />
<br />
RPC Routine to return properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to get properties of<br />
<br />
aGroupSettings (array) - Array containing the properties to request.<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|gid||description<br />
|-<br />
|sid||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==set_group_properties==<br />
<br />
RPC Routine to set properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to set properties to<br />
<br />
aGroupData (array) - Assosiative Array containing key-value pairs of the properties to set.<br />
<br />
Returns:<br />
*On success: (array) The result of each set action<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Group with dependencies - Order cannot be changed<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|||description<br />
|-<br />
|||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_groups==<br />
<br />
RPC Routine to return the ids and info of groups belonging to survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey to get groups of<br />
<br />
Returns:<br />
*On success: (array) The list of the groups<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**No groups found<br />
**Invalid session key<br />
**No permission<br />
<br />
==delete_question==<br />
<br />
RPC Routine to delete a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to delete<br />
<br />
Returns:<br />
*On success: (int)id of the deleted Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
** Invalid question ID<br />
**Survey is active and not editable<br />
**Cannot delete Question. Others rely on this question<br />
**Error<br />
<br />
==import_question==<br />
<br />
RPC Routine to import a question - imports lsq,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey that the new questions belongs<br />
<br />
iGroupID (int) - Id of the group that the new questions belongs<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sImportDataType (string) - Format of the input stream (lsq,csv)<br />
<br />
sMandatory (string) - Optional Mandatory question option (default to No)<br />
<br />
sNewQuestionTitle (string) - Optional new title for the question<br />
<br />
sNewqQuestion (string) - An optional new question<br />
<br />
sNewQuestionHelp (string) - An optional new question help text<br />
<br />
Returns:<br />
*On success: (int) Id of the new Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Invalid group ID<br />
**Survey is active and not editable<br />
**Invalid extension<br />
**Invalid LimeSurvey question structure XML<br />
<br />
==get_question_properties==<br />
<br />
RPC Routine to return properties of a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to get properties of<br />
<br />
aQuestionSettings (array) The properties to get<br />
<br />
sLanguage (string) Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
|gid||type||help||language<br />
|-<br />
|parent_qid||title||other||scale_id<br />
|-<br />
|sid||question||mandatory||same_default<br />
|-<br />
|gid||preg||question_order||relevance<br />
|-<br />
|subquestions||attributes||attributes_lang||answeroptions<br />
|-<br />
|<br />
|}<br />
<br />
==set_question_properties==<br />
<br />
RPC Routine to set question properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iQuestionID (int) - Id of the question to get properties of<br />
<br />
aQuestionData (array) - An array with the particular fieldnames as keys and their values to set on that particular question<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The resilt of the set of each property<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Questions with dependencies - Order cannot be changed<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|help|| ||<br />
|-<br />
|title||other||scale_id<br />
|-<br />
|question||mandatory||same_default<br />
|-<br />
|preg||question_order||relevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_questions==<br />
<br />
RPC Routine to return the ids and info of questions of a survey/group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
iGroupID (int) - Id of the group to get questions of<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The list of the questions<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Invalid survey ID<br />
**Missmatch in surveyid and groupid<br />
**No questions found<br />
<br />
==activate_tokens==<br />
<br />
Activate tokens<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
surveyid (string) The survey ID<br />
<br />
additional_attributes (array of integers) Any additional attribute fields to create. Just give the attribute IDs<br />
<br />
Returns:<br />
*On success: (array) status OK<br />
*On failure: (array) Any other status<br />
<br />
==add_participants==<br />
<br />
Using this function you can add new entries to your token table. You can also set if for these new entries a token key is automatically created. Please note that this function does not check for duplicate content in any of the fields, except for token keys created by the function itself.<br />
<br />
Parameters:<br />
*sessionkey (string) - The session key<br />
*surveyID (string) - The survey id<br />
*participantData (array) - 2-dimensional array/structure containing your participants data<br />
*createTokenKey (boolean) - Set this to true if you want a token key create automatically for each entry - if your participant data included a [token] field it will be overwritten<br />
<br />
Returns:<br />
*On success: participant data (struct) - structure containing your participants data plus the token ID and (if applicable) the new token<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
<br />
JSON-RPC example:<br />
<br />
<syntaxhighlight lang="php" enclose="div">Request:<br />
<br />
{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}<br />
<br />
Response:<br />
<br />
{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight><br />
<br />
==delete_participants==<br />
<br />
RPC Routine to delete multiple participants of a Survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
aTokenIDs (array) - IId of the tokens/participants to delete<br />
<br />
Returns:<br />
*On success: (array) Array of deletion status for each participant<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
<br />
==get_participant_properties==<br />
<br />
RPC Routine to return settings of a token/participant of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to get token properties<br />
<br />
iTokenID (int) - Id of the participant to check<br />
<br />
aTokenProperties (array) - The properties to get<br />
<br />
Returns:<br />
*On success: (array) Array of requested values<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|tid|| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==set_participant_properties==<br />
<br />
RPC Routine to set properties of a survey participant/token<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to set token properties<br />
<br />
iTokenID (int) - Id of the participant to alter<br />
<br />
aTokenData (array) - Key - value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) Array of results of changing properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
||| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==list_participants==<br />
<br />
RPC routine to return the IDs and info of token/participants of a survey.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
iSurveyID (int) - Id of the survey to list participants<br />
iStart (int) - Start id of the token list<br />
iLimit (int) - Number of participants to return<br />
bUnused (bool) - If you want unused tokensm, set true<br />
aAttributes(bool|array) An array of extended attributes that can be requested, besides the default ones (default value to false)<br />
<br />
Returns:<br />
*On success: (array) Array of Participants info<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No Tokens found<br />
<br />
==activate_tokens==<br />
<br />
RPC routine to to initialise the survey's collection of tokens where new participant tokens may be later added<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to list participants<br />
<br />
aAttributeFields (array) - An array of integer describing any additional attribute fields<br />
<br />
Returns:<br />
*On success: (array) Status OK<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Token table could not be created<br />
<br />
==invite_participants==<br />
<br />
RPC Routine to invite participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==remind_participants==<br />
<br />
RPC Routine to send reminder for participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
iMinDaysBetween (int) - Optional parameter days from last reminder<br />
<br />
iMaxReminders (int) - Optional parameter Maximum reminders count<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==add_response==<br />
<br />
Using this function you can add new responses to your survey response table.<br />
<br />
Parameters:<br />
*sSessionKey (string) - The session key<br />
*iSurveyID (integer) - The survey id<br />
*aResponseData (array) - array/structure containing your response data<br />
<br />
Returns:<br />
*On success: response_id (integer) - Returns the id of the inserted survey response<br />
*On failure: (array) with error description<br />
<br />
==export_responses==<br />
<br />
Export response data to pdf,csv,xls,doc<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
SurveyID (int) - Id of the Survey<br />
<br />
DocumentType (string) - pdf,csv,xls,doc, html<br />
<br />
sLanguageCode (string) - Optional The language to be used - if not given then the base language will be used<br />
<br />
CompletionStatus (string) - Optional 'complete','incomplete' or 'all' selection of responses - defaults to complete<br />
<br />
HeadingType (string) - 'code','full' or 'abbreviated'. type of question heading. Optional defaults to 'code'<br />
<br />
ResponseType (string) - 'short' or 'long' response type.Optional defaults to 'short'<br />
<br />
FromResponse (int) - Optional start number of response<br />
<br />
ToResponse (int) - Optional end number of responses<br />
<br />
Return:<br />
<br />
On success: Requested file as base 64-encoded string.<br />
<br />
On failure: Array with error information<br />
<br />
Note: If you have huge response sets try only to request a certain number of records at a time otherwise the server may run out of memory.<br />
<br />
==export_responses_by_token==<br />
<br />
Export responses data of specific token to pdf,csv,xls,doc<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
SurveyID (int) - Id of the Survey<br />
<br />
DocumentType (string) - pdf,csv,xls,doc,html<br />
<br />
sToken (string) - Token string of a candidate<br />
<br />
sLanguageCode (string) - Optional The language to be used - if not given then the base language will be used<br />
<br />
CompletionStatus (string) - Optional 'complete','incomplete' or 'all' selection of responses - defaults to complete<br />
<br />
HeadingType (string) - 'code','full' or 'abbreviated'. type of question heading. Optional defaults to 'code'<br />
<br />
ResponseType (string) - 'short' or 'long' response type.Optional defaults to 'short'<br />
<br />
aFields (array) - Optional Selected fields<br />
<br />
Return:<br />
<br />
On success: Requested file as base 64-encoded string.<br />
<br />
On failure: Array with error information<br />
<br />
=Testing=<br />
<br />
To test you will have to activate JSON-RPC in global settings. To run a simple self-test go to<br />
<br />
http://path_to_your_limesurvey_installation/index.php/admin/remotecontrol/test . This will import the example survey, do various things with it and delete it afterwards.<br />
<br />
The test assumes that you still are using the standard user 'admin' with password 'password'.<br />
<br />
The client function for this test can be found in /application/controller/admin/remotecontrol.php and the particular function is called test().<br />
<br />
=Ruby Example=<br />
<br />
==Load Requirements and Declare Values==<br />
You will first need to require the dependencies needed to establish communication with the API. Also, note that there is a username and password field that requires to be stored in plain text. I have a separate API User within my LimeSurvey to handle these calls.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
#!/usr/bin/env ruby<br />
<br />
require 'net/https'<br />
require 'uri'<br />
require 'json'<br />
<br />
username = "api_user"<br />
password = "api_user"<br />
</syntaxhighlight><br />
<br />
==Module==<br />
<br />
The below code is used to define the module LimeSurvey. Within this module is an API class. We will use this to create an instance of this module and then call on the API call wherever needed.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
module LimeSurvey<br />
class API<br />
def initialize(service_url)<br />
@uri = URI.parse(service_url)<br />
end<br />
<br />
def method_missing(name, *args)<br />
post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json<br />
resp = JSON.parse( http_post_request(post_body) )<br />
raise JSONRPCError, resp['error'] if resp['error']<br />
resp['result']<br />
end<br />
<br />
def http_post_request(post_body)<br />
http = Net::HTTP.new(@uri.host, @uri.port)<br />
request = Net::HTTP::Post.new(@uri.request_uri)<br />
request.content_type = 'application/json'<br />
request.body = post_body<br />
http.request(request).body<br />
end<br />
end<br />
<br />
class JSONRPCError < RuntimeError; end<br />
end<br />
</syntaxhighlight><br />
<br />
==API Call==<br />
This code is used to create the instance of the LimeSurvey::API module and class. You will want to change the URL to that of your RemoteControl2 URL.<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')<br />
</syntaxhighlight><br />
<br />
==Examples==<br />
This example takes the above code and puts it into play. I create a new session with the RemoteControl2 API and store the session in the variable session_key. You will want to change the ID numbers to the appropriate Survey ID in the examples.<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
system("cls")<br />
session_key = survey.get_session_key(username,password)<br />
puts "Session Key: #{session_key}"<br />
puts "\n"<br />
<br />
<br />
response = survey.get_survey_properties(session_key, "863224", ["owner_id"])<br />
puts "Properties: #{response}"<br />
puts "\n"<br />
<br />
response = survey.list_surveys(sSessionKey: session_key, sUser: "dkimura")<br />
puts "Survey List: #{response}"<br />
puts "\n"<br />
<br />
response = survey.add_participants(<br />
session_key, <br />
"863224",<br />
[email:"james.bond@example.com",lastname:"Bond",firstname:"James"]<br />
)<br />
puts "Add Participant: #{response}"<br />
puts "\n"<br />
<br />
response = survey.invite_participants(<br />
session_key, <br />
"863224"<br />
)<br />
puts "Invite Participant: #{response}"<br />
</syntaxhighlight><br />
<br />
==Example Return==<br />
<br />
From the above example, here is the return that I receive. Some of the items are returned as a hash and some items returned as an array of hashes.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
Session Key: piadscbc94vyanxwkdy8f3xii4av2b2w<br />
<br />
Properties: {"owner_id"=>"1"}<br />
<br />
Survey List: [{"sid"=>"863224", "surveyls_title"=>"Statement of Work v0.12", "startdate"=>nil, "expires"=>nil, "active"=>"Y"}]<br />
<br />
Add Participant: [{"email"=>"james.bond@example.com", "lastname"=>"Bond", "firstname"=>"James", "tid"=>"7", "token"=>"pt5ztzxndibkz4j"}]<br />
<br />
Invite Participant: {"7"=>{"name"=>"James Bond", "email"=>"james.bond@example.com", "status"=>"OK"}, "status"=>"0 left to send"}<br />
</syntaxhighlight><br />
<br />
=PHP Example=<br />
<br />
To include JSON-RPC in your application, you can write an application based on the tiny jsonRPCClient from [http://jsonrpcphp.org/ | jsonrpcphp.org]<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<?php<br />
<br />
require_once 'jsonRPCClient.php';<br />
<br />
define( 'LS_BASEURL', 'http://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL<br />
<br />
define( 'LS_USER', 'rpcuser' );<br />
<br />
define( 'LS_PASSWORD', 'mypassword' );<br />
<br />
// the survey to process<br />
<br />
$survey_id=374699;<br />
<br />
// instanciate a new client<br />
<br />
$myJSONRPCClient = new jsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );<br />
<br />
// receive session key<br />
<br />
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );<br />
<br />
// receive all ids and info of groups belonging to a given survey<br />
<br />
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );<br />
<br />
print_r($groups, null );<br />
<br />
// release the session key<br />
<br />
$myJSONRPCClient->release_session_key( $sessionKey );<br />
<br />
?><br />
<br />
</syntaxhighlight><br />
<br />
=JAVA example=<br />
To decode and code your json calls you can use the library gson as you can see in the following example:<br />
<br />
<syntaxhighlight lang="java" enclose="div"><br />
import java.io.IOException;<br />
import java.io.UnsupportedEncodingException;<br />
<br />
import org.apache.http.HttpEntity;<br />
import org.apache.http.HttpResponse;<br />
import org.apache.http.client.methods.HttpPost;<br />
import org.apache.http.entity.StringEntity;<br />
import org.apache.http.impl.client.DefaultHttpClient;<br />
import org.apache.http.util.EntityUtils;<br />
<br />
import com.google.gson.JsonElement;<br />
import com.google.gson.JsonObject;<br />
import com.google.gson.JsonParser;<br />
<br />
public class TestHttpClient {<br />
<br />
public static String parse(String jsonLine) {<br />
JsonElement jelement = new JsonParser().parse(jsonLine);<br />
JsonObject jobject = jelement.getAsJsonObject();<br />
String result = jobject.get("result").toString();<br />
return result;<br />
}<br />
<br />
<br />
public static void main(String[] args) throws UnsupportedEncodingException {<br />
DefaultHttpClient client = new DefaultHttpClient(); <br />
<br />
HttpPost post = new HttpPost("http://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");<br />
post.setHeader("Content-type", "application/json");<br />
post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": {\"username\": \"YOUR_USERNAME\", \"password\": \"YOUR_PASSWORD\" }, \"id\": 1}"));<br />
try {<br />
HttpResponse response = client.execute(post);<br />
if(response.getStatusLine().getStatusCode() == 200){<br />
HttpEntity entity = response.getEntity();<br />
String sessionKey = parse(EntityUtils.toString(entity));<br />
post.setEntity( new StringEntity("{\"method\": \"list_groups\", \"params\": {\"sSessionKey \": "+sessionKey+", \"iSurveyID \": \"ID_SURVEY\" }, \"id\": 1}"));<br />
response = client.execute(post);<br />
if(response.getStatusLine().getStatusCode() == 200){<br />
entity = response.getEntity();<br />
System.out.println(EntityUtils.toString(entity));<br />
}<br />
}<br />
<br />
<br />
} catch (IOException e) {<br />
e.printStackTrace();<br />
}<br />
}}<br />
<br />
<br />
</syntaxhighlight><br />
<br />
=JSON-RPC notes=<br />
<br />
The content-type of the HTTP request must be application/json. Most formatting errors or a failure to set the content-type header will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.<br />
<br />
<syntaxhighlight lang="php" enclose="div">Request:<br />
<br />
HTTP headers:<br />
<br />
content-type=application/json<br />
<br />
connection=Keep-Alive<br />
<br />
host=mylimesurveyhost.com<br />
<br />
content-length=65<br />
<br />
user-agent=Apache-HttpClient/4.2.2 (java 1.5)<br />
<br />
Post body:<br />
<br />
{"method":"get_session_key","params":{"username":"admin","password":"mypassword"},"id":1}<br />
<br />
Response body:<br />
<br />
{"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}</syntaxhighlight><br />
<br />
=Changes=<br />
<br />
2.0a Only three functions are supported right now: getSessionKey, releaseSessionKey, deleteSurvey<br />
<br />
2.0b Added function add_participants<br />
<br />
2.0RC5 Added import_survey, activate_survey, activate_tokens<br />
<br />
2.0 (build 121030) Added subquestions, attributes, attributes_lang and answeroptions properties for get_question_properties<br />
<br />
...<br />
<br />
for further changes check the Limesurvey release notes, thanks!<br />
<br />
[[Category:Development]]</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=RemoteControl_2_API&diff=44312RemoteControl 2 API2013-07-06T15:31:42Z<p>Sammousa: /* export_responses */</p>
<hr />
<div><br />
__TOC__<br />
<br />
=Introduction=<br />
<br />
LimeSurvey RemoteControl 2 is a XML-RPC/JSON-RPC based web service available in LimeSurvey 2.0 or later. The old [RemoteControl] will not be available any longer in version 2.<br />
<br />
LSRC2 makes it possible for developers to control specific functionality of LimeSurvey from any other application, without being restricted to PHP as a programming language.<br />
<br />
The following features are planned:<br />
* start a predefined survey (change titles and things)<br />
* add predefined groups or questions<br />
* activate the survey, restrict it to start and endtime<br />
* make it closed,<br />
* add participant data/tokens when you need them<br />
* return the unused tokens to the main application<br />
* get a fieldmap for a survey,<br />
* invite or remind the participants of your survey<br />
<br />
...and much more<br />
<br />
==Requirements==<br />
* libXML installed<br />
<br />
=Setup=<br />
<br />
== How to configure LSRC2==<br />
<br />
In a default LimeSurvey installation LSRC2 is disabled. In order to use LSRC2 you must first enable the service, and then adjust the settings to suit your needs. To enable LSRC2 login to the LimeSurvey administration, go to [[Global settings]], choose the tab 'Services' and select one of the two RPC services (XML-RPC or JSON-RPC) service.<br />
<br />
== Security==<br />
<br />
LSRC2 uses the same security measures as the normal administration login. That means that the permission set of the used username and password is the same as if you would login in the administration with that user/password. Also LSRC2 is protected against brute-force password cracking - like the normal administration login.<br />
<br />
=How to use LSRC2=<br />
<br />
The basic LSRC2 URL is: http://<your_domain>/<your_limesurvey_dir>/index.php/admin/remotecontrol<br />
<br />
LSRC2 fully complies to the [http://www.xmlrpc.com/ XML-RPC specification] and JSON-RPC version 1 specifications. We recommend in general to use JSON-RPC because it is well tested and has a much smaller footprint than XML-RPC.<br />
<br />
LSRC2 offers the following functions:<br />
<br />
==get_session_key==<br />
<br />
Using this function you can create a new XML-RPC session key. This is mandatory for all following LSRC2 function calls.<br />
<br />
Parameters: username (string), password (string)<br />
<br />
Returns:<br />
*On success: A session key (string)<br />
*On failure: for protocol-level errors (invalid format etc), an error message. For invalid username and password, returns a null error and the result body contains a 'status' name-value pair with the error message.<br />
<br />
==release_session_key==<br />
<br />
Using this function you can close a previously opened XML-RPC/JSON-RPC session.<br />
<br />
Parameters: session key (string)<br />
<br />
Returns:<br />
*Always: 'OK' (string)<br />
<br />
==get_site_settings==<br />
<br />
Function to provide with site settings only to administrators<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) The session key<br />
<br />
sSetttingName (string) - Name of the setting to get<br />
<br />
Returns:<br />
*On success: (string) Setting<br />
*On failure: (string) Error message<br />
<br />
==add_survey==<br />
<br />
RPC Routine to add an empty survey with minimum details<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (int), The wish id of the Survey to add<br />
<br />
sSurveyTitle (string), Title of the new Survey<br />
<br />
sSurveyLanguage (string), Default language of the Survey<br />
<br />
sformat (string), Question appearance format (S|G|A)<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Faulty parameters<br />
**Creation Failed<br />
<br />
==delete_survey==<br />
<br />
RPC Routine to Delete a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string), Auth credentials<br />
<br />
iSurveyID (int), The Survey to delete<br />
<br />
Returns:<br />
*On success: Status =>OK (array)<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
<br />
==import_survey==<br />
<br />
RPC Routine to import a survey from lss,csv,xls or survey zip archive.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sImportData (string) String containing the BASE 64 encoded data of a lss,csv,xls or survey zip archive<br />
<br />
sImportDataType (string), The format of the import file (lss,csv,xls or zip)<br />
<br />
sNewSurveyName (string), The optional new name of the survey (base language)<br />
<br />
DestSurveyID (int), This is the new ID of the survey - if already used a random one will be taken instead<br />
<br />
Returns:<br />
*On success: (int) $iNewSurveyID<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Import error<br />
<br />
==get_survey_properties==<br />
<br />
RPC Routine to get properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An array with the properties to return<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
{|<br />
| || || || || ||<br />
|-<br />
| sid|| savetimings|| allowprev|| tokenanswerspersistence|| showgroupinfo|| showwelcome<br />
|-<br />
| owner_id|| template|| printanswers|| assessments|| shownoanswer || showprogress<br />
|-<br />
| admin|| language|| ipaddr|| usecaptcha|| showqnumcode|| allowjumps<br />
|-<br />
| active|| additional_languages || refurl|| usetokens|| bouncetime|| navigationdelay<br />
|-<br />
| expires|| datestamp|| datecreated|| bounce_email|| bounceprocessing|| nokeyboard<br />
|-<br />
| startdate|| usecookie|| publicstatistics|| attributedescriptions|| bounceaccounttype|| alloweditaftercompletion<br />
|-<br />
| adminemail|| allowregister|| publicgraphs|| emailresponseto|| bounceaccounthost|| googleanalyticsstyle<br />
|-<br />
| anonymized|| allowsave|| listpublic|| emailnotificationto|| bounceaccountpass|| googleanalyticsapikey<br />
|-<br />
| faxto|| autonumber_start|| htmlemail|| tokenlength|| bounceaccountencryption||<br />
|-<br />
|format|| autoredirect|| sendconfirmation|| showxquestions|| bounceaccountuser|| <br />
|}<br />
<br />
==set_survey_properties==<br />
<br />
RPC Routine to set properties of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveySettings (array), An assosiative array with the name-value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) The result of the change for each property<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available properties:<br />
<br />
Properties available for changing are all those defined in get_survey_properties with the following exceptions<br />
<br />
{|<br />
|properties not allowed to be modified|| Properties not allowed to be modified when survey active<br />
|-<br />
|sid||anonymized<br />
|-<br />
|language||datestamp<br />
|-<br />
|additional_languages||savetimings<br />
|-<br />
|active||ipaddr<br />
|-<br />
|||refurl<br />
|-<br />
|<br />
|}<br />
<br />
==list_surveys==<br />
<br />
RPC Routine to list the ids and info of surveys belonging to a user.<br />
<br />
* If user is admin he can get surveys of every user (parameter sUser) or all surveys (sUser=null)<br />
<br />
* Else only the syrveys belonging to the user requesting will be shown.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
sUser (string) - The users surveys to list<br />
<br />
Returns:<br />
*On success: (array) Survey's properties<br />
*On failure: (array) Failure status<br />
**Invalid user<br />
**Invalid session key<br />
**No permission<br />
**No surveys found<br />
<br />
Survey's properties:<br />
<br />
{|<br />
|property||type<br />
|-<br />
|sid||integer<br />
|-<br />
|surveyls_title||string<br />
|-<br />
|startdate||date<br />
|-<br />
|expires||date<br />
|-<br />
|active||y/n<br />
|-<br />
|<br />
|}<br />
<br />
==activate_survey==<br />
<br />
RPC Routine that launches a newly created survey (sets active -available for users)<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
Returns<br />
*On success: (array) The result of the activation<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Activation Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==export_statistics==<br />
<br />
RPC routine to export statistics of a survey to a user.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
docType (string) - Type of document to generate<br />
<br />
sLanguage (string) Optional language of the survey to use (if not set, default language is selected)<br />
<br />
graph (string) - Optional parameter to enable graphs (0|1)<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid session key<br />
**No permission<br />
<br />
==get_summary==<br />
<br />
RPC routine to get survey summary, regarding token usage and survey participation.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
sStatname (string) - The statistic to return<br />
<br />
Returns<br />
*On success: (string) Base64 encoded string with the statistics file<br />
*On failure: (array) Failure status<br />
**No available data<br />
**No such property<br />
**Invalid session key<br />
**No permission<br />
<br />
Available statistics:<br />
<br />
{|<br />
|Survey stats||Token stats<br />
|-<br />
|completed_responses||token_count<br />
|-<br />
|incomplete_responses||token_invalid<br />
|-<br />
|full_responses||tokens_sent<br />
|-<br />
|||token_opted_out<br />
|-<br />
|||token_completed<br />
|-<br />
|<br />
|}<br />
<br />
==add_language==<br />
<br />
RPC Routine to add a language to an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) - The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the new language to be added. Note: If the language is already in that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Error<br />
**Invalid session key<br />
**No permission<br />
<br />
==delete_survey_language==<br />
<br />
RPC Routine to delete a language of an existing survey<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
SurveyID (integer) - ID of the survey<br />
<br />
aLanguage (string) - The language shortcut for the language to be removed. Note: If the language is not part of that survey no error will be thrown.<br />
<br />
Return values:<br />
*On success: (array) status=>OK<br />
*On failure: (array) Any other status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Cannot remove base language<br />
**Error<br />
**No permission<br />
**Invalid session key<br />
<br />
==get_language_properties==<br />
<br />
RPC Routine to get survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleSettings (array) - An array with the properties to return<br />
<br />
slang (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) the requested value<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Available parameters:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
| surveyls_survey_id || surveyls_url || surveyls_email_register_subj || email_admin_notification_subj<br />
|-<br />
| surveyls_language || surveyls_urldescription || surveyls_email_register || email_admin_notification<br />
|-<br />
| surveyls_title || surveyls_email_invite_subj || surveyls_email_confirm_subj || email_admin_responses_subj<br />
|-<br />
| surveyls_description || surveyls_email_invite || surveyls_email_confirm || email_admin_responses<br />
|-<br />
| surveyls_welcometext || surveyls_email_remind_subj || surveyls_dateformat || surveyls_numberformat<br />
|-<br />
|surveyls_endtext || surveyls_email_remind || surveyls_attributecaptions || <br />
|}<br />
<br />
==set_language_properties==<br />
<br />
RPC Routine to set survey language properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey<br />
<br />
aSurveyLocaleData (array) - An assosiative array with the key-value pairs of properties to set. Invalid fieldnames or fields that may not be modified are ignored.<br />
<br />
sLanguage (string) - The language to use<br />
<br />
Returns:<br />
*On success: (string) Result for each parameter set<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Invalid language<br />
**Invalid session key<br />
**No permission<br />
**No valid Data<br />
<br />
Allowed Parameters:<br />
<br />
All those defined in get-language_properties except:<br />
*surveyls_language<br />
*surveyls_survey_id<br />
<br />
==add_group==<br />
<br />
RPC Routine to add an empty group with minimum details.<br />
<br />
* Used as a placeholder for importing questions.<br />
<br />
* Returns the groupid of the created group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the surveythat the group will be added<br />
<br />
sGroupTitle (string) - Name of the new group<br />
<br />
sGroupDescription (string) - Optional description of the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Creation Failed<br />
<br />
==delete_group==<br />
<br />
RPC Routine to delete a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - ID of the survey that the group belongs<br />
<br />
sGroupID (int) - Id of the group to delete<br />
<br />
Returns:<br />
*On success: (int) The ID of the deleted group<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**Invalid Group ID<br />
**Error:Survey is active and not editable<br />
**Invalid session key<br />
**No permission<br />
**Group deletion failed<br />
<br />
==import_group==<br />
<br />
RPC Routine to import a group - imports lsg,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey that the group will belong<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sGroupDescription (string) -The format of the importfile in the stream (lsg|csv)<br />
<br />
sNewGroupName (string) - Optional new name for the group<br />
<br />
sNewGroupDescription (string) - Optional new description for the group<br />
<br />
Returns:<br />
*On success: (int) The ID of the new group<br />
*On failure: (array) Failure status<br />
**Invalid survey ID<br />
**Error:Survey is active and not editable<br />
**Invalid extension<br />
**Error: Invalid LimeSurvey group structure XML<br />
**Invalid session key<br />
**No permission<br />
**Import Error<br />
<br />
==get_group_properties==<br />
<br />
RPC Routine to return properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to get properties of<br />
<br />
aGroupSettings (array) - Array containing the properties to request.<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|gid||description<br />
|-<br />
|sid||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==set_group_properties==<br />
<br />
RPC Routine to set properties of a group of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iGroupID (integer) - The id of the group to set properties to<br />
<br />
aGroupData (array) - Assosiative Array containing key-value pairs of the properties to set.<br />
<br />
Returns:<br />
*On success: (array) The result of each set action<br />
*On failure: (array) Failure status<br />
**Error: Invalid group ID<br />
**No valid Data<br />
**Group with dependencies - Order cannot be changed<br />
**Invalid session key<br />
**No permission<br />
<br />
Available properties:<br />
<br />
{|<br />
| ||<br />
|-<br />
|||description<br />
|-<br />
|||language<br />
|-<br />
|group_name||randomization_group<br />
|-<br />
|group_order||grelevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_groups==<br />
<br />
RPC Routine to return the ids and info of groups belonging to survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (integer) - The id of the survey to get groups of<br />
<br />
Returns:<br />
*On success: (array) The list of the groups<br />
*On failure: (array) Failure status<br />
**Invalid Survey ID<br />
**No groups found<br />
**Invalid session key<br />
**No permission<br />
<br />
==delete_question==<br />
<br />
RPC Routine to delete a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to delete<br />
<br />
Returns:<br />
*On success: (int)id of the deleted Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
** Invalid question ID<br />
**Survey is active and not editable<br />
**Cannot delete Question. Others rely on this question<br />
**Error<br />
<br />
==import_question==<br />
<br />
RPC Routine to import a question - imports lsq,csv<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey that the new questions belongs<br />
<br />
iGroupID (int) - Id of the group that the new questions belongs<br />
<br />
sImportData (string) - String containing the BASE 64 encoded data of a lsg,csv<br />
<br />
sImportDataType (string) - Format of the input stream (lsq,csv)<br />
<br />
sMandatory (string) - Optional Mandatory question option (default to No)<br />
<br />
sNewQuestionTitle (string) - Optional new title for the question<br />
<br />
sNewqQuestion (string) - An optional new question<br />
<br />
sNewQuestionHelp (string) - An optional new question help text<br />
<br />
Returns:<br />
*On success: (int) Id of the new Question<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Invalid group ID<br />
**Survey is active and not editable<br />
**Invalid extension<br />
**Invalid LimeSurvey question structure XML<br />
<br />
==get_question_properties==<br />
<br />
RPC Routine to return properties of a question of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) Auth credentials<br />
<br />
iQuestionID (int) Id of the question to get properties of<br />
<br />
aQuestionSettings (array) The properties to get<br />
<br />
sLanguage (string) Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The requested properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || || ||<br />
|-<br />
|gid||type||help||language<br />
|-<br />
|parent_qid||title||other||scale_id<br />
|-<br />
|sid||question||mandatory||same_default<br />
|-<br />
|gid||preg||question_order||relevance<br />
|-<br />
|subquestions||attributes||attributes_lang||answeroptions<br />
|-<br />
|<br />
|}<br />
<br />
==set_question_properties==<br />
<br />
RPC Routine to set question properties<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iQuestionID (int) - Id of the question to get properties of<br />
<br />
aQuestionData (array) - An array with the particular fieldnames as keys and their values to set on that particular question<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The resilt of the set of each property<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Questions with dependencies - Order cannot be changed<br />
**No valid Data<br />
<br />
Available Properties:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|help|| ||<br />
|-<br />
|title||other||scale_id<br />
|-<br />
|question||mandatory||same_default<br />
|-<br />
|preg||question_order||relevance<br />
|-<br />
|<br />
|}<br />
<br />
==list_questions==<br />
<br />
RPC Routine to return the ids and info of questions of a survey/group.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
iGroupID (int) - Id of the group to get questions of<br />
<br />
sLanguage (string) - Optional parameter language for multilingual questions<br />
<br />
Returns:<br />
*On success: (array) The list of the questions<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid questionid<br />
**Invalid language<br />
**Invalid survey ID<br />
**Missmatch in surveyid and groupid<br />
**No questions found<br />
<br />
==activate_tokens==<br />
<br />
Activate tokens<br />
<br />
Parameters:<br />
<br />
session key (string) The session key<br />
<br />
surveyid (string) The survey ID<br />
<br />
additional_attributes (array of integers) Any additional attribute fields to create. Just give the attribute IDs<br />
<br />
Returns:<br />
*On success: (array) status OK<br />
*On failure: (array) Any other status<br />
<br />
==add_participants==<br />
<br />
Using this function you can add new entries to your token table. You can also set if for these new entries a token key is automatically created. Please note that this function does not check for duplicate content in any of the fields, except for token keys created by the function itself.<br />
<br />
Parameters:<br />
*sessionkey (string) - The session key<br />
*surveyID (string) - The survey id<br />
*participantData (array) - 2-dimensional array/structure containing your participants data<br />
*createTokenKey (boolean) - Set this to true if you want a token key create automatically for each entry - if your participant data included a [token] field it will be overwritten<br />
<br />
Returns:<br />
*On success: participant data (struct) - structure containing your participants data plus the token ID and (if applicable) the new token<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
<br />
JSON-RPC example:<br />
<br />
<syntaxhighlight lang="php" enclose="div">Request:<br />
<br />
{"id":"1","method":"add_participants","params":{"sessionkey":"73e8rx864rnxmk64gp67bah44u2igivm","surveyID":"668138","participantData":[{"email":"me@example.com","lastname":"Bond","firstname":"James"}]}}<br />
<br />
Response:<br />
<br />
{"id":"1","result":[{"email":"me@example.com","lastname":"Bond","firstname":"James","tid":"1","token":"auc82gar58dpcg6"}],"error":null}</syntaxhighlight><br />
<br />
==delete_participants==<br />
<br />
RPC Routine to delete multiple participants of a Survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to get questions of<br />
<br />
aTokenIDs (array) - IId of the tokens/participants to delete<br />
<br />
Returns:<br />
*On success: (array) Array of deletion status for each participant<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
<br />
==get_participant_properties==<br />
<br />
RPC Routine to return settings of a token/participant of a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to get token properties<br />
<br />
iTokenID (int) - Id of the participant to check<br />
<br />
aTokenProperties (array) - The properties to get<br />
<br />
Returns:<br />
*On success: (array) Array of requested values<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
|tid|| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==set_participant_properties==<br />
<br />
RPC Routine to set properties of a survey participant/token<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the Survey to set token properties<br />
<br />
iTokenID (int) - Id of the participant to alter<br />
<br />
aTokenData (array) - Key - value pair of the properties to set<br />
<br />
Returns:<br />
*On success: (array) Array of results of changing properties<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**Invalid tokenid<br />
**No valid Data<br />
<br />
Available Parameters:<br />
<br />
{|<br />
| || ||<br />
|-<br />
||| token|| completed<br />
|-<br />
| participant_id || language|| usesleft<br />
|-<br />
|firstname|| blacklisted|| validfrom<br />
|-<br />
| lastname|| sent|| validuntil<br />
|-<br />
|email|| remindersent|| mpid<br />
|-<br />
|emailstatus|| remindercount|| <br />
|}<br />
<br />
==list_participants==<br />
<br />
RPC routine to return the IDs and info of token/participants of a survey.<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
iSurveyID (int) - Id of the survey to list participants<br />
iStart (int) - Start id of the token list<br />
iLimit (int) - Number of participants to return<br />
bUnused (bool) - If you want unused tokensm, set true<br />
aAttributes(bool|array) An array of extended attributes that can be requested, besides the default ones (default value to false)<br />
<br />
Returns:<br />
*On success: (array) Array of Participants info<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No Tokens found<br />
<br />
==activate_tokens==<br />
<br />
RPC routine to to initialise the survey's collection of tokens where new participant tokens may be later added<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to list participants<br />
<br />
aAttributeFields (array) - An array of integer describing any additional attribute fields<br />
<br />
Returns:<br />
*On success: (array) Status OK<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**Token table could not be created<br />
<br />
==invite_participants==<br />
<br />
RPC Routine to invite participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==remind_participants==<br />
<br />
RPC Routine to send reminder for participants in a survey<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
iSurveyID (int) - Id of the survey to send invitation to participants<br />
<br />
iMinDaysBetween (int) - Optional parameter days from last reminder<br />
<br />
iMaxReminders (int) - Optional parameter Maximum reminders count<br />
<br />
Returns:<br />
*On success: (array) Array of result of each email send action and count of invitations left to send<br />
*On failure: (array) Failure status<br />
**Invalid session key<br />
**No permission<br />
**Invalid survey ID<br />
**No token table<br />
**No candidate tokens<br />
<br />
==add_response==<br />
<br />
Using this function you can add new responses to your survey response table.<br />
<br />
Parameters:<br />
*sSessionKey (string) - The session key<br />
*iSurveyID (integer) - The survey id<br />
*aResponseData (array) - array/structure containing your response data<br />
<br />
Returns:<br />
*On success: response_id (integer) - Returns the id of the inserted survey response<br />
*On failure: (array) with error description<br />
<br />
==export_responses==<br />
<br />
Export response data to pdf,csv,xls,doc<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
SurveyID (int) - Id of the Survey<br />
<br />
DocumentType (string) - pdf,csv,xls,doc, html<br />
<br />
sLanguageCode (string) - Optional The language to be used - if not given then the base language will be used<br />
<br />
CompletionStatus (string) - Optional 'complete','incomplete' or 'all' selection of responses - defaults to complete<br />
<br />
HeadingType (string) - 'code','full' or 'abbreviated'. type of question heading. Optional defaults to 'code'<br />
<br />
ResponseType (string) - 'short' or 'long' response type.Optional defaults to 'short'<br />
<br />
FromResponse (int) - Optional start number of response<br />
<br />
ToResponse (int) - Optional end number of responses<br />
<br />
Return:<br />
<br />
On success: Requested file as base 64-encoded string.<br />
<br />
On failure: Array with error information<br />
<br />
Note: If you have huge response sets try only to request a certain number of records at a time otherwise the server may run out of memory.<br />
<br />
==export_responses_by_token==<br />
<br />
Export responses data of specific token to pdf,csv,xls,doc<br />
<br />
Parameters:<br />
<br />
sSessionKey (string) - Auth credentials<br />
<br />
SurveyID (int) - Id of the Survey<br />
<br />
DocumentType (string) - pdf,csv,xls,doc<br />
<br />
sToken (string) - Token string of a candidate<br />
<br />
sLanguageCode (string) - Optional The language to be used - if not given then the base language will be used<br />
<br />
CompletionStatus (string) - Optional 'complete','incomplete' or 'all' selection of responses - defaults to complete<br />
<br />
HeadingType (string) - 'code','full' or 'abbreviated'. type of question heading. Optional defaults to 'code'<br />
<br />
ResponseType (string) - 'short' or 'long' response type.Optional defaults to 'short'<br />
<br />
aFields (array) - Optional Selected fields<br />
<br />
Return:<br />
<br />
On success: Requested file as base 64-encoded string.<br />
<br />
On failure: Array with error information<br />
<br />
<br />
<br />
=Testing=<br />
<br />
To test you will have to activate JSON-RPC in global settings. To run a simple self-test go to<br />
<br />
http://path_to_your_limesurvey_installation/index.php/admin/remotecontrol/test . This will import the example survey, do various things with it and delete it afterwards.<br />
<br />
The test assumes that you still are using the standard user 'admin' with password 'password'.<br />
<br />
The client function for this test can be found in /application/controller/admin/remotecontrol.php and the particular function is called test().<br />
<br />
=Ruby Example=<br />
<br />
==Load Requirements and Declare Values==<br />
You will first need to require the dependencies needed to establish communication with the API. Also, note that there is a username and password field that requires to be stored in plain text. I have a separate API User within my LimeSurvey to handle these calls.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
#!/usr/bin/env ruby<br />
<br />
require 'net/https'<br />
require 'uri'<br />
require 'json'<br />
<br />
username = "api_user"<br />
password = "api_user"<br />
</syntaxhighlight><br />
<br />
==Module==<br />
<br />
The below code is used to define the module LimeSurvey. Within this module is an API class. We will use this to create an instance of this module and then call on the API call wherever needed.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
module LimeSurvey<br />
class API<br />
def initialize(service_url)<br />
@uri = URI.parse(service_url)<br />
end<br />
<br />
def method_missing(name, *args)<br />
post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json<br />
resp = JSON.parse( http_post_request(post_body) )<br />
raise JSONRPCError, resp['error'] if resp['error']<br />
resp['result']<br />
end<br />
<br />
def http_post_request(post_body)<br />
http = Net::HTTP.new(@uri.host, @uri.port)<br />
request = Net::HTTP::Post.new(@uri.request_uri)<br />
request.content_type = 'application/json'<br />
request.body = post_body<br />
http.request(request).body<br />
end<br />
end<br />
<br />
class JSONRPCError < RuntimeError; end<br />
end<br />
</syntaxhighlight><br />
<br />
==API Call==<br />
This code is used to create the instance of the LimeSurvey::API module and class. You will want to change the URL to that of your RemoteControl2 URL.<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
survey = LimeSurvey::API.new('http://localhost/limesurvey/index.php?r=admin/remotecontrol')<br />
</syntaxhighlight><br />
<br />
==Examples==<br />
This example takes the above code and puts it into play. I create a new session with the RemoteControl2 API and store the session in the variable session_key. You will want to change the ID numbers to the appropriate Survey ID in the examples.<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
system("cls")<br />
session_key = survey.get_session_key(username,password)<br />
puts "Session Key: #{session_key}"<br />
puts "\n"<br />
<br />
<br />
response = survey.get_survey_properties(session_key, "863224", ["owner_id"])<br />
puts "Properties: #{response}"<br />
puts "\n"<br />
<br />
response = survey.list_surveys(sSessionKey: session_key, sUser: "dkimura")<br />
puts "Survey List: #{response}"<br />
puts "\n"<br />
<br />
response = survey.add_participants(<br />
session_key, <br />
"863224",<br />
[email:"james.bond@example.com",lastname:"Bond",firstname:"James"]<br />
)<br />
puts "Add Participant: #{response}"<br />
puts "\n"<br />
<br />
response = survey.invite_participants(<br />
session_key, <br />
"863224"<br />
)<br />
puts "Invite Participant: #{response}"<br />
</syntaxhighlight><br />
<br />
==Example Return==<br />
<br />
From the above example, here is the return that I receive. Some of the items are returned as a hash and some items returned as an array of hashes.<br />
<br />
<syntaxhighlight lang="ruby" enclose="div"><br />
Session Key: piadscbc94vyanxwkdy8f3xii4av2b2w<br />
<br />
Properties: {"owner_id"=>"1"}<br />
<br />
Survey List: [{"sid"=>"863224", "surveyls_title"=>"Statement of Work v0.12", "startdate"=>nil, "expires"=>nil, "active"=>"Y"}]<br />
<br />
Add Participant: [{"email"=>"james.bond@example.com", "lastname"=>"Bond", "firstname"=>"James", "tid"=>"7", "token"=>"pt5ztzxndibkz4j"}]<br />
<br />
Invite Participant: {"7"=>{"name"=>"James Bond", "email"=>"james.bond@example.com", "status"=>"OK"}, "status"=>"0 left to send"}<br />
</syntaxhighlight><br />
<br />
=PHP Example=<br />
<br />
To include JSON-RPC in your application, you can write an application based on the tiny jsonRPCClient from [http://jsonrpcphp.org/ | jsonrpcphp.org]<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<?php<br />
<br />
require_once 'jsonRPCClient.php';<br />
<br />
define( 'LS_BASEURL', 'http://localhost/limesurvey/'); // adjust this one to your actual LimeSurvey URL<br />
<br />
define( 'LS_USER', 'rpcuser' );<br />
<br />
define( 'LS_PASSWORD', 'mypassword' );<br />
<br />
// the survey to process<br />
<br />
$survey_id=374699;<br />
<br />
// instanciate a new client<br />
<br />
$myJSONRPCClient = new jsonRPCClient( LS_BASEURL.'/admin/remotecontrol' );<br />
<br />
// receive session key<br />
<br />
$sessionKey= $myJSONRPCClient->get_session_key( LS_USER, LS_PASSWORD );<br />
<br />
// receive all ids and info of groups belonging to a given survey<br />
<br />
$groups = $myJSONRPCClient->list_groups( $sessionKey, $survey_id );<br />
<br />
print_r($groups, null );<br />
<br />
// release the session key<br />
<br />
$myJSONRPCClient->release_session_key( $sessionKey );<br />
<br />
?><br />
<br />
</syntaxhighlight><br />
<br />
=JAVA example=<br />
To decode and code your json calls you can use the library gson as you can see in the following example:<br />
<br />
<syntaxhighlight lang="java" enclose="div"><br />
import java.io.IOException;<br />
import java.io.UnsupportedEncodingException;<br />
<br />
import org.apache.http.HttpEntity;<br />
import org.apache.http.HttpResponse;<br />
import org.apache.http.client.methods.HttpPost;<br />
import org.apache.http.entity.StringEntity;<br />
import org.apache.http.impl.client.DefaultHttpClient;<br />
import org.apache.http.util.EntityUtils;<br />
<br />
import com.google.gson.JsonElement;<br />
import com.google.gson.JsonObject;<br />
import com.google.gson.JsonParser;<br />
<br />
public class TestHttpClient {<br />
<br />
public static String parse(String jsonLine) {<br />
JsonElement jelement = new JsonParser().parse(jsonLine);<br />
JsonObject jobject = jelement.getAsJsonObject();<br />
String result = jobject.get("result").toString();<br />
return result;<br />
}<br />
<br />
<br />
public static void main(String[] args) throws UnsupportedEncodingException {<br />
DefaultHttpClient client = new DefaultHttpClient(); <br />
<br />
HttpPost post = new HttpPost("http://PATH_OF_YOUR_SERVER/index.php/admin/remotecontrol");<br />
post.setHeader("Content-type", "application/json");<br />
post.setEntity( new StringEntity("{\"method\": \"get_session_key\", \"params\": {\"username\": \"YOUR_USERNAME\", \"password\": \"YOUR_PASSWORD\" }, \"id\": 1}"));<br />
try {<br />
HttpResponse response = client.execute(post);<br />
if(response.getStatusLine().getStatusCode() == 200){<br />
HttpEntity entity = response.getEntity();<br />
String sessionKey = parse(EntityUtils.toString(entity));<br />
post.setEntity( new StringEntity("{\"method\": \"list_groups\", \"params\": {\"sSessionKey \": "+sessionKey+", \"iSurveyID \": \"ID_SURVEY\" }, \"id\": 1}"));<br />
response = client.execute(post);<br />
if(response.getStatusLine().getStatusCode() == 200){<br />
entity = response.getEntity();<br />
System.out.println(EntityUtils.toString(entity));<br />
}<br />
}<br />
<br />
<br />
} catch (IOException e) {<br />
e.printStackTrace();<br />
}<br />
}}<br />
<br />
<br />
</syntaxhighlight><br />
<br />
=JSON-RPC notes=<br />
<br />
The content-type of the HTTP request must be application/json. Most formatting errors or a failure to set the content-type header will result in a null response from the server (not a JSON response). Below is an example of a valid request and response pair.<br />
<br />
<syntaxhighlight lang="php" enclose="div">Request:<br />
<br />
HTTP headers:<br />
<br />
content-type=application/json<br />
<br />
connection=Keep-Alive<br />
<br />
host=mylimesurveyhost.com<br />
<br />
content-length=65<br />
<br />
user-agent=Apache-HttpClient/4.2.2 (java 1.5)<br />
<br />
Post body:<br />
<br />
{"method":"get_session_key","params":{"username":"admin","password":"mypassword"},"id":1}<br />
<br />
Response body:<br />
<br />
{"id":1,"result":"6htqat38fyr4v7iu72nqgv7xgavkvfcz","error":null}</syntaxhighlight><br />
<br />
=Changes=<br />
<br />
2.0a Only three functions are supported right now: getSessionKey, releaseSessionKey, deleteSurvey<br />
<br />
2.0b Added function add_participants<br />
<br />
2.0RC5 Added import_survey, activate_survey, activate_tokens<br />
<br />
2.0 (build 121030) Added subquestions, attributes, attributes_lang and answeroptions properties for get_question_properties<br />
<br />
...<br />
<br />
for further changes check the Limesurvey release notes, thanks!<br />
<br />
[[Category:Development]]</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Survey_settings&diff=43940Survey settings2013-07-01T06:26:52Z<p>Sammousa: </p>
<hr />
<div><languages /><br />
<translate><br />
<br />
<!--T:2--><br />
__TOC__<br />
<br />
=Overview= <!--T:3--><br />
<br />
<!--T:4--><br />
To create a new survey, click on the Add button [[File:add.png]] on the right side of the administration button bar and a "Create New Survey" screen will appear. You can edit most of these settings later again by click the 'Edit survey settings' icon [[File:token_manage_30.png]] in the 'Survey properties' dropdown menu of the survey toolbar.<br />
<br />
=Settings= <!--T:5--><br />
<br />
<!--T:6--><br />
All survey settings and functions are organized in tabs. The following is a description of each tab and field.<br />
<br />
==General== <!--T:7--><br />
#'''Base language''': This sets the base language for the survey. Once saved, you cannot change it later. The language-set is the base language for possible translations of the survey. That way you can have multilingual surveys. During survey creation you cannot add additional languages. You will be able do that if you edit the survey properties again, later.<br />
#'''Title''': This is the brief descriptive name of the survey (ie: "Enterprise Bargaining Survey 2003", or "Views on Ice Cream"). This title will be displayed on every page of the public survey.<br />
#'''Description''': This allows you to enter a description of the survey. (ie: "A survey to collect your ideas on the next round of enterprise bargaining" or "A survey to find out the popularity of chocolate ice cream"). You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor. By default, description is used on invitation email.<br />
#'''Welcome message''': This allows you to enter a message that will display when a participant first logs into your survey. (ie: "Thank you for taking the time to participate in this survey..") You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor.<br />
#'''End message''': This allows you to enter a message that will display when a participant completes your survey. (ie: "Thank you for completing our survey. We will publish results soon."). You can incorporate HTML elements such as images or videos in this section using the WYSIWYG editor.<br />
#'''End URL''': This URL will be presented as a link at the end of the survey, and allows you to direct your participants back to your home page (or, in fact, anywhere). The End URL has to be entered with "http://" at the beginning, eg. http://www.limesurvey.org. <br />You can use they placeholder {SAVEDID}, {TOKEN}, {SID} and {LANG} in this URL.<br />SAVEDID is the id assigned to this particular submission, TOKEN is the token used to participate in the survey, SID is the survey ID and LANG is the language code<br />eg. http://www.limesurvey.org/test.php?var1={SAVEDID}&var2;={TOKEN}&var3;={SID}&lang;={LANG} <br />From version 1.82+ you can use [[URL fields]] with this field to pass parameters from the start URL to then end URL. <br />You can also use {INSERTANS:SGQA} in this URL (since 1.82+). This allows adding the response to a specific question in the survey to the final url. This can be useful for sending a response to an external script (ie an email address collected during the survey). eg: "http://www.limesurvey.org/test.php?email={INSERTANS:1234X56X7}"<br />
#'''URL description''': The description for the link using the End URL.<br />
#'''Administrator''': This is the name of the contact person who administers the survey. It will be included in emails sent out inviting participants to respond.<br />
#'''Admin email''': This is the email address of the administrator (as above) and is used as the 'reply to:' address on any emails sent. You can also enter several email addresses separated with a semicolon - that way survey administrator notifications are sent to more than one person. (Example: "firstaddress@test.com;secondaddress@test.com")<br />
#'''Bounce email''': This is the email address where a delivery error notification email should be sent. By default, this is the same as the administrator's email address. If you want to use a custom script to parse delivery error emails, then use a special Bounce Email address here and automatically process emails reaching this address with your script. This script could then update the Email Status field of the token line corresponding to this email address (see tokens).<br />
#'''Fax to''': This field is used to give a fax number on the "printable survey" - ie: when you want to send someone a hard copy because they cannot use the online survey.<br />
<br />
<!--T:8--><br />
<div class="simplebox">'''Caution''': the HTML WYSIWYG editor doesn't allow you to upload files during the survey creation process. Trying to do so will end up with an error message like: "''This file uploader is disabled''". If you need to upload pictures or any other ressources, please do so after survey creation, by editing the newly created survey.</div><br />
<br />
==Presentation & navigation== <!--T:9--><br />
#'''Format''': Choose from "Question by question", "Group by group" or "All in one".<br />
#:[[File:Setting_Pres_Format_EN.png]]<br />
#*'''Question by Question''': Public survey will display one question per page.<br />
#*'''Group by Group''': Public survey will display all questions in a group per page. Group at a time surveys still have a separate "welcome" page and "submit" page, like "Question by Question" surveys.<br />
#*'''All in one''': Public survey will display all questions in one single page. Activated All in one surveys do not have a "welcome" page or "submit" page - the welcome message and submit button all appear on the same page.<br />
#'''Template''': Choose from the installed templates in your system. The default template is rather dull, but functional. More information on creating your own templates is available [[The template editor|here]].<br />
#'''Show welcome screen''': Yes/No. If Yes, then the welcome message defined in Text Elements section will be displayed. Default is Yes.<br />
#'''Navigation delay''': Number of seconds before Previous and Next buttons are enabled. Default 0 seconds<br />
#'''Show <nowiki>[</nowiki><< Prev] button''': This option defaults to yes, however if you set it to "No" then users will not have the option of moving to a previous page while completing the survey.<br />
#'''Show question index / allow jumping''': Yes/No. Default No. When Yes, an index will be displayed on the right side. Users can jump to any section in the survey. In 2.05 the options have changed to Disabled / Incremental / Full. Disabled and Incremental represent the current No and Yes options. Full always shows all groups / questions, this allows the user to freely navigate through the survey. This might not work for all kinds of conditions.<br />
#'''Keyboard-less operation''': By activating this setting there will be a virtual keyboard available for certain question types.<br />
#'''Show progress bar''': Yes/No. Default Yes. Allow the administrator to turn off the Progress bar<br />
#'''Participants may print answers?''': This option defaults to no. When it is set to yes, a participant can print a summary of responses at submit time.<br />
#'''Public statistics''': Yes/No. Default No. If set to "Yes" users who have submitted the survey will be presented a link to statistics of the current survey. The admin can set which questions should be included at these statistics by [[Advanced question settings#public_statistics|applying the according question attribute]].<br />
#'''Show graphs in public statistics''': (''since 1.80'') Determines if public statistics for this survey include graphs or only show a tabular overview. Creating graphs for huge surveys with lots of answers takes some time and server resources so this is the switch to turn them on/off (default setting: ''off'').<br />
#'''Automatically load URL when survey complete''': Yes/No. Default No. If yes, when the survey is submitted, it will automatically redirect to the End URL. The end URL can be defined in the Text Elements Section. Please note that this only works on an active survey.<br />
#'''Show "There are X questions in this survey"''': Yes/No. Default Yes. If Yes, the message will be displayed on the Welcome Screen. This option will not affect the print version.<br />
#'''Show group name and/or group description''': Will control the display of Group Names and Descriptions. This option will not affect the print version. Four Options:<br />
#*'''Show Both''' - Default<br />
#*'''Show Group Names Only'''<br />
#*'''Show group description Only'''<br />
#*'''Hide Both'''<br />
#'''Show question number and/or code''':<br />
#*'''Show Both''' - Default<br />
#*'''Show Question Number Only'''<br />
#*'''Show Question Code Only'''<br />
#*'''Hide Both'''<br />
#'''Show "No answer"''': Yes/No. Default Yes. When Yes, the No Answer will be displayed as the default option for non-mandatory single-select questions. Be aware that if you switch this off, the participant won't be able to unselect a chosen answer option in a non-mandatory question.<br />
<br />
==Publication & access control== <!--T:10--><br />
#'''List survey publicly''': Yes/No. Default No. When it is set to yes, your survey will be listed in the 'available surveys' portal<br />
# '''Start date/time''': Set this to some date if you want your survey to start on a certain date. The survey will start on midnight of that day and only then will people be able to answer to it. To disable this just clear the date from the input field.<br />
#'''Expiry date/time''': Set this to some date if you want your survey to expire on a special date. This is the last date on which the public survey script will let people participate. (Example: If you set it for the 31st of December, then people will no longer be able to use the survey script on the 1st of January). To disable this just clear the date from the input field.<br />
#'''Set cookie to prevent repeated participation?''': If you set this to 'Yes', and your survey does not use a tokens table to control participant access, then a cookie will be saved to the client computer of each survey participant once they have submitted a survey. This cookie will stop the same user on that computer from accessing the survey more than once. There are inherent limitations in the 'security' strength of such a system, but, in general, it allows you to retain some control over multiple entries on public surveys.<br />
#'''Use CAPTCHA for''': With this option you can decide when you want a CAPTCHA to be used. Default is to enable CAPTCHA only for the public Registration page, but you can also enable it before accessing the survey, and before Load/Saving partial answers.<br />
<br />
==Notification & data management== <!--T:11--><br />
#'''Send basic admin notification email to:''' and '''Send detailed admin notification email to:''' These fields allow you to send notifications or survey responses to additional email addresses once the survey is submitted. You can edit the templates for these emails under 'Email templates'. Multiple recipients can be set by seperating the entries with a semicolon (;) - eg "yourname@test.com; myname@test.com;hisname@test.com" OR when using placeholders "yourname@test.com;{INSERTANS:82733X12X73};{TOKEN:EMAIL}". Make sure that at least your administrator email is set properly in the survey settings - otherwise no email will be sent or there will be an 'Invalid address:' message when a participant finishes a survey. Please note that there are three different ways for entering an address:<br />
##Enter a specific ''email address'' (ie: yourname@test.com)<br />
##Enter a ''SGQA code'' and the response will be sent to an email address entered as an answer to that particular question (use the format {INSERTANS:9999X88X12}, in the same way you would [[Adding a question#Information from previous answers|Re-use information from previous answers]])<br />
##Enter a ''Token code'' (only possible if your survey is ''not'' anonymous) and the response will be sent to an email address retrieved from a token field (use the format {TOKEN:EMAIL} or {TOKEN:ATTRIBUTE_1} in the same way you would [[Adding a question#Information from tokens table|Re-use Information from the Tokens Table]])<br />
##''As of Version 1.92:'' Enter a valid expression conforming to [[Expression Manager|Expression Manager]] syntax. This lets you use question code instead of SGQA syntax (for easier readability), plus conditional logic (e.g. route the notifications to different people depending upon the data entered into the survey).<br />
#'''Date stamp?''': This field allows you to determine whether the survey will datestamp all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response indicating the time and date that the response was made. (See configuration settings for $timeadjust setting.)<br />
#'''Save IP address?''': This field allows you to determine whether the survey will save an IP-address for all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response indicating the ip-address of the participant.<br />
#'''Save referrer URL?''': This field allows you to determine whether the survey will save the referrer URL for all responses. If you choose "Yes", then when a response is submitted, a field will be included in that response where this URL is saved. A referrer URL is the URL from which the user was led to your survey URL.<br />
#'''Enable assessment mode?''': With this setting you can enable/disable [[Assessments|assessments]] for this survey.<br />
#'''Save timings''': If activate then on survey activation a separate table will be created where timings for your questions will be saved, e.g. how long a user stays on one page during taking the survey.<br />
#'''Participant may save and resume later?''': This setting allows a participant to save his responses and resume to answer the survey at a later time. Please note that this makes most sense with open surveys or surveys with anonymized answer. If you are using tokens and the survey is not anonymous in most cases it is better to activate 'Token-based response persistence' in the token tab.<br />
#'''Google Analytics API Key for this survey''': Allows for integration with Google Analytics. The API key can be inserted into templates using {GOOGLE_ANALYTICS_API_KEY}. The full JavaScript that Google Analytics expects (including the key) can be included in templates via {GOOGLE_ANALYTICS_JAVASCRIPT}<br />
#'''Google Analytics Style for this Survey''': Choices are:<br />
##'''Do not use Google Analytics''' - so {GOOGLE_ANALYTICS_JAVASCRIPT} is an empty string<br />
##'''Default Google Analytics''' - {GOOGLE_ANALYTICS_JAVASCRIPT} uses the standard Google Analytics code, inserting the proper Google Analytics Key<br />
##'''SurveyName-<nowiki>[</nowiki>SID]/GroupName''' - {GOOGLE_ANALYTICS_JAVASCRIPT} contains customized Google Analytics code to log the URL as {SURVEYNAME}-<nowiki>[</nowiki>{SID}]/{GROUPNAME}. This can be helpful if you want to analyze navigation paths through your survey, time spent per page, and drop-off rates per page.<br />
<br />
<!--T:12--><br />
'''Google API howto''':<br />
# Register/login on Google Analytics (GA): [http://www.google.com/analytics/ www.google.com/analytics/]<br />
# Create a key (the site should not point to the survey, but to the part before 'index.php?') The key should be UA-xxxxx.<br />
# Go to your survey's global settings in LimeSurvey.<br />
# Put the key in appropriate field (Google Analytics API Key). It's probably the best to set GA Style to track all pages as you can have more info.<br />
# You don't need to do anything in shipped templates, as the {GOOGLE_ANALYTICS_JAVASCRIPT} part is already there.<br />
# Activate the survey.<br />
# Do the survey.<br />
# Go to GA panel mainsite. (select appropriate account in left-hand upper corner if you have more than one). You should see some graphs with the statistics. Beware of the dates in upper right corner.<br />
<br />
==Tokens== <!--T:13--><br />
#'''Anonymized responses?''': This allows you to determine whether responses to your survey are matched up with information from your surveys tokens table, or kept 'anonymous'. The default is 'No'. If you choose 'Yes' then your survey is set to radically anonymize responses - there is really no way to connect answers and participants. Even the admin can't link response data and participant/token data. However you will always be able to specifically view each response entered by your participants in the survey. Thus individual, but anonymous, statistics is still possible to do. '''''Attention:''''': If this feature is activated the response submission date and the token completed date are always set to 1980-01-01 00:00, no matter of other settings. Why? Invalidating the submission date ensures no match with webserver logs where the token key might show up when a survey is started. Invalidating the token completed date makes sure that you can't align the order of submitted responses to the order of the token date/time.<br />
#'''Allow multiple responses or update responses with one token?''': Default: No If you activate this setting the participants may return to his survey by clicking the invitation link, even if he already submitted the survey. If survey is anonymous, this add a new responses. If survey is not anonymous, user update existing responses.<br />
#'''Enable token-based response persistence''': If your survey uses tokens and your responses are not anonymized, then you may want to enable this feature. If you turn this on, then your participants can leave your survey and resume later at any time without using the 'Resume later' function - for example if he/she gets distracted or his browser crashes. Upon clicking the invitation link again he will find his survey answers so far still in place when returns to the survey and will even continue on the last page seen.<br />
#'''Allow public registration''': If you use tokens to control access to your survey, the only people who can use the survey are those who have an entry and a unique token from the token table. If you would like to use tokens, but also allow public registration, set this to "Yes". The "Yes" setting will allow a visitor to register his name and email address. The script will create a new entry in your tokens table for this person, then send them an invitation email. The script will ensure that only one person per email address can complete your survey.<br />
#'''Use HTML format for token emails?''': When set to yes, all emails sent by the token management interface (invite, reminder, confirmation) will be formatted as HTML. You'll then be able to use rich formatting for this emails. Default is Yes at survey creation. Caution, when you switch on/off this feature, you'll have to double check that your email templates are still displayed as you want.<br />
#'''Set token length to''': Usually you don't need to change this, the default setting of 15 digits (max. supported value: 99) is fine. If changing this setting please enter a number (X) which should be greater than 5 (if the number entered is <5 it will be converted to the default value of 15). When generating tokens all tokens will use a length of X digits.<br />
<br />
==Import== <!--T:14--><br />
<br />
<!--T:15--><br />
Alternatively you can [[Importing a survey structure|import a survey structure]] from this tab on survey creation. You have the option to let LimeSurvey automatically convert relative URLs to local images/media files and INSERTANS tags (recommended).<br />
<br />
==Copy== <!--T:16--><br />
<br />
<!--T:17--><br />
Alternatively you can copy an existing survey from this tab on survey creation. You have the option to let LimeSurvey automatically convert relative URLs to local images/media files and INSERTANS tags (recommended). The other options are pretty self-explaining. Please note that when copying a survey the start date and the end date of a survey cleared.<br />
<br />
==Panel integration (URL parameters)== <!--T:18--><br />
<br />
<!--T:19--><br />
<div class="simplebox"> Please note that this tab is currently not visible on survey creation but only when you edit the survey settings after saving them for the first time.</div><br />
<br />
<!--T:20--><br />
On this tab you can set which additional URL parameters will be accepted by your survey. If you like you can also save the value as a response of a "Short text question" or "Multiple short text question" type (you will be able to select any short text question to save it to). Even if you do NOT save the value of the URL parameter you will be able to use this parameter in the end URL. Please have a look at the documentation of the End-URL for further information.<br />
<br />
==Resources== <!--T:21--><br />
<br />
<!--T:22--><br />
This tab lets you manage files (pictures, media files) that were uploaded in the HTML Editor and it is only visible if you edit a survey - not during survey creation.<br />
<br />
<!--T:23--><br />
You can:<br />
* Browse available files<br />
* Export files as a ZIP archive<br />
* Import a ZIP archive of files<br />
<br />
<!--T:24--><br />
Important hints:<br />
* Authorized files extensions are defined in config-defaults.php.<br />
* Files for the survey are in the upload/surveys/<sid> subdirectory.<br />
* Uploaded files will only been seen while browsing resources on this survey (groups, questions, answers) not in other surveys or objects (labels).<br />
* Do not expect this limited visibility to ensure confidentiality of the resources as they are reachable with a simple browser to anyone who know the URL to the file.<br />
* You can't import a ZIP file containing subdirectories.<br />
<br />
=2nd Step - Additional languages= <!--T:25--><br />
<br />
<!--T:26--><br />
To add more language to a survey you have to create and save it - then edit it again. Now you can add and remove additional languages to the survey. If you remove a language from a survey the complete contents of that language in that survey is deleted permanently so be careful what you are doing.<br />
<br />
<!--T:27--><br />
By clicking on the button 'Save and continue' on the first page in the survey settings you will be taken to the language-specific page which lets you change all texts for each language like ''Survey name'', ''Welcome Text'', etc. You can also edit the date format which should be used for a certain language.<br />
<br />
<!--T:28--><br />
Previous [[Creating surveys - Introduction]]<br />
<br />
<!--T:29--><br />
Next [[Importing a survey structure]]<br />
<br />
</translate></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Coding_guidelines&diff=43745Coding guidelines2013-06-28T08:06:52Z<p>Sammousa: /* Localization */</p>
<hr />
<div><br />
Contents:__TOC__<br />
<br />
=General=<br />
<br />
'''This is a free development, everything you do can be useful for others. If the feature is very personal there is a way to turn it into a universal solution. This is the challenge!'''<br />
<br />
<div class="simplebox">"The difficulty within a solution is to solve it in a simple way"<br />
<br />
(Lance Burton, magician)</div><br />
<br />
Some general rules:<br />
*Be efficient and save resources (memory and runtime). Things might work for a small survey but also try out your new feature with a survey that has 400 question, 5 languages and 20,000 responses (Yes, there are surveys like this out there).<br />
*Keep a fluid dialog with the others coders, they have their own thoughts about what you are doing.<br />
*Ask if you are in doubt.<br />
<br />
=Naming convention=<br />
*Use the Hungarian Rule for variables:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
[t]NameOfVariable<br />
<br />
| <strike>-</strike><strike>+</strike>----<br />
<br />
| +--> Descriptive name<br />
<br />
+--> Datatype stored (for example start with "a" if it is an array)<br />
<br />
</syntaxhighlight><br />
<br />
Examples:<br />
<br />
aQuestionAttributes: Array to store the questions attributes, Mixed values<br />
<br />
dSurveyEnds: Date when the survey ends<br />
<br />
sContditionsOutput: String used to create the JS for conditions<br />
*In case a function is declared '''do not''' use the Hungarian rule for the function name, instead use "Lower CamelCase":<br />
<br />
function questionsRetrieve( $iQID, $iSurvey)<br />
*What about files? Unless Yii requires it in some way always name your files in lowercase - this prevents problems on systems using case-aware filesystems<br />
<br />
Here a list of prefixes:<br />
*o=Object<br />
*a=Array<br />
*i=Integer<br />
*f=Float<br />
*s=String<br />
<br />
=Documentation=<br />
<br />
Please refer to this introduction: [[How to document your source code]].<br />
<br />
=Structures=<br />
*Indent using spaces instead of TAB, or be gentle to announce how many spaces are your TABs long. There is wide ranging debate about tabs vs. spaces, many people prefer using tabs, others prefer spaces, others are happy with a mix of tabs and spaces. Because LimeSurvey is developed collaboratively, we ask that you leave your preference and follow this standard.<br />
*The opening curly brace must be below the structure opening:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
if (condition)<br />
<br />
{<br />
<br />
...<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
*Using one line for a simple condition is very "fashionable", a taste of "hacker", but it is not clear at all:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG: if (condition) {do true} else {do false}<br />
<br />
WRONG: if (condition) {do true}<br />
<br />
else {do false}<br />
<br />
RIGHT: if (condition)<br />
<br />
{<br />
<br />
do true<br />
<br />
} else<br />
<br />
{<br />
<br />
do false<br />
<br />
}<br />
<br />
RIGHT: swith $sSelector<br />
<br />
{<br />
<br />
case X:<br />
<br />
...<br />
<br />
break;<br />
<br />
case Y:<br />
<br />
...<br />
<br />
default:<br />
<br />
}<br />
<br />
</syntaxhighlight><br />
<br />
NOTE: It&acute;s true that sometimes the "WRONG" way can be useful, but if it makes the straight reading difficult, please use the "RIGHT" way instead. Be gentle with your fellow developers.<br />
*SQL sentences must respect the same rule:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
$sSQL = "SELECT field1, field2, field3 "<br />
<br />
."WHERE condition "<br />
<br />
."AND condition "<br />
<br />
."OR condition "<br />
<br />
."ORDER BY field1, field2";<br />
<br />
</syntaxhighlight><br />
*The same for HTML in views tags:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
<table><br />
<br />
<tr><br />
<br />
<td colspan='2'<br />
<br />
height='4'><br />
<br />
<strong><br />
<br />
Some Text<br />
<br />
</strong><br />
<br />
</td><br />
<br />
</tr><br />
<br />
</table><br />
<br />
</syntaxhighlight><br />
<br />
=HTML=<br />
*As you will notice, a very customized HTML element can take a lot of lines (very expensive if you paid each one (:wink:) ) to avoid that, use 'CSS classes'. In general, use classes to aesthetic related stuff: color, borders, backgrounds, font faces, sizes, etc.<br />
*Respect W3C standards, and try to use the HTML understandable for all browsers. If one of them has a special feature, think if this feature is so special to break down the HTML in other browsers.<br />
*Do not use PHP short tags <? ?>. Always use full PHP tags <?php ?><br />
*Any rules of the mentioned before: about CSS, well closed HTML tags and JS respect XHTML standards. Give it a try!.<br />
<br />
=Localization=<br />
<br />
Currently we are using the gT(),eT(),ngT() and neT() functions of the limesurvey_lang object for translations.<br />
<br />
Since LimeSurvey is available in 60 languages it is very important that your original English string (which will be picked up automatically for translation by our translators) is done right from the start. Imagine if we have to correct only one string at a later time - then 60 strings become invalid across the project and need to be re-translated by the poor translator souls.<br />
* gT() is the original translation function. It will return a translated version of the string in the currently selected language. ie: echo ''gT("Hello");''<br />
* ngT() returns multiple translations of a sentence or phrase for which alternate plural forms may apply. ie: ''echo sprintf(ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers)'';<br />
* eT() echos the translation directly. (ie: instead of ''echo gT("Hello");'' you can use ''eT("Hello");''<br />
* neT() echos the multiple translations of the sentence or phrase for which alternate plural forms may apply directly.<br />
<br />
Please follow these important rules:<br />
*'''Do not embed margin spaces''' in your translation. Instead use proper CSS formatting<br />
<br />
<span style='color:#F00'>Wrong</span>: eT('Visible? ');<br />
<br />
<span style='color:#060'>Right</span>: eT('Visible?');<br />
*'''Do not capitalize words''' except where grammatically correct (like at the beginning of a sentence or for a brand name). LimeSurvey is not a newspaper.<br />
<br />
<span style='color:#F00'>Wrong</span>: eT('Create A New Label Set');<br />
<br />
<span style='color:#060'>Right</span>: eT('Create a new label set');<br />
<br />
<span style='color:#F00'>Wrong</span>: eT('Google Maps API Key');<br />
<br />
<span style='color:#060'>Right</span>: eT('Google Maps API key');<br />
*'''Do not concatenate''' several translations to form a sentence or concatenate to an additional information (like a number or string). Instead use the sprint() or sprintf() function with placeholders.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The sum must not be bigger than').$iMaxSum;<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The sum must not be bigger than %s'),$iMaxSum);<br />
<br />
This comes from the problem that in other languages the setting of a sentence can be much different and the information $iMaxSum from the example above might be needed in the middle of the sentence.<br />
<br />
<span style='color:#F00'>Wrong</span>: echo $clang->gT('The user').$sUsername.$clang->gT('was deleted.');<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->gT('The user %s was deleted.'),$sUsername);<br />
*'''Use the n*T functions where applicable'''. These functions show a different translation depending the number of items. Currently LimeSurvey only supports the numbers/situations 1 and >1.<br />
<br />
+Example:<br />
<br />
<span style='color:#F00'>Wrong</span>: echo sprintf($clang->gT('Please select at least %s answer(s).'),$iMinimumAnswers);<br />
<br />
<span style='color:#060'>Right</span>: echo sprintf($clang->ngT('Please select at least %s answer','Please select at least %s answers',iMinimumAnswers),$iMinimumAnswers);<br />
<br />
=Bug tracker=<br />
#First consider if the reported issue is really a bug. If it is a feature request please point the reporter to http://ideas.limesurvey.org and set the issue status to 'Closed'.<br />
#If you would like to work on a bug assign it to yourself.<br />
#Try to reproduce the issue.<br />
##If you cannot reproduce ask the user to provide a small example survey to demonstrate the issue. Then set the issue to 'Feedback'. After the user added the necessary information it will automatically be set to 'Assigned' again.<br />
##If the user does not responds for more than a week ask once again for feedback by adding a comment. After a further week without feedback close the issue.<br />
#After you resolved the issue set the status to resolved AND provide the 'Fixed in version' information.<br />
#After you committed your fix add a comment to the resolved issue 'Fixed in rev. <Subversion revision number>'<br />
#After a release the release technician will set all issues to 'Closed' that were fixed for this release. That signals to the reporter that a fix is available in the version and it was just released.<br />
<br />
=Cross-DB compatibility=<br />
<br />
LimeSurvey targets several database types it can run on: MySQL, Postgres and Microsoft SQL Server. This demands certain precautions when coding<br />
<br />
==Parameter binding==<br />
<br />
Yii/PDO supports parameter binding - use it. Don't inject variables directly into the query or into conditions because this might create a security issue.<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('somefield')<br />
<br />
->where("sid = :sid")<br />
<br />
->from('{{sometable}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
If you bind the same value several times do NOT use the same parameter name, instead use a different named parameter for each bind:<br />
<br />
WRONG:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('somefield')<br />
<br />
->where("sid = :sid and parent_sid= :sid ")<br />
<br />
->from('{{sometable}}')<br />
<br />
->bindParam(":sid", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
RIGHT:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><?php<br />
<br />
$oResult = Yii::app()->db<br />
<br />
->createCommand()<br />
<br />
->select('somefield')<br />
<br />
->where("sid = :sid1 and parent_sid= :sid2 ")<br />
<br />
->from('{{sometable}}')<br />
<br />
->bindParam(":sid1", $surveyid, PDO::PARAM_INT)<br />
<br />
->bindParam(":sid2", $surveyid, PDO::PARAM_INT);<br />
<br />
?></syntaxhighlight><br />
<br />
=Miscellaneous=<br />
*Do not use "global" to access to a declared variable in another process. Pass variables or arrays by reference, use the session or the configuration object.<br />
*If using an auxiliary variable makes clear the code or process, just do it. If you are coding a very complex expression, calling to functions with parameters that are other functions:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
WRONG:<br />
<br />
iAResult= fa(fb(p1,p2),fc(fd(p3),p4),p5)<br />
<br />
It will be more readable:<br />
<br />
iAuxB = fb(p1,p2)<br />
<br />
iAuxD = fd(p3)<br />
<br />
iAuxC = fc(iAuxD,p4)<br />
<br />
iAResult = fa(iAuxB, iAuxC, p5)<br />
<br />
</syntaxhighlight><br />
<br />
Anyway, if you are in doubt about someone missing the point or you are afraid that your expression is obscure, take the chance of writing it in a more simple way, even if that involves the use of one or more auxiliary variables.<br />
<br />
[[Category:Development]]</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Plugins_-_advanced&diff=2416Plugins - advanced2013-03-05T10:31:38Z<p>Sammousa: </p>
<hr />
<div><br />
Starting from Limesurvey 2.05, Limesurvey will officially support plugins.<br />
<br />
Plugins allow users to customize the functionality of their installation while still being able to benefit from regular software updates.<br />
<br />
This documentation is meant for developers that are extending Limesurvey for their own use or for their clients; end users will not be helped by this documentation.<br />
<br />
Plugins must implement the [https://github.com/LimeSurvey/LimeSurvey/blob/2.05/application/libraries/PluginManager/iPlugin.php iPlugin] interface. We recommend<br />
<br />
extending your plugin class from the [https://github.com/LimeSurvey/LimeSurvey/blob/2.05/application/libraries/PluginManager/PluginBase.php PluginBase] class.<br />
<br />
By extending you benefit from common functionality required by plugins that we already have implemented for you. One of these function is the implementation of the getPluginSettings function. This function must return an array describing the configuration options for the user.<br />
<br />
The example plugin exposes just 1 configurable setting, the message it'll show.<br />
<br />
<syntaxhighlight lang="php" enclose="div">protected $settings = array(<br />
<br />
'logo' => array(<br />
<br />
'type' => 'logo',<br />
<br />
'path' => 'assets/logo.png'<br />
<br />
),<br />
<br />
'message' => array(<br />
<br />
'type' => 'string',<br />
<br />
'label' => 'Message'<br />
<br />
)<br />
<br />
);</syntaxhighlight><br />
<br />
The array contains a name for each setting as a key. The values are arrays containing the required meta data.<br />
<br />
Supported types are:<br />
<br />
- logo<br />
<br />
- string<br />
<br />
- html<br />
<br />
- choice<br />
<br />
- relevance<br />
<br />
Besides type a number of other keys are available:<br />
<br />
- label, defines a label (use English, the label specified here will be passed through the translation functions)<br />
<br />
- default, defines a value to show if no value is specified.<br />
<br />
- current, defines the current value.<br />
<br />
- readOnly, specifies the setting is read only.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_signature&diff=2546Question signature2013-02-25T22:25:17Z<p>Sammousa: </p>
<hr />
<div><br />
=Question signature=<br />
<br />
Since question types can no longer be uniquely identified their object names, we have created a signature scheme.<br />
<br />
While in a single limesurvey instance question objects must be uniquely named, there might be different plugins defining the question objects with the same name.<br />
<br />
To make sure we can identify what the type of a question is, we derive a unique identifier (GUID) from a signature.<br />
<br />
Each question object MUST therefore define a protected static $signature field. This field is used to derive the signature using a hashing approach.<br />
<br />
It is the developers task to make this signature as unique as possible, yet, it MUST never change. If the signature of a question object changes it is recognized as a new question type, while this is not necessarily a problem, the fact that the old question type is no longer available is. Since Limesurvey cannot find the old question type it will not be able to execute, import, or maybe even edit, surveys containing this now unknown question type.<br />
<br />
An example of a signature is shown below:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
protected static $signature = array(<br />
<br />
'orignalAuthor' => 'Sam Mousa',<br />
<br />
'originalName' => 'Yes / No',<br />
<br />
'startDev' => '2013-30-1'<br />
<br />
);<br />
<br />
</syntaxhighlight><br />
<br />
Note that you are free to use any format / data type you want. The GUID is derived using the following code:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
/**<br />
* This function derives a unique identifier for identifying a question type.<br />
*/<br />
<br />
public static function getGUID()<br />
<br />
{<br />
<br />
// We use json_encode because it is faster than serialize.<br />
<br />
return md5(json_encode(static::$signature));<br />
<br />
}<br />
<br />
</syntaxhighlight></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_plugins&diff=2541Question plugins2013-02-25T22:16:45Z<p>Sammousa: </p>
<hr />
<div><br />
Question object considerations.<br />
<br />
Questions are plugins.<br />
<br />
- No difference between core and thirdparty questions<br />
<br />
- Questions can include views.<br />
<br />
- MM: All question related texts can make use of placeholders (EM).<br />
<br />
Questions can have database columns.<br />
<br />
- A question may define a column type for storing its answer.<br />
<br />
Questions may have subquestions.<br />
<br />
- A question may have subquestions; these are Question objects, possible of another type.<br />
<br />
- Questions are rendered recursively; a parent question is responsible for telling its children when to render.<br />
<br />
- Answercolumns are discovered recursively; a parent question is responsible for getting column meta data (upon survey activation) from its children.<br />
<br />
Questions may have AnswerSets.<br />
<br />
- Multiple questions may share the same AnswerSet.<br />
<br />
- An answer set is a numerically indexed array; assigning each text option an numeric value.<br />
<br />
- Texts inside answer sets can be localized.<br />
<br />
Questions belong to 1 Category.<br />
<br />
interface iQuestionPlugin {<br />
<br />
public</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Defining_attributes&diff=4304Defining attributes2013-02-25T22:15:20Z<p>Sammousa: </p>
<hr />
<div><br />
=Defining attributes for question types.=<br />
<br />
Attributes for question types are all configurable, non default, aspects of a question. A good example of an attribute is question text.<br />
<br />
Question attributes are defined using an array with the name of the attribute as a key. An attribute definition supports several keys.<br />
*type - string: The data type of the attribute. Supported types are ('html', 'string', 'boolean', 'select')<br />
*localized - boolean: Whether this attribute should be configurable per language.<br />
*advanced - boolean: Whether this attribute should be shown in the default or advanced tab.<br />
*label - string: The label of the attribute in English (this is localized by the admin interface).<br />
*options - array(string-string): Contains the options for an attribute of type 'select'.<br />
*default - mixed: Contains the default value for the attribute.<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
protected $attributes = array(<br />
<br />
'question' => array(<br />
<br />
'type' => 'html',<br />
<br />
'localized' => true,<br />
<br />
'label' => 'Question text:'<br />
<br />
),<br />
<br />
'help' => array(<br />
<br />
'type' => 'html',<br />
<br />
'localized' => true,<br />
<br />
'label' => 'Help text:'<br />
<br />
),<br />
<br />
'mandatory' => array(<br />
<br />
'type' => 'boolean',<br />
<br />
'label' => 'Mandatory:'<br />
<br />
),<br />
<br />
'display' => array(<br />
<br />
'label' => 'Display using:',<br />
<br />
'type' => 'select',<br />
<br />
'options' => array(<br />
<br />
'radio' => 'Radio buttons',<br />
<br />
'dropdown' => 'Dropdown list'<br />
<br />
),<br />
<br />
'localized' => false,<br />
<br />
'advanced' => false,<br />
<br />
'default' => 'dropdown'<br />
<br />
)<br />
<br />
);<br />
<br />
</syntaxhighlight></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Defining_attributes&diff=4305Defining attributes2013-02-25T22:12:30Z<p>Sammousa: </p>
<hr />
<div><br />
=Defining attributes for question types.=<br />
<br />
Attributes for question types are all configurable, non default, aspects of a question. A good example of an attribute is question text.<br />
<br />
Question attributes are defined using an array with the name of the attribute as a key. An attribute definition supports several keys.<br />
*type - string: The data type of the attribute. Supported types are ('html', 'string', 'boolean', 'select')<br />
*localized - boolean: Whether this attribute should be configurable per language.<br />
*advanced - boolean: Whether this attribute should be shown in the default or advanced tab.<br />
*label - string: The label of the attribute in English (this is localized by the admin interface).<br />
*options - array(string-string): Contains the options for an attribute of type 'select'.<br />
*default - mixed: Contains the default value for the attribute.<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div"><br />
<br />
protected $attributes = array(<br />
<br />
'question' => array(<br />
<br />
'type' => 'html',<br />
<br />
'localized' => true,<br />
<br />
'label' => 'Question text:'<br />
<br />
),<br />
<br />
'help' => array(<br />
<br />
'type' => 'html',<br />
<br />
'localized' => true,<br />
<br />
'label' => 'Help text:'<br />
<br />
),<br />
<br />
'mandatory' => array(<br />
<br />
'type' => 'boolean',<br />
<br />
'label' => 'Mandatory:'<br />
<br />
),<br />
<br />
'display' => array(<br />
<br />
'label' => 'Display using:',<br />
<br />
'type' => 'select',<br />
<br />
'options' => array(<br />
<br />
'radio' => 'Radio buttons',<br />
<br />
'dropdown' => 'Dropdown list'<br />
<br />
),<br />
<br />
'localized' => false,<br />
<br />
'advanced' => false,<br />
<br />
'default' => 'dropdown'<br />
<br />
)<br />
<br />
);<br />
<br />
</syntaxhighlight></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Defining_attributes&diff=4306Defining attributes2013-02-25T22:11:48Z<p>Sammousa: </p>
<hr />
<div><br />
=Defining attributes for question types.=<br />
<br />
Attributes for question types are all configurable, non default, aspects of a question. A good example of an attribute is question text.<br />
<br />
Question attributes are defined using an array with the name of the attribute as a key. An attribute definition supports several keys.<br />
*type - string: The data type of the attribute. Supported types are ('html', 'string', 'boolean', 'select')<br />
*localized - boolean: Whether this attribute should be configurable per language.<br />
*advanced - boolean: Whether this attribute should be shown in the default or advanced tab.<br />
*label - string: The label of the attribute in English (this is localized by the admin interface).<br />
*options - array(string-string): Contains the options for an attribute of type 'select'.<br />
*default - mixed: Contains the default value for the attribute.<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="php" enclose="div">protected $attributes = array(<br />
<br />
'question' => array(<br />
<br />
'type' => 'html',<br />
<br />
'localized' => true,<br />
<br />
'label' => 'Question text:'<br />
<br />
),<br />
<br />
'help' => array(<br />
<br />
'type' => 'html',<br />
<br />
'localized' => true,<br />
<br />
'label' => 'Help text:'<br />
<br />
),<br />
<br />
'mandatory' => array(<br />
<br />
'type' => 'boolean',<br />
<br />
'label' => 'Mandatory:'<br />
<br />
),<br />
<br />
'display' => array(<br />
<br />
'label' => 'Display using:',<br />
<br />
'type' => 'select',<br />
<br />
'options' => array(<br />
<br />
'radio' => 'Radio buttons',<br />
<br />
'dropdown' => 'Dropdown list'<br />
<br />
),<br />
<br />
'localized' => false,<br />
<br />
'advanced' => false,<br />
<br />
'default' => 'dropdown'<br />
<br />
)<br />
<br />
);</syntaxhighlight></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_Objects&diff=2536Question Objects2013-02-25T21:40:16Z<p>Sammousa: </p>
<hr />
<div><br />
=DEPRECATED DEPRECATED DEPRECATED DEPRECATED=<br />
<br />
As of LimeSurvey 2.0, questions type were internally identified by a single character. That is, a display question was represented by 'X' while a list question was represented by 'L' etc. Unfortunately, this made adding and altering question types incredibly difficult since code for each question type was spread across literally dozens of files. To make it easier for independent developers to add and modify question types, each question will have it's own class in the application/modules folder. These classes will contain all question-type-specific code.<br />
<br />
There are 3 abstract question classes: QuestionModule, ArrayQuestion, and TextQuestion. All the question classes (including Array and Text) extend QuestionModule and end in "Question." Below is a list of class names and descriptions.<br />
<br />
{|<br />
|Description||Class Prefix||Legacy Character Code||Parent (if blank assume QuestionModule)<br />
|-<br />
|5 point choice||FiveList||5||<br />
|-<br />
|List (dropdown)||Select||!||List<br />
|-<br />
|List (radio)||List||L||<br />
|-<br />
|List with comment||CommentList||O||List<br />
|-<br />
|Array||RadioArray||F||Array<br />
|-<br />
|Array (10 point choice)||TenRadioArray||B||RadioArray<br />
|-<br />
|Array (5 point choice)||FiveRadioArray||A||RadioArray<br />
|-<br />
|Array (Increase/Same/Decrease)||IDRadioArray||E||RadioArray<br />
|-<br />
|Array (Numbers)||NumberArray||:||Array<br />
|-<br />
|Array (Texts)||TextArray||;||Array<br />
|-<br />
|Array (Yes/No/Uncertain)||YNRadioArray||C||RadioArray<br />
|-<br />
|Array by column||ColumnRadioArray||H||RadioArray<br />
|-<br />
|Array dual scale||DualRadioArray||1||RadioArray<br />
|-<br />
|Date/Time||Date||D||<br />
|-<br />
|Equation||Equation||*||<br />
|-<br />
|File upload||File||pipe character||<br />
|-<br />
|Gender||Gender||G||<br />
|-<br />
|Language switch||Language||I||<br />
|-<br />
|Multiple numerical input||Multinumerical||K||<br />
|-<br />
|Numerical input||Numerical||N||<br />
|-<br />
|Ranking||Ranking||R||<br />
|-<br />
|Text display||Display||X||<br />
|-<br />
|Yes/No||YN||Y||<br />
|-<br />
|Huge free text||HugeText||U||Text<br />
|-<br />
|Long free text||LongText||T||Text<br />
|-<br />
|Multiple short text||Multitext||Q<br />
|-<br />
|Short free text||ShortText||S||Text<br />
|-<br />
|Multiple choice||Check||M||<br />
|-<br />
|Multiple choice with comments||CommentCheck||P||Check<br />
|}<br />
<br />
Each of these classes contains (or inherits) a number of public methods that are abstracted by the QuestionModule class. To execute this question specific code, the question class is loaded out of the database, the object is dynamically instantiated and the relevant function is called. The question objects store question id, group id, survey id, question text, and other relevant data. Question objects then become a very useful way to pass around data instead of the previously used arrays.<br />
<br />
These question objects come with two new database tables. First, a question types table stores a list of type ids, group ids, description, and legacy character code. There is a new int tid column in the questions table that replaces the type column and maps to the tid column in the new question types table. In addition, there is a new question type groups table that contains a group id, a description, and an order. This configuration will allow for backend configuration in the future, and ultimately, custom question types that can be shared among the community.<br />
<br />
One of the biggest advantages of switching from procedural code to object-oriented code is that it will both allow developers to easily create custom question types by extending any of the existing question types. In order to do this, a developer can either extend one of the predefined question types and override one or more of the methods (such as getAnswerHTML() which returns the HTML code that renders each question) or by extending the base QuestionModule class or one of the other abstract classes and implementing its abstract methods.<br />
<br />
{|<br />
|Abstract Method&dagger;||Functionality<br />
|-<br />
|getAnswerHTML||Returns the HTML for the question<br />
|-<br />
|getDataEntry||Returns the HTML for manually entering survey data from the backend<br />
|-<br />
|availableAttributes||Returns an array of attributes the question can have in the question_attributes table<br />
|-<br />
|questionProperties||Returns an array of question properties including description, group name, whether the class has subquestions, css class name, whether the class has default values, whether the class is assessable, and whether the class has answer scales<br />
|}<br />
<br />
&dagger;Once the porting of the question objects is completed, a table will be added with a complete list of methods both abstract and extendable.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Naming_conventions&diff=2234Naming conventions2013-01-18T21:18:41Z<p>Sammousa: </p>
<hr />
<div><br />
Having moved to a (partial) MVC architecture we should adopt some conventions for naming our models and controllers. I realize that functionally naming conventions don't have any benefit, however they do increase maintainability. Currently we don't have naming conventions (or I am unaware of them AND they have not been consistently obeyed in the current code base).<br />
<br />
The folks at cakephp (http://book.cakephp.org/2.0/en/getting-started/cakephp-conventions.html#model-and-database-conventions) came up with some nice naming conventions.<br />
<br />
I suggest we use these for new concepts we introduce to our architecture.<br />
<br />
In short:<br />
<br />
- Models are singular: Plugin not Plugins.<br />
<br />
- Database tables backing the model are plural, lowercase: plugins, not plugin or Plugins.<br />
<br />
- Controllers are plural if they are "directly" backed by a model: PluginsController, not PluginController.<br />
<br />
- Controllers are singular if they are not backed by a model: AdministrationController (which we shortened to AdminController)<br />
<br />
- Controllers backed by a main model handle most stuff related to that model. This modularization makes it easy to find the code we are interested in when bugs need fixing.<br />
<br />
Table field names:<br />
<br />
- Table field names are all lowercase.<br />
<br />
- Each table has a primary key named id [[Do we want this for join tables??]]<br />
<br />
- Each table has either a name or title field, whichever is more appropriate for the model in question. The name / title field should be used for easy identification of a model isntance.<br />
<br />
- Foreign keys are named after their model postfixed with _id; so model PluginSetting belongsTo Plugin results in a plugin_id field in the pluginsettings table.<br />
<br />
- Join tables (for many2many relations) are either named after the concept they implement, or by concatening the participating models in alphabetical order separated by underscores. For example: user HABTM groups could be stored either in a table called memberships, which would then introduce a model Membership with relations User hasMany Membership and Group hasMany Membership, or alternatively in a table called groups_users.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Naming_conventions&diff=2235Naming conventions2013-01-18T21:10:43Z<p>Sammousa: </p>
<hr />
<div><br />
Having moved to a (partial) MVC architecture we should adopt some conventions for naming our models and controllers.<br />
<br />
The folks at cakephp (http://book.cakephp.org/2.0/en/getting-started/cakephp-conventions.html#model-and-database-conventions) came up with some nice naming conventions.<br />
<br />
I suggest we use these for new concepts we introduce to our architecture.<br />
<br />
In short:<br />
<br />
- Models are singular: Plugin not Plugins.<br />
<br />
- Database tables backing the model are plural, lowercase: plugins, not plugin or Plugins.<br />
<br />
- Controllers are plural if they are "directly" backed by a model: PluginsController, not PluginController.<br />
<br />
- Controllers are singular if they are not backed by a model: AdministrationController (which we shortened to AdminController)<br />
<br />
- Controllers backed by a main model handle most stuff related to that model. This modularization makes it easy to find the code we are interested in when bugs need fixing.<br />
<br />
I realize that functionally naming conventions don't have any benefit, however they do increase maintainability. Currently we don't have naming conventions (or I am unaware of them AND they have not been consistently obeyed in the current code base).</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_plugins&diff=2543Question plugins2013-01-18T09:08:27Z<p>Sammousa: </p>
<hr />
<div><br />
Question object considerations.<br />
<br />
Questions are plugins.<br />
<br />
- No difference between core and thirdparty questions<br />
<br />
- Questions can include views.<br />
<br />
Questions can have database columns.<br />
<br />
- A question may define a column type for storing its answer.<br />
<br />
Questions may have subquestions.<br />
<br />
- A question may have subquestions; these are Question objects, possible of another type.<br />
<br />
- Questions are rendered recursively; a parent question is responsible for telling its children when to render.<br />
<br />
- Answercolumns are discovered recursively; a parent question is responsible for getting column meta data (upon survey activation) from its children.<br />
<br />
Questions may have AnswerSets.<br />
<br />
- Multiple questions may share the same AnswerSet.<br />
<br />
- An answer set is a numerically indexed array; assigning each text option an numeric value.<br />
<br />
- Texts inside answer sets can be localized.<br />
<br />
Questions belong to 1 Category.<br />
<br />
interface iQuestionPlugin {<br />
<br />
public</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Plugin_system_architecture&diff=2415Plugin system architecture2013-01-08T10:27:07Z<p>Sammousa: </p>
<hr />
<div><br />
Some random stuff on plugin architecture.<br />
<br />
The plugins will extend a base class.<br />
<br />
The base plugin class will initialize a storage interface and create wrapper functions for the get and set implemented in the interface.<br />
<br />
Code below might contain mistakes, textarea doesnt have syntax checking :p<br />
<br />
<syntaxhighlight lang="php" enclose="div">interface PluginStorage {<br />
<br />
/**<br />
<br />
Returns plugin data.<br />
<br />
@param object $plugin The plugin object getting its data.<br />
<br />
@param string | null $key The storage key, if null will return all data for the plugin.<br />
<br />
@param string $model Name of a model in case its model specific plugin data, like for a specific question or survey.<br />
<br />
@param int $id Id of the model for which the data is retreived<br />
<br />
@return mixed The data stored.<br />
*/<br />
<br />
public function get($plugin, $key = null, $model = null, $id = null);<br />
<br />
/**<br />
<br />
Stores plugin data.<br />
<br />
@param object $plugin The plugin object getting its data.<br />
<br />
@param string $key The storage key to identify the data.<br />
<br />
@param mixed $data The data to be stored, serialized using serialize.<br />
<br />
@param string $model Name of a model in case its model specific plugin data, like for a specific question or survey.<br />
<br />
@param int $id Id of the model for which the data is retreived<br />
*/<br />
<br />
public function set ($plugin, $key, $data, $model = null, $id = null);<br />
<br />
}<br />
<br />
class PluginBase {<br />
<br />
protected $storage = 'PluginStorage';<br />
<br />
private $store = null;<br />
<br />
public function '''construct()<br />
<br />
{<br />
<br />
$this->store = Plugin::getStore($this->storage);<br />
<br />
}<br />
<br />
/**<br />
<br />
This function stores plugin data.<br />
<br />
*/<br />
<br />
protected function set($key, $data, $model = null, $id = null)<br />
<br />
{<br />
<br />
if (isset($this->store))<br />
<br />
{<br />
<br />
return $this->store->set($this, $key, $model, $id);<br />
<br />
}<br />
<br />
return false;<br />
<br />
}<br />
<br />
/**<br />
<br />
This function retrieves plugin data. Do not cache this data; the plugin storage<br />
<br />
engine will handling caching. After the first call to this function, subsequent<br />
<br />
calls will only consist of a few function calls and array lookups.<br />
<br />
*/<br />
<br />
protected function get($key = null, $model = null, $id = null)<br />
<br />
{<br />
<br />
if (isset($this->store))<br />
<br />
{<br />
<br />
return $this->store->get($this, $key, $model, $id);<br />
<br />
}<br />
<br />
return false;<br />
<br />
}<br />
<br />
}</syntaxhighlight></div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Email_templates&diff=4361Email templates2012-12-20T11:39:25Z<p>Sammousa: </p>
<hr />
<div><br />
To edit the email templates select the according entry from the survey menu:<br />
<br />
[[File:emailtemplates.png]]<br />
<br />
=Email attachment feature.=<br />
<br />
From 2.1 forwards, LimeSurvey will officially support adding file attachments to emails sent by the system.<br />
<br />
The following templates support adding attachments:<br />
*invitation<br />
*reminder<br />
*admin notification<br />
*detailed admin notification<br />
*confirmation<br />
<br />
Attachments can be added at the bottom of the email template editing interface. Email attachments are uploaded on a per survey basis.<br />
<br />
To decide if an attachment should be sent on an individual basis it is possible to add a relevance equation to each attachment.<br />
<br />
All functions supported by the [[Expression Manager|Expression Manager]] can be used, as well as token attributes if the survey uses tokens.<br />
<br />
In case of a notification or confirmation template it is also possible to use [http://docs.limesurvey.org/Expression+Manager#Access_to_Variables question codes] used in the survey.<br />
<br />
==Things to watch out for==<br />
*When a '''file can not be found''' on the file system, the email will be '''sent without attachment'''.<br />
*'''Exporting / importing''' a survey does not export the uploaded files. The settings for attachments will be maintained, as will the relevance equations.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Email_templates&diff=4364Email templates2012-12-19T13:16:24Z<p>Sammousa: </p>
<hr />
<div><br />
=Email attachment feature.=<br />
<br />
From 2.1 forwards, LimeSurvey will officially support adding file attachments to emails sent by the system.<br />
<br />
The following templates support adding attachments: invitation, reminder, admin notification, detailed admin notification and confirmation.<br />
<br />
Attachments can be added in the email template editing interface. Email attachments are uploaded on a per survey basis.<br />
<br />
To decide if an attachment should be sent on an individual basis it is possible to add a relevance equation to each attachment.<br />
<br />
All functions supported by the Expression Manager can be used, as well as token attributes if the survey uses tokens.<br />
<br />
In case of a notification or confirmation template it is also possible to use question codes used in the survey.<br />
<br />
'''Note 1''': When a file can not be found on the file system, the email will be send without attachment.<br />
<br />
'''Note 2''': Exporting / importing a survey does not export the uploaded files. The settings for attachments will be maintained, as will the relevance equations.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Controllers&diff=3210Controllers2012-08-14T12:01:46Z<p>Sammousa: </p>
<hr />
<div><br />
This is a proposal for (re)organizing the controller structure for LS2.1<br />
<br />
Currently we have very few but fat controllers. It is desirable to have skinny controllers for easier maintenance.<br />
<br />
Several main tasks can be identified within LS.<br />
<br />
- Survey taking<br />
<br />
- Survey creation<br />
<br />
- Token management<br />
<br />
Since survey taking is what LS is all about we should try to decrease the complexity of this process.<br />
<br />
A survey hasMany groups and a group hasMany questions. For taking a survey (which is creating a survey entry) four controllers should be used.<br />
<br />
SurveyController<br />
<br />
- Actions for creating and editing a survey.<br />
<br />
GroupController<br />
<br />
- Actions for creating and editing a group.<br />
<br />
QuestionController<br />
<br />
- Actions for creating and editing a question.<br />
<br />
EntryController<br />
<br />
- Responsible for managing the creation of new entries for surveys.<br />
<br />
Example process for a 1-question-at-a-time survey:<br />
<br />
/entry/create?sid=12345<br />
<br />
- Initialize session.<br />
<br />
- Store survey ID in session.<br />
<br />
- Redirect to /survey/welcome<br />
<br />
/survey/welcome<br />
<br />
- If applicable show welcome screen.<br />
<br />
- Store group ID in session.<br />
<br />
- Redirect to /group/welcome<br />
<br />
/group/welcome<br />
<br />
- Show welcome screen for group.<br />
<br />
- Store question ID in session.<br />
<br />
- Redirect to /question/render<br />
<br />
/question/render<br />
<br />
- Show question, form action = /entry/addanswer<br />
<br />
/entry/addanswer<br />
<br />
- Store the result for the current answered question.<br />
<br />
- Use answer to find next question / group & store ID.<br />
<br />
- Redirect appropriately.<br />
<br />
And so on... This does not cause a lot of extra redirects since redirecting after a HTTP POST is standard procedure, we just change the POST ACTION.<br />
<br />
This approach allows us to divide large complex controller(s) into smaller and easier to manage pieces.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Controllers&diff=3211Controllers2012-08-14T10:28:16Z<p>Sammousa: </p>
<hr />
<div><br />
This is a proposal for (re)organizing the controller structure for LS2.1<br />
<br />
Currently we have very few but fat controllers. It is desirable to have skinny controllers for easier maintenance.<br />
<br />
Several main tasks can be identified within LS.<br />
<br />
- Survey taking<br />
<br />
- Survey creation<br />
<br />
- Token management<br />
<br />
Since survey taking is what LS is all about we should try to decrease the complexity of this process.<br />
<br />
A survey hasMany groups and a group hasMany questions. For taking a survey (which is creating a survey entry) four controllers should be used.<br />
<br />
SurveyController<br />
<br />
- Actions for creating and editing a survey.<br />
<br />
GroupController<br />
<br />
- Actions for creating and editing a group.<br />
<br />
QuestionController<br />
<br />
- Actions for creating and editing a question.<br />
<br />
EntryController<br />
<br />
- Responsible for managing the creation of new entries for surveys.<br />
<br />
Example process:<br />
<br />
- EntryController-> create entry for survey 1<br />
<br />
- Redirect to SurveyController -> welcome screen (which has a post button that goes to entrycontroller)<br />
<br />
- Redirect to GroupController -> welcome screen<br />
<br />
And so on... This does not cause a lot of extra redirects since redirecting after a HTTP POST is standard procedure, we just change the POST ACTION.<br />
<br />
This approach allows us to divide large complex controller(s) into smaller and easier to manage pieces.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Directory_structure&diff=4326Directory structure2012-08-14T10:10:32Z<p>Sammousa: </p>
<hr />
<div><br />
This page should explain the directory hierarchy for the Yii branch.<br />
<br />
Root<br />
* application -- Contains the Yii limesurvey application, back-end stuff should mostly be in here.<br />
** config -- Contains the configuration for the framework and Limesurvey.<br />
** controllers -- Contains the controllers from the MVC paradigm.<br />
** core<br />
** errors<br />
** helpers<br />
** hooks<br />
** language<br />
** libraries<br />
** logs<br />
** models<br />
** tests<br />
** third_party -- Contains third party libraries that are used by the backend and do not have to be available directly from a browser.<br />
** views<br />
* docs<br />
* fonts<br />
* framework -- The Yii framework. This directory should not be changed unless you are updating Yii.<br />
* images<br />
* installer -- Contains files for initial installation and upgrading.<br />
* locale<br />
* scripts -- Contains javascript files.<br />
* styles-public -- Contains css files (difference with normal styles dir?)<br />
* styles -- Contains css files<br />
* templates<br />
* third-party -- This contains (scripting) libraries that must be available directly via the browser. For example jquery. Only place original libraries here, put configuration in the scripts dir. Create a subdirectory for each library, but don't include the version number in the directory; this allows for easy upgrading.<br />
* tmp<br />
* upload</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Question_Objects&diff=2537Question Objects2012-08-12T23:44:12Z<p>Sammousa: </p>
<hr />
<div><br />
As of LimeSurvey 2.0, questions type were internally identified by a single character. That is, a display question was represented by 'X' while a list question was represented by 'L' etc. Unfortunately, this made adding and altering question types incredibly difficult since code for each question type was spread across literally dozens of files. To make it easier for independent developers to add and modify question types, each question will have it's own class in the application/modules folder. These classes will contain all question-type-specific code.<br />
<br />
There are 3 abstract question classes: QuestionModule, ArrayQuestion, and TextQuestion. All the question classes (including Array and Text) extend QuestionModule and end in "Question." Below is a list of class names and descriptions.<br />
<br />
{|<br />
|Description||Class Prefix||Legacy Character Code||Parent (if blank assume QuestionModule)<br />
|-<br />
|5 point choice||FiveList||5||<br />
|-<br />
|List (dropdown)||Select||!||List<br />
|-<br />
|List (radio)||List||L||<br />
|-<br />
|List with comment||CommentList||O||List<br />
|-<br />
|Array||RadioArray||F||Array<br />
|-<br />
|Array (10 point choice)||TenRadioArray||B||RadioArray<br />
|-<br />
|Array (5 point choice)||FiveRadioArray||A||RadioArray<br />
|-<br />
|Array (Increase/Same/Decrease)||IDRadioArray||E||RadioArray<br />
|-<br />
|Array (Numbers)||NumberArray||:||Array<br />
|-<br />
|Array (Texts)||TextArray||;||Array<br />
|-<br />
|Array (Yes/No/Uncertain)||YNRadioArray||C||RadioArray<br />
|-<br />
|Array by column||ColumnRadioArray||H||RadioArray<br />
|-<br />
|Array dual scale||DualRadioArray||1||RadioArray<br />
|-<br />
|Date/Time||Date||D||<br />
|-<br />
|Equation||Equation||*||<br />
|-<br />
|File upload||File||pipe character||<br />
|-<br />
|Gender||Gender||G||<br />
|-<br />
|Language switch||Language||I||<br />
|-<br />
|Multiple numerical input||Multinumerical||K||<br />
|-<br />
|Numerical input||Numerical||N||<br />
|-<br />
|Ranking||Ranking||R||<br />
|-<br />
|Text display||Display||X||<br />
|-<br />
|Yes/No||YN||Y||<br />
|-<br />
|Huge free text||HugeText||U||Text<br />
|-<br />
|Long free text||LongText||T||Text<br />
|-<br />
|Multiple short text||Multitext||Q<br />
|-<br />
|Short free text||ShortText||S||Text<br />
|-<br />
|Multiple choice||Check||M||<br />
|-<br />
|Multiple choice with comments||CommentCheck||P||Check<br />
|}<br />
<br />
Each of these classes contains (or inherits) a number of public methods that are abstracted by the QuestionModule class. To execute this question specific code, the question class is loaded out of the database, the object is dynamically instantiated and the relevant function is called. The question objects store question id, group id, survey id, question text, and other relevant data. Question objects then become a very useful way to pass around data instead of the previously used arrays.<br />
<br />
These question objects come with two new database tables. First, a question types table stores a list of type ids, group ids, description, and legacy character code. There is a new int tid column in the questions table that replaces the type column and maps to the tid column in the new question types table. In addition, there is a new question type groups table that contains a group id, a description, and an order. This configuration will allow for backend configuration in the future, and ultimately, custom question types that can be shared among the community.<br />
<br />
One of the biggest advantages of switching from procedural code to object-oriented code is that it will both allow developers to easily create custom question types by extending any of the existing question types. In order to do this, a developer can either extend one of the predefined question types and override one or more of the methods (such as getAnswerHTML() which returns the HTML code that renders each question) or by extending the base QuestionModule class or one of the other abstract classes and implementing its abstract methods.<br />
<br />
{|<br />
|Abstract Method&dagger;||Functionality<br />
|-<br />
|getAnswerHTML||Returns the HTML for the question<br />
|-<br />
|getDataEntry||Returns the HTML for manually entering survey data from the backend<br />
|-<br />
|availableAttributes||Returns an array of attributes the question can have in the question_attributes table<br />
|-<br />
|questionProperties||Returns an array of question properties including description, group name, whether the class has subquestions, css class name, whether the class has default values, whether the class is assessable, and whether the class has answer scales<br />
|}<br />
<br />
&dagger;Once the porting of the question objects is completed, a table will be added with a complete list of methods both abstract and extendable.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=The_bugtracker_and_git&diff=3332The bugtracker and git2012-08-09T12:40:57Z<p>Sammousa: </p>
<hr />
<div><br />
This article should help developers on the LimeSurvey when resolving issues.<br />
<br />
General process outline.<br />
<br />
1. Bug reported by user.<br />
<br />
2. Bug assigned to developer (by the developer himself or someone else)<br />
<br />
3. Bug fixed github.com<br />
<br />
4. Issue assigned to LimeSurvey repository owner (c_schmitz), status set to resolved.<br />
<br />
5. When a new version is released c_schmitz closes the resolved bugs.<br />
<br />
This method of working should allow for efficient bug fixing with multiple developers without getting c_schmitz overworked..?<br />
<br />
Please respond on what you think of this process, or what should be changed.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=The_bugtracker_and_git&diff=3333The bugtracker and git2012-08-09T10:19:10Z<p>Sammousa: </p>
<hr />
<div><br />
This article should help developers on the LimeSurvey when resolving issues.<br />
<br />
General process outline.<br />
<br />
1. Bug reported by user.<br />
<br />
2. Bug assigned to developer (by the developer himself or someone else)<br />
<br />
3. Bug fixed in fork on github.com (each developer has his own fork?)<br />
<br />
4. Pull request generated on github.com<br />
<br />
5. Issue assigned to LimeSurvey repository owner (c_schmitz), status set to resolved.<br />
<br />
6. Pull request fulfilled and bug status set to closed (done by c_schmitz)<br />
<br />
This method of working should allow for efficient bug fixing with multiple developers without getting c_schmitz overworked..?<br />
<br />
Please respond on what you think of this process, or what should be changed.</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Directory_structure&diff=4327Directory structure2012-08-08T20:57:03Z<p>Sammousa: </p>
<hr />
<div><br />
This page should explain the directory hierarchy for the Yii branch.<br />
<br />
Root<br />
* admin -- Contains just a redirect to keep the old /admin URL available; dont put any files in there.<br />
* application -- Contains the Yii limesurvey application, back-end stuff should mostly be in here.<br />
** config -- Contains the configuration for the framework and Limesurvey.<br />
** controllers -- Contains the controllers from the MVC paradigm.<br />
** core<br />
** errors<br />
** helpers<br />
** hooks<br />
** language<br />
** libraries<br />
** logs<br />
** models<br />
** tests<br />
** third_party -- Contains third party libraries that are used by the backend and do not have to be available directly from a browser.<br />
** views<br />
* docs<br />
* fonts<br />
* framework -- The Yii framework. This directory should not be changed unless you are updating Yii.<br />
* images<br />
* installer -- Contains files for initial installation and upgrading.<br />
* locale<br />
* scripts -- Contains javascript files.<br />
* styles-public -- Contains css files (difference with normal styles dir?)<br />
* styles -- Contains css files<br />
* templates<br />
* third-party -- This contains (scripting) libraries that must be available directly via the browser. For example jquery. Only place original libraries here, put configuration in the scripts dir. Create a subdirectory for each library, but don't include the version number in the directory; this allows for easy upgrading.<br />
* tmp<br />
* upload</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Directory_structure&diff=4328Directory structure2012-08-08T20:52:37Z<p>Sammousa: </p>
<hr />
<div><br />
This page should explain the directory hierarchy for the Yii branch.<br />
<br />
Root<br />
* admin -- Contains just a redirect to keep the old /admin URL available; dont put any files in there.<br />
* application -- Contains the Yii limesurvey application, back-end stuff should mostly be in here.<br />
** config<br />
** controllers<br />
** core<br />
** errors<br />
** helpers<br />
** hooks<br />
** language<br />
** libraries<br />
** logs<br />
** models<br />
** tests<br />
** third_party -- Contains third party libraries that are used by the backend and do not have to be available directly from a browser.<br />
** vies<br />
* docs<br />
* fonts<br />
* framework -- The Yii framework. This directory should not be changed unless you are updating Yii.<br />
* images<br />
* installer -- Contains files for initial installation and upgrading.<br />
* locale<br />
* scripts -- Contains javascript files.<br />
* styles-public -- Contains css files (difference with normal styles dir?)<br />
* styles -- Contains css files<br />
* templates<br />
* third-party -- This contains (scripting) libraries that must be available directly via the browser. For example jquery. Only place original libraries here, put configuration in the scripts dir. Create a subdirectory for each library, but don't include the version number in the directory; this allows for easy upgrading.<br />
* tmp<br />
* upload</div>Sammousahttps://www.limesurvey.org/manual/index.php?title=Directory_structure&diff=4329Directory structure2012-08-08T20:47:24Z<p>Sammousa: </p>
<hr />
<div><br />
This page should explain the directory hierarchy for the Yii branch.<br />
<br />
Root<br />
* admin<br />
* application<br />
* docs<br />
* fonts<br />
* framework -- The Yii framework. This directory should not be changed unless you are updating Yii.<br />
* images<br />
* installer -- Contains files for initial installation and upgrading.<br />
* locale<br />
* scripts -- Contains javascript files.<br />
* styles-public -- Contains css files (difference with normal styles dir?)<br />
* styles -- Contains css files<br />
* templates<br />
* third-party -- This contains (scripting) libraries that must be available directly. For example jquery. Only place original libraries here, put configuration in the scripts dir. Create a subdirectory for each library, but don't include the version number in the directory; this allows for easy upgrading.<br />
* tmp<br />
* upload</div>Sammousa